libjava/javax/swing/JMenuBar.java

   1 /* JMenuBar.java --
   2    Copyright (C) 2002, 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.swing;
  40
  41 import java.awt.Component;
  42 import java.awt.Graphics;
  43 import java.awt.Insets;
  44 import java.awt.event.KeyEvent;
  45 import java.awt.event.MouseEvent;
  46
  47 import javax.accessibility.Accessible;
  48 import javax.accessibility.AccessibleContext;
  49 import javax.swing.plaf.MenuBarUI;
  50
  51 /**
  52  * JMenuBar is a container for menu's. For a menu bar to be seen on the
  53  * screen, at least one menu should be added to it. Just like adding
  54  * components to container, one can use add() to add menu's to the menu bar.
  55  * Menu's will be displayed in the menu  bar in the order they were added.
  56  * The JMenuBar uses selectionModel to keep track of selected menu index.
  57  * JMenuBar's selectionModel will fire ChangeEvents to its registered
  58  * listeners when the selected index changes.
  59  */
  60 public class JMenuBar extends JComponent implements Accessible, MenuElement
  61 {
  62   private static final long serialVersionUID = -8191026883931977036L;
  63
  64   /** JMenuBar's model. It keeps track of selected menu's index */
  65   private transient SingleSelectionModel selectionModel;
  66
  67   /* borderPainted property indicating if the menuBar's border will be painted*/
  68   private boolean borderPainted;
  69
  70   /* margin between menu bar's border and its menues*/
  71   private Insets margin;
  72
  73   /**
  74    * Creates a new JMenuBar object.
  75    */
  76   public JMenuBar()
  77   {
  78     selectionModel = new DefaultSingleSelectionModel();
  79     borderPainted = true;
  80     updateUI();
  81   }
  82
  83   /**
  84    * Adds menu to the menu bar
  85    *
  86    * @param c menu to add
  87    *
  88    * @return reference to the added menu
  89    */
  90   public JMenu add(JMenu c)
  91   {
  92     c.setAlignmentX(Component.LEFT_ALIGNMENT);
  93     super.add(c);
  94     return c;
  95   }
  96
  97   /**
  98    * This method overrides addNotify() in the Container to register
  99    * this menu bar with the current keyboard manager.
 100    */
 101   public void addNotify()
 102   {
 103     // FIXME: Should register this menu bar with the keyboard manager
 104     super.addNotify();
 105   }
 106
 107   public AccessibleContext getAccessibleContext()
 108   {
 109     return null;
 110   }
 111
 112   /**
 113    * Returns reference to this menu bar
 114    *
 115    * @return reference to this menu bar
 116    */
 117   public Component getComponent()
 118   {
 119     return this;
 120   }
 121
 122   /**
 123    * Returns component at the specified index.
 124    *
 125    * @param i index of the component to get
 126    *
 127    * @return component at the specified index. Null is returned if
 128    * component at the specified index doesn't exist.
 129    * @deprecated Replaced by getComponent(int)
 130    */
 131   public Component getComponentAtIndex(int i)
 132   {
 133     return getComponent(i);
 134   }
 135
 136   /**
 137    * Returns index of the specified component
 138    *
 139    * @param c Component to search for
 140    *
 141    * @return index of the specified component. -1 is returned if
 142    * specified component doesnt' exist in the menu bar.
 143    */
 144   public int getComponentIndex(Component c)
 145   {
 146     Component[] comps = getComponents();
 147
 148     int index = -1;
 149
 150     for (int i = 0; i < comps.length; i++)
 151       {
 152         if (comps[i].equals(c))
 153           {
 154             index = i;
 155             break;
 156           }
 157       }
 158
 159     return index;
 160   }
 161
 162   /**
 163    * DOCUMENT ME!
 164    *
 165    * @return DOCUMENT ME!
 166    */
 167   public JMenu getHelpMenu()
 168   {
 169     return null;
 170   }
 171
 172   /**
 173    * Returns margin betweeen menu bar's border and its menues
 174    *
 175    * @return margin between menu bar's border and its menues
 176    */
 177   public Insets getMargin()
 178   {
 179     if (margin == null)
 180       return new Insets(0, 0, 0, 0);
 181     else
 182       return margin;
 183   }
 184
 185   /**
 186    * Return menu at the specified index. If component at the
 187    * specified index is not a menu, then null is returned.
 188    *
 189    * @param index index to look for the menu
 190    *
 191    * @return menu at specified index, or null if menu doesn't exist
 192    * at the specified index.
 193    */
 194   public JMenu getMenu(int index)
 195   {
 196     if (getComponentAtIndex(index) instanceof JMenu)
 197       return (JMenu) getComponentAtIndex(index);
 198     else
 199       return null;
 200   }
 201
 202   /**
 203    * Returns number of menu's in this menu bar
 204    *
 205    * @return number of menu's in this menu bar
 206    */
 207   public int getMenuCount()
 208   {
 209     return getComponentCount();
 210   }
 211
 212   /**
 213    * Returns selection model for this menu bar. SelectionModel
 214    * keeps track of the selected menu in the menu bar. Whenever
 215    * selected property of selectionModel changes, the ChangeEvent
 216    * will be fired its ChangeListeners.
 217    *
 218    * @return selection model for this menu bar.
 219    */
 220   public SingleSelectionModel getSelectionModel()
 221   {
 222     return selectionModel;
 223   }
 224
 225   /**
 226    * Method of MenuElement interface. It returns subcomponents
 227    * of the menu bar, which are all the menues that it contains.
 228    *
 229    * @return MenuElement[] array containing menues in this menu bar
 230    */
 231   public MenuElement[] getSubElements()
 232   {
 233     MenuElement[] subElements = new MenuElement[getComponentCount()];
 234
 235     for (int i = 0; i < getComponentCount(); i++)
 236       subElements[i] = (MenuElement) getMenu(i);
 237
 238     return subElements;
 239   }
 240
 241   /**
 242     * Set the "UI" property of the menu bar, which is a look and feel class
 243     * responsible for handling the menuBar's input events and painting it.
 244     *
 245     * @return The current "UI" property
 246     */
 247   public MenuBarUI getUI()
 248   {
 249     return (MenuBarUI) ui;
 250   }
 251
 252   /**
 253    * This method returns a name to identify which look and feel class will be
 254    * the UI delegate for the menu bar.
 255    *
 256    * @return The Look and Feel classID. "MenuItemUI"
 257    */
 258   public String getUIClassID()
 259   {
 260     return "MenuBarUI";
 261   }
 262
 263   /**
 264    * Returns true if menu bar paints its border and false otherwise
 265    *
 266    * @return true if menu bar paints its border and false otherwise
 267    */
 268   public boolean isBorderPainted()
 269   {
 270     return borderPainted;
 271   }
 272
 273   /**
 274    * Returns true if some menu in menu bar is selected.
 275    *
 276    * @return true if some menu in menu bar is selected and false otherwise
 277    */
 278   public boolean isSelected()
 279   {
 280     return selectionModel.isSelected();
 281   }
 282
 283   /**
 284    * This method does nothing by default. This method is need for the
 285    * MenuElement interface to be implemented.
 286    *
 287    * @param isIncluded true if menuBar is included in the selection
 288    * and false otherwise
 289    */
 290   public void menuSelectionChanged(boolean isIncluded)
 291   {
 292     // Do nothing - needed for implementation of MenuElement interface
 293   }
 294
 295   /**
 296    * Paints border of the menu bar, if its borderPainted property is set to
 297    * true.
 298    *
 299    * @param g The graphics context with which to paint the border
 300    */
 301   protected void paintBorder(Graphics g)
 302   {
 303     if (borderPainted)
 304       getBorder().paintBorder(this, g, 0, 0, getSize(null).width,
 305                               getSize(null).height);
 306   }
 307
 308   /**
 309    * A string that describes this JMenuBar. Normally only used
 310    * for debugging.
 311    *
 312    * @return A string describing this JMenuBar
 313    */
 314   protected String paramString()
 315   {
 316     StringBuffer sb = new StringBuffer();
 317     sb.append(super.paramString());
 318     sb.append(",margin=");
 319     if (getMargin() != null)
 320       sb.append(getMargin());
 321     sb.append(",paintBorder=").append(isBorderPainted());
 322     return sb.toString();
 323   }
 324
 325   /**
 326    * Process key events forwarded from MenuSelectionManager. This method
 327    * doesn't do anything. It is here to conform to the MenuElement interface.
 328    *
 329    * @param event event forwarded from MenuSelectionManager
 330    * @param path path to the menu element from which event was generated
 331    * @param manager MenuSelectionManager for the current menu hierarchy
 332    *
 333    */
 334   public void processKeyEvent(KeyEvent e, MenuElement[] path,
 335                               MenuSelectionManager manager)
 336   {
 337     // Do nothing - needed for implementation of MenuElement interface
 338   }
 339
 340   /**
 341    * Process mouse events forwarded from MenuSelectionManager. This method
 342    * doesn't do anything. It is here to conform to the MenuElement interface.
 343    *
 344    * @param event event forwarded from MenuSelectionManager
 345    * @param path path to the menu element from which event was generated
 346    * @param manager MenuSelectionManager for the current menu hierarchy
 347    *
 348    */
 349   public void processMouseEvent(MouseEvent event, MenuElement[] path,
 350                                 MenuSelectionManager manager)
 351   {
 352     // Do nothing - needed for implementation of MenuElement interface
 353   }
 354
 355   /**
 356    * This method overrides removeNotify() in the Container to
 357    * unregister this menu bar from the current keyboard manager.
 358    */
 359   public void removeNotify()
 360   {
 361     // Must unregister this menu bar with the current keyboard manager.
 362     super.removeNotify();
 363   }
 364
 365   /**
 366    * Sets painting status of the border. If 'b' is true then menu bar's
 367    * border will be painted, and it will not be painted otherwise.
 368    *
 369    * @param b indicates if menu bar's border should be painted.
 370    */
 371   public void setBorderPainted(boolean b)
 372   {
 373     if (b != borderPainted)
 374       {
 375         boolean old = borderPainted;
 376         borderPainted = b;
 377         firePropertyChange("borderPainted", old, b);
 378         revalidate();
 379         repaint();
 380       }
 381   }
 382
 383   /**
 384    * Sets help menu for this menu bar
 385    *
 386    * @param menu help menu
 387    */
 388   public void setHelpMenu(JMenu menu)
 389   {
 390   }
 391
 392   /**
 393    * Sets the menu bar's "margin" bound property,  which represents
 394    * distance between the menubar's border and its menus.
 395    * icon. When marging property is modified, PropertyChangeEvent will
 396    * be fired to menuBar's PropertyChangeListener's.
 397    *
 398    * @param m distance between the menubar's border and its menus.
 399    *
 400    */
 401   public void setMargin(Insets m)
 402   {
 403     if (m != margin)
 404       {
 405         Insets oldMargin = margin;
 406         margin = m;
 407         firePropertyChange("margin", oldMargin, margin);
 408       }
 409   }
 410
 411   /**
 412    * Changes menu bar's selection to the specified menu.
 413    * This method updates selected index of menu bar's selection model,
 414    * which results in a model firing change event.
 415    *
 416    * @param sel menu to select
 417    */
 418   public void setSelected(Component sel)
 419   {
 420     int index = getComponentIndex(sel);
 421     selectionModel.setSelectedIndex(index);
 422   }
 423
 424   /**
 425    * Sets menuBar's selection model to the one specified
 426    *
 427    * @param model SingleSelectionModel that needs to be set for this menu bar
 428    */
 429   public void setSelectionModel(SingleSelectionModel model)
 430   {
 431     if (selectionModel != model)
 432       {
 433         SingleSelectionModel oldModel = selectionModel;
 434         selectionModel = model;
 435         firePropertyChange("model", oldModel, selectionModel);
 436       }
 437   }
 438
 439   /**
 440    * Set the "UI" property of the menu bar, which is a look and feel class
 441    * responsible for handling menuBar's input events and painting it.
 442    *
 443    * @param ui The new "UI" property
 444    */
 445   public void setUI(MenuBarUI ui)
 446   {
 447     super.setUI(ui);
 448   }
 449
 450   /**
 451    * Set the "UI" property to a class constructed, via the {@link
 452    * UIManager}, from the current look and feel.
 453    */
 454   public void updateUI()
 455   {
 456     setUI((MenuBarUI) UIManager.getUI(this));
 457     invalidate();
 458   }
 459 }