javax.swing.text Documentation Differences

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

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

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

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

This class implements a locking mechanism for the document. It allows multiple readers or one writer and writers must wait until all observers of the document have been notified of a previous change before beginning another mutation to the document. The read lock is aquired 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 release of Swing will provide support for long term persistence. @author Timothy Prinzing @version 1.100 11112 02/1902/9800

Does a read unlock. This signals that one of the readers is done. If there are no more readers then writing can begin again. This should be balanced with a readLock and should occur in a finally statement so that the balance is guaranteed. The following is an example.

 try {  readLock();   try {   // do something   } finally {   readUnlock();   } 

@see #readLock

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.10 0414 02/2202/9900

Increments the indent level. If indenting would cause getIndentSpace() *getIndentLevel() to be > than getLineLength() this will not cause an indent.

Does indentation. The number of spaces written out is indent level times the space to map mapping. If the current line is empty this will not make it so that the current line is still considered empty. @exception IOException on any I/O error

Writes out a character. IfThis the character is a newline then it resetsimplemented the current length to 0. If the currentinvoke length equals the maximumwrite line length thenmethod that takes a newline is outputed and the current length is reset to 0char[]. @param a char. @exception IOException on any I/O error

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.26 0833 02/2602/9800 @see MutableAttributeSet @see AttributeCharacterIterator

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 JDKplatform and can be ammended by additional user added entries that correspond to logical settings that are specific to some type of content.

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. A future release of Swing will provide support for long term persistence. @author Timothy Prinzing @version 1.14 0816 02/2802/9800

A view that arranges its children into a box shape by tiling it's 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 useful building block that might be useful to represent things like a collection of lines paragraphs lists columns pages etc. @author Timothy Prinzing @version 1.34 0544 02/1702/00

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 offsetindex the starting offsetindex 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 replaceremove. This should be a value >= 0 and < (getViewCount() - offset). @param elemsviews the child views to insertadd. This value can be null to indicate no children are being added (useful to remove).

A place within a document view that represents where things can be inserted into the document model. ItA caret giveshas a wayposition in the document referred to navigateas a dot. The dot throughis where the document view while abstracting awaycaret is currently located in the detailsmodel. There ofis a second howposition maintained by the viewcaret that represents the other end of a selection called mark. If there is arrangedno selection the dot and mark will be equal. If a selection exists the two values will be different. This

The dot can be useful because some viewsplaced by either calling maysetDot filteror outmoveDot. portionsSetting ofthe dot has the associated model and someeffect of removing any viewsselection that may not allowhave previously navigationexisted. inThe dot certainand mark will be equal. Moving the dot has the effect of creating areas sucha selection as read-onlythe mark is left areasat whatever position it previously had. @author Timothy Prinzing @version 1.23 0826 02/2602/9800

Gets the current caret positionvisual location. @return the visual position. @see #setMagicCaretPosition

Moves the caret position (dot) to some other position leaving behind the mark. This is useful for making selections. @param dot the new position to move the caret to >= 0

SavesSet the current caret positionvisual location. This iscan be used when moving between lines that have uneven end positions (such as when caret up or down actions occur). moving between linesIf text flows thatleft-to-right haveor unevenright-to-left endthe positionsx-coordinate will indicate the desired navigation location for vertical movement. If the text flow is top-to-bottom the y-coordinate will indicate the desired navigation location for horizontal movement. @param p the Point to use for the saved position. This can be null to indicate there is no visual location.

ChangedCharSetException as the name indicates is an exception thrown when the charset is changed. @author Sunita Mani 1.3 085 02/2602/9800

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). @author Timothy Prinzing @version 1.35 0440 02/2202/9900

Paints a component view. The real paint behavior occurs naturally from the association that the component has with its parent container (the same container hosting this view) so this simply allows us to position the component properly relative to the view. Since the coordinate system for the viewThis is simplyimplemented the parent containers positioning the child componentto is easydo nothing. @param g the graphics context @param a the shape @see View#paint

Sets the size of the view. This is implemented to setdo the size of the component to match the size of the view. nothing Thesince changing of the component sizeitself will touch the component lock which is the one thing that is not safe from the View hierarchy. Therefore thisget functionalityits is executed immediatelysize if onestablished by the event thread or isLayoutManager queuedinstalled on the event queue if called from another thread (notification of change from an asynchronoushosting update)Container. @param width the width >= 0 @param height the height >= 0

A view that is composed of other views (has children). As a container of children the composite view needs to provide:

services to manage the collection of children

The following methods can be used to manage the collection.

• removeAll
• insert
• append
• replace
• getViewCount
• getView
• loadChildren

layout of the children

This class does not implement a layout policy as it is abstract. A subclass will determine how the children are laid out by implementing the setSize method to position the children when the size has been changed.

paint the children

This class does not attempt to paint the children. Subclasses will want to use the layout information and call paint on the children that are visible (intersect the clipping region) with the Shape argument set to the location of the child view.

propagation of DocumentEvent information to the appropriate children.

propagation of model/view translation to the proper child.

@author Timothy Prinzing @version 1.45 0454 02/2202/9900

Appends a single child view. This is a convenience call to replace. @param v the view @see #replace @since 1.3

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

Removes all of the children. This is a convenience call to replace. @since 1.3

Replace 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. @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).

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 future release of Swing will provide support for long term persistence. @author Timothy Prinzing @version 1.79 0490 02/2202/9900 @see Caret

