Chapter 30. The javax.swing.text Package

AbstractDocument	Java 1.2
javax.swing.text	serializable

This class is a partial, abstract implementation of the Document interface, which also defines several important inner classes and interfaces. Typical applications do not have to use or subclass this class. Instead, they can rely on predefined concrete implementations such as PlainDocument, DefaultStyledDocument, and javax.swing.text.html.HTMLDocument.

Hierarchy: Object-->AbstractDocument(Document,Serializable)

Subclasses: DefaultStyledDocument, PlainDocument

AbstractDocument.AbstractElement	Java 1.2
javax.swing.text	serializable

This abstract class is a partial implementation of the Element interface. Document objects derived from AbstractDocument are composed of Element objects derived from AbstractDocument.AbstractElement. In addition to implementing Element, this class also implements the MutableAttributeSet interface, so it can serve as its own attribute set. And it implements the TreeNode interface, which can make it easy to display the element structure of an AbstractDocument using the JTree component (a useful debugging technique). Applications typically do not use or subclass this class. See also the BranchElement and LeafElement subclasses, both of which are also inner classes of AbstractDocument.

Subclasses: AbstractDocument.BranchElement, AbstractDocument.LeafElement

Returned By: DefaultStyledDocument.createDefaultRoot(), PlainDocument.createDefaultRoot(), javax.swing.text.html.HTMLDocument.createDefaultRoot()

AbstractDocument.AttributeContext	Java 1.2
javax.swing.text

This interface defines methods that accept an immutable AttributeSet argument and return another immutable AttributeSet object. These methods can be used to implement the MutableAttributeSet interface entirely in terms of immutable AttributeSet objects. Most documents frequently reuse a small set of common attribute sets. The use of immutable AttributeSet objects is desirable because they may be cached and shared, resulting in substantial memory savings. JTextComponent uses the attribute set caching technique by default, and typical applications never need to use or implement this interface. See StyleContext for a concrete implementation of this interface.

Implementations: StyleContext

Passed To: AbstractDocument.AbstractDocument()

Returned By: AbstractDocument.getAttributeContext()

AbstractDocument.BranchElement	Java 1.2
javax.swing.text	serializable

This class is an Element implementation suitable for Document elements that contain other elements (e.g., paragraph elements).

Subclasses: DefaultStyledDocument.SectionElement, javax.swing.text.html.HTMLDocument.BlockElement

AbstractDocument.Content	Java 1.2
javax.swing.text

This interface defines an abstract representation of an editable piece of text. An AbstractDocument.Content object is used to represent the contents of any Document derived from AbstractDocument. A Content implementation must be able to return arbitrary text segments, insert and delete text, and return Position objects that mark positions within the content. If the Content implementation allows undo operations, the insertString() method should return an UndoableEdit object; otherwise it should return null. Applications typically do not use or implement this interface. See StringContent and GapContent for two implementations.

Implementations: GapContent, StringContent

Passed To: AbstractDocument.AbstractDocument(), DefaultStyledDocument.DefaultStyledDocument(), PlainDocument.PlainDocument(), javax.swing.text.html.HTMLDocument.HTMLDocument()

Returned By: AbstractDocument.getContent()

AbstractDocument.DefaultDocumentEvent	Java 1.2
javax.swing.text	serializable

This class is the javax.swing.event.DocumentEvent implementation used by documents derived from AbstractDocument. It is also an UndoableEdit and therefore can be used with the undo architecture of javax.swing.undo.

Passed To: AbstractDocument.{insertUpdate(), postRemoveUpdate(), removeUpdate()}, DefaultStyledDocument.{insertUpdate(), removeUpdate()}, DefaultStyledDocument.ElementBuffer.{change(), insert(), remove()}, PlainDocument.{insertUpdate(), removeUpdate()}, javax.swing.text.html.HTMLDocument.insertUpdate()

AbstractDocument.ElementEdit	Java 1.2
javax.swing.text	serializable

This class is the implementation of DocumentEvent.ElementEdit used by AbstractDocument.

AbstractDocument.LeafElement	Java 1.2
javax.swing.text	serializable

This class is an Element implementation suitable for Document elements that do not contain children elements (e.g., runs of styled text).

Subclasses: javax.swing.text.html.HTMLDocument.RunElement

AbstractWriter	Java 1.2
javax.swing.text

This abstract class provides a simple but convenient starting place for applications that want to write a textual representation of a Document or Element tree. The abstract write() method must be implemented by a subclass. This method must iterate over the Document or Element tree (using the ElementIterator provided by getElementIterator()) and write out a textual description of the Element objects using the other methods of the class. Applications do not typically use or subclass this class.

