Generated by
JDiff

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.

Class AbstractDocument

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.116 03130 12/1603/01


Class AbstractDocument.AbstractElement

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder

Class AbstractDocument.AbstractElement, Enumeration children()

Returns the children of the recieverreceiver as an Enumeration. @return the children of the receiver as an Enumeration
Class AbstractDocument.AbstractElement, boolean getAllowsChildren()

Returns true if the receiver allows children. @return true if the receiver allows children otherwise false
Class AbstractDocument.AbstractElement, int getChildCount()

Returns the number of children TreeNode's receiver contains. @return the number of children TreeNodews's receiver contains.
Class AbstractDocument.AbstractElement, int getIndex(TreeNode)

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
Class AbstractDocument.AbstractElement, TreeNode getParent()

Returns the parent TreeNode of the receiver. @return the parent TreeNode of the receiver
Class AbstractDocument.AbstractElement, AttributeSet getResolveParent()

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

Class AbstractDocument.BranchElement

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder

Class AbstractDocument.BranchElement, Enumeration children()

Returns the children of the recieverreceiver as an Enumeration. @return the children of the receiver
Class AbstractDocument.BranchElement, boolean getAllowsChildren()

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

Class AbstractDocument.Content, UndoableEdit insertString(int, String)

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.

Class AbstractDocument.LeafElement

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see Element

Class AbstractDocument.LeafElement, Enumeration children()

Returns the children of the recieverreceiver as an Enumeration. @return the children of the receiver
Class AbstractDocument.LeafElement, boolean getAllowsChildren()

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

Class AbstractDocument, constructor AbstractDocument(Content)

Constructs a new AbstractDocument wrapped around some specified content storage mechanism. @param data the content
Class AbstractDocument, constructor AbstractDocument(Content, AttributeContext)

Constructs a new AbstractDocument wrapped around some specified content storage mechanism. @param data the content @param context the attribute context
Class AbstractDocument, void addDocumentListener(DocumentListener)

Adds a document listener for notification of any changes. @param listener the listenerDocumentListener to add @see Document#addDocumentListener
Class AbstractDocument, void addUndoableEditListener(UndoableEditListener)

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
Class AbstractDocument, Element createLeafElement(Element, AttributeSet, int, int)

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
Class AbstractDocument, int getAsynchronousLoadPriority()

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
Class AbstractDocument, Thread getCurrentWriter()

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
Class AbstractDocument, Dictionary getDocumentProperties()

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
Class AbstractDocument, EventListener[] getListeners(Class)

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
Class AbstractDocument, Object getProperty(Object)

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
Class AbstractDocument, void getText(int, int, Segment)

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
Class AbstractDocument, void putProperty(Object, Object)

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
Class AbstractDocument, void removeDocumentListener(DocumentListener)

Removes a document listener. @param listener the listenerDocumentListener to remove @see Document#removeDocumentListener
Class AbstractDocument, void removeUndoableEditListener(UndoableEditListener)

Removes an undo listener. @param listener the listenerUndoableEditListener to remove @see Document#removeDocumentListener
Class AbstractDocument, void render(Runnable)

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.

Class AbstractDocument, void setAsynchronousLoadPriority(int)

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
Class AbstractDocument, void setDocumentProperties(Dictionary)

ReplaceReplaces the document properties dictionary for this document. @param x the new dictionary @see #getDocumentProperties
Class AbstractDocument, void writeLock()

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.

Class AbstractDocument, void writeUnlock()

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

Class AbstractWriter

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
Class AbstractWriter, String getText(Element)

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.

Class AsyncBoxView

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


Class AsyncBoxView.ChildLocator, int getViewIndexAtVisualOffset(float)

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.

Class AsyncBoxView, void flushRequirementChanges()

Publish the changes in preferences upward to the parent view. This is normally called by the layout thread.
Class AsyncBoxView, float getMaximumSpan(int)

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
Class AsyncBoxView, float getMinimumSpan(int)

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
Class AsyncBoxView, int getNextVisualPositionFrom(int, Bias, Shape, int, Bias[])

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: @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
Class AsyncBoxView, float getPreferredSpan(int)

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
Class AsyncBoxView, int getViewIndexAtPosition(int, Bias)

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
Class AsyncBoxView, void majorRequirementChange(ChildState, float)

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.

Class AsyncBoxView, void setSize(float, float)

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


Class AttributeSet

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


Class AttributeSet.FontAttribute

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.

Class AttributeSet, Enumeration getAttributeNames()

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
Class AttributeSet, Object ResolveAttribute

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

Class BadLocationException

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.16 0218 12/0203/0001


Class BoxView

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

Class BoxView, constructor BoxView(Element, int)

Constructs a BoxView. @param elem the element this view is responsible for @param axis either View.X_AXIS or View.Y_AXIS
Class BoxView, void forwardUpdate(ElementChange, DocumentEvent, Shape, ViewFactory)

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
Class BoxView, float getAlignment(int)

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
Class BoxView, int getAxis()

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
Class BoxView, Shape getChildAllocation(int, Shape)

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
Class BoxView, int getHeight()

TheReturns the current height of the box. This is the height that it was last allocated. @return the current height of the box
Class BoxView, float getMaximumSpan(int)

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
Class BoxView, float getMinimumSpan(int)

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
Class BoxView, int getOffset(int, int)

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
Class BoxView, float getPreferredSpan(int)

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
Class BoxView, int getResizeWeight(int)

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
Class BoxView, int getSpan(int, int)

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
Class BoxView, View getViewAtPoint(int, int, Rectangle)

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
Class BoxView, int getWidth()

TheReturns the current width of the box. This is the width that it was last allocated. @return the current width of the box
Class BoxView, boolean isAfter(int, int, Rectangle)

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
Class BoxView, boolean isBefore(int, int, Rectangle)

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
Class BoxView, void layout(int, int)

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
Class BoxView, void layoutChanged(int)

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
Class BoxView, void layoutMajorAxis(int, int, int[], int[])

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.
Class BoxView, void layoutMinorAxis(int, int, int[], int[])

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.
Class BoxView, Shape modelToView(int, Shape, Bias)

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
Class BoxView, void paint(Graphics, Shape)

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
Class BoxView, void preferenceChanged(View, boolean, boolean)

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
Class BoxView, void replace(int, int, View[])

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).
Class BoxView, void setAxis(int)

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
Class BoxView, void setSize(float, float)

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

Class Caret

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

Class Caret, int getBlinkRate()

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.

Class ChangedCharSetException

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

Class ComponentView

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

Class ComponentView, float getAlignment(int)

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.
Class ComponentView, float getMaximumSpan(int)

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
Class ComponentView, float getMinimumSpan(int)

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
Class ComponentView, float getPreferredSpan(int)

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
Class ComponentView, void setParent(View)

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

Class ComponentView, void setSize(float, float)

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

Class CompositeView

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:

@author Timothy Prinzing @version 1.5463 0212/0212/0001
Class CompositeView, constructor CompositeView(Element)

Constructs a CompositeView for the given element. @param elem the element this view is responsible for
Class CompositeView, boolean flipEastAndWestAtEnds(int, Bias)

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

Class CompositeView, Shape getChildAllocation(int, Shape)

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
Class CompositeView, Rectangle getInsideAllocation(Shape)

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.
Class CompositeView, int getNextEastWestVisualPositionFrom(int, Bias, Shape, int, Bias[])

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: @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
Class CompositeView, int getNextNorthSouthVisualPositionFrom(int, Bias, Shape, int, Bias[])

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: @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.
Class CompositeView, int getNextVisualPositionFrom(int, Bias, Shape, int, Bias[])

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: @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
Class CompositeView, View getView(int)

GetsReturns the n-th view in this container. @param n the number of the view todesired getview >= 0 && at index n
Class CompositeView, View getViewAtPoint(int, int, Rectangle)

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
Class CompositeView, View getViewAtPosition(int, Rectangle)

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
Class CompositeView, int getViewIndex(int, Bias)

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
Class CompositeView, int getViewIndexAtPosition(int)

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
Class CompositeView, void loadChildren(ViewFactory)

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
Class CompositeView, Shape modelToView(int, Bias, int, Bias, Shape)

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
Class CompositeView, Shape modelToView(int, Shape, Bias)

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
Class CompositeView, void replace(int, int, View[])

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).
Class CompositeView, void setParent(View)

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
Class CompositeView, int viewToModel(float, float, Shape, Bias[])

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

Class DefaultCaret

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.92 02116 12/0903/01 @see Caret

Class DefaultCaret, boolean equals(Object)

Compares this object to the specifedspecified object. The superclass behavior of comparing rectangles is not desired so this is changed to the Object behavior. @param obj the object to compare this font with. @return true if the objects are equal; false otherwise.
Class DefaultCaret, int getBlinkRate()

Gets the caret blink rate. @returnsreturn the delay in milliseconds. If this is zero the caret will not blink. @see Caret#getBlinkRate
Class DefaultCaret, EventListener[] getListeners(Class)

ReturnReturns an array of all the objects currently registered as FooListeners upon this caret. 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 DefaultCaret c for its change listeners ofwith the givenfollowing typecode: that

ChangeListener[] cls = (ChangeListener[])(c.getListeners(ChangeListener.class));
wereIf addedno such listeners toexist this modelmethod returns an empty array. @returnsparam alllistenerType 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 #getChangeListeners @since 1.3

Class DefaultEditorKit

This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document. This implementation provides a default implementation which treats text as plain text and provides a minimal set of actions for a simple editor.

Newlines
There are two properties which deal with newlines. The system property line.separator is defined to be platform-dependent either "\n" "\r" or "\r\n". There is also a property defined in DefaultEditorKit called EndOfLineStringProperty which is defined automatically when a document is loaded to be the first occurrence of any of the newline characters. When a document is loaded EndOfLineStringProperty is set appropriately and when the document is written back out the EndOfLineStringProperty is used. But while the document is in memory the "\n" character is used to define a newline regardless of how the newline is defined when the document is on disk. Therefore for searching purposes "\n" should always be used. When a new document is created and the EndOfLineStringProperty has not been defined it will use the System property when writing out the document.

Note that EndOfLineStringProperty is set on the Document using the get/setProperty methods. Subclasses may override this behavior.

@author Timothy Prinzing @version 1.50 0262 12/0203/0001

Class DefaultEditorKit.BeepAction

Creates a beep.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see DefaultEditorKit#beepAction @see DefaultEditorKit#getActions


Class DefaultEditorKit.CopyAction

CoiesCopies the selected region and place its contents into the system clipboard.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see DefaultEditorKit#copyAction @see DefaultEditorKit#getActions


Class DefaultEditorKit.CutAction

Cuts the selected region and place its contents into the system clipboard.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see DefaultEditorKit#cutAction @see DefaultEditorKit#getActions


Class DefaultEditorKit.DefaultKeyTypedAction

The action that is executed by default if a key typed event is received and there is no keymap entry. There is a variation across different VM's in what gets sent as a key typed event and this action tries to filter out the undesired events. This filters the control characters and those with the ALT modifier. It allows Control-Alt sequences through as these form legitimate unicode characters on some PC keyboards.

If the event doesn't get filtered it will try to insert content into the text editor. The content is fetched from the command string of the ActionEvent. The text entry is done through the replaceSelection method on the target text component. This is the action that will be fired for most text entry tasks.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see DefaultEditorKit#defaultKeyTypedAction @see DefaultEditorKit#getActions @see Keymap#setDefaultAction @see Keymap#getDefaultAction


Class DefaultEditorKit.InsertBreakAction

Places a line/paragraph break into the document. If there is a selection it is removed before the break is added.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see DefaultEditorKit#insertBreakAction @see DefaultEditorKit#getActions


Class DefaultEditorKit.InsertContentAction

Places content into the associated document. If there is a selection it is removed before the new content is added.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see DefaultEditorKit#insertContentAction @see DefaultEditorKit#getActions


Class DefaultEditorKit.InsertTabAction

Places a tab character into the document. If there is a selection it is removed before the tab is added.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see DefaultEditorKit#insertTabAction @see DefaultEditorKit#getActions


Class DefaultEditorKit.PasteAction

Pastes the contents of the system clipboard into the selected region or before the caret if nothing is selected.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see DefaultEditorKit#pasteAction @see DefaultEditorKit#getActions


Class DefaultEditorKit, String beginAction

Name of the Action for moving the caret to the beginingbeginning of the document. @see #getActions
Class DefaultEditorKit, String beginLineAction

Name of the Action for moving the caret to the beginingbeginning of a line. @see #getActions
Class DefaultEditorKit, String beginParagraphAction

Name of the Action for moving the caret to the beginingbeginning of a paragraph. @see #getActions
Class DefaultEditorKit, String beginWordAction

Name of the Action for moving the caret to the beginingbeginning of a word. @see #getActions
Class DefaultEditorKit, String endAction

Name of the Action for moving the caret to the end of the document. @see #getActions
Class DefaultEditorKit, String endLineAction

Name of the Action for moving the caret to the end of a line. @see #getActions
Class DefaultEditorKit, String endParagraphAction

Name of the Action for moving the caret to the end of a paragraph. @see #getActions
Class DefaultEditorKit, String nextWordAction