If button 1 is pressed this is implemented to request focus on the associated text component and to set the caret position. If the shift key is held down the caret will be moved potentially resulting in a selection otherwise the caret position will be set to the new location. If the component is not enabled there will be no request for focus. @param e the mouse event @see MouseListener#mousePressed

Saves the current caret position. This is used when caret up/down actions occur moving between lines that have uneven end positions. @param p the position @see #getMagicCaretPosition @see UpAction @see DownAction

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. @author Timothy Prinzing @version 1.41 0350 02/0802/00

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. A future release of Swing will provide support for long term persistence. @see DefaultEditorKit#defaultKeyTypedAction @see DefaultEditorKit#getActions @see Keymap#setDefaultAction @see Keymap#getDefaultAction

Creates a copy of the editor kit. This allows anis implemented implementation to serve as ause prototypeObject.clone. for others so that they can be quickly createdIf the kit cannot be cloned null is returned. @return the copy

Name of the Action for moving the caret logically backward one position. @see BackwardAction @see #getActions

Name of the action to create a beep. @see BeepAction @see #getActions

Name of the Action for moving the caret to the begining of the document. @see BeginAction @see #getActions

Name of the Action for moving the caret to the begining of a line. @see BeginAction @see #getActions

Name of the Action for moving the caret to the begining of a paragraph. @see BeginAction @see #getActions

Name of the Action for moving the caret to the begining of a word. @see BeginAction @see #getActions

Name of the action that is executed by default if a key typed event is received and there is no keymap entry. @see DefaultKeyTypedAction @see #getActions

Name of the action to delete the character of content that follows the current caret position. @see DeleteNextCharAction @see #getActions

Name of the action to delete the character of content that precedes the current caret position. @see DeletePrevCharAction @see #getActions

Name of the Action for moving the caret logically downward one position. @see DownAction @see #getActions

Name of the Action for moving the caret to the end of the document. @see EndAction @see #getActions

Name of the Action for moving the caret to the end of a line. @see EndAction @see #getActions

Name of the Action for moving the caret to the end of a paragraph. @see EndAction @see #getActions

Name of the Action for moving the caret to the end of a word. @see EndAction @see #getActions

Name of the Action for moving the caret logically forward one position. @see ForwardAction @see #getActions

Name of the action to place a line/paragraph break into the document. If there is a selection it is removed before the break is added. @see InsertBreakAction @see #getActions

Name of the action to place content into the associated document. If there is a selection it is removed before the new content is added. @see InsertContentAction @see #getActions

Name of the action to place a tab character into the document. If there is a selection it is removed before the tab is added. @see InsertTabAction @see #getActions

