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 acquired 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. As of 1.4 support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.130 12132 04/0317/0102

Class AbstractDocument, void replace(int, int, String, AttributeSet)

Deletes the region of text from offset to offset + length and replaces it with text. It is up to the implementation as to how this is implemented some implementations may treat this as two distinct operations: a remove followed by an insert others may treat the replace as one atomic operation. @param offset Locationindex inof child Documentelement @param length Lengthlength of text to delete may be 0 indicating don't delete anything @param text Texttext to insert null indicates no text to insert @param attrs AttributeSet indicating attributes of inserted text null is legal and typically treated as an empty attributeset but exact interpretation is left to the subclass @exception BadLocationException the given position is not a valid position within the document @since 1.4
Class AbstractDocument, void setAsynchronousLoadPriority(int)

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

Class BoxView

A view that arranges its children into a box shape by tiling its 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 a 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.56 1257 04/0318/0102


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.48 1249 04/0318/0102


Class CompositeView

CompositeView is an abstract View implementation which manages one or more child views. (Note that CompositeView is intended for managing relatively small numbers of child views.) CompositeView is intended to be used as a starting point for View implementations such as BoxView that will contain child Views. Subclasses that wish to manage the collection of child Views should use the #replace method. As View invokes replace during DocumentListener notification you normally won't need to directly invoke replace.

While CompositeView does not impose a layout policy on its child Views it does allow for inseting the child Views it will contain. The insets can be set by either #setInsets or #setParagraphInsets

In addition to the abstract methods of javax.swing.text.View subclasses of CompositeView will need to override:

@author Timothy Prinzing @version 1.63 1264 01/1231/0102

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. As of 1.4 support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @author Timothy Prinzing @version 1.116118 12/03/0104/02 @see Caret


Class DefaultFormatter

DefaultFormatter formats aribtrary objects. Formatting is done by invoking the toString method. In order to convert the value back to a String your class must provide a constructor that takes a String argument. If no single argument constructor that takes a String is found the returned value will be the String passed into stringToValue.

Instances of DefaultFormatter can not be used in multiple instances of JFormattedTextField. To obtain a copy of an already configured DefaultFormatter use the clone 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. As of 1.4 support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @see javax.swing.JFormattedTextField.AbstractTextFormatterAbstractFormatter @version 1.67 12/03/0120/02 @since 1.4


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.28 1229 01/1207/0102 @see View

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. As of 1.4 support for long term storage 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.192 12196 05/0315/0102 @see Document @see DocumentEvent @see DocumentListener @see Caret @see CaretEvent @see CaretListener @see TextUI @see View @see ViewFactory


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.82 1286 02/0313/0102 @see View
Class ParagraphView, void setLineSpacing(float)

Sets the line spacing. @param ls the value inis pointsa factor of the line hight

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. As of 1.4 support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @version 1.37 1238 02/0307/0102 @author Tim Prinzing


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.29 1231 02/0311/0102


Class StyleConstants.ParagraphConstants, Object LineSpacing

The amount of space between lines of the paragraph. Type is float and specifies the size inas points.a factor of the line height

Class StyleConstants, Object LineSpacing

The amount of space between lines of the paragraph. Type is float and specifies the size inas points.a factor of the line height

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. As of 1.4 support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder @version 1.17 1218 02/0307/0102