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</code> 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</code> object, call the
40 * frame's <code>setMenuBar</code> 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</code>.
56 * The <code>MenuBar</code> 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 = Toolkit.getDefaultToolkit().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 menus.addElement(m);
226 m.parent = this;
227
228 MenuBarPeer peer = (MenuBarPeer)this.peer;
229 if (peer != null) {
230 if (m.peer == null) {
231 m.addNotify();
232 }
233 peer.addMenu(m);
234 }
235 return m;
236 }
237 }
238
239 /**
240 * Removes the menu located at the specified
241 * index from this menu bar.
242 * @param index the position of the menu to be removed.
243 * @see java.awt.MenuBar#add(java.awt.Menu)
244 */
245 public void remove(final int index) {
246 synchronized (getTreeLock()) {
247 Menu m = getMenu(index);
248 menus.removeElementAt(index);
249 MenuBarPeer peer = (MenuBarPeer)this.peer;
250 if (peer != null) {
251 m.removeNotify();
252 m.parent = null;
253 peer.delMenu(index);
254 }
255 if (helpMenu == m) {
256 helpMenu = null;
257 m.isHelpMenu = false;
258 }
259 }
260 }
261
262 /**
263 * Removes the specified menu component from this menu bar.
264 * @param m the menu component to be removed.
265 * @see java.awt.MenuBar#add(java.awt.Menu)
266 */
267 public void remove(MenuComponent m) {
268 synchronized (getTreeLock()) {
269 int index = menus.indexOf(m);
270 if (index >= 0) {
271 remove(index);
272 }
273 }
274 }
275
276 /**
277 * Gets the number of menus on the menu bar.
278 * @return the number of menus on the menu bar.
279 * @since 1.1
280 */
281 public int getMenuCount() {
282 return countMenus();
283 }
284
285 /**
286 * Gets the number of menus on the menu bar.
287 *
288 * @return the number of menus on the menu bar.
289 * @deprecated As of JDK version 1.1,
290 * replaced by <code>getMenuCount()</code>.
291 */
292 @Deprecated
293 public int countMenus() {
294 return getMenuCountImpl();
295 }
296
297 /*
298 * This is called by the native code, so client code can't
299 * be called on the toolkit thread.
300 */
301 final int getMenuCountImpl() {
302 return menus.size();
303 }
304
305 /**
306 * Gets the specified menu.
307 * @param i the index position of the menu to be returned.
308 * @return the menu at the specified index of this menu bar.
309 */
310 public Menu getMenu(int i) {
311 return getMenuImpl(i);
312 }
313
314 /*
315 * This is called by the native code, so client code can't
316 * be called on the toolkit thread.
317 */
318 final Menu getMenuImpl(int i) {
319 return menus.elementAt(i);
320 }
321
322 /**
323 * Gets an enumeration of all menu shortcuts this menu bar
324 * is managing.
325 * @return an enumeration of menu shortcuts that this
326 * menu bar is managing.
327 * @see java.awt.MenuShortcut
328 * @since 1.1
329 */
330 public synchronized Enumeration<MenuShortcut> shortcuts() {
331 Vector<MenuShortcut> shortcuts = new Vector<>();
332 int nmenus = getMenuCount();
333 for (int i = 0 ; i < nmenus ; i++) {
334 Enumeration<MenuShortcut> e = getMenu(i).shortcuts();
335 while (e.hasMoreElements()) {
336 shortcuts.addElement(e.nextElement());
337 }
338 }
339 return shortcuts.elements();
340 }
341
342 /**
343 * Gets the instance of <code>MenuItem</code> associated
344 * with the specified <code>MenuShortcut</code> object,
345 * or <code>null</code> if none of the menu items being managed
346 * by this menu bar is associated with the specified menu
347 * shortcut.
348 * @param s the specified menu shortcut.
349 * @return the menu item for the specified shortcut.
350 * @see java.awt.MenuItem
351 * @see java.awt.MenuShortcut
352 * @since 1.1
353 */
354 public MenuItem getShortcutMenuItem(MenuShortcut s) {
355 int nmenus = getMenuCount();
356 for (int i = 0 ; i < nmenus ; i++) {
357 MenuItem mi = getMenu(i).getShortcutMenuItem(s);
358 if (mi != null) {
359 return mi;
360 }
361 }
362 return null; // MenuShortcut wasn't found
363 }
364
365 /*
366 * Post an ACTION_EVENT to the target of the MenuPeer
367 * associated with the specified keyboard event (on
368 * keydown). Returns true if there is an associated
369 * keyboard event.
370 */
371 boolean handleShortcut(KeyEvent e) {
372 // Is it a key event?
373 int id = e.getID();
374 if (id != KeyEvent.KEY_PRESSED && id != KeyEvent.KEY_RELEASED) {
375 return false;
376 }
377
378 // Is the accelerator modifier key pressed?
379 int accelKey = Toolkit.getDefaultToolkit().getMenuShortcutKeyMask();
380 if ((e.getModifiers() & accelKey) == 0) {
381 return false;
382 }
383
384 // Pass MenuShortcut on to child menus.
385 int nmenus = getMenuCount();
386 for (int i = 0 ; i < nmenus ; i++) {
387 Menu m = getMenu(i);
388 if (m.handleShortcut(e)) {
389 return true;
390 }
391 }
392 return false;
393 }
394
395 /**
396 * Deletes the specified menu shortcut.
397 * @param s the menu shortcut to delete.
398 * @since 1.1
399 */
400 public void deleteShortcut(MenuShortcut s) {
401 int nmenus = getMenuCount();
402 for (int i = 0 ; i < nmenus ; i++) {
403 getMenu(i).deleteShortcut(s);
404 }
405 }
406
407 /* Serialization support. Restore the (transient) parent
408 * fields of Menubar menus here.
409 */
410
411 /**
412 * The MenuBar's serialized data version.
413 *
414 * @serial
415 */
416 private int menuBarSerializedDataVersion = 1;
417
418 /**
419 * Writes default serializable fields to stream.
420 *
421 * @param s the <code>ObjectOutputStream</code> to write
422 * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
423 * @see #readObject(java.io.ObjectInputStream)
424 */
425 private void writeObject(java.io.ObjectOutputStream s)
426 throws java.lang.ClassNotFoundException,
427 java.io.IOException
428 {
429 s.defaultWriteObject();
430 }
431
432 /**
433 * Reads the <code>ObjectInputStream</code>.
434 * Unrecognized keys or values will be ignored.
435 *
436 * @param s the <code>ObjectInputStream</code> to read
437 * @exception HeadlessException if
438 * <code>GraphicsEnvironment.isHeadless</code> returns
439 * <code>true</code>
440 * @see java.awt.GraphicsEnvironment#isHeadless
441 * @see #writeObject(java.io.ObjectOutputStream)
442 */
443 private void readObject(ObjectInputStream s)
444 throws ClassNotFoundException, IOException, HeadlessException
445 {
446 // HeadlessException will be thrown from MenuComponent's readObject
447 s.defaultReadObject();
448 for (int i = 0; i < menus.size(); i++) {
449 Menu m = menus.elementAt(i);
450 m.parent = this;
451 }
452 }
453
454 /**
455 * Initialize JNI field and method IDs
456 */
457 private static native void initIDs();
458
459
460 /////////////////
461 // Accessibility support
462 ////////////////
463
464 /**
465 * Gets the AccessibleContext associated with this MenuBar.
466 * For menu bars, the AccessibleContext takes the form of an
467 * AccessibleAWTMenuBar.
468 * A new AccessibleAWTMenuBar instance is created if necessary.
469 *
470 * @return an AccessibleAWTMenuBar that serves as the
471 * AccessibleContext of this MenuBar
472 * @since 1.3
473 */
474 public AccessibleContext getAccessibleContext() {
475 if (accessibleContext == null) {
476 accessibleContext = new AccessibleAWTMenuBar();
477 }
478 return accessibleContext;
479 }
480
481 /**
482 * Defined in MenuComponent. Overridden here.
483 */
484 int getAccessibleChildIndex(MenuComponent child) {
485 return menus.indexOf(child);
486 }
487
488 /**
489 * Inner class of MenuBar used to provide default support for
490 * accessibility. This class is not meant to be used directly by
491 * application developers, but is instead meant only to be
492 * subclassed by menu component developers.
493 * <p>
494 * This class implements accessibility support for the
495 * <code>MenuBar</code> class. It provides an implementation of the
496 * Java Accessibility API appropriate to menu bar user-interface elements.
497 * @since 1.3
498 */
499 protected class AccessibleAWTMenuBar extends AccessibleAWTMenuComponent
500 {
501 /*
502 * JDK 1.3 serialVersionUID
503 */
504 private static final long serialVersionUID = -8577604491830083815L;
505
506 /**
507 * Get the role of this object.
508 *
509 * @return an instance of AccessibleRole describing the role of the
510 * object
511 * @since 1.4
512 */
513 public AccessibleRole getAccessibleRole() {
514 return AccessibleRole.MENU_BAR;
515 }
516
517 } // class AccessibleAWTMenuBar
518
519 }