All Packages  Class Hierarchy  This Package  Previous  Next  Index  

Class java.awt.swing.text.JTextComponent

java.lang.Object
    |
    +----java.awt.Component
            |
            +----java.awt.Container
                    |
                    +----java.awt.swing.JComponent
                            |
                            +----java.awt.swing.text.JTextComponent

public abstract class JTextComponent

extends JComponent

implements Scrollable, Accessible, AccessibleText

A text-oriented editor is defined to pull together the components 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. 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. User interface events are sent to the editor's controller which determines if and how it will deal with the events. Some events result in modifications to the model which subsequently cause notifcation to the view which updates itself to reflect the modified model. Some events modify the view directly, such as a mouse sweep being used to highlight an area of the view or moving an insert position.

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. Changes to the model are sent in the form of a DocumentEvent which is sent to observers that have implemented the DocumentListener interface and registered interest with the model being observed.

See Also:

Document, DocumentEvent, DocumentListener, TextUI, ViewFactory, Highlighter, Caret

FOCUS_ACCELERATOR_KEY

The key name for the focus accelerator.

JTextComponent()

Creates a new JTextComponent.

copy()

Transfers the currently selected range in the associated text model to the system clipboard, leaving the contents in the text model.

cut()

Transfers the currently selected range in the associated text model to the system clipboard, removing the contents from the model.

getAccessibleRole()

Gets the role of this object.

getAccessibleText()

Gets the AccessibleText interface for the component.

getActions()

Fetches the command list for the editor.

getAfterIndex(int, int)

Return the String after a given index.

getAtIndex(int, int)

Return the String at a given index.

getBeforeIndex(int, int)

Return the String before a given index.

getCaret()

Fetches the cursor that allows text-oriented navigation over the view.

getCaretColor()

Fetch the current color used to render the caret.

getCaretPosition()

Returns the position of the text insertion caret for the text component.

getCharacterAttribute(int)

Returns the AttributeSet for a given character (at a given index)

getCharacterBounds(int)

Given an index into the String, determines the bounding box of the character at that index.

getCharCount()

Returns the number of characters (valid indices)

getDisabledTextColor()

Fetch the current color used to render the selected text.

getDocument()

Fetches the model associated with the editor.

getFocusAccelerator()

Returns the key accelerator that will cause the receiving text component to get the focus.

getHighlighter()

Fetches the object responsible for making highlights.

getIndexAtPoint(Point)

Given a point in local coordinates, returns the zero-based index of the character under that Point.

getKeymap()

Fetches the keymap being used by the controller

getMargin()

Returns the margin between the text component's border and its text.

getPreferredScrollableViewportSize()

Returns the preferred size of the viewport for a view component.

getScrollableBlockIncrement(Rectangle, int, int)

Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.

getScrollableTracksViewportHeight()

Return true if a viewport should always force the height of this Scrollable to match the height of the viewport.

getScrollableTracksViewportWidth()

Return true if a viewport should always force the width of this Scrollable to match the width of the viewport.

getScrollableUnitIncrement(Rectangle, int, int)

Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation.

getSelectedText()

Returns the selected text contained in this TextComponent.

getSelectedTextColor()

Fetch the current color used to render the selected text.

getSelectionColor()

Fetch the current color used to render the selection.

getSelectionEnd()

Returns the selected text's end position.

getSelectionStart()

Returns the selected text's start position.

getText()

Returns the text contained in this TextComponent.

getText(int, int)

Fetch a portion of the text represented by the component.

getUI()

Fetches the user-interface factory for this text-oriented editor.

isEditable()

Returns the boolean indicating whether this TextComponent is editable or not.

isFocusTraversable()

Returns true if the focus can be traversed.

isOpaque()

Returns true if this component is completely opaque.

modelToView(int)

Converts the given location in the model to a place in the view coordinate system.

moveCaretPosition(int)

Moves the caret to a new position, leaving behind a mark defined by the last time setCaretPosition was called.

paste()

Transfers the contents of the system clipboard into the associated text model.

read(Reader, Object)

Initialize from a stream.

replaceSelection(String)

Replaces the currently selected content with new content represented by the given string.

select(int, int)

Selects the text found between the specified start and end locations.

selectAll()

Selects all the text in the TextComponent.

setCaret(Caret)

Set the caret to be used.

setCaretColor(Color)

Set the current color used to render the caret.

setCaretPosition(int)

Sets the position of the text insertion caret for the TextComponent

setDisabledTextColor(Color)