Subclasses: javax.swing.text.html.HTMLWriter, javax.swing.text.html.MinimalHTMLWriter

AttributeSet	Java 1.2
javax.swing.text

This interface defines the basic methods required for a set of attributes. It defines a mapping from attribute names, or keys, to attribute values. Both keys and values can be arbitrary objects. The StyleConstants class defines a number of commonly used attribute keys. The AttributeSet interface defines four inner interfaces. These empty interfaces serve as marker interfaces and should be implemented by an attribute key object to specify the general category of the key.

An AttributeSet can have another AttributeSet as its parent. When you look up a value with getAttribute(), the local mappings are searched first. If no matching attribute is found locally, however, the search continues (recursively) on the parent AttributeSet. The parent attribute set is itself stored as an attribute, using the key defined by the ResolveAttribute constant. Call getResolveParent() to query the parent AttributeSet. The isDefined() and getAttributeNames() methods operate only on the local attribute mappings and do not use the parent AttributeSet.

See also MutableAttributeSet, SimpleAttributeSet, Style, and StyleConstants.

Implementations: MutableAttributeSet, StyleContext.SmallAttributeSet

Passed To: Too many methods to list.

Returned By: Too many methods to list.

Type Of: DefaultStyledDocument.AttributeUndoableEdit.{copy, newAttributes}, SimpleAttributeSet.EMPTY

AttributeSet.CharacterAttribute	Java 1.2
javax.swing.text

This marker interface should be implemented by any object that serves as the key for a character attribute.

Implementations: StyleConstants.CharacterConstants, StyleConstants.ColorConstants, StyleConstants.FontConstants

AttributeSet.ColorAttribute	Java 1.2
javax.swing.text

This marker interface should be implemented by any object that serves as the key for a color attribute.

Implementations: StyleConstants.ColorConstants

AttributeSet.FontAttribute	Java 1.2
javax.swing.text

This marker interface should be implemented by any object that serves as the key for a font attribute.

Implementations: StyleConstants.FontConstants

AttributeSet.ParagraphAttribute	Java 1.2
javax.swing.text

This marker interface should be implemented by any object that serves as the key for a paragraph attribute.

Implementations: StyleConstants.ParagraphConstants

BadLocationException	Java 1.2
javax.swing.text	serializable checked

Thrown by methods throughout javax.swing.text when they are passed a document position that does not exist.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->BadLocationException

Thrown By: Too many methods to list.

BoxView	Java 1.2
javax.swing.text

This class is a CompositeView that arranges its children into a row or a column.

Hierarchy: Object-->View(SwingConstants)-->CompositeView-->BoxView

Subclasses: javax.swing.text.ParagraphView, TableView, TableView.TableCell, TableView.TableRow, WrappedPlainView, javax.swing.text.html.BlockView

Caret	Java 1.2
javax.swing.text

This interface defines the methods that must be implemented by a class that wants to keep track of the insertion cursor position and draw the insertion cursor for a JTextComponent. In the nomenclature of text editing, the dot is the current insertion position, and the mark is some other position in the text. The text between the dot and the mark is implicitly selected, and certain editing commands operate on this text. The setDot() method sets the position of both the dot and the mark, while moveDot() sets the position of the dot, leaving the mark where it is. The paint() method is called when the insertion cursor needs to be drawn or redrawn. setBlinkRate() specifies how often the cursor should blink. If the cursor does blink, Caret is responsible for causing this blinking; paint() is not automatically called to implement blinking. The Caret should notify any registered ChangeListener objects when the position of the cursor changes.

Although the Caret interface allows the appearance and behavior of the JTextComponent cursor to be customized, it is uncommon to do this. Most applications are perfectly content to use DefaultCaret, which is the Caret implementation installed by all the standard look-and-feels.

Implementations: DefaultCaret

Passed To: JTextComponent.setCaret()

Returned By: DefaultEditorKit.createCaret(), EditorKit.createCaret(), JTextComponent.getCaret()

ChangedCharSetException	Java 1.2
javax.swing.text	serializable checked

This subclass of IOException is thrown by the read() method of an EditorKit when it reads a document that it expects to be encoded in a given character set and finds that the document specifies that it is encoded using some other character set. Typically, this happens when reading HTML documents that specify their encoding using a <META> tag.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->java.io.IOException-->ChangedCharSetException

Thrown By: javax.swing.text.html.parser.DocumentParser.handleEmptyTag(), javax.swing.text.html.parser.Parser.{handleEmptyTag(), startTag()}

ComponentView	Java 1.2
javax.swing.text

This class is a View that encapsulates a Component and allows it to be displayed within a Document.

