/*

 * Copyright 1995-2008 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.awt;

import java.awt.peer.CheckboxPeer;

import java.awt.event.*;

import java.util.EventListener;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

import javax.accessibility.*;

/**

 * A check box is a graphical component that can be in either an

 * "on" (<code>true</code>) or "off" (<code>false</code>) state.

 * Clicking on a check box changes its state from

 * "on" to "off," or from "off" to "on."

 * <p>

 * The following code example creates a set of check boxes in

 * a grid layout:

 * <p>

 * <hr><blockquote><pre>

 * setLayout(new GridLayout(3, 1));

 * add(new Checkbox("one", null, true));

 * add(new Checkbox("two"));

 * add(new Checkbox("three"));

 * </pre></blockquote><hr>

 * <p>

 * This image depicts the check boxes and grid layout

 * created by this code example:

 * <p>

 * <img src="doc-files/Checkbox-1.gif" alt="The following context describes the graphic."

 * ALIGN=center HSPACE=10 VSPACE=7>

 * <p>

 * The button labeled <code>one</code> is in the "on" state, and the

 * other two are in the "off" state. In this example, which uses the

 * <code>GridLayout</code> class, the states of the three check

 * boxes are set independently.

 * <p>

 * Alternatively, several check boxes can be grouped together under

 * the control of a single object, using the

 * <code>CheckboxGroup</code> class.

 * In a check box group, at most one button can be in the "on"

 * state at any given time. Clicking on a check box to turn it on

 * forces any other check box in the same group that is on

 * into the "off" state.

 *

 * @author      Sami Shaio

 * @see         java.awt.GridLayout

 * @see         java.awt.CheckboxGroup

 * @since       JDK1.0

 */

public class Checkbox extends Component implements ItemSelectable, Accessible {

    static {

        /* ensure that the necessary native libraries are loaded */

        Toolkit.loadLibraries();

        if (!GraphicsEnvironment.isHeadless()) {

            initIDs();

        }

    }

    /**

     * The label of the Checkbox.

     * This field can be null.

     * @serial

     * @see #getLabel()

     * @see #setLabel(String)

     */

    String label;

    /**

     * The state of the <code>Checkbox</code>.

     * @serial

     * @see #getState()

     * @see #setState(boolean)

     */

    boolean state;

    /**

     * The check box group.

         * This field can be null indicating that the checkbox

         * is not a group checkbox.

         * @serial

     * @see #getCheckboxGroup()

     * @see #setCheckboxGroup(CheckboxGroup)

     */

    CheckboxGroup group;

    transient ItemListener itemListener;

    private static final String base = "checkbox";

    private static int nameCounter = 0;

    /*

     * JDK 1.1 serialVersionUID

     */

    private static final long serialVersionUID = 7270714317450821763L;

    /**

     * Helper function for setState and CheckboxGroup.setSelectedCheckbox

     * Should remain package-private.

     */

    void setStateInternal(boolean state) {

        this.state = state;

        CheckboxPeer peer = (CheckboxPeer)this.peer;

        if (peer != null) {

            peer.setState(state);

        }

    }

    /**

     * Creates a check box with an empty string for its label.

     * The state of this check box is set to "off," and it is not

     * part of any check box group.

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     * returns true

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public Checkbox() throws HeadlessException {

        this("", false, null);

    }

    /**

     * Creates a check box with the specified label.  The state

     * of this check box is set to "off," and it is not part of

     * any check box group.

     *

     * @param     label   a string label for this check box,

     *                        or <code>null</code> for no label.

     * @exception HeadlessException if

     *      <code>GraphicsEnvironment.isHeadless</code>

     *      returns <code>true</code>

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public Checkbox(String label) throws HeadlessException {

        this(label, false, null);

    }

    /**

     * Creates a check box with the specified label

     * and sets the specified state.

     * This check box is not part of any check box group.

     *

     * @param     label   a string label for this check box,

     *                        or <code>null</code> for no label

     * @param     state    the initial state of this check box

     * @exception HeadlessException if

     *     <code>GraphicsEnvironment.isHeadless</code>

     *     returns <code>true</code>

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public Checkbox(String label, boolean state) throws HeadlessException {

        this(label, state, null);

    }

    /**

     * Constructs a Checkbox with the specified label, set to the

     * specified state, and in the specified check box group.

     *

     * @param     label   a string label for this check box,

     *                        or <code>null</code> for no label.

     * @param     state   the initial state of this check box.

     * @param     group   a check box group for this check box,

     *                           or <code>null</code> for no group.

     * @exception HeadlessException if

     *     <code>GraphicsEnvironment.isHeadless</code>

     *     returns <code>true</code>

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @since     JDK1.1

     */

    public Checkbox(String label, boolean state, CheckboxGroup group)

