java.awt
Class TextComponent

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.TextComponent
All Implemented Interfaces:
Accessible, java.awt.image.ImageObserver, MenuContainer, Serializable
Direct Known Subclasses:
TextArea, TextField

public class TextComponent
extends Component
implements Accessible

Unsafe: The TextComponent class is the superclass of any component that allows the editing of some text.

A text component embodies a string of text. The TextComponent class defines a set of methods that determine whether or not this text is editable. If the component is editable, it defines another set of methods that supports a text insertion caret.

In addition, the class defines methods that are used to maintain a current selection from the text. The text selection, a substring of the component's text, is the target of editing operations. It is also referred to as the selected text.

Since:
JDK1.0
Version:
1.71, 12/03/01
Author:
Sami Shaio, Arthur van Hoff
See Also:
Serialized Form

Field Summary
(package private)  boolean backgroundSetByClientCode
           
private  boolean canAccessClipboard
          True if this TextComponent has access to the System clipboard.
private  boolean checkForEnableIM
           
(package private)  boolean editable
          A boolean indicating whether or not this TextComponent is editable.
(package private)  int selectionEnd
          The selection refers to the selected text, and the selectionEnd is the end position of the selected text.
(package private)  int selectionStart
          The selection refers to the selected text, and the selectionStart is the start position of the selected text.
private static long serialVersionUID
           
(package private)  String text
          The value of the text.
private  int textComponentSerializedDataVersion
          The textComponent SerializedDataVersion.
protected  TextListener textListener
           
 
Fields inherited from class java.awt.Component
accessibleContext, actionListenerK, adjustmentListenerK, appContext, background, BOTTOM_ALIGNMENT, bufferStrategy, CENTER_ALIGNMENT, componentListener, componentListenerK, componentOrientation, containerListenerK, cursor, dropTarget, enabled, eventMask, focusListener, focusListenerK, focusTraversalKeys, font, foreground, graphicsConfig, height, hierarchyBoundsListener, hierarchyBoundsListenerK, hierarchyListener, hierarchyListenerK, ignoreRepaint, incRate, inputMethodListener, inputMethodListenerK, isInc, isPacked, itemListenerK, keyListener, keyListenerK, LEFT_ALIGNMENT, locale, LOCK, metrics, minSize, mouseListener, mouseListenerK, mouseMotionListener, mouseMotionListenerK, mouseWheelListener, mouseWheelListenerK, newEventsOnly, ownedWindowK, parent, peer, peerFont, popups, prefSize, RIGHT_ALIGNMENT, textListenerK, TOP_ALIGNMENT, valid, visible, width, windowClosingException, windowFocusListenerK, windowListenerK, windowStateListenerK, x, y
 
Constructor Summary
(package private) TextComponent(String text)
          Constructs a new text component initialized with the specified text.
 
Method Summary
 void addNotify()
          Suppressed: Makes this Component displayable by connecting it to a native screen resource.
 void addTextListener(TextListener l)
          Suppressed: Adds the specified text event listener to receive text events from this text component.
(package private)  boolean areInputMethodsEnabled()
           
private  void checkSystemClipboardAccess()
          Assigns a valid value to the canAccessClipboard instance variable.
 void enableInputMethods(boolean enable)
          Suppressed:
private  void enableInputMethodsIfNecessary()
           
(package private)  boolean eventEnabled(AWTEvent e)
           
 AccessibleContext getAccessibleContext()
          Suppressed: Gets the AccessibleContext associated with this TextComponent.
 Color getBackground()
          Suppressed: Gets the background color of this text component.
 int getCaretPosition()
          Suppressed: Gets the position of the text insertion caret for this text component.
(package private)  Rectangle getCharacterBounds(int i)
           
