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