Name of the Action for moving the caret to the begining of the next word. to the next of the document. @see NextWordAction @see #getActions

Name of the action to page down vertically. @see PageDownAction @see #getActions

Name of the action to page up vertically. @see PageUpAction @see #getActions

Name of the Action for moving the caret to the begining of the previous word. @see PreviousWordAction @see #getActions

Name of the action to set the editor into read-only mode. @see ReadOnlyAction @see #getActions

Name of the Action for selecting the entire document @see SelectAllAction @see #getActions

Name of the Action for selecting a line around the caret. @see SelectLineAction @see #getActions

Name of the Action for selecting a paragraph around the caret. @see SelectParagraphAction @see #getActions

Name of the Action for selecting a word around the caret. @see SelectWordAction @see #getActions

Name of the Action for extending the selection by moving the caret logically backward one position. @see SelectionBackwardAction @see #getActions

Name of the Action for moving the caret to the begining of the document. @see BeginAction @see #getActions

Name of the Action for moving the caret to the begining of a line extending the selection. @see BeginLineAction @see #getActions

Name of the Action for moving the caret to the begining of a paragraph extending the selection. @see BeginParagraphAction @see #getActions

Name of the Action for moving the caret to the begining of a word extending the selection. @see BeginWordAction @see #getActions

Name of the Action for moving the caret logically downward one position extending the selection. @see DownAction @see #getActions

Name of the Action for moving the caret to the end of the document. @see EndAction @see #getActions

Name of the Action for moving the caret to the end of a line extending the selection. @see EndLineAction @see #getActions

Name of the Action for moving the caret to the end of a paragraph extending the selection. @see EndParagraphAction @see #getActions

Name of the Action for moving the caret to the end of a word extending the selection. @see EndWordAction @see #getActions

Name of the Action for extending the selection by moving the caret logically forward one position. @see SelectionForwardAction @see #getActions

Name of the Action for moving the selection to the begining of the next word extending the selection. @see NextWordAction @see #getActions

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

Name of the Action for moving the caret logically upward one position extending the selection. @see UpAction @see #getActions

Name of the Action for moving the caret logically upward one position. @see UpAction @see #getActions

Name of the action to set the editor into writeable mode. @see WritableAction @see #getActions

Implements the Highlighter interfaces. Implements a simple highlight painter that renders in a solid color. @author Timothy Prinzing @version 1.28 0831 02/2602/9800 @see Highlighter

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 boundriesboundaries since logical styles are assigned to paragraph boundriesboundaries.

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 release of Swing will provide support for long term persistence. @author Timothy Prinzing @version 1.100 04111 02/2202/9900 @see Document @see AbstractDocument

