< prev index next >
src/java.desktop/share/classes/java/awt/TextField.java
Print this page
*** 32,47 ****
import java.io.IOException;
import javax.accessibility.*;
/**
! * A <code>TextField</code> object is a text component
* that allows for the editing of a single line of text.
* <p>
* For example, the following image depicts a frame with four
* text fields of varying widths. Two of these text fields
! * display the predefined text <code>"Hello"</code>.
* <p>
* <img src="doc-files/TextField-1.gif" alt="The preceding text describes this image."
* style="float:center; margin: 7px 10px;">
* <p>
* Here is the code that produces these four text fields:
--- 32,47 ----
import java.io.IOException;
import javax.accessibility.*;
/**
! * A {@code TextField} object is a text component
* that allows for the editing of a single line of text.
* <p>
* For example, the following image depicts a frame with four
* text fields of varying widths. Two of these text fields
! * display the predefined text {@code "Hello"}.
* <p>
* <img src="doc-files/TextField-1.gif" alt="The preceding text describes this image."
* style="float:center; margin: 7px 10px;">
* <p>
* Here is the code that produces these four text fields:
*** 57,87 ****
* // predefined text in 30 columns
* tf4 = new TextField("Hello", 30);
* </pre></blockquote><hr>
* <p>
* Every time the user types a key in the text field, one or
! * more key events are sent to the text field. A <code>KeyEvent</code>
* may be one of three types: keyPressed, keyReleased, or keyTyped.
* The properties of a key event indicate which of these types
* it is, as well as additional information about the event,
* such as what modifiers are applied to the key event and the
* time at which the event occurred.
* <p>
! * The key event is passed to every <code>KeyListener</code>
! * or <code>KeyAdapter</code> object which registered to receive such
! * events using the component's <code>addKeyListener</code> method.
! * (<code>KeyAdapter</code> objects implement the
! * <code>KeyListener</code> interface.)
* <p>
! * It is also possible to fire an <code>ActionEvent</code>.
* If action events are enabled for the text field, they may
! * be fired by pressing the <code>Return</code> key.
* <p>
! * The <code>TextField</code> class's <code>processEvent</code>
* method examines the action event and passes it along to
! * <code>processActionEvent</code>. The latter method redirects the
! * event to any <code>ActionListener</code> objects that have
* registered to receive action events generated by this
* text field.
*
* @author Sami Shaio
* @see java.awt.event.KeyEvent
--- 57,87 ----
* // predefined text in 30 columns
* tf4 = new TextField("Hello", 30);
* </pre></blockquote><hr>
* <p>
* Every time the user types a key in the text field, one or
! * more key events are sent to the text field. A {@code KeyEvent}
* may be one of three types: keyPressed, keyReleased, or keyTyped.
* The properties of a key event indicate which of these types
* it is, as well as additional information about the event,
* such as what modifiers are applied to the key event and the
* time at which the event occurred.
* <p>
! * The key event is passed to every {@code KeyListener}
! * or {@code KeyAdapter} object which registered to receive such
! * events using the component's {@code addKeyListener} method.
! * ({@code KeyAdapter} objects implement the
! * {@code KeyListener} interface.)
* <p>
! * It is also possible to fire an {@code ActionEvent}.
* If action events are enabled for the text field, they may
! * be fired by pressing the {@code Return} key.
* <p>
! * The {@code TextField} class's {@code processEvent}
* method examines the action event and passes it along to
! * {@code processActionEvent}. The latter method redirects the
! * event to any {@code ActionListener} objects that have
* registered to receive action events generated by this
* text field.
*
* @author Sami Shaio
* @see java.awt.event.KeyEvent
*** 110,120 ****
/**
* The echo character, which is used when
* the user wishes to disguise the characters
* typed into the text field.
! * The disguises are removed if echoChar = <code>0</code>.
*
* @serial
* @see #getEchoChar()
* @see #setEchoChar(char)
* @see #echoCharIsSet()
--- 110,120 ----
/**
* The echo character, which is used when
* the user wishes to disguise the characters
* typed into the text field.
! * The disguises are removed if echoChar = {@code 0}.
*
* @serial
* @see #getEchoChar()
* @see #setEchoChar(char)
* @see #echoCharIsSet()
*** 155,166 ****
}
/**
* Constructs a new text field initialized with the specified text.
* @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 GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
public TextField(String text) throws HeadlessException {
--- 155,166 ----
}
/**
* Constructs a new text field initialized with the specified text.
* @param text the text to be displayed. If
! * {@code text} is {@code null}, the empty
! * string {@code ""} will be displayed.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
public TextField(String text) throws HeadlessException {
*** 170,181 ****
/**
* Constructs a new empty text field with the specified number
* of columns. A column is an approximate average character
* width that is platform-dependent.
* @param columns the number of columns. If
! * <code>columns</code> is less than <code>0</code>,
! * <code>columns</code> is set to <code>0</code>.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
public TextField(int columns) throws HeadlessException {
--- 170,181 ----
/**
* Constructs a new empty text field with the specified number
* of columns. A column is an approximate average character
* width that is platform-dependent.
* @param columns the number of columns. If
! * {@code columns} is less than {@code 0},
! * {@code columns} is set to {@code 0}.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
public TextField(int columns) throws HeadlessException {
*** 186,200 ****
* Constructs a new text field initialized with the specified text
* to be displayed, and wide enough to hold the specified
* number of columns. A column is an approximate average character
* width that is platform-dependent.
* @param text the text to be displayed. If
! * <code>text</code> is <code>null</code>, the empty
! * string <code>""</code> will be displayed.
* @param columns the number of columns. If
! * <code>columns</code> is less than <code>0</code>,
! * <code>columns</code> is set to <code>0</code>.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
public TextField(String text, int columns) throws HeadlessException {
--- 186,200 ----
* Constructs a new text field initialized with the specified text
* to be displayed, and wide enough to hold the specified
* number of columns. A column is an approximate average character
* width that is platform-dependent.
* @param text the text to be displayed. If
! * {@code text} is {@code null}, the empty
! * string {@code ""} will be displayed.
* @param columns the number of columns. If
! * {@code columns} is less than {@code 0},
! * {@code columns} is set to {@code 0}.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
public TextField(String text, int columns) throws HeadlessException {
*** 228,238 ****
* Gets the character that is to be used for echoing.
* <p>
* An echo character is useful for text fields where
* user input should not be echoed to the screen, as in
* the case of a text field for entering a password.
! * If <code>echoChar</code> = <code>0</code>, user
* input is echoed to the screen unchanged.
* <p>
* A Java platform implementation may support only a limited,
* non-empty set of echo characters. This function returns the
* echo character originally requested via setEchoChar(). The echo
--- 228,238 ----
* Gets the character that is to be used for echoing.
* <p>
* An echo character is useful for text fields where
* user input should not be echoed to the screen, as in
* the case of a text field for entering a password.
! * If {@code echoChar} = {@code 0}, user
* input is echoed to the screen unchanged.
* <p>
* A Java platform implementation may support only a limited,
* non-empty set of echo characters. This function returns the
* echo character originally requested via setEchoChar(). The echo
*** 250,260 ****
* Sets the echo character for this text field.
* <p>
* An echo character is useful for text fields where
* user input should not be echoed to the screen, as in
* the case of a text field for entering a password.
! * Setting <code>echoChar</code> = <code>0</code> allows
* user input to be echoed to the screen again.
* <p>
* A Java platform implementation may support only a limited,
* non-empty set of echo characters. Attempts to set an
* unsupported echo character will cause the default echo
--- 250,260 ----
* Sets the echo character for this text field.
* <p>
* An echo character is useful for text fields where
* user input should not be echoed to the screen, as in
* the case of a text field for entering a password.
! * Setting {@code echoChar} = {@code 0} allows
* user input to be echoed to the screen again.
* <p>
* A Java platform implementation may support only a limited,
* non-empty set of echo characters. Attempts to set an
* unsupported echo character will cause the default echo
*** 275,285 ****
* Sets the character to be echoed when protected input is displayed.
*
* @param c the echo character for this text field
*
* @deprecated As of JDK version 1.1,
! * replaced by <code>setEchoChar(char)</code>.
*/
@Deprecated
public synchronized void setEchoCharacter(char c) {
if (echoChar != c) {
echoChar = c;
--- 275,285 ----
* Sets the character to be echoed when protected input is displayed.
*
* @param c the echo character for this text field
*
* @deprecated As of JDK version 1.1,
! * replaced by {@code setEchoChar(char)}.
*/
@Deprecated
public synchronized void setEchoCharacter(char c) {
if (echoChar != c) {
echoChar = c;
*** 308,320 ****
* character set for echoing.
* <p>
* An echo character is useful for text fields where
* user input should not be echoed to the screen, as in
* the case of a text field for entering a password.
! * @return <code>true</code> if this text field has
* a character set for echoing;
! * <code>false</code> otherwise.
* @see java.awt.TextField#setEchoChar
* @see java.awt.TextField#getEchoChar
*/
public boolean echoCharIsSet() {
return echoChar != 0;
--- 308,320 ----
* character set for echoing.
* <p>
* An echo character is useful for text fields where
* user input should not be echoed to the screen, as in
* the case of a text field for entering a password.
! * @return {@code true} if this text field has
* a character set for echoing;
! * {@code false} otherwise.
* @see java.awt.TextField#setEchoChar
* @see java.awt.TextField#getEchoChar
*/
public boolean echoCharIsSet() {
return echoChar != 0;
*** 335,346 ****
* Sets the number of columns in this text field. A column is an
* approximate average character width that is platform-dependent.
* @param columns the number of columns.
* @see java.awt.TextField#getColumns
* @exception IllegalArgumentException if the value
! * supplied for <code>columns</code>
! * is less than <code>0</code>.
* @since 1.1
*/
public void setColumns(int columns) {
int oldVal;
synchronized (this) {
--- 335,346 ----
* Sets the number of columns in this text field. A column is an
* approximate average character width that is platform-dependent.
* @param columns the number of columns.
* @see java.awt.TextField#getColumns
* @exception IllegalArgumentException if the value
! * supplied for {@code columns}
! * is less than {@code 0}.
* @since 1.1
*/
public void setColumns(int columns) {
int oldVal;
synchronized (this) {
*** 377,387 ****
*
* @param columns the number of columns
* @return the preferred size for the text field
*
* @deprecated As of JDK version 1.1,
! * replaced by <code>getPreferredSize(int)</code>.
*/
@Deprecated
public Dimension preferredSize(int columns) {
synchronized (getTreeLock()) {
TextFieldPeer peer = (TextFieldPeer)this.peer;
--- 377,387 ----
*
* @param columns the number of columns
* @return the preferred size for the text field
*
* @deprecated As of JDK version 1.1,
! * replaced by {@code getPreferredSize(int)}.
*/
@Deprecated
public Dimension preferredSize(int columns) {
synchronized (getTreeLock()) {
TextFieldPeer peer = (TextFieldPeer)this.peer;
*** 401,411 ****
return preferredSize();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by <code>getPreferredSize()</code>.
*/
@Deprecated
public Dimension preferredSize() {
synchronized (getTreeLock()) {
return (columns > 0) ?
--- 401,411 ----
return preferredSize();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by {@code getPreferredSize()}.
*/
@Deprecated
public Dimension preferredSize() {
synchronized (getTreeLock()) {
return (columns > 0) ?
*** 431,441 ****
* the specified number of columns.
*
* @param columns the number of columns
* @return the minimum size for this text field
* @deprecated As of JDK version 1.1,
! * replaced by <code>getMinimumSize(int)</code>.
*/
@Deprecated
public Dimension minimumSize(int columns) {
synchronized (getTreeLock()) {
TextFieldPeer peer = (TextFieldPeer)this.peer;
--- 431,441 ----
* the specified number of columns.
*
* @param columns the number of columns
* @return the minimum size for this text field
* @deprecated As of JDK version 1.1,
! * replaced by {@code getMinimumSize(int)}.
*/
@Deprecated
public Dimension minimumSize(int columns) {
synchronized (getTreeLock()) {
TextFieldPeer peer = (TextFieldPeer)this.peer;
*** 455,465 ****
return minimumSize();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by <code>getMinimumSize()</code>.
*/
@Deprecated
public Dimension minimumSize() {
synchronized (getTreeLock()) {
return (columns > 0) ?
--- 455,465 ----
return minimumSize();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by {@code getMinimumSize()}.
*/
@Deprecated
public Dimension minimumSize() {
synchronized (getTreeLock()) {
return (columns > 0) ?
*** 511,521 ****
/**
* Returns an array of all the action listeners
* registered on this textfield.
*
! * @return all of this textfield's <code>ActionListener</code>s
* or an empty array if no action
* listeners are currently registered
*
* @see #addActionListener
* @see #removeActionListener
--- 511,521 ----
/**
* Returns an array of all the action listeners
* registered on this textfield.
*
! * @return all of this textfield's {@code ActionListener}s
* or an empty array if no action
* listeners are currently registered
*
* @see #addActionListener
* @see #removeActionListener
*** 527,562 ****
}
/**
* Returns an array of all the objects currently registered
* as <code><em>Foo</em>Listener</code>s
! * upon this <code>TextField</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>TextField</code> <code>t</code>
* for its action listeners with the following code:
*
* <pre>ActionListener[] als = (ActionListener[])(t.getListeners(ActionListener.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 textfield,
* 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 #getActionListeners
* @since 1.3
*/
public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
--- 527,562 ----
}
/**
* Returns an array of all the objects currently registered
* as <code><em>Foo</em>Listener</code>s
! * upon this {@code TextField}.
* <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 TextField t}
* for its action listeners with the following code:
*
* <pre>ActionListener[] als = (ActionListener[])(t.getListeners(ActionListener.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 textfield,
* 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 #getActionListeners
* @since 1.3
*/
public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
*** 581,595 ****
return super.eventEnabled(e);
}
/**
* Processes events on this text field. If the event
! * is an instance of <code>ActionEvent</code>,
! * it invokes the <code>processActionEvent</code>
! * method. Otherwise, it invokes <code>processEvent</code>
* on the superclass.
! * <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
* @see java.awt.event.ActionEvent
--- 581,595 ----
return super.eventEnabled(e);
}
/**
* Processes events on this text field. If the event
! * is an instance of {@code ActionEvent},
! * it invokes the {@code processActionEvent}
! * method. Otherwise, it invokes {@code processEvent}
* on the superclass.
! * <p>Note that if the event parameter is {@code null}
* the behavior is unspecified and may result in an
* exception.
*
* @param e the event
* @see java.awt.event.ActionEvent
*** 605,625 ****
}
/**
* Processes action events occurring on this text field by
* dispatching them to any registered
! * <code>ActionListener</code> objects.
* <p>
* This method is not called unless action events are
* enabled for this component. Action events are enabled
* when one of the following occurs:
* <ul>
! * <li>An <code>ActionListener</code> object is registered
! * via <code>addActionListener</code>.
! * <li>Action 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 action event
* @see java.awt.event.ActionListener
--- 605,625 ----
}
/**
* Processes action events occurring on this text field by
* dispatching them to any registered
! * {@code ActionListener} objects.
* <p>
* This method is not called unless action events are
* enabled for this component. Action events are enabled
* when one of the following occurs:
* <ul>
! * <li>An {@code ActionListener} object is registered
! * via {@code addActionListener}.
! * <li>Action 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 action event
* @see java.awt.event.ActionListener
*** 633,647 ****
listener.actionPerformed(e);
}
}
/**
! * Returns a string representing the state of this <code>TextField</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 field
*/
protected String paramString() {
String str = super.paramString();
--- 633,647 ----
listener.actionPerformed(e);
}
}
/**
! * Returns a string representing the state of this {@code TextField}.
* 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 field
*/
protected String paramString() {
String str = super.paramString();
*** 691,702 ****
* add a listener to receive action events fired by the
* TextField. Unrecognized keys or values will be
* ignored.
*
* @exception HeadlessException if
! * <code>GraphicsEnvironment.isHeadless()</code> returns
! * <code>true</code>
* @see #removeActionListener(ActionListener)
* @see #addActionListener(ActionListener)
* @see java.awt.GraphicsEnvironment#isHeadless
*/
private void readObject(ObjectInputStream s)
--- 691,702 ----
* add a listener to receive action events fired by the
* TextField. Unrecognized keys or values will be
* ignored.
*
* @exception HeadlessException if
! * {@code GraphicsEnvironment.isHeadless()} returns
! * {@code true}
* @see #removeActionListener(ActionListener)
* @see #addActionListener(ActionListener)
* @see java.awt.GraphicsEnvironment#isHeadless
*/
private void readObject(ObjectInputStream s)
*** 747,757 ****
return accessibleContext;
}
/**
* This class implements accessibility support for the
! * <code>TextField</code> class. It provides an implementation of the
* Java Accessibility API appropriate to text field user-interface elements.
* @since 1.3
*/
protected class AccessibleAWTTextField extends AccessibleAWTTextComponent
{
--- 747,757 ----
return accessibleContext;
}
/**
* This class implements accessibility support for the
! * {@code TextField} class. It provides an implementation of the
* Java Accessibility API appropriate to text field user-interface elements.
* @since 1.3
*/
protected class AccessibleAWTTextField extends AccessibleAWTTextComponent
{
< prev index next >