libjava/javax/swing/JMenuBar.java

   1 /* JMenuBar.java --
   2    Copyright (C) 2002, 2004  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  * <p>
  53  * JMenuBar is a container for menu's. For a menu bar to be seen on the
  54  * screen, at least one menu should be added to it. Just like adding
  55  * components to container, one can use add() to add menu's to the menu bar.
  56  * Menu's will be displayed in the menu  bar in the order they were added.
  57  * The JMenuBar uses selectionModel to keep track of selected menu index.
  58  * JMenuBar's selectionModel will fire ChangeEvents to its registered
  59  * listeners when the selected index changes.
  60  * </p>
  61  */
  62 public class JMenuBar extends JComponent implements Accessible, MenuElement
  63 {
  64   /** Fired in a PropertyChangeEvent when the "borderPainted" property changes. */
  65   public static final String BORDER_PAINTED_CHANGED_PROPERTY = "borderPainted";
  66
  67   /** Fired in a PropertyChangeEvent when the "model" changes. */
  68   public static final String MODEL_CHANGED_PROPERTY = "model";
  69
  70   /** Fired in a PropertyChangeEvent when the "margin" changes. */
  71   public static final String MARGIN_CHANGED_PROPERTY = "margin";
  72   private static final long serialVersionUID = -8191026883931977036L;
  73
  74   /** JMenuBar's model. It keeps track of selected menu's index */
  75   private transient SingleSelectionModel selectionModel;
  76
  77   /* borderPainted property indicating if the menuBar's border will be painted*/
  78   private boolean borderPainted;
  79
  80   /* margin between menu bar's border and its menues*/
  81   private Insets margin;
  82
  83   /**
  84    * Creates a new JMenuBar object.
  85    */
  86   public JMenuBar()
  87   {
  88     selectionModel = new DefaultSingleSelectionModel();
  89     borderPainted = true;
  90     updateUI();
  91   }
  92
  93   /**
  94    * Adds menu to the menu bar
  95    *
  96    * @param c menu to add
  97    *
  98    * @return reference to the added menu
  99    */
 100   public JMenu add(JMenu c)
 101   {
 102     c.setAlignmentX(Component.LEFT_ALIGNMENT);
 103     super.add(c);
 104     return c;
 105   }
 106
 107   /**
 108    * This method overrides addNotify() in the Container to register
 109    * this menu bar with the current keyboard manager.
 110    */
 111   public void addNotify()
 112   {
 113     // FIXME: Should register this menu bar with the keyboard manager
 114     super.addNotify();
 115   }
 116
 117   public AccessibleContext getAccessibleContext()
 118   {
 119     return null;
 120   }
 121
 122   /**
 123    * Returns reference to this menu bar
 124    *
 125    * @return reference to this menu bar
 126    */
 127   public Component getComponent()
 128   {
 129     return this;
 130   }
 131
 132   /**
 133    * Returns component at the specified index.
 134    *
 135    * @param i index of the component to get
 136    *
 137    * @return component at the specified index. Null is returned if
 138    * component at the specified index doesn't exist.
 139    * @deprecated Replaced by getComponent(int)
 140    */
 141   public Component getComponentAtIndex(int i)
 142   {
 143     return getComponent(i);
 144   }
 145
 146   /**
 147    * Returns index of the specified component
 148    *
 149    * @param c Component to search for
 150    *
 151    * @return index of the specified component. -1 is returned if
 152    * specified component doesnt' exist in the menu bar.
 153    */
 154   public int getComponentIndex(Component c)
 155   {
 156     Component[] comps = getComponents();
 157
 158     int index = -1;
 159
 160     for (int i = 0; i < comps.length; i++)
 161       {
 162         if (comps[i].equals(c))
 163           {
 164             index = i;
 165             break;
 166           }
 167       }
 168
 169     return index;
 170   }
 171
 172   /**
 173    * DOCUMENT ME!
 174    *
 175    * @return DOCUMENT ME!
 176    */
 177   public JMenu getHelpMenu()
 178   {
 179     return null;
 180   }
 181
 182   /**
 183    * Returns margin betweeen menu bar's border and its menues
 184    *
 185    * @return margin between menu bar's border and its menues
 186    */
 187   public Insets getMargin()
 188   {
 189     if (margin == null)
 190       return new Insets(0, 0, 0, 0);
 191     else
 192       return margin;
 193   }
 194
 195   /**
 196    * Return menu at the specified index. If component at the
 197    * specified index is not a menu, then null is returned.
 198    *
 199    * @param index index to look for the menu
 200    *
 201    * @return menu at specified index, or null if menu doesn't exist
 202    * at the specified index.
 203    */
 204   public JMenu getMenu(int index)
 205   {
 206     if (getComponentAtIndex(index) instanceof JMenu)
 207       return (JMenu) getComponentAtIndex(index);
 208     else
 209       return null;
 210   }
 211
 212   /**
 213    * Returns number of menu's in this menu bar
 214    *
 215    * @return number of menu's in this menu bar
 216    */
 217   public int getMenuCount()
 218   {
 219     return getComponentCount();
 220   }
 221
 222   /**
 223    * Returns selection model for this menu bar. SelectionModel
 224    * keeps track of the selected menu in the menu bar. Whenever
 225    * selected property of selectionModel changes, the ChangeEvent
 226    * will be fired its ChangeListeners.
 227    *
 228    * @return selection model for this menu bar.
 229    */
 230   public SingleSelectionModel getSelectionModel()
 231   {
 232     return selectionModel;
 233   }
 234
 235   /**
 236    * Method of MenuElement interface. It returns subcomponents
 237    * of the menu bar, which are all the menues that it contains.
 238    *
 239    * @return MenuElement[] array containing menues in this menu bar
 240    */
 241   public MenuElement[] getSubElements()
 242   {
 243     MenuElement[] subElements = new MenuElement[getComponentCount()];
 244
 245     for (int i = 0; i < getComponentCount(); i++)
 246       subElements[i] = (MenuElement) getMenu(i);
 247
 248     return subElements;
 249   }
 250
 251   /**
 252     * Set the "UI" property of the menu bar, which is a look and feel class
 253     * responsible for handling the menuBar's input events and painting it.
 254     *
 255     * @return The current "UI" property
 256     */
 257   public MenuBarUI getUI()
 258   {
 259     return (MenuBarUI) ui;
 260   }
 261
 262   /**
 263    * This method returns a name to identify which look and feel class will be
 264    * the UI delegate for the menu bar.
 265    *
 266    * @return The Look and Feel classID. "MenuItemUI"
 267    */
 268   public String getUIClassID()
 269   {
 270     return "MenuBarUI";
 271   }
 272
 273   /**
 274    * Returns true if menu bar paints its border and false otherwise
 275    *
 276    * @return true if menu bar paints its border and false otherwise
 277    */
 278   public boolean isBorderPainted()
 279   {
 280     return borderPainted;
 281   }
 282
 283   /**
 284    * Returns true if some menu in menu bar is selected.
 285    *
 286    * @return true if some menu in menu bar is selected and false otherwise
 287    */
 288   public boolean isSelected()
 289   {
 290     return selectionModel.isSelected();
 291   }
 292
 293   /**
 294    * This method does nothing by default. This method is need for the
 295    * MenuElement interface to be implemented.
 296    *
 297    * @param isIncluded true if menuBar is included in the selection
 298    * and false otherwise
 299    */
 300   public void menuSelectionChanged(boolean isIncluded)
 301   {
 302     // Do nothing - needed for implementation of MenuElement interface
 303   }
 304
 305   /**
 306    * Paints border of the menu bar, if its borderPainted property is set to
 307    * true.
 308    *
 309    * @param g The graphics context with which to paint the border
 310    */
 311   protected void paintBorder(Graphics g)
 312   {
 313     if (borderPainted)
 314       getBorder().paintBorder(this, g, 0, 0, getSize(null).width,
 315                               getSize(null).height);
 316   }
 317
 318   /**
 319    * A string that describes this JMenuBar. Normally only used
 320    * for debugging.
 321    *
 322    * @return A string describing this JMenuBar
 323    */
 324   protected String paramString()
 325   {
 326     return "JMenuBar";
 327   }
 328
 329   /**
 330    * Process key events forwarded from MenuSelectionManager. This method
 331    * doesn't do anything. It is here to conform to the MenuElement interface.
 332    *
 333    * @param event event forwarded from MenuSelectionManager
 334    * @param path path to the menu element from which event was generated
 335    * @param manager MenuSelectionManager for the current menu hierarchy
 336    *
 337    */
 338   public void processKeyEvent(KeyEvent e, MenuElement[] path,
 339                               MenuSelectionManager manager)
 340   {
 341     // Do nothing - needed for implementation of MenuElement interface
 342   }
 343
 344   /**
 345    * Process mouse events forwarded from MenuSelectionManager. This method
 346    * doesn't do anything. It is here to conform to the MenuElement interface.
 347    *
 348    * @param event event forwarded from MenuSelectionManager
 349    * @param path path to the menu element from which event was generated
 350    * @param manager MenuSelectionManager for the current menu hierarchy
 351    *
 352    */
 353   public void processMouseEvent(MouseEvent event, MenuElement[] path,
 354                                 MenuSelectionManager manager)
 355   {
 356     // Do nothing - needed for implementation of MenuElement interface
 357   }
 358
 359   /**
 360    * This method overrides removeNotify() in the Container to
 361    * unregister this menu bar from the current keyboard manager.
 362    */
 363   public void removeNotify()
 364   {
 365     // Must unregister this menu bar with the current keyboard manager.
 366     super.removeNotify();
 367   }
 368
 369   /**
 370    * Sets painting status of the border. If 'b' is true then menu bar's
 371    * border will be painted, and it will not be painted otherwise.
 372    *
 373    * @param b indicates if menu bar's border should be painted.
 374    */
 375   public void setBorderPainted(boolean b)
 376   {
 377     boolean old = borderPainted;
 378     borderPainted = b;
 379     if (b != old)
 380       {
 381         firePropertyChange(BORDER_PAINTED_CHANGED_PROPERTY, old, b);
 382         revalidate();
 383         repaint();
 384       }
 385   }
 386
 387   /**
 388    * Sets help menu for this menu bar
 389    *
 390    * @param menu help menu
 391    */
 392   public void setHelpMenu(JMenu menu)
 393   {
 394   }
 395
 396   /**
 397    * Sets the menu bar's "margin" bound property,  which represents
 398    * distance between the menubar's border and its menus.
 399    * icon. When marging property is modified, PropertyChangeEvent will
 400    * be fired to menuBar's PropertyChangeListener's.
 401    *
 402    * @param m distance between the menubar's border and its menus.
 403    *
 404    */
 405   public void setMargin(Insets m)
 406   {
 407     if (m.equals(this.margin))
 408       {
 409         Insets oldMargin = this.margin;
 410         this.margin = m;
 411         firePropertyChange(MARGIN_CHANGED_PROPERTY, oldMargin, margin);
 412       }
 413
 414     this.margin = m;
 415   }
 416
 417   /**
 418    * Changes menu bar's selection to the specified menu.
 419    * This method updates selected index of menu bar's selection model,
 420    * which results in a model firing change event.
 421    *
 422    * @param sel menu to select
 423    */
 424   public void setSelected(Component sel)
 425   {
 426     int index = getComponentIndex(sel);
 427     selectionModel.setSelectedIndex(index);
 428   }
 429
 430   /**
 431    * Sets menuBar's selection model to the one specified
 432    *
 433    * @param model SingleSelectionModel that needs to be set for this menu bar
 434    */
 435   public void setSelectionModel(SingleSelectionModel model)
 436   {
 437     selectionModel = model;
 438     if (selectionModel != model)
 439       {
 440         SingleSelectionModel oldModel = selectionModel;
 441
 442         selectionModel = model;
 443
 444         firePropertyChange(MODEL_CHANGED_PROPERTY, oldModel,
 445                            this.selectionModel);
 446       }
 447   }
 448
 449   /**
 450    * Set the "UI" property of the menu bar, which is a look and feel class
 451    * responsible for handling menuBar's input events and painting it.
 452    *
 453    * @param ui The new "UI" property
 454    */
 455   public void setUI(MenuBarUI ui)
 456   {
 457     super.setUI(ui);
 458   }
 459
 460   /**
 461    * Set the "UI" property to a class constructed, via the {@link
 462    * UIManager}, from the current look and feel.
 463    */
 464   public void updateUI()
 465   {
 466     setUI((MenuBarUI) UIManager.getUI(this));
 467     invalidate();
 468   }
 469 }