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 }