Hierarchy: Object-->View(SwingConstants)-->ComponentView

Subclasses: javax.swing.text.html.FormView, javax.swing.text.html.ObjectView

CompositeView	Java 1.2
javax.swing.text

This abstract class is a View that can have children.

Hierarchy: Object-->View(SwingConstants)-->CompositeView

Subclasses: BoxView

DefaultCaret	Java 1.2
javax.swing.text	cloneable serializable shape

This is the default Caret implementation installed on all JTextComponent components by all of the standard look-and-feel implementations. It displays the caret as a thin vertical line between characters. Most applications do not have to use this class directly and can simply rely on its automatic use by JTextComponent.

Hierarchy: Object-->java.awt.geom.RectangularShape(Cloneable,java.awt.Shape)-->java.awt.geom.Rectangle2D-->java.awt.Rectangle(Serializable,java.awt.Shape)-->DefaultCaret(Caret,java.awt.event.FocusListener(java.util.EventListener),java.awt.event.MouseListener(java.util.EventListener),java.awt.event.MouseMotionListener(java.util.EventListener))

DefaultEditorKit	Java 1.2
javax.swing.text	cloneable serializable

This class is an EditorKit for plain text. You can configure a JEditorPane to display plain, unformatted text using an instance of this class. The actions defined by this class are used by default by JTextComponent. DefaultEditorKit defines a number of String constants, which it uses as the names of the various Action objects it returns from its getActions() method.

Hierarchy: Object-->EditorKit(Cloneable,Serializable)-->DefaultEditorKit

Subclasses: StyledEditorKit

DefaultEditorKit.BeepAction	Java 1.2
javax.swing.text	cloneable serializable

This Action causes a beep.

DefaultEditorKit.CopyAction	Java 1.2
javax.swing.text	cloneable serializable

This action causes the selected region of the JTextComponent to be placed on the system clipboard and made available for pasting.

DefaultEditorKit.CutAction	Java 1.2
javax.swing.text	cloneable serializable

This Action deletes the selected region of the JTextComponent and makes its contents available for pasting on the system clipboard.

DefaultEditorKit.DefaultKeyTypedAction	Java 1.2
javax.swing.text	cloneable serializable

This Action is invoked when no other action is registered for a keystroke. It inserts the action command string (which is usually the key that triggered the action) at the current cursor position. Or, if there is currently a selection, it replaces the selected text with this text. This is the most commonly used action in a JTextComponent, since it is used to insert all characters the user types.

DefaultEditorKit.InsertBreakAction	Java 1.2
javax.swing.text	cloneable serializable

This Action inserts a new line break into the document and deletes any currently selected text.

DefaultEditorKit.InsertContentAction	Java 1.2
javax.swing.text	cloneable serializable

This Action inserts the ActionEvent command string into the document at the current position, deleting any current selection in the process.

DefaultEditorKit.InsertTabAction	Java 1.2
javax.swing.text	cloneable serializable

This Action inserts a horizontal tab into the document, replacing the selected text, if any.

DefaultEditorKit.PasteAction	Java 1.2
javax.swing.text	cloneable serializable

This Action gets the current text selection from the system clipboard and pastes it into the current document at the current insertion position, replacing any selected text.

DefaultHighlighter	Java 1.2
javax.swing.text

This class is the default highlighter object used by JTextComponent to keep track of highlighted regions within the Document.

Hierarchy: Object-->LayeredHighlighter(Highlighter)-->DefaultHighlighter

DefaultHighlighter.DefaultHighlightPainter	Java 1.2
javax.swing.text

This class is the default highlight painter object used by JTextComponent to draw its highlighted regions. It fills the highlighted area with a solid color. By default, the color is obtained with the getSelectionColor() method of the associated JTextComponent.

DefaultStyledDocument	Java 1.2
javax.swing.text	serializable

This class extends AbstractDocument and implements StyledDocument. It represents formatted text annotated with character and paragraph attributes. To insert text into a DefaultStyledDocument, use the inherited insertString() method, specifying a document position, the string to insert, and the AttributeSet of attributes that should be applied to the inserted string. You can display the contents of a DefaultStyledDocument using a JTextPane component.

Hierarchy: Object-->AbstractDocument(Document,Serializable)-->DefaultStyledDocument(StyledDocument(Document))

Subclasses: javax.swing.text.html.HTMLDocument

DefaultStyledDocument.AttributeUndoableEdit	Java 1.2
javax.swing.text	serializable

This UndoableEdit implementation is used internally by DefaultStyledDocument to remember (and undo) changes to the AttributeSet of an Element.

DefaultStyledDocument.ElementBuffer	Java 1.2
javax.swing.text	serializable