Set the current color used to render the disabled text.

setDocument(Document)

Associates the editor with a text document.

setEditable(boolean)

Sets the specified boolean to indicate whether or not this TextComponent should be editable.

setFocusAccelerator(char)

Sets the key accelerator that will cause the receiving text component to get the focus.

setHighlighter(Highlighter)

Set the highlighter to be used.

setKeymap(Keymap)

Sets the keymap to use for binding events to actions.

setMargin(Insets)

Sets margin space between the text component's border and its text.

setOpaque(boolean)

Set whether or not the UI should render a background

setSelectedTextColor(Color)

Set the current color used to render the selected text.

setSelectionColor(Color)

Set the current color used to render the selection.

setSelectionEnd(int)

Sets the selection end to the specified position.

setSelectionStart(int)

Sets the selection start to the specified position.

setText(String)

Sets the text of this TextComponent to the specified text.

setUI(TextUI)

Sets the user-interface factory for this text-oriented editor

updateUI()

Reloads the pluggable UI.

viewToModel(Point)

Converts the given place in the view coordinate system to the nearest representative location in the model.

write(Writer)

Stores the contents of the model into the given stream.

public static final String FOCUS_ACCELERATOR_KEY

The key name for the focus accelerator.

public JTextComponent()

Creates a new JTextComponent.

public TextUI getUI()

Fetches the user-interface factory for this text-oriented editor.

Returns:

the factory

public void setUI(TextUI ui)

Sets the user-interface factory for this text-oriented editor

Parameters:

ui - the factory

public void updateUI()

Reloads the pluggable UI. The key used to fetch the new interface is getUIClassID(). The type of the UI is TextUI.

Overrides:

updateUI in class JComponent

public boolean isOpaque()

Returns true if this component is completely opaque.

Returns:

true if this component is completely opaque.

Overrides:

isOpaque in class JComponent

public void setOpaque(boolean o)

Set whether or not the UI should render a background

Parameters:

o - true if should render a background

public void setDocument(Document doc)

Associates the editor with a text document. The currently registered factory is used to build a view for the document, which gets displayed by the editor.

Parameters:

doc - the document to display/edit

public Document getDocument()

Fetches the model associated with the editor. This is primarily for the UI to get at the minimal amount of state required to be a text editor. Subclasses will return the actual type of the model which will typically be something that extends Document.

Returns:

the model

public Action[] getActions()

Fetches the command list for the editor. This is the list of commands supported by the plugged-in UI augmented by the collection of commands that the editor itself supports. These are useful for binding to events, such as in a keymap.

Returns:

the command list

public void setMargin(Insets m)

Sets margin space between the text component's border and its text. Setting it to null will cause the text component to use a default margin. The text component's default Border object will use this value to create the proper margin. However, if a non-default border is set on the text component, it is that Border object's responsibility to create the appropriate margin space (else this property will effectively be ignored).

Parameters:

m - the space between the border and the text

public Insets getMargin()

Returns the margin between the text component's border and its text.

Returns:

the margin

public Caret getCaret()

Fetches the cursor that allows text-oriented navigation over the view.

Returns:

the cursor

public void setCaret(Caret c)

Set the caret to be used. By default this will be set by the UI that gets installed. This can be changed to a custom caret if desired.

Parameters:

c - the caret

public Highlighter getHighlighter()

Fetches the object responsible for making highlights.

Returns:

the highlighter

public void setHighlighter(Highlighter h)

Set the highlighter to be used. By default this will be set by the UI that gets installed. This can be changed to a custom highlighter if desired.

Parameters:

h - the highlighter

public void setKeymap(Keymap map)

Sets the keymap to use for binding events to actions.

Parameters:

map - the keymap

public Keymap getKeymap()

Fetches the keymap being used by the controller

Returns:

the keymap

public Color getCaretColor()

Fetch the current color used to render the caret.

Returns:

the color

public void setCaretColor(Color c)

Set the current color used to render the caret.

Parameters:

c - the color

public Color getSelectionColor()

Fetch the current color used to render the selection.

Returns:

the color

public void setSelectionColor(Color c)

Set the current color used to render the selection.

Parameters:

c - the color

public Color getSelectedTextColor()

Fetch the current color used to render the selected text.

Returns:

the color

public void setSelectedTextColor(Color c)

Set the current color used to render the selected text.

Parameters:

c - the color

public Color getDisabledTextColor()

Fetch the current color used to render the selected text.

Returns:

the color

public void setDisabledTextColor(Color c)