(package private)  int getIndexAtPoint(Point p)
           
 EventListener[] getListeners(Class listenerType)
          Suppressed: Returns an array of all the objects currently registered as FooListeners upon this TextComponent.
 String getSelectedText()
          Suppressed: Returns the selected text from the text that is presented by this text component.
 int getSelectionEnd()
          Suppressed: Gets the end position of the selected text in this text component.
 int getSelectionStart()
          Suppressed: Gets the start position of the selected text in this text component.
 String getText()
          Suppressed: Returns the text that is presented by this text component.
 TextListener[] getTextListeners()
          Suppressed: Returns an array of all the text listeners registered on this text component.
 boolean isEditable()
          Suppressed: Indicates whether or not this text component is editable.
protected  String paramString()
          Returns a string representing the state of this TextComponent.
protected  void processEvent(AWTEvent e)
          Processes events on this text component.
protected  void processTextEvent(TextEvent e)
          Processes text events occurring on this text component by dispatching them to any registered TextListener objects.
private  void readObject(ObjectInputStream s)
          Read the ObjectInputStream, and if it isn't null, add a listener to receive text events fired by the TextComponent.
 void removeNotify()
          Suppressed: Removes the TextComponent's peer.
 void removeTextListener(TextListener l)
          Suppressed: Removes the specified text event listener so that it no longer receives text events from this text component If l is null, no exception is thrown and no action is performed.
 void select(int selectionStart, int selectionEnd)
          Suppressed: Selects the text between the specified start and end positions.
 void selectAll()
          Suppressed: Selects all the text in this text component.
 void setBackground(Color c)
          Suppressed: Sets the background color of this text component.
 void setCaretPosition(int position)
          Suppressed: Sets the position of the text insertion caret for this text component.
 void setEditable(boolean b)
          Suppressed: Sets the flag that determines whether or not this text component is editable.
 void setSelectionEnd(int selectionEnd)
          Suppressed: Sets the selection end for this text component to the specified position.
 void setSelectionStart(int selectionStart)
          Suppressed: Sets the selection start for this text component to the specified position.
 void setText(String t)
          Suppressed: Sets the text that is presented by this text component to be the specified text.
private  void writeObject(ObjectOutputStream s)
          Writes default serializable fields to stream.
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, adjustListeningChildrenOnParent, applyComponentOrientation, areFocusTraversalKeysSet, autoProcessMouseWheel, autoTransferFocus, bounds, checkGD, checkImage, checkImage, checkWindowClosingException, clearCurrentFocusCycleRootOnHide, clearMostRecentFocusOwnerOnHide, coalesceEvents, constructComponentName, contains, contains, containsFocus, countHierarchyMembers, createBufferStrategy, createBufferStrategy, createChildHierarchyEvents, createHierarchyEvents, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, dispatchEventImpl, dispatchMouseWheelToAncestor, doLayout, enable, enable, enableEvents, eventTypeEnabled, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleIndexInParent, getAccessibleStateSet, getAlignmentX, getAlignmentY, getBackBuffer, getBounds, getBounds, getBufferStrategy, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys_NoIDCheck, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont_NoClientCode, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen_NoTreeLock, getLocationOnScreen, getMaximumSize, getMinimumSize, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getNativeContainer, getParent_NoClientCode, getParent, getPeer, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getToolkitImpl, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, initializeFocusTraversalKeys, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isEnabledImpl, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFocusTraversableOverridden, isFontSet, isForegroundSet, isLightweight, isOpaque, isRecursivelyVisible, isShowing, isValid, isVisible, iterate, keyDown, keyUp, layout, lightweightPaint, lightweightPrint, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, nextFocusHelper, numListening, paint, paintAll, paintHeavyweightComponents, postEvent, postsOldMouseEvents, preferredSize, prepareImage, prepareImage, print, printAll, printHeavyweightComponents, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusHelper, requestFocusInWindow, requestFocusInWindow, resetGC, reshape, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys_NoIDCheck, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setGCFromPeer, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocus, transferFocusBackward, transferFocusUpCycle, update, updateCursorImmediately, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

text

String text
The value of the text. A null value is the same as "".

See Also:
setText(), getText()

editable

boolean editable
A boolean indicating whether or not this TextComponent is editable. It will be true if the text component is editable and false if not.

