Summary of Text

The Java^TM Tutorial

Start of Tutorial > Start of Trail > Start of Lesson

Trail: Creating a GUI with JFC/Swing
Lesson: Using Swing Components

Summary of Text

Because JTextComponent and its subclasses have too many features to be completely described in this tutorial, please periodically search The Swing Connection for pointers to other text documentation. Also, check our book.html file for references to further documentation and examples. For API tables and examples of text fields and password fields, see The Text Field and Password Field API and Examples that Use Text Fields and Password Fields.
This section has two parts:

The Text API
Examples that Use Text Components

The Text API

The tables in this section cover just part of the text API. For more information about the text API, see the API documentation for JTextComponent and for the various classes and interfaces in the text package . Also see The JComponent Class, which describes the API that the text components inherit from JComponent.
The API for text falls into these categories:

Swing Text Component Classes
Setting Attributes
Converting Positions Between the Model and The View
Classes and Interfaces that Represent Documents
Useful Methods for Working with Documents
Manipulating the Current Selection
Manipulating Carets and Selection Highlighters
Text Editing Commands
Binding KeyStrokes to Actions
Reading and Writing Text
Displaying Text from a URL

Swing Text Component Classes
Class Description

JTextComponent The abstract superclass of all Swing text components. See General Rules for Using Text Components.

JTextField An optionally editable, single-line, plain text component. See How to Use Text Fields.

JPasswordField An optionally editable, single-line, plain text component that masks its content. See Providing a Password Field.

JTextArea An optionally editable, multi-line, plain text component. See Using a Text Area.

JEditorPane An optionally editable, multi-line, styled text component. See Concepts: About Editor Panes and Text Panes.

JTextPane An optionally editable, multi-line, styled text component with support for named attributes. See Concepts: About Editor Panes and Text Panes.

Setting Attributes
Method Description

void setDisabledTextColor(Color) Color getDisabledTextColor()
(in JTextComponent) Set or get the color used to display text when the text component is disabled.

void setOpaque(boolean) boolean getOpaque()
(in JTextComponent) Set or get whether the text component is completely opaque.

void setMargin(Insets) Insets getMargin()
(in JTextComponent) Set or get the margin between the text and the text component's border.

void setEditable(boolean) boolean isEditable()
(in JTextComponent) Set or get whether the user can edit the text in the text component.

Converting Positions Between the Model and the View
Method Description

int viewToModel(Point)
(in JTextComponent) Convert the specified point in the view coordinate system to a position within the text.

Rectangle modelToView(int)
(in JTextComponent) Convert the specified position within the text to a rectangle in the view coordinate system.

Classes and Interfaces that Represent Documents
Interface or Class Description

Document
(an interface) Defines the API that must be implemented by all documents.

AbstractDocument
(an interface) An abstract superclass implementation of the Document interface. This is the superclass for all documents provided by the Swing text package.

PlainDocument
(a class) Implements the Document interface. This is the default document for the plain text components (text field, password field, and text area). Additionally used by editor pane and text pane when loading plain text or text of an unknown format.

StyledDocument
(an interface) A Document subinterface. Defines the API that must be implemented by documents that support styled text. JTextPane requires that its document be of this type.

DefaultStyledDocument
(a class) Implements the StyledDocument interface. The default document for JTextPane.

Useful Methods for Working with Documents
Method Description

setDocument(Document) Document getDocument()
(in JTextComponent) Set or get the document for a text component.

Document createDefaultModel()
(in JTextField) Override this method in text field and its subclasses to create a custom document instead of the default PlainDocument. Creating a Validated Text Field provides an example of overriding this method.

void insertString(int, String, AttributeSet) void remove(int, int)
(in Document) These methods are commonly overridden by custom documents. For an example of a custom document that overrides both of these methods, see Creating a Validated Text Field.

void addDocumentListener(DocumentListener) void removeDocumentListener(DocumentListener)
(in Document) Add or remove a document listener to a document. See Listening for Changes on a Document.

