001 /*
002 * Copyright 1995-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package java.awt;
026
027 import java.awt.peer.TextFieldPeer;
028 import java.awt.event.*;
029 import java.util.EventListener;
030 import java.io.ObjectOutputStream;
031 import java.io.ObjectInputStream;
032 import java.io.IOException;
033 import javax.accessibility.*;
034
035 /**
036 * A <code>TextField</code> object is a text component
037 * that allows for the editing of a single line of text.
038 * <p>
039 * For example, the following image depicts a frame with four
040 * text fields of varying widths. Two of these text fields
041 * display the predefined text <code>"Hello"</code>.
042 * <p>
043 * <img src="doc-files/TextField-1.gif" alt="The preceding text describes this image."
044 * ALIGN=center HSPACE=10 VSPACE=7>
045 * <p>
046 * Here is the code that produces these four text fields:
047 * <p>
048 * <hr><blockquote><pre>
049 * TextField tf1, tf2, tf3, tf4;
050 * // a blank text field
051 * tf1 = new TextField();
052 * // blank field of 20 columns
053 * tf2 = new TextField("", 20);
054 * // predefined text displayed
055 * tf3 = new TextField("Hello!");
056 * // predefined text in 30 columns
057 * tf4 = new TextField("Hello", 30);
058 * </pre></blockquote><hr>
059 * <p>
060 * Every time the user types a key in the text field, one or
061 * more key events are sent to the text field. A <code>KeyEvent</code>
062 * may be one of three types: keyPressed, keyReleased, or keyTyped.
063 * The properties of a key event indicate which of these types
064 * it is, as well as additional information about the event,
065 * such as what modifiers are applied to the key event and the
066 * time at which the event occurred.
067 * <p>
068 * The key event is passed to every <code>KeyListener</code>
069 * or <code>KeyAdapter</code> object which registered to receive such
070 * events using the component's <code>addKeyListener</code> method.
071 * (<code>KeyAdapter</code> objects implement the
072 * <code>KeyListener</code> interface.)
073 * <p>
074 * It is also possible to fire an <code>ActionEvent</code>.
075 * If action events are enabled for the text field, they may
076 * be fired by pressing the <code>Return</code> key.
077 * <p>
078 * The <code>TextField</code> class's <code>processEvent</code>
079 * method examines the action event and passes it along to
080 * <code>processActionEvent</code>. The latter method redirects the
081 * event to any <code>ActionListener</code> objects that have
082 * registered to receive action events generated by this
083 * text field.
084 *
085 * @version 1.92, 05/05/07
086 * @author Sami Shaio
087 * @see java.awt.event.KeyEvent
088 * @see java.awt.event.KeyAdapter
089 * @see java.awt.event.KeyListener
090 * @see java.awt.event.ActionEvent
091 * @see java.awt.Component#addKeyListener
092 * @see java.awt.TextField#processEvent
093 * @see java.awt.TextField#processActionEvent
094 * @see java.awt.TextField#addActionListener
095 * @since JDK1.0
096 */
097 public class TextField extends TextComponent {
098
099 /**
100 * The number of columns in the text field.
101 * A column is an approximate average character
102 * width that is platform-dependent.
103 * Guaranteed to be non-negative.
104 *
105 * @serial
106 * @see #setColumns(int)
107 * @see #getColumns()
108 */
109 int columns;
110
111 /**
112 * The echo character, which is used when
113 * the user wishes to disguise the characters
114 * typed into the text field.
115 * The disguises are removed if echoChar = <code>0</code>.
116 *
117 * @serial
118 * @see #getEchoChar()
119 * @see #setEchoChar(char)
120 * @see #echoCharIsSet()
121 */
122 char echoChar;
123
124 transient ActionListener actionListener;
125
126 private static final String base = "textfield";
127 private static int nameCounter = 0;
128
129 /*
130 * JDK 1.1 serialVersionUID
131 */
132 private static final long serialVersionUID = -2966288784432217853L;
133
134 /**
135 * Initialize JNI field and method ids
136 */
137 private static native void initIDs();
138
139 static {
140 /* ensure that the necessary native libraries are loaded */
141 Toolkit.loadLibraries();
142 if (!GraphicsEnvironment.isHeadless()) {
143 initIDs();
144 }
145 }
146
147 /**
148 * Constructs a new text field.
149 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
150 * returns true.
151 * @see java.awt.GraphicsEnvironment#isHeadless
152 */
153 public TextField() throws HeadlessException {
154 this ("", 0);
155 }
156
157 /**
158 * Constructs a new text field initialized with the specified text.
159 * @param text the text to be displayed. If
160 * <code>text</code> is <code>null</code>, the empty
161 * string <code>""</code> will be displayed.
162 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
163 * returns true.
164 * @see java.awt.GraphicsEnvironment#isHeadless
165 */
166 public TextField(String text) throws HeadlessException {
167 this (text, (text != null) ? text.length() : 0);
168 }
169
170 /**
171 * Constructs a new empty text field with the specified number
172 * of columns. A column is an approximate average character
173 * width that is platform-dependent.
174 * @param columns the number of columns. If
175 * <code>columns</code> is less than <code>0</code>,
176 * <code>columns</code> is set to <code>0</code>.
177 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
178 * returns true.
179 * @see java.awt.GraphicsEnvironment#isHeadless
180 */
181 public TextField(int columns) throws HeadlessException {
182 this ("", columns);
183 }
184
185 /**
186 * Constructs a new text field initialized with the specified text
187 * to be displayed, and wide enough to hold the specified
188 * number of columns. A column is an approximate average character
189 * width that is platform-dependent.
190 * @param text the text to be displayed. If
191 * <code>text</code> is <code>null</code>, the empty
192 * string <code>""</code> will be displayed.
193 * @param columns the number of columns. If
194 * <code>columns</code> is less than <code>0</code>,
195 * <code>columns</code> is set to <code>0</code>.
196 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
197 * returns true.
198 * @see java.awt.GraphicsEnvironment#isHeadless
199 */
200 public TextField(String text, int columns) throws HeadlessException {
201 super (text);
202 this .columns = (columns >= 0) ? columns : 0;
203 }
204
205 /**
206 * Construct a name for this component. Called by getName() when the
207 * name is null.
208 */
209 String constructComponentName() {
210 synchronized (TextField.class) {
211 return base + nameCounter++;
212 }
213 }
214
215 /**
216 * Creates the TextField's peer. The peer allows us to modify the
217 * appearance of the TextField without changing its functionality.
218 */
219 public void addNotify() {
220 synchronized (getTreeLock()) {
221 if (peer == null)
222 peer = getToolkit().createTextField(this );
223 super .addNotify();
224 }
225 }
226
227 /**
228 * Gets the character that is to be used for echoing.
229 * <p>
230 * An echo character is useful for text fields where
231 * user input should not be echoed to the screen, as in
232 * the case of a text field for entering a password.
233 * If <code>echoChar</code> = <code>0</code>, user
234 * input is echoed to the screen unchanged.
235 * <p>
236 * A Java platform implementation may support only a limited,
237 * non-empty set of echo characters. This function returns the
238 * echo character originally requested via setEchoChar(). The echo
239 * character actually used by the TextField implementation might be
240 * different.
241 * @return the echo character for this text field.
242 * @see java.awt.TextField#echoCharIsSet
243 * @see java.awt.TextField#setEchoChar
244 */
245 public char getEchoChar() {
246 return echoChar;
247 }
248
249 /**
250 * Sets the echo character for this text field.
251 * <p>
252 * An echo character is useful for text fields where
253 * user input should not be echoed to the screen, as in
254 * the case of a text field for entering a password.
255 * Setting <code>echoChar</code> = <code>0</code> allows
256 * user input to be echoed to the screen again.
257 * <p>
258 * A Java platform implementation may support only a limited,
259 * non-empty set of echo characters. Attempts to set an
260 * unsupported echo character will cause the default echo
261 * character to be used instead. Subsequent calls to getEchoChar()
262 * will return the echo character originally requested. This might
263 * or might not be identical to the echo character actually
264 * used by the TextField implementation.
265 * @param c the echo character for this text field.
266 * @see java.awt.TextField#echoCharIsSet
267 * @see java.awt.TextField#getEchoChar
268 * @since JDK1.1
269 */
270 public void setEchoChar(char c) {
271 setEchoCharacter(c);
272 }
273
274 /**
275 * @deprecated As of JDK version 1.1,
276 * replaced by <code>setEchoChar(char)</code>.
277 */
278 @Deprecated
279 public synchronized void setEchoCharacter(char c) {
280 if (echoChar != c) {
281 echoChar = c;
282 TextFieldPeer peer = (TextFieldPeer) this .peer;
283 if (peer != null) {
284 peer.setEchoCharacter(c);
285 }
286 }
287 }
288
289 /**
290 * Sets the text that is presented by this
291 * text component to be the specified text.
292 * @param t the new text.
293 * @see java.awt.TextComponent#getText
294 */
295 public void setText(String t) {
296 super .setText(t);
297
298 // This could change the preferred size of the Component.
299 if (valid) {
300 invalidate();
301 }
302 }
303
304 /**
305 * Indicates whether or not this text field has a
306 * character set for echoing.
307 * <p>
308 * An echo character is useful for text fields where
309 * user input should not be echoed to the screen, as in
310 * the case of a text field for entering a password.
311 * @return <code>true</code> if this text field has
312 * a character set for echoing;
313 * <code>false</code> otherwise.
314 * @see java.awt.TextField#setEchoChar
315 * @see java.awt.TextField#getEchoChar
316 */
317 public boolean echoCharIsSet() {
318 return echoChar != 0;
319 }
320
321 /**
322 * Gets the number of columns in this text field. A column is an
323 * approximate average character width that is platform-dependent.
324 * @return the number of columns.
325 * @see java.awt.TextField#setColumns
326 * @since JDK1.1
327 */
328 public int getColumns() {
329 return columns;
330 }
331
332 /**
333 * Sets the number of columns in this text field. A column is an
334 * approximate average character width that is platform-dependent.
335 * @param columns the number of columns.
336 * @see java.awt.TextField#getColumns
337 * @exception IllegalArgumentException if the value
338 * supplied for <code>columns</code>
339 * is less than <code>0</code>.
340 * @since JDK1.1
341 */
342 public void setColumns(int columns) {
343 int oldVal;
344 synchronized (this ) {
345 oldVal = this .columns;
346 if (columns < 0) {
347 throw new IllegalArgumentException(
348 "columns less than zero.");
349 }
350 if (columns != oldVal) {
351 this .columns = columns;
352 }
353 }
354
355 if (columns != oldVal) {
356 invalidate();
357 }
358 }
359
360 /**
361 * Gets the preferred size of this text field
362 * with the specified number of columns.
363 * @param columns the number of columns
364 * in this text field.
365 * @return the preferred dimensions for
366 * displaying this text field.
367 * @since JDK1.1
368 */
369 public Dimension getPreferredSize(int columns) {
370 return preferredSize(columns);
371 }
372
373 /**
374 * @deprecated As of JDK version 1.1,
375 * replaced by <code>getPreferredSize(int)</code>.
376 */
377 @Deprecated
378 public Dimension preferredSize(int columns) {
379 synchronized (getTreeLock()) {
380 TextFieldPeer peer = (TextFieldPeer) this .peer;
381 return (peer != null) ? peer.preferredSize(columns) : super
382 .preferredSize();
383 }
384 }
385
386 /**
387 * Gets the preferred size of this text field.
388 * @return the preferred dimensions for
389 * displaying this text field.
390 * @since JDK1.1
391 */
392 public Dimension getPreferredSize() {
393 return preferredSize();
394 }
395
396 /**
397 * @deprecated As of JDK version 1.1,
398 * replaced by <code>getPreferredSize()</code>.
399 */
400 @Deprecated
401 public Dimension preferredSize() {
402 synchronized (getTreeLock()) {
403 return (columns > 0) ? preferredSize(columns) : super
404 .preferredSize();
405 }
406 }
407
408 /**
409 * Gets the minumum dimensions for a text field with
410 * the specified number of columns.
411 * @param columns the number of columns in
412 * this text field.
413 * @since JDK1.1
414 */
415 public Dimension getMinimumSize(int columns) {
416 return minimumSize(columns);
417 }
418
419 /**
420 * @deprecated As of JDK version 1.1,
421 * replaced by <code>getMinimumSize(int)</code>.
422 */
423 @Deprecated
424 public Dimension minimumSize(int columns) {
425 synchronized (getTreeLock()) {
426 TextFieldPeer peer = (TextFieldPeer) this .peer;
427 return (peer != null) ? peer.minimumSize(columns) : super
428 .minimumSize();
429 }
430 }
431
432 /**
433 * Gets the minumum dimensions for this text field.
434 * @return the minimum dimensions for
435 * displaying this text field.
436 * @since JDK1.1
437 */
438 public Dimension getMinimumSize() {
439 return minimumSize();
440 }
441
442 /**
443 * @deprecated As of JDK version 1.1,
444 * replaced by <code>getMinimumSize()</code>.
445 */
446 @Deprecated
447 public Dimension minimumSize() {
448 synchronized (getTreeLock()) {
449 return (columns > 0) ? minimumSize(columns) : super
450 .minimumSize();
451 }
452 }
453
454 /**
455 * Adds the specified action listener to receive
456 * action events from this text field.
457 * If l is null, no exception is thrown and no action is performed.
458 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
459 * >AWT Threading Issues</a> for details on AWT's threading model.
460 *
461 * @param l the action listener.
462 * @see #removeActionListener
463 * @see #getActionListeners
464 * @see java.awt.event.ActionListener
465 * @since JDK1.1
466 */
467 public synchronized void addActionListener(ActionListener l) {
468 if (l == null) {
469 return;
470 }
471 actionListener = AWTEventMulticaster.add(actionListener, l);
472 newEventsOnly = true;
473 }
474
475 /**
476 * Removes the specified action listener so that it no longer
477 * receives action events from this text field.
478 * If l is null, no exception is thrown and no action is performed.
479 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
480 * >AWT Threading Issues</a> for details on AWT's threading model.
481 *
482 * @param l the action listener.
483 * @see #addActionListener
484 * @see #getActionListeners
485 * @see java.awt.event.ActionListener
486 * @since JDK1.1
487 */
488 public synchronized void removeActionListener(ActionListener l) {
489 if (l == null) {
490 return;
491 }
492 actionListener = AWTEventMulticaster.remove(actionListener, l);
493 }
494
495 /**
496 * Returns an array of all the action listeners
497 * registered on this textfield.
498 *
499 * @return all of this textfield's <code>ActionListener</code>s
500 * or an empty array if no action
501 * listeners are currently registered
502 *
503 * @see #addActionListener
504 * @see #removeActionListener
505 * @see java.awt.event#ActionListener
506 * @since 1.4
507 */
508 public synchronized ActionListener[] getActionListeners() {
509 return (ActionListener[]) (getListeners(ActionListener.class));
510 }
511
512 /**
513 * Returns an array of all the objects currently registered
514 * as <code><em>Foo</em>Listener</code>s
515 * upon this <code>TextField</code>.
516 * <code><em>Foo</em>Listener</code>s are registered using the
517 * <code>add<em>Foo</em>Listener</code> method.
518 *
519 * <p>
520 * You can specify the <code>listenerType</code> argument
521 * with a class literal, such as
522 * <code><em>Foo</em>Listener.class</code>.
523 * For example, you can query a
524 * <code>TextField</code> <code>t</code>
525 * for its action listeners with the following code:
526 *
527 * <pre>ActionListener[] als = (ActionListener[])(t.getListeners(ActionListener.class));</pre>
528 *
529 * If no such listeners exist, this method returns an empty array.
530 *
531 * @param listenerType the type of listeners requested; this parameter
532 * should specify an interface that descends from
533 * <code>java.util.EventListener</code>
534 * @return an array of all objects registered as
535 * <code><em>Foo</em>Listener</code>s on this textfield,
536 * or an empty array if no such
537 * listeners have been added
538 * @exception ClassCastException if <code>listenerType</code>
539 * doesn't specify a class or interface that implements
540 * <code>java.util.EventListener</code>
541 *
542 * @see #getActionListeners
543 * @since 1.3
544 */
545 public <T extends EventListener> T[] getListeners(
546 Class<T> listenerType) {
547 EventListener l = null;
548 if (listenerType == ActionListener.class) {
549 l = actionListener;
550 } else {
551 return super .getListeners(listenerType);
552 }
553 return AWTEventMulticaster.getListeners(l, listenerType);
554 }
555
556 // REMIND: remove when filtering is done at lower level
557 boolean eventEnabled(AWTEvent e) {
558 if (e.id == ActionEvent.ACTION_PERFORMED) {
559 if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0
560 || actionListener != null) {
561 return true;
562 }
563 return false;
564 }
565 return super .eventEnabled(e);
566 }
567
568 /**
569 * Processes events on this text field. If the event
570 * is an instance of <code>ActionEvent</code>,
571 * it invokes the <code>processActionEvent</code>
572 * method. Otherwise, it invokes <code>processEvent</code>
573 * on the superclass.
574 * <p>Note that if the event parameter is <code>null</code>
575 * the behavior is unspecified and may result in an
576 * exception.
577 *
578 * @param e the event
579 * @see java.awt.event.ActionEvent
580 * @see java.awt.TextField#processActionEvent
581 * @since JDK1.1
582 */
583 protected void processEvent(AWTEvent e) {
584 if (e instanceof ActionEvent) {
585 processActionEvent((ActionEvent) e);
586 return;
587 }
588 super .processEvent(e);
589 }
590
591 /**
592 * Processes action events occurring on this text field by
593 * dispatching them to any registered
594 * <code>ActionListener</code> objects.
595 * <p>
596 * This method is not called unless action events are
597 * enabled for this component. Action events are enabled
598 * when one of the following occurs:
599 * <p><ul>
600 * <li>An <code>ActionListener</code> object is registered
601 * via <code>addActionListener</code>.
602 * <li>Action events are enabled via <code>enableEvents</code>.
603 * </ul>
604 * <p>Note that if the event parameter is <code>null</code>
605 * the behavior is unspecified and may result in an
606 * exception.
607 *
608 * @param e the action event
609 * @see java.awt.event.ActionListener
610 * @see java.awt.TextField#addActionListener
611 * @see java.awt.Component#enableEvents
612 * @since JDK1.1
613 */
614 protected void processActionEvent(ActionEvent e) {
615 ActionListener listener = actionListener;
616 if (listener != null) {
617 listener.actionPerformed(e);
618 }
619 }
620
621 /**
622 * Returns a string representing the state of this <code>TextField</code>.
623 * This method is intended to be used only for debugging purposes, and the
624 * content and format of the returned string may vary between
625 * implementations. The returned string may be empty but may not be
626 * <code>null</code>.
627 *
628 * @return the parameter string of this text field
629 */
630 protected String paramString() {
631 String str = super .paramString();
632 if (echoChar != 0) {
633 str += ",echo=" + echoChar;
634 }
635 return str;
636 }
637
638 /*
639 * Serialization support.
640 */
641 /**
642 * The textField Serialized Data Version.
643 *
644 * @serial
645 */
646 private int textFieldSerializedDataVersion = 1;
647
648 /**
649 * Writes default serializable fields to stream. Writes
650 * a list of serializable ActionListener(s) as optional data.
651 * The non-serializable ActionListener(s) are detected and
652 * no attempt is made to serialize them.
653 *
654 * @serialData Null terminated sequence of zero or more pairs.
655 * A pair consists of a String and Object.
656 * The String indicates the type of object and
657 * is one of the following :
658 * ActionListenerK indicating and ActionListener object.
659 *
660 * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
661 * @see java.awt.Component#actionListenerK
662 */
663 private void writeObject(ObjectOutputStream s) throws IOException {
664 s.defaultWriteObject();
665
666 AWTEventMulticaster.save(s, actionListenerK, actionListener);
667 s.writeObject(null);
668 }
669
670 /**
671 * Read the ObjectInputStream and if it isn't null,
672 * add a listener to receive action events fired by the
673 * TextField. Unrecognized keys or values will be
674 * ignored.
675 *
676 * @exception HeadlessException if
677 * <code>GraphicsEnvironment.isHeadless()</code> returns
678 * <code>true</code>
679 * @see #removeActionListener(ActionListener)
680 * @see #addActionListener(ActionListener)
681 * @see java.awt.GraphicsEnvironment#isHeadless
682 */
683 private void readObject(ObjectInputStream s)
684 throws ClassNotFoundException, IOException,
685 HeadlessException {
686 // HeadlessException will be thrown by TextComponent's readObject
687 s.defaultReadObject();
688
689 // Make sure the state we just read in for columns has legal values
690 if (columns < 0) {
691 columns = 0;
692 }
693
694 // Read in listeners, if any
695 Object keyOrNull;
696 while (null != (keyOrNull = s.readObject())) {
697 String key = ((String) keyOrNull).intern();
698
699 if (actionListenerK == key) {
700 addActionListener((ActionListener) (s.readObject()));
701 } else {
702 // skip value for unrecognized key
703 s.readObject();
704 }
705 }
706 }
707
708 /////////////////
709 // Accessibility support
710 ////////////////
711
712 /**
713 * Gets the AccessibleContext associated with this TextField.
714 * For text fields, the AccessibleContext takes the form of an
715 * AccessibleAWTTextField.
716 * A new AccessibleAWTTextField instance is created if necessary.
717 *
718 * @return an AccessibleAWTTextField that serves as the
719 * AccessibleContext of this TextField
720 * @since 1.3
721 */
722 public AccessibleContext getAccessibleContext() {
723 if (accessibleContext == null) {
724 accessibleContext = new AccessibleAWTTextField();
725 }
726 return accessibleContext;
727 }
728
729 /**
730 * This class implements accessibility support for the
731 * <code>TextField</code> class. It provides an implementation of the
732 * Java Accessibility API appropriate to text field user-interface elements.
733 * @since 1.3
734 */
735 protected class AccessibleAWTTextField extends
736 AccessibleAWTTextComponent {
737 /*
738 * JDK 1.3 serialVersionUID
739 */
740 private static final long serialVersionUID = 6219164359235943158L;
741
742 /**
743 * Gets the state set of this object.
744 *
745 * @return an instance of AccessibleStateSet describing the states
746 * of the object
747 * @see AccessibleState
748 */
749 public AccessibleStateSet getAccessibleStateSet() {
750 AccessibleStateSet states = super.getAccessibleStateSet();
751 states.add(AccessibleState.SINGLE_LINE);
752 return states;
753 }
754 }
755
756 }
|