See Also:
isEditable()

selectionStart

int selectionStart
The selection refers to the selected text, and the selectionStart is the start position of the selected text.

See Also:
getSelectionStart(), setSelectionStart()

selectionEnd

int selectionEnd
The selection refers to the selected text, and the selectionEnd is the end position of the selected text.

See Also:
getSelectionEnd(), setSelectionEnd()

backgroundSetByClientCode

boolean backgroundSetByClientCode

canAccessClipboard

private transient boolean canAccessClipboard
True if this TextComponent has access to the System clipboard.


textListener

protected transient TextListener textListener

serialVersionUID

private static final long serialVersionUID

textComponentSerializedDataVersion

private int textComponentSerializedDataVersion
The textComponent SerializedDataVersion.


checkForEnableIM

private boolean checkForEnableIM
Constructor Detail

TextComponent

TextComponent(String text)
        throws HeadlessException
Constructs a new text component initialized with the specified text. Sets the value of the cursor to Cursor.TEXT_CURSOR.

Parameters:
text - the text to be displayed; if text is null, the empty string "" will be displayed
See Also:
java.awt.GraphicsEnvironment#isHeadless, java.awt.Cursor
Method Detail

enableInputMethodsIfNecessary

private void enableInputMethodsIfNecessary()

enableInputMethods

public void enableInputMethods(boolean enable)
Suppressed:

Overrides:
enableInputMethods in class Component
Parameters:
enable - true to enable, false to disable
See Also:
Component.processKeyEvent(java.awt.event.KeyEvent)

areInputMethodsEnabled

boolean areInputMethodsEnabled()
Overrides:
areInputMethodsEnabled in class Component

addNotify

public void addNotify()
Suppressed: Makes this Component displayable by connecting it to a native screen resource. This method is called internally by the toolkit and should not be called directly by programs.

Overrides:
addNotify in class Component
See Also:
java.awt.TextComponent#removeNotify

removeNotify

public void removeNotify()
Suppressed: Removes the TextComponent's peer. The peer allows us to modify the appearance of the TextComponent without changing its functionality.

Overrides:
removeNotify in class Component
See Also:
Component.isDisplayable(), Component.addNotify()

setText

public void setText(String t)
Suppressed: Sets the text that is presented by this text component to be the specified text.

Parameters:
t - the new text; if this parameter is null then the text is set to the empty string ""
See Also:
java.awt.TextComponent#getText

getText

public String getText()
Suppressed: Returns the text that is presented by this text component.

See Also:
java.awt.TextComponent#setText

getSelectedText

public String getSelectedText()
Suppressed: Returns the selected text from the text that is presented by this text component.

Returns:
the selected text of this text component
See Also:
java.awt.TextComponent#select

isEditable

public boolean isEditable()
Suppressed: Indicates whether or not this text component is editable.

Returns:
true if this text component is editable; false otherwise.
Since:
JDK1.0
See Also:
java.awt.TextComponent#setEditable

setEditable

public void setEditable(boolean b)
Suppressed: Sets the flag that determines whether or not this text component is editable.

If the flag is set to true, this text component becomes user editable. If the flag is set to false, the user cannot change the text of this text component. By default, non-editable text components have a background color of SystemColor.control. This default can be overridden by calling setBackground.

Parameters:
b - a flag indicating whether this text component is user editable.
Since:
JDK1.0
See Also:
java.awt.TextComponent#isEditable

getBackground

public Color getBackground()
Suppressed: Gets the background color of this text component. By default, non-editable text components have a background color of SystemColor.control. This default can be overridden by calling setBackground.

Overrides:
getBackground in class Component
Returns:
This text component's background color. If this text component does not have a background color, the background color of its parent is returned.
Since:
JDK1.0
See Also:
setBackground

setBackground

public void setBackground(Color c)
Suppressed: Sets the background color of this text component.

Overrides:
setBackground in class Component
Parameters:
c - The color to become this text component's color. If this parameter is null then this text component will inherit the background color of its parent.
Since:
JDK1.0
See Also:
getBackground()

