Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1996, 2006, 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.peer.PopupMenuPeer;
   29   import javax.accessibility;
   30   
   31   import sun.awt.AWTAccessor;
   32   
   33   /**
   34    * A class that implements a menu which can be dynamically popped up
   35    * at a specified position within a component.
   36    * <p>
   37    * As the inheritance hierarchy implies, a <code>PopupMenu</code>
   38    *  can be used anywhere a <code>Menu</code> can be used.
   39    * However, if you use a <code>PopupMenu</code> like a <code>Menu</code>
   40    * (e.g., you add it to a <code>MenuBar</code>), then you <b>cannot</b>
   41    * call <code>show</code> on that <code>PopupMenu</code>.
   42    *
   43    * @author      Amy Fowler
   44    */
   45   public class PopupMenu extends Menu {
   46   
   47       private static final String base = "popup";
   48       static int nameCounter = 0;
   49   
   50       transient boolean isTrayIconPopup = false;
   51   
   52       static {
   53           AWTAccessor.setPopupMenuAccessor(
   54               new AWTAccessor.PopupMenuAccessor() {
   55                   public boolean isTrayIconPopup(PopupMenu popupMenu) {
   56                       return popupMenu.isTrayIconPopup;
   57                   }
   58               });
   59       }
   60   
   61       /*
   62        * JDK 1.1 serialVersionUID
   63        */
   64       private static final long serialVersionUID = -4620452533522760060L;
   65   
   66       /**
   67        * Creates a new popup menu with an empty name.
   68        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
   69        * returns true.
   70        * @see java.awt.GraphicsEnvironment#isHeadless
   71        */
   72       public PopupMenu() throws HeadlessException {
   73           this("");
   74       }
   75   
   76       /**
   77        * Creates a new popup menu with the specified name.
   78        *
   79        * @param label a non-<code>null</code> string specifying
   80        *                the popup menu's label
   81        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
   82        * returns true.
   83        * @see java.awt.GraphicsEnvironment#isHeadless
   84        */
   85       public PopupMenu(String label) throws HeadlessException {
   86           super(label);
   87       }
   88   
   89       /**
   90        * {@inheritDoc}
   91        */
   92       public MenuContainer getParent() {
   93           if (isTrayIconPopup) {
   94               return null;
   95           }
   96           return super.getParent();
   97       }
   98   
   99       /**
  100        * Constructs a name for this <code>MenuComponent</code>.
  101        * Called by <code>getName</code> when the name is <code>null</code>.
  102        */
  103       String constructComponentName() {
  104           synchronized (PopupMenu.class) {
  105               return base + nameCounter++;
  106           }
  107       }
  108   
  109       /**
  110        * Creates the popup menu's peer.
  111        * The peer allows us to change the appearance of the popup menu without
  112        * changing any of the popup menu's functionality.
  113        */
  114       public void addNotify() {
  115           synchronized (getTreeLock()) {
  116               // If our parent is not a Component, then this PopupMenu is
  117               // really just a plain, old Menu.
  118               if (parent != null && !(parent instanceof Component)) {
  119                   super.addNotify();
  120               }
  121               else {
  122                   if (peer == null)
  123                       peer = Toolkit.getDefaultToolkit().createPopupMenu(this);
  124                   int nitems = getItemCount();
  125                   for (int i = 0 ; i < nitems ; i++) {
  126                       MenuItem mi = getItem(i);
  127                       mi.parent = this;
  128                       mi.addNotify();
  129                   }
  130               }
  131           }
  132       }
  133   
  134      /**
  135        * Shows the popup menu at the x, y position relative to an origin
  136        * component.
  137        * The origin component must be contained within the component
  138        * hierarchy of the popup menu's parent.  Both the origin and the parent
  139        * must be showing on the screen for this method to be valid.
  140        * <p>
  141        * If this <code>PopupMenu</code> is being used as a <code>Menu</code>
  142        * (i.e., it has a non-<code>Component</code> parent),
  143        * then you cannot call this method on the <code>PopupMenu</code>.
  144        *
  145        * @param origin the component which defines the coordinate space
  146        * @param x the x coordinate position to popup the menu
  147        * @param y the y coordinate position to popup the menu
  148        * @exception NullPointerException  if the parent is <code>null</code>
  149        * @exception IllegalArgumentException  if this <code>PopupMenu</code>
  150        *                has a non-<code>Component</code> parent
  151        * @exception IllegalArgumentException if the origin is not in the
  152        *                parent's heirarchy
  153        * @exception RuntimeException if the parent is not showing on screen
  154        */
  155       public void show(Component origin, int x, int y) {
  156           // Use localParent for thread safety.
  157           MenuContainer localParent = parent;
  158           if (localParent == null) {
  159               throw new NullPointerException("parent is null");
  160           }
  161           if (!(localParent instanceof Component)) {
  162               throw new IllegalArgumentException(
  163                   "PopupMenus with non-Component parents cannot be shown");
  164           }
  165           Component compParent = (Component)localParent;
  166           //Fixed 6278745: Incorrect exception throwing in PopupMenu.show() method
  167           //Exception was not thrown if compParent was not equal to origin and
  168           //was not Container
  169           if (compParent != origin) {
  170               if (compParent instanceof Container) {
  171                   if (!((Container)compParent).isAncestorOf(origin)) {
  172                       throw new IllegalArgumentException("origin not in parent's hierarchy");
  173                   }
  174               } else {
  175                   throw new IllegalArgumentException("origin not in parent's hierarchy");
  176               }
  177           }
  178           if (compParent.getPeer() == null || !compParent.isShowing()) {
  179               throw new RuntimeException("parent not showing on screen");
  180           }
  181           if (peer == null) {
  182               addNotify();
  183           }
  184           synchronized (getTreeLock()) {
  185               if (peer != null) {
  186                   ((PopupMenuPeer)peer).show(
  187                       new Event(origin, 0, Event.MOUSE_DOWN, x, y, 0, 0));
  188               }
  189           }
  190       }
  191   
  192   
  193   /////////////////
  194   // Accessibility support
  195   ////////////////
  196   
  197       /**
  198        * Gets the <code>AccessibleContext</code> associated with this
  199        * <code>PopupMenu</code>.
  200        *
  201        * @return the <code>AccessibleContext</code> of this
  202        *                <code>PopupMenu</code>
  203        * @since 1.3
  204        */
  205       public AccessibleContext getAccessibleContext() {
  206           if (accessibleContext == null) {
  207               accessibleContext = new AccessibleAWTPopupMenu();
  208           }
  209           return accessibleContext;
  210       }
  211   
  212       /**
  213        * Inner class of PopupMenu used to provide default support for
  214        * accessibility.  This class is not meant to be used directly by
  215        * application developers, but is instead meant only to be
  216        * subclassed by menu component developers.
  217        * <p>
  218        * The class used to obtain the accessible role for this object.
  219        * @since 1.3
  220        */
  221       protected class AccessibleAWTPopupMenu extends AccessibleAWTMenu
  222       {
  223           /*
  224            * JDK 1.3 serialVersionUID
  225            */
  226           private static final long serialVersionUID = -4282044795947239955L;
  227   
  228           /**
  229            * Get the role of this object.
  230            *
  231            * @return an instance of AccessibleRole describing the role of the
  232            * object
  233            */
  234           public AccessibleRole getAccessibleRole() {
  235               return AccessibleRole.POPUP_MENU;
  236           }
  237   
  238       } // class AccessibleAWTPopupMenu
  239   
  240   }

Home » openjdk-7 » java » awt » [javadoc | source]