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