Source for java.awt.MenuComponent

   1: /* MenuComponent.java -- Superclass of all AWT menu components
   2:    Copyright (C) 1999, 2000, 2002, 2003, 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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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 java.awt;
  40: 
  41: import java.awt.event.FocusEvent;
  42: import java.awt.event.FocusListener;
  43: import java.awt.peer.MenuComponentPeer;
  44: import java.io.Serializable;
  45: import java.util.Locale;
  46: 
  47: import javax.accessibility.Accessible;
  48: import javax.accessibility.AccessibleComponent;
  49: import javax.accessibility.AccessibleContext;
  50: import javax.accessibility.AccessibleRole;
  51: import javax.accessibility.AccessibleSelection;
  52: import javax.accessibility.AccessibleStateSet;
  53: 
  54: /**
  55:   * This is the superclass of all menu AWT widgets. 
  56:   *
  57:   * @author Aaron M. Renn (arenn@urbanophile.com)
  58:   * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  59:   */
  60: public abstract class MenuComponent implements Serializable
  61: {
  62: 
  63: /*
  64:  * Static Variables
  65:  */
  66: 
  67: // Serialization Constant
  68: private static final long serialVersionUID = -4536902356223894379L;
  69: 
  70: /*************************************************************************/
  71:   
  72: /*
  73:  * Instance Variables
  74:  */
  75: 
  76: /**
  77:  * The font for this component.
  78:  *
  79:  * @see #getFont()
  80:  * @see #setFont(java.awt.Font)
  81:  * @serial the component's font.
  82:  */
  83:   private Font font;
  84: 
  85:   /**
  86:    * The name of the component.
  87:    *
  88:    * @see #getName()
  89:    * @see #setName(String)
  90:    * @serial the component's name.
  91:    */
  92:   private String name;
  93: 
  94:   /**
  95:    * The parent of this component.
  96:    *
  97:    * @see #getParent()
  98:    * @see #setParent(java.awt.MenuContainer)
  99:    * @serial ignored.
 100:    */
 101:   transient MenuContainer parent;
 102: 
 103:   /**
 104:    * The native peer for this component.
 105:    *
 106:    * @see #getPeer()
 107:    * @see #setPeer(java.awt.peer.MenuComponentPeer)
 108:    * @serial ignored.
 109:    */
 110:   transient MenuComponentPeer peer;
 111: 
 112:   /**
 113:    * The synchronization locking object for this component.
 114:    *
 115:    * @serial ignored.
 116:    */
 117:   private transient Object tree_lock = this;
 118: 
 119:   /**
 120:    * The toolkit for this object.
 121:    *
 122:    * @see #getToolkit()
 123:    * @serial ignored.
 124:    */
 125:   private static transient Toolkit toolkit = Toolkit.getDefaultToolkit();
 126: 
 127:   /**
 128:    * The accessible context for this component.
 129:    *
 130:    * @see #getAccessibleContext()
 131:    * @serial the accessibility information for this component.
 132:    */
 133:   AccessibleContext accessibleContext;
 134: 
 135:   /**
 136:    * Was the name of the component set?  This value defaults
 137:    * to false and becomes true after a call to <code>setName()</code>.
 138:    * Please note that this does not guarantee that name will then
 139:    * be non-null, as this may be the value passed to <code>setName()</code>.
 140:    *
 141:    * @see #setName(String)
 142:    * @serial true if the name value has been explicitly set by calling
 143:    *         <code>setName()</code>.
 144:    */
 145:   private boolean nameExplicitlySet;
 146: 
 147:   /**
 148:    * Does this component handle new events?  Events will be handled
 149:    * by this component if this is true.  Otherwise, they will be forwarded
 150:    * up the component hierarchy.  This implementation does not use this
 151:    * variable; it is merely provided for serialization compatability.
 152:    *
 153:    * @see #dispatchEvent(AWTEvent)
 154:    * @serial true if events are to be processed locally.  Unused.
 155:    */
 156:   private boolean newEventsOnly;
 157: 
 158:   /**
 159:    * The focus listener chain handler which deals with focus events for
 160:    * the accessible context of this component.
 161:    *
 162:    * @see AccessibleAWTMenuComponent#addFocusListener(java.awt.event.FocusListener)
 163:    * @serial ignored.
 164:    * This is package-private to avoid an accessor method.
 165:    */
 166:   transient FocusListener focusListener;
 167: 
 168: /*************************************************************************/
 169: 
 170: /*
 171:  * Constructors
 172:  */
 173: 
 174: /**
 175:   * Default constructor for subclasses.
 176:   *
 177:   * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 178:   */
 179: public
 180: MenuComponent()
 181: {
 182:   if (GraphicsEnvironment.isHeadless())
 183:     throw new HeadlessException ();
 184: }
 185: 
 186: /*************************************************************************/
 187: 
 188: /*
 189:  * Instance Methods
 190:  */
 191: 
 192: /**
 193:   * Returns the font in use for this component.
 194:   *
 195:   * @return The font for this component.
 196:   */
 197: public Font
 198: getFont()
 199: {
 200:   if (font != null)
 201:     return font;
 202: 
 203:   if (parent != null)
 204:     return parent.getFont ();
 205: 
 206:   return null;
 207: }
 208: 
 209: /*************************************************************************/
 210: 
 211: /**
 212:   * Sets the font for this component to the specified font.
 213:   *
 214:   * @param font The new font for this component.
 215:   */
 216: public void
 217: setFont(Font font)
 218: {
 219:   this.font = font;
 220: }
 221: 
 222: /*************************************************************************/
 223: 
 224: /**
 225:   * Returns the name of this component.
 226:   *
 227:   * @return The name of this component.
 228:   */
 229: public String
 230: getName()
 231: {
 232:   return(name);
 233: }
 234: 
 235: /*************************************************************************/
 236: 
 237: /**
 238:   * Sets the name of this component to the specified name.
 239:   *
 240:   * @param name The new name of this component.
 241:   */
 242: public void
 243: setName(String name)
 244: {
 245:   this.name = name;
 246:   nameExplicitlySet = true;
 247: }
 248: 
 249: /*************************************************************************/
 250: 
 251: /**
 252:   * Returns the parent of this component.
 253:   * 
 254:   * @return The parent of this component.
 255:   */
 256: public MenuContainer
 257: getParent()
 258: {
 259:   return(parent);
 260: } 
 261: 
 262: /*************************************************************************/
 263: 
 264: // Sets the parent of this component.
 265: final void
 266: setParent(MenuContainer parent)
 267: {
 268:   this.parent = parent;
 269: }
 270: 
 271: /*************************************************************************/
 272: 
 273: /**
 274:   * Returns the native windowing system peer for this component.
 275:   *
 276:   * @return The peer for this component.
 277:   *
 278:   * @deprecated
 279:   */
 280: public MenuComponentPeer
 281: getPeer()
 282: {
 283:   return(peer);
 284: }
 285: 
 286: /*************************************************************************/
 287: 
 288: // Sets the peer for this component.
 289: final void
 290: setPeer(MenuComponentPeer peer)
 291: {
 292:   this.peer = peer;
 293: }
 294: 
 295: /*************************************************************************/
 296: 
 297: /**
 298:   * Destroys this component's native peer
 299:   */
 300: public void
 301: removeNotify()
 302: {
 303:   if (peer != null)
 304:     peer.dispose();
 305:   peer = null;
 306: }
 307: 
 308: /*************************************************************************/
 309: 
 310: /**
 311:   * Returns the toolkit in use for this component.
 312:   *
 313:   * @return The toolkit for this component.
 314:   */
 315: final Toolkit
 316: getToolkit()
 317: {
 318:   return(toolkit);
 319: }
 320: 
 321: /*************************************************************************/
 322: 
 323: /**
 324:   * Returns the object used for synchronization locks on this component
 325:   * when performing tree and layout functions.
 326:   *
 327:   * @return The synchronization lock for this component.
 328:   */
 329: protected final Object
 330: getTreeLock()
 331: {
 332:   return(tree_lock);
 333: }
 334: 
 335: /*************************************************************************/
 336: 
 337: // The sync lock object for this component.
 338: final void
 339: setTreeLock(Object tree_lock)
 340: {
 341:   this.tree_lock = tree_lock;
 342: }
 343: 
 344: /*************************************************************************/
 345: 
 346: /**
 347:   * AWT 1.0 event dispatcher.
 348:   *
 349:   * @deprecated Deprecated in favor of <code>dispatchEvent()</code>.
 350:   * @return true if the event was dispatched, false otherwise.
 351:   */
 352: public boolean
 353: postEvent(Event event)
 354: {
 355:   // This is overridden by subclasses that support events.
 356:   return false;
 357: }
 358: /*************************************************************************/
 359: 
 360: /**
 361:   * Sends this event to this component or a subcomponent for processing.
 362:   *
 363:   * @param event The event to dispatch
 364:   */
 365: public final void dispatchEvent(AWTEvent event)
 366: {
 367:   // See comment in Component.dispatchEvent().
 368:   dispatchEventImpl(event);
 369: }
 370: 
 371: 
 372: /**
 373:  * Implementation of dispatchEvent. Allows trusted package classes
 374:  * to dispatch additional events first.  This implementation first
 375:  * translates <code>event</code> to an AWT 1.0 event and sends the
 376:  * result to {@link #postEvent}.  The event is then
 377:  * passed on to {@link #processEvent} for local processing.
 378:  *
 379:  * @param event the event to dispatch.
 380:  */
 381: void dispatchEventImpl(AWTEvent event)
 382: {
 383:   Event oldStyleEvent;
 384: 
 385:   // This is overridden by subclasses that support events.
 386:   /* Convert AWT 1.1 event to AWT 1.0 event */
 387:   oldStyleEvent = Component.translateEvent(event);
 388:   if (oldStyleEvent != null)
 389:     {
 390:       postEvent(oldStyleEvent);
 391:     }
 392:   /* Do local processing */
 393:   processEvent(event);
 394: }
 395: 
 396: /*************************************************************************/
 397: 
 398: /**
 399:   * Processes the specified event.  In this class, this method simply
 400:   * calls one of the more specific event handlers.
 401:   * 
 402:   * @param event The event to process.
 403:   */
 404: protected void
 405: processEvent(AWTEvent event)
 406: {
 407:   /* 
 408:      Pass a focus event to the focus listener for
 409:      the accessibility context.
 410:   */
 411:   if (event instanceof FocusEvent)
 412:     {
 413:       if (focusListener != null)
 414:         {
 415:           switch (event.id)
 416:             {
 417:             case FocusEvent.FOCUS_GAINED:
 418:               focusListener.focusGained((FocusEvent) event);
 419:               break;
 420:             case FocusEvent.FOCUS_LOST:
 421:               focusListener.focusLost((FocusEvent) event);
 422:               break;
 423:             }
 424:         }
 425:     }
 426: }
 427: 
 428: /*************************************************************************/
 429: 
 430: /**
 431:   * Returns a string representation of this component.
 432:   *
 433:   * @return A string representation of this component
 434:   */
 435: public String
 436: toString()
 437: {
 438:   return this.getClass().getName() + "[" + paramString() + "]";
 439: }
 440: 
 441: /*************************************************************************/
 442: 
 443: /**
 444:  * Returns a debugging string for this component
 445:  */
 446: protected String
 447: paramString()
 448: {
 449:   return "name=" + getName();
 450: }
 451: 
 452: /**
 453:  * Gets the AccessibleContext associated with this <code>MenuComponent</code>.
 454:  * As an abstract class, we return null.  Concrete subclasses should return
 455:  * their implementation of the accessibility context.
 456:  *
 457:  * @return null.
 458:  */
 459: 
 460: public AccessibleContext getAccessibleContext()
 461: {
 462:   return null;
 463: }
 464: 
 465: /**
 466:  * This class provides a base for the accessibility support of menu
 467:  * components.
 468:  *
 469:  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
 470:  */
 471: protected abstract class AccessibleAWTMenuComponent
 472:   extends AccessibleContext
 473:   implements Serializable, AccessibleComponent, AccessibleSelection
 474: {
 475: 
 476:   /**
 477:    * Compatible with JDK 1.4.2 revision 5
 478:    */
 479:   private static final long serialVersionUID = -4269533416223798698L;
 480: 
 481:   /**
 482:    * This is the default constructor.  It should be called by
 483:    * concrete subclasses to ensure necessary groundwork is completed.
 484:    */
 485:   protected AccessibleAWTMenuComponent()
 486:   {
 487:   }
 488: 
 489:   /**
 490:    * Replaces or supplements the component's selection with the
 491:    * <code>Accessible</code> child at the supplied index.  If
 492:    * the component supports multiple selection, the child is
 493:    * added to the current selection.  Otherwise, the current
 494:    * selection becomes the specified child.  If the child is
 495:    * already selected, nothing happens.
 496:    * <br />
 497:    * <br />
 498:    * As the existence of children can not be determined from
 499:    * this abstract class, the implementation of this method
 500:    * is left to subclasses.
 501:    *
 502:    * @param index the index of the specified child within a
 503:    *        zero-based list of the component's children.
 504:    */
 505:   public void addAccessibleSelection(int index)
 506:   {
 507:     /* Subclasses with children should implement this */
 508:   }
 509: 
 510:   /**
 511:    * Registers the specified focus listener to receive
 512:    * focus events from this component.
 513:    *
 514:    * @param listener the new focus listener.
 515:    */
 516:   public void addFocusListener(FocusListener listener)
 517:   {
 518:     /*
 519:      * Chain the new focus listener to the existing chain
 520:      * of focus listeners.  Each new focus listener is
 521:      * coupled via multicasting to the existing chain.
 522:      */
 523:     focusListener = AWTEventMulticaster.add(focusListener, listener);
 524:   }
 525: 
 526:   /**
 527:    * Clears the component's current selection.  Following
 528:    * the calling of this method, no children of the component
 529:    * will be selected.
 530:    * <br />
 531:    * <br />
 532:    * As the existence of children can not be determined from
 533:    * this abstract class, the implementation of this method
 534:    * is left to subclasses.
 535:    */
 536:   public void clearAccessibleSelection()
 537:   {
 538:   }
 539: 
 540:   /**
 541:    * Returns true if the specified point lies within the
 542:    * component.  The supplied co-ordinates are assumed to
 543:    * be relative to the co-ordinate system of the component
 544:    * itself.  Thus, the point (0,0) is the upper left corner
 545:    * of this component.
 546:    * <br />
 547:    * <br />
 548:    * Please note that this method depends on a correctly implemented
 549:    * version of the <code>getBounds()</code> method.  Subclasses
 550:    * must provide the bounding rectangle via <code>getBounds()</code>
 551:    * in order for this method to work.  
 552:    *
 553:    * @param point the point to check against this component.
 554:    * @return true if the point is within this component.
 555:    * @see #getBounds()
 556:    */
 557:   public boolean contains(Point point)
 558:   {
 559:     /* 
 560:        We can simply return the result of a
 561:        test for containment in the bounding rectangle 
 562:     */
 563:     return getBounds().contains(point);
 564:   }
 565: 
 566:   /**
 567:    * Returns the <code>Accessible</code> child of this component present
 568:    * at the specified point.  The supplied co-ordinates are
 569:    * assumed to be relative to the co-ordinate system of this
 570:    * component (the parent of any returned accessible).  Thus,
 571:    * the point (0,0) is the upper left corner of this menu
 572:    * component.
 573:    * <br />
 574:    * <br />
 575:    * As the existence of children can not be determined from
 576:    * this abstract class, the implementation of this method
 577:    * is left to subclasses.
 578:    * 
 579:    * @param point the point at which the returned accessible
 580:    *        is located.
 581:    * @return null.
 582:    */
 583:   public Accessible getAccessibleAt(Point point)
 584:   {
 585:     return null;
 586:   }
 587: 
 588:   /**
 589:    * Returns the <code>Accessible</code> child at the supplied
 590:    * index within the list of children of this component.
 591:    * <br />
 592:    * <br />
 593:    * As the existence of children can not be determined from
 594:    * this abstract class, the implementation of this method
 595:    * is left to subclasses.
 596:    *
 597:    * @param index the index of the <code>Accessible</code> child
 598:    *        to retrieve.
 599:    * @return null.
 600:    */
 601:   public Accessible getAccessibleChild(int index)
 602:   {
 603:     return null;
 604:   }
 605: 
 606:   /**
 607:    * Returns the number of children of this component which
 608:    * implement the <code>Accessible</code> interface.  If
 609:    * all children of this component are accessible, then
 610:    * the returned value will be the same as the number of
 611:    * children.
 612:    * <br />
 613:    * <br />
 614:    *
 615:    * @return 0.
 616:    */
 617:   public int getAccessibleChildrenCount()
 618:   {
 619:     return 0;
 620:   }
 621: 
 622:   /**
 623:    * Retrieves the <code>AccessibleComponent</code> associated
 624:    * with this accessible context and its component.  As the
 625:    * context itself implements <code>AccessibleComponent</code>,
 626:    * this is the return value.
 627:    *
 628:    * @return the context itself.
 629:    */
 630:   public AccessibleComponent getAccessibleComponent()
 631:   {
 632:     return this;
 633:   }
 634: 
 635:   /**
 636:    * Returns the accessible name for this menu component.  This
 637:    * is the name given to the component, which may be null if
 638:    * not set using <code>setName()</code>.
 639:    * <br />
 640:    * <br />
 641:    * The name is not the most appropriate description of this
 642:    * object.  Subclasses should preferably provide a more
 643:    * accurate description.  For example, a File menu could
 644:    * have the description `Lists commands related to the
 645:    * file system'.
 646:    *
 647:    * @return a description of the component.  Currently,
 648:    *         this is just the contents of the name property.
 649:    * @see MenuComponent#setName(String)
 650:    */
 651:   public String getAccessibleDescription()
 652:   {
 653:     return MenuComponent.this.getName();
 654:   }
 655: 
 656:   /**
 657:    * Retrieves the index of this component within its parent.
 658:    * If no parent exists, -1 is returned.
 659:    *
 660:    * @return -1 as the parent, a <code>MenuContainer</code>
 661:    *         is not <code>Accessible</code>.
 662:    */
 663:   public int getAccessibleIndexInParent()
 664:   {
 665:     return -1;
 666:   }
 667: 
 668:   /**
 669:    * Returns the accessible name of this component.  This
 670:    * is the name given to the component, which may be null if
 671:    * not set using <code>setName()</code>.
 672:    * <br />
 673:    * <br />
 674:    * The name property is not the most suitable string to return
 675:    * for this method.  The string should be localized, and
 676:    * relevant to the operation of the component.  For example,
 677:    * it could be the text of a menu item.  However, this can
 678:    * not be used at this level of abstraction, so it is the
 679:    * responsibility of subclasses to provide a more appropriate
 680:    * name.
 681:    *
 682:    * @return a localized name for this component.  Currently, this
 683:    *         is just the contents of the name property.
 684:    * @see MenuComponent#setName(String)
 685:    */
 686:   public String getAccessibleName()
 687:   {
 688:     return MenuComponent.this.getName();
 689:   }
 690: 
 691:   /**
 692:    * Returns the <code>Accessible</code> parent of this component.
 693:    * As the parent of a <code>MenuComponent</code> is a
 694:    * <code>MenuContainer</code>, which doesn't implement
 695:    * <code>Accessible</code>, this method returns null.
 696:    *
 697:    * @return null.
 698:    */
 699:   public Accessible getAccessibleParent()
 700:   {
 701:     return null;
 702:   }
 703: 
 704:   /**
 705:    * Returns the accessible role of this component.
 706:    * <br />
 707:    * <br />
 708:    * The abstract implementation of this method returns
 709:    * <code>AccessibleRole.AWT_COMPONENT</code>,
 710:    * as the abstract component has no specific role.  This
 711:    * method should be overridden by concrete subclasses, so
 712:    * as to return an appropriate role for the component.
 713:    *
 714:    * @return <code>AccessibleRole.AWT_COMPONENT</code>.
 715:    */
 716:   public AccessibleRole getAccessibleRole()
 717:   {
 718:     return AccessibleRole.AWT_COMPONENT;
 719:   }
 720: 
 721:   /**
 722:    * Retrieves the <code>AccessibleSelection</code> associated
 723:    * with this accessible context and its component.  As the
 724:    * context itself implements <code>AccessibleSelection</code>,
 725:    * this is the return value.
 726:    *
 727:    * @return the context itself.
 728:    */
 729:   public AccessibleSelection getAccessibleSelection()
 730:   {
 731:     return this;
 732:   }
 733: 
 734:   /**
 735:    * Retrieves the <code>Accessible</code> selected child
 736:    * at the specified index.  If there are no selected children
 737:    * or the index is outside the range of selected children,
 738:    * null is returned.  Please note that the index refers
 739:    * to the index of the child in the list of <strong>selected
 740:    * children</strong>, and not the index of the child in
 741:    * the list of all <code>Accessible</code> children.
 742:    * <br />
 743:    * <br />
 744:    * As the existence of children can not be determined from
 745:    * this abstract class, the implementation of this method
 746:    * is left to subclasses.
 747:    *
 748:    * @param index the index of the selected <code>Accessible</code>
 749:    *        child.
 750:    */
 751:   public Accessible getAccessibleSelection(int index)
 752:   {
 753:     return null;
 754:   }
 755: 
 756:   /**
 757:    * Returns a count of the number of <code>Accessible</code>
 758:    * children of this component which are currently selected.
 759:    * If there are no children currently selected, 0 is returned.
 760:    * <br />
 761:    * <br />
 762:    * As the existence of children can not be determined from
 763:    * this abstract class, the implementation of this method
 764:    * is left to subclasses.
 765:    *
 766:    * @return 0.
 767:    */
 768:   public int getAccessibleSelectionCount()
 769:   {
 770:     return 0;
 771:   }
 772: 
 773:   /**
 774:    * Retrieves the current state of this component
 775:    * in an accessible form.  For example, a given component
 776:    * may be visible, selected, disabled, etc.
 777:    * <br />
 778:    * <br />
 779:    * As this class tells us virtually nothing about the component,
 780:    * except for its name and font, no state information can be
 781:    * provided.  This implementation thus returns an empty
 782:    * state set, and it is left to concrete subclasses to provide
 783:    * a more acceptable and relevant state set.  Changes to these
 784:    * properties also need to be handled using
 785:    * <code>PropertyChangeListener</code>s.
 786:    *
 787:    * @return an empty <code>AccessibleStateSet</code>.
 788:    */
 789:   public AccessibleStateSet getAccessibleStateSet()
 790:   {
 791:     return new AccessibleStateSet();
 792:   }
 793: 
 794:   /**
 795:    * Returns the background color of the component, or null
 796:    * if this property is unsupported.
 797:    * <br />
 798:    * <br />
 799:    * This abstract class knows nothing about how the component
 800:    * is drawn on screen, so this method simply returns the
 801:    * default system background color used for rendering menus.
 802:    * Concrete subclasses which handle the drawing of an onscreen
 803:    * menu component should override this method and provide
 804:    * the appropriate information.
 805:    *
 806:    * @return the default system background color for menus.
 807:    * @see #setBackground(java.awt.Color)
 808:    */
 809:   public Color getBackground()
 810:   {
 811:     return SystemColor.menu;
 812:   }
 813: 
 814:   /**
 815:    * Returns a <code>Rectangle</code> which represents the
 816:    * bounds of this component.  The returned rectangle has the
 817:    * height and width of the component's bounds, and is positioned
 818:    * at a location relative to this component's parent, the
 819:    * <code>MenuContainer</code>.  null is returned if bounds
 820:    * are not supported by the component.
 821:    * <br />
 822:    * <br />
 823:    * This abstract class knows nothing about how the component
 824:    * is drawn on screen, so this method simply returns null.
 825:    * Concrete subclasses which handle the drawing of an onscreen
 826:    * menu component should override this method and provide
 827:    * the appropriate information.
 828:    *
 829:    * @return null.
 830:    * @see #setBounds(java.awt.Rectangle)
 831:    */
 832:   public Rectangle getBounds()
 833:   {
 834:     return null;
 835:   }
 836: 
 837:   /**
 838:    * Returns the <code>Cursor</code> displayed when the pointer
 839:    * is positioned over this component.  Alternatively, null
 840:    * is returned if the component doesn't support the cursor
 841:    * property.
 842:    * <br />
 843:    * <br />
 844:    * This abstract class knows nothing about how the component
 845:    * is drawn on screen, so this method simply returns the default
 846:    * system cursor.  Concrete subclasses which handle the drawing
 847:    * of an onscreen menu component may override this method and provide
 848:    * the appropriate information.
 849:    *
 850:    * @return the default system cursor.
 851:    * @see #setCursor(java.awt.Cursor)
 852:    */
 853:   public Cursor getCursor()
 854:   {
 855:     return Cursor.getDefaultCursor();
 856:   }
 857: 
 858:   /**
 859:    * Returns the <code>Font</code> used for text created by this component.
 860:    *
 861:    * @return the current font.
 862:    * @see #setFont(java.awt.Font)
 863:    */
 864:   public Font getFont()
 865:   {
 866:     return MenuComponent.this.getFont();
 867:   }
 868: 
 869:   /**
 870:    * Retrieves information on the rendering and metrics of the supplied
 871:    * font.  If font metrics are not supported by this component, null
 872:    * is returned.
 873:    * <br />
 874:    * <br />
 875:    * The abstract implementation of this method simply uses the toolkit
 876:    * to obtain the <code>FontMetrics</code>.  Concrete subclasses may
 877:    * find it more efficient to invoke their peer class directly, if one
 878:    * is available.
 879:    *
 880:    * @param font the font about which to retrieve rendering and metric
 881:    *        information.
 882:    * @return the metrics of the given font, as provided by the system
 883:    *         toolkit.
 884:    * @throws NullPointerException if the supplied font was null.
 885:    */
 886:   public FontMetrics getFontMetrics(Font font)
 887:   {
 888:     return MenuComponent.this.getToolkit().getFontMetrics(font);
 889:   }
 890: 
 891:   /**
 892:    * Returns the foreground color of the component, or null
 893:    * if this property is unsupported.
 894:    * <br />
 895:    * <br />
 896:    * This abstract class knows nothing about how the component
 897:    * is drawn on screen, so this method simply returns the
 898:    * default system text color used for rendering menus.
 899:    * Concrete subclasses which handle the drawing of an onscreen
 900:    * menu component should override this method and provide
 901:    * the appropriate information.
 902:    *
 903:    * @return the default system text color for menus.
 904:    * @see #setForeground(java.awt.Color)
 905:    */
 906:   public Color getForeground()
 907:   {
 908:     return SystemColor.menuText;
 909:   }
 910: 
 911:   /**
 912:    * Returns the locale currently in use by this component.
 913:    * <br />
 914:    * <br />
 915:    * This abstract class has no property relating to the
 916:    * locale used by the component, so this method simply
 917:    * returns the default locale for the current instance
 918:    * of the Java Virtual Machine (JVM).  Concrete subclasses
 919:    * which maintain such a property should override this method
 920:    * and provide the locale information more accurately.
 921:    *
 922:    * @return the default locale for this JVM instance.
 923:    */
 924:   public Locale getLocale()
 925:   {
 926:     return Locale.getDefault();
 927:   }
 928: 
 929:   /**
 930:    * Returns the location of the component, with co-ordinates
 931:    * relative to the parent component and using the co-ordinate
 932:    * space of the screen.  Thus, the point (0,0) is the upper
 933:    * left corner of the parent component.
 934:    * <br />
 935:    * <br />
 936:    * Please note that this method depends on a correctly implemented
 937:    * version of the <code>getBounds()</code> method.  Subclasses
 938:    * must provide the bounding rectangle via <code>getBounds()</code>
 939:    * in order for this method to work.  
 940:    *
 941:    * @return the location of the component, relative to its parent.
 942:    * @see #setLocation(java.awt.Point)
 943:    */
 944:   public Point getLocation()
 945:   {
 946:     /* Simply return the location of the bounding rectangle */
 947:     return getBounds().getLocation();
 948:   }
 949: 
 950:   /**
 951:    * Returns the location of the component, with co-ordinates
 952:    * relative to the screen.  Thus, the point (0,0) is the upper
 953:    * left corner of the screen.  null is returned if the component
 954:    * is either not on screen or if this property is unsupported.
 955:    * <br />
 956:    * <br />
 957:    * This abstract class knows nothing about how the component
 958:    * is drawn on screen, so this method simply returns null.
 959:    * Concrete subclasses which handle the drawing of an onscreen
 960:    * menu component should override this method and provide
 961:    * the appropriate information.
 962:    *
 963:    * @return the location of the component, relative to the screen.
 964:    */
 965:   public Point getLocationOnScreen()
 966:   {
 967:     return null;
 968:   }
 969: 
 970:   /**
 971:    * Returns the size of the component.
 972:    * <br />
 973:    * <br />
 974:    * Please note that this method depends on a correctly implemented
 975:    * version of the <code>getBounds()</code> method.  Subclasses
 976:    * must provide the bounding rectangle via <code>getBounds()</code>
 977:    * in order for this method to work.  
 978:    *
 979:    * @return the size of the component.
 980:    * @see #setSize(java.awt.Dimension)
 981:    */
 982:   public Dimension getSize()
 983:   {
 984:     /* Simply return the size of the bounding rectangle */
 985:     return getBounds().getSize();
 986:   }
 987: 
 988:   /**
 989:    * Returns true if the accessible child specified by the supplied index
 990:    * is currently selected.
 991:    * <br />
 992:    * <br />
 993:    * As the existence of children can not be determined from
 994:    * this abstract class, the implementation of this method
 995:    * is left to subclasses.
 996:    *
 997:    * @param index the index of the accessible child to check for selection.
 998:    * @return false.
 999:    */
1000:   public boolean isAccessibleChildSelected(int index)
1001:   {
1002:     return false;
1003:   }
1004: 
1005:   /**
1006:    * Returns true if this component is currently enabled.
1007:    * <br />
1008:    * <br />
1009:    * As this abstract component has no properties related to
1010:    * its enabled or disabled state, the implementation of this
1011:    * method is left to subclasses.
1012:    *
1013:    * @return false.
1014:    * @see #setEnabled(boolean)
1015:    */
1016:   public boolean isEnabled()
1017:   {
1018:     return false;
1019:   }
1020: 
1021:   /**
1022:    * Returns true if this component is included in the traversal
1023:    * of the current focus from one component to the other.
1024:    * <br />
1025:    * <br />
1026:    * As this abstract component has no properties related to
1027:    * its ability to accept the focus, the implementation of this
1028:    * method is left to subclasses.
1029:    *
1030:    * @return false.
1031:    */
1032:   public boolean isFocusTraversable()
1033:   {
1034:     return false;
1035:   }
1036: 
1037:   /**
1038:    * Returns true if the component is being shown on screen.
1039:    * A component is determined to be shown if it is visible,
1040:    * and each parent component is also visible.  Please note
1041:    * that, even when a component is showing, it may still be
1042:    * obscured by other components in front.  This method only
1043:    * determines if the component is being drawn on the screen.
1044:    * <br />
1045:    * <br />
1046:    * As this abstract component and its parent have no properties
1047:    * relating to visibility, the implementation of this method is
1048:    * left to subclasses.
1049:    *
1050:    * @return false.
1051:    * @see #isVisible()
1052:    */
1053:   public boolean isShowing()
1054:   {
1055:     return false;
1056:   }
1057: 
1058:   /**
1059:    * Returns true if the component is visible.  A component may
1060:    * be visible but not drawn on the screen if one of its parent
1061:    * components is not visible.  To determine if the component is
1062:    * actually drawn on screen, <code>isShowing()</code> should be
1063:    * used.
1064:    * <br />
1065:    * <br />
1066:    * As this abstract component has no properties relating to its
1067:    * visibility, the implementation of this method is left to subclasses.
1068:    *
1069:    * @return false.
1070:    * @see #isShowing()
1071:    * @see #setVisible(boolean)
1072:    */
1073:   public boolean isVisible()
1074:   {
1075:     return false;
1076:   }
1077: 
1078:   /**
1079:    * Removes the accessible child specified by the supplied index from
1080:    * the list of currently selected children.  If the child specified
1081:    * is not selected, nothing happens.
1082:    * <br />
1083:    * <br />
1084:    * As the existence of children can not be determined from
1085:    * this abstract class, the implementation of this method
1086:    * is left to subclasses.
1087:    *
1088:    * @param index the index of the <code>Accessible</code> child.
1089:    */
1090:   public void removeAccessibleSelection(int index)
1091:   {
1092:     /* Subclasses with children should implement this */
1093:   }
1094: 
1095:   /**
1096:    * Removes the specified focus listener from the list of registered
1097:    * focus listeners for this component.
1098:    *
1099:    * @param listener the listener to remove.
1100:    */
1101:   public void removeFocusListener(FocusListener listener)
1102:   {
1103:     /* Remove the focus listener from the chain */
1104:     focusListener = AWTEventMulticaster.remove(focusListener, listener);
1105:   }
1106: 
1107:   /**
1108:    * Requests that this component gains focus.  This depends on the
1109:    * component being focus traversable.
1110:    * <br />
1111:    * <br />
1112:    * As this abstract component has no properties relating to its
1113:    * focus traversability, or access to a peer with request focusing
1114:    * abilities, the implementation of this method is left to subclasses.
1115:    */
1116:   public void requestFocus()
1117:   {
1118:     /* Ignored */
1119:   }
1120: 
1121:   /**
1122:    * Selects all <code>Accessible</code> children of this component which
1123:    * it is possible to select.  The component needs to support multiple
1124:    * selections.
1125:    * <br />
1126:    * <br />
1127:    * This abstract component provides a simplistic implementation of this
1128:    * method, which ignores the ability of the component to support multiple
1129:    * selections and simply uses <code>addAccessibleSelection</code> to
1130:    * add each <code>Accessible</code> child to the selection.  The last
1131:    * <code>Accessible</code> component is thus selected for components
1132:    * which don't support multiple selections.  Concrete implementations should
1133:    * override this with a more appopriate and efficient implementation, which
1134:    * properly takes into account the ability of the component to support multiple
1135:    * selections. 
1136:    */
1137:   public void selectAllAccessibleSelection()
1138:   {
1139:     /* Simply call addAccessibleSelection() on all accessible children */
1140:     for (int a = 0; a < getAccessibleChildrenCount(); ++a)
1141:       {
1142:         addAccessibleSelection(a);
1143:       }
1144:   }
1145: 
1146:   /**
1147:    * Sets the background color of the component to that specified.
1148:    * Unspecified behaviour occurs when null is given as the new
1149:    * background color.
1150:    * <br />
1151:    * <br />
1152:    * This abstract class knows nothing about how the component
1153:    * is drawn on screen, so this method simply ignores the supplied
1154:    * color and continues to use the default system color.   
1155:    * Concrete subclasses which handle the drawing of an onscreen
1156:    * menu component should override this method and provide
1157:    * the appropriate information.
1158:    *
1159:    * @param color the new color to use for the background.
1160:    * @see #getBackground()
1161:    */
1162:   public void setBackground(Color color)
1163:   {
1164:     /* Ignored */
1165:   }
1166: 
1167:   /**
1168:    * Sets the height and width of the component, and its position
1169:    * relative to this component's parent, to the values specified
1170:    * by the supplied rectangle.  Unspecified behaviour occurs when
1171:    * null is given as the new bounds.
1172:    * <br />
1173:    * <br />
1174:    * This abstract class knows nothing about how the component
1175:    * is drawn on screen, so this method simply ignores the new
1176:    * rectangle and continues to return null from <code>getBounds()</code>.
1177:    * Concrete subclasses which handle the drawing of an onscreen
1178:    * menu component should override this method and provide
1179:    * the appropriate information.
1180:    *
1181:    * @param rectangle a rectangle which specifies the new bounds of
1182:    *        the component.
1183:    * @see #getBounds()
1184:    */
1185:   public void setBounds(Rectangle rectangle)
1186:   {
1187:     /* Ignored */
1188:   }
1189: 
1190:   /**
1191:    * Sets the <code>Cursor</code> used when the pointer is positioned over the
1192:    * component.  Unspecified behaviour occurs when null is given as the new
1193:    * cursor.
1194:    * <br />
1195:    * <br />
1196:    * This abstract class knows nothing about how the component
1197:    * is drawn on screen, so this method simply ignores the new cursor
1198:    * and continues to return the default system cursor.  Concrete
1199:    * subclasses which handle the drawing of an onscreen menu component
1200:    * may override this method and provide the appropriate information.
1201:    *
1202:    * @param cursor the new cursor to use.
1203:    * @see #getCursor()
1204:    */
1205:   public void setCursor(Cursor cursor)
1206:   {
1207:     /* Ignored */
1208:   }
1209: 
1210:   /**
1211:    * Sets the enabled/disabled state of this component.
1212:    * <br />
1213:    * <br />
1214:    * As this abstract component has no properties related to
1215:    * its enabled or disabled state, the implementation of this
1216:    * method is left to subclasses.
1217:    *
1218:    * @param enabled true if the component should be enabled,
1219:    *        false otherwise.
1220:    * @see #isEnabled()
1221:    */
1222:   public void setEnabled(boolean enabled)
1223:   {
1224:     /* Ignored */
1225:   }
1226: 
1227:   /**
1228:    * Sets the <code>Font</code> used for text created by this component.
1229:    * Unspecified behaviour occurs when null is given as the new
1230:    * font.
1231:    *
1232:    * @param font the new font to use for text.
1233:    * @see #getFont()
1234:    */
1235:   public void setFont(Font font)
1236:   {
1237:     /* Call the method of the enclosing component */
1238:     MenuComponent.this.setFont(font);
1239:   }
1240: 
1241:   /**
1242:    * Sets the foreground color of the component to that specified.
1243:    * Unspecified behaviour occurs when null is given as the new
1244:    * background color.
1245:    * <br />
1246:    * <br />
1247:    * This abstract class knows nothing about how the component
1248:    * is drawn on screen, so this method simply ignores the supplied
1249:    * color and continues to return the default system text color used
1250:    * for rendering menus.
1251:    * Concrete subclasses which handle the drawing of an onscreen
1252:    * menu component should override this method and provide
1253:    * the appropriate information.
1254:    *
1255:    * @param color the new foreground color.
1256:    * @see #getForeground()
1257:    */
1258:   public void setForeground(Color color)
1259:   {
1260:     /* Ignored */
1261:   }
1262: 
1263:   /**
1264:    * Sets the location of the component, with co-ordinates
1265:    * relative to the parent component and using the co-ordinate
1266:    * space of the screen.  Thus, the point (0,0) is the upper
1267:    * left corner of the parent component.
1268:    * <br />
1269:    * <br />
1270:    * Please note that this method depends on a correctly implemented
1271:    * version of the <code>getBounds()</code> method.  Subclasses
1272:    * must provide the bounding rectangle via <code>getBounds()</code>
1273:    * in order for this method to work.  
1274:    *
1275:    * @param point the location of the component, relative to its parent.
1276:    * @see #getLocation()
1277:    */
1278:   public void setLocation(Point point)
1279:   {
1280:     getBounds().setLocation(point);
1281:   }
1282: 
1283:   /**
1284:    * Sets the size of the component.
1285:    * <br />
1286:    * <br />
1287:    * Please note that this method depends on a correctly implemented
1288:    * version of the <code>getBounds()</code> method.  Subclasses
1289:    * must provide the bounding rectangle via <code>getBounds()</code>
1290:    * in order for this method to work.  
1291:    *
1292:    * @param size the new size of the component.
1293:    * @see #getSize()
1294:    */
1295:   public void setSize(Dimension size)
1296:   {
1297:     getBounds().setSize(size);
1298:   }
1299: 
1300:   /**
1301:    * Sets the visibility state of the component.  A component may
1302:    * be visible but not drawn on the screen if one of its parent
1303:    * components is not visible.  To determine if the component is
1304:    * actually drawn on screen, <code>isShowing()</code> should be
1305:    * used.
1306:    * <br />
1307:    * <br />
1308:    * As this abstract component has no properties relating to its
1309:    * visibility, the implementation of this method is left to subclasses.
1310:    *
1311:    * @param visibility the new visibility of the component -- true if
1312:    *        the component is visible, false if not.
1313:    * @see #isShowing()
1314:    * @see #isVisible()
1315:    */
1316:   public void setVisible(boolean visibility)
1317:   {
1318:     /* Ignored */
1319:   }
1320: 
1321: } /* class AccessibleAWTMenuComponent */
1322:           
1323: 
1324: } // class MenuComponent