        throws HeadlessException {

        GraphicsEnvironment.checkHeadless();

        this.label = label;

        this.state = state;

        this.group = group;

        if (state && (group != null)) {

            group.setSelectedCheckbox(this);

        }

    }

    /**

     * Creates a check box with the specified label, in the specified

     * check box group, and set to the specified state.

     *

     * @param     label   a string label for this check box,

     *                        or <code>null</code> for no label.

     * @param     group   a check box group for this check box,

     *                           or <code>null</code> for no group.

     * @param     state   the initial state of this check box.

     * @exception HeadlessException if

     *    <code>GraphicsEnvironment.isHeadless</code>

     *    returns <code>true</code>

     * @see java.awt.GraphicsEnvironment#isHeadless

     * @since     JDK1.1

     */

    public Checkbox(String label, CheckboxGroup group, boolean state)

        throws HeadlessException {

        this(label, state, group);

    }

    /**

     * Constructs a name for this component.  Called by

     * <code>getName</code> when the name is <code>null</code>.

     *

     * @return a name for this component

     */

    String constructComponentName() {

        synchronized (Checkbox.class) {

            return base + nameCounter++;

        }

    }

    /**

     * Creates the peer of the Checkbox. The peer allows you to change the

     * look of the Checkbox without changing its functionality.

     *

     * @see     java.awt.Toolkit#createCheckbox(java.awt.Checkbox)

     * @see     java.awt.Component#getToolkit()

     */

    public void addNotify() {

        synchronized (getTreeLock()) {

            if (peer == null)

                peer = getToolkit().createCheckbox(this);

            super.addNotify();

        }

    }

    /**

     * Gets the label of this check box.

     *

     * @return   the label of this check box, or <code>null</code>

     *                  if this check box has no label.

     * @see      #setLabel(String)

     */

    public String getLabel() {

        return label;

    }

    /**

     * Sets this check box's label to be the string argument.

     *

     * @param    label   a string to set as the new label, or

     *                        <code>null</code> for no label.

     * @see      #getLabel

     */

    public void setLabel(String label) {

        boolean testvalid = false;

        synchronized (this) {

            if (label != this.label && (this.label == null ||

                                        !this.label.equals(label))) {

                this.label = label;

                CheckboxPeer peer = (CheckboxPeer)this.peer;

                if (peer != null) {

                    peer.setLabel(label);

                }

                testvalid = true;

            }

        }

        // This could change the preferred size of the Component.

        if (testvalid) {

            invalidateIfValid();

        }

    }

    /**

     * Determines whether this check box is in the "on" or "off" state.

     * The boolean value <code>true</code> indicates the "on" state,

     * and <code>false</code> indicates the "off" state.

     *

     * @return    the state of this check box, as a boolean value

     * @see       #setState

     */

    public boolean getState() {

        return state;

    }

    /**

     * Sets the state of this check box to the specified state.

     * The boolean value <code>true</code> indicates the "on" state,

     * and <code>false</code> indicates the "off" state.

     *

     * <p>Note that this method should be primarily used to

     * initialize the state of the checkbox.  Programmatically

     * setting the state of the checkbox will <i>not</i> trigger

     * an <code>ItemEvent</code>.  The only way to trigger an

     * <code>ItemEvent</code> is by user interaction.

     *

     * @param     state   the boolean state of the check box

     * @see       #getState

     */

    public void setState(boolean state) {

        /* Cannot hold check box lock when calling group.setSelectedCheckbox. */

        CheckboxGroup group = this.group;

        if (group != null) {

            if (state) {

                group.setSelectedCheckbox(this);

            } else if (group.getSelectedCheckbox() == this) {

                state = true;

            }

        }

        setStateInternal(state);

    }

    /**

     * Returns an array (length 1) containing the checkbox

     * label or null if the checkbox is not selected.

     * @see ItemSelectable

     */

    public Object[] getSelectedObjects() {

        if (state) {

            Object[] items = new Object[1];

            items[0] = label;

            return items;

        }

        return null;

    }

    /**

     * Determines this check box's group.

     * @return     this check box's group, or <code>null</code>

     *               if the check box is not part of a check box group.

     * @see        #setCheckboxGroup(CheckboxGroup)

     */

    public CheckboxGroup getCheckboxGroup() {

        return group;

    }

    /**

     * Sets this check box's group to the specified check box group.

     * If this check box is already in a different check box group,

     * it is first taken out of that group.

     * <p>

     * If the state of this check box is <code>true</code> and the new

     * group already has a check box selected, this check box's state

     * is changed to <code>false</code>.  If the state of this check

     * box is <code>true</code> and the new group has no check box

     * selected, this check box becomes the selected checkbox for

     * the new group and its state is <code>true</code>.

     *

     * @param     g   the new check box group, or <code>null</code>

     *                to remove this check box from any check box group

     * @see       #getCheckboxGroup

     */

