home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 July & August / Pcwk78a98.iso / Internet / Javadraw / DATA.Z / Choice.java < prev    next >
Text File  |  1997-08-30  |  14KB  |  451 lines
  1. /*
  2.  * @(#)Choice.java    1.41 97/06/12 Sami Shaio
  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.util.*;
  25. import java.awt.peer.ChoicePeer;
  26. import java.awt.event.*;
  27. import java.io.ObjectOutputStream;
  28. import java.io.ObjectInputStream;
  29. import java.io.IOException;
  30.  
  31.  
  32. /**
  33.  * The <code>Choice</code> class presents a pop-up menu of choices. 
  34.  * The current choice is displayed as the title of the menu. 
  35.  * <p>
  36.  * The following code example produces a pop-up menu: 
  37.  * <p>
  38.  * <hr><blockquote><pre>
  39.  * Choice ColorChooser = new Choice();
  40.  * ColorChooser.add("Green");
  41.  * ColorChooser.add("Red");
  42.  * ColorChooser.add("Blue");
  43.  * </pre></blockquote><hr>
  44.  * <p>
  45.  * After this choice menu has been added to a panel, 
  46.  * it appears as follows in its normal state:
  47.  * <p>
  48.  * <img src="images-awt/Choice-1.gif"
  49.  * ALIGN=center HSPACE=10 VSPACE=7> 
  50.  * <p>
  51.  * In the picture, <code>"Green"</code> is the current choice. 
  52.  * Pushing the mouse button down on the object causes a menu to 
  53.  * appear with the current choice highlighted. 
  54.  * <p>
  55.  * @version    1.41 06/12/97
  56.  * @author     Sami Shaio
  57.  * @author     Arthur van Hoff
  58.  * @since       JDK1.0
  59.  */
  60. public class Choice extends Component implements ItemSelectable {
  61.     /**
  62.      * The items for the Choice.
  63.      */
  64.     Vector pItems;
  65.  
  66.     /** 
  67.      * The index of the current choice for this Choice.
  68.      */
  69.     int selectedIndex = -1;
  70.  
  71.     transient ItemListener itemListener;
  72.  
  73.     private static final String base = "choice";
  74.     private static int nameCounter = 0;
  75.  
  76.     /*
  77.      * JDK 1.1 serialVersionUID 
  78.      */
  79.      private static final long serialVersionUID = -4075310674757313071L;
  80.  
  81.     /** 
  82.      * Creates a new choice menu. The menu initially has no items in it. 
  83.      * <p>
  84.      * By default, the first item added to the choice menu becomes the 
  85.      * selected item, until a different selection is made by the user  
  86.      * by calling one of the <code>select</code> methods. 
  87.      * @see       java.awt.Choice#select(int)
  88.      * @see       java.awt.Choice#select(java.lang.String)
  89.      * @since     JDK1.0
  90.      */
  91.     public Choice() {
  92.         this.name = base + nameCounter++;
  93.     pItems = new Vector();
  94.     }
  95.  
  96.     /**
  97.      * Creates the Choice's peer.  This peer allows us to change the look
  98.      * of the Choice without changing its functionality.
  99.      * @see     java.awt.Toolkit#createChoice(java.awt.Choice)
  100.      * @see     java.awt.Component#getToolkit()
  101.      * @since   JDK1.0
  102.      */
  103.     public void addNotify() {
  104.     peer = getToolkit().createChoice(this);
  105.     super.addNotify();
  106.     }
  107.  
  108.     /**
  109.      * Returns the number of items in this <code>Choice</code> menu.
  110.      * @see     java.awt.Choice#getItem
  111.      * @since   JDK1.1
  112.      */
  113.     public int getItemCount() {
  114.     return countItems();
  115.     }
  116.  
  117.     /**
  118.      * @deprecated As of JDK version 1.1,
  119.      * replaced by <code>getItemCount()</code>.
  120.      */
  121.     public int countItems() {
  122.     return pItems.size();
  123.     }
  124.  
  125.     /**
  126.      * Gets the string at the specified index in this 
  127.      * <code>Choice</code> menu.
  128.      * @param      index the index at which to begin.
  129.      * @see        java.awt.Choice#getItemCount
  130.      * @since      JDK1.0
  131.      */
  132.     public String getItem(int index) {
  133.     return (String)pItems.elementAt(index);
  134.     }
  135.  
  136.     /**
  137.      * Adds an item to this <code>Choice</code> menu.
  138.      * @param      item    the item to be added
  139.      * @exception  NullPointerException   if the item's value is <code>null</code>.
  140.      * @since      JDK1.1
  141.      */
  142.     public synchronized void add(String item) {
  143.     addItem(item);
  144.     }
  145.  
  146.     /**
  147.      * Adds an item to this Choice.
  148.      * @param item the item to be added
  149.      * @exception NullPointerException If the item's value is equal to null.
  150.      */
  151.     public synchronized void addItem(String item) {
  152.     if (item == null) {
  153.         throw new NullPointerException("cannot add null item to Choice");
  154.     }
  155.     pItems.addElement(item);
  156.     ChoicePeer peer = (ChoicePeer)this.peer;
  157.     if (peer != null) {
  158.         peer.addItem(item, pItems.size() - 1);
  159.     }
  160.     if (selectedIndex < 0) {
  161.         select(0);
  162.     }
  163.     }
  164.  
  165.  
  166.     /**
  167.      * Inserts the item into this choice at the specified position.
  168.      * @param item the item to be inserted
  169.      * @param index the position at which the item should be inserted
  170.      * @exception IllegalArgumentException if index is less than 0.
  171.      */
  172.  
  173.     public synchronized void insert(String item, int index) {
  174.     if (index < 0) {
  175.         throw new IllegalArgumentException("index less than zero.");
  176.     }
  177.  
  178.         int nitems = getItemCount();
  179.     Vector tempItems = new Vector();
  180.  
  181.     /* Remove the item at index, nitems-index times 
  182.        storing them in a temporary vector in the
  183.        order they appear on the choice menu.
  184.        */
  185.     for (int i = index ; i < nitems; i++) {
  186.         tempItems.addElement(getItem(index));
  187.         remove(index);
  188.     }
  189.  
  190.     add(item);
  191.  
  192.     /* Add the removed items back to the choice menu, they 
  193.        are already in the correct order in the temp vector.
  194.        */
  195.     for (int i = 0; i < tempItems.size()  ; i++) {
  196.         add((String)tempItems.elementAt(i));
  197.     }
  198.     }
  199.  
  200.     /**
  201.      * Remove the first occurrence of <code>item</code> 
  202.      * from the <code>Choice</code> menu.
  203.      * @param      item  the item to remove from this <code>Choice</code> menu.
  204.      * @exception  IllegalArgumentException  if the item doesn't 
  205.      *                     exist in the choice menu.
  206.      * @since      JDK1.1
  207.      */
  208.     public synchronized void remove(String item) {
  209.         int index = pItems.indexOf(item);
  210.         if (index < 0) {
  211.         throw new IllegalArgumentException("item " + item +
  212.                            " not found in choice");
  213.     } else {
  214.         remove(index);
  215.     }
  216.     }
  217.  
  218.     /**
  219.      * Removes an item from the choice menu 
  220.      * at the specified position.
  221.      * @param      position the position of the item.
  222.      * @since      JDK1.1
  223.      */
  224.     public synchronized void remove(int position) {
  225.         pItems.removeElementAt(position);
  226.         ChoicePeer peer = (ChoicePeer)this.peer;
  227.         if (peer != null) {
  228.         peer.remove(position);
  229.     }
  230.         /* Adjust selectedIndex if selected item was removed. */
  231.         if (pItems.size() == 0) {
  232.         selectedIndex = -1;
  233.     } else if (selectedIndex == position) {
  234.         select(0);
  235.     }
  236.     }
  237.  
  238.     /**
  239.      * Removes all items from the choice menu.
  240.      * @see       java.awt.Choice#remove
  241.      * @since     JDK1.1
  242.      */
  243.     public synchronized void removeAll() {
  244.         int nitems = getItemCount();
  245.     for (int i = 0 ; i < nitems ; i++) {
  246.         remove(0);
  247.     }
  248.     }
  249.  
  250.     /**
  251.      * Gets a representation of the current choice as a string.
  252.      * @return    a string representation of the currently 
  253.      *                     selected item in this choice menu.
  254.      * @see       java.awt.Choice#getSelectedIndex
  255.      * @since     JDK1.0
  256.      */
  257.     public synchronized String getSelectedItem() {
  258.     return (selectedIndex >= 0) ? getItem(selectedIndex) : null;
  259.     }
  260.  
  261.     /**
  262.      * Returns an array (length 1) containing the currently selected
  263.      * item.  If this choice has no items, returns null.
  264.      * @see ItemSelectable
  265.      */
  266.     public synchronized Object[] getSelectedObjects() {
  267.     if (selectedIndex >= 0) {
  268.             Object[] items = new Object[1];
  269.             items[0] = getItem(selectedIndex);
  270.             return items;
  271.         }
  272.         return null;
  273.     }
  274.  
  275.     /**
  276.      * Returns the index of the currently selected item.
  277.      * @see #getSelectedItem
  278.      */
  279.     public int getSelectedIndex() {
  280.     return selectedIndex;
  281.     }
  282.  
  283.     /**
  284.      * Sets the selected item in this <code>Choice</code> menu to be the 
  285.      * item at the specified position. 
  286.      * @param      pos      the positon of the selected item.
  287.      * @exception  IllegalArgumentException if the specified
  288.      *                            position is invalid.
  289.      * @see        java.awt.Choice#getSelectedItem
  290.      * @see        java.awt.Choice#getSelectedIndex
  291.      * @since      JDK1.0
  292.      */
  293.     public synchronized void select(int pos) {
  294.     if (pos >= pItems.size()) {
  295.         throw new IllegalArgumentException("illegal Choice item position: " + pos);
  296.     }
  297.     if (pItems.size() > 0) {
  298.         selectedIndex = pos;
  299.         ChoicePeer peer = (ChoicePeer)this.peer;
  300.         if (peer != null) {
  301.         peer.select(pos);
  302.         }
  303.     }
  304.     }
  305.  
  306.     /**
  307.      * Sets the selected item in this <code>Choice</code> menu 
  308.      * to be the item whose name is equal to the specified string. 
  309.      * If more than one item matches (is equal to) the specified string, 
  310.      * the one with the smallest index is selected. 
  311.      * @param       str     the specified string
  312.      * @see         java.awt.Choice#getSelectedItem
  313.      * @see         java.awt.Choice#getSelectedIndex
  314.      * @since       JDK1.0
  315.      */
  316.     public synchronized void select(String str) {
  317.     int index = pItems.indexOf(str);
  318.     if (index >= 0) {
  319.         select(index);
  320.     }
  321.     }
  322.  
  323.     /**
  324.      * Adds the specified item listener to receive item events from
  325.      * this <code>Choice</code> menu.
  326.      * @param         l    the item listener.
  327.      * @see           java.awt.event.ItemEvent
  328.      * @see           java.awt.event.ItemListener
  329.      * @see           java.awt.Choice#removeItemListener
  330.      * @since         JDK1.1
  331.      */ 
  332.     public synchronized void addItemListener(ItemListener l) {
  333.         itemListener = AWTEventMulticaster.add(itemListener, l);
  334.         newEventsOnly = true;
  335.     }
  336.  
  337.     /**
  338.      * Removes the specified item listener so that it no longer receives 
  339.      * item events from this <code>Choice</code> menu. 
  340.      * @param         l    the item listener.
  341.      * @see           java.awt.event.ItemEvent
  342.      * @see           java.awt.event.ItemListener
  343.      * @see           java.awt.Choice#addItemListener
  344.      * @since         JDK1.1
  345.      */ 
  346.     public synchronized void removeItemListener(ItemListener l) {
  347.         itemListener = AWTEventMulticaster.remove(itemListener, l);
  348.     }
  349.  
  350.     // REMIND: remove when filtering is done at lower level
  351.     boolean eventEnabled(AWTEvent e) {
  352.         if (e.id == ItemEvent.ITEM_STATE_CHANGED) {
  353.             if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||
  354.                 itemListener != null) {
  355.                 return true;
  356.             } 
  357.             return false;
  358.         }
  359.         return super.eventEnabled(e);
  360.     }        
  361.  
  362.     /**
  363.      * Processes events on this choice. If the event is an 
  364.      * instance of <code>ItemEvent</code>, it invokes the 
  365.      * <code>processItemEvent</code> method. Otherwise, it calls its
  366.      * superclass's <code>processEvent</code> method.
  367.      * @param      e the event.
  368.      * @see        java.awt.event.ItemEvent
  369.      * @see        java.awt.Choice#processItemEvent
  370.      * @since      JDK1.1
  371.      */
  372.     protected void processEvent(AWTEvent e) {
  373.         if (e instanceof ItemEvent) {
  374.             processItemEvent((ItemEvent)e);
  375.             return;
  376.         }
  377.     super.processEvent(e);
  378.     }
  379.  
  380.     /** 
  381.      * Processes item events occurring on this <code>Choice</code> 
  382.      * menu by dispatching them to any registered 
  383.      * <code>ItemListener</code> objects. 
  384.      * <p>
  385.      * This method is not called unless item events are 
  386.      * enabled for this component. Item events are enabled 
  387.      * when one of the following occurs:
  388.      * <p><ul>
  389.      * <li>An <code>ItemListener</code> object is registered 
  390.      * via <code>addItemListener</code>.
  391.      * <li>Item events are enabled via <code>enableEvents</code>.
  392.      * </ul>
  393.      * @param       e the item event.
  394.      * @see         java.awt.event.ItemEvent
  395.      * @see         java.awt.event.ItemListener
  396.      * @see         java.awt.Choice#addItemListener
  397.      * @see         java.awt.Component#enableEvents
  398.      * @since       JDK1.1
  399.      */  
  400.     protected void processItemEvent(ItemEvent e) {
  401.         if (itemListener != null) {
  402.             itemListener.itemStateChanged(e);
  403.         }
  404.     }
  405.  
  406.     /**
  407.      * Returns the parameter string representing the state of this 
  408.      * choice menu. This string is useful for debugging. 
  409.      * @return    the parameter string of this <code>Choice</code> menu.
  410.      * @since     JDK1.0
  411.      */
  412.     protected String paramString() {
  413.     return super.paramString() + ",current=" + getSelectedItem();
  414.     }
  415.  
  416.  
  417.     /* Serialization support. 
  418.      */
  419.  
  420.     private int choiceSerializedDataVersion = 1;
  421.  
  422.  
  423.     private void writeObject(ObjectOutputStream s)
  424.       throws java.io.IOException 
  425.     {
  426.       s.defaultWriteObject();
  427.  
  428.       AWTEventMulticaster.save(s, itemListenerK, itemListener);
  429.       s.writeObject(null);
  430.     }
  431.  
  432.  
  433.     private void readObject(ObjectInputStream s)
  434.       throws ClassNotFoundException, IOException 
  435.     {
  436.       s.defaultReadObject();
  437.  
  438.       Object keyOrNull;
  439.       while(null != (keyOrNull = s.readObject())) {
  440.     String key = ((String)keyOrNull).intern();
  441.  
  442.     if (itemListenerK == key) 
  443.       addItemListener((ItemListener)(s.readObject()));
  444.  
  445.     else // skip value for unrecognized key
  446.       s.readObject();
  447.       }
  448.     }
  449.  
  450. }
  451.