< prev index next >
src/java.desktop/share/classes/java/awt/TextComponent.java
Print this page
*** 36,50 ****
import java.awt.im.InputMethodRequests;
import sun.awt.AWTPermissions;
import sun.awt.InputMethodSupport;
/**
! * The <code>TextComponent</code> class is the superclass of
* any component that allows the editing of some text.
* <p>
* A text component embodies a string of text. The
! * <code>TextComponent</code> 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.
* <p>
* In addition, the class defines methods that are used
--- 36,50 ----
import java.awt.im.InputMethodRequests;
import sun.awt.AWTPermissions;
import sun.awt.InputMethodSupport;
/**
! * The {@code TextComponent} class is the superclass of
* any component that allows the editing of some text.
* <p>
* A text component embodies a string of text. The
! * {@code 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.
* <p>
* In addition, the class defines methods that are used
*** 59,101 ****
*/
public class TextComponent extends Component implements Accessible {
/**
* The value of the text.
! * A <code>null</code> value is the same as "".
*
* @serial
* @see #setText(String)
* @see #getText()
*/
String text;
/**
* A boolean indicating whether or not this
! * <code>TextComponent</code> is editable.
! * It will be <code>true</code> if the text component
! * is editable and <code>false</code> if not.
*
* @serial
* @see #isEditable()
*/
boolean editable = true;
/**
* The selection refers to the selected text, and the
! * <code>selectionStart</code> is the start position
* of the selected text.
*
* @serial
* @see #getSelectionStart()
* @see #setSelectionStart(int)
*/
int selectionStart;
/**
* The selection refers to the selected text, and the
! * <code>selectionEnd</code>
* is the end position of the selected text.
*
* @serial
* @see #getSelectionEnd()
* @see #setSelectionEnd(int)
--- 59,101 ----
*/
public class TextComponent extends Component implements Accessible {
/**
* The value of the text.
! * A {@code null} value is the same as "".
*
* @serial
* @see #setText(String)
* @see #getText()
*/
String text;
/**
* A boolean indicating whether or not this
! * {@code TextComponent} is editable.
! * It will be {@code true} if the text component
! * is editable and {@code false} if not.
*
* @serial
* @see #isEditable()
*/
boolean editable = true;
/**
* The selection refers to the selected text, and the
! * {@code selectionStart} is the start position
* of the selected text.
*
* @serial
* @see #getSelectionStart()
* @see #setSelectionStart(int)
*/
int selectionStart;
/**
* The selection refers to the selected text, and the
! * {@code selectionEnd}
* is the end position of the selected text.
*
* @serial
* @see #getSelectionEnd()
* @see #setSelectionEnd(int)
*** 118,133 ****
private static final long serialVersionUID = -2214773872412987419L;
/**
* Constructs a new text component initialized with the
* specified text. Sets the value of the cursor to
! * <code>Cursor.TEXT_CURSOR</code>.
* @param text the text to be displayed; if
! * <code>text</code> is <code>null</code>, the empty
! * string <code>""</code> will be displayed
* @exception HeadlessException if
! * <code>GraphicsEnvironment.isHeadless</code>
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @see java.awt.Cursor
*/
TextComponent(String text) throws HeadlessException {
--- 118,133 ----
private static final long serialVersionUID = -2214773872412987419L;
/**
* Constructs a new text component initialized with the
* specified text. Sets the value of the cursor to
! * {@code Cursor.TEXT_CURSOR}.
* @param text the text to be displayed; if
! * {@code text} is {@code null}, the empty
! * string {@code ""} will be displayed
* @exception HeadlessException if
! * {@code GraphicsEnvironment.isHeadless}
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @see java.awt.Cursor
*/
TextComponent(String text) throws HeadlessException {
*** 201,213 ****
super.addNotify();
enableInputMethodsIfNecessary();
}
/**
! * Removes the <code>TextComponent</code>'s peer.
* The peer allows us to modify the appearance of the
! * <code>TextComponent</code> without changing its
* functionality.
*/
public void removeNotify() {
synchronized (getTreeLock()) {
TextComponentPeer peer = (TextComponentPeer)this.peer;
--- 201,213 ----
super.addNotify();
enableInputMethodsIfNecessary();
}
/**
! * Removes the {@code TextComponent}'s peer.
* The peer allows us to modify the appearance of the
! * {@code TextComponent} without changing its
* functionality.
*/
public void removeNotify() {
synchronized (getTreeLock()) {
TextComponentPeer peer = (TextComponentPeer)this.peer;
*** 222,232 ****
/**
* Sets the text that is presented by this
* text component to be the specified text.
* @param t the new text;
! * if this parameter is <code>null</code> then
* the text is set to the empty string ""
* @see java.awt.TextComponent#getText
*/
public synchronized void setText(String t) {
boolean skipTextEvent = (text == null || text.isEmpty())
--- 222,232 ----
/**
* Sets the text that is presented by this
* text component to be the specified text.
* @param t the new text;
! * if this parameter is {@code null} then
* the text is set to the empty string ""
* @see java.awt.TextComponent#getText
*/
public synchronized void setText(String t) {
boolean skipTextEvent = (text == null || text.isEmpty())
*** 243,253 ****
/**
* Returns the text that is presented by this text component.
* By default, this is an empty string.
*
! * @return the value of this <code>TextComponent</code>
* @see java.awt.TextComponent#setText
*/
public synchronized String getText() {
TextComponentPeer peer = (TextComponentPeer)this.peer;
if (peer != null) {
--- 243,253 ----
/**
* Returns the text that is presented by this text component.
* By default, this is an empty string.
*
! * @return the value of this {@code TextComponent}
* @see java.awt.TextComponent#setText
*/
public synchronized String getText() {
TextComponentPeer peer = (TextComponentPeer)this.peer;
if (peer != null) {
*** 266,277 ****
return getText().substring(getSelectionStart(), getSelectionEnd());
}
/**
* Indicates whether or not this text component is editable.
! * @return <code>true</code> if this text component is
! * editable; <code>false</code> otherwise.
* @see java.awt.TextComponent#setEditable
* @since 1.0
*/
public boolean isEditable() {
return editable;
--- 266,277 ----
return getText().substring(getSelectionStart(), getSelectionEnd());
}
/**
* Indicates whether or not this text component is editable.
! * @return {@code true} if this text component is
! * editable; {@code false} otherwise.
* @see java.awt.TextComponent#setEditable
* @since 1.0
*/
public boolean isEditable() {
return editable;
*** 279,290 ****
/**
* Sets the flag that determines whether or not this
* text component is editable.
* <p>
! * If the flag is set to <code>true</code>, this text component
! * becomes user editable. If the flag is set to <code>false</code>,
* 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.
*
--- 279,290 ----
/**
* Sets the flag that determines whether or not this
* text component is editable.
* <p>
! * If the flag is set to {@code true}, this text component
! * becomes user editable. If the flag is set to {@code 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.
*
*** 359,369 ****
* 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 <code>selectionStart</code>
* that is out of bounds, the method enforces these constraints
* silently, and without failure.
* @param selectionStart the start position of the
* selected text
* @see java.awt.TextComponent#getSelectionStart
--- 359,369 ----
* 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 {@code selectionStart}
* that is out of bounds, the method enforces these constraints
* silently, and without failure.
* @param selectionStart the start position of the
* selected text
* @see java.awt.TextComponent#getSelectionStart
*** 395,405 ****
/**
* 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 <code>selectionEnd</code>
* that is out of bounds, the method enforces these constraints
* silently, and without failure.
* @param selectionEnd the end position of the
* selected text
* @see java.awt.TextComponent#getSelectionEnd
--- 395,405 ----
/**
* 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 {@code selectionEnd}
* that is out of bounds, the method enforces these constraints
* silently, and without failure.
* @param selectionEnd the end position of the
* selected text
* @see java.awt.TextComponent#getSelectionEnd
*** 421,432 ****
* 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
! * <code>endPosition</code> - <code>startPosition</code>, so the
! * character at <code>endPosition</code> is not selected.
* If the start and end positions of the selected text are equal,
* all text is deselected.
* <p>
* If the caller supplies values that are inconsistent or out of
* bounds, the method enforces these constraints silently, and
--- 421,432 ----
* 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
! * {@code endPosition} - {@code startPosition}, so the
! * character at {@code endPosition} is not selected.
* If the start and end positions of the selected text are equal,
* all text is deselected.
* <p>
* If the caller supplies values that are inconsistent or out of
* bounds, the method enforces these constraints silently, and
*** 435,448 ****
* 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.
*
* @param selectionStart the zero-based index of the first
! character (<code>char</code> value) to be selected
* @param selectionEnd the zero-based end position of the
! text to be selected; the character (<code>char</code> value) at
! <code>selectionEnd</code> is not selected
* @see java.awt.TextComponent#setSelectionStart
* @see java.awt.TextComponent#setSelectionEnd
* @see java.awt.TextComponent#selectAll
*/
public synchronized void select(int selectionStart, int selectionEnd) {
--- 435,448 ----
* 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.
*
* @param selectionStart the zero-based index of the first
! * character ({@code char} value) to be selected
* @param selectionEnd the zero-based end position of the
! * text to be selected; the character ({@code char} value) at
! * {@code selectionEnd} is not selected
* @see java.awt.TextComponent#setSelectionStart
* @see java.awt.TextComponent#setSelectionEnd
* @see java.awt.TextComponent#selectAll
*/
public synchronized void select(int selectionStart, int selectionEnd) {
*** 487,503 ****
* Sets the position of the text insertion caret.
* The caret position is constrained to be between 0
* and the last character of the text, inclusive.
* If the passed-in value is greater than this range,
* the value is set to the last character (or 0 if
! * the <code>TextComponent</code> contains no text)
* and no error is returned. If the passed-in value is
! * less than 0, an <code>IllegalArgumentException</code>
* is thrown.
*
* @param position the position of the text insertion caret
! * @exception IllegalArgumentException if <code>position</code>
* is less than zero
* @since 1.1
*/
public synchronized void setCaretPosition(int position) {
if (position < 0) {
--- 487,503 ----
* Sets the position of the text insertion caret.
* The caret position is constrained to be between 0
* and the last character of the text, inclusive.
* If the passed-in value is greater than this range,
* the value is set to the last character (or 0 if
! * the {@code TextComponent} contains no text)
* and no error is returned. If the passed-in value is
! * less than 0, an {@code IllegalArgumentException}
* is thrown.
*
* @param position the position of the text insertion caret
! * @exception IllegalArgumentException if {@code position}
* is less than zero
* @since 1.1
*/
public synchronized void setCaretPosition(int position) {
if (position < 0) {
*** 545,555 ****
}
/**
* Adds the specified text event listener to receive text events
* from this text component.
! * If <code>l</code> is <code>null</code>, no exception is
* thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the text event listener
--- 545,555 ----
}
/**
* Adds the specified text event listener to receive text events
* from this text component.
! * If {@code l} is {@code null}, no exception is
* thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the text event listener
*** 566,576 ****
}
/**
* Removes the specified text event listener so that it no longer
* receives text events from this text component
! * If <code>l</code> is <code>null</code>, no exception is
* thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the text listener
--- 566,576 ----
}
/**
* Removes the specified text event listener so that it no longer
* receives text events from this text component
! * If {@code l} is {@code null}, no exception is
* thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the text listener
*** 588,598 ****
/**
* Returns an array of all the text listeners
* registered on this text component.
*
! * @return all of this text component's <code>TextListener</code>s
* or an empty array if no text
* listeners are currently registered
*
*
* @see #addTextListener
--- 588,598 ----
/**
* Returns an array of all the text listeners
* registered on this text component.
*
! * @return all of this text component's {@code TextListener}s
* or an empty array if no text
* listeners are currently registered
*
*
* @see #addTextListener
*** 604,639 ****
}
/**
* Returns an array of all the objects currently registered
* as <code><em>Foo</em>Listener</code>s
! * upon this <code>TextComponent</code>.
* <code><em>Foo</em>Listener</code>s are registered using the
* <code>add<em>Foo</em>Listener</code> method.
*
* <p>
! * You can specify the <code>listenerType</code> argument
* with a class literal, such as
* <code><em>Foo</em>Listener.class</code>.
* For example, you can query a
! * <code>TextComponent</code> <code>t</code>
* for its text listeners with the following code:
*
* <pre>TextListener[] tls = (TextListener[])(t.getListeners(TextListener.class));</pre>
*
* If no such listeners exist, this method returns an empty array.
*
* @param listenerType the type of listeners requested; this parameter
* should specify an interface that descends from
! * <code>java.util.EventListener</code>
* @return an array of all objects registered as
* <code><em>Foo</em>Listener</code>s on this text component,
* or an empty array if no such
* listeners have been added
! * @exception ClassCastException if <code>listenerType</code>
* doesn't specify a class or interface that implements
! * <code>java.util.EventListener</code>
*
* @see #getTextListeners
* @since 1.3
*/
public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
--- 604,639 ----
}
/**
* Returns an array of all the objects currently registered
* as <code><em>Foo</em>Listener</code>s
! * upon this {@code TextComponent}.
* <code><em>Foo</em>Listener</code>s are registered using the
* <code>add<em>Foo</em>Listener</code> method.
*
* <p>
! * You can specify the {@code listenerType} argument
* with a class literal, such as
* <code><em>Foo</em>Listener.class</code>.
* For example, you can query a
! * {@code TextComponent t}
* for its text listeners with the following code:
*
* <pre>TextListener[] tls = (TextListener[])(t.getListeners(TextListener.class));</pre>
*
* If no such listeners exist, this method returns an empty array.
*
* @param listenerType the type of listeners requested; this parameter
* should specify an interface that descends from
! * {@code java.util.EventListener}
* @return an array of all objects registered as
* <code><em>Foo</em>Listener</code>s on this text component,
* or an empty array if no such
* listeners have been added
! * @exception ClassCastException if {@code listenerType}
* doesn't specify a class or interface that implements
! * {@code java.util.EventListener}
*
* @see #getTextListeners
* @since 1.3
*/
public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
*** 658,670 ****
return super.eventEnabled(e);
}
/**
* Processes events on this text component. If the event is a
! * <code>TextEvent</code>, it invokes the <code>processTextEvent</code>
! * method else it invokes its superclass's <code>processEvent</code>.
! * <p>Note that if the event parameter is <code>null</code>
* the behavior is unspecified and may result in an
* exception.
*
* @param e the event
*/
--- 658,670 ----
return super.eventEnabled(e);
}
/**
* Processes events on this text component. If the event is a
! * {@code TextEvent}, it invokes the {@code processTextEvent}
! * method else it invokes its superclass's {@code processEvent}.
! * <p>Note that if the event parameter is {@code null}
* the behavior is unspecified and may result in an
* exception.
*
* @param e the event
*/
*** 676,696 ****
super.processEvent(e);
}
/**
* Processes text events occurring on this text component by
! * dispatching them to any registered <code>TextListener</code> objects.
* <p>
* NOTE: This method will not be called unless text events
* are enabled for this component. This happens when one of the
* following occurs:
* <ul>
! * <li>A <code>TextListener</code> object is registered
! * via <code>addTextListener</code>
! * <li>Text events are enabled via <code>enableEvents</code>
* </ul>
! * <p>Note that if the event parameter is <code>null</code>
* the behavior is unspecified and may result in an
* exception.
*
* @param e the text event
* @see Component#enableEvents
--- 676,696 ----
super.processEvent(e);
}
/**
* Processes text events occurring on this text component by
! * dispatching them to any registered {@code TextListener} objects.
* <p>
* NOTE: This method will not be called unless text events
* are enabled for this component. This happens when one of the
* following occurs:
* <ul>
! * <li>A {@code TextListener} object is registered
! * via {@code addTextListener}
! * <li>Text events are enabled via {@code enableEvents}
* </ul>
! * <p>Note that if the event parameter is {@code null}
* the behavior is unspecified and may result in an
* exception.
*
* @param e the text event
* @see Component#enableEvents
*** 707,721 ****
}
}
/**
* Returns a string representing the state of this
! * <code>TextComponent</code>. 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
! * <code>null</code>.
*
* @return the parameter string of this text component
*/
protected String paramString() {
String str = super.paramString() + ",text=" + getText();
--- 707,721 ----
}
}
/**
* Returns a string representing the state of this
! * {@code 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
! * {@code null}.
*
* @return the parameter string of this text component
*/
protected String paramString() {
String str = super.paramString() + ",text=" + getText();
*** 787,798 ****
* add a listener to receive text events fired by the
* TextComponent. Unrecognized keys or values will be
* ignored.
*
* @exception HeadlessException if
! * <code>GraphicsEnvironment.isHeadless()</code> returns
! * <code>true</code>
* @see #removeTextListener
* @see #addTextListener
* @see java.awt.GraphicsEnvironment#isHeadless
*/
private void readObject(ObjectInputStream s)
--- 787,798 ----
* add a listener to receive text events fired by the
* TextComponent. Unrecognized keys or values will be
* ignored.
*
* @exception HeadlessException if
! * {@code GraphicsEnvironment.isHeadless()} returns
! * {@code true}
* @see #removeTextListener
* @see #addTextListener
* @see java.awt.GraphicsEnvironment#isHeadless
*/
private void readObject(ObjectInputStream s)
*** 842,852 ****
return accessibleContext;
}
/**
* This class implements accessibility support for the
! * <code>TextComponent</code> class. It provides an implementation of the
* Java Accessibility API appropriate to text component user-interface
* elements.
* @since 1.3
*/
protected class AccessibleAWTTextComponent extends AccessibleAWTComponent
--- 842,852 ----
return accessibleContext;
}
/**
* This class implements accessibility support for the
! * {@code TextComponent} class. It provides an implementation of the
* Java Accessibility API appropriate to text component user-interface
* elements.
* @since 1.3
*/
protected class AccessibleAWTTextComponent extends AccessibleAWTComponent
< prev index next >