javax.swing.text Documentation Differences

This file contains all the changes in documentation in the package javax.swing.text as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

An implementation of the document interface to serve as a basis for implementing various kinds of documents. At this level there is very little policy so there is a corresponding increase in difficulty of use.

This class implements a locking mechanism for the document. It allows multiple readers or one writer and writers must wait until all observers of the document have been notified of a previous change before beginning another mutation to the document. The read lock is aquiredacquired and released using the render method. A write lock is aquired by the methods that mutate the document and are held for the duration of the method call. Notification is done on the thread that produced the mutation and the thread has full read access to the document for the duration of the notification but other readers are kept out until the notification has finished. The notification is a beans event notification which does not allow any further mutations until all listeners have been notified.

Any models subclassed from this class and used in conjunction with a text component that has a look and feel implementation that is derived from BasicTextUI may be safely updated asynchronously because all access to the View hierarchy is serialized by BasicTextUI if the document is of type AbstractDocument. The locking assumes that an independant thread will access the View hierarchy only from the DocumentListener methods and that there will be only one event thread active at a time.

If concurrency support is desired there are the following additional implications. The code path for any DocumentListener implementation and any UndoListener implementation must be threadsafe and not access the component lock if trying to be safe from deadlocks. The repaint and revalidate methods on JComponent are safe.

AbstractDocument models an implied break at the end of the document. Among other things this allows you to position the caret after the last character. As a result of this getLength returns one less than the length of the Content. If you create your own Content be sure and initialize it to have an additional character. Refer to StringContent and GapContent for examples of this. Another implication of this is that Elements that model the implied end character will have an endOffset == (getLength() + 1). For example in DefaultStyledDocument getParagraphElement(getLength()).getEndOffset() == getLength() + 1 .

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. A future releaseAs of Swing will provide1.4 support for long term persistencestorage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.116 03130 12/1603/01

Implements the abstract part of an element. By default elements support attributes by having a field that represents the immutable part of the current attribute set for the element. The element itself implements MutableAttributeSet which can be used to modify the set by fetching a new immutable set. The immutable sets are provided by the AttributeContext associated with the document.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. AAs future release of Swing will provide1.4 support for long term persistencestorage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder

Returns the children of the recieverreceiver as an Enumeration. @return the children of the receiver as an Enumeration

Returns true if the receiver allows children. @return true if the receiver allows children otherwise false

Returns the number of children TreeNode's receiver contains. @return the number of children TreeNodews's receiver contains.

Returns the index of node in the receivers children. If the receiver does not contain node -1 will be returned. @param node the location of interest @return the index of node in the receiver's children or -1 if absent

Returns the parent TreeNode of the receiver. @return the parent TreeNode of the receiver

Gets the resolving parent. If not overridenoverridden the resolving parent defaults to the parent element. @return the attributes from the parent null if none @see AttributeSet#getResolveParent

Implements a composite element that contains other elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. AAs future release of Swing will provide1.4 support for long term persistencestorage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder

Returns the children of the recieverreceiver as an Enumeration. @return the children of the receiver

Returns true if the receiver allows children. @return true if the receiver allows children otherwise false

Inserts a string of characters into the sequence. @param where Offsetoffset into the sequence to make the insertion >= 0. @param str Stringstring to insert. @return Ifif the implementation supports a history mechansimmechanism a reference to an Edit implementation will be returned otherwise returns null. @exception BadLocationException Thrownthrown if the area covered by the arguments is not contained in the character sequence.

Implements an element that directly represents content of some kind.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. AAs future release of Swing will provide1.4 support for long term persistencestorage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder @see Element

Returns the children of the recieverreceiver as an Enumeration. @return the children of the receiver

Returns true if the receiver allows children. @return true if the receiver allows children otherwise false

Constructs a new AbstractDocument wrapped around some specified content storage mechanism. @param data the content

Constructs a new AbstractDocument wrapped around some specified content storage mechanism. @param data the content @param context the attribute context

Adds a document listener for notification of any changes. @param listener the listenerDocumentListener to add @see Document#addDocumentListener

Adds an undo listener for notification of any changes. Undo/Redo operations performed on the UndoableEdit will cause the appropriate DocumentEvent to be fired to keep the view(s) in sync with the model. @param listener the listenerUndoableEditListener to add @see Document#addUndoableEditListener

Creates a document leaf element. Hook through which elements are created to represent the document structure. Because this implementation keeps structure and content seperateseparate elements grow automatically when content is extended so splits of existing elements follow. The document itself gets to decide how to generate elements to give flexibility in the type of elements used. @param parent the parent element @param a the attributes for the element @param p0 the beginning of the range >= 0 @param p1 the end of the range >= p0 @return the new element

