home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / Checkbox.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  12.6 KB  |  419 lines
  1. /*
  2.  * @(#)Checkbox.java    1.39 98/03/18
  3.  *
  4.  * Copyright 1995-1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.peer.CheckboxPeer;
  17. import java.awt.event.*;
  18. import java.io.ObjectOutputStream;
  19. import java.io.ObjectInputStream;
  20. import java.io.IOException;
  21.  
  22.  
  23. /**
  24.  * A check box is a graphical component that can be in either an 
  25.  * "on" (<code>true</code>) or "off" (<code>false</code>) state.
  26.  * Clicking on a check box changes its state from 
  27.  * "on" to "off," or from "off" to "on." 
  28.  * <p>
  29.  * The following code example creates a set of check boxes in
  30.  * a grid layout: 
  31.  * <p>
  32.  * <hr><blockquote><pre>
  33.  * setLayout(new GridLayout(3, 1));
  34.  * add(new Checkbox("one", null, true));
  35.  * add(new Checkbox("two"));
  36.  * add(new Checkbox("three"));
  37.  * </pre></blockquote><hr>
  38.  * <p>
  39.  * This image depicts the check boxes and grid layout
  40.  * created by this code example:
  41.  * <p>
  42.  * <img src="images-awt/Checkbox-1.gif"
  43.  * ALIGN=center HSPACE=10 VSPACE=7>
  44.  * <p>
  45.  * The button labeled <code>one</code> is in the "on" state, and the 
  46.  * other two are in the "off" state. In this example, which uses the
  47.  * <code>GridLayout</code> class, the states of the three check 
  48.  * boxes are set independently.
  49.  * <p>
  50.  * Alternatively, several check boxes can be grouped together under 
  51.  * the control of a single object, using the 
  52.  * <code>CheckboxGroup</code> class. 
  53.  * In a check box group, at most one button can be in the "on" 
  54.  * state at any given time. Clicking on a check box to turn it on
  55.  * forces any other check box in the same group that is on 
  56.  * into the "off" state.
  57.  *
  58.  * @version    1.39 03/18/98
  59.  * @author     Sami Shaio
  60.  * @see         java.awt.GridLayout
  61.  * @see         java.awt.CheckboxGroup
  62.  * @since       JDK1.0
  63.  */
  64. public class Checkbox extends Component implements ItemSelectable {
  65.  
  66.     static {
  67.         initIDs();
  68.     }
  69.  
  70.     /**
  71.      * The label of the Checkbox.
  72.      */
  73.     String label;
  74.  
  75.     /**
  76.      * The state of the Checkbox.
  77.      */
  78.     boolean state;
  79.  
  80.     /**
  81.      * The check box group.
  82.      */
  83.     CheckboxGroup group;
  84.  
  85.     transient ItemListener itemListener;
  86.  
  87.     private static final String base = "checkbox";
  88.     private static int nameCounter = 0;
  89.  
  90.     /*
  91.      * JDK 1.1 serialVersionUID 
  92.      */
  93.     private static final long serialVersionUID = 7270714317450821763L;
  94.  
  95.     /**
  96.      * Helper function for setState and CheckboxGroup.setSelectedCheckbox
  97.      * Should remain package-private.
  98.      */
  99.     synchronized void setStateInternal(boolean state) {
  100.     this.state = state;
  101.     CheckboxPeer peer = (CheckboxPeer)this.peer;
  102.     if (peer != null) {
  103.         peer.setState(state);
  104.     }
  105.     }
  106.  
  107.     /**
  108.      * Creates a check box with no label. The state of this 
  109.      * check box is set to "off," and it is not part of any 
  110.      * check box group. 
  111.      */
  112.     public Checkbox() {
  113.         this("", false, null);
  114.     }
  115.  
  116.     /**
  117.      * Creates a check box with the specified label.  The state 
  118.      * of this check box is set to "off," and it is not part of  
  119.      * any check box group. 
  120.      * @param     label   a string label for this check box, 
  121.      *                        or <code>null</code> for no label.
  122.      */
  123.     public Checkbox(String label) {
  124.     this(label, false, null);
  125.     }
  126.  
  127.     /**
  128.      * Creates a check box with the specified label.  The state 
  129.      * of this check box is as specified by the <code>state</code> 
  130.      * argument, and it is not part of any check box group. 
  131.      * @param     label   a string label for this check box, 
  132.      *                        or <code>null</code> for no label.
  133.      * @param     state    the initial state of this check box.
  134.      */
  135.     public Checkbox(String label, boolean state) {
  136.         this(label, state, null);
  137.     }
  138.  
  139.     /**
  140.      * Creates a check box with the specified label, in the specified 
  141.      * check box group, and set to the specified state. 
  142.  
  143.      * @param     label   a string label for this check box, 
  144.      *                        or <code>null</code> for no label.
  145.      * @param     state   the initial state of this check box.
  146.      * @param     group   a check box group for this check box, 
  147.      *                           or <code>null</code> for no group.
  148.      * @since     JDK1.1
  149.      */
  150.     public Checkbox(String label, boolean state, CheckboxGroup group) {
  151.     this.name = base + nameCounter++;        
  152.     this.label = label;
  153.     this.state = state;
  154.     this.group = group;
  155.     if (state && (group != null)) {
  156.         group.setSelectedCheckbox(this);
  157.     }
  158.     }
  159.  
  160.     /**
  161.      * Constructs a Checkbox with the specified label, set to the
  162.      * specified state, and in the specified check box group.
  163.      */
  164.     public Checkbox(String label, CheckboxGroup group, boolean state) {
  165.         this(label, state, group);
  166.     }
  167.  
  168.     /**
  169.      * Creates the peer of the Checkbox. The peer allows you to change the
  170.      * look of the Checkbox without changing its functionality.
  171.      * @see     java.awt.Toolkit#createCheckbox(java.awt.Checkbox)
  172.      * @see     java.awt.Component#getToolkit()
  173.      */
  174.     public void addNotify() {
  175.     peer = getToolkit().createCheckbox(this);
  176.     super.addNotify();
  177.     }
  178.  
  179.     /**
  180.      * Gets the label of this check box.
  181.      * @return   the label of this check box, or <code>null</code> 
  182.      *                  if this check box has no label.
  183.      * @see      java.awt.Checkbox#setLabel
  184.      */
  185.     public String getLabel() {
  186.     return label;
  187.     }
  188.  
  189.     /**
  190.      * Sets this check box's label to be the string argument. 
  191.      * @param    label   a string to set as the new label, or 
  192.      *                        <code>null</code> for no label.
  193.      * @see      java.awt.Checkbox#getLabel 
  194.      */
  195.     public synchronized void setLabel(String label) {
  196.     this.label = label;
  197.     CheckboxPeer peer = (CheckboxPeer)this.peer;
  198.     if (peer != null) {
  199.         peer.setLabel(label);
  200.     }
  201.     }
  202.  
  203.     /** 
  204.      * Determines whether this check box is in the "on" or "off" state.
  205.      * The boolean value <code>true</code> indicates the "on" state,  
  206.      * and <code>false</code> indicates the "off" state.
  207.      * @return    the state of this check box, as a boolean value. 
  208.      * @see       java.awt.Checkbox#setState  
  209.      */
  210.     public boolean getState() {
  211.     return state;
  212.     }
  213.     
  214.     /** 
  215.      * Sets the state of this check box to the specified state. 
  216.      * The boolean value <code>true</code> indicates the "on" state,  
  217.      * and <code>false</code> indicates the "off" state.
  218.      * @param     state   the boolean state of the check box.
  219.      * @see       java.awt.Checkbox#getState  
  220.      */
  221.     public void setState(boolean state) {
  222.     /* Cannot hold check box lock when calling group.setSelectedCheckbox. */
  223.         CheckboxGroup group = this.group;
  224.     if (group != null) {
  225.         if (state) {
  226.         group.setSelectedCheckbox(this);
  227.         } else if (group.getSelectedCheckbox() == this) {
  228.         state = true;
  229.         }
  230.     }
  231.     setStateInternal(state);
  232.     }
  233.  
  234.     /**
  235.      * Returns the an array (length 1) containing the checkbox
  236.      * label or null if the checkbox is not selected.
  237.      * @see ItemSelectable
  238.      */
  239.     public Object[] getSelectedObjects() {
  240.         if (state) {
  241.             Object[] items = new Object[1];
  242.             items[0] = label;
  243.             return items;
  244.         }
  245.         return null;
  246.     }
  247.  
  248.     /**
  249.      * Determines this check box's group. 
  250.      * @return     this check box's group, or <code>null</code> 
  251.      *               if the check box is not part of a check box group.
  252.      * @see        java.awt.Checkbox#setCheckboxGroup 
  253.      */
  254.     public CheckboxGroup getCheckboxGroup() {
  255.     return group;
  256.     }
  257.  
  258.     /**
  259.      * Sets this check box's group to be the specified check box group. 
  260.      * If this check box is already in a different check box group, 
  261.      * it is first taken out of that group. 
  262.      * @param     g   the new check box group, or <code>null</code> 
  263.      *                to remove this check box from any check box group.
  264.      * @see       java.awt.Checkbox#getCheckboxGroup  
  265.      */
  266.     public void setCheckboxGroup(CheckboxGroup g) {
  267.         CheckboxGroup group = this.group;
  268.     if (group != null) {
  269.         group.setSelectedCheckbox(null);
  270.     }
  271.     /* Locking check box above could cause deadlock with
  272.      * CheckboxGroup's setSelectedCheckbox method.
  273.      */
  274.     synchronized (this) {
  275.         this.group = g;
  276.         CheckboxPeer peer = (CheckboxPeer)this.peer;
  277.         if (peer != null) {
  278.         peer.setCheckboxGroup(g);
  279.         }
  280.     }
  281.     }
  282.  
  283.     /**
  284.      * Adds the specified item listener to receive item events from
  285.      * this check box.
  286.      * @param         l    the item listener.
  287.      * @see           java.awt.event.ItemEvent
  288.      * @see           java.awt.event.ItemListener
  289.      * @see           java.awt.Checkbox#removeItemListener
  290.      * @since         JDK1.1
  291.      */ 
  292.     public synchronized void addItemListener(ItemListener l) {
  293.         itemListener = AWTEventMulticaster.add(itemListener, l);
  294.         newEventsOnly = true;
  295.     }
  296.  
  297.     /**
  298.      * Removes the specified item listener so that the item listener 
  299.      * no longer receives item events from this check box. 
  300.      * @param         l    the item listener.
  301.      * @see           java.awt.event.ItemEvent
  302.      * @see           java.awt.event.ItemListener
  303.      * @see           java.awt.Checkbox#addItemListener
  304.      * @since         JDK1.1
  305.      */ 
  306.     public synchronized void removeItemListener(ItemListener l) {
  307.         itemListener = AWTEventMulticaster.remove(itemListener, l);
  308.     }
  309.  
  310.     // REMIND: remove when filtering is done at lower level
  311.     boolean eventEnabled(AWTEvent e) {
  312.         if (e.id == ItemEvent.ITEM_STATE_CHANGED) {
  313.             if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||
  314.                 itemListener != null) {
  315.                 return true;
  316.             }             
  317.             return false;
  318.         }
  319.         return super.eventEnabled(e);
  320.     }          
  321.  
  322.     /**
  323.      * Processes events on this check box. 
  324.      * If the event is an instance of <code>ItemEvent</code>,
  325.      * this method invokes the <code>processItemEvent</code> method. 
  326.      * Otherwise, it calls its superclass's <code>processEvent</code> method.
  327.      * @param         e the event.
  328.      * @see           java.awt.event.ItemEvent
  329.      * @see           java.awt.Checkbox#processItemEvent
  330.      * @since         JDK1.1
  331.      */
  332.     protected void processEvent(AWTEvent e) {
  333.         if (e instanceof ItemEvent) {
  334.             processItemEvent((ItemEvent)e);
  335.             return;
  336.         }
  337.     super.processEvent(e);
  338.     }
  339.  
  340.     /** 
  341.      * Processes item events occurring on this check box by
  342.      * dispatching them to any registered 
  343.      * <code>ItemListener</code> objects. 
  344.      * <p>
  345.      * This method is not called unless item events are 
  346.      * enabled for this component. Item events are enabled 
  347.      * when one of the following occurs:
  348.      * <p><ul>
  349.      * <li>An <code>ItemListener</code> object is registered 
  350.      * via <code>addItemListener</code>.
  351.      * <li>Item events are enabled via <code>enableEvents</code>.
  352.      * </ul>
  353.      * @param       e the item event.
  354.      * @see         java.awt.event.ItemEvent
  355.      * @see         java.awt.event.ItemListener
  356.      * @see         java.awt.Checkbox#addItemListener
  357.      * @see         java.awt.Component#enableEvents
  358.      * @since       JDK1.1
  359.      */  
  360.     protected void processItemEvent(ItemEvent e) {
  361.         if (itemListener != null) {
  362.             itemListener.itemStateChanged(e);
  363.         }
  364.     }
  365.  
  366.     /**
  367.      * Returns the parameter string representing the state of 
  368.      * this check box. This string is useful for debugging. 
  369.      * @return    the parameter string of this check box.
  370.      */
  371.     protected String paramString() {
  372.     String str = super.paramString();
  373.     String label = this.label;
  374.     if (label != null) {
  375.         str += ",label=" + label;
  376.     }
  377.     return str + ",state=" + state;
  378.     }
  379.  
  380.  
  381.     /* Serialization support. 
  382.      */
  383.  
  384.     private int checkboxSerializedDataVersion = 1;
  385.  
  386.  
  387.     private void writeObject(ObjectOutputStream s)
  388.       throws java.io.IOException 
  389.     {
  390.       s.defaultWriteObject();
  391.  
  392.       AWTEventMulticaster.save(s, itemListenerK, itemListener);
  393.       s.writeObject(null);
  394.     }
  395.  
  396.  
  397.     private void readObject(ObjectInputStream s)
  398.       throws ClassNotFoundException, IOException 
  399.     {
  400.       s.defaultReadObject();
  401.  
  402.       Object keyOrNull;
  403.       while(null != (keyOrNull = s.readObject())) {
  404.     String key = ((String)keyOrNull).intern();
  405.  
  406.     if (itemListenerK == key) 
  407.       addItemListener((ItemListener)(s.readObject()));
  408.  
  409.     else // skip value for unrecognized key
  410.       s.readObject();
  411.       }
  412.     }
  413.     
  414.     /**
  415.      * Initialize JNI field and method ids
  416.      */
  417.     private static native void initIDs();
  418. }
  419.