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>.
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.setEchoChar(c);
285 }
286 }
287 }
288
304 * character set for echoing.
305 * <p>
306 * An echo character is useful for text fields where
307 * user input should not be echoed to the screen, as in
308 * the case of a text field for entering a password.
309 * @return <code>true</code> if this text field has
310 * a character set for echoing;
311 * <code>false</code> otherwise.
312 * @see java.awt.TextField#setEchoChar
313 * @see java.awt.TextField#getEchoChar
314 */
315 public boolean echoCharIsSet() {
316 return echoChar != 0;
317 }
318
319 /**
320 * Gets the number of columns in this text field. A column is an
321 * approximate average character width that is platform-dependent.
322 * @return the number of columns.
323 * @see java.awt.TextField#setColumns
324 * @since JDK1.1
325 */
326 public int getColumns() {
327 return columns;
328 }
329
330 /**
331 * Sets the number of columns in this text field. A column is an
332 * approximate average character width that is platform-dependent.
333 * @param columns the number of columns.
334 * @see java.awt.TextField#getColumns
335 * @exception IllegalArgumentException if the value
336 * supplied for <code>columns</code>
337 * is less than <code>0</code>.
338 * @since JDK1.1
339 */
340 public void setColumns(int columns) {
341 int oldVal;
342 synchronized (this) {
343 oldVal = this.columns;
344 if (columns < 0) {
345 throw new IllegalArgumentException("columns less than zero.");
346 }
347 if (columns != oldVal) {
348 this.columns = columns;
349 }
350 }
351
352 if (columns != oldVal) {
353 invalidate();
354 }
355 }
356
357 /**
358 * Gets the preferred size of this text field
359 * with the specified number of columns.
360 * @param columns the number of columns
361 * in this text field.
362 * @return the preferred dimensions for
363 * displaying this text field.
364 * @since JDK1.1
365 */
366 public Dimension getPreferredSize(int columns) {
367 return preferredSize(columns);
368 }
369
370 /**
371 * @deprecated As of JDK version 1.1,
372 * replaced by <code>getPreferredSize(int)</code>.
373 */
374 @Deprecated
375 public Dimension preferredSize(int columns) {
376 synchronized (getTreeLock()) {
377 TextFieldPeer peer = (TextFieldPeer)this.peer;
378 return (peer != null) ?
379 peer.getPreferredSize(columns) :
380 super.preferredSize();
381 }
382 }
383
384 /**
385 * Gets the preferred size of this text field.
386 * @return the preferred dimensions for
387 * displaying this text field.
388 * @since JDK1.1
389 */
390 public Dimension getPreferredSize() {
391 return preferredSize();
392 }
393
394 /**
395 * @deprecated As of JDK version 1.1,
396 * replaced by <code>getPreferredSize()</code>.
397 */
398 @Deprecated
399 public Dimension preferredSize() {
400 synchronized (getTreeLock()) {
401 return (columns > 0) ?
402 preferredSize(columns) :
403 super.preferredSize();
404 }
405 }
406
407 /**
408 * Gets the minimum dimensions for a text field with
409 * the specified number of columns.
410 * @param columns the number of columns in
411 * this text field.
412 * @since JDK1.1
413 */
414 public Dimension getMinimumSize(int columns) {
415 return minimumSize(columns);
416 }
417
418 /**
419 * @deprecated As of JDK version 1.1,
420 * replaced by <code>getMinimumSize(int)</code>.
421 */
422 @Deprecated
423 public Dimension minimumSize(int columns) {
424 synchronized (getTreeLock()) {
425 TextFieldPeer peer = (TextFieldPeer)this.peer;
426 return (peer != null) ?
427 peer.getMinimumSize(columns) :
428 super.minimumSize();
429 }
430 }
431
432 /**
433 * Gets the minimum 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) ?
450 minimumSize(columns) :
451 super.minimumSize();
452 }
453 }
454
455 /**
456 * Adds the specified action listener to receive
457 * action events from this text field.
458 * If l is null, no exception is thrown and no action is performed.
459 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
460 * >AWT Threading Issues</a> for details on AWT's threading model.
461 *
462 * @param l the action listener.
463 * @see #removeActionListener
464 * @see #getActionListeners
465 * @see java.awt.event.ActionListener
466 * @since JDK1.1
467 */
468 public synchronized void addActionListener(ActionListener l) {
469 if (l == null) {
470 return;
471 }
472 actionListener = AWTEventMulticaster.add(actionListener, l);
473 newEventsOnly = true;
474 }
475
476 /**
477 * Removes the specified action listener so that it no longer
478 * receives action events from this text field.
479 * If l is null, no exception is thrown and no action is performed.
480 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
481 * >AWT Threading Issues</a> for details on AWT's threading model.
482 *
483 * @param l the action listener.
484 * @see #addActionListener
485 * @see #getActionListeners
486 * @see java.awt.event.ActionListener
487 * @since JDK1.1
488 */
489 public synchronized void removeActionListener(ActionListener l) {
490 if (l == null) {
491 return;
492 }
493 actionListener = AWTEventMulticaster.remove(actionListener, l);
494 }
495
496 /**
497 * Returns an array of all the action listeners
498 * registered on this textfield.
499 *
500 * @return all of this textfield's <code>ActionListener</code>s
501 * or an empty array if no action
502 * listeners are currently registered
503 *
504 * @see #addActionListener
505 * @see #removeActionListener
506 * @see java.awt.event.ActionListener
507 * @since 1.4
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 * <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) {
|
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 1.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>.
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 1.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.setEchoChar(c);
285 }
286 }
287 }
288
304 * character set for echoing.
305 * <p>
306 * An echo character is useful for text fields where
307 * user input should not be echoed to the screen, as in
308 * the case of a text field for entering a password.
309 * @return <code>true</code> if this text field has
310 * a character set for echoing;
311 * <code>false</code> otherwise.
312 * @see java.awt.TextField#setEchoChar
313 * @see java.awt.TextField#getEchoChar
314 */
315 public boolean echoCharIsSet() {
316 return echoChar != 0;
317 }
318
319 /**
320 * Gets the number of columns in this text field. A column is an
321 * approximate average character width that is platform-dependent.
322 * @return the number of columns.
323 * @see java.awt.TextField#setColumns
324 * @since 1.1
325 */
326 public int getColumns() {
327 return columns;
328 }
329
330 /**
331 * Sets the number of columns in this text field. A column is an
332 * approximate average character width that is platform-dependent.
333 * @param columns the number of columns.
334 * @see java.awt.TextField#getColumns
335 * @exception IllegalArgumentException if the value
336 * supplied for <code>columns</code>
337 * is less than <code>0</code>.
338 * @since 1.1
339 */
340 public void setColumns(int columns) {
341 int oldVal;
342 synchronized (this) {
343 oldVal = this.columns;
344 if (columns < 0) {
345 throw new IllegalArgumentException("columns less than zero.");
346 }
347 if (columns != oldVal) {
348 this.columns = columns;
349 }
350 }
351
352 if (columns != oldVal) {
353 invalidate();
354 }
355 }
356
357 /**
358 * Gets the preferred size of this text field
359 * with the specified number of columns.
360 * @param columns the number of columns
361 * in this text field.
362 * @return the preferred dimensions for
363 * displaying this text field.
364 * @since 1.1
365 */
366 public Dimension getPreferredSize(int columns) {
367 return preferredSize(columns);
368 }
369
370 /**
371 * @deprecated As of JDK version 1.1,
372 * replaced by <code>getPreferredSize(int)</code>.
373 */
374 @Deprecated
375 public Dimension preferredSize(int columns) {
376 synchronized (getTreeLock()) {
377 TextFieldPeer peer = (TextFieldPeer)this.peer;
378 return (peer != null) ?
379 peer.getPreferredSize(columns) :
380 super.preferredSize();
381 }
382 }
383
384 /**
385 * Gets the preferred size of this text field.
386 * @return the preferred dimensions for
387 * displaying this text field.
388 * @since 1.1
389 */
390 public Dimension getPreferredSize() {
391 return preferredSize();
392 }
393
394 /**
395 * @deprecated As of JDK version 1.1,
396 * replaced by <code>getPreferredSize()</code>.
397 */
398 @Deprecated
399 public Dimension preferredSize() {
400 synchronized (getTreeLock()) {
401 return (columns > 0) ?
402 preferredSize(columns) :
403 super.preferredSize();
404 }
405 }
406
407 /**
408 * Gets the minimum dimensions for a text field with
409 * the specified number of columns.
410 * @param columns the number of columns in
411 * this text field.
412 * @since 1.1
413 */
414 public Dimension getMinimumSize(int columns) {
415 return minimumSize(columns);
416 }
417
418 /**
419 * @deprecated As of JDK version 1.1,
420 * replaced by <code>getMinimumSize(int)</code>.
421 */
422 @Deprecated
423 public Dimension minimumSize(int columns) {
424 synchronized (getTreeLock()) {
425 TextFieldPeer peer = (TextFieldPeer)this.peer;
426 return (peer != null) ?
427 peer.getMinimumSize(columns) :
428 super.minimumSize();
429 }
430 }
431
432 /**
433 * Gets the minimum dimensions for this text field.
434 * @return the minimum dimensions for
435 * displaying this text field.
436 * @since 1.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) ?
450 minimumSize(columns) :
451 super.minimumSize();
452 }
453 }
454
455 /**
456 * Adds the specified action listener to receive
457 * action events from this text field.
458 * If l is null, no exception is thrown and no action is performed.
459 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
460 * >AWT Threading Issues</a> for details on AWT's threading model.
461 *
462 * @param l the action listener.
463 * @see #removeActionListener
464 * @see #getActionListeners
465 * @see java.awt.event.ActionListener
466 * @since 1.1
467 */
468 public synchronized void addActionListener(ActionListener l) {
469 if (l == null) {
470 return;
471 }
472 actionListener = AWTEventMulticaster.add(actionListener, l);
473 newEventsOnly = true;
474 }
475
476 /**
477 * Removes the specified action listener so that it no longer
478 * receives action events from this text field.
479 * If l is null, no exception is thrown and no action is performed.
480 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
481 * >AWT Threading Issues</a> for details on AWT's threading model.
482 *
483 * @param l the action listener.
484 * @see #addActionListener
485 * @see #getActionListeners
486 * @see java.awt.event.ActionListener
487 * @since 1.1
488 */
489 public synchronized void removeActionListener(ActionListener l) {
490 if (l == null) {
491 return;
492 }
493 actionListener = AWTEventMulticaster.remove(actionListener, l);
494 }
495
496 /**
497 * Returns an array of all the action listeners
498 * registered on this textfield.
499 *
500 * @return all of this textfield's <code>ActionListener</code>s
501 * or an empty array if no action
502 * listeners are currently registered
503 *
504 * @see #addActionListener
505 * @see #removeActionListener
506 * @see java.awt.event.ActionListener
507 * @since 1.4
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 1.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 * <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 1.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) {
|