    public void setCheckboxGroup(CheckboxGroup g) {

        CheckboxGroup oldGroup;

        boolean oldState;

        /* Do nothing if this check box has already belonged

         * to the check box group g.

         */

        if (this.group == g) {

            return;

        }

        synchronized (this) {

            oldGroup = this.group;

            oldState = getState();

            this.group = g;

            CheckboxPeer peer = (CheckboxPeer)this.peer;

            if (peer != null) {

                peer.setCheckboxGroup(g);

            }

            if (this.group != null && getState()) {

                if (this.group.getSelectedCheckbox() != null) {

                    setState(false);

                } else {

                    this.group.setSelectedCheckbox(this);

                }

            }

        }

        /* Locking check box below could cause deadlock with

         * CheckboxGroup's setSelectedCheckbox method.

         *

         * Fix for 4726853 by kdm@sparc.spb.su

         * Here we should check if this check box was selected

         * in the previous group and set selected check box to

         * null for that group if so.

         */

        if (oldGroup != null && oldState) {

            oldGroup.setSelectedCheckbox(null);

        }

    }

    /**

     * Adds the specified item listener to receive item events from

     * this check box.  Item events are sent to listeners in response

     * to user input, but not in response to calls to setState().

     * If l is null, no exception is thrown and no action is performed.

     * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"

     * >AWT Threading Issues</a> for details on AWT's threading model.

     *

     * @param         l    the item listener

     * @see           #removeItemListener

     * @see           #getItemListeners

     * @see           #setState

     * @see           java.awt.event.ItemEvent

     * @see           java.awt.event.ItemListener

     * @since         JDK1.1

     */

    public synchronized void addItemListener(ItemListener l) {

        if (l == null) {

            return;

        }

        itemListener = AWTEventMulticaster.add(itemListener, l);

        newEventsOnly = true;

    }

    /**

     * Removes the specified item listener so that the item listener

     * no longer receives item events from this check box.

     * If l is null, no exception is thrown and no action is performed.

     * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"

     * >AWT Threading Issues</a> for details on AWT's threading model.

     *

     * @param         l    the item listener

     * @see           #addItemListener

     * @see           #getItemListeners

     * @see           java.awt.event.ItemEvent

     * @see           java.awt.event.ItemListener

     * @since         JDK1.1

     */

    public synchronized void removeItemListener(ItemListener l) {

        if (l == null) {

            return;

        }

        itemListener = AWTEventMulticaster.remove(itemListener, l);

    }

    /**

     * Returns an array of all the item listeners

     * registered on this checkbox.

     *

     * @return all of this checkbox's <code>ItemListener</code>s

     *         or an empty array if no item

     *         listeners are currently registered

     *

     * @see           #addItemListener

     * @see           #removeItemListener

     * @see           java.awt.event.ItemEvent

     * @see           java.awt.event.ItemListener

     * @since 1.4

     */

    public synchronized ItemListener[] getItemListeners() {

        return (ItemListener[]) (getListeners(ItemListener.class));

    }

    /**

     * Returns an array of all the objects currently registered

     * as <code><em>Foo</em>Listener</code>s

     * upon this <code>Checkbox</code>.

     * <code><em>Foo</em>Listener</code>s are registered using the

     * <code>add<em>Foo</em>Listener</code> method.

     *

     * <p>

     * You can specify the <code>listenerType</code> argument

     * with a class literal, such as

     * <code><em>Foo</em>Listener.class</code>.

     * For example, you can query a

     * <code>Checkbox</code> <code>c</code>

     * for its item listeners with the following code:

     *

     * <pre>ItemListener[] ils = (ItemListener[])(c.getListeners(ItemListener.class));</pre>

     *

     * If no such listeners exist, this method returns an empty array.

     *

     * @param listenerType the type of listeners requested; this parameter

     *          should specify an interface that descends from

     *          <code>java.util.EventListener</code>

     * @return an array of all objects registered as

     *          <code><em>Foo</em>Listener</code>s on this checkbox,

     *          or an empty array if no such

     *          listeners have been added

     * @exception ClassCastException if <code>listenerType</code>

     *          doesn't specify a class or interface that implements

     *          <code>java.util.EventListener</code>

     *

     * @see #getItemListeners

     * @since 1.3

     */

    public <T extends EventListener> T[] getListeners(Class<T> listenerType) {

        EventListener l = null;

        if  (listenerType == ItemListener.class) {

            l = itemListener;

        } else {

            return super.getListeners(listenerType);

        }

        return AWTEventMulticaster.getListeners(l, listenerType);

    }

    // REMIND: remove when filtering is done at lower level

    boolean eventEnabled(AWTEvent e) {

        if (e.id == ItemEvent.ITEM_STATE_CHANGED) {

            if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||

                itemListener != null) {

                return true;

            }

            return false;

        }

        return super.eventEnabled(e);