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