Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1995, 2006, 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.CheckboxMenuItemPeer;
   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    * This class represents a check box that can be included in a menu.
   38    * Selecting the check box in the menu changes its state from
   39    * "on" to "off" or from "off" to "on."
   40    * <p>
   41    * The following picture depicts a menu which contains an instance
   42    * of <code>CheckBoxMenuItem</code>:
   43    * <p>
   44    * <img src="doc-files/MenuBar-1.gif"
   45    * alt="Menu labeled Examples, containing items Basic, Simple, Check, and More Examples. The Check item is a CheckBoxMenuItem instance, in the off state."
   46    * ALIGN=center HSPACE=10 VSPACE=7>
   47    * <p>
   48    * The item labeled <code>Check</code> shows a check box menu item
   49    * in its "off" state.
   50    * <p>
   51    * When a check box menu item is selected, AWT sends an item event to
   52    * the item. Since the event is an instance of <code>ItemEvent</code>,
   53    * the <code>processEvent</code> method examines the event and passes
   54    * it along to <code>processItemEvent</code>. The latter method redirects
   55    * the event to any <code>ItemListener</code> objects that have
   56    * registered an interest in item events generated by this menu item.
   57    *
   58    * @author      Sami Shaio
   59    * @see         java.awt.event.ItemEvent
   60    * @see         java.awt.event.ItemListener
   61    * @since       JDK1.0
   62    */
   63   public class CheckboxMenuItem extends MenuItem implements ItemSelectable, Accessible {
   64   
   65       static {
   66           /* ensure that the necessary native libraries are loaded */
   67           Toolkit.loadLibraries();
   68           if (!GraphicsEnvironment.isHeadless()) {
   69               initIDs();
   70           }
   71       }
   72   
   73      /**
   74       * The state of a checkbox menu item
   75       * @serial
   76       * @see #getState()
   77       * @see #setState(boolean)
   78       */
   79       boolean state = false;
   80   
   81       transient ItemListener itemListener;
   82   
   83       private static final String base = "chkmenuitem";
   84       private static int nameCounter = 0;
   85   
   86       /*
   87        * JDK 1.1 serialVersionUID
   88        */
   89        private static final long serialVersionUID = 6190621106981774043L;
   90   
   91       /**
   92        * Create a check box menu item with an empty label.
   93        * The item's state is initially set to "off."
   94        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
   95        * returns true
   96        * @see java.awt.GraphicsEnvironment#isHeadless
   97        * @since   JDK1.1
   98        */
   99       public CheckboxMenuItem() throws HeadlessException {
  100           this("", false);
  101       }
  102   
  103       /**
  104        * Create a check box menu item with the specified label.
  105        * The item's state is initially set to "off."
  106   
  107        * @param     label   a string label for the check box menu item,
  108        *                or <code>null</code> for an unlabeled menu item.
  109        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
  110        * returns true
  111        * @see java.awt.GraphicsEnvironment#isHeadless
  112        */
  113       public CheckboxMenuItem(String label) throws HeadlessException {
  114           this(label, false);
  115       }
  116   
  117       /**
  118        * Create a check box menu item with the specified label and state.
  119        * @param      label   a string label for the check box menu item,
  120        *                     or <code>null</code> for an unlabeled menu item.
  121        * @param      state   the initial state of the menu item, where
  122        *                     <code>true</code> indicates "on" and
  123        *                     <code>false</code> indicates "off."
  124        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
  125        * returns true
  126        * @see java.awt.GraphicsEnvironment#isHeadless
  127        * @since      JDK1.1
  128        */
  129       public CheckboxMenuItem(String label, boolean state)
  130           throws HeadlessException {
  131           super(label);
  132           this.state = state;
  133       }
  134   
  135       /**
  136        * Construct a name for this MenuComponent.  Called by getName() when
  137        * the name is null.
  138        */
  139       String constructComponentName() {
  140           synchronized (CheckboxMenuItem.class) {
  141               return base + nameCounter++;
  142           }
  143       }
  144   
  145       /**
  146        * Creates the peer of the checkbox item.  This peer allows us to
  147        * change the look of the checkbox item without changing its
  148        * functionality.
  149        * Most applications do not call this method directly.
  150        * @see     java.awt.Toolkit#createCheckboxMenuItem(java.awt.CheckboxMenuItem)
  151        * @see     java.awt.Component#getToolkit()
  152        */
  153       public void addNotify() {
  154           synchronized (getTreeLock()) {
  155               if (peer == null)
  156                   peer = Toolkit.getDefaultToolkit().createCheckboxMenuItem(this);
  157               super.addNotify();
  158           }
  159       }
  160   
  161       /**
  162        * Determines whether the state of this check box menu item
  163        * is "on" or "off."
  164        *
  165        * @return      the state of this check box menu item, where
  166        *                     <code>true</code> indicates "on" and
  167        *                     <code>false</code> indicates "off"
  168        * @see        #setState
  169        */
  170       public boolean getState() {
  171           return state;
  172       }
  173   
  174       /**
  175        * Sets this check box menu item to the specifed state.
  176        * The boolean value <code>true</code> indicates "on" while
  177        * <code>false</code> indicates "off."
  178        *
  179        * <p>Note that this method should be primarily used to
  180        * initialize the state of the check box menu item.
  181        * Programmatically setting the state of the check box
  182        * menu item will <i>not</i> trigger
  183        * an <code>ItemEvent</code>.  The only way to trigger an
  184        * <code>ItemEvent</code> is by user interaction.
  185        *
  186        * @param      b   <code>true</code> if the check box
  187        *             menu item is on, otherwise <code>false</code>
  188        * @see        #getState
  189        */
  190       public synchronized void setState(boolean b) {
  191           state = b;
  192           CheckboxMenuItemPeer peer = (CheckboxMenuItemPeer)this.peer;
  193           if (peer != null) {
  194               peer.setState(b);
  195           }
  196       }
  197   
  198       /**
  199        * Returns the an array (length 1) containing the checkbox menu item
  200        * label or null if the checkbox is not selected.
  201        * @see ItemSelectable
  202        */
  203       public synchronized Object[] getSelectedObjects() {
  204           if (state) {
  205               Object[] items = new Object[1];
  206               items[0] = label;
  207               return items;
  208           }
  209           return null;
  210       }
  211   
  212       /**
  213        * Adds the specified item listener to receive item events from
  214        * this check box menu item.  Item events are sent in response to user
  215        * actions, but not in response to calls to setState().
  216        * If l is null, no exception is thrown and no action is performed.
  217        * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
  218        * >AWT Threading Issues</a> for details on AWT's threading model.
  219        *
  220        * @param         l the item listener
  221        * @see           #removeItemListener
  222        * @see           #getItemListeners
  223        * @see           #setState
  224        * @see           java.awt.event.ItemEvent
  225        * @see           java.awt.event.ItemListener
  226        * @since         JDK1.1
  227        */
  228       public synchronized void addItemListener(ItemListener l) {
  229           if (l == null) {
  230               return;
  231           }
  232           itemListener = AWTEventMulticaster.add(itemListener, l);
  233           newEventsOnly = true;
  234       }
  235   
  236       /**
  237        * Removes the specified item listener so that it no longer receives
  238        * item events from this check box menu item.
  239        * If l is null, no exception is thrown and no action is performed.
  240        * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
  241        * >AWT Threading Issues</a> for details on AWT's threading model.
  242        *
  243        * @param         l the item listener
  244        * @see           #addItemListener
  245        * @see           #getItemListeners
  246        * @see           java.awt.event.ItemEvent
  247        * @see           java.awt.event.ItemListener
  248        * @since         JDK1.1
  249        */
  250       public synchronized void removeItemListener(ItemListener l) {
  251           if (l == null) {
  252               return;
  253           }
  254           itemListener = AWTEventMulticaster.remove(itemListener, l);
  255       }
  256   
  257       /**
  258        * Returns an array of all the item listeners
  259        * registered on this checkbox menuitem.
  260        *
  261        * @return all of this checkbox menuitem's <code>ItemListener</code>s
  262        *         or an empty array if no item
  263        *         listeners are currently registered
  264        *
  265        * @see           #addItemListener
  266        * @see           #removeItemListener
  267        * @see           java.awt.event.ItemEvent
  268        * @see           java.awt.event.ItemListener
  269        * @since 1.4
  270        */
  271       public synchronized ItemListener[] getItemListeners() {
  272           return (ItemListener[])(getListeners(ItemListener.class));
  273       }
  274   
  275       /**
  276        * Returns an array of all the objects currently registered
  277        * as <code><em>Foo</em>Listener</code>s
  278        * upon this <code>CheckboxMenuItem</code>.
  279        * <code><em>Foo</em>Listener</code>s are registered using the
  280        * <code>add<em>Foo</em>Listener</code> method.
  281        *
  282        * <p>
  283        * You can specify the <code>listenerType</code> argument
  284        * with a class literal, such as
  285        * <code><em>Foo</em>Listener.class</code>.
  286        * For example, you can query a
  287        * <code>CheckboxMenuItem</code> <code>c</code>
  288        * for its item listeners with the following code:
  289        *
  290        * <pre>ItemListener[] ils = (ItemListener[])(c.getListeners(ItemListener.class));</pre>
  291        *
  292        * If no such listeners exist, this method returns an empty array.
  293        *
  294        * @param listenerType the type of listeners requested; this parameter
  295        *          should specify an interface that descends from
  296        *          <code>java.util.EventListener</code>
  297        * @return an array of all objects registered as
  298        *          <code><em>Foo</em>Listener</code>s on this checkbox menuitem,
  299        *          or an empty array if no such
  300        *          listeners have been added
  301        * @exception ClassCastException if <code>listenerType</code>
  302        *          doesn't specify a class or interface that implements
  303        *          <code>java.util.EventListener</code>
  304        *
  305        * @see #getItemListeners
  306        * @since 1.3
  307        */
  308       public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
  309           EventListener l = null;
  310           if  (listenerType == ItemListener.class) {
  311               l = itemListener;
  312           } else {
  313               return super.getListeners(listenerType);
  314           }
  315           return AWTEventMulticaster.getListeners(l, listenerType);
  316       }
  317   
  318       // REMIND: remove when filtering is done at lower level
  319       boolean eventEnabled(AWTEvent e) {
  320           if (e.id == ItemEvent.ITEM_STATE_CHANGED) {
  321               if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||
  322                   itemListener != null) {
  323                   return true;
  324               }
  325               return false;
  326           }
  327           return super.eventEnabled(e);
  328       }
  329   
  330       /**
  331        * Processes events on this check box menu item.
  332        * If the event is an instance of <code>ItemEvent</code>,
  333        * this method invokes the <code>processItemEvent</code> method.
  334        * If the event is not an item event,
  335        * it invokes <code>processEvent</code> on the superclass.
  336        * <p>
  337        * Check box menu items currently support only item events.
  338        * <p>Note that if the event parameter is <code>null</code>
  339        * the behavior is unspecified and may result in an
  340        * exception.
  341        *
  342        * @param        e the event
  343        * @see          java.awt.event.ItemEvent
  344        * @see          #processItemEvent
  345        * @since        JDK1.1
  346        */
  347       protected void processEvent(AWTEvent e) {
  348           if (e instanceof ItemEvent) {
  349               processItemEvent((ItemEvent)e);
  350               return;
  351           }
  352           super.processEvent(e);
  353       }
  354   
  355       /**
  356        * Processes item events occurring on this check box menu item by
  357        * dispatching them to any registered <code>ItemListener</code> objects.
  358        * <p>
  359        * This method is not called unless item events are
  360        * enabled for this menu item. Item events are enabled
  361        * when one of the following occurs:
  362        * <p><ul>
  363        * <li>An <code>ItemListener</code> object is registered
  364        * via <code>addItemListener</code>.
  365        * <li>Item events are enabled via <code>enableEvents</code>.
  366        * </ul>
  367        * <p>Note that if the event parameter is <code>null</code>
  368        * the behavior is unspecified and may result in an
  369        * exception.
  370        *
  371        * @param       e the item event
  372        * @see         java.awt.event.ItemEvent
  373        * @see         java.awt.event.ItemListener
  374        * @see         #addItemListener
  375        * @see         java.awt.MenuItem#enableEvents
  376        * @since       JDK1.1
  377        */
  378       protected void processItemEvent(ItemEvent e) {
  379           ItemListener listener = itemListener;
  380           if (listener != null) {
  381               listener.itemStateChanged(e);
  382           }
  383       }
  384   
  385       /*
  386        * Post an ItemEvent and toggle state.
  387        */
  388       void doMenuEvent(long when, int modifiers) {
  389           setState(!state);
  390           Toolkit.getEventQueue().postEvent(
  391               new ItemEvent(this, ItemEvent.ITEM_STATE_CHANGED,
  392                             getLabel(),
  393                             state ? ItemEvent.SELECTED :
  394                                     ItemEvent.DESELECTED));
  395       }
  396   
  397       /**
  398        * Returns a string representing the state of this
  399        * <code>CheckBoxMenuItem</code>. This
  400        * method is intended to be used only for debugging purposes, and the
  401        * content and format of the returned string may vary between
  402        * implementations. The returned string may be empty but may not be
  403        * <code>null</code>.
  404        *
  405        * @return     the parameter string of this check box menu item
  406        */
  407       public String paramString() {
  408           return super.paramString() + ",state=" + state;
  409       }
  410   
  411       /* Serialization support.
  412        */
  413   
  414       /*
  415        * Serial Data Version
  416        * @serial
  417        */
  418       private int checkboxMenuItemSerializedDataVersion = 1;
  419   
  420       /**
  421        * Writes default serializable fields to stream.  Writes
  422        * a list of serializable <code>ItemListeners</code>
  423        * as optional data.  The non-serializable
  424        * <code>ItemListeners</code> are detected and
  425        * no attempt is made to serialize them.
  426        *
  427        * @param s the <code>ObjectOutputStream</code> to write
  428        * @serialData <code>null</code> terminated sequence of
  429        *  0 or more pairs; the pair consists of a <code>String</code>
  430        *  and an <code>Object</code>; the <code>String</code> indicates
  431        *  the type of object and is one of the following:
  432        *  <code>itemListenerK</code> indicating an
  433        *    <code>ItemListener</code> object
  434        *
  435        * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
  436        * @see java.awt.Component#itemListenerK
  437        * @see #readObject(ObjectInputStream)
  438        */
  439       private void writeObject(ObjectOutputStream s)
  440         throws java.io.IOException
  441       {
  442         s.defaultWriteObject();
  443   
  444         AWTEventMulticaster.save(s, itemListenerK, itemListener);
  445         s.writeObject(null);
  446       }
  447   
  448       /*
  449        * Reads the <code>ObjectInputStream</code> and if it
  450        * isn't <code>null</code> adds a listener to receive
  451        * item events fired by the <code>Checkbox</code> menu item.
  452        * Unrecognized keys or values will be ignored.
  453        *
  454        * @param s the <code>ObjectInputStream</code> to read
  455        * @serial
  456        * @see removeActionListener()
  457        * @see addActionListener()
  458        * @see #writeObject
  459        */
  460       private void readObject(ObjectInputStream s)
  461         throws ClassNotFoundException, IOException
  462       {
  463         s.defaultReadObject();
  464   
  465         Object keyOrNull;
  466         while(null != (keyOrNull = s.readObject())) {
  467           String key = ((String)keyOrNull).intern();
  468   
  469           if (itemListenerK == key)
  470             addItemListener((ItemListener)(s.readObject()));
  471   
  472           else // skip value for unrecognized key
  473             s.readObject();
  474         }
  475       }
  476   
  477       /**
  478        * Initialize JNI field and method IDs
  479        */
  480       private static native void initIDs();
  481   
  482   
  483   /////////////////
  484   // Accessibility support
  485   ////////////////
  486   
  487       /**
  488        * Gets the AccessibleContext associated with this CheckboxMenuItem.
  489        * For checkbox menu items, the AccessibleContext takes the
  490        * form of an AccessibleAWTCheckboxMenuItem.
  491        * A new AccessibleAWTCheckboxMenuItem is created if necessary.
  492        *
  493        * @return an AccessibleAWTCheckboxMenuItem that serves as the
  494        *         AccessibleContext of this CheckboxMenuItem
  495        * @since 1.3
  496        */
  497       public AccessibleContext getAccessibleContext() {
  498           if (accessibleContext == null) {
  499               accessibleContext = new AccessibleAWTCheckboxMenuItem();
  500           }
  501           return accessibleContext;
  502       }
  503   
  504       /**
  505        * Inner class of CheckboxMenuItem used to provide default support for
  506        * accessibility.  This class is not meant to be used directly by
  507        * application developers, but is instead meant only to be
  508        * subclassed by menu component developers.
  509        * <p>
  510        * This class implements accessibility support for the
  511        * <code>CheckboxMenuItem</code> class.  It provides an implementation
  512        * of the Java Accessibility API appropriate to checkbox menu item
  513        * user-interface elements.
  514        * @since 1.3
  515        */
  516       protected class AccessibleAWTCheckboxMenuItem extends AccessibleAWTMenuItem
  517           implements AccessibleAction, AccessibleValue
  518       {
  519           /*
  520            * JDK 1.3 serialVersionUID
  521            */
  522           private static final long serialVersionUID = -1122642964303476L;
  523   
  524           /**
  525            * Get the AccessibleAction associated with this object.  In the
  526            * implementation of the Java Accessibility API for this class,
  527            * return this object, which is responsible for implementing the
  528            * AccessibleAction interface on behalf of itself.
  529            *
  530            * @return this object
  531            */
  532           public AccessibleAction getAccessibleAction() {
  533               return this;
  534           }
  535   
  536           /**
  537            * Get the AccessibleValue associated with this object.  In the
  538            * implementation of the Java Accessibility API for this class,
  539            * return this object, which is responsible for implementing the
  540            * AccessibleValue interface on behalf of itself.
  541            *
  542            * @return this object
  543            */
  544           public AccessibleValue getAccessibleValue() {
  545               return this;
  546           }
  547   
  548           /**
  549            * Returns the number of Actions available in this object.
  550            * If there is more than one, the first one is the "default"
  551            * action.
  552            *
  553            * @return the number of Actions in this object
  554            */
  555           public int getAccessibleActionCount() {
  556               return 0;  //  To be fully implemented in a future release
  557           }
  558   
  559           /**
  560            * Return a description of the specified action of the object.
  561            *
  562            * @param i zero-based index of the actions
  563            */
  564           public String getAccessibleActionDescription(int i) {
  565               return null;  //  To be fully implemented in a future release
  566           }
  567   
  568           /**
  569            * Perform the specified Action on the object
  570            *
  571            * @param i zero-based index of actions
  572            * @return true if the action was performed; otherwise false.
  573            */
  574           public boolean doAccessibleAction(int i) {
  575               return false;    //  To be fully implemented in a future release
  576           }
  577   
  578           /**
  579            * Get the value of this object as a Number.  If the value has not been
  580            * set, the return value will be null.
  581            *
  582            * @return value of the object
  583            * @see #setCurrentAccessibleValue
  584            */
  585           public Number getCurrentAccessibleValue() {
  586               return null;  //  To be fully implemented in a future release
  587           }
  588   
  589           /**
  590            * Set the value of this object as a Number.
  591            *
  592            * @return true if the value was set; otherwise false
  593            * @see #getCurrentAccessibleValue
  594            */
  595           public boolean setCurrentAccessibleValue(Number n) {
  596               return false;  //  To be fully implemented in a future release
  597           }
  598   
  599           /**
  600            * Get the minimum value of this object as a Number.
  601            *
  602            * @return Minimum value of the object; null if this object does not
  603            * have a minimum value
  604            * @see #getMaximumAccessibleValue
  605            */
  606           public Number getMinimumAccessibleValue() {
  607               return null;  //  To be fully implemented in a future release
  608           }
  609   
  610           /**
  611            * Get the maximum value of this object as a Number.
  612            *
  613            * @return Maximum value of the object; null if this object does not
  614            * have a maximum value
  615            * @see #getMinimumAccessibleValue
  616            */
  617           public Number getMaximumAccessibleValue() {
  618               return null;  //  To be fully implemented in a future release
  619           }
  620   
  621           /**
  622            * Get the role of this object.
  623            *
  624            * @return an instance of AccessibleRole describing the role of the
  625            * object
  626            */
  627           public AccessibleRole getAccessibleRole() {
  628               return AccessibleRole.CHECK_BOX;
  629           }
  630   
  631       } // class AccessibleAWTMenuItem
  632   
  633   }

Home » openjdk-7 » java » awt » [javadoc | source]