|
Generated by JDiff |
||||||||
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES |
This file contains all the changes in documentation in the packagejavax.swing.text
as colored differences. Deletions are shownlike 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.Class AbstractDocument, void replace(int, int, String, AttributeSet)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
andrevalidate
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 DefaultStyledDocumentgetParagraphElement(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
Deletes the region of text fromClass AbstractDocument, void setAsynchronousLoadPriority(int)offset
tooffset + length
and replaces it withtext
. 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 offsetLocationindexinof childDocumentelement @param lengthLengthlength of text to delete may be 0 indicating don't delete anything @param textTexttext to insertnull
indicates no text to insert @param attrs AttributeSet indicating attributes of inserted textnull
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
Sets the asynchronous loading priority. @param p the newaynchronousasynchronous loading priority; a value less than zero indicates that the document should be loaded asynchronously
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
andlayoutMinorAxis
. 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 iflayoutChanged
is called to force an updated layout. ThelayoutChanged
method invalidates cached layout information if there is any. The requirements published to the parent view are calculated by the methodscalculateMajorAxisRequirements
andcalculateMinorAxisRequirements
. If the layout algorithm is changed these methods will likely need to be reimplemented. @author Timothy Prinzing @version 1.56 1257 04/0318/0102
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 methodJComponent.setAlignmentY
. For example setting a value of0.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
CompositeView
is an abstractView
implementation which manages one or more child views. (Note thatCompositeView
is intended for managing relatively small numbers of child views.)CompositeView
is intended to be used as a starting point forView
implementations such asBoxView
that will contain childView
s. Subclasses that wish to manage the collection of childView
s should use the #replace method. AsView
invokesreplace
duringDocumentListener
notification you normally won't need to directly invokereplace
.While
CompositeView
does not impose a layout policy on its childView
s it does allow for inseting the childView
s it will contain. The insets can be set by either #setInsets or #setParagraphInsetsIn addition to the abstract methods of javax.swing.text.View subclasses of
CompositeView
will need to override:@author Timothy Prinzing @version 1.
- {@link #isBefore} - Used to test if a given
View
location is before the visual space of theCompositeView
.- {@link #isAfter} - Used to test if a given
View
location is after the visual space of theCompositeView
.- {@link #getViewAtPoint} - Returns the view at a given visual location.
- {@link #childAllocation} - Returns the bounds of a particular child
View
.getChildAllocation
will invokechildAllocation
after offseting the bounds by theInset
s of theCompositeView
.63 1264 01/1231/0102
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 tomodelToView
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.11611812/03/0104/02 @see Caret
DefaultFormatter
formats aribtrary objects. Formatting is done by invoking thetoString
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 intostringToValue
.Instances of
DefaultFormatter
can not be used in multiple instances ofJFormattedTextField
. To obtain a copy of an already configuredDefaultFormatter
use theclone
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.6712/03/0120/02 @since 1.4
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.
- A logical set of child views which as used as a layout pool from which a physical view is formed.
- A strategy for translating the logical view to a physical (flowed) view.
- Constraints for the strategy to work against.
- A physical structure that represents the flow. The children of this view are where the pieces of of the logical views are placed to create the flow.
28 1229 01/1207/0102 @see View
JTextComponent
is the base class for swing text components. It tries to be compatible with thejava.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 theTextAction
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 whichJTextComponent
most recently has or had focus and therefore is the subject of the action (In the case that theActionEvent
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 inkeyTyped
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.
- 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
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 theClass ParagraphView, void setLineSpacing(float)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
Sets the line spacing. @param ls the valueinispointsa factor of the line hight
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
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
The amount of space between lines of the paragraph. Type is float and specifies the sizeinaspoints.a factor of the line height
The amount of space between lines of the paragraph. Type is float and specifies the sizeinaspoints.a factor of the line height
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