001 /*
002 * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package java.awt;
026
027 import java.io.IOException;
028 import java.io.ObjectInputStream;
029 import java.util.Vector;
030 import java.util.Enumeration;
031 import java.awt.peer.MenuBarPeer;
032 import java.awt.event.KeyEvent;
033 import javax.accessibility.*;
034
035 /**
036 * The <code>MenuBar</code> class encapsulates the platform's
037 * concept of a menu bar bound to a frame. In order to associate
038 * the menu bar with a <code>Frame</code> object, call the
039 * frame's <code>setMenuBar</code> method.
040 * <p>
041 * <A NAME="mbexample"></A><!-- target for cross references -->
042 * This is what a menu bar might look like:
043 * <p>
044 * <img src="doc-files/MenuBar-1.gif"
045 * <alt="Diagram of MenuBar containing 2 menus: Examples and Options.
046 * Examples menu is expanded showing items: Basic, Simple, Check, and More Examples."
047 * ALIGN=center HSPACE=10 VSPACE=7>
048 * <p>
049 * A menu bar handles keyboard shortcuts for menu items, passing them
050 * along to its child menus.
051 * (Keyboard shortcuts, which are optional, provide the user with
052 * an alternative to the mouse for invoking a menu item and the
053 * action that is associated with it.)
054 * Each menu item can maintain an instance of <code>MenuShortcut</code>.
055 * The <code>MenuBar</code> class defines several methods,
056 * {@link MenuBar#shortcuts} and
057 * {@link MenuBar#getShortcutMenuItem}
058 * that retrieve information about the shortcuts a given
059 * menu bar is managing.
060 *
061 * @version 1.79, 05/05/07
062 * @author Sami Shaio
063 * @see java.awt.Frame
064 * @see java.awt.Frame#setMenuBar(java.awt.MenuBar)
065 * @see java.awt.Menu
066 * @see java.awt.MenuItem
067 * @see java.awt.MenuShortcut
068 * @since JDK1.0
069 */
070 public class MenuBar extends MenuComponent implements MenuContainer,
071 Accessible {
072
073 static {
074 /* ensure that the necessary native libraries are loaded */
075 Toolkit.loadLibraries();
076 if (!GraphicsEnvironment.isHeadless()) {
077 initIDs();
078 }
079 }
080
081 /**
082 * This field represents a vector of the
083 * actual menus that will be part of the MenuBar.
084 *
085 * @serial
086 * @see #countMenus()
087 */
088 Vector menus = new Vector();
089
090 /**
091 * This menu is a special menu dedicated to
092 * help. The one thing to note about this menu
093 * is that on some platforms it appears at the
094 * right edge of the menubar.
095 *
096 * @serial
097 * @see #getHelpMenu()
098 * @see #setHelpMenu(Menu)
099 */
100 Menu helpMenu;
101
102 private static final String base = "menubar";
103 private static int nameCounter = 0;
104
105 /*
106 * JDK 1.1 serialVersionUID
107 */
108 private static final long serialVersionUID = -4930327919388951260L;
109
110 /**
111 * Creates a new menu bar.
112 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
113 * returns true.
114 * @see java.awt.GraphicsEnvironment#isHeadless
115 */
116 public MenuBar() throws HeadlessException {
117 }
118
119 /**
120 * Construct a name for this MenuComponent. Called by getName() when
121 * the name is null.
122 */
123 String constructComponentName() {
124 synchronized (MenuBar.class) {
125 return base + nameCounter++;
126 }
127 }
128
129 /**
130 * Creates the menu bar's peer. The peer allows us to change the
131 * appearance of the menu bar without changing any of the menu bar's
132 * functionality.
133 */
134 public void addNotify() {
135 synchronized (getTreeLock()) {
136 if (peer == null)
137 peer = Toolkit.getDefaultToolkit().createMenuBar(this );
138
139 int nmenus = getMenuCount();
140 for (int i = 0; i < nmenus; i++) {
141 getMenu(i).addNotify();
142 }
143 }
144 }
145
146 /**
147 * Removes the menu bar's peer. The peer allows us to change the
148 * appearance of the menu bar without changing any of the menu bar's
149 * functionality.
150 */
151 public void removeNotify() {
152 synchronized (getTreeLock()) {
153 int nmenus = getMenuCount();
154 for (int i = 0; i < nmenus; i++) {
155 getMenu(i).removeNotify();
156 }
157 super .removeNotify();
158 }
159 }
160
161 /**
162 * Gets the help menu on the menu bar.
163 * @return the help menu on this menu bar.
164 */
165 public Menu getHelpMenu() {
166 return helpMenu;
167 }
168
169 /**
170 * Sets the specified menu to be this menu bar's help menu.
171 * If this menu bar has an existing help menu, the old help menu is
172 * removed from the menu bar, and replaced with the specified menu.
173 * @param m the menu to be set as the help menu
174 */
175 public void setHelpMenu(Menu m) {
176 synchronized (getTreeLock()) {
177 if (helpMenu == m) {
178 return;
179 }
180 if (helpMenu != null) {
181 remove(helpMenu);
182 }
183 if (m.parent != this ) {
184 add(m);
185 }
186 helpMenu = m;
187 if (m != null) {
188 m.isHelpMenu = true;
189 m.parent = this ;
190 MenuBarPeer peer = (MenuBarPeer) this .peer;
191 if (peer != null) {
192 if (m.peer == null) {
193 m.addNotify();
194 }
195 peer.addHelpMenu(m);
196 }
197 }
198 }
199 }
200
201 /**
202 * Adds the specified menu to the menu bar.
203 * If the menu has been part of another menu bar,
204 * removes it from that menu bar.
205 *
206 * @param m the menu to be added
207 * @return the menu added
208 * @see java.awt.MenuBar#remove(int)
209 * @see java.awt.MenuBar#remove(java.awt.MenuComponent)
210 */
211 public Menu add(Menu m) {
212 synchronized (getTreeLock()) {
213 if (m.parent != null) {
214 m.parent.remove(m);
215 }
216 menus.addElement(m);
217 m.parent = this ;
218
219 MenuBarPeer peer = (MenuBarPeer) this .peer;
220 if (peer != null) {
221 if (m.peer == null) {
222 m.addNotify();
223 }
224 peer.addMenu(m);
225 }
226 return m;
227 }
228 }
229
230 /**
231 * Removes the menu located at the specified
232 * index from this menu bar.
233 * @param index the position of the menu to be removed.
234 * @see java.awt.MenuBar#add(java.awt.Menu)
235 */
236 public void remove(int index) {
237 synchronized (getTreeLock()) {
238 Menu m = getMenu(index);
239 menus.removeElementAt(index);
240 MenuBarPeer peer = (MenuBarPeer) this .peer;
241 if (peer != null) {
242 m.removeNotify();
243 m.parent = null;
244 peer.delMenu(index);
245 }
246 }
247 }
248
249 /**
250 * Removes the specified menu component from this menu bar.
251 * @param m the menu component to be removed.
252 * @see java.awt.MenuBar#add(java.awt.Menu)
253 */
254 public void remove(MenuComponent m) {
255 synchronized (getTreeLock()) {
256 int index = menus.indexOf(m);
257 if (index >= 0) {
258 remove(index);
259 }
260 }
261 }
262
263 /**
264 * Gets the number of menus on the menu bar.
265 * @return the number of menus on the menu bar.
266 * @since JDK1.1
267 */
268 public int getMenuCount() {
269 return countMenus();
270 }
271
272 /**
273 * @deprecated As of JDK version 1.1,
274 * replaced by <code>getMenuCount()</code>.
275 */
276 @Deprecated
277 public int countMenus() {
278 return getMenuCountImpl();
279 }
280
281 /*
282 * This is called by the native code, so client code can't
283 * be called on the toolkit thread.
284 */
285 final int getMenuCountImpl() {
286 return menus.size();
287 }
288
289 /**
290 * Gets the specified menu.
291 * @param i the index position of the menu to be returned.
292 * @return the menu at the specified index of this menu bar.
293 */
294 public Menu getMenu(int i) {
295 return getMenuImpl(i);
296 }
297
298 /*
299 * This is called by the native code, so client code can't
300 * be called on the toolkit thread.
301 */
302 final Menu getMenuImpl(int i) {
303 return (Menu) menus.elementAt(i);
304 }
305
306 /**
307 * Gets an enumeration of all menu shortcuts this menu bar
308 * is managing.
309 * @return an enumeration of menu shortcuts that this
310 * menu bar is managing.
311 * @see java.awt.MenuShortcut
312 * @since JDK1.1
313 */
314 public synchronized Enumeration<MenuShortcut> shortcuts() {
315 Vector shortcuts = new Vector();
316 int nmenus = getMenuCount();
317 for (int i = 0; i < nmenus; i++) {
318 Enumeration e = getMenu(i).shortcuts();
319 while (e.hasMoreElements()) {
320 shortcuts.addElement(e.nextElement());
321 }
322 }
323 return shortcuts.elements();
324 }
325
326 /**
327 * Gets the instance of <code>MenuItem</code> associated
328 * with the specified <code>MenuShortcut</code> object,
329 * or <code>null</code> if none of the menu items being managed
330 * by this menu bar is associated with the specified menu
331 * shortcut.
332 * @param s the specified menu shortcut.
333 * @see java.awt.MenuItem
334 * @see java.awt.MenuShortcut
335 * @since JDK1.1
336 */
337 public MenuItem getShortcutMenuItem(MenuShortcut s) {
338 int nmenus = getMenuCount();
339 for (int i = 0; i < nmenus; i++) {
340 MenuItem mi = getMenu(i).getShortcutMenuItem(s);
341 if (mi != null) {
342 return mi;
343 }
344 }
345 return null; // MenuShortcut wasn't found
346 }
347
348 /*
349 * Post an ACTION_EVENT to the target of the MenuPeer
350 * associated with the specified keyboard event (on
351 * keydown). Returns true if there is an associated
352 * keyboard event.
353 */
354 boolean handleShortcut(KeyEvent e) {
355 // Is it a key event?
356 int id = e.getID();
357 if (id != KeyEvent.KEY_PRESSED && id != KeyEvent.KEY_RELEASED) {
358 return false;
359 }
360
361 // Is the accelerator modifier key pressed?
362 int accelKey = Toolkit.getDefaultToolkit()
363 .getMenuShortcutKeyMask();
364 if ((e.getModifiers() & accelKey) == 0) {
365 return false;
366 }
367
368 // Pass MenuShortcut on to child menus.
369 int nmenus = getMenuCount();
370 for (int i = 0; i < nmenus; i++) {
371 Menu m = getMenu(i);
372 if (m.handleShortcut(e)) {
373 return true;
374 }
375 }
376 return false;
377 }
378
379 /**
380 * Deletes the specified menu shortcut.
381 * @param s the menu shortcut to delete.
382 * @since JDK1.1
383 */
384 public void deleteShortcut(MenuShortcut s) {
385 int nmenus = getMenuCount();
386 for (int i = 0; i < nmenus; i++) {
387 getMenu(i).deleteShortcut(s);
388 }
389 }
390
391 /* Serialization support. Restore the (transient) parent
392 * fields of Menubar menus here.
393 */
394
395 /**
396 * The MenuBar's serialized data version.
397 *
398 * @serial
399 */
400 private int menuBarSerializedDataVersion = 1;
401
402 /**
403 * Writes default serializable fields to stream.
404 *
405 * @param s the <code>ObjectOutputStream</code> to write
406 * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
407 * @see #readObject(java.io.ObjectInputStream)
408 */
409 private void writeObject(java.io.ObjectOutputStream s)
410 throws java.lang.ClassNotFoundException,
411 java.io.IOException {
412 s.defaultWriteObject();
413 }
414
415 /**
416 * Reads the <code>ObjectInputStream</code>.
417 * Unrecognized keys or values will be ignored.
418 *
419 * @param s the <code>ObjectInputStream</code> to read
420 * @exception HeadlessException if
421 * <code>GraphicsEnvironment.isHeadless</code> returns
422 * <code>true</code>
423 * @see java.awt.GraphicsEnvironment#isHeadless
424 * @see #writeObject(java.io.ObjectOutputStream)
425 */
426 private void readObject(ObjectInputStream s)
427 throws ClassNotFoundException, IOException,
428 HeadlessException {
429 // HeadlessException will be thrown from MenuComponent's readObject
430 s.defaultReadObject();
431 for (int i = 0; i < menus.size(); i++) {
432 Menu m = (Menu) menus.elementAt(i);
433 m.parent = this ;
434 }
435 }
436
437 /**
438 * Initialize JNI field and method IDs
439 */
440 private static native void initIDs();
441
442 /////////////////
443 // Accessibility support
444 ////////////////
445
446 /**
447 * Gets the AccessibleContext associated with this MenuBar.
448 * For menu bars, the AccessibleContext takes the form of an
449 * AccessibleAWTMenuBar.
450 * A new AccessibleAWTMenuBar instance is created if necessary.
451 *
452 * @return an AccessibleAWTMenuBar that serves as the
453 * AccessibleContext of this MenuBar
454 * @since 1.3
455 */
456 public AccessibleContext getAccessibleContext() {
457 if (accessibleContext == null) {
458 accessibleContext = new AccessibleAWTMenuBar();
459 }
460 return accessibleContext;
461 }
462
463 /**
464 * Defined in MenuComponent. Overridden here.
465 */
466 int getAccessibleChildIndex(MenuComponent child) {
467 return menus.indexOf(child);
468 }
469
470 /**
471 * Inner class of MenuBar used to provide default support for
472 * accessibility. This class is not meant to be used directly by
473 * application developers, but is instead meant only to be
474 * subclassed by menu component developers.
475 * <p>
476 * This class implements accessibility support for the
477 * <code>MenuBar</code> class. It provides an implementation of the
478 * Java Accessibility API appropriate to menu bar user-interface elements.
479 * @since 1.3
480 */
481 protected class AccessibleAWTMenuBar extends
482 AccessibleAWTMenuComponent {
483 /*
484 * JDK 1.3 serialVersionUID
485 */
486 private static final long serialVersionUID = -8577604491830083815L;
487
488 /**
489 * Get the role of this object.
490 *
491 * @return an instance of AccessibleRole describing the role of the
492 * object
493 * @since 1.4
494 */
495 public AccessibleRole getAccessibleRole() {
496 return AccessibleRole.MENU_BAR;
497 }
498
499 } // class AccessibleAWTMenuBar
500
501 }
|