void addUndoableEditListener(UndoableEditListener) void removeUndoableEditListener(UndoableEditlistener)
(in Document) Add or remove an undoable edit listener to a document. Undoable edit listeners are used in Implementing Undo and Redo.

int getLength() Position getStartPosition() Position getEndPosition() String getText(int, int)
(in Document) Document methods that return useful information about the document.

Object getProperty(Object) void putProperty(Object, Object)
(in Document)
Dictionary getDocumentProperties() void setDocumentProperties(Dictionary)
(in AbstractDocument) A Document maintains a set of properties that you can manipulate with these methods. The example described in Using a Document Listener on a Text Field uses a property to name text components so that a shared document listener can identify the document that generated the event.

Manipulating the Current Selection
Method Description

String getSelectedText() Get the currently selected text.

void selectAll() void select(int, int)
(in JTextComponent) Select all text or select text within a start and end range.

void setSelectionStart(int) void setSelectionEnd(int) int getSelectionStart() int getSelectionEnd()
(in JTextComponent) Set or get extent of the current selection by index.

void setSelectedTextColor(Color) Color getSelectedTextColor()
(in JTextComponent) Set or get the color of selected text.

void setSelectionColor(Color) Color getSelectionColor() (in JTextComponent) Set or get the background color of selected text.

Manipulating Carets and Selection Highlighters
Interface, Class, or Method Description

Caret
(an interface) Defines the API for objects that represent an insertion point within documents.

DefaultCaret
(a class) The default caret used by all text components.

void setCaret(Caret) Caret getCaret()
(in JTextComponent) Set or get the caret object used by a text component.

void setCaretColor(Color) Color getCaretColor()
(in JTextComponent) Set or get the color of the caret.

void setCaretPosition(Position) void moveCaretPosition(int) Position getCaretPosition()
(in JTextComponent) Set or get the current position of the caret within the document.

void addCaretListener(CaretListener) void removeCaretListener(CaretListener)
(in JTextComponent) Add or remove a caret listener to a text component.

Highlighter
(an interface) Defines the API for objects used to highlight the current selection.

DefaultHighlighter
(a class) The default highlighter used by all text components.

void setHighlighter(Highlighter) Highlighter getHighlighter()
(in JTextComponent) Set or get the highlighter used by a text component.

Text Editing Commands
Class or Method Description

void cut() void copy() void paste() void replaceSelection(String)
(in JTextComponent) Cut, copy, and paste text using the system clipboard.

EditorKit
(a class) Edit, read, and write text of a particular format.

DefaultEditorKit
(a class) A concrete subclass of EditorKit that provides the basic text editing capabilities.

StyledEditorKit
(a class) A subclass of Default EditorKit that provides additional editing capabilities for styled text.

String xxxxAction
(in DefaultEditorKit) The names of all the actions supported by the default editor kit.

BeepAction CopyAction CutAction DefaultKeyTypedAction InsertBreakAction InsertContentAction InsertTabAction PasteAction
(in DefaultEditorKit) Inner classes that implement various text editing commands.

AlignmentAction BoldAction FontFamilyAction FontSizeAction ForegroundAction ItalicAction StyledTextAction UnderlineAction
(in StyledEditorKit) Inner classes that implement various editing commands for styled text.

Action[] getActions()
(in JTextComponent) Get the actions supported by this component. This method gets the array of actions from the editor kit if one is used by the component.

Binding KeyStrokes to Actions
Interface or Method Description

Keymap
(an interface) An interface for managing a set of key bindings. A key binding is represented by a keystroke/action pair.

Keymap addKeymap(nm, Keymap) Keymap removeKeymap(nm) Keymap getKeymap(nm)
(in JTextComponent) Add or remove a keymap to the keymap hierarchy. Also get a keymap by name. Note that these are class methods. The keymap hierarchy is shared by all text components.

void loadKeymap(Keymap, KeyBinding[], Action[])
(in JTextComponent) Adds a set of key bindings to the specified keymap. This is a class method.

void setKeymap(Keymap) Keymap getKeymap()
(in JTextComponent) Set or get the currently active keymap for a particular text component.