GetGets the asynchronous loading priority. If less than zero the document should not be loaded asynchronously. @return the asynchronous loading priority or -1 if the document should not be loaded asynchronously

Fetches the current writing thread if there is one. This can be used to distinguish whether a method is being called as part of an existing modification or if a lock needs to be acquired and a new transaction started. @returnsreturn the thread actively modifying the document or null if there are no modifications in progress

SupportSupports for managing a set of properties. Callers can use the documentProperties dictionary to annotate the document with document-wide properties. @return a non -null Dictionary @see #setDocumentProperties

ReturnReturns an array of all the objects currently registered as FooListeners upon this document. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal such as FooListener.class. For example you can query a document d for its document listeners ofwith the givenfollowing typecode: that

DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));

wereIf addedno such listeners toexist this modelmethod returns an empty array. @returns allparam listenerType the type of thelisteners requested; this parameter should specify an interface that descends from java.util.EventListener @return an array of all objects recievingregistered as listenerTypeFoo notificationsListeners fromon this modelcomponent or an empty array if no such listeners have been added @exception ClassCastException if listenerType doesn't specify a class or interface that implements java.util.EventListener @see #getDocumentListeners @see #getUndoableEditListeners @since 1.3

A convenience method for looking up a property value. It is equivalent to:

 getDocumentProperties().get(key); 

@param key the non-null property key @return the value of this property or null @see #getDocumentProperties

Gets someFetches the text fromcontained within the given portion of the document. potentially without making a