Name of the Action for moving the caret to the beginingbeginning of the next word. to the next of the document. @see #getActions
Class DefaultEditorKit, String previousWordAction

Name of the Action for moving the caret to the beginingbeginning of the previous word. @see #getActions
Class DefaultEditorKit, String selectionBeginAction

Name of the Action for moving the caret to the beginingbeginning of the document. @see #getActions
Class DefaultEditorKit, String selectionBeginLineAction

Name of the Action for moving the caret to the beginingbeginning of a line extending the selection. @see #getActions
Class DefaultEditorKit, String selectionBeginParagraphAction

Name of the Action for moving the caret to the beginingbeginning of a paragraph extending the selection. @see #getActions
Class DefaultEditorKit, String selectionBeginWordAction

Name of the Action for moving the caret to the beginingbeginning of a word extending the selection. @see #getActions
Class DefaultEditorKit, String selectionEndLineAction

Name of the Action for moving the caret to the end of a line extending the selection. @see #getActions
Class DefaultEditorKit, String selectionEndParagraphAction

Name of the Action for moving the caret to the end of a paragraph extending the selection. @see #getActions
Class DefaultEditorKit, String selectionNextWordAction

Name of the Action for moving the selection to the beginingbeginning of the next word extending the selection. @see #getActions
Class DefaultEditorKit, String selectionPreviousWordAction

Name of the Action for moving the selection to the beginingbeginning of the previous word extending the selection. @see #getActions

Class DefaultHighlighter

Implements the Highlighter interfaces. Implements a simple highlight painter that renders in a solid color. @author Timothy Prinzing @version 1.31 0235 12/0203/0001 @see Highlighter
Class DefaultHighlighter, Object addHighlight(int, int, HighlightPainter)

Adds a highlight to the view. Returns a tag that can be used to refer to the highlight. @param p0 the start offset of the range to highlight >= 0 @param p1 the end offset of the range to highlight >= p0 @param p the painter to use to actually render the highlight @returnsreturn an object that can be used as a tag to refer to the highlight @exception BadLocationException if the specified location is invalid

Class DefaultStyledDocument

A document that can be marked up with character and paragraph styles in a manner similar to the Rich Text Format. The element structure for this document represents style crossings for style runs. These style runs are mapped into a paragraph element structure (which may reside in some other structure). The style runs break at paragraph boundaries since logical styles are assigned to paragraph boundaries.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.113 02120 12/0903/01 @see Document @see AbstractDocument


Class DefaultStyledDocument.ElementBuffer

Class to manage changes to the element hierarchy.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class DefaultStyledDocument.ElementSpec

Specification for building 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. A future releaseAs of Swing will provide1.4 support for long term persistencestorage of all JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class DefaultStyledDocument.SectionElement

Default root element for a document... maps out the paragraphs/lines contained.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class DefaultStyledDocument, Enumeration getStyleNames()

Fetches the list of of style names. @returnsreturn all the style names.
Class DefaultStyledDocument, void styleChanged(Style)

Creates a change event forCalled when any of this the whole document and propagates's itstyles to thehave listenerschanged. Subclasses may wish to be inteligentintelligent about what gets damaged. @param style The Style that has changed.

Class Document

The Document is a container for text that serves as the model for swing text components. The goal for this interface is to scale from very simple needs (a plain text textfield) to complex needs (an HTML or XML documentsdocument for example).

Content

At the simplest level text can be modeled as a linear sequence of characters. To support internationalization the Swing text model uses unicode characters. The sequence of characters displayed in a text component is generally referred to as the component's content.

To refer to locations within the sequence the coordinates used are the location between two characters. As the diagram below shows a location in a text document can be referred to as a position or an offset. This position is zero-based.

In the example if the content of a document is the sequence "The quick brown fox " as shown in the preceding diagram the location just before the word "The" is 0 and the location after the word "The" and before the whitespace that follows it is 3. The entire sequence of characters in the sequence "The" is called a range.

The following methods give access to the character data that makes up the content.

Structure

Text is rarely represented simply as featureless content. Rather text typically has some sort of structure associated with it. Exactly what structure is modeled is up to a particular Document implementation. It might be as simple as no structure (i.e. a simple text field) or it might be something like diagram below.

The unit of structure (i.e. a node of the tree) is referred to by the Element interface. Each Element can be tagged with a set of attributes. These attributes (name/value pairs) are defined by the AttributeSet interface.

The following methods give access to the document structure.

Mutations

All documents need to be able to add and remove simple text. Typically text is inserted and removed via gestures from a keyboard or a mouse. What effect the insertion or removal has upon the document structure is entirely up to the implementation of the document.

The following methods are related to mutation of the document content:

Notification

Mutations to the Document must be communicated to interested observers. The notification of change follows the event model guidelines that are specified for JavaBeans. In the JavaBeans event model once an event notification is dispatched all listeners must be notified before any further mutations occur to the source of the event. Further order of delivery is not guaranteed.

Notification is provided as two seperateseparate events DocumentEvent and UndoableEditEvent. If a mutation is made to a Document through its api a DocumentEvent will be sent to all of the registered DocumentListeners. If the Document implementation supports undo/redo capabilities an UndoableEditEvent will be sent to all of the registered UndoableEditListenersUndoableEditListeners. If an undoable edit is undone a DocumentEvent should be fired from the Document to indicate it has changed again. In this case however there should be no UndoableEditEvent generated since that edit is actually the source of the change rather than a mutation to the Document made through it's api.

Referring to the above diagram suppose that the component shown on the left mutates the document object represented by the blue rectangle. The document responds by dispatching a DocumentEvent to both component views and sends an UndoableEditEvent to the listening logic which maintains a history buffer.

Now suppose that the component shown on the right mutates the same document. Again the document dispatches a DocumentEvent to both component views and sends an UndoableEditEvent to the listening logic that is maintaining the history buffer.