void addActionForKeyStroke(KeyStroke, Action) Action getAction(KeyStroke) KeyStroke[] getKeyStrokesForAction(Action)
(in Keymap) Set or get keystroke/action binding from a keymap.

boolean isLocallyDefined(KeyStroke)
(in Keymap) Get whether the specified keystroke is bound to an action in a keymap.

void removeKeyStrokeBinding(KeyStroke) void removeBindings()
(in Keymap) Remove one or all key bindings from a keymap.

void setDefaultAction(Action) Action getDefaultAction()
(in Keymap) Set or get the default action. This action is fired if a keystroke is not explicitly bound to an action.

Action[] getBoundActions() KeyStroke[] getBoundKeyStrokes()
(in Keymap) Get an array containing all of the bound actions or keystrokes in a keymap.

Reading and Writing Text
Method Description

void JTextComponent.read(Reader, Object) void JTextComponent.write(Writer)
(in JTextComponent) Read or write text.

void read(Reader, Document, int) void read(InputStream, Document, int)
(in EditorKit) Read text from a stream into a document.

void write(Writer, Document, int, int) void write(OutputStream, Document, int, int)
(in EditorKit) Write text from a document to a stream.

Displaying Text from a URL
Method or Constructor Description

JEditorPane(URL) JEditorPane(String)
(in JEditorPane) Create an editor pane loaded with the text at the specified URL.

setPage(URL) setPage(String)
(in JEditorPane) Load an editor pane (or text pane) with the text at the specified URL.

URL getPage()
(in JEditorPane) Get the URL for the editor pane's (or text pane's) current page.

Swing Text Component Classes
Class	Description
`JTextComponent`	The abstract superclass of all Swing text components. See General Rules for Using Text Components.
`JTextField`	An optionally editable, single-line, plain text component. See How to Use Text Fields.
`JPasswordField`	An optionally editable, single-line, plain text component that masks its content. See Providing a Password Field.
`JTextArea`	An optionally editable, multi-line, plain text component. See Using a Text Area.
`JEditorPane`	An optionally editable, multi-line, styled text component. See Concepts: About Editor Panes and Text Panes.
`JTextPane`	An optionally editable, multi-line, styled text component with support for named attributes. See Concepts: About Editor Panes and Text Panes.

Setting Attributes
Method	Description
`void setDisabledTextColor(Color) Color getDisabledTextColor()` (in `JTextComponent`)	Set or get the color used to display text when the text component is disabled.
`void setOpaque(boolean) boolean getOpaque()` (in `JTextComponent`)	Set or get whether the text component is completely opaque.
`void setMargin(Insets) Insets getMargin()` (in `JTextComponent`)	Set or get the margin between the text and the text component's border.
`void setEditable(boolean) boolean isEditable()` (in `JTextComponent`)	Set or get whether the user can edit the text in the text component.

Converting Positions Between the Model and the View
Method	Description
`int viewToModel(Point)` (in `JTextComponent`)	Convert the specified point in the view coordinate system to a position within the text.
`Rectangle modelToView(int)` (in `JTextComponent`)	Convert the specified position within the text to a rectangle in the view coordinate system.

Classes and Interfaces that Represent Documents
Interface or Class	Description
`Document` (an interface)	Defines the API that must be implemented by all documents.
`AbstractDocument` (an interface)	An abstract superclass implementation of the `Document` interface. This is the superclass for all documents provided by the Swing text package.
`PlainDocument` (a class)	Implements the `Document` interface. This is the default document for the plain text components (text field, password field, and text area). Additionally used by editor pane and text pane when loading plain text or text of an unknown format.
`StyledDocument` (an interface)	A `Document` subinterface. Defines the API that must be implemented by documents that support styled text. `JTextPane` requires that its document be of this type.
`DefaultStyledDocument` (a class)	Implements the `StyledDocument` interface. The default document for `JTextPane`.

