home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 July & August / Pcwk78a98.iso / Internet / Javadraw / DATA.Z / TextField.java < prev    next >
Text File  |  1997-08-30  |  14KB  |  464 lines
  1. /*
  2.  * @(#)TextField.java    1.40 97/06/24
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22. package java.awt;
  23.  
  24. import java.awt.peer.TextFieldPeer;
  25. import java.awt.event.*;
  26. import java.io.ObjectOutputStream;
  27. import java.io.ObjectInputStream;
  28. import java.io.IOException;
  29.  
  30.  
  31. /**
  32.  * A <code>TextField</code> object is a text component 
  33.  * that allows for the editing of a single line of text.
  34.  * <p>
  35.  * For example, the following image depicts a frame with four
  36.  * text fields of varying widths. Two of these text fields
  37.  * display the predefined text <code>"Hello"</code>.
  38.  * <p>
  39.  * <img src="images-awt/TextField-1.gif"
  40.  * ALIGN=center HSPACE=10 VSPACE=7>
  41.  * <p>
  42.  * Here is the code that produces these four text fields:
  43.  * <p>
  44.  * <hr><blockquote><pre>
  45.  * TextField tf1, tf2, tf3, tf4; 
  46.  * // a blank text field
  47.  * tf1 = new TextField();
  48.  * // blank field of 20 columns
  49.  * tf2 = new TextField("", 20);
  50.  * // predefined text displayed
  51.  * tf3 = new TextField("Hello!");
  52.  * // predefined text in 30 columns
  53.  * tf4 = new TextField("Hello", 30);
  54.  * </pre></blockquote><hr>
  55.  * <p>
  56.  * Every time the user types a key in the text field, AWT 
  57.  * sends two action events to the text field. The first 
  58.  * one represents the key press and the second one, 
  59.  * the key release. Each action event embodies the state 
  60.  * of the system at the time that some action occurred.
  61.  * The properties of an action event indicate which 
  62.  * key was pressed, what modifier keys were also pressed,
  63.  * and the time at which the event occurred. 
  64.  * <p>
  65.  * Since the event is an instance of <code>ActionEvent</code>, 
  66.  * the <code>TextField</code> class's <code>processEvent</code> 
  67.  * method examines the event and passes it along to 
  68.  * <code>processActionEvent</code>. The latter method redirects the
  69.  * event to any <code>ActionListener</code> objects that have
  70.  * registered an interest in action events generated by this
  71.  * text field. 
  72.  *
  73.  * @version    1.40, 06/24/97
  74.  * @author     Sami Shaio
  75.  * @see         java.awt.event.ActionEvent
  76.  * @see         java.awt.TextField#processEvent
  77.  * @see         java.awt.TextField#processActionEvent
  78.  * @since       JDK1.0
  79.  */
  80. public class TextField extends TextComponent {
  81.  
  82.     /**
  83.      * The number of columns in the TextField.
  84.      */
  85.     int columns;
  86.  
  87.     /**
  88.      * The echo character.
  89.      */
  90.     char echoChar;
  91.  
  92.     transient ActionListener actionListener;
  93.  
  94.     private static final String base = "textfield";
  95.     private static int nameCounter = 0;
  96.  
  97.     /*
  98.      * JDK 1.1 serialVersionUID 
  99.      */
  100.     private static final long serialVersionUID = -2966288784432217853L;
  101.  
  102.     /**
  103.      * Constructs a new text field.
  104.      * @since      JDK1.0
  105.      */
  106.     public TextField() {
  107.     this("", 0);
  108.     }
  109.  
  110.     /**
  111.      * Constructs a new text field initialized with the specified text.
  112.      * @param      text       the text to be displayed.
  113.      * @since      JDK1.0
  114.      */
  115.     public TextField(String text) {
  116.     this(text, text.length());
  117.     }
  118.  
  119.     /**
  120.      * Constructs a new empty TextField with the specified number of columns.
  121.      * @param columns the number of columns
  122.      */ 
  123.     public TextField(int columns) {
  124.     this("", columns);
  125.     }
  126.  
  127.     /**
  128.      * Constructs a new text field initialized with the specified text
  129.      * to be displayed, and wide enough to hold the specified 
  130.      * number of characters.
  131.      * @param      text       the text to be displayed.
  132.      * @param      columns    the number of characters.
  133.      * @since      JDK1.0
  134.      */
  135.     public TextField(String text, int columns) {
  136.     super(text);
  137.     this.name = base + nameCounter++;
  138.     this.columns = columns;
  139.     }
  140.  
  141.     /**
  142.      * Creates the TextField's peer.  The peer allows us to modify the
  143.      * appearance of the TextField without changing its functionality.
  144.      */
  145.     public void addNotify() {
  146.     peer = getToolkit().createTextField(this);
  147.     super.addNotify();
  148.     }
  149.  
  150.     /**
  151.      * Gets the character that is to be used for echoing.
  152.      * <p>
  153.      * An echo character is useful for text fields where 
  154.      * user input should not be echoed to the screen, as in 
  155.      * the case of a text field for entering a password.
  156.      * @return      the echo character for this text field.
  157.      * @see         java.awt.TextField#echoCharIsSet
  158.      * @see         java.awt.TextField#setEchoChar
  159.      * @since       JDK1.0
  160.      */
  161.     public char getEchoChar() {
  162.     return echoChar;
  163.     }
  164.  
  165.     /**
  166.      * Sets the echo character for this text field. 
  167.      * <p>
  168.      * An echo character is useful for text fields where 
  169.      * user input should not be echoed to the screen, as in 
  170.      * the case of a text field for entering a password.
  171.      * @param       c   the echo character for this text field.
  172.      * @see         java.awt.TextField#echoCharIsSet
  173.      * @see         java.awt.TextField#getEchoChar
  174.      * @since       JDK1.1
  175.      */
  176.     public void setEchoChar(char c) {
  177.     setEchoCharacter(c);
  178.     }
  179.  
  180.     /**
  181.      * @deprecated As of JDK version 1.1,
  182.      * replaced by <code>setEchoChar(char)</code>.
  183.      */
  184.     public void setEchoCharacter(char c) {
  185.     echoChar = c;
  186.     TextFieldPeer peer = (TextFieldPeer)this.peer;
  187.     if (peer != null) {
  188.         peer.setEchoCharacter(c);
  189.     }
  190.     }
  191.  
  192.     /**
  193.      * Indicates whether or not this text field has a 
  194.      * character set for echoing.
  195.      * <p>
  196.      * An echo character is useful for text fields where 
  197.      * user input should not be echoed to the screen, as in 
  198.      * the case of a text field for entering a password.
  199.      * @return     <code>true</code> if this text field has 
  200.      *                 a character set for echoing; 
  201.      *                 <code>false</code> otherwise.
  202.      * @see        java.awt.TextField#setEchoChar
  203.      * @see        java.awt.TextField#getEchoChar
  204.      * @since      JDK1.0
  205.      */
  206.     public boolean echoCharIsSet() {
  207.     return echoChar != 0;
  208.     }
  209.  
  210.     /**
  211.      * Gets the number of columns in this text field. 
  212.      * @return     the number of columns.
  213.      * @see        java.awt.TextField#setColumns
  214.      * @since      JDK1.1ld.
  215.      */
  216.     public int getColumns() {
  217.     return columns;
  218.     }
  219.  
  220.     /**
  221.      * Sets the number of columns in this text field.
  222.      * @param      columns   the number of columns.
  223.      * @see        java.awt.TextField#getColumns
  224.      * @exception  IllegalArgumentException   if the value
  225.      *                 supplied for <code>columns</code> 
  226.      *                 is less than zero.
  227.      * @since      JDK1.1
  228.      */
  229.     public void setColumns(int columns) {
  230.     int oldVal = this.columns;
  231.     if (columns < 0) {
  232.         throw new IllegalArgumentException("columns less than zero.");
  233.     }
  234.     if (columns != oldVal) {
  235.         this.columns = columns;
  236.         invalidate();
  237.     }
  238.     }
  239.  
  240.     /**
  241.      * Gets the preferred size of this text field 
  242.      * with the specified number of columns.
  243.      * @param     columns the number of columns 
  244.      *                 in this text field. 
  245.      * @return    the preferred dimensions for 
  246.      *                 displaying this text field.
  247.      * @since     JDK1.1
  248.      */
  249.     public Dimension getPreferredSize(int columns) {
  250.         return preferredSize(columns);
  251.     }
  252.  
  253.     /**
  254.      * @deprecated As of JDK version 1.1,
  255.      * replaced by <code>getPreferredSize(int)</code>.
  256.      */
  257.     public Dimension preferredSize(int columns) {
  258.     synchronized (Component.LOCK) {
  259.         TextFieldPeer peer = (TextFieldPeer)this.peer;
  260.         return (peer != null) ?
  261.                peer.preferredSize(columns) :
  262.                super.preferredSize();
  263.     }
  264.     }
  265.  
  266.     /**
  267.      * Gets the preferred size of this text field. 
  268.      * @return     the preferred dimensions for 
  269.      *                         displaying this text field.
  270.      * @since      JDK1.1
  271.      */
  272.     public Dimension getPreferredSize() {
  273.         return preferredSize();
  274.     }
  275.  
  276.     /**
  277.      * @deprecated As of JDK version 1.1,
  278.      * replaced by <code>getPreferredSize()</code>.
  279.      */
  280.     public Dimension preferredSize() {
  281.     synchronized (Component.LOCK) {
  282.         return (columns > 0) ?
  283.                preferredSize(columns) :
  284.                super.preferredSize();
  285.     }
  286.     }
  287.  
  288.     /**
  289.      * Gets the minumum dimensions for a text field with 
  290.      * the specified number of columns.
  291.      * @param    columns   the number of columns in 
  292.      *                          this text field.
  293.      * @since    JDK1.1
  294.      */
  295.     public Dimension getMinimumSize(int columns) {
  296.         return minimumSize(columns);
  297.     }
  298.  
  299.     /**
  300.      * @deprecated As of JDK version 1.1,
  301.      * replaced by <code>getMinimumSize(int)</code>.
  302.      */
  303.     public Dimension minimumSize(int columns) {
  304.     synchronized (Component.LOCK) {
  305.         TextFieldPeer peer = (TextFieldPeer)this.peer;
  306.         return (peer != null) ?
  307.                peer.minimumSize(columns) :
  308.                super.minimumSize();
  309.     }
  310.     }
  311.  
  312.     /**
  313.      * Gets the minumum dimensions for this text field.
  314.      * @return     the minimum dimensions for 
  315.      *                  displaying this text field.
  316.      * @since      JDK1.1
  317.      */
  318.     public Dimension getMinimumSize() {
  319.         return minimumSize();
  320.     }
  321.  
  322.     /**
  323.      * @deprecated As of JDK version 1.1,
  324.      * replaced by <code>getMinimumSize()</code>.
  325.      */
  326.     public Dimension minimumSize() {
  327.     synchronized (Component.LOCK) {
  328.         return (columns > 0) ?
  329.                minimumSize(columns) :
  330.                super.minimumSize();
  331.     }
  332.     }
  333.  
  334.     /**
  335.      * Adds the specified action listener to recieve 
  336.      * action events from this text field.
  337.      * @param      l the action listener.
  338.      * @see        java.awt.event#ActionListener
  339.      * @see        java.awt.TextField#removeActionListener
  340.      * @since      JDK1.1
  341.      */ 
  342.     public synchronized void addActionListener(ActionListener l) {
  343.     actionListener = AWTEventMulticaster.add(actionListener, l);
  344.         newEventsOnly = true;    
  345.     }
  346.  
  347.     /**
  348.      * Removes the specified action listener so that it no longer
  349.      * receives action events from this text field.
  350.      * @param      l the action listener.
  351.      * @see        java.awt.event#ActionListener
  352.      * @see        java.awt.TextField#addActionListener
  353.      * @since      JDK1.1 
  354.      */ 
  355.     public synchronized void removeActionListener(ActionListener l) {
  356.     actionListener = AWTEventMulticaster.remove(actionListener, l);
  357.     }
  358.  
  359.     // REMIND: remove when filtering is done at lower level
  360.     boolean eventEnabled(AWTEvent e) {
  361.         if (e.id == ActionEvent.ACTION_PERFORMED) {
  362.             if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0 ||
  363.                 actionListener != null) {
  364.                 return true;
  365.             } 
  366.             return false;
  367.         }
  368.         return super.eventEnabled(e);
  369.     }          
  370.  
  371.     /**
  372.      * Processes events on this text field. If the event 
  373.      * is an instance of <code>ActionEvent</code>,
  374.      * it invokes the <code>processActionEvent</code> 
  375.      * method. Otherwise, it invokes <code>processEvent</code> 
  376.      * on the superclass.
  377.      * @param      e the event.
  378.      * @see        java.awt.event.ActionEvent
  379.      * @see        java.awt.TextField#processActionEvent
  380.      * @since      JDK1.1
  381.      */
  382.     protected void processEvent(AWTEvent e) {
  383.         if (e instanceof ActionEvent) {
  384.             processActionEvent((ActionEvent)e);     
  385.             return;
  386.         }
  387.     super.processEvent(e);
  388.     }
  389.  
  390.     /** 
  391.      * Processes action events occurring on this text field by
  392.      * dispatching them to any registered 
  393.      * <code>ActionListener</code> objects. 
  394.      * <p>
  395.      * This method is not called unless action events are 
  396.      * enabled for this component. Action events are enabled 
  397.      * when one of the following occurs:
  398.      * <p><ul>
  399.      * <li>An <code>ActionListener</code> object is registered 
  400.      * via <code>addActionListener</code>.
  401.      * <li>Action events are enabled via <code>enableEvents</code>.
  402.      * </ul>
  403.      * @param       e the action event.
  404.      * @see         java.awt.event.ActionListener
  405.      * @see         java.awt.TextField#addActionListener
  406.      * @see         java.awt.Component#enableEvents
  407.      * @since       JDK1.1
  408.      */  
  409.     protected void processActionEvent(ActionEvent e) {
  410.         if (actionListener != null) {
  411.             actionListener.actionPerformed(e);
  412.         }
  413.     }
  414.  
  415.     /**
  416.      * Returns the parameter string representing the state of this 
  417.      * text field. This string is useful for debugging. 
  418.      * @return      the parameter string of this text field. 
  419.      * @since       JDK1.0
  420.      */
  421.     protected String paramString() {
  422.     String str = super.paramString();
  423.     if (echoChar != 0) {
  424.         str += ",echo=" + echoChar;
  425.     }
  426.     return str;
  427.     }
  428.  
  429.  
  430.     /* Serialization support. 
  431.      */
  432.  
  433.     private int textFieldSerializedDataVersion = 1;
  434.  
  435.  
  436.     private void writeObject(ObjectOutputStream s)
  437.       throws IOException 
  438.     {
  439.       s.defaultWriteObject();
  440.  
  441.       AWTEventMulticaster.save(s, actionListenerK, actionListener);
  442.       s.writeObject(null);
  443.     }
  444.  
  445.  
  446.     private void readObject(ObjectInputStream s)
  447.       throws ClassNotFoundException, IOException 
  448.     {
  449.       s.defaultReadObject();
  450.  
  451.       Object keyOrNull;
  452.       while(null != (keyOrNull = s.readObject())) {
  453.     String key = ((String)keyOrNull).intern();
  454.  
  455.     if (actionListenerK == key) 
  456.       addActionListener((ActionListener)(s.readObject()));
  457.  
  458.     else // skip value for unrecognized key
  459.       s.readObject();
  460.       }
  461.     }
  462.  
  463. }
  464.