1 /*
2 * Copyright (c) 1995, 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 java.awt;
26
27 import java.io.IOException;
28 import java.io.ObjectInputStream;
29 import java.util.Vector;
30 import java.util.Enumeration;
31 import sun.awt.AWTAccessor;
32 import java.awt.peer.MenuBarPeer;
33 import java.awt.event.KeyEvent;
34 import javax.accessibility.*;
35
36 /**
37 * The {@code MenuBar} class encapsulates the platform's
38 * concept of a menu bar bound to a frame. In order to associate
39 * the menu bar with a {@code Frame} object, call the
40 * frame's {@code setMenuBar} method.
41 * <p>
42 * <A NAME="mbexample"></A><!-- target for cross references -->
43 * This is what a menu bar might look like:
44 * <p>
45 * <img src="doc-files/MenuBar-1.gif"
46 * alt="Diagram of MenuBar containing 2 menus: Examples and Options.
47 * Examples menu is expanded showing items: Basic, Simple, Check, and More Examples."
48 * style="float:center; margin: 7px 10px;">
49 * <p>
50 * A menu bar handles keyboard shortcuts for menu items, passing them
51 * along to its child menus.
52 * (Keyboard shortcuts, which are optional, provide the user with
53 * an alternative to the mouse for invoking a menu item and the
54 * action that is associated with it.)
55 * Each menu item can maintain an instance of {@code MenuShortcut}.
56 * The {@code MenuBar} class defines several methods,
57 * {@link MenuBar#shortcuts} and
58 * {@link MenuBar#getShortcutMenuItem}
59 * that retrieve information about the shortcuts a given
60 * menu bar is managing.
61 *
62 * @author Sami Shaio
63 * @see java.awt.Frame
64 * @see java.awt.Frame#setMenuBar(java.awt.MenuBar)
65 * @see java.awt.Menu
66 * @see java.awt.MenuItem
67 * @see java.awt.MenuShortcut
68 * @since 1.0
69 */
70 public class MenuBar extends MenuComponent implements MenuContainer, Accessible {
71
72 static {
73 /* ensure that the necessary native libraries are loaded */
74 Toolkit.loadLibraries();
75 if (!GraphicsEnvironment.isHeadless()) {
76 initIDs();
77 }
78 AWTAccessor.setMenuBarAccessor(
79 new AWTAccessor.MenuBarAccessor() {
80 public Menu getHelpMenu(MenuBar menuBar) {
81 return menuBar.helpMenu;
82 }
83
84 public Vector<Menu> getMenus(MenuBar menuBar) {
85 return menuBar.menus;
86 }
87 });
88 }
89
90 /**
91 * This field represents a vector of the
92 * actual menus that will be part of the MenuBar.
93 *
94 * @serial
95 * @see #countMenus()
96 */
97 Vector<Menu> menus = new Vector<>();
98
99 /**
100 * This menu is a special menu dedicated to
101 * help. The one thing to note about this menu
102 * is that on some platforms it appears at the
103 * right edge of the menubar.
104 *
105 * @serial
106 * @see #getHelpMenu()
107 * @see #setHelpMenu(Menu)
108 */
109 Menu helpMenu;
110
111 private static final String base = "menubar";
112 private static int nameCounter = 0;
113
114 /*
115 * JDK 1.1 serialVersionUID
116 */
117 private static final long serialVersionUID = -4930327919388951260L;
118
119 /**
120 * Creates a new menu bar.
121 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
122 * returns true.
123 * @see java.awt.GraphicsEnvironment#isHeadless
124 */
125 public MenuBar() throws HeadlessException {
126 }
127
128 /**
129 * Construct a name for this MenuComponent. Called by getName() when
130 * the name is null.
131 */
132 String constructComponentName() {
133 synchronized (MenuBar.class) {
134 return base + nameCounter++;
135 }
136 }
137
138 /**
139 * Creates the menu bar's peer. The peer allows us to change the
140 * appearance of the menu bar without changing any of the menu bar's
141 * functionality.
142 */
143 public void addNotify() {
144 synchronized (getTreeLock()) {
145 if (peer == null)
146 peer = getComponentFactory().createMenuBar(this);
147
148 int nmenus = getMenuCount();
149 for (int i = 0 ; i < nmenus ; i++) {
150 getMenu(i).addNotify();
151 }
152 }
153 }
154
155 /**
156 * Removes the menu bar's peer. The peer allows us to change the
157 * appearance of the menu bar without changing any of the menu bar's
158 * functionality.
159 */
160 public void removeNotify() {
161 synchronized (getTreeLock()) {
162 int nmenus = getMenuCount();
163 for (int i = 0 ; i < nmenus ; i++) {
164 getMenu(i).removeNotify();
165 }
166 super.removeNotify();
167 }
168 }
169
170 /**
171 * Gets the help menu on the menu bar.
172 * @return the help menu on this menu bar.
173 */
174 public Menu getHelpMenu() {
175 return helpMenu;
176 }
177
178 /**
179 * Sets the specified menu to be this menu bar's help menu.
180 * If this menu bar has an existing help menu, the old help menu is
181 * removed from the menu bar, and replaced with the specified menu.
182 * @param m the menu to be set as the help menu
183 */
184 public void setHelpMenu(final Menu m) {
185 synchronized (getTreeLock()) {
186 if (helpMenu == m) {
187 return;
188 }
189 if (helpMenu != null) {
190 remove(helpMenu);
191 }
192 helpMenu = m;
193 if (m != null) {
194 if (m.parent != this) {
195 add(m);
196 }
197 m.isHelpMenu = true;
198 m.parent = this;
199 MenuBarPeer peer = (MenuBarPeer)this.peer;
200 if (peer != null) {
201 if (m.peer == null) {
202 m.addNotify();
203 }
204 peer.addHelpMenu(m);
205 }
206 }
207 }
208 }
209
210 /**
211 * Adds the specified menu to the menu bar.
212 * If the menu has been part of another menu bar,
213 * removes it from that menu bar.
214 *
215 * @param m the menu to be added
216 * @return the menu added
217 * @see java.awt.MenuBar#remove(int)
218 * @see java.awt.MenuBar#remove(java.awt.MenuComponent)
219 */
220 public Menu add(Menu m) {
221 synchronized (getTreeLock()) {
222 if (m.parent != null) {
223 m.parent.remove(m);
224 }
225 m.parent = this;
226
227 MenuBarPeer peer = (MenuBarPeer)this.peer;
228 if (peer != null) {
229 if (m.peer == null) {
230 m.addNotify();
231 }
232 menus.addElement(m);
233 peer.addMenu(m);
234 } else {
235 menus.addElement(m);
236 }
237 return m;
238 }
239 }
240
241 /**
242 * Removes the menu located at the specified
243 * index from this menu bar.
244 * @param index the position of the menu to be removed.
245 * @see java.awt.MenuBar#add(java.awt.Menu)
246 */
247 public void remove(final int index) {
248 synchronized (getTreeLock()) {
249 Menu m = getMenu(index);
250 menus.removeElementAt(index);
251 MenuBarPeer peer = (MenuBarPeer)this.peer;
252 if (peer != null) {
253 peer.delMenu(index);
254 m.removeNotify();
255 m.parent = null;
256 }
257 if (helpMenu == m) {
258 helpMenu = null;
259 m.isHelpMenu = false;
260 }
261 }
262 }
263
264 /**
265 * Removes the specified menu component from this menu bar.
266 * @param m the menu component to be removed.
267 * @see java.awt.MenuBar#add(java.awt.Menu)
268 */
269 public void remove(MenuComponent m) {
270 synchronized (getTreeLock()) {
271 int index = menus.indexOf(m);
272 if (index >= 0) {
273 remove(index);
274 }
275 }
276 }
277
278 /**
279 * Gets the number of menus on the menu bar.
280 * @return the number of menus on the menu bar.
281 * @since 1.1
282 */
283 public int getMenuCount() {
284 return countMenus();
285 }
286
287 /**
288 * Gets the number of menus on the menu bar.
289 *
290 * @return the number of menus on the menu bar.
291 * @deprecated As of JDK version 1.1,
292 * replaced by {@code getMenuCount()}.
293 */
294 @Deprecated
295 public int countMenus() {
296 return getMenuCountImpl();
297 }
298
299 /*
300 * This is called by the native code, so client code can't
301 * be called on the toolkit thread.
302 */
303 final int getMenuCountImpl() {
304 return menus.size();
305 }
306
307 /**
308 * Gets the specified menu.
309 * @param i the index position of the menu to be returned.
310 * @return the menu at the specified index of this menu bar.
311 */
312 public Menu getMenu(int i) {
313 return getMenuImpl(i);
314 }
315
316 /*
317 * This is called by the native code, so client code can't
318 * be called on the toolkit thread.
319 */
320 final Menu getMenuImpl(int i) {
321 return menus.elementAt(i);
322 }
323
324 /**
325 * Gets an enumeration of all menu shortcuts this menu bar
326 * is managing.
327 * @return an enumeration of menu shortcuts that this
328 * menu bar is managing.
329 * @see java.awt.MenuShortcut
330 * @since 1.1
331 */
332 public synchronized Enumeration<MenuShortcut> shortcuts() {
333 Vector<MenuShortcut> shortcuts = new Vector<>();
334 int nmenus = getMenuCount();
335 for (int i = 0 ; i < nmenus ; i++) {
336 Enumeration<MenuShortcut> e = getMenu(i).shortcuts();
337 while (e.hasMoreElements()) {
338 shortcuts.addElement(e.nextElement());
339 }
340 }
341 return shortcuts.elements();
342 }
343
344 /**
345 * Gets the instance of {@code MenuItem} associated
346 * with the specified {@code MenuShortcut} object,
347 * or {@code null} if none of the menu items being managed
348 * by this menu bar is associated with the specified menu
349 * shortcut.
350 * @param s the specified menu shortcut.
351 * @return the menu item for the specified shortcut.
352 * @see java.awt.MenuItem
353 * @see java.awt.MenuShortcut
354 * @since 1.1
355 */
356 public MenuItem getShortcutMenuItem(MenuShortcut s) {
357 int nmenus = getMenuCount();
358 for (int i = 0 ; i < nmenus ; i++) {
359 MenuItem mi = getMenu(i).getShortcutMenuItem(s);
360 if (mi != null) {
361 return mi;
362 }
363 }
364 return null; // MenuShortcut wasn't found
365 }
366
367 /*
368 * Post an ACTION_EVENT to the target of the MenuPeer
369 * associated with the specified keyboard event (on
370 * keydown). Returns true if there is an associated
371 * keyboard event.
372 */
373 boolean handleShortcut(KeyEvent e) {
374 // Is it a key event?
375 int id = e.getID();
376 if (id != KeyEvent.KEY_PRESSED && id != KeyEvent.KEY_RELEASED) {
377 return false;
378 }
379
380 // Is the accelerator modifier key pressed?
381 int accelKey = Toolkit.getDefaultToolkit().getMenuShortcutKeyMask();
382 if ((e.getModifiers() & accelKey) == 0) {
383 return false;
384 }
385
386 // Pass MenuShortcut on to child menus.
387 int nmenus = getMenuCount();
388 for (int i = 0 ; i < nmenus ; i++) {
389 Menu m = getMenu(i);
390 if (m.handleShortcut(e)) {
391 return true;
392 }
393 }
394 return false;
395 }
396
397 /**
398 * Deletes the specified menu shortcut.
399 * @param s the menu shortcut to delete.
400 * @since 1.1
401 */
402 public void deleteShortcut(MenuShortcut s) {
403 int nmenus = getMenuCount();
404 for (int i = 0 ; i < nmenus ; i++) {
405 getMenu(i).deleteShortcut(s);
406 }
407 }
408
409 /* Serialization support. Restore the (transient) parent
410 * fields of Menubar menus here.
411 */
412
413 /**
414 * The MenuBar's serialized data version.
415 *
416 * @serial
417 */
418 private int menuBarSerializedDataVersion = 1;
419
420 /**
421 * Writes default serializable fields to stream.
422 *
423 * @param s the {@code ObjectOutputStream} to write
424 * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
425 * @see #readObject(java.io.ObjectInputStream)
426 */
427 private void writeObject(java.io.ObjectOutputStream s)
428 throws java.lang.ClassNotFoundException,
429 java.io.IOException
430 {
431 s.defaultWriteObject();
432 }
433
434 /**
435 * Reads the {@code ObjectInputStream}.
436 * Unrecognized keys or values will be ignored.
437 *
438 * @param s the {@code ObjectInputStream} to read
439 * @exception HeadlessException if
440 * {@code GraphicsEnvironment.isHeadless} returns
441 * {@code true}
442 * @see java.awt.GraphicsEnvironment#isHeadless
443 * @see #writeObject(java.io.ObjectOutputStream)
444 */
445 private void readObject(ObjectInputStream s)
446 throws ClassNotFoundException, IOException, HeadlessException
447 {
448 // HeadlessException will be thrown from MenuComponent's readObject
449 s.defaultReadObject();
450 for (int i = 0; i < menus.size(); i++) {
451 Menu m = menus.elementAt(i);
452 m.parent = this;
453 }
454 }
455
456 /**
457 * Initialize JNI field and method IDs
458 */
459 private static native void initIDs();
460
461
462 /////////////////
463 // Accessibility support
464 ////////////////
465
466 /**
467 * Gets the AccessibleContext associated with this MenuBar.
468 * For menu bars, the AccessibleContext takes the form of an
469 * AccessibleAWTMenuBar.
470 * A new AccessibleAWTMenuBar instance is created if necessary.
471 *
472 * @return an AccessibleAWTMenuBar that serves as the
473 * AccessibleContext of this MenuBar
474 * @since 1.3
475 */
476 public AccessibleContext getAccessibleContext() {
477 if (accessibleContext == null) {
478 accessibleContext = new AccessibleAWTMenuBar();
479 }
480 return accessibleContext;
481 }
482
483 /**
484 * Defined in MenuComponent. Overridden here.
485 */
486 int getAccessibleChildIndex(MenuComponent child) {
487 return menus.indexOf(child);
488 }
489
490 /**
491 * Inner class of MenuBar used to provide default support for
492 * accessibility. This class is not meant to be used directly by
493 * application developers, but is instead meant only to be
494 * subclassed by menu component developers.
495 * <p>
496 * This class implements accessibility support for the
497 * {@code MenuBar} class. It provides an implementation of the
498 * Java Accessibility API appropriate to menu bar user-interface elements.
499 * @since 1.3
500 */
501 protected class AccessibleAWTMenuBar extends AccessibleAWTMenuComponent
502 {
503 /*
504 * JDK 1.3 serialVersionUID
505 */
506 private static final long serialVersionUID = -8577604491830083815L;
507
508 /**
509 * Get the role of this object.
510 *
511 * @return an instance of AccessibleRole describing the role of the
512 * object
513 * @since 1.4
514 */
515 public AccessibleRole getAccessibleRole() {
516 return AccessibleRole.MENU_BAR;
517 }
518
519 } // class AccessibleAWTMenuBar
520
521 }