libjava/java/awt/MenuComponent.java

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