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 = 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             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 }