Set the current color used to render the disabled text.

Parameters:

c - the color

public void replaceSelection(String content)

Replaces the currently selected content with new content represented by the given string. If there is no selection this amounts to an insert of the given text. If there is no replacement text this amounts to a removal of the current selection. This is the method that is used by the default implementation of the action for inserting content that gets bound to the keyboard.

Parameters:

content - the content to replace the selection with

public String getText(int offs,
                      int len) throws BadLocationException

Fetch a portion of the text represented by the component.

Parameters:

offs - the offset

len - the length

Returns:

the text

Throws: BadLocationException

of the offset or length are invalid

public Rectangle modelToView(int pos) throws BadLocationException

Converts the given location in the model to a place in the view coordinate system.

Parameters:

pos - the position

Returns:

the coordinates as a rectangle

Throws: BadLocationException

if the given position does not represent a valid location in the associated document

See Also:

modelToView

public int viewToModel(Point pt)

Converts the given place in the view coordinate system to the nearest representative location in the model.

Parameters:

pt - the location in the view to translate

Returns:

the offset from the start of the document

See Also:

viewToModel

public void cut()

Transfers the currently selected range in the associated text model to the system clipboard, removing the contents from the model. The current selection is reset.

public void copy()

Transfers the currently selected range in the associated text model to the system clipboard, leaving the contents in the text model. The current selection is remains intact.

public void paste()

Transfers the contents of the system clipboard into the associated text model. If there is a selection in the associated view, it is replaced with the contents of the clipboard. If there is no selection, the clipboard contents are inserted in front of the current insert position in the associated view.

See Also:

replaceSelection

public void moveCaretPosition(int pos)

Moves the caret to a new position, leaving behind a mark defined by the last time setCaretPosition was called. This forms a selection.

Parameters:

pos - the position

See Also:

setCaretPosition

public void read(Reader in,
                 Object desc) throws IOException

Initialize from a stream. This creates a model of the type appropriate for the component and initializes the model from the stream. By default this will load the model as plain text.

Parameters:

in - The stream to read from

desc - An object describing the stream. This might be a string, a File, a URL, etc. Some kinds of documents (such as html for example) might be able to make use of this information.

Throws: IOException

as thrown by the stream being used to initialize.

See Also:

#createDocument, setDocument

public void write(Writer out) throws IOException

Stores the contents of the model into the given stream. By default this will store the model as plain text.

Parameters:

out - the output stream

Throws: IOException

on any I/O error

public boolean isFocusTraversable()

Returns true if the focus can be traversed.

Returns:

true if the focus is traversable

Overrides:

isFocusTraversable in class JComponent

public void setCaretPosition(int position)

Sets the position of the text insertion caret for the TextComponent

Parameters:

position - the position

Throws: IllegalArgumentException

if position is less than 0 or greater than the length of the associated document

public int getCaretPosition()

Returns the position of the text insertion caret for the text component.

Returns:

the position of the text insertion caret for the text component

public void setText(String t)

Sets the text of this TextComponent to the specified text.

Parameters:

t - the new text to be set

See Also:

getText

public String getText()

Returns the text contained in this TextComponent.

Returns:

the text

See Also:

setText

public String getSelectedText()

Returns the selected text contained in this TextComponent.

Returns:

the text

Throws: IllegalArgumentException

if the selection doesn't have a valid mapping into the document for some reason

See Also:

setText

public boolean isEditable()

Returns the boolean indicating whether this TextComponent is editable or not.

Returns:

the boolean value

See Also:

setEditable

public void setEditable(boolean b)

Sets the specified boolean to indicate whether or not this TextComponent should be editable.

Parameters:

b - the boolean to be set

See Also:

isEditable

public int getSelectionStart()

Returns the selected text's start position.

Returns:

the start position

public void setSelectionStart(int selectionStart)

Sets the selection start to the specified position. The new starting point is constrained to be before or at the current selection end.

Parameters:

selectionStart - the start position of the text

public int getSelectionEnd()

Returns the selected text's end position.

Returns:

the end position

public void setSelectionEnd(int selectionEnd)

Sets the selection end to the specified position. The new end point is constrained to be at or after the current selection start.

Parameters:

selectionEnd - the start position of the text

public void select(int selectionStart,
                   int selectionEnd)

Selects the text found between the specified start and end locations. This call is provided for backward compatibility. It is routed to a call to setCaretPosition followed by a call to moveCaretPostion. The preferred way to manage selection is by calling those methods directly.