Useful Methods for Working with Documents
Method	Description
`setDocument(Document) Document getDocument()` (in `JTextComponent`)	Set or get the document for a text component.
`Document createDefaultModel()` (in `JTextField`)	Override this method in text field and its subclasses to create a custom document instead of the default `PlainDocument`. Creating a Validated Text Field provides an example of overriding this method.
`void insertString(int, String, AttributeSet) void remove(int, int)` (in `Document`)	These methods are commonly overridden by custom documents. For an example of a custom document that overrides both of these methods, see Creating a Validated Text Field.
`void addDocumentListener(DocumentListener) void removeDocumentListener(DocumentListener)` (in `Document`)	Add or remove a document listener to a document. See Listening for Changes on a Document.
`void addUndoableEditListener(UndoableEditListener) void removeUndoableEditListener(UndoableEditlistener)` (in `Document`)	Add or remove an undoable edit listener to a document. Undoable edit listeners are used in Implementing Undo and Redo.
`int getLength() Position getStartPosition() Position getEndPosition() String getText(int, int)` (in `Document`)	`Document` methods that return useful information about the document.
`Object getProperty(Object) void putProperty(Object, Object)` (in `Document`) `Dictionary getDocumentProperties() void setDocumentProperties(Dictionary)` (in `AbstractDocument`)	A `Document` maintains a set of properties that you can manipulate with these methods. The example described in Using a Document Listener on a Text Field uses a property to name text components so that a shared document listener can identify the document that generated the event.

Manipulating the Current Selection
Method	Description
`String getSelectedText()`	Get the currently selected text.
`void selectAll() void select(int, int)` (in `JTextComponent`)	Select all text or select text within a start and end range.
`void setSelectionStart(int) void setSelectionEnd(int) int getSelectionStart() int getSelectionEnd()` (in `JTextComponent`)	Set or get extent of the current selection by index.
`void setSelectedTextColor(Color) Color getSelectedTextColor()` (in `JTextComponent`)	Set or get the color of selected text.
`void setSelectionColor(Color) Color getSelectionColor() (in JTextComponent)`	Set or get the background color of selected text.

Manipulating Carets and Selection Highlighters
Interface, Class, or Method	Description
`Caret` (an interface)	Defines the API for objects that represent an insertion point within documents.
`DefaultCaret` (a class)	The default caret used by all text components.
`void setCaret(Caret) Caret getCaret()` (in `JTextComponent`)	Set or get the caret object used by a text component.
`void setCaretColor(Color) Color getCaretColor()` (in `JTextComponent`)	Set or get the color of the caret.
`void setCaretPosition(Position) void moveCaretPosition(int) Position getCaretPosition()` (in `JTextComponent`)	Set or get the current position of the caret within the document.
`void addCaretListener(CaretListener) void removeCaretListener(CaretListener)` (in `JTextComponent`)	Add or remove a caret listener to a text component.
`Highlighter` (an interface)	Defines the API for objects used to highlight the current selection.
`DefaultHighlighter` (a class)	The default highlighter used by all text components.
`void setHighlighter(Highlighter) Highlighter getHighlighter()` (in `JTextComponent`)	Set or get the highlighter used by a text component.

Text Editing Commands
Class or Method	Description
`void cut() void copy() void paste() void replaceSelection(String)` (in `JTextComponent`)	Cut, copy, and paste text using the system clipboard.
`EditorKit` (a class)	Edit, read, and write text of a particular format.
`DefaultEditorKit` (a class)	A concrete subclass of `EditorKit` that provides the basic text editing capabilities.
`StyledEditorKit` (a class)	A subclass of `Default EditorKit` that provides additional editing capabilities for styled text.
`String xxxxAction` (in `DefaultEditorKit`)	The names of all the actions supported by the default editor kit.
`BeepAction CopyAction CutAction DefaultKeyTypedAction InsertBreakAction InsertContentAction InsertTabAction PasteAction` (in `DefaultEditorKit`)	Inner classes that implement various text editing commands.
`AlignmentAction BoldAction FontFamilyAction FontSizeAction ForegroundAction ItalicAction StyledTextAction UnderlineAction` (in `StyledEditorKit`)	Inner classes that implement various editing commands for styled text.
`Action[] getActions()` (in `JTextComponent`)	Get the actions supported by this component. This method gets the array of actions from the editor kit if one is used by the component.