getSelectionStart

public int getSelectionStart()
Suppressed: Gets the start position of the selected text in this text component.

Returns:
the start position of the selected text
See Also:
java.awt.TextComponent#setSelectionStart, java.awt.TextComponent#getSelectionEnd

setSelectionStart

public void setSelectionStart(int selectionStart)
Suppressed: Sets the selection start for this text component to the specified position. The new start point is constrained to be at or before the current selection end. It also cannot be set to less than zero, the beginning of the component's text. If the caller supplies a value for selectionStart that is out of bounds, the method enforces these constraints silently, and without failure.

Parameters:
selectionStart - the start position of the selected text
Since:
JDK1.1
See Also:
java.awt.TextComponent#getSelectionStart, java.awt.TextComponent#setSelectionEnd

getSelectionEnd

public int getSelectionEnd()
Suppressed: Gets the end position of the selected text in this text component.

Returns:
the end position of the selected text
See Also:
java.awt.TextComponent#setSelectionEnd, java.awt.TextComponent#getSelectionStart

setSelectionEnd

public void setSelectionEnd(int selectionEnd)
Suppressed: Sets the selection end for this text component to the specified position. The new end point is constrained to be at or after the current selection start. It also cannot be set beyond the end of the component's text. If the caller supplies a value for selectionEnd that is out of bounds, the method enforces these constraints silently, and without failure.

Parameters:
selectionEnd - the end position of the selected text
Since:
JDK1.1
See Also:
java.awt.TextComponent#getSelectionEnd, java.awt.TextComponent#setSelectionStart

select

public void select(int selectionStart,
                   int selectionEnd)
Suppressed: Selects the text between the specified start and end positions.

This method sets the start and end positions of the selected text, enforcing the restriction that the start position must be greater than or equal to zero. The end position must be greater than or equal to the start position, and less than or equal to the length of the text component's text. The character positions are indexed starting with zero. The length of the selection is endPosition - startPosition, so the character at endPosition is not selected. If the start and end positions of the selected text are equal, all text is deselected.

If the caller supplies values that are inconsistent or out of bounds, the method enforces these constraints silently, and without failure. Specifically, if the start position or end position is greater than the length of the text, it is reset to equal the text length. If the start position is less than zero, it is reset to zero, and if the end position is less than the start position, it is reset to the start position.

Parameters:
selectionStart - the zero-based index of the first character to be selected
selectionEnd - the zero-based end position of the text to be selected; the character at selectionEnd is not selected
See Also:
java.awt.TextComponent#setSelectionStart, java.awt.TextComponent#setSelectionEnd, java.awt.TextComponent#selectAll

selectAll

public void selectAll()
Suppressed: Selects all the text in this text component.

See Also:
java.awt.TextComponent#select

setCaretPosition

public void setCaretPosition(int position)
Suppressed: Sets the position of the text insertion caret for this text component. The caret position is constrained to be at or before the current selection end. If the caller supplies a value for position that is greater than the end of the component's text, the caret position is set to the end of the component's text. This happens silently and without failure. The caret position also cannot be set to less than zero, the beginning of the component's text. If the caller supplies a value for position that is less than zero, an IllegalArgumentException is thrown.

Parameters:
position - the position of the text insertion caret
Since:
JDK1.1

getCaretPosition

public int getCaretPosition()
Suppressed: Gets the position of the text insertion caret for this text component.

Returns:
the position of the text insertion caret
Since:
JDK1.1

addTextListener

public void addTextListener(TextListener l)
Suppressed: Adds the specified text event listener to receive text events from this text component. If l is null, no exception is thrown and no action is performed.

Parameters:
l - the text event listener
See Also:
removeTextListener(java.awt.event.TextListener), getTextListeners(), java.awt.event.TextListener

removeTextListener

public void removeTextListener(TextListener l)
Suppressed: Removes the specified text event listener so that it no longer receives text events from this text component If l is null, no exception is thrown and no action is performed.

