Source for java.awt.MenuComponent

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