1 /*
2 * Copyright (c) 1997, 2014, 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 javax.swing;
26
27 import java.util.EventListener;
28
29 import java.awt.*;
30 import java.awt.event.*;
31 import java.awt.image.*;
32
33 import java.io.ObjectOutputStream;
34 import java.io.ObjectInputStream;
35 import java.io.IOException;
36
37 import javax.swing.plaf.*;
38 import javax.accessibility.*;
39
40
41 /**
42 * A menu item that can be selected or deselected. If selected, the menu
43 * item typically appears with a checkmark next to it. If unselected or
44 * deselected, the menu item appears without a checkmark. Like a regular
45 * menu item, a check box menu item can have either text or a graphic
46 * icon associated with it, or both.
47 * <p>
48 * Either <code>isSelected</code>/<code>setSelected</code> or
49 * <code>getState</code>/<code>setState</code> can be used
50 * to determine/specify the menu item's selection state. The
51 * preferred methods are <code>isSelected</code> and
52 * <code>setSelected</code>, which work for all menus and buttons.
53 * The <code>getState</code> and <code>setState</code> methods exist for
54 * compatibility with other component sets.
55 * <p>
56 * Menu items can be configured, and to some degree controlled, by
57 * <code><a href="Action.html">Action</a></code>s. Using an
58 * <code>Action</code> with a menu item has many benefits beyond directly
59 * configuring a menu item. Refer to <a href="Action.html#buttonActions">
60 * Swing Components Supporting <code>Action</code></a> for more
61 * details, and you can find more information in <a
62 * href="http://docs.oracle.com/javase/tutorial/uiswing/misc/action.html">How
63 * to Use Actions</a>, a section in <em>The Java Tutorial</em>.
64 * <p>
65 * For further information and examples of using check box menu items,
66 * see <a
67 href="http://docs.oracle.com/javase/tutorial/uiswing/components/menu.html">How to Use Menus</a>,
68 * a section in <em>The Java Tutorial.</em>
69 * <p>
70 * <strong>Warning:</strong> Swing is not thread safe. For more
71 * information see <a
72 * href="package-summary.html#threading">Swing's Threading
73 * Policy</a>.
74 * <p>
75 * <strong>Warning:</strong>
76 * Serialized objects of this class will not be compatible with
77 * future Swing releases. The current serialization support is
78 * appropriate for short term storage or RMI between applications running
79 * the same version of Swing. As of 1.4, support for long term storage
80 * of all JavaBeans™
81 * has been added to the <code>java.beans</code> package.
82 * Please see {@link java.beans.XMLEncoder}.
83 *
84 * @beaninfo
85 * attribute: isContainer false
86 * description: A menu item which can be selected or deselected.
87 *
88 * @author Georges Saab
89 * @author David Karlton
90 * @since 1.2
91 */
92 @SuppressWarnings("serial") // Same-version serialization only
93 public class JCheckBoxMenuItem extends JMenuItem implements SwingConstants,
94 Accessible
95 {
96 /**
97 * @see #getUIClassID
98 * @see #readObject
99 */
100 private static final String uiClassID = "CheckBoxMenuItemUI";
101
102 /**
103 * Creates an initially unselected check box menu item with no set text or icon.
104 */
105 public JCheckBoxMenuItem() {
106 this(null, null, false);
107 }
108
109 /**
110 * Creates an initially unselected check box menu item with an icon.
111 *
112 * @param icon the icon of the {@code JCheckBoxMenuItem}.
113 */
114 public JCheckBoxMenuItem(Icon icon) {
115 this(null, icon, false);
116 }
117
118 /**
119 * Creates an initially unselected check box menu item with text.
120 *
121 * @param text the text of the {@code JCheckBoxMenuItem}
122 */
123 public JCheckBoxMenuItem(String text) {
124 this(text, null, false);
125 }
126
127 /**
128 * Creates a menu item whose properties are taken from the
129 * Action supplied.
130 *
131 * @param a the action of the {@code JCheckBoxMenuItem}
132 * @since 1.3
133 */
134 public JCheckBoxMenuItem(Action a) {
135 this();
136 setAction(a);
137 }
138
139 /**
140 * Creates an initially unselected check box menu item with the specified text and icon.
141 *
142 * @param text the text of the {@code JCheckBoxMenuItem}
143 * @param icon the icon of the {@code JCheckBoxMenuItem}
144 */
145 public JCheckBoxMenuItem(String text, Icon icon) {
146 this(text, icon, false);
147 }
148
149 /**
150 * Creates a check box menu item with the specified text and selection state.
151 *
152 * @param text the text of the check box menu item.
153 * @param b the selected state of the check box menu item
154 */
155 public JCheckBoxMenuItem(String text, boolean b) {
156 this(text, null, b);
157 }
158
159 /**
160 * Creates a check box menu item with the specified text, icon, and selection state.
161 *
162 * @param text the text of the check box menu item
163 * @param icon the icon of the check box menu item
164 * @param b the selected state of the check box menu item
165 */
166 public JCheckBoxMenuItem(String text, Icon icon, boolean b) {
167 super(text, icon);
168 setModel(new JToggleButton.ToggleButtonModel());
169 setSelected(b);
170 setFocusable(false);
171 }
172
173 /**
174 * Returns the name of the L&F class
175 * that renders this component.
176 *
177 * @return "CheckBoxMenuItemUI"
178 * @see JComponent#getUIClassID
179 * @see UIDefaults#getUI
180 */
181 public String getUIClassID() {
182 return uiClassID;
183 }
184
185 /**
186 * Returns the selected-state of the item. This method
187 * exists for AWT compatibility only. New code should
188 * use isSelected() instead.
189 *
190 * @return true if the item is selected
191 */
192 public boolean getState() {
193 return isSelected();
194 }
195
196 /**
197 * Sets the selected-state of the item. This method
198 * exists for AWT compatibility only. New code should
199 * use setSelected() instead.
200 *
201 * @param b a boolean value indicating the item's
202 * selected-state, where true=selected
203 * @beaninfo
204 * description: The selection state of the check box menu item
205 * hidden: true
206 */
207 public synchronized void setState(boolean b) {
208 setSelected(b);
209 }
210
211
212 /**
213 * Returns an array (length 1) containing the check box menu item
214 * label or null if the check box is not selected.
215 *
216 * @return an array containing one Object -- the text of the menu item
217 * -- if the item is selected; otherwise null
218 */
219 public Object[] getSelectedObjects() {
220 if (isSelected() == false)
221 return null;
222 Object[] selectedObjects = new Object[1];
223 selectedObjects[0] = getText();
224 return selectedObjects;
225 }
226
227 /**
228 * See readObject() and writeObject() in JComponent for more
229 * information about serialization in Swing.
230 */
231 private void writeObject(ObjectOutputStream s) throws IOException {
232 s.defaultWriteObject();
233 if (getUIClassID().equals(uiClassID)) {
234 byte count = JComponent.getWriteObjCounter(this);
235 JComponent.setWriteObjCounter(this, --count);
236 if (count == 0 && ui != null) {
237 ui.installUI(this);
238 }
239 }
240 }
241
242
243 /**
244 * Returns a string representation of this JCheckBoxMenuItem. This method
245 * is intended to be used only for debugging purposes, and the
246 * content and format of the returned string may vary between
247 * implementations. The returned string may be empty but may not
248 * be <code>null</code>.
249 *
250 * @return a string representation of this JCheckBoxMenuItem.
251 */
252 protected String paramString() {
253 return super.paramString();
254 }
255
256 /**
257 * Overriden to return true, JCheckBoxMenuItem supports
258 * the selected state.
259 */
260 boolean shouldUpdateSelectedStateFromAction() {
261 return true;
262 }
263
264 /////////////////
265 // Accessibility support
266 ////////////////
267
268 /**
269 * Gets the AccessibleContext associated with this JCheckBoxMenuItem.
270 * For JCheckBoxMenuItems, the AccessibleContext takes the form of an
271 * AccessibleJCheckBoxMenuItem.
272 * A new AccessibleJCheckBoxMenuItem instance is created if necessary.
273 *
274 * @return an AccessibleJCheckBoxMenuItem that serves as the
275 * AccessibleContext of this AccessibleJCheckBoxMenuItem
276 */
277 public AccessibleContext getAccessibleContext() {
278 if (accessibleContext == null) {
279 accessibleContext = new AccessibleJCheckBoxMenuItem();
280 }
281 return accessibleContext;
282 }
283
284 /**
285 * This class implements accessibility support for the
286 * <code>JCheckBoxMenuItem</code> class. It provides an implementation
287 * of the Java Accessibility API appropriate to checkbox menu item
288 * user-interface elements.
289 * <p>
290 * <strong>Warning:</strong>
291 * Serialized objects of this class will not be compatible with
292 * future Swing releases. The current serialization support is
293 * appropriate for short term storage or RMI between applications running
294 * the same version of Swing. As of 1.4, support for long term storage
295 * of all JavaBeans™
296 * has been added to the <code>java.beans</code> package.
297 * Please see {@link java.beans.XMLEncoder}.
298 */
299 @SuppressWarnings("serial") // Same-version serialization only
300 protected class AccessibleJCheckBoxMenuItem extends AccessibleJMenuItem {
301 /**
302 * Get the role of this object.
303 *
304 * @return an instance of AccessibleRole describing the role of the
305 * object
306 */
307 public AccessibleRole getAccessibleRole() {
308 return AccessibleRole.CHECK_BOX;
309 }
310 } // inner class AccessibleJCheckBoxMenuItem
311 }