Parameters:
l - the text listener
Since:
JDK1.1
See Also:
addTextListener(java.awt.event.TextListener), getTextListeners(), java.awt.event.TextListener

getTextListeners

public TextListener[] getTextListeners()
Suppressed: Returns an array of all the text listeners registered on this text component.

Returns:
all of this text component's TextListeners or an empty array if no text listeners are currently registered
Since:
1.4
See Also:
addTextListener(java.awt.event.TextListener), removeTextListener(java.awt.event.TextListener)

getListeners

public EventListener[] getListeners(Class listenerType)
Suppressed: Returns an array of all the objects currently registered as FooListeners upon this TextComponent. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a TextComponent t for its text listeners with the following code:

TextListener[] tls = (TextListener[])(t.getListeners(TextListener.class));
If no such listeners exist, this method returns an empty array.

Overrides:
getListeners in class Component
Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this text component, or an empty array if no such listeners have been added
Since:
1.3
See Also:
getTextListeners()

eventEnabled

boolean eventEnabled(AWTEvent e)
Overrides:
eventEnabled in class Component

processEvent

protected void processEvent(AWTEvent e)
Processes events on this text component. If the event is a TextEvent, it invokes the processTextEvent method else it invokes its superclass's processEvent.

Note that if the event parameter is null the behavior is unspecified and may result in an exception.

Overrides:
processEvent in class Component
Parameters:
e - the event
See Also:
Component.processComponentEvent(java.awt.event.ComponentEvent), Component.processFocusEvent(java.awt.event.FocusEvent), Component.processKeyEvent(java.awt.event.KeyEvent), Component.processMouseEvent(java.awt.event.MouseEvent), Component.processMouseMotionEvent(java.awt.event.MouseEvent), Component.processInputMethodEvent(java.awt.event.InputMethodEvent), Component.processHierarchyEvent(java.awt.event.HierarchyEvent), Component.processMouseWheelEvent(java.awt.event.MouseWheelEvent)

processTextEvent

protected void processTextEvent(TextEvent e)
Processes text events occurring on this text component by dispatching them to any registered TextListener objects.

NOTE: This method will not be called unless text events are enabled for this component. This happens when one of the following occurs:

Note that if the event parameter is null the behavior is unspecified and may result in an exception.

Parameters:
e - the text event
See Also:
Component.enableEvents(long)

paramString

protected String paramString()
Returns a string representing the state of this TextComponent. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class Component
Returns:
the parameter string of this text component

checkSystemClipboardAccess

private void checkSystemClipboardAccess()
Assigns a valid value to the canAccessClipboard instance variable.


writeObject

private void writeObject(ObjectOutputStream s)
                  throws IOException
Writes default serializable fields to stream. Writes a list of serializable TextListener(s) as optional data. The non-serializable TextListener(s) are detected and no attempt is made to serialize them.

Parameters:
s - the ObjectOutputStream to write
IOException
See Also:
AWTEventMulticaster.save(ObjectOutputStream, String, EventListener), java.awt.Component.textListenerK

readObject

private void readObject(ObjectInputStream s)
                 throws ClassNotFoundException,
                        IOException,
                        HeadlessException
Read the ObjectInputStream, and if it isn't null, add a listener to receive text events fired by the TextComponent. Unrecognized keys or values will be ignored.

Parameters:
s - the ObjectInputStream to read
ClassNotFoundException
IOException
HeadlessException
See Also:
removeTextListener(), addTextListener(), java.awt.GraphicsEnvironment#isHeadless

getIndexAtPoint

int getIndexAtPoint(Point p)

getCharacterBounds

Rectangle getCharacterBounds(int i)

getAccessibleContext

public AccessibleContext getAccessibleContext()
Suppressed: Gets the AccessibleContext associated with this TextComponent. For text components, the AccessibleContext takes the form of an AccessibleAWTTextComponent. A new AccessibleAWTTextComponent instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class Component
Returns:
an AccessibleAWTTextComponent that serves as the AccessibleContext of this TextComponent


comments?