This class allows insertions into an Element tree in the form of an array of DefaultStyledDocument.ElementSpec objects. This is useful because a linear array of ElementSpec objects is often easier to work with than a tree of Element objects.

Type Of: DefaultStyledDocument.buffer

DefaultStyledDocument.ElementSpec	Java 1.2
javax.swing.text

This class is used to represent the elements of a document in a flat structure, instead of a tree. An ElementSpec object represent a start tag, an end tag, or document content. Arrays of ElementSpec objects can be used to represent a document or a portion of a document, and these ElementSpec objects can later be converted into a tree of Element objects. This class can be useful because it is often easier to work with an array of ElementSpec objects than with a tree of Element objects.

Passed To: DefaultStyledDocument.{create(), insert()}, DefaultStyledDocument.ElementBuffer.{insert(), insertUpdate()}, javax.swing.text.html.HTMLDocument.{create(), insert()}

DefaultStyledDocument.SectionElement	Java 1.2
javax.swing.text	serializable

This protected inner class is the default root element used by DefaultStyledDocument. Applications do not need to use or subclass this class.

DefaultTextUI	Java 1.2; Deprecated in Java 1.2
javax.swing.text

This class is deprecated and should not be used. As a text component UI delegate class, it never should have been part of this package.

Hierarchy: javax.swing.plaf.basic.BasicTextUI-->DefaultTextUI

Document	Java 1.2
javax.swing.text

This interface defines the fundamental methods required in a class that stores document text to be displayed and edited by a JTextComponent. The methods of this interface require that a Document object be able to represent document content both as a linear sequence of characters and as a tree of hierarchical Element objects. Element objects model the document structure and are used to represent things like paragraphs, lines, and runs of styled text. When a JTree component displays a Document, the Element tree is used to create a tree of View objects that display the individual elements.

The getText() methods return text from the document, either as a String or in a supplied Segment object. insertString() inserts a run of text associated with the specified attributes. remove() deletes text from the Document. The Document object must fire appropriate DocumentEvent and UndoableEditEvent events when edits like these are performed. createPosition() returns a Position object that represents a relative position in the document. The Position reference remains valid even if text is inserted or deleted from the document. The putProperty() and getProperty() methods allow arbitrary key/value pairs to be associated with a Document. These properties can be used to hold metainformation, such as the author and title of the document. The TitleProperty and StreamDescriptionProperty constants are two predefined property keys. Finally, the render() method must run the specified Runnable object while guaranteeing that there will not be any changes to the document. This method is used to perform the potentially time-consuming document-rendering process in a thread-safe way.

See also Element, AttributeSet, Position, and Segment.

Implementations: AbstractDocument, StyledDocument

Passed To: Too many methods to list.

Returned By: JTextArea.createDefaultModel(), JTextField.createDefaultModel(), javax.swing.event.DocumentEvent.getDocument(), AbstractDocument.AbstractElement.getDocument(), AbstractDocument.DefaultDocumentEvent.getDocument(), AbstractWriter.getDocument(), DefaultEditorKit.createDefaultDocument(), EditorKit.createDefaultDocument(), javax.swing.text.Element.getDocument(), JTextComponent.getDocument(), StyledEditorKit.createDefaultDocument(), View.getDocument(), javax.swing.text.html.HTMLEditorKit.createDefaultDocument()

EditorKit	Java 1.2
javax.swing.text	cloneable serializable

This abstract class defines the methods that are used to configure a JEditorPane to display and edit a particular type of document. Swing contains concrete subclasses for plain text, as well as HTML and RTF documents. To configure a JEditorPane, instantiate an EditorKit object and pass it to the setEditorKit() method of your JEditorPane.

The getContentType() method of an EditorKit returns the MIME type supported by the kit. createDefaultDocument() creates an appropriate type of empty Document object to hold the document. The read() and write() methods read and write document content from and to streams. getViewFactory() returns a ViewFactory object for this document type. The ViewFactory is used to convert the Element objects of the document into View objects that display the document on the screen. createCaret() returns a Caret object that the JEditorPane can use to navigate the document, and getActions() returns an array of Action objects that the JEditorPane can bind to keystrokes. EditorKit implementations typically define a number of Action implementations as inner classes.

Hierarchy: Object-->EditorKit(Cloneable,Serializable)

Subclasses: DefaultEditorKit

Passed To: JEditorPane.{setEditorKit(), setEditorKitForContentType()}, JTextPane.setEditorKit()

Returned By: JEditorPane.{createDefaultEditorKit(), createEditorKitForContentType(), getEditorKit(), getEditorKitForContentType()}, JTextPane.createDefaultEditorKit(), javax.swing.plaf.TextUI.getEditorKit()