If the history buffer is then rolled back (i.e. the last UndoableEdit undone) a DocumentEvent is sent to both views causing both of them to reflect the undone mutation to the document (that is the removal of the right component's mutation). If the history buffer again rolls back another change another DocumentEvent is sent to both views causing them to reflect the undone mutation to the document -- that is the removal of the left component's mutation.

The methods related to observing mutations to the document are:

Properties

Document implementations will generally have some set of properties associated with them at runtime. Two well known properties are the StreamDescriptionProperty which can be used to describe where the Document came from and the TitleProperty which can be used to name the Document. The methods related to the properties are:

For more information on the Document class see The Swing Connection and most particularly the article The Element Interface. @author Timothy Prinzing @version 1.32 0237 12/0203/0001 @see javax.swing.event.DocumentEvent @see javax.swing.event.DocumentListener @see javax.swing.event.UndoableEditEvent @see javax.swing.event.UndoableEditListener @see Element @see Position @see AttributeSet

Class Document, Object getProperty(Object)

Gets the properties associated with the document. Allows one to store things like the document title author etc. @param key a non-null property key @return the properties @see #putProperty(Object Object)
Class Document, void getText(int, int, Segment)

Fetches the text contained within the given portion of the document.

If the partialReturn property on the txt parameter is false the data returned in the Segment will be the entire length requested and may or may not be a copy depending upon how the data was stored. If the partialReturn property is true only the amount of text that can be returned without creating a copy is returned. Using partial returns will give better performance for situations where large parts of the document are being scanned. The following is an example of using the partial return to access the entire document:

   int nleft = doc.getDocumentLength();   Segment text = new Segment();   int offs = 0;   text.setPartialReturn(true);   while (nleft > 0) {   doc.getText(offs nleft text);   // do someting with text   nleft -= text.count;   offs += text.count;   } 
@param offset the offset into the document representing the desired start of the text >= 0 @param length the length of the desired string >= 0 @param txt the Segment object to return the text in @exception BadLocationException Some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.
Class Document, void putProperty(Object, Object)

PutsAssociates a new property onwith the listdocument. Two standard property keys provided are: StreamDescriptionProperty and TitleProperty. Other properties such as author may also be defined. @param key the non-null property key @param value the property value @see #getProperty(Object)
Class Document, void remove(int, int)

Removes a portion of the content of the document. This will cause a DocumentEvent of type DocumentEvent.EventType.REMOVE to be sent to the registered DocumentListeners unless an exception is thrown. The notification will be sent to the listeners by calling the removeUpdate method on the DocumentListeners.

To ensure reasonable behavior in the face of concurrency the event is dispatched after the mutation has occurred. This means that by the time a notification of removal is dispatched the document has already been updated and any marks created by createPosition have already changed. For a removal the end of the removal range is collapsed down to the start of the range and any marks in the removal range are collapsed down to the start of the range.

If the Document structure changed as result of the removal the details of what Elements were inserted and removed in response to the change will also be contained in the generated DocumentEvent. It is up to the implementation of a Document to decide how the structure should change in response to a remove.

If the Document supports undo/redo an UndoableEditEvent will also be generated. @param offs the offset from the beginingbeginning >= 0 @param len the number of characters to remove >= 0 @exception BadLocationException some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered. @see javax.swing.event.DocumentEvent @see javax.swing.event.DocumentListener @see javax.swing.event.UndoableEditEvent @see javax.swing.event.UndoableEditListener


Class EditorKit

Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content. The EditorKit acts as a factory for some kind of policy. For example an implementation of html and rtf can be provided that is replaceable with other implementations.

A kit can safely store editing state as an instance of the kit will be dedicated to a text component. New kits will normally be created by cloning a prototype kit. The kit will have it's setComponent method called to establish it's relationship with a JTextComponent. @author Timothy Prinzing @version 1.16 0217 12/0203/0001


Class Element

Interface to describe a structural piece of a document. It is intended to capture the spirit of an SGML element. @author Timothy Prinzing @version 1.17 0221 12/0203/0001
Class Element, int getElementIndex(int)

Gets the child element index closest to the given offset. The offset is specified relative to the beginingbeginning of the document. Returns -1 if the Element is a leaf otherwise returns the index of the Element that best represents the given location. Returns 0 if the location is less than the start offset. Returns getElementCount() - 1 if the location is greater than or equal to the end offset. @param offset the specified offset >= 0 @return the element index >= 0
Class Element, int getEndOffset()

Fetches the offset from the beginning of the document that this element ends at. If this element has children this will be the end offset of the last child. As a document position there is an implied backward bias.

All the default Document implementations descend from AbstractDocument. AbstractDocument models an implied break at the end of the document. As a result of this it is possible for this to return a value greater than the length of the document. @return the ending offset >= getStartOffset() and < getDocument().getLength() + 1 @see 0Document @see AbstractDocument

Class Element, Element getParentElement()

Fetches the parent element. If the element is a root level element returns null. @return the parent element
Class Element, int getStartOffset()

Fetches the offset from the beginning of the document that this element begins at. If this element has children this will be the offset of the first child. As a document position there is an implied forward bias. @return the starting offset >= 0 and
Class Element, boolean isLeaf()

Is this element a leaf element An element that may have children even if it currently has no children would return false. @return true if a leaf element else false

Class ElementIterator

ElementIterator as the name suggests iteratates over the Element tree. The constructor can be invoked with either Document or an Element as an argument. If the constructor is invoked with a Document as an argument then the root of the iteration is the return value of document.getDefaultRootElement(). The iteration happens in a depth-first manner. In terms of how boundary conditions are handled: a) if next() is called before first() or current() the root will be returned. b) next() returns null to indicate the end of the list. c) previous() returns null when the current element is the root or next() has returned null. The ElementIterator does no locking of the Element tree. This means that it does not track any changes. It is the responsibility of the user of this class to ensure that no changes happen during element iteration. Simple usage example: public void iterate() { ElementIterator it = new ElementIterator(root); Element elem; while (true) { if ((elem = next()) = null) { // process element System.out.println("elem: " + elem.getName()); } else { break; } } } @author Sunita Mani @version 1.9 0211 12/0203/0001

Class ElementIterator, Element current()

Fetches the current Element. @returnsreturn element on top of the stack or null if the root element is null.
Class ElementIterator, Element next()

Fetches the next Element. The strategy used to locate the next element is a depth-first search. @returnsreturn the next element or null at the end of the list.
Class ElementIterator, Element previous()

Fetches the previous Element. If howver the current element is the last element or the current element is null then null is returned. @returnsreturn previous Element if available.

Class FieldView

Extends the multi-line plain text view to be suitable for a single-line editor view. If the view is allocated extra space the field must adjust for it. If the hosting component is a JTextField this view will manage the ranges of the associated BoundedRangeModel and will adjust the horizontal allocation to match the current visibility settings of the JTextField. @author Timothy Prinzing @version 1.18 0221 12/0203/0001 @see View
Class FieldView, float getPreferredSpan(int)

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.

Class FlowView

A View that tries to flow it's children into some partially constrained space. This can be used to build things like paragraphs pages etc. The flow is made up of the following pieces of functionality. @author Timothy Prinzing @version 1.15 0228 12/0212/0001 @see View

Class FlowView.FlowStrategy, int layoutRow(FlowView, int, int)

Creates a row of views that will fit within the layout span of the row. This is called by the layout method. This is implemented to fill the row by repeatedly calling the createView method until the available span has been exhausted a forced break was encountered or the createView method returned null. If the remaining span was exhaused the adjustRow method will be called to perform adjustments to the row to try and make it fit into the given span. @param rowIndex the index of the row to fill in with views. The row is assumed to be empty on entry. @param pos The current position in the children of this views element from which to start. @returnsreturn the position to start the next row

Class FlowView, int getFlowAxis()

FetchFetches the axis along which views should be flowed. By default this will be the axis orthoginalorthogonal to the axis along which the flow rows are tiled (the axis of the default flow rows themselves). This is typically used by the FlowStrategy.
Class FlowView, int getViewIndexAtPosition(int)

Fetches the child view index representing the given position in the model. @param pos the position >= 0 @returnsreturn index of the view representing the given position or -1 if no view represents that position
Class FlowView, void layout(int, int)

Lays out the children. If the span along the flow axis has changed layout is marked as invalid which which will cause the superclass behavior to recalculate the layout along the box axis. If the FlowStrategy reports that a layout isThe needed the FlowStrategy.layout method will be called to rebuild the flow rows as appropriate. If the height of this view changes (determined by the perferred size along the box axis) a preferenceChanged is messagedcalled. Following all of that the normal box layout of the superclass is performed. @param width the width to lay out against >= 0. This is the width inside of the inset area. @param height the height to lay out against >= 0 This is the height inside of the inset area.

Class GapContent

An implementation of the AbstractDocument.Content interface implemented using a gapped buffer similar to that used by emacs. The underlying storage is a array of unicode characters with a gap somewhere. The gap is moved to the location of changes to take advantage of common behavior where most changes are in the same location. Changes that occur at a gap boundary are generally cheap and moving the gap is generally cheaper than moving the array contents directly to accomodate the change.

The positions tracking change are also generally cheap to maintain. The Position implementations (marks) store the array index and can easily calculate the sequential position from the current gap location. Changes only require update to the the marks between the old and new gap boundaries when the gap is moved so generally updating the marks is pretty cheap. The marks are stored sorted so they can be located quickly with a binary search. This increases the cost of adding a mark and decreases the cost of keeping the mark updated. @author Timothy Prinzing @version 1.15 0221 12/0203/0001

Class GapContent, void updateUndoPositions(Vector, int, int)

Resets the location for all the UndoPosRef instances in positions.

This is meant for internal usage and is generally not of interest to subclasses. @param positions the UndoPosRef instances to reset


Class GlyphView

A GlyphView is a styled chunk of text that represents a view mapped over an element in the text model. This view is generally responsible for displaying text glyphs using character level attributes in some way. An implementation of the GlyphPainter class is used to do the actual rendering and model/view translations. This separates rendering from layout and management of the association with the model.

The view supports breaking for the purpose of formatting. The fragments produced by breaking share the view that has primary responsibility for the element (i.e. they are nested classes and carry only a small amount of state of their own) so they can share its resources.

Since this view represents text that may have tabs embedded in it it implements the TabableView interface. Tabs will only be expanded if this view is embedded in a container that does tab expansion. ParagraphView is an example of a container that does tab expansion.

@since 1.3 @author Timothy Prinzing @version 1.16 0421 12/2103/01


Class GlyphView.GlyphPainter

A class to perform rendering of the glyphs. This can be implemented to be stateless or to hold some information as a cache to facilitate faster rendering and model/view translation. At a minimum the GlyphPainter allows a View implementation to perform its duties independant of a particular version of JVM and selection of capabilities (i.e. shaping for i18n etc). @since 1.3

Class GlyphView, View createFragment(int, int)

Creates a view that represents a portion of the element. This is potentially useful during formatting operations for taking measurements of fragments of the view. If the view doesn't support fragmenting (the default) it should return itself.

This view does support fragmenting. It is implemented to return a nested class that shares state in this view representing only a portion of the view. @param p0 the starting offset >= 0. This should be a value greater or equal to the element starting offset and less than the element ending offset. @param p1 the ending offset > p0. This should be a value less than or equal to the elements end offset and greater than the elements starting offset. @returnsreturn the view fragment or itself if the view doesn't support breaking into fragments. @see LabelView

Class GlyphView, float getAlignment(int)

Determines the desired alignment for this view along an axis. For the label the alignment is along the font baseline for the y axis and the superclasses alignment along the x axis. @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 inclusive 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.
Class GlyphView, float getPreferredSpan(int)

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.
Class GlyphView, int viewToModel(float, float, Shape, Bias[])

Provides a mapping from the view coordinate space to the logical coordinate space of the model. @param x the X coordinate >= 0 @param y the Y coordinate >= 0 @param a the allocated region to render into @param biasReturn either Position.Bias.Forward or Position.Bias.Backward is returned as the zero-th element of this array @return the location within the model that best represents the given point of view >= 0 @see View#viewToModel

Class Highlighter

An interface for an object that allows one to mark up the background with colored areas. @author Timothy Prinzing @version 1.19 0220 12/0203/0001

Class IconView

Icon decorator that implements the view interface. The entire element is used to represent the icon. This acts as a gateway from the display-only View implementations to interactive lightweight icons (that is it allows icons to be embedded into the View hierarchy. The parent of the icon is the container that is handed out by the associated view factory. @author Timothy Prinzing @version 1.23 0226 12/0203/0001
Class IconView, float getAlignment(int)

Determines the desired alignment for this view along an axis. This is implemented to give the alignment to the bottom of the icon along the y axis and the default along the x axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the desired alignment >= 0.0f && < 1.0f. 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.
Class IconView, float getPreferredSpan(int)

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. 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
Class IconView, void setSize(float, float)

Sets the size of the view. Since IconThis should doesn'tcause supportlayout thisof the view along the given functionality there is nothing we can doaxis if it has any layout duties. @param width the width >= 0 @param height the height >= 0

Class JTextComponent

JTextComponent is the base class for swing text components. It tries to be compatible with the java.awt.TextComponent class where it can reasonably do so. Also provided are other services for additional flexibility (beyond the pluggable UI and bean support). You can find information on how to use the functionality this class provides in General Rules for Using Text Components a section in The Java Tutorial.

Caret Changes
The caret is a pluggable object in swing text components. Notification of changes to the caret position and the selection are sent to implementations of the CaretListener interface that have been registered with the text component. The UI will install a default caret unless a customized caret has been set.

Commands
Text components provide a number of commands that can be used to manipulate the component. This is essentially the way that the component expresses its capabilities. These are expressed in terms of the swing Action interface using the TextAction implementation. The set of commands supported by the text component can be found with the #getActions method. These actions can be bound to key events fired from buttons etc.

Text Input
The text components support flexible and internationalized text input using keymaps and the input method framework while maintaining compatibility with the AWT listener model.

A javax.swing.text.Keymap lets an application bind key strokes to actions. In order to allow keymaps to be shared across multiple text components they can use actions that extend TextAction. TextAction can determine which JTextComponent most recently has or had focus and therefore is the subject of the action (In the case that the ActionEvent sent to the action doesn't contain the target text component as its source).

The input method framework lets text components interact with input methods separate software components that preprocess events to let users enter thousands of different characters using keyboards with far fewer keys. JTextComponent is an active client of the framework so it implements the preferred user interface for interacting with input methods. As a consequence some key events do not reach the text component because they are handled by an input method and some text input reaches the text component as committed text within an java.awt.event.InputMethodEvent instead of as a key event. The complete text input is the combination of the characters in keyTyped key events and committed text in input method events.

The AWT listener model lets applications attach event listeners to components in order to bind events to actions. Swing encourages the use of keymaps instead of listeners but maintains compatibility with listeners by giving the listeners a chance to steal an event by consuming it.

Keyboard event and input method events are handled in the following stages with each stage capable of consuming the event:
StageKeyEvent InputMethodEvent
1. input methods (generated here)
2. focus manager
3. registered key listenersregistered input method listeners
4. input method handling in JTextComponent
5. keymap handling using the current keymap
6. keyboard handling in JComponent (e.g. accelerators component navigation etc.)

To maintain compatibility with applications that listen to key events but are not aware of input method events the input method handling in stage 4 provides a compatibility mode for components that do not process input method events. For these components the committed text is converted to keyTyped key events and processed in the key event pipeline starting at stage 3 instead of in the input method event pipeline.

By default the component will create a keymap (named DEFAULT_KEYMAP) that is shared by all JTextComponent instances as the default keymap. Typically a look-and-feel implementation will install a different keymap that resolves to the default keymap for those bindings not found in the different keymap. The minimal bindings include:

  • inserting content into the editor for the printable keys.
  • removing content with the backspace and del keys.
  • caret movement forward and backward

Model/View Split
The text components have a model-view split. A text component pulls together the objects used to represent the model view and controller. The text document model may be shared by other views which act as observers of the model (e.g. a document may be shared by multiple components).

The model is defined by the Document interface. This is intended to provide a flexible text storage mechanism that tracks change during edits and can be extended to more sophisticated models. The model interfaces are meant to capture the capabilities of expression given by SGML a system used to express a wide variety of content. Each modification to the document causes notification of the details of the change to be sent to all observers in the form of a DocumentEvent which allows the views to stay up to date with the model. This event is sent to observers that have implemented the DocumentListener interface and registered interest with the model being observed.

Location Information
The capability of determining the location of text in the view is provided. There are two methods #modelToView and #viewToModel for determining this information.

Undo/Redo support
Support for an edit history mechanism is provided to allow undo/redo operations. The text component does not itself provide the history buffer by default but does provide the UndoableEdit records that can be used in conjunction with a history buffer to provide the undo/redo support. The support is provided by the Document model which allows one to attach UndoableEditListener implementations.

Thread Safety
The swing text components provide some support of thread safe operations. Because of the high level of configurability of the text components it is possible to circumvent the protection provided. The protection primarily comes from the model so the documentation of AbstractDocument describes the assumptions of the protection provided. The methods that are safe to call asynchronously are marked with comments.

Newlines
For a discussion on how newlines are handled see DefaultEditorKit.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @beaninfo attribute: isContainer false @author Timothy Prinzing @version 1.157 02192 12/2803/01 @see Document @see DocumentEvent @see DocumentListener @see Caret @see CaretEvent @see CaretListener @see TextUI @see View @see ViewFactory /


Class JTextComponent.AccessibleJTextComponent

This class implements accessibility support for the JTextComponent class. It provides an implementation of the Java Accessibility API appropriate to menu user-interface 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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder

Class JTextComponent.AccessibleJTextComponent, int getCharCount()

Returns the number of characters (valid indiciesindices) @return the number of characters >= 0
Class JTextComponent.AccessibleJTextComponent, Rectangle getCharacterBounds(int)

Determines the bounding box of the character at the given index into the string. The bounds are returned in local coordinates. If the index is invalid a null rectangle is returned. The screen coordinates returned are "unscrolled coordinates" if the JTextComponent is contained in a JScrollPane in which case the resulting rectangle should be composed with the parent coordinates. A good algorithm to use is: Accessible a: AccessibleText at = a.getAccessibleText(); AccessibleComponent ac = a.getAccessibleComponent(); Rectangle r = at.getCharacterBounds(); Point p = ac.getLocation(); r.x += p.x; r.y += p.y; Note: the JTextComponent must have a valid size (e.g. have been added to a parent container whose ancestor container is a valid top-level window) for this method to be able to return a meaningful (non-null) value. @param i the index into the String >= 0 @return the screen coordinates of the character's bounding box

Class JTextComponent.KeyBinding

Binding record for creating key bindings.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class JTextComponent, constructor JTextComponent()

Creates a new JTextComponent. Listeners for caret events are established and the pluggable UI installed. The component is marked as editable. No layout manager is used because layout is managed by the view subsystem of text. The document model is set to null.
Class JTextComponent, void addCaretListener(CaretListener)

Adds a caret listener for notification of any changes to the caret. @param listener the listener to be added @see javax.swing.event.CaretEvent
Class JTextComponent, Keymap addKeymap(String, Keymap)

Adds a new keymap into the keymap hierarchy. Keymap bindings resolve from bottom up so an attribute specified in a child will override an attribute specified in the parent. @param nm the name of the keymap (must be unique within the collection of named keymaps in the document). The; the name may be null if the keymap is unnamed but the caller is responsible for managing the reference returned as an unnamed keymap can't be fetched by name. @param parent the parent keymap. This; this may be null if unspecified bindings need not be resolved in some other keymap. @return the keymap
Class JTextComponent, void copy()

Transfers the currently selected range in the associated text model to the system clipboard leaving the contents in the text model. The current selection is remains intact. Does nothing for null selections. @see java.awt.Toolkit#getSystemClipboard @see java.awt.datatransfer.Clipboard
Class JTextComponent, void cut()

Transfers the currently selected range in the associated text model to the system clipboard removing the contents from the model. The current selection is reset. Does nothing for null selections. @see java.awt.Toolkit#getSystemClipboard @see java.awt.datatransfer.Clipboard
Class JTextComponent, AccessibleContext getAccessibleContext()

Gets the AccessibleContext associated with this JTextComponent. For text components the AccessibleContext takes the form of an AccessibleJTextComponent. A new AccessibleJTextComponent instance is created if necessary. @return an AccessibleJTextComponent that serves as the AccessibleContext of this JTextComponent
Class JTextComponent, Keymap getKeymap(String)

Fetches a named keymap previously added to the document. This does not work with null-named keymaps. @param nm the name of the keymap @return the keymap
Class JTextComponent, Dimension getPreferredScrollableViewportSize()

Returns the preferred size of the viewport for a view component. This is implemented to do the default behavior of returning the preferred size of the component. @return Thethe preferredSize of a JViewport whose view is this Scrollable.
Class JTextComponent, int getScrollableBlockIncrement(Rectangle, int, int)

Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns depending on the value of orientation.

The default implementation of this is to simply return the visible area. Subclasses will likely be able to provide a much more reasonable value. @param visibleRect Thethe view area visible within the viewport @param orientation Eithereither SwingConstants.VERTICAL or SwingConstants.HORIZONTAL. @param direction Lessless than zero to scroll up/left greater than zero for down/right. @return Thethe "block" increment for scrolling in the specified direction. @exception IllegalArgumentException for an invalid orientation @see JScrollBar#setBlockIncrement

Class JTextComponent, boolean getScrollableTracksViewportHeight()

ReturnReturns true if a viewport should always force the height of this Scrollable to match the height of the viewport. For example a columnar text view that flowed text in left to right columns could effectively disable vertical scrolling by returning true here.

Scrolling containers like JViewport will use this method each time they are validated. @return true if a viewport should force the Scrollables height to match its own.

Class JTextComponent, boolean getScrollableTracksViewportWidth()

ReturnReturns true if a viewport should always force the width of this Scrollable to match the width of the viewport. For example a normal text view that supported line wrapping would return true here since it would be undesirable for wrapped lines to disappear beyond the right edge of the viewport. Note that returning true for a Scrollable whose ancestor is a JScrollPane effectively disables horizontal scrolling.

Scrolling containers like JViewport will use this method each time they are validated. @return true if a viewport should force the ScrollablesScrollables width to match its own.

Class JTextComponent, int getScrollableUnitIncrement(Rectangle, int, int)

Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column depending on the value of orientation. Ideally components should handle a partially exposed row or column by returning the distance required to completely expose the item.

The default implementation of this is to simply return 10% of the visible area. Subclasses are likely to be able to provide a much more reasonable value. @param visibleRect Thethe view area visible within the viewport @param orientation Eithereither SwingConstants.VERTICAL or SwingConstants.HORIZONTAL. @param direction Lessless than zero to scroll up/left greater than zero for down/right. @return Thethe "unit" increment for scrolling in the specified direction @exception IllegalArgumentException for an invalid orientation @see JScrollBar#setUnitIncrement

Class JTextComponent, String getSelectedText()

Returns the selected text contained in this TextComponent. If the selection is null or the document empty returns null. @return the text @exception IllegalArgumentException if the selection doesn't have a valid mapping into the document for some reason @see #setText
Class JTextComponent, String getText()

Returns the text contained in this TextComponent. If the underlying document is null will give a NullPointerException. @return the text @exception NullPointerException if the document is null @see #setText
Class JTextComponent, boolean isEditable()

Returns the boolean indicating whether this TextComponent is editable or not. @return the boolean value @see #setEditable
Class JTextComponent, boolean isFocusTraversable()

Returns truewhether ifthis Component can become the focus canowner. be@return traversed.true This wouldif this beComponent falseis focusable; forfalse componentsotherwise like@see a#setFocusable disabled@since buttonJDK1.1 @return true ifdeprecated As of the1.4 focus isreplaced by traversableisFocusable().
Class JTextComponent, void loadKeymap(Keymap, KeyBinding[], Action[])

Loads a keymap with a bunch of bindings. This can be used to take a static table of definitions and load them into some keymap. The following example illustrates an example of binding some keys to the cut copy and paste actions associated with a JTextComponent. A code fragment to accomplish this might look as follows:

 static final JTextComponent.KeyBinding[] defaultBindings = { new JTextComponent.KeyBinding( KeyStroke.getKeyStroke(KeyEvent.VK_C InputEvent.CTRL_MASK) DefaultEditorKit.copyAction) new JTextComponent.KeyBinding( KeyStroke.getKeyStroke(KeyEvent.VK_V InputEvent.CTRL_MASK) DefaultEditorKit.pasteAction) new JTextComponent.KeyBinding( KeyStroke.getKeyStroke(KeyEvent.VK_X InputEvent.CTRL_MASK) DefaultEditorKit.cutAction) }; JTextComponent c = new JTextPane(); Keymap k = c.getKeymap(); JTextComponent.loadKeymap(k defaultBindings c.getActions()); 
The sets of bindings and actions may be empty but must be non-null. @param map the keymap @param bindings the bindings @param actions the set of actions
Class JTextComponent, void moveCaretPosition(int)

Moves the caret to a new position leaving behind a mark defined by the last time setCaretPosition was called. This forms a selection. If the document is null does nothing. The position must be between 0 and the length of the component's text or else an exception is thrown. @param pos the position @exception IllegalArgumentException if the value supplied for position is less than zero or greater than the component's text length @see #setCaretPosition
Class JTextComponent, String paramString()

Returns a string representation of this JTextComponent. This method is intended to be used only for debugging purposes and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overriding paramString() to provide information about the specific new aspects of the JFC components. @return a string representation of this JTextComponent.

Class JTextComponent, void paste()

Transfers the contents of the system clipboard into the associated text model. If there is a selection in the associated view it is replaced with the contents of the clipboard. If there is no selection the clipboard contents are inserted in front of the current insert position in the associated view. If the clipboard is empty does nothing. @see #replaceSelection @see java.awt.Toolkit#getSystemClipboard @see java.awt.datatransfer.Clipboard
Class JTextComponent, void read(Reader, Object)

Initializes from a stream. This creates a model of the type appropriate for the component and initializes the model from the stream. By default this will load the model as plain text. Previous contents of the model are discarded. @param in Thethe stream to read from @param desc Anan object describing the stream. This; this might be a string a File a URL etc. Some kinds of documents (such as html for example) might be able to make use of this information.; Ifif non-null it is added as a property of the document. @exception IOException as thrown by the stream being used to initialize. @see EditorKit#createDefaultDocument @see #setDocument @see PlainDocument
Class JTextComponent, void removeCaretListener(CaretListener)

Removes a caret listener. @param listener the listener to be removed @see javax.swing.event.CaretEvent
Class JTextComponent, Keymap removeKeymap(String)

Removes a named keymap previously added to the document. Keymaps with null names may not be removed in this way. @param nm the name of the keymap to remove @return the keymap that was removed
Class JTextComponent, void select(int, int)

Selects the text found between the specified start and end locationspositions.

This method sets the start and end positions of the selected text enforcing the restriction that the start position must be greater than or equal to zero. The end position must be greater than or equal to the start position and less than or equal to the length of the text component's text.

If the caller supplies values that are inconsistent or out of bounds the method enforces these constraints silently and without failure. Specifically if the start position or end position is greater than the length of the text it is reset to equal the text length. If the start position is less than zero it is reset to zero and if the end position is less than the start position it is reset to the start position.

This call is provided for backward compatibility. It is routed to a call to setCaretPosition followed by a call to moveCaretPostionmoveCaretPosition. The preferred way to manage selection is by calling those methods directly. @param selectionStart the start position of the text = 0 @param selectionEnd the end position of the text = 0 @see #setCaretPosition @see #moveCaretPosition

Class JTextComponent, void selectAll()

Selects all the text in the TextComponent. Does nothing on a null or empty document.
Class JTextComponent, void setCaretColor(Color)

Sets the current color used to render the caret. Setting to null effectively restores the default color. Setting the color results in a PropertyChange event ("caretColor") being fired. @param c the color @see #getCaretColor @beaninfo description: the color used to render the caret bound: true preferred: true
Class JTextComponent, void setCaretPosition(int)

Sets the position of the text insertion caret for the TextComponent. Note that the caret tracks change so this may move if the underlying text of the component is changed. If the document is null does nothing. The position must be between 0 and the length of the component's text or else an exception is thrown. @param position the position @exception IllegalArgumentException if the value supplied for position is less than zero or greater than the component's text length @beaninfo description: the caret position
Class JTextComponent, void setEditable(boolean)

Sets the specified boolean to indicate whether or not this TextComponent should be editable. A PropertyChange event ("editable") is fired when the state is changed. @param b the boolean to be set @see #isEditable @beaninfo description: specifies if the text can be edited bound: true
Class JTextComponent, void setHighlighter(Highlighter)

Sets the highlighter to be used. By default this will be set by the UI that gets installed. This can be changed to a custom highlighter if desired. The highlighter can be set to null to disable it. A PropertyChange event ("highlighter") is fired when a new highlighter is installed. @param h the highlighter @see #getHighlighter @beaninfo description: object responsible for background highlights bound: true expert: true
Class JTextComponent, void setKeymap(Keymap)

Sets the keymap to use for binding events to actions. Setting to null effectively disables keyboard input. A PropertyChange event ("keymap") is fired when a new keymap is installed. @param map the keymap @see #getKeymap @beaninfo description: set of key event to action bindings to use bound: true
Class JTextComponent, void setMargin(Insets)

Sets margin space between the text component's border and its text. The text component's default Border object will use this value to create the proper margin. However if a non-default border is set on the text component it is that Border object's responsibility to create the appropriate margin space (else this property will effectively be ignored). This causes a redraw of the component. A PropertyChange event ("margin") is sent to all listeners. @param m the space between the border and the text @beaninfo description: desired space between the border and text area bound: true
Class JTextComponent, void setSelectedTextColor(Color)

Sets the current color used to render the selected text. Setting the color to null is the same as Color.black. Setting the color results in a PropertyChange event ("selectedTextColor") being fired. @param c the color @see #getSelectedTextColor @beaninfo description: color used to render selected text bound: true preferred: true
Class JTextComponent, void setSelectionColor(Color)

Sets the current color used to render the selection. Setting the color to null is the same as setting Color.white. Setting the color results in a PropertyChange event ("selectionColor"). @param c the color @see #getSelectionColor @beaninfo description: color used to render selection background bound: true preferred: true
Class JTextComponent, void setSelectionEnd(int)

Sets the selection end to the specified position. The new end point is constrained to be at or after the current selection start.

This is available for backward compatiblititycompatibility to code that called this method on java.awt.TextComponent. This is implemented to forward to the Caret implementation which is where the actual selection is maintained. @param selectionEnd the end position of the text >= 0 @beaninfo description: ending location of the selection.

Class JTextComponent, void setSelectionStart(int)

Sets the selection start to the specified position. The new starting point is constrained to be before or at the current selection end.

This is available for backward compatiblititycompatibility to code that called this method on java.awt.TextComponent. This is implemented to forward to the Caret implementation which is where the actual selection is maintained. @param selectionStart the start position of the text >= 0 @beaninfo description: starting location of the selection.

Class JTextComponent, void setText(String)

Sets the text of this TextComponent to the specified text. If the text is null or empty has the effect of simply deleting the old text. When text has been inserted the resulting caret location is determined by the implementation of the caret class.

This method is thread safe although most Swing methods are not. Please see Threads and Swing for more information. @param t the new text to be set @see #getText @see DefaultCaret @beaninfo description: the text of this component

Class JTextComponent, void setUI(TextUI)

Sets the user-interface factory for this text-oriented editor. @param ui the factory
Class JTextComponent, void updateUI()

Reloads the pluggable UI. The key used to fetch the new interface is getUIClassID(). The type of the UI is TextUI. invalidate() is called after setting the UI.
Class JTextComponent, String DEFAULT_KEYMAP

ThisThe is the name of the default keymap that will be shared by all JTextComponent instances unless they have had a different keymap set.

Class Keymap

A collection of bindings of KeyStrokes to actions. The bindings are basically name-value pairs that potentially resolve in a hierarchy. @author Timothy Prinzing @version 1.14 0216 12/0203/0001
Class Keymap, Action getAction(KeyStroke)

Fetches the action appropriate for the given symbolic event sequence. This is used by JTextController to determine how to interpret key sequences. If the binding is not resolved locally an attempt is made to resolve through the parent keymap if one is set. @param key the key sequence @returnsreturn the action associated with the key sequence if one is defined otherwise null

Class LabelView

A LabelView is a styled chunk of text that represents a view mapped over an element in the text model. It caches the character level attributes used for rendering. @author Timothy Prinzing @version 1.56 0260 12/0203/0001
Class LabelView, Color getBackground()

FetchFetches the background color to use to render the glyphs. If thereThis is no backgroundimplemented color null should beto return a cached returned.background This is implementedcolor which defaults to null. @return athe cached background color.
Class LabelView, Font getFont()

FetchFetches the font that the glyphs should be based upon. This is implemented to return a cached font. @return the cached font
Class LabelView, FontMetrics getFontMetrics()

FetchFetches the FontMetrics used for this view. @deprecated FontMetrics are not used for glyph rendering when running in the Java2 SDK.
Class LabelView, Color getForeground()

FetchFetches the foreground color to use to render the glyphs. If thereThis is no foregroundimplemented color null should beto return a cached returned.foreground This is implementedcolor which defaults to null. @return athe cached foreground color.
Class LabelView, boolean isStrikeThrough()

DetermineDetermines if the glyphs should have a strikethrough line. If true a line should be drawn through the center of the glyphs. This is implemented to return the cached strikeThrough property.

When you request this property LabelView re-syncs its state with the properties of the Element's AttributeSet. If Element's AttributeSet does not have this property set it will revert to false. @return the value of the cached strikeThrough property

Class LabelView, boolean isSubscript()

DetermineDetermines if the glyphs should be rendered as superscript. @return the value of the cached subscript property

When you request this property LabelView re-syncs its state with the properties of the Element's AttributeSet. If Element's AttributeSet does not have this property set it will revert to false. @return the value of the cached subscript property

Class LabelView, boolean isSuperscript()

DetermineDetermines if the glyphs should be rendered as subscript.

When you request this property LabelView re-syncs its state with the properties of the Element's AttributeSet. If Element's AttributeSet does not have this property set it will revert to false. @return the value of the cached superscript property

Class LabelView, boolean isUnderline()

DetermineDetermines if the glyphs should be underlined. If true an underline should be drawn through the baseline. This is implemented to return the cached underline property.

When you request this property LabelView re-syncs its state with the properties of the Element's AttributeSet. If Element's AttributeSet does not have this property set it will revert to false. @return the value of the cached underline property

Class LabelView, void setPropertiesFromAttributes()

SetSets the cached properties from the attributes.
Class LabelView, void setStrikeThrough(boolean)

SetSets whether or not the view has a strike/line through it. Note that this setter is protected and is really only meant if you need to update some additional state when set. @param u true if the view has a strike/line through it otherwise false @see #isStrikeThrough
Class LabelView, void setSubscript(boolean)

SetSets whether or not the view represents a subscript. Note that this setter is protected and is really only meant if you need to update some additional state when set. @param u true if the view represents a subscript otherwise false @see #isSubscript
Class LabelView, void setSuperscript(boolean)

SetSets whether or not the view represents a superscript. Note that this setter is protected and is really only meant if you need to update some additional state when set. @param u true if the view represents a superscript otherwise false @see #isSuperscript
Class LabelView, void setUnderline(boolean)

SetSets whether or not the view is underlined. Note that this setter is protected and is really only meant if you need to update some additional state when set. @param u true if the view is underlined otherwise false @see #isUnderline

Class LayeredHighlighter

@author Scott Violet @author Timothy Prinzing @version 1.4 025 12/0203/0001 @see Highlighter

Class LayoutQueue

A queue of text layout tasks. @author Timothy Prinzing @version 1.3 024 12/0203/0001 @see AsyncBoxView @since 1.3

Class MutableAttributeSet

A generic interface for a mutable collection of unique attributes. Implementations will probably want to provide a constructor of the form: public XXXAttributeSet(ConstAttributeSet source); @version 1.12 0214 12/0203/0001
Class MutableAttributeSet, void removeAttribute(Object)

Creates aRemoves an new attribute set similar to this one except that it contains no attribute with the given name. @param name the attribute name
Class MutableAttributeSet, void removeAttributes(AttributeSet)

CreatesRemoves a new attribute set similar to this one except that it contains no attribute with any of the given names and values. Existing attributes with the samegiven name and different value will remain. @param attributes the set of attributes
Class MutableAttributeSet, void removeAttributes(Enumeration)

Creates aRemoves an new attribute set similar to this one except that it contains no attribute with any of the given names. @param names the set of names

Class ParagraphView

View of a simple line-wrapping paragraph that supports multiple fonts colors components icons etc. It is basically a vertical box with a margin around it. The contents of the box are a bunch of rows which are special horizontal boxes. This view creates a collection of views that represent the child elements of the paragraph element. Each of these views are placed into a row directly if they will fit otherwise the breakView method is called to try and carve the view into pieces that fit. @author Timothy Prinzing @author Scott Violet @version 1.76 0282 12/0203/0001 @see View
Class ParagraphView, constructor ParagraphView(Element)

Constructs a ParagraphView for the given element. @param elem the element that this view is responsible for
Class ParagraphView, void adjustRow(Row, int, int)

Adjusts the given row if possible to fit within the layout span. By default this will try to find the highest break weight possible nearest the end of the row. If a forced break is encountered the break will be positioned there.

This is meant for internal usage and should not be used directly. @param r the row to adjust to the current layout span. @param desiredSpan the current layout span >= 0 @param x the location r starts at.

Class ParagraphView, View breakView(int, float, Shape)

Breaks this view on the given axis at the given length.

ParagraphView instances are breakable along the Y_AXIS only and only if len is after the first line. @param axis may be either View.X_AXIS or View.Y_AXIS @param len specifies where a potential break is desired along the given axis >= 0 @param a the current allocation of the view @return the fragment of the view that represents the given span if the view can be broken. If; if the view doesn't support breaking behavior the view itself is returned. @see View#breakView

Class ParagraphView, View createRow()

Create a View that should be used to hold a a rowsrow's worth of children in a flow. @return the new View
Class ParagraphView, int findOffsetToCharactersInString(char[], int)

Finds the next character in the document with a character in string starting at offset start. If there are no characters found -1 will be returned. @param string the string of characters @param start where to start in the model >= 0 @return the document offset or -1 if no characters found
Class ParagraphView, float getAlignment(int)

Determines the desired alignment for this view along an axis. This is implemented to give the alignment to the center of the first row along the y axis and the default along the x axis. @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 inclusive 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.
Class ParagraphView, int getBreakWeight(int, float)

Gets the break weight for a given location.

ParagraphView instances are breakable along the Y_AXIS only and only if len is after the first row. If the length is less than one row a value of BadBreakWeight is returned. @param axis may be either View.X_AXIS or View.Y_AXIS @param len specifies where a potential break is desired >= 0 @return a value indicating the attractiveness of breaking here; either GoodBreakWeight or BadBreakWeight @see View#getBreakWeight

Class ParagraphView, int getClosestPositionTo(int, Bias, Shape, int, Bias[], int, int)

Returns the closest model position to x. rowIndex gives the index of the view that corresponds that should be looked in. @param pos position into the model @param a the allocated region to render into @param direction one of the following values: @param biasRet an array containing the bias that were checked in this method @param rowIndex the index of the view @param x the x coordinate of interest @return the closest model position to x
Class ParagraphView, int getFlowSpan(int)

FetchFetches the constraining span to flow against for the given child index. @param index the index of the view being queried @return the constraining span for the given view at index
Class ParagraphView, int getFlowStart(int)

FetchFetches the location along the flow axis that the flow span will start at. @param index the index of the view being queried @return the location for the given view at index
Class ParagraphView, View getLayoutView(int)

Returns the view at a given index. The child views of the paragraph are rows which have been used to arrange pieces of the Views that represent the child elements. This methods returns the view responsible for the child element index (prior to breaking). These are the Views that were produced from a factory (to represent the child elements) and used for layout. @param index the index of the desired view @return the view at index
Class ParagraphView, int getLayoutViewCount()

Returns the number of views that this view is responsible for. The child views of the paragraph are rows which have been used to arrange pieces of the ViewsViews that represent the child elements. This is the number of views that have been tiled in two dimensions and should be equivalent to the number of child elements to the element this view is responsible for. @return the number of views that this ParagraphView is responsible for
Class ParagraphView, int getNextNorthSouthVisualPositionFrom(int, Bias, Shape, int, Bias[])

OverridenReturns the next visual position for the cursor in either the east or west direction. Overridden from CompositeView. @param pos position into the model @param bias either Position.Bias.Forward or Position.Bias.Backward @param a the allocated region to render into @param direction either SwingConstants.NORTH or SwingConstants.SOUTH @param biasRet an array containing the bias that were checked in this method @return the location in the model that represents the next location visual position
Class ParagraphView, float getPartialSize(int, int)

Returns the size used by the views between startOffset and endOffset. This uses getPartialView to calculate the size if the child view implements the TabableView interface. If a size is needed and a View does not implement the TabableView interface the preferredSpan will be used. @param startOffset the starting document offset >= 0 @param endOffset the ending document offset >= startOffset @return the size >= 0
Class ParagraphView, float getTabBase()

Returns where the tabs are calculated from. @return where tabs are calculated from.
Class ParagraphView, TabSet getTabSet()

Gets the Tabset to be used in calculating tabs. @return the TabSet
Class ParagraphView, float nextTabStop(float, int)

Returns the next tab stop position given a reference position. This view implements the tab coordinate system and calls getTabbedSpan on the logical children in the process of layout to determine the desired span of the children. The logical children can delegate their tab expansion upward to the paragraph which knows how to expand tabs. LabelView is an example of a view that delegates its tab expansion needs upward to the paragraph.

This is implemented to try and locate a TabSet in the paragraph element's attribute set. If one can be found its settings will be used otherwise a default expansion will be provided. The base location for for tab expansion is the left inset from the paragraphs most recent allocation (which is what the layout of the children is based upon). @param x the X reference position @param tabOffset the position within the text stream that the tab occurred at >= 0. @return the trailing end of the tab expansion >= 0 @see TabSet @see TabStop @see LabelView

Class ParagraphView, void setFirstLineIndent(float)

SetSets the indent on the first line. @param lsfi the value in points
Class ParagraphView, void setJustification(int)

SetSets the type of justification. @param j one of the following values:
Class ParagraphView, void setLineSpacing(float)

SetSets the line spacing. @param ls the value in points

Class PasswordView

Implements a View suitable for use in JPasswordField UI implementations. This is basically a field ui that renders its contents as the echo character specified in the associated component (if it can narrow the component to a JPasswordField). @author Timothy Prinzing @version 1.13 0217 12/0203/0001 @see View
Class PasswordView, int drawSelectedText(Graphics, int, int, int, int)

Renders the given range in the model as selected text. This is implemented to render the text in the color specified in the hosting component. It assumes the highlighter will render the selected background. Uses the result of getEchoChar() to display the characters. @param g the graphics context @param x the starting X coordinate >= 0 @param y the starting Y coordinate >= 0 @param p0 the starting offset in the model >= 0 @param p1 the ending offset in the model >= p0 @returnsreturn the X location of the end of the range >= 0. @exception BadLocationException if p0 or p1 are out of range
Class PasswordView, int drawUnselectedText(Graphics, int, int, int, int)

Renders the given range in the model as normal unselected text. This sets the foreground color and echos the characters using the value returned by getEchoChar(). @param g the graphics context @param x the starting X coordinate >= 0 @param y the starting Y coordinate >= 0 @param p0 the starting offset in the model >= 0 @param p1 the ending offset in the model >= p0 @returnsreturn the X location of the end of the range >= 0 @exception BadLocationException if p0 or p1 are out of range
Class PasswordView, float getPreferredSpan(int)

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.

Class PlainDocument

A plain document that maintains no character attributes. The default element structure for this document is a map of the lines in the text. The Element returned by getDefaultRootElement is a map of the lines and each child element represents a line. This model does not maintain any character level attributes but each line can be tagged with an arbitrary set of attributes. Line to offset and offset to line translations can be quickly performed using the default root element. The structure information of the DocumentEvent's fired by edits will indicate the line structure changes.

The default content storage management is performed by a gapped buffer implementation (GapContent). It supports editing reasonably large documents with good efficiency when the edits are contiguous or clustered as is typical.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.34 0239 12/0203/0001 @see Document @see AbstractDocument

Class PlainDocument, constructor PlainDocument()

Constructs a plain text document. A default model using StringContentGapContent is constructed and set.

Class PlainView

Implements View interface for a simple multi-line text view that has text in one font and color. The view represents each child element as a line of text. @author Timothy Prinzing @version 1.63 0269 12/0203/0001 @see View
Class PlainView, void drawLine(int, Graphics, int, int)

Renders a line of text suppressing whitespace at the end and exandingexpanding any tabs. This is implemented to make calls to the methods drawUnselectedText and drawSelectedText so that the way selected and unselected text are rendered can be customized. @param lineIndex the line to draw >= 0 @param g the graphicsGraphics context @param x the starting X position >= 0 @param y the starting Y position >= 0 @see #drawUnselectedText @see #drawSelectedText
Class PlainView, int drawSelectedText(Graphics, int, int, int, int)

Renders the given range in the model as selected text. This is implemented to render the text in the color specified in the hosting component. It assumes the highlighter will render the selected background. @param g the graphics context @param x the starting X coordinate >= 0 @param y the starting Y coordinate >= 0 @param p0 the beginning position in the model >= 0 @param p1 the ending position in the model >= 0 @returnsreturn the location of the end of the range. @exception BadLocationException if the range is invalid
Class PlainView, int drawUnselectedText(Graphics, int, int, int, int)

Renders the given range in the model as normal unselected text. Uses the foreground or disabled color to render the text. @param g the graphics context @param x the starting X coordinate >= 0 @param y the starting Y coordinate >= 0 @param p0 the beginning position in the model >= 0 @param p1 the ending position in the model >= 0 @returnsreturn the X location of the end of the range >= 0 @exception BadLocationException if the range is invalid
Class PlainView, Segment getLineBuffer()

Gives access to a buffer that can be used to fetch text from the associated document. @returnsreturn the buffer
Class PlainView, float getPreferredSpan(int)

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
Class PlainView, void setSize(float, float)

Sets the size of the view. This should cause layout of the view along the given axis if it has any layout duties. The default is to do nothing. @param width the width >= 0 @param height the height >= 0
Class PlainView, FontMetrics metrics

Font metrics for the currrentcurrent font.

Class Position

Represents a location within a document. It is intended to abstract away implementation details of the document and enable specification of positions within the document that are capable of tracking of change as the document is edited (i.e. offsets are fragile). @author Timothy Prinzing @version 1.15 0216 12/0203/0001

Class Segment

A segment of a character array representing a fragment of text. It should be treated as immutable even though the array is directly accessableaccessible. This gives fast access to fragments of text without the overhead of copying around characters. This is effectively an unprotected String.

The Segment implements the java.text.CharacterIterator interface to support use with the i18n support without copying text into a string. @author Timothy Prinzing @version 1.1820 0412/2103/01


Class SimpleAttributeSet

A straightforward implementation of MutableAttributeSet using a hash table.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @version 1.32 0237 12/0203/0001 @author Tim Prinzing

Class SimpleAttributeSet, boolean equals(Object)

Compares this object to the specifedspecified object. The result is true if the object is an equivalent set of attributes. @param obj the object to compare this fontattribute set with. @return true if the objects are equal; false otherwise.
Class SimpleAttributeSet, Enumeration getAttributeNames()

Gets the names of the attributes in the set. @return the names as an Enumeration
Class SimpleAttributeSet, boolean isEqual(AttributeSet)

Compares two attribute sets. @param attr the second attribute set @return true if equathethe sets are equal false listlotherwise

Class StringContent

An implementation of the AbstractDocument.Content interface that is a brute force implementation that is useful for relatively small documents and/or debugging. It manages the character content as a simple character array. It is also quite inefficient.

It is generally recommended that the gap buffer or piece table implementations be used instead. This buffer does not scale up to large sizes.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.37 0242 12/0203/0001

Class StringContent, Vector getPositionsInRange(Vector, int, int)

Returns a Vector containing instances of UndoPosRef for the Positions in the range offset to offset + length. If v is not null the matching Positions are placed in there. The vector with the resulting Positions are returned.

This is meant for internal usage and is generally not of interest to subclasses. @param v the Vector to use with a new one created on null @param offset the starting offset >= 0 @param length the length >= 0 @return the set of instances

Class StringContent, void updateUndoPositions(Vector)

Resets the location for all the UndoPosRef instances in positions.

This is meant for internal usage and is generally not of interest to subclasses. @param positions the positions of the instances


Class Style

A collection of attributes to associate with an element in a document. Since these are typically used to associate character and paragraph styles with the element operations for this are provided. Other customized attributes that get associated with the element will effectively be name-value pairs that live in a hierarchy and if a name (key) is not found locally the request is forwarded to the parent. Commonly used attributes are seperatedseparated out to facilitate alternative implementations that are more efficient. @author Timothy Prinzing @version 1.1619 0212/0203/0001
Class Style, String getName()

Fetches the name of the style. A style is not required to be named so null is returned if there is no name associated with the style. @return the name

Class StyleConstants

A collection of well known or common attribute keys and methods to apply to an AttributeSet or MutableAttributeSet to get/set the properties in a typesafe manner.

The paragraph attributes form the definition of a paragraph to be rendered. All sizes are specified in points (such as found in postscript) a device independent measure.

@author Timothy Prinzing @version 1.27 0229 12/0203/0001

Class StyleConstants, int getAlignment(AttributeSet)

Gets the alignment setting. @param a the attribute set @returnsreturn the value StyleConstants.ALIGN_LEFT if not set
Class StyleConstants, int getBidiLevel(AttributeSet)

Gets the BidiLevel setting. @param a the attribute set @returnsreturn the value
Class StyleConstants, float getFirstLineIndent(AttributeSet)

Gets the first line indent setting. @param a the attribute set @returnsreturn the value 0 if not set
Class StyleConstants, float getLeftIndent(AttributeSet)

Gets the left indent setting. @param a the attribute set @returnsreturn the value 0 if not set
Class StyleConstants, float getLineSpacing(AttributeSet)

Gets the line spacing setting. @param a the attribute set @returnsreturn the value 0 if not set
Class StyleConstants, float getRightIndent(AttributeSet)

Gets the right indent setting. @param a the attribute set @returnsreturn the value 0 if not set
Class StyleConstants, float getSpaceAbove(AttributeSet)

Gets the space above setting. @param a the attribute set @returnsreturn the value 0 if not set
Class StyleConstants, float getSpaceBelow(AttributeSet)

Gets the space below setting. @param a the attribute set @returnsreturn the value 0 if not set
Class StyleConstants, TabSet getTabSet(AttributeSet)

Gets the TabSet. @param a the attribute set @returnsreturn the TabSet.

Class StyleContext

A pool of styles and their associated resources. This class determines the lifetime of a group of resources by being a container that holds caches for various resources such as font and color that get reused by the various style definitions. This can be shared by multiple documents if desired to maximize the sharing of related resources.

This class also provides efficient support for small sets of attributes and compresses them by sharing across uses and taking advantage of their immutable nature. Since many styles are replicated the potential for sharing is significant and copies can be extremely cheap. Larger sets reduce the possibility of sharing and therefore revert automatically to a less space-efficient implementation.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.65 0271 12/0203/0001


Class StyleContext.NamedStyle

A collection of attributes typically used to represent character and paragraph styles. This is an implementation of MutableAttributeSet that can be observed if desired. These styles will take advantage of immutability while the sets are small enough and may be substantially more efficient than something like SimpleAttributeSet.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder

Class StyleContext.NamedStyle, EventListener[] getListeners(Class)

Return an array of all the listeners of the given type that were added to this model. @returnsreturn all of the objects recievingreceiving listenerType notifications from this model @since 1.3

Class StyledDocument

Interface for a generic styled document. @author Timothy Prinzing @version 1.18 0219 12/0203/0001

Class StyledEditorKit

This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document. This implementation provides a default implementation which treats text as styled text and provides a minimal set of actions for editing styled text. @author Timothy Prinzing @version 1.33 0241 12/0203/0001

Class StyledEditorKit.AlignmentAction

An action to set paragraph alignment. This sets the StyleConstants.Alignment attribute for the currently selected range of the target JEditorPane. This is done by calling StyledDocument.setParagraphAttributes on the styled document associated with the target JEditorPane.

If the target text component is specified as the source of the ActionEvent and there is a command string the command string will be interpreted as an integer that should be one of the legal values for the StyleConstants.Alignment attribute.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class StyledEditorKit.BoldAction

An action to toggle the bold attribute.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class StyledEditorKit.FontFamilyAction

An action to set the font family in the associated JEditorPane. This will use the family specified as the command string on the ActionEvent if there is one otherwise the family that was initialized with will be used.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class StyledEditorKit.FontSizeAction

An action to set the font size in the associated JEditorPane. This will use the size specified as the command string on the ActionEvent if there is one otherwise the size that was initialized with will be used.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class StyledEditorKit.ForegroundAction

An action to set foreground color. This sets the StyleConstants.Foreground attribute for the currently selected range of the target JEditorPane. This is done by calling StyledDocument.setCharacterAttributes on the styled document associated with the target JEditorPane.

If the target text component is specified as the source of the ActionEvent and there is a command string the command string will be interpreted as the foreground color. It will be interpreted by called Color.decode and should therefore be legal input for that method.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class StyledEditorKit.ItalicAction

An action to toggle the italic attribute.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class StyledEditorKit.StyledTextAction

An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed. This has some convenience methods for causing character or paragraph level attribute changes. The convenience methods will throw an IllegalArgumentException if the assumption of a StyledDocument a JEditorPane or a StyledEditorKit fail to be true.

The component that gets acted upon by the action will be the source of the ActionEvent if the source can be narrowed to a JEditorPane type. If the source can't be narrowed the most recently focused text component is changed. If neither of these are the case the action cannot be performed.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class StyledEditorKit.UnderlineAction

An action to toggle the underline attribute.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder


Class StyledEditorKit, Object clone()

CreateCreates a copy of the editor kit. This allows an implementation to serve as a prototype for others so that they can be quickly created. @return the copy

Class TabExpander

Simple interface to allow for different types of implementations of tab expansion. @author Timothy Prinzing @version 1.12 0213 12/0203/0001

Class TabSet

A TabSet is comprised of many TabStops. It offers methods for locating the closest TabStop to a given position and finding all the potential TabStops. It is also immutable.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Scott Violet @version 1.10 0212 12/0203/0001


Class TabStop

This class encapsulates a single tab stop (basically as tab stops are thought of by RTF). A tab stop is at a specified distance from the left margin aligns text in a specified way and has a specified leader. TabStops are immutable and usually contained in TabSets.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @version 1.14 0217 12/0203/0001

Class TabStop, boolean equals(Object)

Returns true if other equals the receiverthe tabs are equal. @return true if the tabs are equal otherwise false
Class TabStop, int getAlignment()

Returns the alignment as an integer of the tab. @return the alignment of the tab.
Class TabStop, int getLeader()

Returns the leader of the tab. @return the leader of the tab.
Class TabStop, float getPosition()

Returns the position as a float of the tab. @return the postionposition of the tab.
Class TabStop, int ALIGN_DECIMAL

Characters following tab are aligned such that next decimal/tab/newline is at the tab location very similiarsimilar to RIGHT_TAB just includes decimal as additional character to look for.

Class TabableView

Interface for View's that have size dependantdependent upon tabs. @author Timothy Prinzing @author Scott Violet @version 1.6 028 12/0203/0001 @see TabExpander @see LabelView @see ParagraphView

Class TableView

Implements View interface for a table that is composed of an element structure where the child elements of the element this view is responsible for represent rows and the child elements of the row elements are cells. The cell elements can have an arbitrary element structure under them which will be built with the ViewFactory returned by the getViewFactory method.

   TABLE   ROW   CELL   CELL   ROW   CELL   CELL 

This is implemented as a hierarchy of boxes the table itself is a vertical box the rows are horizontal boxes and the cells are vertical boxes. The cells are allowed to span multiple columns and rows. By default the table can be thought of as being formed over a grid (i.e. somewhat like one would find in gridbag layout) where table cells can request to span more than one grid cell. The default horizontal span of table cells will be based upon this grid but can be changed by reimplementing the requested span of the cell (i.e. table cells can have independant spans if desired). @author Timothy Prinzing @version 1.28 0230 12/0203/0001 @see View


Class TableView.TableRow, View getViewAtPosition(int, Rectangle)

Fetches the child view that represents the given position in the model. This is implemented to walk through the children looking for a range that contains the given position. In this view the children do not necessarily have a one to one mapping with the child elements. @param pos the search position >= 0 @param a the allocation to the table 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
Class TableView.TableRow, void layoutMajorAxis(int, int, int[], int[])

Perform 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.

This is re-implemented to give each child the span of the column width for the table and to give cells that span multiple columns the multi-column span. @param targetSpan the total span given to the view which whould 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 is a return value and is filled in by the implementation of this method. @param spans the span of each child view. 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.

Class TableView.TableRow, void layoutMinorAxis(int, int, int[], int[])

Perform 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. This is called by the superclass whenever the layout needs to be updated along the minor axis.

This is implemented to delegate to the superclass then adjust the span for any cell that spans multiple rows. @param targetSpan the total span given to the view which whould 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 is a return value and is filled in by the implementation of this method. @param spans the span of each child view. 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.


Class TableView, View getViewAtPosition(int, Rectangle)

Fetches the child view that represents the given position in the model. This is implemented to walk through the children looking for a range that contains the given position. In this view the children do not necessarily have a one to one mapping with the child elements. @param pos the search position >= 0 @param a the allocation to the table 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
Class TableView, void layoutColumns(int, int[], int[], SizeRequirements[])

Layout the columns to fit within the given target span. @param targetSpan the given span for total of all the table columns. @param reqs the requirements desired for each column. This is the column maximum of the cells minimum preferred and maximum requested span. @param spans the return value of how much to allocated to each column. @param offsets the return value of the offset from the origin for each column. @returnsreturn the offset from the origin and the span for each column in the offsets and spans parameters.
Class TableView, void layoutMinorAxis(int, int, int[], int[])

Perform 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. This is called by the superclass whenever the layout needs to be updated along the minor axis.

This is implemented to call the layoutColumns method and then forward to the superclass to actually carry out the layout of the tables rows. @param targetSpan the total span given to the view which whould 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 is a return value and is filled in by the implementation of this method. @param spans the span of each child view. 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.


Class TextAction

An Action implementation useful for key bindings that are shared across a number of different text components. Because the action is shared it must have a way of getting it's target to act upon. This class provides support to try and find a text component to operate on. The preferred way of getting the component to act upon is through the ActionEvent that is received. If the Object returned by getSource can be narrowed to a text component it will be used. If the action event is null or can't be narrowed the last focused text component is tried. This is determined by being used in conjunction with a JTextController which arranges to share that information with a TextAction.

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 JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.21 0226 12/0203/0001


Class Utilities

A collection of methods to deal with various text related activities. @author Timothy Prinzing @version 1.31 0738 12/2603/0001
Class Utilities, int drawTabbedText(Segment, int, int, Graphics, TabExpander, int)

Draws the given text expanding any tabs that are contained using the given tab expansion technique. This particular implementation renders in a 1.1 style coordinate system where ints are used and 72dpi is assumed. @param s the source of the text @param x the X origin >= 0 @param y the Y origin >= 0 @param g the graphics context @param e how to expand the tabs. If this value is null tabs will be expanded as a space character. @param startOffset starting offset of the text in the document >= 0 @returnsreturn the X location at the end of the rendered text
Class Utilities, int getBreakLocation(Segment, FontMetrics, int, int, TabExpander, int)

Determine where to break the given text to fit within the the given span. This tries to find a whitespace boundary. @param s the source of the text @param metrics the font metrics to use for the calculation @param x0 the starting view location representing the start of the given text. @param x the target view location to translate to an offset into the text. @param e how to expand the tabs. If this value is null tabs will be expanded as a space character. @param startOffset starting offset in the document of the text @returnsreturn the offset into the given text.
Class Utilities, int getNextWord(JTextComponent, int)

Determines the start of the next word for the given location. Uses BreakIterator.getWordInstance() to actually get the words. @param c the editor @param offs the offset in the document >= 0 @returnsreturn the location in the model of the word start >= 0. @exception BadLocationException if the offset is out of range
Class Utilities, int getPreviousWord(JTextComponent, int)

Determine the start of the prev word for the given location. Uses BreakIterator.getWordInstance() to actually get the words. @param c the editor @param offs the offset in the document >= 0 @returnsreturn the location in the model of the word start >= 0. @exception BadLocationException if the offset is out of range
Class Utilities, int getTabbedTextOffset(Segment, FontMetrics, int, int, TabExpander, int)

Determines the relative offset into the given text that best represents the given span in the view coordinate system. This is implemented in a 1.1 style coordinate system where ints are used and 72dpi is assumed. @param s the source of the text @param metrics the font metrics to use for the calculation @param x0 the starting view location representing the start of the given text >= 0. @param x the target view location to translate to an offset into the text >= 0. @param e how to expand the tabs. If this value is null tabs will be expanded as a space character. @param startOffset starting offset of the text in the document >= 0 @returnsreturn the offset into the text >= 0
Class Utilities, int getTabbedTextWidth(Segment, FontMetrics, int, TabExpander, int)

Determines the width of the given segment of text taking tabs into consideration. This is implemented in a 1.1 style coordinate system where ints are used and 72dpi is assumed. @param s the source of the text @param metrics the font metrics to use for the calculation @param x the X origin >= 0 @param e how to expand the tabs. If this value is null tabs will be expanded as a space character. @param startOffset starting offset of the text in the document >= 0 @returnsreturn the width of the text
Class Utilities, int getWordEnd(JTextComponent, int)

Determines the end of a word for the given location. Uses BreakIterator.getWordInstance() to actually get the words. @param c the editor @param offs the offset in the document >= 0 @returnsreturn the location in the model of the word end >= 0. @exception BadLocationException if the offset is out of range
Class Utilities, int getWordStart(JTextComponent, int)

Determines the start of a word for the given model location. Uses BreakIterator.getWordInstance() to actually get the words. @param c the editor @param offs the offset in the document >= 0 @returnsreturn the location in the model of the word start >= 0. @exception BadLocationException if the offset is out of range

Class View

A very important part of the text package is the View class. As the name suggests it represents a view of the text model or a piece of the text model. It is this class that is responsible for the look of the text component. The view is not intended to be some completely new thing that one must learn but rather is much like a lightweight component. In fact the original View implementation was a lightweight component. There were several reasons why the Component implementation was abandoned in favor of an alternative.

  1. There was barely had time to get the lightweight component support in the 1.1 version of the JDK. There simply wasn't time to lighten up the component further to where it would need to be to be used for text purposes. The additions made to JComponent increased the memory consumption and as it currently stands it'sits much too heavy for representing text.

  2. The layout semantics aren't quite right for text and changing the current layout semantics of component might break existing applications.

  3. The component api uses integers but in 1.2 one can use floating point device independent coordinates. An api that works in both 1.1 and 1.2 would be convenient for minimizing transition difficulties. The View class uses the Shape interface and float arguments to enable View implementations for the Java 2 platform v1.2 and later while still functioning in the older 1.1 JDK.

By default a view is very light. It contains a reference to the parent view from which it can fetch many things without holding state and it contains a reference to a portion of the model (Element). A view does not have to exactly represent an element in the model that is simply a typical and therefore convenient mapping. A view can alternatively maintain a couple of Position objects to maintain it'sits location in the model (i.e. represent a fragment of an element). This is typically the result of formatting where views have been broken down into pieces. The convenience of a substantial relationship to the element makes it easier to build factories to produce the views and makes it easier to keep track of the view pieces as the model is changed and the view must be changed to reflect the model. Simple views therefore represent an Element directly and complex views do not.

A view has the following responsibilities:

Participate in layout.

The view has a setSize method which is like doLayout and setSize in Component combined. The view has a preferenceChanged method which is like invalidate in Component except that one can invalidate just one axis and the child requesting the change is identified.

A View expresses the size that it would like to be in terms of three values a minimum a preferred and a maximum span. Layout in a view is can be done independantlyindependently upon each axis. For a properly functioning View implementation the minimum span will be <= the preferred span which in turn will be <= the maximum span.

The minimum set of methods for layout are:

The setSize method should be prepared to be called a number of times (i.e. It may be called even if the size didn't change). The setSize method is generally called to make sure the View layout is complete prior to trying to perform an operation on it that requires an up-to-date layout. A viewsview's size should always be set to a value within the minimum and maximum span specified by that view. Additionally the view must always call the preferenceChanged method on the parent if it has changed the values for the layout it would like and expects the parent to honor. The parent View is not required to recognize a change until the preferenceChanged has been sent. This allows parent View implementations to cache the child requirements if desired. The calling sequence looks something like the following:

The exact calling sequence is up to the layout functionality of the parent view (if the view has any children). The view may collect the preferences of the children prior to determining what it will give each child or it might iteratively update the children one at a time.

Render a portion of the model.

This is done in the paint method which is pretty much like a component paint method. Views are expected to potentially populate a fairly large tree. A View has the following semantics for rendering:

  • The view gets it'sits allocation from the parent at paint time so it must be prepared to redo layout if the allocated area is different from what it is prepared to deal with.
  • The coordinate system is the same as the hosting Component (i.e. the Component returned by the getContainer method). This means a child view lives in the same coordinate system as the parent view unless the parent has explicitly changed the coordinate system. To schedule itself to be repainted a view can call repaint on the hosting Component.
  • The default is to not clip the children. It is more effecientefficient to allow a view to clip only if it really feels it needs clipping.
  • The Graphics object given is not initialized in any way. A view should set any settings needed.
  • A View is inherently transparent. While a view may render into it'sits entire allocation typically a view does not. Rendering is performed by tranversing down the tree of View implementations. Each View is responsible for rendering it'sits children. This behavior is depended upon for thread safety. While view implementations do not necessarily have to be implemented with thread safety in mind other view implementations that do make use of concurrency can depend upon a tree traversal to guarantee thread safety.
  • The order of views relative to the model is up to the implementation. Although child views will typically be arranged in the same order that they occur in the model they may be visually arranged in an entirely different order. View implementations may have Z-Order associated with them if the children are overlapping.

The methods for rendering are:

Translate between the model and view coordinate systems.

Because the view objects are produced from a factory and therefore cannot necessarily be counted upon to be in a particular pattern one must be able to perform translation to properly locate spatial representation of the model. The methods for doing this are:

The layout must be valid prior to attempting to make the translation. The translation is not valid and must not be attempted while changes are being broadcasted from the model via a DocumentEvent.

Respond to changes from the model.

If the overall view is represented by many pieces (which is the best situation if one want to be able to change the view and write the least amount of new code) it would be impractical to have a huge number of DocumentListenersDocumentListeners. If each view listened to the model only a few would actually be interested in the changes broadcasted at any given time. Since the model has no knowledge of views it has no way to filter the broadcast of change information. The view hierarchy itself is instead responsible for propagating the change information. At any level in the view hierarchy that view knows enough about it'sits children to best distribute the change information further. Changes are therefore broadcasted starting from the root of the view hierarchy. The methods for doing this are:

@author Timothy Prinzing @version 1.51 0263 12/0212/0001
Class View, constructor View(Element)

Creates a new View object. @param elem the elementElement to represent
Class View, void append(View)

Appends a single child view. This is a convenience call to replace. @param v the view @see #replace @since 1.3
Class View, View breakView(int, int, float, float)

Tries to break this view on the given axis. This is called by views that try to do formatting of their children. For example a view of a paragraph will typically try to place its children into row and views representing chunks of text can sometimes be broken down into smaller pieces.

This is implemented to return the view itself which represents the default behavior on not being breakable. If the view does support breaking the starting offset of the view returned should be the given offset and the end offset should be less than or equal to the end offset of the view being broken. @param axis may be either View.X_AXIS or View.Y_AXIS @param offset the location in the document model that a broken fragment would occupy >= 0. This would be the starting offset of the fragment returned. @param pos the position along the axis that the broken view would occupy >= 0. This may be useful for things like tab calculations. @param len specifies the distance along the axis where a potential break is desired >= 0. @return the fragment of the view that represents the given span if the view can be broken. If the view doesn't support breaking behavior the view itself is returned. @see ParagraphView

Class View, void changedUpdate(DocumentEvent, Shape, ViewFactory)

Gives notification from the document that attributes were changed in a location that this view is responsible for. To reduce the burden to subclasses this functionality is spread out into the following calls that subclasses can reimplement:
  1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements then this method should do whatever is necessary to make sure the child views correctly represent the model.
  2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
  3. updateLayout is called to give the view a chance to either repair it'sits layout to reschedule layout or do nothing.
@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 View#changedUpdate
Class View, View createFragment(int, int)

CreateCreates a view that represents a portion of the element. This is potentially useful during formatting operations for taking measurements of fragments of the view. If the view doesn't support fragmenting (the default) it should return itself. @param p0 the starting offset >= 0. This should be a value greater or equal to the element starting offset and less than the element ending offset. @param p1 the ending offset > p0. This should be a value less than or equal to the elements end offset and greater than the elements starting offset. @returnsreturn the view fragment or itself if the view doesn't support breaking into fragments. @see LabelView
Class View, void forwardUpdate(ElementChange, DocumentEvent, Shape, ViewFactory)

ForwardForwards the given DocumentEvent to the child views that need to be notified of the change to the model. If there were changes to the element this view is responsible for that should be considered when forwarding (i.e. new child views should not get notified). @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 @since 1.3
Class View, void forwardUpdateToView(View, DocumentEvent, Shape, ViewFactory)

ForwardForwards the DocumentEvent to the give child view. This simply messages the view with a call to insertUpdate removeUpdate or changedUpdate depending upon the type of the event. This is called by forwardUpdate to forward the event to children that need it. @param v the child view to forward the event to. @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 #forwardUpdate @since 1.3
Class View, float getAlignment(int)

Determines the desired alignment for this view along an axis. By default this is simply centered. @param axis may be either View.X_AXIS or View.Y_AXIS @returns The desired alignment is returned. This should be a value >= 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. @param axis may be either View.X_AXIS or View.Y_AXIS @return the value 0.5
Class View, AttributeSet getAttributes()

Fetches the attributes to use when rendering. By default this simply returns the attributes of the associated element. This method should be used rather than using the element directly to obtain access to the attributes to allow view-specific attributes to be mixed in or to allow the view to have view-specific conversion of attributes by subclasses. Each view should document what attributes it recognizes for the purpose of rendering or layout and should always access them through the AttributeSet returned by this method.
Class View, int getBreakWeight(int, float, float)

Determines how attractive a break opportunity in this view is. This can be used for determining which view is the most attractive to call breakView on in the process of formatting. A view that represents text that has whitespace in it might be more attractive than a view that has no whitespace for example. The higher the weight the more attractive the break. A value equal to or lower than BadBreakWeight should not be considered for a break. A value greater than or equal to ForcedBreakWeight should be broken.

This is implemented to provide the default behavior of returning BadBreakWeight unless the length is greater than the length of the view in which case the entire view represents the fragment. Unless a view has been written to support breaking behavior it is not attractive to try and break the view. An example of a view that does support breaking is LabelView. An example of a view that uses break weight is ParagraphView. @param axis may be either View.X_AXIS or View.Y_AXIS @param pos the potential location of the start of the broken view >= 0. This may be useful for calculating tab positions. @param len specifies the relative length from pos where a potential break is desired >= 0. @return the weight which should be a value between ForcedBreakWeight and BadBreakWeight. @see LabelView @see ParagraphView @see #BadBreakWeight @see #GoodBreakWeight @see #ExcellentBreakWeight @see #ForcedBreakWeight

Class View, Shape getChildAllocation(int, Shape)

Fetches the allocation for the given child view. This enables finding out where various views are located without assuming how the views store their location. This returns null since the default is to not have any child views. @param index the index of the child >= 0 && <getViewCount() @param a the allocation to this view. @return the allocation to the child
Class View, Container getContainer()

Fetches the container hosting the view. This is useful for things like scheduling a repaint finding out the host components font etc. The default implementation of this is to forward the query to the parent view. @return the container null if none
Class View, Document getDocument()

Fetches the model associated with the view. @return the view model null if none @see View#getDocument
Class View, int getEndOffset()

Fetches the portion of the model thatfor which this view is responsible for. @return the ending offset into the model >= 0 @see View#getEndOffset
Class View, Graphics getGraphics()

Fetch a Graphics for rendering. This can be used to determine font characteristics and will be different for a print view than a component view. @return a Graphics object for rendering @since 1.3
Class View, float getMaximumSpan(int)

Determines the maximum span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the maximum span the view can be rendered into. @see View#getPreferredSpan
Class View, float getMinimumSpan(int)

Determines the minimum span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the minimum span the view can be rendered into. @see View#getPreferredSpan
Class View, int getNextVisualPositionFrom(int, Bias, Shape, int, Bias[])

Provides a way to determine the next visually represented model location thatat which 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 in which 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 maywill be one of the following values: @return the location within the model that best represents the next location visual position. @exception BadLocationException @exception IllegalArgumentException forif direction andoesn't invalidhave directionone of the legal values above
Class View, View getParent()

Returns the parent of the view. @return the parent or null if none exists
Class View, float getPreferredSpan(int)

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. 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. @see View#getPreferredSpan
Class View, int getResizeWeight(int)

Determines the resizability of the view along the given axis. A value of 0 or less is not resizable. @param axis may be either View.X_AXIS or View.Y_AXIS @return the weight
Class View, int getStartOffset()

Fetches the portion of the model thatfor which this view is responsible for. @return the starting offset into the model >= 0 @see View#getStartOffset
Class View, View getView(int)

Gets the nthnth child view. Since there are no children by default this returns null. @param n the number of the view to get >= 0 && Class View, ViewFactory getViewFactory()

Fetches the ViewFactory implementation that is feeding the view hierarchy. Normally the views are given this as an argument to updates from the model when they are most likely to need the factory but this method serves to provide it at other times. @return the factory null if none
Class View, void insert(int, View)

Inserts a single child view. This is a convenience call to replace. @param offs the offset of the view to insert before >= 0 @param v the view @see #replace @since 1.3
Class View, void insertUpdate(DocumentEvent, Shape, ViewFactory)

Gives notification that something was inserted into the document in a location that this view is responsible for. To reduce the burden to subclasses this functionality is spread out into the following calls that subclasses can reimplement:
  1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements then this method should do whatever is necessary to make sure the child views correctly represent the model.
  2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
  3. updateLayout is called to give the view a chance to either repair it'sits layout to reschedule layout or do nothing.
@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 View#insertUpdate
Class View, boolean isVisible()

Returns a boolean that indicates whether the view is visible or not. By default all views are visible. @return booleanalways value.returns true
Class View, Shape modelToView(int, Bias, int, Bias, Shape)

Provides a mapping for a given region from the document model coordinate space to the view coordinate space. The specified region is created as a union of the view mappedfirst and tolast character itpositions. @param p0 the position toof the convertfirst character (>= 0) @param b0 the bias of the first character position toward the previous character or the next character represented by p0the offset in case the position is a boundary of two views; b0 will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
@param p1 the position toof the last convertcharacter (>= 0) @param b1 the bias towardfor the previoussecond character or the nextposition character represented by p1 in case the positiondefined one of the legal values shown above is@param a boundarythe area of twothe views.view @paramwhich aencompasses the allocatedrequested region to render into @return the bounding box which is a union of the given positionregion specified isby the first and returnedlast character positions @exception BadLocationException if the given position does not represent a valid location in the associated document @exception IllegalArgumentException forif anb0 invalidor biasb1 are not one of the legal Position.Bias values listed argumentabove @see View#viewToModel
Class View, Shape modelToView(int, Shape)

Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. This is implemented to default the bias to Position.Bias.Forward which was previously implied. @param pos the position to convert >= 0 @param a the allocated region in which 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 @see View#modelToView @deprecated
Class View, Shape modelToView(int, Shape, Bias)

Provides a mapping for a given character from the document model coordinate space to the coordinate space of the view mapped tocoordinate itspace. @param pos the position toof convertthe desired character (>= 0) @param a the allocatedarea of regionthe toview which renderencompasses intothe requested character @param b the bias toward the previous character or the next character represented by the offset in case the position is a boundary of two views; b will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
@return the bounding box in view coordinate space of the given positioncharacter at isthe specified returnedposition @exception BadLocationException if the givenspecified position does not represent a valid location in the associated document @exception IllegalArgumentException forif anb invalidis biasnot one of the legal Position.Bias values listed argumentabove @see View#viewToModel
Class View, void remove(int)

Removes one of the children at the given position. This is a convenience call to replace. @since 1.3
Class View, void removeAll()

Removes all of the children. This is a convenience call to replace. @since 1.3
Class View, void removeUpdate(DocumentEvent, Shape, ViewFactory)

Gives notification that something was removed from the document in a location that this view is responsible for. To reduce the burden to subclasses this functionality is spread out into the following calls that subclasses can reimplement:
  1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements then this method should do whatever is necessary to make sure the child views correctly represent the model.
  2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
  3. updateLayout is called to give the view a chance to either repair it'sits layout to reschedule layout or do nothing.
@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 View#removeUpdate
Class View, void replace(int, int, View[])

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 can be garbage collected. This is implemented to do nothing because by default a view has no children. @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 should be a value >= 0 and < (getViewCount() - offset). @param views the child views to add. This value can be null to indicate no children are being added (useful to remove). @since 1.3
Class View, void setParent(View)

Establishes the parent view for this view. This is guaranteed to be called before any other methods if the parent view is functioning properly. This is also the last method called since it is called to indicate the view has been removed from the hierarchy as well. When this method is called to set the parent to null this method does the same for each of its children propogating the notification that they have been disconnected from the view tree. If this is reimplemented super.setParent() should be called. @param parent the new parent or null if the view is being removed from a parent it was previously added to
Class View, void setSize(float, float)

Sets the size of the view. This should cause layout of the view along the given axis if it has any layout duties. The default is to do nothing. @param width the width >= 0 @param height the height >= 0
Class View, boolean updateChildren(ElementChange, DocumentEvent, ViewFactory)

Updates the child views in response to receiving notification that the model changed and there is change record for the element this view is responsible for. This is implemented to assume the child views are directly responsible for the child elements of the element this view represents. The ViewFactory is used to create child views for each element specified as added in the ElementChange starting at the index specified in the given ElementChange. The number of child views representing the removed elements specified are removed. @param ec Thethe change information for the element this view is responsible for. This should not be null if this method gets called. @param e the change information from the associated document @param f the factory to use to build child views @return whether or not the child views represent the child elements of the element this view is responsible for. Some views create children that represent a portion of the element they are responsible for and should return false. This information is used to determine if views in the range of the added elements should be forwarded to or not. @see #insertUpdate @see #removeUpdate @see #changedUpdate @since 1.3
Class View, void updateLayout(ElementChange, DocumentEvent, Shape)

UpdateUpdates the layout in response to receiving notification of change from the model. This is implemented to call preferenceChanged to reschedule a new layout if the ElementChange record is not null. @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 @since 1.3
Class View, int viewToModel(float, float, Shape)

Provides a mapping from the view coordinate space to the logical coordinate space of the model. @param x the X coordinate >= 0 @param y the Y coordinate >= 0 @param a the allocated region in which to render into @return the location within the model that best represents the given point in the view >= 0 @see View#viewToModel @deprecated
Class View, int viewToModel(float, float, Shape, Bias[])

Provides a mapping from the view coordinate space to the logical coordinate space of the model. The biasReturn argument will be filled in to indicate that the point given is closer to the next character in the model or the previous character in the model. @param x the X coordinate >= 0 @param y the Y coordinate >= 0 @param a the allocated region in which to render into @return the location within the model that best represents the given point in the view >= 0. The biasReturn argument will be filled in to indicate that the point given is closer to the next character in the model or the previous character in the model.
Class View, int ForcedBreakWeight

The weight to indicate a view supports breaking and must be broken to be represented properly when placed in a view that formats it'sits children by breaking them. @see #getBreakWeight @see #BadBreakWeight @see #GoodBreakWeight @see #ExcellentBreakWeight

Class ViewFactory

A factory to create a view of some portion of document subject. This is intended to enable customization of how views get mapped over a document model. @author Timothy Prinzing @version 1.15 0216 12/0203/0001

Class WrappedPlainView

View of plain text (text with only one font and color) that does line-wrapping. This view expects that its associated element has child elements that represent the lines it should be wrapping. It is implemented as a vertical box that contains logical line views. The logical line views are nested classes that render the logical line as multiple physical line if the logical line is too wide to fit within the allocation. The line views draw upon the outer class for its state to reduce their memory requirements.

The line views do all of their rendering through the drawLine method which in turn does all of its rendering through the drawSelectedText and drawUnselectedText methods. This enables subclasses to easily specialize the rendering without concern for the layout aspects. @author Timothy Prinzing @version 1.22 0228 12/0203/0001 @see View

Class WrappedPlainView, int drawSelectedText(Graphics, int, int, int, int)

Renders the given range in the model as selected text. This is implemented to render the text in the color specified in the hosting component. It assumes the highlighter will render the selected background. @param g the graphics context @param x the starting X coordinate >= 0 @param y the starting Y coordinate >= 0 @param p0 the beginning position in the model >= 0 @param p1 the ending position in the model >= p0 @returnsreturn the location of the end of the range. @exception BadLocationException if the range is invalid
Class WrappedPlainView, int drawUnselectedText(Graphics, int, int, int, int)

Renders the given range in the model as normal unselected text. @param g the graphics context @param x the starting X coordinate >= 0 @param y the starting Y coordinate >= 0 @param p0 the beginning position in the model >= 0 @param p1 the ending position in the model >= p0 @returnsreturn the X location of the end of the range >= 0 @exception BadLocationException if the range is invalid
Class WrappedPlainView, Segment getLineBuffer()

Gives access to a buffer that can be used to fetch text from the associated document. @returnsreturn the buffer
Class WrappedPlainView, float getMaximumSpan(int)

Determines the maximum span for this view along an axis. This is implemented to provide the superclass behavior after first making sure that the current font metrics are cached (for the nested lines which use the metrics to determine the height of the potentially wrapped lines). @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into. 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. @see View#getMaximumSpan
Class WrappedPlainView, float getMinimumSpan(int)

Determines the minimum span for this view along an axis. This is implemented to provide the superclass behavior after first making sure that the current font metrics are cached (for the nested lines which use the metrics to determine the height of the potentially wrapped lines). @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into. 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. @see View#getMinimumSpan
Class WrappedPlainView, float getPreferredSpan(int)

Determines the preferred span for this view along an axis. This is implemented to provide the superclass behavior after first making sure that the current font metrics are cached (for the nested lines which use the metrics to determine the height of the potentially wrapped lines). @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into. 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. @see View#getPreferredSpan
Class WrappedPlainView, void setSize(float, float)

Sets the size of the view. IfThis the size hasshould changedcause layout is redone.of The size isthe view along the full sizegiven of the view including the inset areasaxis if it has any layout duties. @param width the width >= 0 @param height the height >= 0

Class ZoneView

ZoneView is a View implementation that creates zones for which the child views are not created or stored until they are needed for display or model/view translations. This enables a substantial reduction in memory consumption for situations where the model being represented is very large by building view objects only for the region being actively viewed/edited. The size of the children can be estimated in some way or calculated asynchronously with only the result being saved.

ZoneView extends BoxView to provide a box that implements zones for it's children. The zones are special View implementations (the children of an instance of this class) that represent only a portion of the model that an instance of ZoneView is responsible for. The zones don't create child views until an attempt is made to display them. A box shaped view is well suited to this because:

  • Boxes are a heavily used view and having a box that provides this behavior gives substantial opportunity to plug the behavior into a view hierarchy from the view factory.
  • Boxes are tiled in one direction so it is easy to divide them into zones in a reliable way.
  • Boxes typically have a simple relationship to the model (i.e. they create child views that directly represent the child elements).
  • Boxes are easier to estimate the size of than some other shapes.

The default behavior is controled by two properties maxZoneSize and maxZonesLoaded. Setting maxZoneSize to Integer.MAX_VALUE would have the effect of causing only one zone to be created. This would effectively turn the view into an implementation of the decorator pattern. Setting maxZonesLoaded to a value of Integer.MAX_VALUE would cause zones to never be unloaded. For simplicity zones are created on boundaries represented by the child elements of the element the view is responsible for. The zones can be any View implementation but the default implementation is based upon AsyncBoxView which supports fairly large zones efficiently. @author Timothy Prinzing @version 1.6 0215 12/0203/0001 @see View @since 1.3

Class ZoneView, int getViewIndexAtPosition(int)

FetchesReturns the child view index representing the given position in the model. @param pos the position >= 0 @returnsreturn index of the view representing the given position or -1 if no view represents that position
Class ZoneView, void setMaxZonesLoaded(int)

SetSets the current setting of the number of zones allowed to be loaded at the same time. This will throw an IllegalArgumentException if mzl is less than 1. @param mzl the desired maximum number of zones to be actively loaded. must be greater than 0 @exception IllegalArgumentException if mzl is <1