001    /* JMenuBar.java --
002       Copyright (C) 2002, 2004, 2005, 2006  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.swing;
040    
041    import gnu.java.lang.CPStringBuilder;
042    
043    import java.awt.Component;
044    import java.awt.Graphics;
045    import java.awt.Insets;
046    import java.awt.event.KeyEvent;
047    import java.awt.event.MouseEvent;
048    
049    import javax.accessibility.Accessible;
050    import javax.accessibility.AccessibleContext;
051    import javax.accessibility.AccessibleRole;
052    import javax.accessibility.AccessibleSelection;
053    import javax.accessibility.AccessibleStateSet;
054    import javax.swing.plaf.MenuBarUI;
055    
056    import javax.swing.border.Border;
057    
058    /**
059     * JMenuBar is a container for menu's. For a menu bar to be seen on the
060     * screen, at least one menu should be added to it. Just like adding
061     * components to container, one can use add() to add menu's to the menu bar.
062     * Menu's will be displayed in the menu  bar in the order they were added.
063     * The JMenuBar uses selectionModel to keep track of selected menu index.
064     * JMenuBar's selectionModel will fire ChangeEvents to its registered
065     * listeners when the selected index changes.
066     */
067    public class JMenuBar extends JComponent implements Accessible, MenuElement
068    {
069      /**
070       * Provides accessibility support for <code>JMenuBar</code>.
071       *
072       * @author Roman Kennke (kennke@aicas.com)
073       */
074      protected class AccessibleJMenuBar extends AccessibleJComponent
075        implements AccessibleSelection
076      {
077    
078        /**
079         * Returns the number of selected items in the menu bar. Possible values
080         * are <code>0</code> if nothing is selected, or <code>1</code> if one
081         * item is selected.
082         *
083         * @return the number of selected items in the menu bar
084         */
085        public int getAccessibleSelectionCount()
086        {
087          int count = 0;
088          if (getSelectionModel().getSelectedIndex() != -1)
089            count = 1;
090          return count;
091        }
092    
093        /**
094         * Returns the selected with index <code>i</code> menu, or
095         * <code>null</code> if the specified menu is not selected.
096         *
097         * @param i the index of the menu to return
098         *
099         * @return the selected with index <code>i</code> menu, or
100         *         <code>null</code> if the specified menu is not selected
101         */
102        public Accessible getAccessibleSelection(int i)
103        {
104          if (getSelectionModel().getSelectedIndex() != i)
105            return null;
106          return getMenu(i);
107        }
108    
109        /**
110         * Returns <code>true</code> if the specified menu is selected,
111         * <code>false</code> otherwise.
112         *
113         * @param i the index of the menu to check
114         *
115         *@return <code>true</code> if the specified menu is selected,
116         *        <code>false</code> otherwise
117         */
118        public boolean isAccessibleChildSelected(int i)
119        {
120          return getSelectionModel().getSelectedIndex() == i;
121        }
122    
123        /**
124         * Selects the menu with index <code>i</code>. If another menu is already
125         * selected, this will be deselected.
126         *
127         * @param i the menu to be selected
128         */
129        public void addAccessibleSelection(int i)
130        {
131          getSelectionModel().setSelectedIndex(i);
132        }
133    
134        /**
135         * Deselects the menu with index <code>i</code>.
136         *
137         * @param i the menu index to be deselected
138         */
139        public void removeAccessibleSelection(int i)
140        {
141          if (getSelectionModel().getSelectedIndex() == i)
142            getSelectionModel().clearSelection();
143        }
144    
145        /**
146         * Deselects all possibly selected menus.
147         */
148        public void clearAccessibleSelection()
149        {
150          getSelectionModel().clearSelection();
151        }
152    
153        /**
154         * In menu bars it is not possible to select all items, so this method
155         * does nothing.
156         */
157        public void selectAllAccessibleSelection()
158        {
159          // In menu bars it is not possible to select all items, so this method
160          // does nothing.
161        }
162    
163        /**
164         * Returns the accessible role of <code>JMenuBar</code>, which is
165         * {@link AccessibleRole#MENU_BAR}.
166         *
167         * @return the accessible role of <code>JMenuBar</code>, which is
168         *         {@link AccessibleRole#MENU_BAR}
169         */
170        public AccessibleRole getAccessibleRole()
171        {
172          return AccessibleRole.MENU_BAR;
173        }
174    
175        /**
176         * Returns the <code>AccessibleSelection</code> for this object. This
177         * method returns <code>this</code>, since the
178         * <code>AccessibleJMenuBar</code> manages its selection itself.
179         *
180         * @return the <code>AccessibleSelection</code> for this object
181         */
182        public AccessibleSelection getAccessibleSelection()
183        {
184          return this;
185        }
186    
187        /**
188         * Returns the state of this <code>AccessibleJMenuBar</code>.
189         *
190         * @return the state of this <code>AccessibleJMenuBar</code>.
191         */
192        public AccessibleStateSet getAccessibleStateSet()
193        {
194          AccessibleStateSet stateSet = super.getAccessibleStateSet();
195          // TODO: Figure out what state must be added to the super state set.
196          return stateSet;
197        }
198      }
199    
200      private static final long serialVersionUID = -8191026883931977036L;
201    
202      /** JMenuBar's model. It keeps track of selected menu's index */
203      private transient SingleSelectionModel selectionModel;
204    
205      /* borderPainted property indicating if the menuBar's border will be painted*/
206      private boolean borderPainted;
207    
208      /* margin between menu bar's border and its menues*/
209      private Insets margin;
210    
211      /**
212       * Creates a new JMenuBar object.
213       */
214      public JMenuBar()
215      {
216        selectionModel = new DefaultSingleSelectionModel();
217        borderPainted = true;
218        updateUI();
219      }
220    
221      /**
222       * Adds menu to the menu bar
223       *
224       * @param c menu to add
225       *
226       * @return reference to the added menu
227       */
228      public JMenu add(JMenu c)
229      {
230        c.setAlignmentX(Component.LEFT_ALIGNMENT);
231        super.add(c);
232        return c;
233      }
234    
235      /**
236       * This method overrides addNotify() in the Container to register
237       * this menu bar with the current keyboard manager.
238       */
239      public void addNotify()
240      {
241        super.addNotify();
242        KeyboardManager.getManager().registerJMenuBar(this);
243      }
244    
245      public AccessibleContext getAccessibleContext()
246      {
247        if (accessibleContext == null)
248          accessibleContext = new AccessibleJMenuBar();
249        return accessibleContext;
250      }
251    
252      /**
253       * Returns reference to this menu bar
254       *
255       * @return reference to this menu bar
256       */
257      public Component getComponent()
258      {
259        return this;
260      }
261    
262      /**
263       * Returns component at the specified index.
264       *
265       * @param i index of the component to get
266       *
267       * @return component at the specified index. Null is returned if
268       * component at the specified index doesn't exist.
269       * @deprecated Replaced by getComponent(int)
270       */
271      public Component getComponentAtIndex(int i)
272      {
273        return getComponent(i);
274      }
275    
276      /**
277       * Returns index of the specified component
278       *
279       * @param c Component to search for
280       *
281       * @return index of the specified component. -1 is returned if
282       * specified component doesnt' exist in the menu bar.
283       */
284      public int getComponentIndex(Component c)
285      {
286        Component[] comps = getComponents();
287    
288        int index = -1;
289    
290        for (int i = 0; i < comps.length; i++)
291          {
292            if (comps[i].equals(c))
293              {
294                index = i;
295                break;
296              }
297          }
298    
299        return index;
300      }
301    
302      /**
303       * This method is not implemented and will throw an {@link Error} if called.
304       *
305       * @return This method never returns anything, it throws an exception.
306       */
307      public JMenu getHelpMenu()
308      {
309        // the following error matches the behaviour of the reference
310        // implementation...
311        throw new Error("getHelpMenu() is not implemented");
312      }
313    
314      /**
315       * Returns the margin between the menu bar's border and its menus.  If the
316       * margin is <code>null</code>, this method returns
317       * <code>new Insets(0, 0, 0, 0)</code>.
318       *
319       * @return The margin (never <code>null</code>).
320       *
321       * @see #setMargin(Insets)
322       */
323      public Insets getMargin()
324      {
325        if (margin == null)
326          return new Insets(0, 0, 0, 0);
327        else
328          return margin;
329      }
330    
331      /**
332       * Return menu at the specified index. If component at the
333       * specified index is not a menu, then null is returned.
334       *
335       * @param index index to look for the menu
336       *
337       * @return menu at specified index, or null if menu doesn't exist
338       * at the specified index.
339       */
340      public JMenu getMenu(int index)
341      {
342        if (getComponentAtIndex(index) instanceof JMenu)
343          return (JMenu) getComponentAtIndex(index);
344        else
345          return null;
346      }
347    
348      /**
349       * Returns number of menu's in this menu bar
350       *
351       * @return number of menu's in this menu bar
352       */
353      public int getMenuCount()
354      {
355        return getComponentCount();
356      }
357    
358      /**
359       * Returns selection model for this menu bar. SelectionModel
360       * keeps track of the selected menu in the menu bar. Whenever
361       * selected property of selectionModel changes, the ChangeEvent
362       * will be fired its ChangeListeners.
363       *
364       * @return selection model for this menu bar.
365       */
366      public SingleSelectionModel getSelectionModel()
367      {
368        return selectionModel;
369      }
370    
371      /**
372       * Method of MenuElement interface. It returns subcomponents
373       * of the menu bar, which are all the menues that it contains.
374       *
375       * @return MenuElement[] array containing menues in this menu bar
376       */
377      public MenuElement[] getSubElements()
378      {
379        MenuElement[] subElements = new MenuElement[getComponentCount()];
380    
381        int j = 0;
382        boolean doResize = false;
383        MenuElement menu;
384        for (int i = 0; i < getComponentCount(); i++)
385          {
386            menu = getMenu(i);
387            if (menu != null)
388              {
389                subElements[j++] = (MenuElement) menu;
390              }
391            else
392              doResize = true;
393          }
394    
395        if (! doResize)
396          return subElements;
397        else
398          {
399            MenuElement[] subElements2 = new MenuElement[j];
400            for (int i = 0; i < j; i++)
401              subElements2[i] = subElements[i];
402    
403            return subElements2;
404          }
405      }
406    
407      /**
408        * Set the "UI" property of the menu bar, which is a look and feel class
409        * responsible for handling the menuBar's input events and painting it.
410        *
411        * @return The current "UI" property
412        */
413      public MenuBarUI getUI()
414      {
415        return (MenuBarUI) ui;
416      }
417    
418      /**
419       * This method returns a name to identify which look and feel class will be
420       * the UI delegate for the menu bar.
421       *
422       * @return The Look and Feel classID. "MenuBarUI"
423       */
424      public String getUIClassID()
425      {
426        return "MenuBarUI";
427      }
428    
429      /**
430       * Returns true if menu bar paints its border and false otherwise
431       *
432       * @return true if menu bar paints its border and false otherwise
433       */
434      public boolean isBorderPainted()
435      {
436        return borderPainted;
437      }
438    
439      /**
440       * Returns true if some menu in menu bar is selected.
441       *
442       * @return true if some menu in menu bar is selected and false otherwise
443       */
444      public boolean isSelected()
445      {
446        return selectionModel.isSelected();
447      }
448    
449      /**
450       * This method does nothing by default. This method is need for the
451       * MenuElement interface to be implemented.
452       *
453       * @param isIncluded true if menuBar is included in the selection
454       * and false otherwise
455       */
456      public void menuSelectionChanged(boolean isIncluded)
457      {
458        // Do nothing - needed for implementation of MenuElement interface
459      }
460    
461      /**
462       * Paints border of the menu bar, if its borderPainted property is set to
463       * true.
464       *
465       * @param g The graphics context with which to paint the border
466       */
467      protected void paintBorder(Graphics g)
468      {
469        if (borderPainted)
470          {
471            Border border = getBorder();
472            if (border != null)
473              getBorder().paintBorder(this, g, 0, 0, getSize(null).width,
474                                      getSize(null).height);
475          }
476      }
477    
478      /**
479       * A string that describes this JMenuBar. Normally only used
480       * for debugging.
481       *
482       * @return A string describing this JMenuBar
483       */
484      protected String paramString()
485      {
486        CPStringBuilder sb = new CPStringBuilder();
487        sb.append(super.paramString());
488        sb.append(",margin=");
489        if (getMargin() != null)
490          sb.append(getMargin());
491        sb.append(",paintBorder=").append(isBorderPainted());
492        return sb.toString();
493      }
494    
495      /**
496       * Process key events forwarded from MenuSelectionManager. This method
497       * doesn't do anything. It is here to conform to the MenuElement interface.
498       *
499       * @param e event forwarded from MenuSelectionManager
500       * @param path path to the menu element from which event was generated
501       * @param manager MenuSelectionManager for the current menu hierarchy
502       *
503       */
504      public void processKeyEvent(KeyEvent e, MenuElement[] path,
505                                  MenuSelectionManager manager)
506      {
507        // Do nothing - needed for implementation of MenuElement interface
508      }
509    
510      /**
511       * This method overrides JComponent.processKeyBinding to allow the
512       * JMenuBar to check all the child components (recursiveley) to see
513       * if they'll consume the event.
514       *
515       * @param ks the KeyStroke for the event
516       * @param e the KeyEvent for the event
517       * @param condition the focus condition for the binding
518       * @param pressed true if the key is pressed
519       */
520      protected boolean processKeyBinding(KeyStroke ks, KeyEvent e, int condition,
521                                          boolean pressed)
522      {
523        // See if the regular JComponent behavior consumes the event
524        if (super.processKeyBinding(ks, e, condition, pressed))
525          return true;
526    
527        // If not, have to recursively check all the child menu elements to see
528        // if they want it
529        MenuElement[] children = getSubElements();
530        for (int i = 0; i < children.length; i++)
531          if (processKeyBindingHelper(children[i], ks, e, condition, pressed))
532            return true;
533        return false;
534      }
535    
536      /**
537       * This is a helper method to recursively check the children of this
538       * JMenuBar to see if they will consume a key event via key bindings.
539       * This is used for menu accelerators.
540       * @param menuElement the menuElement to check (and check all its children)
541       * @param ks the KeyStroke for the event
542       * @param e the KeyEvent that may be consumed
543       * @param condition the focus condition for the binding
544       * @param pressed true if the key was pressed
545       * @return true <code>menuElement</code> or one of its children consume
546       * the event (processKeyBinding returns true for menuElement or one of
547       * its children).
548       */
549      static boolean processKeyBindingHelper(MenuElement menuElement, KeyStroke ks,
550                                             KeyEvent e, int condition,
551                                             boolean pressed)
552      {
553        if (menuElement == null)
554          return false;
555    
556        // First check the menuElement itself, if it's a JComponent
557        if (menuElement instanceof JComponent
558            && ((JComponent) menuElement).processKeyBinding(ks, e, condition,
559                                                            pressed))
560          return true;
561    
562        // If that didn't consume it, check all the children recursively
563        MenuElement[] children = menuElement.getSubElements();
564        for (int i = 0; i < children.length; i++)
565          if (processKeyBindingHelper(children[i], ks, e, condition, pressed))
566            return true;
567        return false;
568      }
569    
570      /**
571       * Process mouse events forwarded from MenuSelectionManager. This method
572       * doesn't do anything. It is here to conform to the MenuElement interface.
573       *
574       * @param event event forwarded from MenuSelectionManager
575       * @param path path to the menu element from which event was generated
576       * @param manager MenuSelectionManager for the current menu hierarchy
577       *
578       */
579      public void processMouseEvent(MouseEvent event, MenuElement[] path,
580                                    MenuSelectionManager manager)
581      {
582        // Do nothing - needed for implementation of MenuElement interface
583      }
584    
585      /**
586       * This method overrides removeNotify() in the Container to
587       * unregister this menu bar from the current keyboard manager.
588       */
589      public void removeNotify()
590      {
591        KeyboardManager.getManager().unregisterJMenuBar(this);
592        super.removeNotify();
593      }
594    
595      /**
596       * Sets painting status of the border. If 'b' is true then menu bar's
597       * border will be painted, and it will not be painted otherwise.
598       *
599       * @param b indicates if menu bar's border should be painted.
600       */
601      public void setBorderPainted(boolean b)
602      {
603        if (b != borderPainted)
604          {
605            boolean old = borderPainted;
606            borderPainted = b;
607            firePropertyChange("borderPainted", old, b);
608            revalidate();
609            repaint();
610          }
611      }
612    
613      /**
614       * Sets help menu for this menu bar
615       *
616       * @param menu help menu
617       *
618       * @specnote The specification states that this method is not yet implemented
619       *           and should throw an exception.
620       */
621      public void setHelpMenu(JMenu menu)
622      {
623        // We throw an Error here, just as Sun's JDK does.
624        throw new Error("setHelpMenu() not yet implemented.");
625      }
626    
627      /**
628       * Sets the margin between the menu bar's border and its menus (this is a
629       * bound property with the name 'margin').
630       *
631       * @param m  the margin (<code>null</code> permitted).
632       *
633       * @see #getMargin()
634       */
635      public void setMargin(Insets m)
636      {
637        if (m != margin)
638          {
639            Insets oldMargin = margin;
640            margin = m;
641            firePropertyChange("margin", oldMargin, margin);
642          }
643      }
644    
645      /**
646       * Changes menu bar's selection to the specified menu.
647       * This method updates selected index of menu bar's selection model,
648       * which results in a model firing change event.
649       *
650       * @param sel menu to select
651       */
652      public void setSelected(Component sel)
653      {
654        int index = getComponentIndex(sel);
655        selectionModel.setSelectedIndex(index);
656      }
657    
658      /**
659       * Sets menuBar's selection model to the one specified
660       *
661       * @param model SingleSelectionModel that needs to be set for this menu bar
662       */
663      public void setSelectionModel(SingleSelectionModel model)
664      {
665        if (selectionModel != model)
666          {
667            SingleSelectionModel oldModel = selectionModel;
668            selectionModel = model;
669            firePropertyChange("model", oldModel, selectionModel);
670          }
671      }
672    
673      /**
674       * Set the "UI" property of the menu bar, which is a look and feel class
675       * responsible for handling menuBar's input events and painting it.
676       *
677       * @param ui The new "UI" property
678       */
679      public void setUI(MenuBarUI ui)
680      {
681        super.setUI(ui);
682      }
683    
684      /**
685       * Set the "UI" property to a class constructed, via the {@link
686       * UIManager}, from the current look and feel.
687       */
688      public void updateUI()
689      {
690        setUI((MenuBarUI) UIManager.getUI(this));
691      }
692    }