Element	Java 1.2
javax.swing.text

This interface defines the methods required for objects that want to be part of a Document object's element tree. An Element object must keep track of its parent and its children. It must also know its position and the position of its children within the linear sequence of characters that comprise the Document. Finally, an Element must be able to return the set of attributes that have been applied to it. getParentElement() returns the parent. getElementCount() and getElement() return the number of child elements and the specified child element, respectively. getStartOffset() and getEndOffset() return the start and end positions of this element. getElementIndex() returns the index of the child element that contains the specified position. getAttributes() returns the AttributeSet for this element.

Implementations: AbstractDocument.AbstractElement

Passed To: Too many methods to list.

Returned By: Too many methods to list.

Type Of: DefaultStyledDocument.AttributeUndoableEdit.element

ElementIterator	Java 1.2
javax.swing.text	cloneable

This class is used to perform a depth-first traversal, or iteration, through a tree of Element objects. The Element tree structure should not be changed while the iteration is in progress. Note that despite its name, this class does not implement java.util.Iterator.

Hierarchy: Object-->ElementIterator(Cloneable)

Returned By: AbstractWriter.getElementIterator()

FieldView	Java 1.2
javax.swing.text

This View class displays a single line of plain text. It is used, for example, by JTextField.

Hierarchy: Object-->View(SwingConstants)-->PlainView(TabExpander)-->FieldView

Subclasses: PasswordView

GapContent	Java 1.2
javax.swing.text	serializable

This class is an implementation of the AbstractDocument.Content interface that uses an array of characters with a gap of unused characters in it. This gap is positioned near the current insertion position so that subsequent insertions require fewer characters to be shifted in the array. This implementation is more complicated than StringContent, but it works efficiently with documents of any size. This is the default Content implementation for all documents derived from AbstractDocument. This class inherits from a private superclass, GapVector, which is not covered in this book because it is private.

Hierarchy: Object-->GapVector(Serializable)-->GapContent(AbstractDocument.Content,Serializable)

Highlighter	Java 1.2
javax.swing.text

This interface defines the methods that must be implemented by an object that wants to maintain and draw the list of selected regions within a JTextComponent. The methods of Highlighter allow selected regions to be added, changed, and removed for the set of highlighted regions. Each region is specified as a start and end position within the Document and a Highlighter.HighlightPainter object that is used to draw the highlight. The getHighlights() method returns an array of Highlighter.Highlight objects that describe the individual highlighted regions and their painter objects. Most applications can rely on the DefaultHighlighter class that is used by default by JTextComponent and never have to implement this interface.

Implementations: LayeredHighlighter

Passed To: JTextComponent.setHighlighter()

Returned By: JTextComponent.getHighlighter()

Highlighter.Highlight	Java 1.2
javax.swing.text

The methods of this interface describe a highlighted region in a Document by specifying the start and end positions of the region and the Highlighter.HighlightPainter object that is used to draw the highlighted region.

Returned By: DefaultHighlighter.getHighlights(), Highlighter.getHighlights(), LayeredHighlighter.getHighlights()

Highlighter.HighlightPainter	Java 1.2
javax.swing.text

This interface defines the paint() method used to draw a highlighted region.

Implementations: LayeredHighlighter.LayerPainter

Passed To: DefaultHighlighter.addHighlight(), Highlighter.addHighlight(), LayeredHighlighter.addHighlight()

Returned By: DefaultCaret.getSelectionPainter(), Highlighter.Highlight.getPainter()

IconView	Java 1.2
javax.swing.text

This View class encapsulates a javax.swing.Icon and allows icons and images to be displayed within a Document.

Hierarchy: Object-->View(SwingConstants)-->IconView

JTextComponent	Java 1.2
javax.swing.text	serializable accessible(text) swing component

This is the base class for all Swing text-editing components. Applications do not use this class directly, but instead use one of its subclasses in the javax.swing package: JTextField, JTextArea, JPasswordField, JEditorPane, or JTextPane. A JTextComponent displays the text contained in its model object, an object of type Document. Other important classes and interfaces used by JTextComponent are Caret, Highlighter, Keymap, Style, EditorKit, TextAction, and View.

Hierarchy: Object-->Component(java.awt.image.ImageObserver,java.awt.MenuContainer,Serializable)-->Container-->JComponent(Serializable)-->JTextComponent(Accessible,Scrollable)

Subclasses: JEditorPane, JTextArea, JTextField

Passed To: Too many methods to list.

Returned By: DefaultCaret.getComponent(), TextAction.{getFocusedComponent(), getTextComponent()}