If the partialReturn copy.property Theon the txt parameter is false character arraythe data returned in the given Segment will be the entire length requested and may or should nevermay not be mutateda copy depending upon how the data was stored. This kind of accessIf the partialReturn property tois true only the charactersamount of thetext documentthat can be returned without creating a copy is providedreturned. to help makeUsing partial returns will give better performance for situations where large parts of the rendering potentially more efficientdocument are being scanned. The callerfollowing should make no assumptions aboutis an example of using the lifetimepartial ofreturn to access the returnedentire characterdocument: array which

 should  be copied ifint nleft = neededdoc.getDocumentLength();   beyond the useSegment text = fornew Segment();   int offs = 0; rendering  text.setPartialReturn(true);   while (nleft > 0) {   doc.getText(offs nleft text);   // do something with text   nleft -= text.count;   offs += text.count;   } 

@param offset the starting offset >= 0 @param length the number of characters to retrieve >= 0 @param txt the Segment object to retrieve the text into @exception BadLocationException the range given includes a position that is not a valid position within the document

A convenience method for storing up a property value. It is equivalent to:

 getDocumentProperties().put(key value); 

If value is null this method will remove the property. @param key the non-null key @param value the property value @see #getDocumentProperties

Removes a document listener. @param listener the listenerDocumentListener to remove @see Document#removeDocumentListener

Removes an undo listener. @param listener the listenerUndoableEditListener to remove @see Document#removeDocumentListener

This allows the model to be safely rendered in the presence of currency if the model supports being updated asynchronously. The given runnable will be executed in a way that allows it to safely read the model with no changes while the runnable is being executed. The runnable itself may not make any mutations.

This is implemented to aquire a read lock for the duration of the runnables execution. There may be multiple runnables executing at the same time and all writers will be blocked while there are active rendering runnables. If the runnable throws an exception its lock will be safely released. There is no protection against a runnable that never exits which will effectively leave the document locked for it's lifetime.

If the given runnable attempts to make any mutations in this implementation a deadlock will occur. There is no tracking of individual rendering threads to enable detecting this situation but a subclass could incur the overhead of tracking them and throwing an error.

This method is thread safe although most Swing methods are not. Please see Threads and Swing for more information. @param r the renderer to execute.

SetSets the asynchronous loading priority. @param p the new aynchronous loading priority; a value less than zero indicates that the document should be loaded asynchronously

ReplaceReplaces the document properties dictionary for this document. @param x the new dictionary @see #getDocumentProperties

Acquires a lock to begin mutating the document this lock protects. There can be no writing notification of changes or reading going on in order to gain the lock. Additionally a thread is allowed to gain more than one writeLock as long as it doesn't attempt to gain additional writeLocks from within document notification. Attempting to gain a writeLock from within a DocumentListener notification will result in an IllegalStateException. The ability to obtain more than one writeLock per thread allows subclasses to gain a writeLock perform a number of operations then release the lock.

Calls to writeLock must be balanced with calls to writeUnlock else the Document will be left in a locked state so that no reading or writing can be done. @exception IllegalStateException thrown on illegal lock attempt. If the document is implemented properly this can only happen if a document listener attempts to mutate the document. This situation violates the bean event model where order of delivery is not guaranteed and all listeners should be notified before further mutations are allowed.

Releases thea write lock heldpreviously obtained via writeLock. After becausedecrementing the writelock operation iscount if finished.there This allows eitherare no oustanding locks this will allow a new writer or readers to aquire. a@see lock.#writeLock

AbstractWriter is an abstract class that actually does the work of writing out the element tree including the attributes. In terms of how much is written out per line the writer defaults to 100. But this value can be set by subclasses. @author Sunita Mani @version 1.14 0216 12/0203/0001

Returns the text associated with the element. The assumption here is that the element is a leaf element. Throws a BadLocationException when encountered. @param an Element. @exception BadLocationException if pos represents an invalid location within the document. @returnsreturn the text as a String.

A box that does layout asynchronously. This is useful to keep the GUI event thread moving by not doing any layout on it. The layout is done on a granularity of operations on the child views. After each child view is accessed for some part of layout (a potentially time consuming operation) the remaining tasks can be abandoned or a new higher priority task (i.e. to service a synchronous request or a visible area) can be taken on.

While the child view is being accessed a read lock is aquired on the associated document so that the model is stable while being accessed. @author Timothy Prinzing @version 1.5 0412 12/0603/0001 @since 1.3

Locate the view responsible for an offset into the box along the major axis. Make sure that offsets are set on the ChildState objects up to the given target span past the desired offset. @returnsreturn index of the view representing the given visual location (targetOffset) or -1 if no view represents that location.

Publish the changes in preferences upward to the parent view. This is normally called by the layout thread.

Determines the maximum span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned although there is no guarantee. The parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type

Determines the minimum span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned although there is no guarantee. The parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type

Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible they might not be in the same order found in the model or they just might not allow access to some of the locations in the model. @param pos the position to convert >= 0 @param a the allocated region to render into @param direction the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This; this may be one of the following:

SwingConstants.WEST SwingConstants.EAST SwingConstants.NORTH or SwingConstants.SOUTH.

@param biasRet an array contain the bias that was checked @return the location within the model that best represents the next location visual position. @exception BadLocationException @exception IllegalArgumentException forif andirection invalid directionis invalid

Determines the preferred span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned although there is no guarantee. The parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type

Fetches the child view index representing the given position in the model. This is implemented to fetch the view in the case where there is a child view for each child element. @param pos the position >= 0 @returnsreturn index of the view representing the given position or -1 if no view represents that position

Requirements changed along the major axis. This is called by the thread doing layout for the given ChildState object when it has completed fetching the child views new preferences. Typically this would be the layout thread but might be the GUIevent thread if it is trying to update something immediately (such as to perform a model/view translation).

This is implemented to mark the major axis as having changed so that a future check to see if the requirements need to be published to the parent view will consider the major axis. If the span along the major axis is not estimated it is updated by the given delta to reflect the incremental change. The delta is ignored if the major span is estimated.

Sets the size of the view. This should cause layout of the view if itthe view hascaches any layout dutiesinformation.

This isSince implemented to check and see if there has been a change inthe major axis is updated asynchronously and should be the sum of the minor spantiled (sincechildren the viewcall is flexibleignored alongfor the minormajor axis). If there has been a change this willSince add a high priorty task on the layout thread that will mark allminor of the ChildState records as needingaxis is flexible work is queued to resize the child and to spawn a bunch of low priority tasks to fixup the children. This method will normally be called by the GUI event thread which we don't want to slow down in any way if we can help it. Pushing the potentially time consuming task of marking each record frees the GUI thread but also leaves the view open to paint attempts that can't be satisfied. The view is marked as resizing and the ResizeTask will turn off the flag when the children have allminor been markedspan changes. @param width the width >= 0 @param height the height >= 0

A collection of unique attributes. This is a read-only immutable interface. An attribute is basically a key and a value assigned to the key. The collection may represent something like a style run a logical style etc. These are generally used to describe features that will contribute to some graphical representation such as a font. The set of possible keys is unbounded and can be anything. Typically View implementations will respond to attribute definitions and render something to represent the attributes.

Attributes can potentially resolve in a hierarchy. If a key doesn't resolve locally and a resolving parent exists the key will be resolved through the parent. @author Timothy Prinzing @version 1.33 0237 12/0203/0001 @see MutableAttributeSet

This interface is the type signature that is expected to be present on any attribute key that contributes to the determination of what font to use to render some text. This is not considered to be a closed set the definition can change across version of the platform and can be ammendedamended by additional user added entries that correspond to logical settings that are specific to some type of content.

Returns an enumeration over the names of the attributes in the set. The elementsvalues of the enumerationEnumeration may be anything and are allnot constrained to a particular Object Stringstype. The set does not include the resolving parent if one is defined. @return the names

Attribute name used to identifiyidentify the resolving parent set of attributes if one is defined.

This exception is to report bad locations within a document model (that is attempts to reference a location that doesn't exist).

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. AAs future release of Swing will provide1.4 support for long term persistencestorage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.16 0218 12/0203/0001

A view that arranges its children into a box shape by tiling it'sits children along an axis. The box is somewhat like that found in TeX where there is alignment of the children flexibility of the children is considered etc. This is considered an usefula building block that might be useful to represent things like a collection of lines paragraphs lists columns pages etc. The axis along which the children are tiled is considered the major axis. The orthoginal axis is the minor axis.

Layout for each axis is handled separately by the methods layoutMajorAxis and layoutMinorAxis. Subclasses can change the layout algorithm by reimplementing these methods. These methods will be called as necessary depending upon whether or not there is cached layout information and the cache is considered valid. These methods are typically called if the given size along the axis changes or if layoutChanged is called to force an updated layout. The layoutChanged method invalidates cached layout information if there is any. The requirements published to the parent view are calculated by the methods calculateMajorAxisRequirements and calculateMinorAxisRequirements. If the layout algorithm is changed these methods will likely need to be reimplemented. @author Timothy Prinzing @version 1.44 0256 12/0203/0001

Constructs a BoxView. @param elem the element this view is responsible for @param axis either View.X_AXIS or View.Y_AXIS

ForwardForwards the given DocumentEvent to the child views that need to be notified of the change to the model. If a child changed it'sits requirements and the allocation was valid prior to forwarding the portion of the box from the starting child to the end of the box will be repainted. @param ec changes to the element this view is responsible for (may be null if there were no changes). @param e the change information from the associated document @param a the current allocation of the view @param f the factory to use to rebuild if the view has children @see #insertUpdate @see #removeUpdate @see #changedUpdate

Determines the desired alignment for this view along an axis. This is implemented to give the total alignment needed to position the children with the alignment points lined up along the axis orthoginal to the axis that is being tiled. The axis being tiled will request to be centered (i.e. 0.5f). @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the desired alignment >= 0.0f && < 1.0f.; Thisthis should be a value between 0.0 and 1.0 where 0 indicates alignment at the origin and 1.0 indicates alignment to the full span away from the origin.; Anan alignment of 0.5 would be the center of the view. @exception IllegalArgumentException for an invalid axis

FetchFetches the tile axis property. This is the axis along which the child views are tiled. @return the major axis of the box either View.X_AXIS or View.Y_AXIS @since 1.3

Fetches the allocation for the given child view. This enables finding out where various views are located. This is implemented to return null if the layout is invalid otherwise the superclass behavior is executed. @param index the index of the child >= 0 && . @return the allocation to the child; or null if a is null; or null if the layout is invalid

TheReturns the current height of the box. This is the height that it was last allocated. @return the current height of the box

Determines the maximum span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0.; Typicallytypically the view is told to render into the span that is returned although there is no guarantee.; Thethe parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type

Determines the minimum span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0.; Typicallytypically the view is told to render into the span that is returned although there is no guarantee.; Thethe parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type

FetchFetches the offset of a particular childschild's current layout. @param axis the axis being studied @param childIndex the index of the requested child @return the offset (location) for the specified child

Determines the preferred span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0.; Typicallytypically the view is told to render into the span that is returned although there is no guarantee.; Thethe parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type

Gets the resize weight. A value of 0 or less is not resizable. @param axis may be either View.X_AXIS or View.Y_AXIS @return the weight @exception IllegalArgumentException for an invalid axis

FetchFetches the span of a particular childs current layout. @param axis the axis being studied @param childIndex the index of the requested child @return the span (width or height) of the specified child

Fetches the child view at the given pointcoordinates. @param x the X coordinate >= 0 @param y the Y coordinate >= 0 @param alloc the parents inner allocation on entry which should be changed to the childs allocation on exit. @return the view

TheReturns the current width of the box. This is the width that it was last allocated. @return the current width of the box

Determines if a point falls after an allocated region. @param x the X coordinate >= 0 @param y the Y coordinate >= 0 @param innerAlloc the allocated region. This; this is the area inside of the insets. @return true if the point lies after the region else false

Determines if a point falls before an allocated region. @param x the X coordinate >= 0 @param y the Y coordinate >= 0 @param innerAlloc the allocated region. This; this is the area inside of the insets. @return true if the point lies before the region else false

PerformsPerform layout ofon the children. Thebox size@param iswidth the areawidth (inside of the insets. This method calls the methods layoutMajorAxis and layoutMinorAxis as needed. To change how layout is) done those methods should be reimplemented. @param width the width >= 0 @param height the height (inside of the insets) >= 0

InvalidateInvalidates the layout along an axis. This happens automatically if the preferences have changed for any of the child views. In some cases the layout may need to be recalculated when the preferences have not changed. The layout can be marked as invalid by calling this method. The layout will be updated the next time the setSize method is called on this view (typically in paint). @param axis either View.X_AXIS or View.Y_AXIS @since 1.3

PerformPerforms layout for the major axis of the box (i.e. the axis that it represents). The results of the layout should be placed in the given arrays which represent the allocations to the children along the major axis. @param targetSpan the total span given to the view which whouldwould be used to layout the children. @param axis the axis being layed out. @param offsets the offsets from the origin of the view for each of the child views. This; this is a return value and is filled in by the implementation of this method. @param spans the span of each child view. This; this is a return value and is filled in by the implementation of this method. @returnsreturn the offset and span for each child view in the offsets and spans parameters.

PerformPerforms layout for the minor axis of the box (i.e. the axis orthoginal to the axis that it represents). The results of the layout should be placed in the given arrays which represent the allocations to the children along the minor axis. @param targetSpan the total span given to the view which whouldwould be used to layout the children. @param axis the axis being layed out. @param offsets the offsets from the origin of the view for each of the child views. This; this is a return value and is filled in by the implementation of this method. @param spans the span of each child view. This; this is a return value and is filled in by the implementation of this method. @returnsreturn the offset and span for each child view in the offsets and spans parameters.

Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. This makes sure the allocation is valid before lettingcalling the superclass do its thing. @param pos the position to convert >= 0 @param a the allocated region to render into @return the bounding box of the given position @exception BadLocationException if the given position does not represent a valid location in the associated document @see View#modelToView

Renders the BoxView using the given rendering surface and area on that surface. Only the children that intersect the clip bounds of the given Graphics will be rendered. @param g the rendering surface to use @param allocation the allocated region to render into @see View#paint

This is called by a child to indicatedindicate its preferred span has changed. This is implemented to throw away cached layout information so that new calculations will be done the next time the children need an allocation. @param child the child view @param width true if the width preference should change @param height true if the height preference should change

Invalidates the layout and resizes the cache of requests/allocations. The child allocations can still be accessed for the old layout but the new children will have an offset and span of 0. @param index the starting index into the child views to insert the new views. This; this should be a value >= 0 and < getViewCount. @param length the number of existing child views to remove.; This should be a value >= 0 and < (getViewCount() - offset). @param views the child views to add. This; this value can be null to indicate no children are being added (useful to remove).

SetSets the tile axis property. This is the axis along which the child views are tiled. @param axis either View.X_AXIS or View.Y_AXIS @since 1.3

Sets the size of the view. IfThis should cause layout of the size has changed layout isview if the view caches redone.any layout Theinformation. sizeThis is implemented to call the full size oflayout method with the viewsizes including the inset areasinside of the insets. @param width the width >= 0 @param height the height >= 0

A place within a document view that represents where things can be inserted into the document model. A caret has a position in the document referred to as a dot. The dot is where the caret is currently located in the model. There is a second position maintained by the caret that represents the other end of a selection called mark. If there is no selection the dot and mark will be equal. If a selection exists the two values will be different.

The dot can be placed by either calling setDot or moveDot. Setting the dot has the effect of removing any selection that may have previously existed. The dot and mark will be equal. Moving the dot has the effect of creating a selection as the mark is left at whatever position it previously had. @author Timothy Prinzing @version 1.26 0228 12/0203/0001

Gets the blink rate of the caret. This determines if and how fast the caret blinks commonly used as one way to attract attention to the caret. @returnsreturn the delay in milliseconds >= 0. If this is zero the caret will not blink.

ChangedCharSetException as the name indicates is an exception thrown when the charset is changed. @author Sunita Mani 1.5 026 12/0203/0001

Component decorator that implements the view interface. The entire element is used to represent the component. This acts as a gateway from the display-only View implementations to interactive lightweight components (ie it allows components to be embedded into the View hierarchy).

The component is placed relative to the text baseline according to the value returned by Component.getAlignmentY. For Swing components this value can be conveniently set using the method JComponent.setAlignmentY. For example setting a value of 0.75 will cause 75 percent of the component to be above the baseline and 25 percent of the component to be below the baseline.

This class is implemented to do the extra work necessary to work properly in the presence of multiple threads (i.e. from asynchronous notification of model changes for example) by ensuring that all component access is done on the event thread.

The component used is determined by the return value of the createComponent method. The default implementation of this method is to return the component held as an attribute of the element (by calling StyleConstants.getComponent). A limitation of this behavior is that the component cannot be used by more than one text component (i.e. with a shared model). Subclasses can remove this constraint by implementing the createComponent to actually create a component based upon some kind of specification contained in the attributes. The ObjectView class in the html package is an example of a ComponentView implementation that supports multiple component views of a shared model. @author Timothy Prinzing @version 1.40 0248 12/0203/0001

Determines the desired alignment for this view along an axis. This is implemented to give the alignment of the embedded component. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the desired alignment. This should be a value between 0.0 and 1.0 where 0 indicates alignment at the origin and 1.0 indicates alignment to the full span away from the origin. An alignment of 0.5 would be the center of the view.

Determines the maximum span for this view along an axis. This is implemented to return the value returned by Component.getMaximumSize along the axis of interest. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned although there is no guarantee. The parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis

Determines the minimum span for this view along an axis. This is implemented to return the value returned by Component.getMinimumSize along the axis of interest. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned although there is no guarantee. The parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis

Determines the preferred span for this view along an axis. This is implemented to return the value returned by Component.getPreferredSize along the axis of interest. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned although there is no guarantee. The parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis

Sets the parent for a child view. The parent calls this on the child to tell it who its parent is giving the view access to things like the hosting Container. The superclass behavior is executed followed by a call to createComponent if the parent view parameter is non-null and a component has not yet been created and. theThe embedded components parent is then set to the value returned by getContainer. If the parent view parameter is null this view is being cleaned up thus the component is removed from its parent.

The changing of the component hierarhcyhierarchy will touch the component lock which is the one thing that is not safe from the View hierarchy. Therefore this functionality is executed immediately if on the event thread or is queued on the event queue if called from another thread (notification of change from an asynchronous update). @param p the parent

Sets the size of the view. This is implemented toshould cause layout do nothing sinceof the component itself will get itsview size established by the LayoutManager installed on the hosting Containeralong the given axis if it has any layout duties. @param width the width >= 0 @param height the height >= 0

ACompositeView view that isis an abstract composedView ofimplementation which othermanages one or more child views. (hasNote children).that AsCompositeView ais intended for containermanaging relatively small numbers of childrenchild theviews.) compositeCompositeView view needsis intended to provide:be used servicesas to manage the collectiona starting point for ofView childrenimplementations Thesuch followingas methodsBoxView can bethat will usedcontain child Views. Subclasses that wish to manage the collection. of removeAllchild insertViews appendshould use the #replace getViewCountmethod. getViewAs loadChildrenView invokes layoutreplace ofduring theDocumentListener childrennotification Thisyou classnormally won't need to directly invoke replace.

While CompositeView does not implementimpose a layout policy ason it isits child abstract.Views A subclass will determine howit does allow for inseting the childrenchild areViews laid outit will bycontain. implementing theThe insets setSizecan method to positionbe set by theeither #setInsets or children#setParagraphInsets when

In addition to the size has beenabstract methods of changedjavax.swing.text.View paintsubclasses theof childrenCompositeView Thiswill class doesneed to notoverride:

• {@link attempt#isBefore} - Used to painttest if a given View location is before the visual space of the childrenCompositeView. Subclasses
• {@link will#isAfter} want- Used to use the layout informationtest if a given andView call paint onlocation is after the childrenvisual that are visiblespace of the (intersectCompositeView. the
• {@link clipping#getViewAtPoint} region)- withReturns the Shapeview argument set to theat a given visual location. of
• {@link the#childAllocation} child- view.Returns the propagationbounds of DocumentEventa information toparticular child theView. appropriategetChildAllocation children.will propagationinvoke ofchildAllocation model/viewafter translationoffseting tothe bounds by the properInsets childof the CompositeView.

@author Timothy Prinzing @version 1.5463 0212/0212/0001

Constructs a CompositeView for the given element. @param elem the element this view is responsible for

Subclasses may wish to subclass this andDetermines in which direction the next view conditionallylays. returnConsider truethe View at index basedn. onTypically the position.Views A return value ofare layed out from trueleft to indicatesright so that whenthe View to the EAST will be at index n + 1 and athe View returnsto the WEST will be at index n - 1. from getNextVisualPositionFrom the next view for east shouldIn certain situations such as with bidirectional text beit is possible that the currentView to EAST is not at index offsetn + 1 but rather at index byn - 1 andor forthat the westView itto the WEST is not at index n - 1 but means offset byindex n + 1. TheIn normal directionthis case (forthis left to rightmethod would return text)true indicating the Views are layed out in descending order.

This unconditionally returns false subclasses should override this method if there is to offset east bythe possibility for laying 1Views and westin descending byorder. -1@param position position into the model @param bias either Position.Bias.Forward or Position.Bias.Backward @return false

Fetches the allocation for the given child view to render into. This enables finding out where various views are located. @param index the index of the child >= 0 && . @return the allocation to the child

Translates the immutable allocation given to the view to a mutable allocation that represents the interior allocation (i.e. the bounds of the given allocation with the top left bottom and right insets removed. It is expected that the returned value would be further mutated to represent an allocation to a child view. This is implemented to reuse an instance variable so it avoids creating excessive Rectangles. Typically the result of calling this method would be fed to the childAllocation method. @param a Thethe allocation given to the view. @returns Thereturn the allocation that represents the inside of the view after the margins have all been removed.; Ifif the given allocation was null the return value is null.

Returns the next visual position for the cursor in either the east or west direction. @returnparam nextpos the position westto convert >= 0 @param b a bias value of either Position.Bias.Forward or Position.Bias.Backward @param a the passedallocated inregion to render into @param direction the direction from the current position that can be thought of as the arrow keys typically found on a keyboard; this may be one of the following:

• SwingConstants.WEST
• SwingConstants.EAST

@param biasRet an array containing the bias that was checked @return the location within the model that best represents the next west or east location @exception BadLocationException @exception IllegalArgumentException if direction is invalid @see #getNextVisualPositionFrom

Returns the next visual position for the cursor in either the eastnorth or westsouth direction. @param pos the position to convert >= 0 @param b a bias value of either Position.Bias.Forward or Position.Bias.Backward @param a the allocated region to render into @param direction the direction from the current position that can be thought of as the arrow keys typically found on a keyboard; this may be one of the following:

• SwingConstants.NORTH
• SwingConstants.SOUTH

@param biasRet an array containing the bias that was checked @return the location within the model that best represents the next north or south location @exception BadLocationException @exception IllegalArgumentException if direction is invalid @see #getNextVisualPositionFrom @return the next position west of the passed in position.

Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible they might not be in the same order found in the model or they just might not allow access to some of the locations in the model. This is a convenience method for #getNextNorthSouthVisualPositionFrom and #getNextEastWestVisualPositionFrom @param pos the position to convert >= 0 @param b a bias value of either Position.Bias.Forward or Position.Bias.Backward @param a the allocated region to render into @param direction the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This; this may be one of the following:

• SwingConstants.WEST
• SwingConstants.EAST
• SwingConstants.NORTH or
• SwingConstants.SOUTH.

@param biasRet an array containing the bias that was checked @return the location within the model that best represents the next location visual position. @exception BadLocationException @exception IllegalArgumentException forif andirection invalid directionis invalid

GetsReturns the n-th view in this container. @param n the number of the view todesired getview >= 0 && at index n

Fetches the child view at the given pointcoordinates. @param x the X coordinate >= 0 @param y the Y coordinate >= 0 @param alloc the parent's allocation on entry which should be changed to the child's allocation on exit @return the child view

Fetches the child view that represents the given position in the model. This is implemented to fetch the view in the case where there is a child view for each child element. @param pos the position >= 0 @param a the allocation to the interior of the box on entry and the allocation of the view containing the position on exit @returnsreturn the view representing the given position or null if there isn't one

Returns the child view index representing the given position in the model. This is implemented to call the getViewIndexByPosition method for backward compatibility. @param pos the position >= 0 @returnsreturn index of the view representing the given position or -1 if no view represents that position

Fetches the child view index representing the given position in the model. This is implemented to fetch the view in the case where there is a child view for each child element. @param pos the position >= 0 @returnsreturn index of the view representing the given position or -1 if no view represents that position

Loads all of the children to initialize the view. This is called by the #setParent method. Subclasses can reimplement this to initialize their child views in a different manner. The default implementation creates a child view for each child element. @param f the view factory @see #setParent

Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. @param p0 the position to convert >= 0 @param b0 the bias toward the previous character or the next character represented by p0 in case the position is a boundary of two views; either Position.Bias.Forward or Position.Bias.Backward @param p1 the position to convert >= 0 @param b1 the bias toward the previous character or the next character represented by p1 in case the position is a boundary of two views. @param a the allocated region to render into @return the bounding box of the given position is returned @exception BadLocationException if the given position does not represent a valid location in the associated document @exception IllegalArgumentException for an invalid bias argument @see View#viewToModel

Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. @param pos the position to convert >= 0 @param a the allocated region to render into @param b a bias value of either Position.Bias.Forward or Position.Bias.Backward @return the bounding box of the given position @exception BadLocationException if the given position does not represent a valid location in the associated document @see View#modelToView

ReplaceReplaces child views. If there are no views to remove this acts as an insert. If there are no views to add this acts as a remove. Views being removed will have the parent set to null and the internal reference to them removed so that they canmay be garbage collected. @param index the starting index into the child views to insert the new views. This should be a; value >= 0 and < getViewCount. @param length the number of existing child views to remove. This; this should be a value >= 0 and < (getViewCount() - offset). @param views the child views to add. This; this value can be null to indicate no children are being added (useful to remove).

Sets the parent of the view. This is reimplemented to provide the superclass behavior as well as calling the loadChildren method if this view does not already have children. The children should not be loaded in the constructor because the act of setting the parent may cause them to try to search up the hierarchy (to get the hosting Container for example). If this view has children (the view is being moved from one place in the view hierarchy to another) the loadChildren method will not be called. @param parent the parent of the view null if none

Provides a mapping from the view coordinate space to the logical coordinate space of the model. @param x x coordinate of the view location to convert >= 0 @param y y coordinate of the view location to convert >= 0 @param a the allocated region to render into @param bias either Position.Bias.Forward or Position.Bias.Backward @return the location within the model that best represents the given point in the view >= 0 @see View#viewToModel

A default implementation of Caret. The caret is rendered as a vertical line in the color specified by the CaretColor property of the associated JTextComponent. It can blink at the rate specified by the BlinkRate property.

This implementation expects two sources of asynchronous notification. The timer thread fires asynchronously and causes the caret to simply repaint the most recent bounding box. The caret also tracks change as the document is modified. Typically this will happen on the event thread as a result of some mouse or keyboard event. Updates can also occur from some other thread mutating the document. There is a property AsynchronousMovement that determines if the caret will move on asynchronous updates. The default behavior is to not update on asynchronous updates. If asynchronous updates are allowed the update thread will fire the caret position change to listeners asynchronously. The repaint of the new caret location will occur on the event thread in any case as calls to modelToView are only safe on the event thread.

The caret acts as a mouse and focus listener on the text component it has been installed in and defines the caret semantics based upon those events. The listener methods can be reimplemented to change the semantics. By default the first mouse button will be used to set focus and caret position. Dragging the mouse pointer with the first mouse button will sweep out a selection that is contiguous in the model. If the associated text component is editable the caret will become visible when focus is gained and invisible when focus is lost.

The Highlighter bound to the associated text component is used to render the selection by default. Selection appearance can be customized by supplying a painter to use for the highlights. By default a painter is used that will render a solid color as specified in the associated text component in the SelectionColor property. This can easily be changed by reimplementing the getSelectionHighlighter method.

A customized caret appearance can be achieved by reimplementing the paint method. If the paint method is changed the damage method should also be reimplemented to cause a repaint for the area needed to render the caret. The caret extends the Rectangle class which is used to hold the bounding box for where the caret was last rendered. This enables the caret to repaint in a thread-safe manner when the caret moves without making a call to modelToView which is unstable between model updates and view repair (i.e. the order of delivery to DocumentListeners is not guaranteed).

The magic caret position is set to null when the caret position changes. A timer is used to determine the new location (after the caret change). When the timer fires if the magic caret position is still null it is reset to the current caret position. Any actions that change the caret position and want the magic caret position to remain the same must remember the magic caret position change the cursor and then set the magic caret position to its original value. This has the benefit that only actions that want the magic caret position to persist (such as open/down) need to know about it.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. A futureAs release of Swing will provide1.4 support for long term persistencestorage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timot