1 /* 2 * Copyright (c) 1995, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package java.awt; 26 27 import java.awt.peer.TextFieldPeer; 28 import java.awt.event.*; 29 import java.util.EventListener; 30 import java.io.ObjectOutputStream; 31 import java.io.ObjectInputStream; 32 import java.io.IOException; 33 import javax.accessibility.*; 34 35 36 /** 37 * A <code>TextField</code> object is a text component 38 * that allows for the editing of a single line of text. 39 * <p> 40 * For example, the following image depicts a frame with four 41 * text fields of varying widths. Two of these text fields 42 * display the predefined text <code>"Hello"</code>. 43 * <p> 44 * <img src="doc-files/TextField-1.gif" alt="The preceding text describes this image." 45 * style="float:center; margin: 7px 10px;"> 46 * <p> 47 * Here is the code that produces these four text fields: 48 * 49 * <hr><blockquote><pre> 50 * TextField tf1, tf2, tf3, tf4; 51 * // a blank text field 52 * tf1 = new TextField(); 53 * // blank field of 20 columns 54 * tf2 = new TextField("", 20); 55 * // predefined text displayed 56 * tf3 = new TextField("Hello!"); 57 * // predefined text in 30 columns 58 * tf4 = new TextField("Hello", 30); 59 * </pre></blockquote><hr> 60 * <p> 61 * Every time the user types a key in the text field, one or 62 * more key events are sent to the text field. A <code>KeyEvent</code> 63 * may be one of three types: keyPressed, keyReleased, or keyTyped. 64 * The properties of a key event indicate which of these types 65 * it is, as well as additional information about the event, 66 * such as what modifiers are applied to the key event and the 67 * time at which the event occurred. 68 * <p> 69 * The key event is passed to every <code>KeyListener</code> 70 * or <code>KeyAdapter</code> object which registered to receive such 71 * events using the component's <code>addKeyListener</code> method. 72 * (<code>KeyAdapter</code> objects implement the 73 * <code>KeyListener</code> interface.) 74 * <p> 75 * It is also possible to fire an <code>ActionEvent</code>. 76 * If action events are enabled for the text field, they may 77 * be fired by pressing the <code>Return</code> key. 78 * <p> 79 * The <code>TextField</code> class's <code>processEvent</code> 80 * method examines the action event and passes it along to 81 * <code>processActionEvent</code>. The latter method redirects the 82 * event to any <code>ActionListener</code> objects that have 83 * registered to receive action events generated by this 84 * text field. 85 * 86 * @author Sami Shaio 87 * @see java.awt.event.KeyEvent 88 * @see java.awt.event.KeyAdapter 89 * @see java.awt.event.KeyListener 90 * @see java.awt.event.ActionEvent 91 * @see java.awt.Component#addKeyListener 92 * @see java.awt.TextField#processEvent 93 * @see java.awt.TextField#processActionEvent 94 * @see java.awt.TextField#addActionListener 95 * @since JDK1.0 96 */ 97 public class TextField extends TextComponent { 98 99 /** 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 * Sets the character to be echoed when protected input is displayed. 276 * 277 * @param c the echo character for this text field 278 * 279 * @deprecated As of JDK version 1.1, 280 * replaced by <code>setEchoChar(char)</code>. 281 */ 282 @Deprecated 283 public synchronized void setEchoCharacter(char c) { 284 if (echoChar != c) { 285 echoChar = c; 286 TextFieldPeer peer = (TextFieldPeer)this.peer; 287 if (peer != null) { 288 peer.setEchoChar(c); 289 } 290 } 291 } 292 293 /** 294 * Sets the text that is presented by this 295 * text component to be the specified text. 296 * @param t the new text. 297 * @see java.awt.TextComponent#getText 298 */ 299 public void setText(String t) { 300 super.setText(t); 301 302 // This could change the preferred size of the Component. 303 invalidateIfValid(); 304 } 305 306 /** 307 * Indicates whether or not this text field has a 308 * character set for echoing. 309 * <p> 310 * An echo character is useful for text fields where 311 * user input should not be echoed to the screen, as in 312 * the case of a text field for entering a password. 313 * @return <code>true</code> if this text field has 314 * a character set for echoing; 315 * <code>false</code> otherwise. 316 * @see java.awt.TextField#setEchoChar 317 * @see java.awt.TextField#getEchoChar 318 */ 319 public boolean echoCharIsSet() { 320 return echoChar != 0; 321 } 322 323 /** 324 * Gets the number of columns in this text field. A column is an 325 * approximate average character width that is platform-dependent. 326 * @return the number of columns. 327 * @see java.awt.TextField#setColumns 328 * @since JDK1.1 329 */ 330 public int getColumns() { 331 return columns; 332 } 333 334 /** 335 * Sets the number of columns in this text field. A column is an 336 * approximate average character width that is platform-dependent. 337 * @param columns the number of columns. 338 * @see java.awt.TextField#getColumns 339 * @exception IllegalArgumentException if the value 340 * supplied for <code>columns</code> 341 * is less than <code>0</code>. 342 * @since JDK1.1 343 */ 344 public void setColumns(int columns) { 345 int oldVal; 346 synchronized (this) { 347 oldVal = this.columns; 348 if (columns < 0) { 349 throw new IllegalArgumentException("columns less than zero."); 350 } 351 if (columns != oldVal) { 352 this.columns = columns; 353 } 354 } 355 356 if (columns != oldVal) { 357 invalidate(); 358 } 359 } 360 361 /** 362 * Gets the preferred size of this text field 363 * with the specified number of columns. 364 * @param columns the number of columns 365 * in this text field. 366 * @return the preferred dimensions for 367 * displaying this text field. 368 * @since JDK1.1 369 */ 370 public Dimension getPreferredSize(int columns) { 371 return preferredSize(columns); 372 } 373 374 /** 375 * Returns the preferred size for this text field 376 * with the specified number of columns. 377 * 378 * @param columns the number of columns 379 * @return the preferred size for the text field 380 * 381 * @deprecated As of JDK version 1.1, 382 * replaced by <code>getPreferredSize(int)</code>. 383 */ 384 @Deprecated 385 public Dimension preferredSize(int columns) { 386 synchronized (getTreeLock()) { 387 TextFieldPeer peer = (TextFieldPeer)this.peer; 388 return (peer != null) ? 389 peer.getPreferredSize(columns) : 390 super.preferredSize(); 391 } 392 } 393 394 /** 395 * Gets the preferred size of this text field. 396 * @return the preferred dimensions for 397 * displaying this text field. 398 * @since JDK1.1 399 */ 400 public Dimension getPreferredSize() { 401 return preferredSize(); 402 } 403 404 /** 405 * @deprecated As of JDK version 1.1, 406 * replaced by <code>getPreferredSize()</code>. 407 */ 408 @Deprecated 409 public Dimension preferredSize() { 410 synchronized (getTreeLock()) { 411 return (columns > 0) ? 412 preferredSize(columns) : 413 super.preferredSize(); 414 } 415 } 416 417 /** 418 * Gets the minimum dimensions for a text field with 419 * the specified number of columns. 420 * 421 * @param columns the number of columns in 422 * this text field. 423 * @return the minimum size for this text field 424 * @since JDK1.1 425 */ 426 public Dimension getMinimumSize(int columns) { 427 return minimumSize(columns); 428 } 429 430 /** 431 * Returns the minimum dimensions for a text field with 432 * the specified number of columns. 433 * 434 * @param columns the number of columns 435 * @return the minimum size for this text field 436 * @deprecated As of JDK version 1.1, 437 * replaced by <code>getMinimumSize(int)</code>. 438 */ 439 @Deprecated 440 public Dimension minimumSize(int columns) { 441 synchronized (getTreeLock()) { 442 TextFieldPeer peer = (TextFieldPeer)this.peer; 443 return (peer != null) ? 444 peer.getMinimumSize(columns) : 445 super.minimumSize(); 446 } 447 } 448 449 /** 450 * Gets the minimum dimensions for this text field. 451 * @return the minimum dimensions for 452 * displaying this text field. 453 * @since JDK1.1 454 */ 455 public Dimension getMinimumSize() { 456 return minimumSize(); 457 } 458 459 /** 460 * @deprecated As of JDK version 1.1, 461 * replaced by <code>getMinimumSize()</code>. 462 */ 463 @Deprecated 464 public Dimension minimumSize() { 465 synchronized (getTreeLock()) { 466 return (columns > 0) ? 467 minimumSize(columns) : 468 super.minimumSize(); 469 } 470 } 471 472 /** 473 * Adds the specified action listener to receive 474 * action events from this text field. 475 * If l is null, no exception is thrown and no action is performed. 476 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads" 477 * >AWT Threading Issues</a> for details on AWT's threading model. 478 * 479 * @param l the action listener. 480 * @see #removeActionListener 481 * @see #getActionListeners 482 * @see java.awt.event.ActionListener 483 * @since JDK1.1 484 */ 485 public synchronized void addActionListener(ActionListener l) { 486 if (l == null) { 487 return; 488 } 489 actionListener = AWTEventMulticaster.add(actionListener, l); 490 newEventsOnly = true; 491 } 492 493 /** 494 * Removes the specified action listener so that it no longer 495 * receives action events from this text field. 496 * If l is null, no exception is thrown and no action is performed. 497 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads" 498 * >AWT Threading Issues</a> for details on AWT's threading model. 499 * 500 * @param l the action listener. 501 * @see #addActionListener 502 * @see #getActionListeners 503 * @see java.awt.event.ActionListener 504 * @since JDK1.1 505 */ 506 public synchronized void removeActionListener(ActionListener l) { 507 if (l == null) { 508 return; 509 } 510 actionListener = AWTEventMulticaster.remove(actionListener, l); 511 } 512 513 /** 514 * Returns an array of all the action listeners 515 * registered on this textfield. 516 * 517 * @return all of this textfield's <code>ActionListener</code>s 518 * or an empty array if no action 519 * listeners are currently registered 520 * 521 * @see #addActionListener 522 * @see #removeActionListener 523 * @see java.awt.event.ActionListener 524 * @since 1.4 525 */ 526 public synchronized ActionListener[] getActionListeners() { 527 return getListeners(ActionListener.class); 528 } 529 530 /** 531 * Returns an array of all the objects currently registered 532 * as <code><em>Foo</em>Listener</code>s 533 * upon this <code>TextField</code>. 534 * <code><em>Foo</em>Listener</code>s are registered using the 535 * <code>add<em>Foo</em>Listener</code> method. 536 * 537 * <p> 538 * You can specify the <code>listenerType</code> argument 539 * with a class literal, such as 540 * <code><em>Foo</em>Listener.class</code>. 541 * For example, you can query a 542 * <code>TextField</code> <code>t</code> 543 * for its action listeners with the following code: 544 * 545 * <pre>ActionListener[] als = (ActionListener[])(t.getListeners(ActionListener.class));</pre> 546 * 547 * If no such listeners exist, this method returns an empty array. 548 * 549 * @param listenerType the type of listeners requested; this parameter 550 * should specify an interface that descends from 551 * <code>java.util.EventListener</code> 552 * @return an array of all objects registered as 553 * <code><em>Foo</em>Listener</code>s on this textfield, 554 * or an empty array if no such 555 * listeners have been added 556 * @exception ClassCastException if <code>listenerType</code> 557 * doesn't specify a class or interface that implements 558 * <code>java.util.EventListener</code> 559 * 560 * @see #getActionListeners 561 * @since 1.3 562 */ 563 public <T extends EventListener> T[] getListeners(Class<T> listenerType) { 564 EventListener l = null; 565 if (listenerType == ActionListener.class) { 566 l = actionListener; 567 } else { 568 return super.getListeners(listenerType); 569 } 570 return AWTEventMulticaster.getListeners(l, listenerType); 571 } 572 573 // REMIND: remove when filtering is done at lower level 574 boolean eventEnabled(AWTEvent e) { 575 if (e.id == ActionEvent.ACTION_PERFORMED) { 576 if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0 || 577 actionListener != null) { 578 return true; 579 } 580 return false; 581 } 582 return super.eventEnabled(e); 583 } 584 585 /** 586 * Processes events on this text field. If the event 587 * is an instance of <code>ActionEvent</code>, 588 * it invokes the <code>processActionEvent</code> 589 * method. Otherwise, it invokes <code>processEvent</code> 590 * on the superclass. 591 * <p>Note that if the event parameter is <code>null</code> 592 * the behavior is unspecified and may result in an 593 * exception. 594 * 595 * @param e the event 596 * @see java.awt.event.ActionEvent 597 * @see java.awt.TextField#processActionEvent 598 * @since JDK1.1 599 */ 600 protected void processEvent(AWTEvent e) { 601 if (e instanceof ActionEvent) { 602 processActionEvent((ActionEvent)e); 603 return; 604 } 605 super.processEvent(e); 606 } 607 608 /** 609 * Processes action events occurring on this text field by 610 * dispatching them to any registered 611 * <code>ActionListener</code> objects. 612 * <p> 613 * This method is not called unless action events are 614 * enabled for this component. Action events are enabled 615 * when one of the following occurs: 616 * <ul> 617 * <li>An <code>ActionListener</code> object is registered 618 * via <code>addActionListener</code>. 619 * <li>Action events are enabled via <code>enableEvents</code>. 620 * </ul> 621 * <p>Note that if the event parameter is <code>null</code> 622 * the behavior is unspecified and may result in an 623 * exception. 624 * 625 * @param e the action event 626 * @see java.awt.event.ActionListener 627 * @see java.awt.TextField#addActionListener 628 * @see java.awt.Component#enableEvents 629 * @since JDK1.1 630 */ 631 protected void processActionEvent(ActionEvent e) { 632 ActionListener listener = actionListener; 633 if (listener != null) { 634 listener.actionPerformed(e); 635 } 636 } 637 638 /** 639 * Returns a string representing the state of this <code>TextField</code>. 640 * This method is intended to be used only for debugging purposes, and the 641 * content and format of the returned string may vary between 642 * implementations. The returned string may be empty but may not be 643 * <code>null</code>. 644 * 645 * @return the parameter string of this text field 646 */ 647 protected String paramString() { 648 String str = super.paramString(); 649 if (echoChar != 0) { 650 str += ",echo=" + echoChar; 651 } 652 return str; 653 } 654 655 656 /* 657 * Serialization support. 658 */ 659 /** 660 * The textField Serialized Data Version. 661 * 662 * @serial 663 */ 664 private int textFieldSerializedDataVersion = 1; 665 666 /** 667 * Writes default serializable fields to stream. Writes 668 * a list of serializable ActionListener(s) as optional data. 669 * The non-serializable ActionListener(s) are detected and 670 * no attempt is made to serialize them. 671 * 672 * @serialData Null terminated sequence of zero or more pairs. 673 * A pair consists of a String and Object. 674 * The String indicates the type of object and 675 * is one of the following : 676 * ActionListenerK indicating and ActionListener object. 677 * 678 * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener) 679 * @see java.awt.Component#actionListenerK 680 */ 681 private void writeObject(ObjectOutputStream s) 682 throws IOException 683 { 684 s.defaultWriteObject(); 685 686 AWTEventMulticaster.save(s, actionListenerK, actionListener); 687 s.writeObject(null); 688 } 689 690 /** 691 * Read the ObjectInputStream and if it isn't null, 692 * add a listener to receive action events fired by the 693 * TextField. Unrecognized keys or values will be 694 * ignored. 695 * 696 * @exception HeadlessException if 697 * <code>GraphicsEnvironment.isHeadless()</code> returns 698 * <code>true</code> 699 * @see #removeActionListener(ActionListener) 700 * @see #addActionListener(ActionListener) 701 * @see java.awt.GraphicsEnvironment#isHeadless 702 */ 703 private void readObject(ObjectInputStream s) 704 throws ClassNotFoundException, IOException, HeadlessException 705 { 706 // HeadlessException will be thrown by TextComponent's readObject 707 s.defaultReadObject(); 708 709 // Make sure the state we just read in for columns has legal values 710 if (columns < 0) { 711 columns = 0; 712 } 713 714 // Read in listeners, if any 715 Object keyOrNull; 716 while(null != (keyOrNull = s.readObject())) { 717 String key = ((String)keyOrNull).intern(); 718 719 if (actionListenerK == key) { 720 addActionListener((ActionListener)(s.readObject())); 721 } else { 722 // skip value for unrecognized key 723 s.readObject(); 724 } 725 } 726 } 727 728 729 ///////////////// 730 // Accessibility support 731 //////////////// 732 733 734 /** 735 * Gets the AccessibleContext associated with this TextField. 736 * For text fields, the AccessibleContext takes the form of an 737 * AccessibleAWTTextField. 738 * A new AccessibleAWTTextField instance is created if necessary. 739 * 740 * @return an AccessibleAWTTextField that serves as the 741 * AccessibleContext of this TextField 742 * @since 1.3 743 */ 744 public AccessibleContext getAccessibleContext() { 745 if (accessibleContext == null) { 746 accessibleContext = new AccessibleAWTTextField(); 747 } 748 return accessibleContext; 749 } 750 751 /** 752 * This class implements accessibility support for the 753 * <code>TextField</code> class. It provides an implementation of the 754 * Java Accessibility API appropriate to text field user-interface elements. 755 * @since 1.3 756 */ 757 protected class AccessibleAWTTextField extends AccessibleAWTTextComponent 758 { 759 /* 760 * JDK 1.3 serialVersionUID 761 */ 762 private static final long serialVersionUID = 6219164359235943158L; 763 764 /** 765 * Gets the state set of this object. 766 * 767 * @return an instance of AccessibleStateSet describing the states 768 * of the object 769 * @see AccessibleState 770 */ 771 public AccessibleStateSet getAccessibleStateSet() { 772 AccessibleStateSet states = super.getAccessibleStateSet(); 773 states.add(AccessibleState.SINGLE_LINE); 774 return states; 775 } 776 } 777 778 }