Gets athe paragraph element at the offset pos. TheA paragraph elementconsists is the parent ofof at least one thechild Element deepestwhich is usually a leaf. @param pos the starting offset >= 0 @return the element

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 (plain text textfield) to complex needs (HTML or XML documents 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.

• getLength
• getText(int int)
• getText(int int Segment)

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.

• getDefaultRootElement
• getRootElements

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:

• insertString
• remove
• createPosition

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 seperate 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 UndoableEditListeners. 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:

• addDocumentListener
• removeDocumentListener
• addUndoableEditListener
• removeUndoableEditListener

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 TitleProperty which can be used to name the Document. The methods related to the properties are:

• getProperty
• putProperty

@author Timothy Prinzing @version 1.30 1032 02/2502/9800 @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

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.14 0416 02/2202/9900

Creates a copy of the editor kit. This allowsis an implementationimplemented to serve as a prototype for others so that they can be quicklyuse createdObject. In a futureclone. release this method willIf the kit cannot be implementedcloned to use Objectnull is returned.clone @return the copy

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.14 0817 02/2602/9800

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.

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 >= 0 @see AbstractDocument

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.6 089 02/2602/9800

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.15 1018 02/2902/9800 @see View

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 boundryboundary 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 boundriesboundaries 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.11 1115 02/1902/9800

Adjust the gap end upward. This doesn't move any data but it does update any marks affected by the boundryboundary change. All marks from the old gap end up to the new gap end are squeezed to the end of the gap (their location has been removed).

Adjust the gap end downward. This doesn't move any data but it does update any marks affected by the boundryboundary change. All marks from the old gap start down to the new gap start are squeezed to the end of the gap (their location has been removed).

An interface for an object that allows one to mark up the background with colored areas. @author Timothy Prinzing @version 1.17 0819 02/2602/9800

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.22 0423 02/2202/9900

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:

Stage	KeyEvent	InputMethodEvent
1.	input methods	(generated here)
2.	focus manager
3.	registered key listeners	registered 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.

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 release of Swing will provide support for long term persistence. @beaninfo attribute: isContainer false @author Timothy Prinzing @version 1.130 04154 01/2621/9901 @see Document @see DocumentEvent @see DocumentListener @see Caret @see CaretEvent @see CaretListener @see TextUI @see View @see ViewFactory /

AccessibilityThis implementationclass 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. A future release of Swing will provide support for long term persistence.

Handles document remove (fire appropriate property change event which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). This tracks the dotchanged offset via the event. @param e the DocumentEvent

GetsGet the AccessibleText interface associated with this object. @returnIn an instancethe implementation of the Java Accessibility API for this class return this object which is responsible for implementing the AccessibleText interface on behalf of itself. @return this object

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

Handles document insert (fire appropriate property change event which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). This tracks the dotchanged offset via the event. @param e the DocumentEvent

Handles document remove (fire appropriate property change event which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). This tracks the dotchanged offset via the event. @param e the DocumentEvent

Gets the AccessibleContext associated with this JComponentJTextComponent. For text components the AccessibleContext takes the form of an AccessibleJTextComponent. A new contextAccessibleJTextComponent instance is created if necessary. @return an AccessibleJTextComponent that serves as the AccessibleContext of this JComponentJTextComponent

Returns true if this component is completely opaque. This

isAn opaque component paints every pixel within its rectangular bounds. A non-opaque component paints only a subset of its pixels or none at all allowing the pixels underneath it to "show through". used inTherefore a paintingcomponent that does not fully paint its pixels provides a degree of transparency.

Subclasses that guarantee to backgroundsalways completely paint their contents should override this method and return true. @return true if this component is completely opaque. @see #setOpaque

Converts the given location in the model to a place in the view coordinate system. The component must have a positive size for this translation to be computed (i.e. layout cannot be computed until the component has been sized). The component does not have to be visible or painted. @param pos the position >= 0 @return the coordinates as a rectangle with (r.x r.y) as the location in the coordinate system or null if the component does not yet have a positive size. @exception BadLocationException if the given position does not represent a valid location in the associated document @see TextUI#modelToView

Processes any key events that the component itself recognizes. This will beis called after the focus manager and any interested listeners have been given a chance to steal away the event. This method will only beis called isonly if the event has not yet been consumed. This method is called prior to the keyboard UI logic.

This method is implemented to take a defaultdo action typically inserting the character into the document as contentnothing. Subclasses would normally override this method if they process some key events themselves. If the event is processed it should be consumed. @param e the event

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

EnablesSets whether or disablesnot this component depending on the valueis ofenabled. the parameterA component b.that Anis enabled component canmay respond to user input and generatewhile a events.component Componentsthat areis not enabled initiallycannot respond to by defaultuser input. ASome repaint()components is done after setting the newmay alter their visual representation when state.they @paramare b Ifdisabled in trueorder this component isto provide feedback enabled;to otherwise this component isthe user that they disabledcannot take input. @see java.awt.Component#isEnabled @sincebeaninfo preferred: true JDK1bound: true attribute: visualUpdate true description: The enabled state of the component.1

Sets whetherIf true orthe component paints every pixel within its bounds. Otherwise the component may not paint some or all of its pixels allowing the underlying pixels to show through.

The default value of this property is false for JComponent. However the UIdefault value for should render athis property on backgroundmost standard JComponent subclasses (such as JButton and JTree) is look-and-feel dependent. @paramsee #isOpaque @beaninfo obound: true ifexpert: true shoulddescription: renderThe acomponent's backgroundopacity

Converts the given place in the view coordinate system to the nearest representative location in the model. The component must have a positive size for this translation to be computed (i.e. layout cannot be computed until the component has been sized). The component does not have to be visible or painted. @param pt the location in the view to translate @return the offset >= 0 from the start of the document or -1 if the component does not yet have a positive size. @see TextUI#viewToModel

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.12 0814 02/2602/9800

A LabelView is a styled chunk of text that represents a view mapped over an element in the text model. TheIt view supports breaking for the purpose of formatting. The fragments produced by breaking sharecaches 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. This view is generally responsible for displaying character level attributes in some way. 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 isused an example of a container that does tabfor expansionrendering. @author Timothy Prinzing @author Brian Beck @version 1.14 0456 02/2202/9900

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. The higher the weight the more attractive the break. A value equal to or lower than View.BadBreakWeight should not be considered for a break. A value greater than or equal to View.ForcedBreakWeight should be broken.

This is implemented to forward to the superclass for the Y_AXIS. Along the X_AXIS the following values may be returned.

View.ExcellentBreakWeight

if there is whitespace proceeding the desired break location.

View.BadBreakWeight

if the desired break location results in a break location of the starting offset.

View.GoodBreakWeight

if the other conditions don't occur.

This will normally result in the behavior of breaking on a whitespace location if one can be found otherwise breaking between characters. @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 View.ForcedBreakWeight and View.BadBreakWeight. @see LabelView @see ParagraphView @see View#BadBreakWeight @see View#GoodBreakWeight @see View#ExcellentBreakWeight @see View#ForcedBreakWeight

Fetch the Font usedfont that forthe glyphs should be based upon. This is implemented to return a this viewcached font.

Fetch the FontMetrics used for this view. @deprecated FontMetrics are not used for glyph rendering when running in the Java2 SDK.

Gives notification that something was added toinserted into the document in a location that this view is responsible for. This is implemented to call preferenceChanged along the axis the glyphs are rendered. @param changese 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

Gives notification that something was removed from the document in a location that this view is responsible for. This is implemented to call preferenceChanged along the axis the glyphs are rendered. @param changese 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

@author Scott Violet @author Timothy Prinzing @version 1.2 084 02/2602/9800 @see Highlighter

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.10 0812 02/2602/9800

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.66 0476 02/2202/9900 @see View

Fetches the child view that represents the given position in the model. This is implemented to walkfetch through the children looking for a range that contains the given position. In this view in the children do not havecase where there is a one to one mapping with the child elements (i.e. the children are actually rows that represent aview portion of thefor each child element this view represents). @param pos the search 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 @returns the view representing the given position or null if there isn't one

Lays out the children. If the layout span along the flow axis has changed layout is marked as invalid which which will cause the rowssuperclass behavior to recalculate the layout along arethe box rebuiltaxis. TheIf the superclassFlowStrategy reports that a functionalitylayout is calledneeded the FlowStrategy.layout method after checking and possibly rebuildingwill be called to rebuild the flow rows as appropriate. If the height hasof changedthis view changes (determined by the preferenceChangedperferred methodsize along the box axis) a preferenceChanged is calledmessaged. on the parent sinceFollowing all of that the verticalnormal box layout of the preferencesuperclass is rigidperformed. @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 (not used by paragraph but used by the superclass). This is the height inside of the inset area.

Loads all of the children to initialize the view. This is called by the setParent method. This is reimplemented to not load any children directly (as they are created in the process of formatting). This does create views to represent the child elements but theyIf the layoutPool variable is null an instance of LogicalView is arecreated to placed into a poolrepresent the logical view that is used in the process of formatting. @param f the view factory

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.9 1013 02/2902/9800 @see View

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 release of Swing will provide support for long term persistence. @author Timothy Prinzing @version 1.31 0934 02/2002/9800 @see Document @see AbstractDocument

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.58 0463 02/2202/9900 @see View

SignalsChild thatviews can call this on the desiredparent to spanindicate that the preference has changed and should be reconsidered for layout. By default this just propagates upward to the next parent. The root view will call revalidate on the associated text component. @param child the child view @param width true if the width preference has changed @param height true if the height preference has changed @see javax.swing.JComponent#revalidate

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.12 0815 02/2602/9800

A typesafe enumeration to indicate bias to a position in the model. A position indicates a location between two characters. The bias can be used to indicate an interest toward one of the two sides of the position in boundryboundary conditions where a simple offset is ambiguous.

A segment of a character array representing a fragment of text. It should be treated as immutable even though the array is directly accessable. 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.16 02/02/00

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that for any object x the expression: x.clone() = x will be true and that the expression: x.clone().getClass() == x.getClass() will be true but these are not absolute requirements. While it is typically the case that: x.clone().equals(x) will be true this is not an absolute requirement. Copying an object will typically entail creating a new instance of its class but it also may require copying of internal data structures as well. No constructors are called. The method clone for class Object performs a specific cloning operation. First if the class of this object does not implement the interface Cloneable then a CloneNotSupportedException is thrown. Note that all arrays are considered to implement the interface Cloneable. Otherwise this method creates a new instance of the class of this object and initializes all its fields with exactly the contents of the corresponding fields of this object as if by assignment; the contents of the fields are not themselves cloned. Thus this method performs a "shallow copy" of this object not a "deep copy" operation. The class Object does not itself implement the interface Cloneable so calling the clone method on an object whose class is Object will result in throwing an exception at run time. The clone method is implemented by the class Object as a convenient general utility for subclasses that implement the interface Cloneable possibly also overriding the clone method in which case the overriding definition can refer to this utility definition by the call: super.clone() @return a clone of this instance. @exception CloneNotSupportedException if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned. @exception OutOfMemoryError if there is not enough memory. @see java.lang.Cloneablecopy

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 release of Swing will provide support for long term persistence. @version 1.28 1132 02/0602/9800 @author Tim Prinzing

Compares this object to the specifed object. The result is true if and only if the argument is not null and is a Font object with the same name style andis point size as this fontan equivalent set of attributes. @param obj the object to compare this font with. @return true if the objects are equal; false otherwise.

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. A future release of Swing will provide support for long term persistence. @author Timothy Prinzing @version 1.35 0837 02/2802/9800

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 seperated out to facilitate alternative implementations that are more efficient. @author Timothy Prinzing @version 1.14 0816 02/2602/9800

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.23 0927 02/1802/9800

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 release of Swing will provide support for long term persistence. @author Timothy Prinzing @version 1.57 1165 02/1702/9800

Adds a change listener. @param l the change listener @see Attributes#addChangeListener

Removes a change listener. @param l the change listener @see Attributes#removeChangeListener

Compares this object to the specifed object. The result is true if and only if the argument is not null and is a Font object with the same name style andis point size as this fontan equivalent set of attributes. @param obj the object to compare this font with. @return true if the objects are equal; false otherwise.

Interface for a generic styled document. @author Timothy Prinzing @version 1.16 0818 02/2602/9800

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.31 0433 02/2202/9900

Simple interface to allow for different types of implementations of tab expansion. @author Timothy Prinzing @version 1.10 0812 02/2602/9800

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 release of Swing will provide support for long term persistence. @author Scott Violet @version 1.8 0810 02/2802/9800

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 release of Swing will provide support for long term persistence. @version 1.13 0414 02/2202/9900

Interface for View's that have size dependant upon tabs. @author Timothy Prinzing @author Scott Violet @version 1.4 086 02/2602/9800 @see TabExpander @see LabelView @see ParagraphView

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.24 0528 02/0302/9900 @see View

@deprecated Table cells can now be any arbitrary View implementation and should be produced by the ViewFactory rather than the table. This method will be deprecated in a future release. @param elem an element @return the cell

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. A future release of Swing will provide support for long term persistence. @author Timothy Prinzing @version 1.19 0821 02/2802/9800

A collection of methods to deal with various text related activities. @author Timothy Prinzing @version 1.21 0930 02/0402/9800

Determine where to break the given text to fit within the the given span. This trystries to find a whitespace boundryboundary. @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 @returns the offset into the given text.

Determines the position in the model that is closest to the given view location in the row above. The component given must have a size to compute the result. If the component doesn't have a size a value of -1 will be returned. @param c the editor @param offs the offset in the document >= 0 @param x the X coordinate >= 0 @return the model position >= 0 if the request can be computed otherwise a value of -1 will be returned. @exception BadLocationException if the offset is out of range

Determines the position in the model that is closest to the given view location in the row below. The component given must have a size to compute the result. If the component doesn't have a size a value of -1 will be returned. @param c the editor @param offs the offset in the document >= 0 @param x the X coordinate >= 0 @return the model position >= 0 if the request can be computed otherwise a value of -1 will be returned. @exception BadLocationException if the offset is out of range

Determines the ending row model position of the row that contains the specified model position. AssumesThe component given must have a size to compute the row(s)result. are currently displayedIf the component indoesn't have a size a viewvalue of -1 will be returned. @param c the editor @param offs the offset in the document >= 0 @return the position >= 0 if the request can be computed otherwise a value of -1 will be returned. @exception BadLocationException if the offset is out of range

Determines the starting row model position of the row that contains the specified model position. AssumesThe component given must have a size to compute the row(s)result. are currently displayedIf the component indoesn't have a size a viewvalue of -1 will be returned. @param c the editor @param offs the offset in the document >= 0 @return the position >= 0 if the request can be computed otherwise a value of -1 will be returned. @exception BadLocationException if the offset is out of range

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's 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 in JDKfor the 1Java 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's 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 independantly 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:

• getMinimumSpan
• getPreferredSpan
• getMaximumSpan
• getAlignment
• preferenceChanged
• setSize

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 views 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's 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 effecient 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's 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's 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:

• paint

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:

• modelToView
• viewToModel
• getDocument
• getElement
• getStartOffset
• getEndOffset

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 DocumentListeners. 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's 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:

• insertUpdate
• removeUpdate
• changedUpdate

@author Timothy Prinzing @version 1.35 0451 02/2202/9900

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's 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

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

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's 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

Gives notification that something was removed from the document in a location that attributes were removed inthis view is responsible afor. locationTo 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's 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

The weight to indicate a view is a bad break opportunity for the purpose of formatting. This value indicates that no attempt should be made to break the view into fragments as the view has not been written to support fragmenting. @see #getBreakWeight @see #GoodBreakWeight @see #ExcellentBreakWeight @see #ForcedBreakWeight

The weight to indicate a view supports breaking and this represents a very attractive place to break. @see #getBreakWeight @see #BadBreakWeight @see #GoodBreakWeight @see ExcellentBreakWeight @see #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's children by breaking them. @see #getBreakWeight @see #BadBreakWeight @see #GoodBreakWeight @see #ExcellentBreakWeight @see ForcedBreakWeight

The weight to indicate a view supports breaking but better opportunities probably exist. @see #getBreakWeight @see #BadBreakWeight @see GoodBreakWeight @see #ExcellentBreakWeight @see #ForcedBreakWeight

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.13 0815 02/2602/9800

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.19 1122 02/1702/9800 @see View

Creates a new WrappedPlainView. Lines will be wrapped on character boundriesboundaries. @param elem the element underlying the view

Creates a new WrappedPlainView. Lines can be wrapped on either character or word boundriesboundaries depending upon the setting of the wordWrap parameter. @param elem the element underlying the view @param wordWrap should lines be wrapped on word boundriesboundaries

This is called by the nested wrapped line views to determine the break location. This can be reimplemented to alter the breaking behavior. It will either break at word or character boundriesboundaries depending upon the break argument given at construction.