Binding KeyStrokes to Actions
Interface or Method	Description
`Keymap` (an interface)	An interface for managing a set of key bindings. A key binding is represented by a keystroke/action pair.
`Keymap addKeymap(nm, Keymap) Keymap removeKeymap(nm) Keymap getKeymap(nm)` (in `JTextComponent`)	Add or remove a keymap to the keymap hierarchy. Also get a keymap by name. Note that these are class methods. The keymap hierarchy is shared by all text components.
`void loadKeymap(Keymap, KeyBinding[], Action[])` (in `JTextComponent`)	Adds a set of key bindings to the specified keymap. This is a class method.
`void setKeymap(Keymap) Keymap getKeymap()` (in `JTextComponent`)	Set or get the currently active keymap for a particular text component.
`void addActionForKeyStroke(KeyStroke, Action) Action getAction(KeyStroke) KeyStroke[] getKeyStrokesForAction(Action)` (in `Keymap`)	Set or get keystroke/action binding from a keymap.
`boolean isLocallyDefined(KeyStroke)` (in `Keymap`)	Get whether the specified keystroke is bound to an action in a keymap.
`void removeKeyStrokeBinding(KeyStroke) void removeBindings()` (in `Keymap`)	Remove one or all key bindings from a keymap.
`void setDefaultAction(Action) Action getDefaultAction()` (in `Keymap`)	Set or get the default action. This action is fired if a keystroke is not explicitly bound to an action.
`Action[] getBoundActions() KeyStroke[] getBoundKeyStrokes()` (in `Keymap`)	Get an array containing all of the bound actions or keystrokes in a keymap.

Reading and Writing Text
Method	Description
`void JTextComponent.read(Reader, Object) void JTextComponent.write(Writer)` (in `JTextComponent`)	Read or write text.
`void read(Reader, Document, int) void read(InputStream, Document, int)` (in `EditorKit`)	Read text from a stream into a document.
`void write(Writer, Document, int, int) void write(OutputStream, Document, int, int)` (in `EditorKit`)	Write text from a document to a stream.

Displaying Text from a URL
Method or Constructor	Description
`JEditorPane(URL) JEditorPane(String)` (in `JEditorPane`)	Create an editor pane loaded with the text at the specified URL.
`setPage(URL) setPage(String)` (in `JEditorPane`)	Load an editor pane (or text pane) with the text at the specified URL.
`URL getPage()` (in `JEditorPane`)	Get the URL for the editor pane's (or text pane's) current page.

Examples that Use Text Components

This table shows some of the examples that use text components and where those examples are described. To get started with text, you might want to run these programs and examine their code to find one that does something similar to what you want to do. For text and password field examples, don't forget to look at Examples that Use Text Fields and Password Fields.

Example Where Described Notes

TextSamplerDemo An Example of Using Each Text Component Uses one of each of Swing's text components.

TextComponentDemo General Rules for Using Text Components Provides a customized text pane. Illustrates many text component features.

ToolBarDemo2 How to Use Tool Bars Puts a text field in a tool bar.

CustomDialog.java How to Use Dialogs Puts a validated text field in a dialog. Part of DialogDemo (under the More Dialogs tab).

TreeDemo How to Use Trees Uses an editor pane to display help loaded from an HTML file.

Example	Where Described	Notes
`TextSamplerDemo`	An Example of Using Each Text Component	Uses one of each of Swing's text components.
`TextComponentDemo`	General Rules for Using Text Components	Provides a customized text pane. Illustrates many text component features.
`ToolBarDemo2`	How to Use Tool Bars	Puts a text field in a tool bar.
`CustomDialog.java`	How to Use Dialogs	Puts a validated text field in a dialog. Part of `DialogDemo` (under the More Dialogs tab).
`TreeDemo`	How to Use Trees	Uses an editor pane to display help loaded from an HTML file.

Start of Tutorial > Start of Trail > Start of Lesson