/*
* @(#)CheckboxMenuItem.java 1.51 06/10/10
*
* Copyright 1990-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program 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.
*
* This program 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 at /legal/license.txt).
*
* 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 or visit www.sun.com if you need additional
* information or have any questions.
*
*/
package java.awt;
import sun.awt.peer.CheckboxMenuItemPeer;
import sun.awt.PeerBasedToolkit;
import java.awt.event.*;
import java.io.ObjectOutputStream;
import java.io.ObjectInputStream;
import java.io.IOException;
import java.util.EventListener;
import java.awt.AWTEventMulticaster;
/**
* This class represents a check box that can be included in a menu.
* Clicking on the check box in the menu changes its state from
* "on" to "off" or from "off" to "on."
* <p>
* The following picture depicts a menu which contains an instance
* of <code>CheckBoxMenuItem</code>:
* <p>
* <img src="doc-files/MenuBar-1.gif"
* ALIGN=center HSPACE=10 VSPACE=7>
* <p>
* The item labeled <code>Check</code> shows a check box menu item
* in its "off" state.
* <p>
* When a check box menu item is selected, AWT sends an item event to
* the item. Since the event is an instance of <code>ItemEvent</code>,
* the <code>processEvent</code> method examines the event and passes
* it along to <code>processItemEvent</code>. The latter method redirects
* the event to any <code>ItemListener</code> objects that have
* registered an interest in item events generated by this menu item.
*
* @version 1.44, 08/19/02
* @author Sami Shaio
* @see java.awt.event.ItemEvent
* @see java.awt.event.ItemListener
* @see java.awt.Frame
* @see java.awt.Menu
* @see java.awt.MenuBar
* @see java.awt.PopupMenu
* @see java.awt.MenuShortcut
* @since JDK1.0
*/
public class CheckboxMenuItem extends MenuItem implements ItemSelectable {
/*
* The state of a checkbox menu item
* @serial
* @see getState()
* @see setState()
*/
boolean state = false;
transient ItemListener itemListener;
/*
* JDK 1.1 serialVersionUID
*/
private static final long serialVersionUID = 6190621106981774043L;
/**
* Create a check box menu item with an empty label.
* The item's state is initially set to "off."
* @since JDK1.1
*/
public CheckboxMenuItem() {
this("", false);
}
/**
* Create a check box menu item with the specified label.
* The item's state is initially set to "off."
* @param label a string label for the check box menu item,
* or <code>null</code> for an unlabeled menu item.
*/
public CheckboxMenuItem(String label) {
this(label, false);
}
/**
* Create a check box menu item with the specified label and state.
* @param label a string label for the check box menu item,
* or <code>null</code> for an unlabeled menu item.
* @param state the initial state of the menu item, where
* <code>true</code> indicates "on" and
* <code>false</code> indicates "off."
* @since JDK1.1
*/
public CheckboxMenuItem(String label, boolean state) {
super(label);
this.state = state;
}
/**
* Creates the peer of the checkbox item. This peer allows us to
* change the look of the checkbox item without changing its
* functionality.
* Most applications do not call this method directly.
* @see java.awt.Toolkit#createCheckboxMenuItem(java.awt.CheckboxMenuItem)
* @see java.awt.Component#getToolkit()
* @since JDK1.0
*/
public void addNotify() {
synchronized (getTreeLock()) {
if (peer == null)
peer = ((PeerBasedToolkit) Toolkit.getDefaultToolkit()).createCheckboxMenuItem(this);
super.addNotify();
}
}
/**
* Determines whether the state of this check box menu item
* is "on" or "off."
* @return the state of this check box menu item, where
* <code>true</code> indicates "on" and
* <code>false</code> indicates "off."
* @see java.awt.CheckboxMenuItem#setState
*/
public boolean getState() {
return state;
}
/**
* Sets this check box menu item to the specifed state.
* The boolean value <code>true</code> indicates "on" while
* <code>false</code> indicates "off."
* @param b the boolean state of this
* check box menu item.
* @see java.awt.CheckboxMenuItem#getState
*/
public synchronized void setState(boolean b) {
state = b;
CheckboxMenuItemPeer peer = (CheckboxMenuItemPeer) this.peer;
if (peer != null) {
peer.setState(b);
}
}
/**
* Returns the an array (length 1) containing the checkbox menu item
* label or null if the checkbox is not selected.
* @see ItemSelectable
*/
public synchronized Object[] getSelectedObjects() {
if (state) {
Object[] items = new Object[1];
items[0] = label;
return items;
}
return null;
}
/**
* Adds the specified item listener to receive item events from
* this check box menu item.
* If l is null, no exception is thrown and no action is performed.
*
* @param l the item listener
* @see java.awt.event.ItemEvent
* @see java.awt.event.ItemListener
* @see java.awt.Choice#removeItemListener
* @since JDK1.1
*/
public synchronized void addItemListener(ItemListener l) {
itemListener = AWTEventMulticaster.add(itemListener, l);
newEventsOnly = true;
}
/**
* Removes the specified item listener so that it no longer receives
* item events from this check box menu item.
* If l is null, no exception is thrown and no action is performed.
*
* @param l the item listener
* @see java.awt.event.ItemEvent
* @see java.awt.event.ItemListener
* @see java.awt.Choice#addItemListener
* @since JDK1.1
*/
public synchronized void removeItemListener(ItemListener l) {
itemListener = AWTEventMulticaster.remove(itemListener, l);
}
/**
* Returns an array of all the item listeners
* registered on this checkbox menuitem.
*
* @return all of this checkbox menuitem'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[])AWTEventMulticaster.getListeners(
(EventListener)itemListener,
ItemListener.class);
}
// NOTE: 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);
}
/**
* Processes events on this check box menu item.
* If the event is an instance of <code>ItemEvent</code>,
* this method invokes the <code>processItemEvent</code> method.
* If the event is not an item event,
* it invokes <code>processEvent</code> on the superclass.
* <p>
* Check box menu items currently support only item events.
* @param e the event
* @see java.awt.event.ItemEvent
* @see java.awt.CheckboxMenuItem#processItemEvent
* @since JDK1.1
*/
protected void processEvent(AWTEvent e) {
if (e instanceof ItemEvent) {
processItemEvent((ItemEvent) e);
return;
}
super.processEvent(e);
}
/**
* Processes item events occurring on this check box menu item by
* dispatching them to any registered <code>ItemListener</code> objects.
* <p>
* This method is not called unless item events are
* enabled for this menu item. Item events are enabled
* when one of the following occurs:
* <p><ul>
* <li>An <code>ItemListener</code> object is registered
* via <code>addItemListener</code>.
* <li>Item events are enabled via <code>enableEvents</code>.
* </ul>
* @param e the item event.
* @see java.awt.event.ItemEvent
* @see java.awt.event.ItemListener
* @see java.awt.CheckboxMenuItem#addItemListener
* @see java.awt.MenuItem#enableEvents
* @since JDK1.1
*/
protected void processItemEvent(ItemEvent e) {
if (itemListener != null) {
itemListener.itemStateChanged(e);
}
}
/*
* Post an ItemEvent and toggle state.
*/
void doMenuEvent() {
setState(!state);
Toolkit.getEventQueue().postEvent(
new ItemEvent(this, ItemEvent.ITEM_STATE_CHANGED,
getLabel(),
state ? ItemEvent.SELECTED :
ItemEvent.DESELECTED));
}
/**
* Returns the parameter string representing the state of this check
* box menu item. This string is useful for debugging.
* @return the parameter string of this check box menu item.
*/
public String paramString() {
return super.paramString() + ",state=" + state;
}
/*
* Serial Data Version
* @serial
*/
private int checkboxMenuItemSerializedDataVersion = 1;
/**
* Writes default serializable fields to stream. Writes
* a list of serializable ItemListener(s) as optional data.
* The non-serializable ItemListner(s) are detected and
* no attempt is made to serialize them.
*
* @serialData Null terminated sequence of 0 or more pairs.
* The pair consists of a String and Object.
* The String indicates the type of object and
* is one of the following :
* itemListenerK indicating and ItemListener object.
*
* @see AWTEventMulticaster.save(ObjectOutputStream, String, EventListener)
* @see java.awt.Component.itemListenerK
*/
private void writeObject(ObjectOutputStream s)
throws java.io.IOException {
s.defaultWriteObject();
AWTEventMulticaster.save(s, itemListenerK, itemListener);
s.writeObject(null);
}
/*
* Read the ObjectInputStream and if it isnt null
* add a listener to receive item events fired
* by the Checkbox menu item.
* Unrecognised keys or values will be Ignored.
* @serial
* @see removeActionListener()
* @see addActionListener()
*/
private void readObject(ObjectInputStream s)
throws ClassNotFoundException, IOException {
s.defaultReadObject();
Object keyOrNull;
while (null != (keyOrNull = s.readObject())) {
String key = ((String) keyOrNull).intern();
if (itemListenerK == key)
addItemListener((ItemListener) (s.readObject()));
else // skip value for unrecognized key
s.readObject();
}
}
}