Parameters:

selectionStart - the start position of the text

selectionEnd - the end position of the text

See Also:

setCaretPosition, moveCaretPosition

public void selectAll()

Selects all the text in the TextComponent.

public void setFocusAccelerator(char aKey)

Sets the key accelerator that will cause the receiving text component to get the focus.

Parameters:

aKey - the key

public char getFocusAccelerator()

Returns the key accelerator that will cause the receiving text component to get the focus. Return '\0' if no focus accelerator has been set.

Returns:

the key

public Dimension getPreferredScrollableViewportSize()

Returns the preferred size of the viewport for a view component. This is implemented to do the default behavior of returning the preferred size of the component.

Returns:

The preferredSize of a JViewport whose view is this Scrollable.

See Also:

getPreferredSize

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)

Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation. Ideally, components should handle a partially exposed row or column by returning the distance required to completely expose the item.

The default implementation of this is to simply return 10% of the visible area. Subclasses are likely to be able to provide a much more reasonable value.

Parameters:

visibleRect - The view area visible within the viewport

orientation - Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.

direction - Less than zero to scroll up/left, greater than zero for down/right.

Returns:

The "unit" increment for scrolling in the specified direction

See Also:

setUnitIncrement

public int getScrollableBlockIncrement(Rectangle visibleRect,
                                       int orientation,
                                       int direction)

Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.

The default implementation of this is to simply return the visible area. Subclasses will likely be able to provide a much more reasonable value.

Parameters:

visibleRect - The view area visible within the viewport

orientation - Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.

direction - Less than zero to scroll up/left, greater than zero for down/right.

Returns:

The "block" increment for scrolling in the specified direction.

See Also:

setBlockIncrement

public boolean getScrollableTracksViewportWidth()

Return true if a viewport should always force the width of this Scrollable to match the width of the viewport. For example a noraml text view that supported line wrapping would return true here, since it would be undesirable for wrapped lines to disappear beyond the right edge of the viewport. Note that returning true for a Scrollable whose ancestor is a JScrollPane effectively disables horizontal scrolling.

Scrolling containers, like JViewport, will use this method each time they are validated.

Returns:

True if a viewport should force the Scrollables width to match its own.

public boolean getScrollableTracksViewportHeight()

Return true if a viewport should always force the height of this Scrollable to match the height of the viewport. For example a columnar text view that flowed text in left to right columns could effectively disable vertical scrolling by returning true here.

Scrolling containers, like JViewport, will use this method each time they are validated.

Returns:

True if a viewport should force the Scrollables height to match its own.

public AccessibleRole getAccessibleRole()

Gets the role of this object.

Returns:

an instance of AccessibleRole describing the role of the object

Overrides:

getAccessibleRole in class JComponent

See Also:

AccessibleRole

public AccessibleText getAccessibleText()

Gets the AccessibleText interface for the component.

Returns:

the AccessibleText of the object

Overrides:

getAccessibleText in class JComponent

See Also:

AccessibleText

public int getIndexAtPoint(Point p)

Given a point in local coordinates, returns the zero-based index of the character under that Point. If the point is invalid, this method returns -1.

Parameters:

p - the Point in screen coordinates

Returns:

the zero-based index of the character under Point p

public Rectangle getCharacterBounds(int i)

Given an index into the String, determines the bounding box of the character at that index. The bounds are returned in local coordinates. If the index is invalid, returns an empty rectangle.

Parameters:

i - the index into the String

Returns:

the bounding box, in screen coordinates, of the character

public int getCharCount()

Returns the number of characters (valid indices)

Returns:

the number of characters

public String getAtIndex(int part,
                         int index)

Return the String at a given index.

Parameters:

part - the CHARACTER, WORD, or SENTENCE to retrieve

index - an index within the text

Returns:

the letter, word, or sentence

public String getAfterIndex(int part,
                            int index)

Return the String after a given index.

Parameters:

part - the CHARACTER, WORD, or SENTENCE to retrieve

index - an index within the text

Returns:

the letter, word, or sentence

public String getBeforeIndex(int part,
                             int index)

Return the String before a given index.

Parameters:

part - the CHARACTER, WORD, or SENTENCE to retrieve

index - an index within the text

Returns:

the letter, word, or sentence

public AttributeSet getCharacterAttribute(int i)

Returns the AttributeSet for a given character (at a given index)

Parameters:

i - the zero-based index into the text

Returns:

the AttributeSet

All Packages  Class Hierarchy  This Package  Previous  Next  Index