001/* Component.java -- a graphics component
002   Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2006
003   Free Software Foundation
004
005This file is part of GNU Classpath.
006
007GNU Classpath is free software; you can redistribute it and/or modify
008it under the terms of the GNU General Public License as published by
009the Free Software Foundation; either version 2, or (at your option)
010any later version.
011
012GNU Classpath is distributed in the hope that it will be useful, but
013WITHOUT ANY WARRANTY; without even the implied warranty of
014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015General Public License for more details.
016
017You should have received a copy of the GNU General Public License
018along with GNU Classpath; see the file COPYING.  If not, write to the
019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02002110-1301 USA.
021
022Linking this library statically or dynamically with other modules is
023making a combined work based on this library.  Thus, the terms and
024conditions of the GNU General Public License cover the whole
025combination.
026
027As a special exception, the copyright holders of this library give you
028permission to link this library with independent modules to produce an
029executable, regardless of the license terms of these independent
030modules, and to copy and distribute the resulting executable under
031terms of your choice, provided that you also meet, for each linked
032independent module, the terms and conditions of the license of that
033module.  An independent module is a module which is not derived from
034or based on this library.  If you modify this library, you may extend
035this exception to your version of the library, but you are not
036obligated to do so.  If you do not wish to do so, delete this
037exception statement from your version. */
038
039
040package java.awt;
041
042//import gnu.java.awt.dnd.peer.gtk.GtkDropTargetContextPeer;
043
044import gnu.java.awt.ComponentReshapeEvent;
045
046import gnu.java.lang.CPStringBuilder;
047
048import java.awt.dnd.DropTarget;
049import java.awt.event.ActionEvent;
050import java.awt.event.AdjustmentEvent;
051import java.awt.event.ComponentEvent;
052import java.awt.event.ComponentListener;
053import java.awt.event.FocusEvent;
054import java.awt.event.FocusListener;
055import java.awt.event.HierarchyBoundsListener;
056import java.awt.event.HierarchyEvent;
057import java.awt.event.HierarchyListener;
058import java.awt.event.InputEvent;
059import java.awt.event.InputMethodEvent;
060import java.awt.event.InputMethodListener;
061import java.awt.event.KeyEvent;
062import java.awt.event.KeyListener;
063import java.awt.event.MouseEvent;
064import java.awt.event.MouseListener;
065import java.awt.event.MouseMotionListener;
066import java.awt.event.MouseWheelEvent;
067import java.awt.event.MouseWheelListener;
068import java.awt.event.PaintEvent;
069import java.awt.event.WindowEvent;
070import java.awt.im.InputContext;
071import java.awt.im.InputMethodRequests;
072import java.awt.image.BufferStrategy;
073import java.awt.image.ColorModel;
074import java.awt.image.ImageObserver;
075import java.awt.image.ImageProducer;
076import java.awt.image.VolatileImage;
077import java.awt.peer.ComponentPeer;
078import java.awt.peer.LightweightPeer;
079import java.beans.PropertyChangeEvent;
080import java.beans.PropertyChangeListener;
081import java.beans.PropertyChangeSupport;
082import java.io.IOException;
083import java.io.ObjectInputStream;
084import java.io.ObjectOutputStream;
085import java.io.PrintStream;
086import java.io.PrintWriter;
087import java.io.Serializable;
088import java.lang.reflect.Array;
089import java.util.Collections;
090import java.util.EventListener;
091import java.util.HashSet;
092import java.util.Iterator;
093import java.util.Locale;
094import java.util.Set;
095import java.util.Vector;
096
097import javax.accessibility.Accessible;
098import javax.accessibility.AccessibleComponent;
099import javax.accessibility.AccessibleContext;
100import javax.accessibility.AccessibleRole;
101import javax.accessibility.AccessibleState;
102import javax.accessibility.AccessibleStateSet;
103
104/**
105 * The root of all evil. All graphical representations are subclasses of this
106 * giant class, which is designed for screen display and user interaction.
107 * This class can be extended directly to build a lightweight component (one
108 * not associated with a native window); lightweight components must reside
109 * inside a heavyweight window.
110 *
111 * <p>This class is Serializable, which has some big implications. A user can
112 * save the state of all graphical components in one VM, and reload them in
113 * another. Note that this class will only save Serializable listeners, and
114 * ignore the rest, without causing any serialization exceptions. However, by
115 * making a listener serializable, and adding it to another element, you link
116 * in that entire element to the state of this component. To get around this,
117 * use the idiom shown in the example below - make listeners non-serializable
118 * in inner classes, rather than using this object itself as the listener, if
119 * external objects do not need to save the state of this object.
120 *
121 * <pre>
122 * import java.awt.*;
123 * import java.awt.event.*;
124 * import java.io.Serializable;
125 * class MyApp implements Serializable
126 * {
127 *   BigObjectThatShouldNotBeSerializedWithAButton bigOne;
128 *   // Serializing aButton will not suck in an instance of MyApp, with its
129 *   // accompanying field bigOne.
130 *   Button aButton = new Button();
131 *   class MyActionListener implements ActionListener
132 *   {
133 *     public void actionPerformed(ActionEvent e)
134 *     {
135 *       System.out.println("Hello There");
136 *     }
137 *   }
138 *   MyApp()
139 *   {
140 *     aButton.addActionListener(new MyActionListener());
141 *   }
142 * }
143 * </pre>
144 *
145 * <p>Status: Incomplete. The event dispatch mechanism is implemented. All
146 * other methods defined in the J2SE 1.3 API javadoc exist, but are mostly
147 * incomplete or only stubs; except for methods relating to the Drag and
148 * Drop, Input Method, and Accessibility frameworks: These methods are
149 * present but commented out.
150 *
151 * @author original author unknown
152 * @author Eric Blake (ebb9@email.byu.edu)
153 * @since 1.0
154 * @status still missing 1.4 support
155 */
156public abstract class Component
157  implements ImageObserver, MenuContainer, Serializable
158{
159  // Word to the wise - this file is huge. Search for '\f' (^L) for logical
160  // sectioning by fields, public API, private API, and nested classes.
161
162
163  /**
164   * Compatible with JDK 1.0+.
165   */
166  private static final long serialVersionUID = -7644114512714619750L;
167
168  /**
169   * Constant returned by the <code>getAlignmentY</code> method to indicate
170   * that the component wishes to be aligned to the top relative to
171   * other components.
172   *
173   * @see #getAlignmentY()
174   */
175  public static final float TOP_ALIGNMENT = 0;
176
177  /**
178   * Constant returned by the <code>getAlignmentY</code> and
179   * <code>getAlignmentX</code> methods to indicate
180   * that the component wishes to be aligned to the centdisper relative to
181   * other components.
182   *
183   * @see #getAlignmentX()
184   * @see #getAlignmentY()
185   */
186  public static final float CENTER_ALIGNMENT = 0.5f;
187
188  /**
189   * Constant returned by the <code>getAlignmentY</code> method to indicate
190   * that the component wishes to be aligned to the bottom relative to
191   * other components.
192   *
193   * @see #getAlignmentY()
194   */
195  public static final float BOTTOM_ALIGNMENT = 1;
196
197  /**
198   * Constant returned by the <code>getAlignmentX</code> method to indicate
199   * that the component wishes to be aligned to the right relative to
200   * other components.
201   *
202   * @see #getAlignmentX()
203   */
204  public static final float RIGHT_ALIGNMENT = 1;
205
206  /**
207   * Constant returned by the <code>getAlignmentX</code> method to indicate
208   * that the component wishes to be aligned to the left relative to
209   * other components.
210   *
211   * @see #getAlignmentX()
212   */
213  public static final float LEFT_ALIGNMENT = 0;
214
215  /**
216   * Make the treelock a String so that it can easily be identified
217   * in debug dumps. We clone the String in order to avoid a conflict in
218   * the unlikely event that some other package uses exactly the same string
219   * as a lock object.
220   */
221  static final Object treeLock = new String("AWT_TREE_LOCK");
222
223  /**
224   * The default maximum size.
225   */
226  private static final Dimension DEFAULT_MAX_SIZE 
227                             = new Dimension(Short.MAX_VALUE, Short.MAX_VALUE);
228
229  // Serialized fields from the serialization spec.
230
231  /**
232   * The x position of the component in the parent's coordinate system.
233   *
234   * @see #getLocation()
235   * @serial the x position
236   */
237  int x;
238
239  /**
240   * The y position of the component in the parent's coordinate system.
241   *
242   * @see #getLocation()
243   * @serial the y position
244   */
245  int y;
246
247  /**
248   * The component width.
249   *
250   * @see #getSize()
251   * @serial the width
252   */
253  int width;
254
255  /**
256   * The component height.
257   *
258   * @see #getSize()
259   * @serial the height
260   */
261  int height;
262
263  /**
264   * The foreground color for the component. This may be null.
265   *
266   * @see #getForeground()
267   * @see #setForeground(Color)
268   * @serial the foreground color
269   */
270  Color foreground;
271
272  /**
273   * The background color for the component. This may be null.
274   *
275   * @see #getBackground()
276   * @see #setBackground(Color)
277   * @serial the background color
278   */
279  Color background;
280
281  /**
282   * The default font used in the component. This may be null.
283   *
284   * @see #getFont()
285   * @see #setFont(Font)
286   * @serial the font
287   */
288  Font font;
289
290  /**
291   * The font in use by the peer, or null if there is no peer.
292   *
293   * @serial the peer's font
294   */
295  Font peerFont;
296
297  /**
298   * The cursor displayed when the pointer is over this component. This may
299   * be null.
300   *
301   * @see #getCursor()
302   * @see #setCursor(Cursor)
303   */
304  Cursor cursor;
305
306  /**
307   * The locale for the component.
308   *
309   * @see #getLocale()
310   * @see #setLocale(Locale)
311   */
312  Locale locale = Locale.getDefault ();
313
314  /**
315   * True if the object should ignore repaint events (usually because it is
316   * not showing).
317   *
318   * @see #getIgnoreRepaint()
319   * @see #setIgnoreRepaint(boolean)
320   * @serial true to ignore repaints
321   * @since 1.4
322   */
323  boolean ignoreRepaint;
324
325  /**
326   * True when the object is visible (although it is only showing if all
327   * ancestors are likewise visible). For component, this defaults to true.
328   *
329   * @see #isVisible()
330   * @see #setVisible(boolean)
331   * @serial true if visible
332   */
333  boolean visible = true;
334
335  /**
336   * True if the object is enabled, meaning it can interact with the user.
337   * For component, this defaults to true.
338   *
339   * @see #isEnabled()
340   * @see #setEnabled(boolean)
341   * @serial true if enabled
342   */
343  boolean enabled = true;
344
345  /**
346   * True if the object is valid. This is set to false any time a size
347   * adjustment means the component need to be layed out again.
348   *
349   * @see #isValid()
350   * @see #validate()
351   * @see #invalidate()
352   * @serial true if layout is valid
353   */
354  boolean valid;
355
356  /**
357   * The DropTarget for drag-and-drop operations.
358   *
359   * @see #getDropTarget()
360   * @see #setDropTarget(DropTarget)
361   * @serial the drop target, or null
362   * @since 1.2
363   */
364  DropTarget dropTarget;
365
366  /**
367   * The list of popup menus for this component.
368   *
369   * @see #add(PopupMenu)
370   * @serial the list of popups
371   */
372  Vector popups;
373
374  /**
375   * The component's name. May be null, in which case a default name is
376   * generated on the first use.
377   *
378   * @see #getName()
379   * @see #setName(String)
380   * @serial the name
381   */
382  String name;
383
384  /**
385   * True once the user has set the name. Note that the user may set the name
386   * to null.
387   *
388   * @see #name
389   * @see #getName()
390   * @see #setName(String)
391   * @serial true if the name has been explicitly set
392   */
393  boolean nameExplicitlySet;
394
395  /**
396   * Indicates if the object can be focused. Defaults to true for components.
397   *
398   * @see #isFocusable()
399   * @see #setFocusable(boolean)
400   * @since 1.4
401   */
402  boolean focusable = true;
403
404  /**
405   * Tracks whether this component's {@link #isFocusTraversable}
406   * method has been overridden.
407   *
408   * @since 1.4
409   */
410  int isFocusTraversableOverridden;
411
412  /**
413   * The focus traversal keys, if not inherited from the parent or
414   * default keyboard focus manager. These sets will contain only
415   * AWTKeyStrokes that represent press and release events to use as
416   * focus control.
417   *
418   * @see #getFocusTraversalKeys(int)
419   * @see #setFocusTraversalKeys(int, Set)
420   * @since 1.4
421   */
422  Set[] focusTraversalKeys;
423
424  /**
425   * True if focus traversal keys are enabled. This defaults to true for
426   * Component. If this is true, keystrokes in focusTraversalKeys are trapped
427   * and processed automatically rather than being passed on to the component.
428   *
429   * @see #getFocusTraversalKeysEnabled()
430   * @see #setFocusTraversalKeysEnabled(boolean)
431   * @since 1.4
432   */
433  boolean focusTraversalKeysEnabled = true;
434
435  /**
436   * Cached information on the minimum size. Should have been transient.
437   *
438   * @serial ignore
439   */
440  Dimension minSize;
441
442  /**
443   * Flag indicating whether the minimum size for the component has been set
444   * by a call to {@link #setMinimumSize(Dimension)} with a non-null value.
445   */
446  boolean minSizeSet;
447  
448  /**
449   * The maximum size for the component.
450   * @see #setMaximumSize(Dimension)
451   */
452  Dimension maxSize;
453  
454  /**
455   * A flag indicating whether the maximum size for the component has been set
456   * by a call to {@link #setMaximumSize(Dimension)} with a non-null value.
457   */
458  boolean maxSizeSet;
459  
460  /**
461   * Cached information on the preferred size. Should have been transient.
462   *
463   * @serial ignore
464   */
465  Dimension prefSize;
466
467  /**
468   * Flag indicating whether the preferred size for the component has been set
469   * by a call to {@link #setPreferredSize(Dimension)} with a non-null value.
470   */
471  boolean prefSizeSet;
472
473  /**
474   * Set to true if an event is to be handled by this component, false if
475   * it is to be passed up the hierarcy.
476   *
477   * @see #dispatchEvent(AWTEvent)
478   * @serial true to process event locally
479   */
480  boolean newEventsOnly;
481
482  /**
483   * Set by subclasses to enable event handling of particular events, and
484   * left alone when modifying listeners. For component, this defaults to
485   * enabling only input methods.
486   *
487   * @see #enableInputMethods(boolean)
488   * @see AWTEvent
489   * @serial the mask of events to process
490   */
491  long eventMask = AWTEvent.INPUT_ENABLED_EVENT_MASK;
492
493  /**
494   * Describes all registered PropertyChangeListeners.
495   *
496   * @see #addPropertyChangeListener(PropertyChangeListener)
497   * @see #removePropertyChangeListener(PropertyChangeListener)
498   * @see #firePropertyChange(String, Object, Object)
499   * @serial the property change listeners
500   * @since 1.2
501   */
502  PropertyChangeSupport changeSupport;
503
504  /**
505   * True if the component has been packed (layed out).
506   *
507   * @serial true if this is packed
508   */
509  boolean isPacked;
510
511  /**
512   * The serialization version for this class. Currently at version 4.
513   *
514   * XXX How do we handle prior versions?
515   *
516   * @serial the serialization version
517   */
518  int componentSerializedDataVersion = 4;
519
520  /**
521   * The accessible context associated with this component. This is only set
522   * by subclasses.
523   *
524   * @see #getAccessibleContext()
525   * @serial the accessibility context
526   * @since 1.2
527   */
528  AccessibleContext accessibleContext;
529
530
531  // Guess what - listeners are special cased in serialization. See
532  // readObject and writeObject.
533
534  /** Component listener chain. */
535  transient ComponentListener componentListener;
536
537  /** Focus listener chain. */
538  transient FocusListener focusListener;
539
540  /** Key listener chain. */
541  transient KeyListener keyListener;
542
543  /** Mouse listener chain. */
544  transient MouseListener mouseListener;
545
546  /** Mouse motion listener chain. */
547  transient MouseMotionListener mouseMotionListener;
548
549  /**
550   * Mouse wheel listener chain.
551   *
552   * @since 1.4
553   */
554  transient MouseWheelListener mouseWheelListener;
555
556  /**
557   * Input method listener chain.
558   *
559   * @since 1.2
560   */
561  transient InputMethodListener inputMethodListener;
562
563  /**
564   * Hierarcy listener chain.
565   *
566   * @since 1.3
567   */
568  transient HierarchyListener hierarchyListener;
569
570  /**
571   * Hierarcy bounds listener chain.
572   *
573   * @since 1.3
574   */
575  transient HierarchyBoundsListener hierarchyBoundsListener;
576
577  // Anything else is non-serializable, and should be declared "transient".
578
579  /** The parent. */
580  transient Container parent;
581
582  /** The associated native peer. */
583  transient ComponentPeer peer;
584
585  /** The preferred component orientation. */
586  transient ComponentOrientation componentOrientation = ComponentOrientation.UNKNOWN;
587
588  /**
589   * The associated graphics configuration.
590   *
591   * @since 1.4
592   */
593  transient GraphicsConfiguration graphicsConfig;
594
595  /**
596   * The buffer strategy for repainting.
597   *
598   * @since 1.4
599   */
600  transient BufferStrategy bufferStrategy;
601
602  /**
603   * The number of hierarchy listeners of this container plus all of its
604   * children. This is needed for efficient handling of HierarchyEvents.
605   * These must be propagated to all child components with HierarchyListeners
606   * attached. To avoid traversal of the whole subtree, we keep track of
607   * the number of HierarchyListeners here and only walk the paths that
608   * actually have listeners.
609   */
610  int numHierarchyListeners;
611  int numHierarchyBoundsListeners;
612
613  /**
614   * true if requestFocus was called on this component when its
615   * top-level ancestor was not focusable.
616   */
617  private transient FocusEvent pendingFocusRequest = null;
618
619  /**
620   * The system properties that affect image updating.
621   */
622  private static transient boolean incrementalDraw;
623  private static transient Long redrawRate;
624
625  static
626  {
627    incrementalDraw = Boolean.getBoolean ("awt.image.incrementalDraw");
628    redrawRate = Long.getLong ("awt.image.redrawrate");
629  }
630
631  // Public and protected API.
632
633  /**
634   * Default constructor for subclasses. When Component is extended directly,
635   * it forms a lightweight component that must be hosted in an opaque native
636   * container higher in the tree.
637   */
638  protected Component()
639  {
640    // Nothing to do here.
641  }
642
643  /**
644   * Returns the name of this component.
645   *
646   * @return the name of this component
647   * @see #setName(String)
648   * @since 1.1
649   */
650  public String getName()
651  {
652    if (name == null && ! nameExplicitlySet)
653      name = generateName();
654    return name;
655  }
656
657  /**
658   * Sets the name of this component to the specified name (this is a bound
659   * property with the name 'name').
660   *
661   * @param name the new name (<code>null</code> permitted).
662   * @see #getName()
663   * @since 1.1
664   */
665  public void setName(String name)
666  {
667    nameExplicitlySet = true;
668    String old = this.name;
669    this.name = name;
670    firePropertyChange("name", old, name);
671  }
672
673  /**
674   * Returns the parent of this component.
675   *
676   * @return the parent of this component
677   */
678  public Container getParent()
679  {
680    return parent;
681  }
682
683  /**
684   * Returns the native windowing system peer for this component. Only the
685   * platform specific implementation code should call this method.
686   *
687   * @return the peer for this component
688   * @deprecated user programs should not directly manipulate peers; use
689   *             {@link #isDisplayable()} instead
690   */
691  // Classpath's Gtk peers rely on this.
692  public ComponentPeer getPeer()
693  {
694    return peer;
695  }
696
697  /**
698   * Set the associated drag-and-drop target, which receives events when this
699   * is enabled.
700   *
701   * @param dt the new drop target
702   * @see #isEnabled()
703   */
704  public void setDropTarget(DropTarget dt)
705  {
706    this.dropTarget = dt;
707    
708    if (peer != null)
709      dropTarget.addNotify(peer);
710  }
711
712  /**
713   * Gets the associated drag-and-drop target, if there is one.
714   *
715   * @return the drop target
716   */
717  public DropTarget getDropTarget()
718  {
719    return dropTarget;
720  }
721
722  /**
723   * Returns the graphics configuration of this component, if there is one.
724   * If it has not been set, it is inherited from the parent.
725   *
726   * @return the graphics configuration, or null
727   * @since 1.3
728   */
729  public GraphicsConfiguration getGraphicsConfiguration()
730  {
731    GraphicsConfiguration conf = null;
732    synchronized (getTreeLock())
733      {
734        if (graphicsConfig != null)
735          {
736            conf = graphicsConfig;
737          }
738        else
739          {
740            Component par = getParent();
741            if (par != null)
742              {
743                conf = parent.getGraphicsConfiguration();
744              }
745          }
746      }
747    return conf;
748  }
749
750  /**
751   * Returns the object used for synchronization locks on this component
752   * when performing tree and layout functions.
753   *
754   * @return the synchronization lock for this component
755   */
756  public final Object getTreeLock()
757  {
758    return treeLock;
759  }
760
761  /**
762   * Returns the toolkit in use for this component. The toolkit is associated
763   * with the frame this component belongs to.
764   *
765   * @return the toolkit for this component
766   */
767  public Toolkit getToolkit()
768  {
769    // Only heavyweight peers can handle this.
770    ComponentPeer p = peer;
771    Component comp = this;
772    while (p instanceof LightweightPeer)
773      {
774        comp = comp.parent;
775        p = comp == null ? null : comp.peer;
776      }
777
778    Toolkit tk = null;
779    if (p != null)
780      {
781        tk = peer.getToolkit();
782      }
783    if (tk == null)
784      tk = Toolkit.getDefaultToolkit();
785    return tk;
786  }
787
788  /**
789   * Tests whether or not this component is valid. A invalid component needs
790   * to have its layout redone.
791   *
792   * @return true if this component is valid
793   * @see #validate()
794   * @see #invalidate()
795   */
796  public boolean isValid()
797  {
798    // Tests show that components are invalid as long as they are not showing, even after validate()
799    // has been called on them.
800    return peer != null && valid;
801  }
802
803  /**
804   * Tests if the component is displayable. It must be connected to a native
805   * screen resource.  This reduces to checking that peer is not null.  A 
806   * containment  hierarchy is made displayable when a window is packed or 
807   * made visible.
808   *
809   * @return true if the component is displayable
810   * @see Container#add(Component)
811   * @see Container#remove(Component)
812   * @see Window#pack()
813   * @see Window#show()
814   * @see Window#dispose()
815   * @since 1.2
816   */
817  public boolean isDisplayable()
818  {
819    return peer != null;
820  }
821
822  /**
823   * Tests whether or not this component is visible. Except for top-level
824   * frames, components are initially visible.
825   *
826   * @return true if the component is visible
827   * @see #setVisible(boolean)
828   */
829  public boolean isVisible()
830  {
831    return visible;
832  }
833
834  /**
835   * Tests whether or not this component is actually being shown on
836   * the screen. This will be true if and only if it this component is
837   * visible and its parent components are all visible.
838   *
839   * @return true if the component is showing on the screen
840   * @see #setVisible(boolean)
841   */
842  public boolean isShowing()
843  {
844    Component par = parent;
845    return visible && peer != null && (par == null || par.isShowing());
846  }
847
848  /**
849   * Tests whether or not this component is enabled. Components are enabled
850   * by default, and must be enabled to receive user input or generate events.
851   *
852   * @return true if the component is enabled
853   * @see #setEnabled(boolean)
854   */
855  public boolean isEnabled()
856  {
857    return enabled;
858  }
859
860  /**
861   * Enables or disables this component. The component must be enabled to
862   * receive events (except that lightweight components always receive mouse
863   * events).
864   *
865   * @param enabled true to enable this component
866   * 
867   * @see #isEnabled()
868   * @see #isLightweight()
869   * 
870   * @since 1.1
871   */
872  public void setEnabled(boolean enabled)
873  {
874    enable(enabled);
875  }
876
877  /**
878   * Enables this component.
879   *
880   * @deprecated use {@link #setEnabled(boolean)} instead
881   */
882  public void enable()
883  {
884    if (! enabled)
885      {
886        // Need to lock the tree here, because the peers are involved.
887        synchronized (getTreeLock())
888          {
889            enabled = true;
890            ComponentPeer p = peer;
891            if (p != null)
892              p.enable();
893          }
894      }
895  }
896
897  /**
898   * Enables or disables this component.
899   *
900   * @param enabled true to enable this component
901   * 
902   * @deprecated use {@link #setEnabled(boolean)} instead
903   */
904  public void enable(boolean enabled)
905  {
906    if (enabled)
907      enable();
908    else
909      disable();
910  }
911
912  /**
913   * Disables this component.
914   *
915   * @deprecated use {@link #setEnabled(boolean)} instead
916   */
917  public void disable()
918  {
919    if (enabled)
920      {
921        // Need to lock the tree here, because the peers are involved.
922        synchronized (getTreeLock())
923          {
924            enabled = false;
925            ComponentPeer p = peer;
926            if (p != null)
927              p.disable();
928          }
929      }
930  }
931
932  /**
933   * Checks if this image is painted to an offscreen image buffer that is
934   * later copied to screen (double buffering reduces flicker). This version
935   * returns false, so subclasses must override it if they provide double
936   * buffering.
937   *
938   * @return true if this is double buffered; defaults to false
939   */
940  public boolean isDoubleBuffered()
941  {
942    return false;
943  }
944
945  /**
946   * Enables or disables input method support for this component. By default,
947   * components have this enabled. Input methods are given the opportunity
948   * to process key events before this component and its listeners.
949   *
950   * @param enable true to enable input method processing
951   * @see #processKeyEvent(KeyEvent)
952   * @since 1.2
953   */
954  public void enableInputMethods(boolean enable)
955  {
956    if (enable)
957      eventMask |= AWTEvent.INPUT_ENABLED_EVENT_MASK;
958    else
959      eventMask &= ~AWTEvent.INPUT_ENABLED_EVENT_MASK;
960  }
961
962  /**
963   * Makes this component visible or invisible. Note that it wtill might
964   * not show the component, if a parent is invisible.
965   *
966   * @param visible true to make this component visible
967   * 
968   * @see #isVisible()
969   * 
970   * @since 1.1
971   */
972  public void setVisible(boolean visible)
973  {
974    // Inspection by subclassing shows that Sun's implementation calls
975    // show(boolean) which then calls show() or hide(). It is the show()
976    // method that is overriden in subclasses like Window.
977    show(visible);
978  }
979
980  /**
981   * Makes this component visible on the screen.
982   *
983   * @deprecated use {@link #setVisible(boolean)} instead
984   */
985  public void show()
986  {
987    // We must set visible before showing the peer.  Otherwise the
988    // peer could post paint events before visible is true, in which
989    // case lightweight components are not initially painted --
990    // Container.paint first calls isShowing () before painting itself
991    // and its children.
992    if(! visible)
993      {
994        // Need to lock the tree here to avoid races and inconsistencies.
995        synchronized (getTreeLock())
996          {
997            visible = true;
998            // Avoid NullPointerExceptions by creating a local reference.
999            ComponentPeer currentPeer = peer;
1000            if (currentPeer != null)
1001              {
1002                currentPeer.show();
1003
1004                // Fire HierarchyEvent.
1005                fireHierarchyEvent(HierarchyEvent.HIERARCHY_CHANGED,
1006                                   this, parent,
1007                                   HierarchyEvent.SHOWING_CHANGED);
1008
1009                // The JDK repaints the component before invalidating the parent.
1010                // So do we.
1011                if (peer instanceof LightweightPeer)
1012                  repaint();
1013              }
1014
1015            // Only post an event if this component actually has a listener
1016            // or has this event explicitly enabled.
1017            if (componentListener != null
1018                || (eventMask & AWTEvent.COMPONENT_EVENT_MASK) != 0)
1019              {
1020                ComponentEvent ce =
1021                  new ComponentEvent(this,ComponentEvent.COMPONENT_SHOWN);
1022                getToolkit().getSystemEventQueue().postEvent(ce);
1023              }
1024          }
1025
1026        // Invalidate the parent if we have one. The component itself must
1027        // not be invalidated. We also avoid NullPointerException with
1028        // a local reference here.
1029        Container currentParent = parent;
1030        if (currentParent != null)
1031          currentParent.invalidate();
1032
1033      }
1034  }
1035
1036  /**
1037   * Makes this component visible or invisible.
1038   *
1039   * @param visible true to make this component visible
1040   * 
1041   * @deprecated use {@link #setVisible(boolean)} instead
1042   */
1043  public void show(boolean visible)
1044  {
1045    if (visible)
1046      show();
1047    else
1048      hide();
1049  }
1050
1051  /**
1052   * Hides this component so that it is no longer shown on the screen.
1053   *
1054   * @deprecated use {@link #setVisible(boolean)} instead
1055   */
1056  public void hide()
1057  {
1058    if (visible)
1059      {
1060        // Need to lock the tree here to avoid races and inconsistencies.
1061        synchronized (getTreeLock())
1062          {
1063            visible = false;
1064
1065            // Avoid NullPointerExceptions by creating a local reference.
1066            ComponentPeer currentPeer = peer;
1067            if (currentPeer != null)
1068              {
1069                currentPeer.hide();
1070
1071                // Fire hierarchy event.
1072                fireHierarchyEvent(HierarchyEvent.HIERARCHY_CHANGED,
1073                                   this, parent,
1074                                   HierarchyEvent.SHOWING_CHANGED);
1075                // The JDK repaints the component before invalidating the
1076                // parent. So do we. This only applies for lightweights.
1077                if (peer instanceof LightweightPeer)
1078                  repaint();
1079              }
1080
1081            // Only post an event if this component actually has a listener
1082            // or has this event explicitly enabled.
1083            if (componentListener != null
1084                || (eventMask & AWTEvent.COMPONENT_EVENT_MASK) != 0)
1085              {
1086                ComponentEvent ce =
1087                  new ComponentEvent(this,ComponentEvent.COMPONENT_HIDDEN);
1088                getToolkit().getSystemEventQueue().postEvent(ce);
1089              }
1090          }
1091
1092        // Invalidate the parent if we have one. The component itself need
1093        // not be invalidated. We also avoid NullPointerException with
1094        // a local reference here.
1095        Container currentParent = parent;
1096        if (currentParent != null)
1097          currentParent.invalidate();
1098
1099      }
1100  }
1101
1102  /**
1103   * Returns this component's foreground color. If not set, this is inherited
1104   * from the parent.
1105   *
1106   * @return this component's foreground color, or null
1107   * @see #setForeground(Color)
1108   */
1109  public Color getForeground()
1110  {
1111    if (foreground != null)
1112      return foreground;
1113    return parent == null ? null : parent.getForeground();
1114  }
1115
1116  /**
1117   * Sets this component's foreground color to the specified color. This is a
1118   * bound property.
1119   *
1120   * @param c the new foreground color
1121   * @see #getForeground()
1122   */
1123  public void setForeground(Color c)
1124  {
1125    if (peer != null)
1126      peer.setForeground(c);
1127    
1128    Color previous = foreground;
1129    foreground = c;
1130    firePropertyChange("foreground", previous, c);
1131  }
1132
1133  /**
1134   * Tests if the foreground was explicitly set, or just inherited from the
1135   * parent.
1136   *
1137   * @return true if the foreground has been set
1138   * @since 1.4
1139   */
1140  public boolean isForegroundSet()
1141  {
1142    return foreground != null;
1143  }
1144
1145  /**
1146   * Returns this component's background color. If not set, this is inherited
1147   * from the parent.
1148   *
1149   * @return the background color of the component, or null
1150   * @see #setBackground(Color)
1151   */
1152  public Color getBackground()
1153  {
1154    if (background != null)
1155      return background;
1156    return parent == null ? null : parent.getBackground();
1157  }
1158
1159  /**
1160   * Sets this component's background color to the specified color. The parts
1161   * of the component affected by the background color may by system dependent.
1162   * This is a bound property.
1163   *
1164   * @param c the new background color
1165   * @see #getBackground()
1166   */
1167  public void setBackground(Color c)
1168  {
1169    // return if the background is already set to that color.
1170    if ((c != null) && c.equals(background))
1171      return;
1172
1173    Color previous = background;
1174    background = c;
1175    if (peer != null && c != null)
1176      peer.setBackground(c);
1177    firePropertyChange("background", previous, c);
1178  }
1179
1180  /**
1181   * Tests if the background was explicitly set, or just inherited from the
1182   * parent.
1183   *
1184   * @return true if the background has been set
1185   * @since 1.4
1186   */
1187  public boolean isBackgroundSet()
1188  {
1189    return background != null;
1190  }
1191
1192  /**
1193   * Returns the font in use for this component. If not set, this is inherited
1194   * from the parent.
1195   *
1196   * @return the font for this component
1197   * @see #setFont(Font)
1198   */
1199  public Font getFont()
1200  {
1201    return getFontImpl();
1202  }
1203
1204  /**
1205   * Implementation of getFont(). This is pulled out of getFont() to prevent
1206   * client programs from overriding this.
1207   *
1208   * @return the font of this component
1209   */
1210  private final Font getFontImpl()
1211  {
1212    Font f = font;
1213    if (f == null)
1214      {
1215        Component p = parent;
1216        if (p != null)
1217          f = p.getFontImpl();
1218        else
1219          {
1220            // It is important to return null here and not some kind of default
1221            // font, otherwise the Swing UI would not install its fonts because
1222            // it keeps non-UIResource fonts.
1223            f = null;
1224          }
1225      }
1226    return f;
1227  }
1228
1229  /**
1230   * Sets the font for this component to the specified font. This is a bound
1231   * property.
1232   *
1233   * @param f the new font for this component
1234   * 
1235   * @see #getFont()
1236   */
1237  public void setFont(Font f)
1238  {
1239    Font oldFont;
1240    Font newFont;
1241    // Synchronize on the tree because getFontImpl() relies on the hierarchy
1242    // not beeing changed.
1243    synchronized (getTreeLock())
1244      {
1245        // Synchronize on this here to guarantee thread safety wrt to the
1246        // property values.
1247        synchronized (this)
1248          {
1249            oldFont = font;
1250            font = f;
1251            newFont = f;
1252          }
1253        // Create local variable here for thread safety.
1254        ComponentPeer p = peer;
1255        if (p != null)
1256          {
1257            // The peer receives the real font setting, which can depend on 
1258            // the parent font when this component's font has been set to null.
1259            f = getFont();
1260            if (f != null)
1261              {
1262                p.setFont(f);
1263                peerFont = f;
1264              }
1265          }
1266      }
1267
1268    // Fire property change event.
1269    firePropertyChange("font", oldFont, newFont);
1270
1271    // Invalidate when necessary as font changes can change the size of the
1272    // component.
1273    if (valid)
1274      invalidate();
1275  }
1276
1277  /**
1278   * Tests if the font was explicitly set, or just inherited from the parent.
1279   *
1280   * @return true if the font has been set
1281   * @since 1.4
1282   */
1283  public boolean isFontSet()
1284  {
1285    return font != null;
1286  }
1287
1288  /**
1289   * Returns the locale for this component. If this component does not
1290   * have a locale, the locale of the parent component is returned.
1291   *
1292   * @return the locale for this component
1293   * @throws IllegalComponentStateException if it has no locale or parent
1294   * @see #setLocale(Locale)
1295   * @since 1.1
1296   */
1297  public Locale getLocale()
1298  {
1299    if (locale != null)
1300      return locale;
1301    if (parent == null)
1302      throw new IllegalComponentStateException
1303        ("Component has no parent: can't determine Locale");
1304    return parent.getLocale();
1305  }
1306
1307  /**
1308   * Sets the locale for this component to the specified locale. This is a
1309   * bound property.
1310   *
1311   * @param newLocale the new locale for this component
1312   */
1313  public void setLocale(Locale newLocale)
1314  {
1315    if (locale == newLocale)
1316      return;
1317
1318    Locale oldLocale = locale;
1319    locale = newLocale;
1320    firePropertyChange("locale", oldLocale, newLocale);
1321    // New writing/layout direction or more/less room for localized labels.
1322    invalidate();
1323  }
1324
1325  /**
1326   * Returns the color model of the device this componet is displayed on.
1327   *
1328   * @return this object's color model
1329   * @see Toolkit#getColorModel()
1330   */
1331  public ColorModel getColorModel()
1332  {
1333    GraphicsConfiguration config = getGraphicsConfiguration();
1334    return config != null ? config.getColorModel()
1335      : getToolkit().getColorModel();
1336  }
1337
1338  /**
1339   * Returns the location of this component's top left corner relative to
1340   * its parent component. This may be outdated, so for synchronous behavior,
1341   * you should use a component listner.
1342   *
1343   * @return the location of this component
1344   * @see #setLocation(int, int)
1345   * @see #getLocationOnScreen()
1346   * @since 1.1
1347   */
1348  public Point getLocation()
1349  {
1350    return location ();
1351  }
1352
1353  /**
1354   * Returns the location of this component's top left corner in screen
1355   * coordinates.
1356   *
1357   * @return the location of this component in screen coordinates
1358   * @throws IllegalComponentStateException if the component is not showing
1359   */
1360  public Point getLocationOnScreen()
1361  {
1362    if (! isShowing())
1363      throw new IllegalComponentStateException("component "
1364                                               + getClass().getName()
1365                                               + " not showing");
1366
1367    // Need to lock the tree here. We get crazy races and explosions when
1368    // the tree changes while we are trying to find the location of this
1369    // component.
1370    synchronized (getTreeLock())
1371      {
1372        // Only a heavyweight peer can answer the question for the screen
1373        // location. So we are going through the hierarchy until we find
1374        // one and add up the offsets while doing so.
1375        int offsX = 0;
1376        int offsY = 0;
1377        ComponentPeer p = peer;
1378        Component comp = this;
1379        while (p instanceof LightweightPeer)
1380          {
1381            offsX += comp.x;
1382            offsY += comp.y;
1383            comp = comp.parent;
1384            p = comp == null ? null: comp.peer;
1385          }
1386        // Now we have a heavyweight component.
1387        assert ! (p instanceof LightweightPeer);
1388        Point loc = p.getLocationOnScreen();
1389        loc.x += offsX;
1390        loc.y += offsY;
1391        return loc;
1392      }
1393  }
1394
1395  /**
1396   * Returns the location of this component's top left corner relative to
1397   * its parent component.
1398   *
1399   * @return the location of this component
1400   * @deprecated use {@link #getLocation()} instead
1401   */
1402  public Point location()
1403  {
1404    return new Point (x, y);
1405  }
1406
1407  /**
1408   * Moves this component to the specified location, relative to the parent's
1409   * coordinates. The coordinates are the new upper left corner of this
1410   * component.
1411   *
1412   * @param x the new X coordinate of this component
1413   * @param y the new Y coordinate of this component
1414   * @see #getLocation()
1415   * @see #setBounds(int, int, int, int)
1416   */
1417  public void setLocation(int x, int y)
1418  {
1419    move (x, y);
1420  }
1421
1422  /**
1423   * Moves this component to the specified location, relative to the parent's
1424   * coordinates. The coordinates are the new upper left corner of this
1425   * component.
1426   *
1427   * @param x the new X coordinate of this component
1428   * @param y the new Y coordinate of this component
1429   * @deprecated use {@link #setLocation(int, int)} instead
1430   */
1431  public void move(int x, int y)
1432  {
1433    setBounds(x, y, this.width, this.height);
1434  }
1435
1436  /**
1437   * Moves this component to the specified location, relative to the parent's
1438   * coordinates. The coordinates are the new upper left corner of this
1439   * component.
1440   *
1441   * @param p new coordinates for this component
1442   * @throws NullPointerException if p is null
1443   * @see #getLocation()
1444   * @see #setBounds(int, int, int, int)
1445   * @since 1.1
1446   */
1447  public void setLocation(Point p)
1448  {
1449    setLocation(p.x, p.y);
1450  }
1451
1452  /**
1453   * Returns the size of this object.
1454   *
1455   * @return the size of this object
1456   * @see #setSize(int, int)
1457   * @since 1.1
1458   */
1459  public Dimension getSize()
1460  {
1461    return size ();
1462  }
1463
1464  /**
1465   * Returns the size of this object.
1466   *
1467   * @return the size of this object
1468   * @deprecated use {@link #getSize()} instead
1469   */
1470  public Dimension size()
1471  {
1472    return new Dimension (width, height);
1473  }
1474
1475  /**
1476   * Sets the size of this component to the specified width and height.
1477   *
1478   * @param width the new width of this component
1479   * @param height the new height of this component
1480   * @see #getSize()
1481   * @see #setBounds(int, int, int, int)
1482   */
1483  public void setSize(int width, int height)
1484  {
1485    resize (width, height);
1486  }
1487
1488  /**
1489   * Sets the size of this component to the specified value.
1490   *
1491   * @param width the new width of the component
1492   * @param height the new height of the component
1493   * @deprecated use {@link #setSize(int, int)} instead
1494   */
1495  public void resize(int width, int height)
1496  {
1497    setBounds(this.x, this.y, width, height);
1498  }
1499
1500  /**
1501   * Sets the size of this component to the specified value.
1502   *
1503   * @param d the new size of this component
1504   * @throws NullPointerException if d is null
1505   * @see #setSize(int, int)
1506   * @see #setBounds(int, int, int, int)
1507   * @since 1.1
1508   */
1509  public void setSize(Dimension d)
1510  {
1511    resize (d);
1512  }
1513
1514  /**
1515   * Sets the size of this component to the specified value.
1516   *
1517   * @param d the new size of this component
1518   * @throws NullPointerException if d is null
1519   * @deprecated use {@link #setSize(Dimension)} instead
1520   */
1521  public void resize(Dimension d)
1522  {
1523    resize (d.width, d.height);
1524  }
1525
1526  /**
1527   * Returns a bounding rectangle for this component. Note that the
1528   * returned rectange is relative to this component's parent, not to
1529   * the screen.
1530   *
1531   * @return the bounding rectangle for this component
1532   * @see #setBounds(int, int, int, int)
1533   * @see #getLocation()
1534   * @see #getSize()
1535   */
1536  public Rectangle getBounds()
1537  {
1538    return bounds ();
1539  }
1540
1541  /**
1542   * Returns a bounding rectangle for this component. Note that the
1543   * returned rectange is relative to this component's parent, not to
1544   * the screen.
1545   *
1546   * @return the bounding rectangle for this component
1547   * @deprecated use {@link #getBounds()} instead
1548   */
1549  public Rectangle bounds()
1550  {
1551    return new Rectangle (x, y, width, height);
1552  }
1553
1554  /**
1555   * Sets the bounding rectangle for this component to the specified values.
1556   * Note that these coordinates are relative to the parent, not to the screen.
1557   *
1558   * @param x the X coordinate of the upper left corner of the rectangle
1559   * @param y the Y coordinate of the upper left corner of the rectangle
1560   * @param w the width of the rectangle
1561   * @param h the height of the rectangle
1562   * @see #getBounds()
1563   * @see #setLocation(int, int)
1564   * @see #setLocation(Point)
1565   * @see #setSize(int, int)
1566   * @see #setSize(Dimension)
1567   * @since 1.1
1568   */
1569  public void setBounds(int x, int y, int w, int h)
1570  {
1571    reshape (x, y, w, h);
1572  }
1573
1574  /**
1575   * Sets the bounding rectangle for this component to the specified values.
1576   * Note that these coordinates are relative to the parent, not to the screen.
1577   *
1578   * @param x the X coordinate of the upper left corner of the rectangle
1579   * @param y the Y coordinate of the upper left corner of the rectangle
1580   * @param width the width of the rectangle
1581   * @param height the height of the rectangle
1582   * @deprecated use {@link #setBounds(int, int, int, int)} instead
1583   */
1584  public void reshape(int x, int y, int width, int height)
1585  {
1586    // We need to lock the tree here, otherwise we risk races and
1587    // inconsistencies.
1588    synchronized (getTreeLock())
1589      {
1590        int oldx = this.x;
1591        int oldy = this.y;
1592        int oldwidth = this.width;
1593        int oldheight = this.height;
1594    
1595        boolean resized = oldwidth != width || oldheight != height;
1596        boolean moved = oldx != x || oldy != y;
1597
1598        if (resized || moved)
1599          {
1600            // Update the fields.
1601            this.x = x;
1602            this.y = y;
1603            this.width = width;
1604            this.height = height;
1605
1606            if (peer != null)
1607              {
1608                peer.setBounds (x, y, width, height);
1609                if (resized)
1610                  invalidate();
1611                if (parent != null && parent.valid)
1612                  parent.invalidate();
1613              }
1614
1615            // Send some events to interested listeners.
1616            notifyReshape(resized, moved);
1617
1618            // Repaint this component and the parent if appropriate.
1619            if (parent != null && peer instanceof LightweightPeer
1620                && isShowing())
1621              {
1622                // The parent repaints the area that we occupied before.
1623                parent.repaint(oldx, oldy, oldwidth, oldheight);
1624                // This component repaints the area that we occupy now.
1625                repaint();
1626              }
1627          }
1628      }
1629  }
1630
1631  /**
1632   * Sends notification to interested listeners about resizing and/or moving
1633   * the component. If this component has interested
1634   * component listeners or the corresponding event mask enabled, then
1635   * COMPONENT_MOVED and/or COMPONENT_RESIZED events are posted to the event
1636   * queue.
1637   *
1638   * @param resized true if the component has been resized, false otherwise
1639   * @param moved true if the component has been moved, false otherwise
1640   */
1641  void notifyReshape(boolean resized, boolean moved)
1642  {
1643    // Only post an event if this component actually has a listener
1644    // or has this event explicitly enabled.
1645    if (componentListener != null
1646        || (eventMask & AWTEvent.COMPONENT_EVENT_MASK) != 0)
1647      {
1648        // Fire component event on this component.
1649        if (moved)
1650          {
1651            ComponentEvent ce = new ComponentEvent(this,
1652                                               ComponentEvent.COMPONENT_MOVED);
1653            getToolkit().getSystemEventQueue().postEvent(ce);
1654          }
1655        if (resized)
1656          {
1657            ComponentEvent ce = new ComponentEvent(this,
1658                                             ComponentEvent.COMPONENT_RESIZED);
1659            getToolkit().getSystemEventQueue().postEvent(ce);
1660          }
1661      }
1662  }
1663
1664  /**
1665   * Sets the bounding rectangle for this component to the specified
1666   * rectangle. Note that these coordinates are relative to the parent, not
1667   * to the screen.
1668   *
1669   * @param r the new bounding rectangle
1670   * @throws NullPointerException if r is null
1671   * @see #getBounds()
1672   * @see #setLocation(Point)
1673   * @see #setSize(Dimension)
1674   * @since 1.1
1675   */
1676  public void setBounds(Rectangle r)
1677  {
1678    setBounds (r.x, r.y, r.width, r.height);
1679  }
1680
1681  /**
1682   * Gets the x coordinate of the upper left corner. This is more efficient
1683   * than getBounds().x or getLocation().x.
1684   *
1685   * @return the current x coordinate
1686   * @since 1.2
1687   */
1688  public int getX()
1689  {
1690    return x;
1691  }
1692
1693  /**
1694   * Gets the y coordinate of the upper left corner. This is more efficient
1695   * than getBounds().y or getLocation().y.
1696   *
1697   * @return the current y coordinate
1698   * @since 1.2
1699   */
1700  public int getY()
1701  {
1702    return y;
1703  }
1704
1705  /**
1706   * Gets the width of the component. This is more efficient than
1707   * getBounds().width or getSize().width.
1708   *
1709   * @return the current width
1710   * @since 1.2
1711   */
1712  public int getWidth()
1713  {
1714    return width;
1715  }
1716
1717  /**
1718   * Gets the height of the component. This is more efficient than
1719   * getBounds().height or getSize().height.
1720   *
1721   * @return the current width
1722   * @since 1.2
1723   */
1724  public int getHeight()
1725  {
1726    return height;
1727  }
1728
1729  /**
1730   * Returns the bounds of this component. This allows reuse of an existing
1731   * rectangle, if r is non-null.
1732   *
1733   * @param r the rectangle to use, or null
1734   * @return the bounds
1735   */
1736  public Rectangle getBounds(Rectangle r)
1737  {
1738    if (r == null)
1739      r = new Rectangle();
1740    r.x = x;
1741    r.y = y;
1742    r.width = width;
1743    r.height = height;
1744    return r;
1745  }
1746
1747  /**
1748   * Returns the size of this component. This allows reuse of an existing
1749   * dimension, if d is non-null.
1750   *
1751   * @param d the dimension to use, or null
1752   * @return the size
1753   */
1754  public Dimension getSize(Dimension d)
1755  {
1756    if (d == null)
1757      d = new Dimension();
1758    d.width = width;
1759    d.height = height;
1760    return d;
1761  }
1762
1763  /**
1764   * Returns the location of this component. This allows reuse of an existing
1765   * point, if p is non-null.
1766   *
1767   * @param p the point to use, or null
1768   * @return the location
1769   */
1770  public Point getLocation(Point p)
1771  {
1772    if (p == null)
1773      p = new Point();
1774    p.x = x;
1775    p.y = y;
1776    return p;
1777  }
1778
1779  /**
1780   * Tests if this component is opaque. All "heavyweight" (natively-drawn)
1781   * components are opaque. A component is opaque if it draws all pixels in
1782   * the bounds; a lightweight component is partially transparent if it lets
1783   * pixels underneath show through. Subclasses that guarantee that all pixels
1784   * will be drawn should override this.
1785   *
1786   * @return true if this is opaque
1787   * @see #isLightweight()
1788   * @since 1.2
1789   */
1790  public boolean isOpaque()
1791  {
1792    return ! isLightweight();
1793  }
1794
1795  /**
1796   * Return whether the component is lightweight. That means the component has
1797   * no native peer, but is displayable. This applies to subclasses of
1798   * Component not in this package, such as javax.swing.
1799   *
1800   * @return true if the component has a lightweight peer
1801   * @see #isDisplayable()
1802   * @since 1.2
1803   */
1804  public boolean isLightweight()
1805  {
1806    return peer instanceof LightweightPeer;
1807  }
1808
1809  /**
1810   * Returns the component's preferred size.
1811   *
1812   * @return the component's preferred size
1813   * @see #getMinimumSize()
1814   * @see #setPreferredSize(Dimension)
1815   * @see LayoutManager
1816   */
1817  public Dimension getPreferredSize()
1818  {
1819    return preferredSize();
1820  }
1821
1822  /**
1823   * Sets the preferred size that will be returned by 
1824   * {@link #getPreferredSize()} always, and sends a 
1825   * {@link PropertyChangeEvent} (with the property name 'preferredSize') to 
1826   * all registered listeners.
1827   * 
1828   * @param size  the preferred size (<code>null</code> permitted).
1829   * 
1830   * @since 1.5
1831   * 
1832   * @see #getPreferredSize()
1833   */
1834  public void setPreferredSize(Dimension size)
1835  {
1836    Dimension old = prefSizeSet ? prefSize : null;
1837    prefSize = size;
1838    prefSizeSet = (size != null);
1839    firePropertyChange("preferredSize", old, size);
1840  }
1841  
1842  /**
1843   * Returns <code>true</code> if the current preferred size is not 
1844   * <code>null</code> and was set by a call to 
1845   * {@link #setPreferredSize(Dimension)}, otherwise returns <code>false</code>.
1846   * 
1847   * @return A boolean.
1848   * 
1849   * @since 1.5
1850   */
1851  public boolean isPreferredSizeSet()
1852  {
1853    return prefSizeSet;
1854  }
1855  
1856  /**
1857   * Returns the component's preferred size.
1858   *
1859   * @return the component's preferred size
1860   * @deprecated use {@link #getPreferredSize()} instead
1861   */
1862  public Dimension preferredSize()
1863  {
1864    // Create a new Dimension object, so that the application doesn't mess
1865    // with the actual values.
1866    return new Dimension(preferredSizeImpl());
1867  }
1868
1869  /**
1870   * The actual calculation is pulled out of preferredSize() so that
1871   * we can call it from Container.preferredSize() and avoid creating a
1872   * new intermediate Dimension object.
1873   * 
1874   * @return the preferredSize of the component
1875   */
1876  Dimension preferredSizeImpl()
1877  {
1878    Dimension size = prefSize;
1879    // Try to use a cached value.
1880    if (size == null || !(valid || prefSizeSet))
1881      {
1882        // We need to lock here, because the calculation depends on the
1883        // component structure not changing.
1884        synchronized (getTreeLock())
1885          {
1886            ComponentPeer p = peer;
1887            if (p != null)
1888              size = peer.preferredSize();
1889            else
1890              size = minimumSizeImpl();
1891          }
1892      }
1893    return size;
1894  }
1895
1896  /**
1897   * Returns the component's minimum size.
1898   * 
1899   * @return the component's minimum size
1900   * @see #getPreferredSize()
1901   * @see #setMinimumSize(Dimension)
1902   * @see LayoutManager
1903   */
1904  public Dimension getMinimumSize()
1905  {
1906    return minimumSize();
1907  }
1908
1909  /**
1910   * Sets the minimum size that will be returned by {@link #getMinimumSize()}
1911   * always, and sends a {@link PropertyChangeEvent} (with the property name
1912   * 'minimumSize') to all registered listeners.
1913   * 
1914   * @param size  the minimum size (<code>null</code> permitted).
1915   * 
1916   * @since 1.5
1917   * 
1918   * @see #getMinimumSize()
1919   */
1920  public void setMinimumSize(Dimension size)
1921  {
1922    Dimension old = minSizeSet ? minSize : null;
1923    minSize = size;
1924    minSizeSet = (size != null);
1925    firePropertyChange("minimumSize", old, size);
1926  }
1927  
1928  /**
1929   * Returns <code>true</code> if the current minimum size is not 
1930   * <code>null</code> and was set by a call to 
1931   * {@link #setMinimumSize(Dimension)}, otherwise returns <code>false</code>.
1932   * 
1933   * @return A boolean.
1934   * 
1935   * @since 1.5
1936   */
1937  public boolean isMinimumSizeSet()
1938  {
1939    return minSizeSet;
1940  }
1941  
1942  /**
1943   * Returns the component's minimum size.
1944   *
1945   * @return the component's minimum size
1946   * @deprecated use {@link #getMinimumSize()} instead
1947   */
1948  public Dimension minimumSize()
1949  {
1950    // Create a new Dimension object, so that the application doesn't mess
1951    // with the actual values.
1952    return new Dimension(minimumSizeImpl());
1953  }
1954
1955  /**
1956   * The actual calculation is pulled out of minimumSize() so that
1957   * we can call it from Container.preferredSize() and
1958   * Component.preferredSizeImpl and avoid creating a
1959   * new intermediate Dimension object.
1960   * 
1961   * @return the minimum size of the component
1962   */
1963  Dimension minimumSizeImpl()
1964  {
1965    Dimension size = minSize;
1966    if (size == null || !(valid || minSizeSet))
1967      {
1968        // We need to lock here, because the calculation depends on the
1969        // component structure not changing.
1970        synchronized (getTreeLock())
1971          {
1972            ComponentPeer p = peer;
1973            if (p != null)
1974              size = peer.minimumSize();
1975            else
1976              size = size();
1977          }
1978      }
1979    return size;
1980  }
1981
1982  /**
1983   * Returns the component's maximum size.
1984   *
1985   * @return the component's maximum size
1986   * @see #getMinimumSize()
1987   * @see #setMaximumSize(Dimension)
1988   * @see #getPreferredSize()
1989   * @see LayoutManager
1990   */
1991  public Dimension getMaximumSize()
1992  {
1993    return new Dimension(maximumSizeImpl());
1994  }
1995
1996  /**
1997   * This is pulled out from getMaximumSize(), so that we can access it
1998   * from Container.getMaximumSize() without creating an additional
1999   * intermediate Dimension object.
2000   *
2001   * @return the maximum size of the component
2002   */
2003  Dimension maximumSizeImpl()
2004  {
2005    Dimension size;
2006    if (maxSizeSet)
2007      size = maxSize;
2008    else
2009      size = DEFAULT_MAX_SIZE;
2010    return size;
2011  }
2012
2013  /**
2014   * Sets the maximum size that will be returned by {@link #getMaximumSize()}
2015   * always, and sends a {@link PropertyChangeEvent} (with the property name
2016   * 'maximumSize') to all registered listeners.
2017   * 
2018   * @param size  the maximum size (<code>null</code> permitted).
2019   * 
2020   * @since 1.5
2021   * 
2022   * @see #getMaximumSize()
2023   */
2024  public void setMaximumSize(Dimension size)
2025  {
2026    Dimension old = maxSizeSet ? maxSize : null;
2027    maxSize = size;
2028    maxSizeSet = (size != null);
2029    firePropertyChange("maximumSize", old, size);
2030  }
2031
2032  /**
2033   * Returns <code>true</code> if the current maximum size is not 
2034   * <code>null</code> and was set by a call to 
2035   * {@link #setMaximumSize(Dimension)}, otherwise returns <code>false</code>.
2036   * 
2037   * @return A boolean.
2038   * 
2039   * @since 1.5
2040   */
2041  public boolean isMaximumSizeSet()
2042  {
2043    return maxSizeSet;
2044  }
2045  
2046  /**
2047   * Returns the preferred horizontal alignment of this component. The value
2048   * returned will be between {@link #LEFT_ALIGNMENT} and
2049   * {@link #RIGHT_ALIGNMENT}, inclusive.
2050   *
2051   * @return the preferred horizontal alignment of this component
2052   */
2053  public float getAlignmentX()
2054  {
2055    return CENTER_ALIGNMENT;
2056  }
2057
2058  /**
2059   * Returns the preferred vertical alignment of this component. The value
2060   * returned will be between {@link #TOP_ALIGNMENT} and
2061   * {@link #BOTTOM_ALIGNMENT}, inclusive.
2062   *
2063   * @return the preferred vertical alignment of this component
2064   */
2065  public float getAlignmentY()
2066  {
2067    return CENTER_ALIGNMENT;
2068  }
2069
2070  /**
2071   * Calls the layout manager to re-layout the component. This is called
2072   * during validation of a container in most cases.
2073   *
2074   * @see #validate()
2075   * @see LayoutManager
2076   */
2077  public void doLayout()
2078  {
2079    layout ();
2080  }
2081
2082  /**
2083   * Calls the layout manager to re-layout the component. This is called
2084   * during validation of a container in most cases.
2085   *
2086   * @deprecated use {@link #doLayout()} instead
2087   */
2088  public void layout()
2089  {
2090    // Nothing to do unless we're a container.
2091  }
2092
2093  /**
2094   * Called to ensure that the layout for this component is valid. This is
2095   * usually called on containers.
2096   *
2097   * @see #invalidate()
2098   * @see #doLayout()
2099   * @see LayoutManager
2100   * @see Container#validate()
2101   */
2102  public void validate()
2103  {
2104    if (! valid)
2105      {
2106        // Synchronize on the tree here as this might change the layout
2107        // of the hierarchy.
2108        synchronized (getTreeLock())
2109          {
2110            // Create local variables for thread safety.
2111            ComponentPeer p = peer;
2112            if (p != null)
2113              {
2114                // Possibly update the peer's font.
2115                Font newFont = getFont();
2116                Font oldFont = peerFont;
2117                // Only update when the font really changed.
2118                if (newFont != oldFont
2119                    && (oldFont == null || ! oldFont.equals(newFont)))
2120                  {
2121                    p.setFont(newFont);
2122                    peerFont = newFont;
2123                  }
2124                // Let the peer perform any layout.
2125                p.layout();
2126              }
2127          }
2128        valid = true;
2129      }
2130  }
2131
2132  /**
2133   * Invalidates this component and all of its parent components. This will
2134   * cause them to have their layout redone. This is called frequently, so
2135   * make it fast.
2136   */
2137  public void invalidate()
2138  {
2139    // Need to lock here, to avoid races and other ugly stuff when doing
2140    // layout or structure changes in other threads.
2141    synchronized (getTreeLock())
2142      {
2143        // Invalidate.
2144        valid = false;
2145
2146        // Throw away cached layout information.
2147        if (! minSizeSet)
2148          minSize = null;
2149        if (! prefSizeSet)
2150          prefSize = null;
2151        if (! maxSizeSet)
2152          maxSize = null;
2153
2154        // Also invalidate the parent, if it hasn't already been invalidated.
2155        if (parent != null && parent.isValid())
2156          parent.invalidate();
2157      }
2158  }
2159
2160  /**
2161   * Returns a graphics object for this component. Returns <code>null</code>
2162   * if this component is not currently displayed on the screen.
2163   *
2164   * @return a graphics object for this component
2165   * @see #paint(Graphics)
2166   */
2167  public Graphics getGraphics()
2168  {
2169    // Only heavyweight peers can handle this.
2170    ComponentPeer p = peer;
2171    Graphics g = null;
2172    if (p instanceof LightweightPeer)
2173      {
2174        if (parent != null)
2175          {
2176            g = parent.getGraphics();
2177            if (g != null)
2178              {
2179                g.translate(x, y);
2180                g.setClip(0, 0, width, height);
2181                g.setFont(getFont());
2182              }
2183          }
2184      }
2185    else
2186      {
2187        if (p != null)
2188          g = p.getGraphics();
2189      }
2190    return g;
2191  }
2192
2193  /**
2194   * Returns the font metrics for the specified font in this component.
2195   *
2196   * @param font the font to retrieve metrics for
2197   * @return the font metrics for the specified font
2198   * @throws NullPointerException if font is null
2199   * @see #getFont()
2200   * @see Toolkit#getFontMetrics(Font)
2201   */
2202  public FontMetrics getFontMetrics(Font font)
2203  {
2204    ComponentPeer p = peer;
2205    Component comp = this;
2206    while (p instanceof LightweightPeer)
2207      {
2208        comp = comp.parent;
2209        p = comp == null ? null : comp.peer;
2210      }
2211
2212    return p == null ? getToolkit().getFontMetrics(font)
2213           : p.getFontMetrics(font);
2214  }
2215
2216  /**
2217   * Sets the cursor for this component to the specified cursor. The cursor
2218   * is displayed when the point is contained by the component, and the
2219   * component is visible, displayable, and enabled. This is inherited by
2220   * subcomponents unless they set their own cursor.
2221   *
2222   * @param cursor the new cursor for this component
2223   * @see #isEnabled()
2224   * @see #isShowing()
2225   * @see #getCursor()
2226   * @see #contains(int, int)
2227   * @see Toolkit#createCustomCursor(Image, Point, String)
2228   */
2229  public void setCursor(Cursor cursor)
2230  {
2231    this.cursor = cursor;
2232
2233    // Only heavyweight peers handle this.
2234    ComponentPeer p = peer;
2235    Component comp = this;
2236    while (p instanceof LightweightPeer)
2237      {
2238        comp = comp.parent;
2239        p = comp == null ? null : comp.peer;
2240      }
2241
2242    if (p != null)
2243      p.setCursor(cursor);
2244  }
2245
2246  /**
2247   * Returns the cursor for this component. If not set, this is inherited
2248   * from the parent, or from Cursor.getDefaultCursor().
2249   *
2250   * @return the cursor for this component
2251   */
2252  public Cursor getCursor()
2253  {
2254    if (cursor != null)
2255      return cursor;
2256    return parent != null ? parent.getCursor() : Cursor.getDefaultCursor();
2257  }
2258
2259  /**
2260   * Tests if the cursor was explicitly set, or just inherited from the parent.
2261   *
2262   * @return true if the cursor has been set
2263   * @since 1.4
2264   */
2265  public boolean isCursorSet()
2266  {
2267    return cursor != null;
2268  }
2269
2270  /**
2271   * Paints this component on the screen. The clipping region in the graphics
2272   * context will indicate the region that requires painting. This is called
2273   * whenever the component first shows, or needs to be repaired because
2274   * something was temporarily drawn on top. It is not necessary for
2275   * subclasses to call <code>super.paint(g)</code>. Components with no area
2276   * are not painted.
2277   *
2278   * @param g the graphics context for this paint job
2279   * @see #update(Graphics)
2280   */
2281  public void paint(Graphics g)
2282  {
2283    // This is a callback method and is meant to be overridden by subclasses
2284    // that want to perform custom painting.
2285  }
2286
2287  /**
2288   * Updates this component. This is called for heavyweight components in
2289   * response to {@link #repaint()}. The default implementation simply forwards
2290   * to {@link #paint(Graphics)}. The coordinates of the graphics are
2291   * relative to this component. Subclasses should call either
2292   * <code>super.update(g)</code> or <code>paint(g)</code>.
2293   *
2294   * @param g the graphics context for this update
2295   *
2296   * @see #paint(Graphics)
2297   * @see #repaint()
2298   */
2299  public void update(Graphics g)
2300  {
2301    // Note 1: We used to clear the background here for lightweights and
2302    // toplevel components. Tests show that this is not what the JDK does
2303    // here. Note that there is some special handling and background
2304    // clearing code in Container.update(Graphics).
2305
2306    // Note 2 (for peer implementors): The JDK doesn't seem call update() for
2307    // toplevel components, even when an UPDATE event is sent (as a result
2308    // of repaint).
2309    paint(g);
2310  }
2311
2312  /**
2313   * Paints this entire component, including any sub-components.
2314   *
2315   * @param g the graphics context for this paint job
2316   * 
2317   * @see #paint(Graphics)
2318   */
2319  public void paintAll(Graphics g)
2320  {
2321    if (isShowing())
2322      {
2323        validate();
2324        if (peer instanceof LightweightPeer)
2325          paint(g);
2326        else
2327          peer.paint(g);
2328      }
2329  }
2330
2331  /**
2332   * Repaint this entire component. The <code>update()</code> method
2333   * on this component will be called as soon as possible.
2334   *
2335   * @see #update(Graphics)
2336   * @see #repaint(long, int, int, int, int)
2337   */
2338  public void repaint()
2339  {   
2340    repaint(0, 0, 0, width, height);
2341  }
2342
2343  /**
2344   * Repaint this entire component. The <code>update()</code> method on this
2345   * component will be called in approximate the specified number of
2346   * milliseconds.
2347   *
2348   * @param tm milliseconds before this component should be repainted
2349   * @see #paint(Graphics)
2350   * @see #repaint(long, int, int, int, int)
2351   */
2352  public void repaint(long tm)
2353  {
2354    repaint(tm, 0, 0, width, height);
2355  }
2356
2357  /**
2358   * Repaints the specified rectangular region within this component. The
2359   * <code>update</code> method on this component will be called as soon as
2360   * possible. The coordinates are relative to this component.
2361   *
2362   * @param x the X coordinate of the upper left of the region to repaint
2363   * @param y the Y coordinate of the upper left of the region to repaint
2364   * @param w the width of the region to repaint
2365   * @param h the height of the region to repaint
2366   * @see #update(Graphics)
2367   * @see #repaint(long, int, int, int, int)
2368   */
2369  public void repaint(int x, int y, int w, int h)
2370  {
2371    repaint(0, x, y, w, h);
2372  }
2373
2374  /**
2375   * Repaints the specified rectangular region within this component. The
2376   * <code>update</code> method on this component will be called in
2377   * approximately the specified number of milliseconds. The coordinates
2378   * are relative to this component.
2379   *
2380   * @param tm milliseconds before this component should be repainted
2381   * @param x the X coordinate of the upper left of the region to repaint
2382   * @param y the Y coordinate of the upper left of the region to repaint
2383   * @param width the width of the region to repaint
2384   * @param height the height of the region to repaint
2385   * @see #update(Graphics)
2386   */
2387  public void repaint(long tm, int x, int y, int width, int height)
2388  {
2389    // The repaint() call has previously been delegated to
2390    // {@link ComponentPeer.repaint()}. Testing on the JDK using some
2391    // dummy peers show that this methods is never called. I think it makes
2392    // sense to actually perform the tasks below here, since it's pretty
2393    // much peer independent anyway, and makes sure only heavyweights are
2394    // bothered by this.
2395    ComponentPeer p = peer;
2396
2397    // Let the nearest heavyweight parent handle repainting for lightweight
2398    // components.
2399    // We need to recursivly call repaint() on the parent here, since
2400    // a (lightweight) parent component might have overridden repaint()
2401    // to perform additional custom tasks.
2402
2403    if (p instanceof LightweightPeer)
2404      {
2405        // We perform some boundary checking to restrict the paint
2406        // region to this component.
2407        if (parent != null)
2408          {
2409            int px = this.x + Math.max(0, x); 
2410            int py = this.y + Math.max(0, y);
2411            int pw = Math.min(this.width, width);
2412            int ph = Math.min(this.height, height);
2413            parent.repaint(tm, px, py, pw, ph);
2414          }
2415      }
2416    else
2417      {
2418        // Now send an UPDATE event to the heavyweight component that we've found.
2419        if (isVisible() && p != null && width > 0 && height > 0)
2420          {
2421            PaintEvent pe = new PaintEvent(this, PaintEvent.UPDATE,
2422                                           new Rectangle(x, y, width, height));
2423            getToolkit().getSystemEventQueue().postEvent(pe);
2424          }
2425      }
2426  }
2427
2428  /**
2429   * Prints this component. This method is provided so that printing can be
2430   * done in a different manner from painting. However, the implementation
2431   * in this class simply calls the <code>paint()</code> method.
2432   *
2433   * @param g the graphics context of the print device
2434   * 
2435   * @see #paint(Graphics)
2436   */
2437  public void print(Graphics g)
2438  {
2439    paint(g);
2440  }
2441
2442  /**
2443   * Prints this component, including all sub-components. 
2444   *
2445   * @param g the graphics context of the print device
2446   * 
2447   * @see #paintAll(Graphics)
2448   */
2449  public void printAll(Graphics g)
2450  {
2451    if( peer != null )
2452      peer.print( g );
2453    paintAll( g );
2454  }
2455
2456  /**
2457   * Called when an image has changed so that this component is repainted.
2458   * This incrementally draws an image as more bits are available, when
2459   * possible. Incremental drawing is enabled if the system property
2460   * <code>awt.image.incrementalDraw</code> is not present or is true, in which
2461   * case the redraw rate is set to 100ms or the value of the system property
2462   * <code>awt.image.redrawrate</code>.
2463   *
2464   * <p>The coordinate system used depends on the particular flags.
2465   *
2466   * @param img the image that has been updated
2467   * @param flags tlags as specified in <code>ImageObserver</code>
2468   * @param x the X coordinate
2469   * @param y the Y coordinate
2470   * @param w the width
2471   * @param h the height
2472   * @return false if the image is completely loaded, loading has been
2473   * aborted, or an error has occurred.  true if more updates are
2474   * required.
2475   * @see ImageObserver
2476   * @see Graphics#drawImage(Image, int, int, Color, ImageObserver)
2477   * @see Graphics#drawImage(Image, int, int, ImageObserver)
2478   * @see Graphics#drawImage(Image, int, int, int, int, Color, ImageObserver)
2479   * @see Graphics#drawImage(Image, int, int, int, int, ImageObserver)
2480   * @see ImageObserver#imageUpdate(Image, int, int, int, int, int)
2481   */
2482  public boolean imageUpdate(Image img, int flags, int x, int y, int w, int h)
2483  {
2484    if ((flags & (FRAMEBITS | ALLBITS)) != 0)
2485      repaint();
2486    else if ((flags & SOMEBITS) != 0)
2487      {
2488        if (incrementalDraw)
2489          {
2490            if (redrawRate != null)
2491              {
2492                long tm = redrawRate.longValue();
2493                if (tm < 0)
2494                  tm = 0;
2495                repaint(tm);
2496              }
2497            else
2498              repaint(100);
2499          }
2500      }
2501    return (flags & (ALLBITS | ABORT | ERROR)) == 0;
2502  }
2503
2504  /**
2505   * Creates an image from the specified producer.
2506   *
2507   * @param producer the image procedure to create the image from
2508   * @return the resulting image
2509   */
2510  public Image createImage(ImageProducer producer)
2511  {
2512    // Only heavyweight peers can handle this.
2513    ComponentPeer p = peer;
2514    Component comp = this;
2515    while (p instanceof LightweightPeer)
2516      {
2517        comp = comp.parent;
2518        p = comp == null ? null : comp.peer;
2519      }
2520
2521    // Sun allows producer to be null.
2522    Image im;
2523    if (p != null)
2524      im = p.createImage(producer);
2525    else
2526      im = getToolkit().createImage(producer);
2527    return im;
2528  }
2529
2530  /**
2531   * Creates an image with the specified width and height for use in
2532   * double buffering. Headless environments do not support images.
2533   *
2534   * @param width the width of the image
2535   * @param height the height of the image
2536   * @return the requested image, or null if it is not supported
2537   */
2538  public Image createImage (int width, int height)
2539  {
2540    Image returnValue = null;
2541    if (!GraphicsEnvironment.isHeadless ())
2542      {
2543        // Only heavyweight peers can handle this.
2544        ComponentPeer p = peer;
2545        Component comp = this;
2546        while (p instanceof LightweightPeer)
2547          {
2548            comp = comp.parent;
2549            p = comp == null ? null : comp.peer;
2550          }
2551
2552        if (p != null)
2553          returnValue = p.createImage(width, height);
2554      }
2555    return returnValue;
2556  }
2557
2558  /**
2559   * Creates an image with the specified width and height for use in
2560   * double buffering. Headless environments do not support images.
2561   *
2562   * @param width the width of the image
2563   * @param height the height of the image
2564   * @return the requested image, or null if it is not supported
2565   * @since 1.4
2566   */
2567  public VolatileImage createVolatileImage(int width, int height)
2568  {
2569    // Only heavyweight peers can handle this.
2570    ComponentPeer p = peer;
2571    Component comp = this;
2572    while (p instanceof LightweightPeer)
2573      {
2574        comp = comp.parent;
2575        p = comp == null ? null : comp.peer;
2576      }
2577
2578    VolatileImage im = null;
2579    if (p != null)
2580      im = p.createVolatileImage(width, height);
2581    return im;
2582  }
2583
2584  /**
2585   * Creates an image with the specified width and height for use in
2586   * double buffering. Headless environments do not support images. The image
2587   * will support the specified capabilities.
2588   *
2589   * @param width the width of the image
2590   * @param height the height of the image
2591   * @param caps the requested capabilities
2592   * @return the requested image, or null if it is not supported
2593   * @throws AWTException if a buffer with the capabilities cannot be created
2594   * @since 1.4
2595   */
2596  public VolatileImage createVolatileImage(int width, int height,
2597                                           ImageCapabilities caps)
2598    throws AWTException
2599  {
2600    // Only heavyweight peers can handle this.
2601    ComponentPeer p = peer;
2602    Component comp = this;
2603    while (p instanceof LightweightPeer)
2604      {
2605        comp = comp.parent;
2606        p = comp == null ? null : comp.peer;
2607      }
2608
2609    VolatileImage im = null;
2610    if (p != null)
2611      im = peer.createVolatileImage(width, height);
2612    return im;
2613  }
2614
2615  /**
2616   * Prepares the specified image for rendering on this component.
2617   *
2618   * @param image the image to prepare for rendering
2619   * @param observer the observer to notify of image preparation status
2620   * @return true if the image is already fully prepared
2621   * @throws NullPointerException if image is null
2622   */
2623  public boolean prepareImage(Image image, ImageObserver observer)
2624  {
2625    return prepareImage(image, image.getWidth(observer),
2626                        image.getHeight(observer), observer);
2627  }
2628
2629  /**
2630   * Prepares the specified image for rendering on this component at the
2631   * specified scaled width and height
2632   *
2633   * @param image the image to prepare for rendering
2634   * @param width the scaled width of the image
2635   * @param height the scaled height of the image
2636   * @param observer the observer to notify of image preparation status
2637   * @return true if the image is already fully prepared
2638   */
2639  public boolean prepareImage(Image image, int width, int height,
2640                              ImageObserver observer)
2641  {
2642    // Only heavyweight peers handle this.
2643    ComponentPeer p = peer;
2644    Component comp = this;
2645    while (p instanceof LightweightPeer)
2646      {
2647        comp = comp.parent;
2648        p = comp == null ? null : comp.peer;
2649      }
2650
2651    boolean retval;
2652    if (p != null)
2653        retval = p.prepareImage(image, width, height, observer);
2654    else
2655        retval = getToolkit().prepareImage(image, width, height, observer);
2656    return retval;
2657  }
2658
2659  /**
2660   * Returns the status of the loading of the specified image. The value
2661   * returned will be those flags defined in <code>ImageObserver</code>.
2662   *
2663   * @param image the image to check on
2664   * @param observer the observer to notify of image loading progress
2665   * @return the image observer flags indicating the status of the load
2666   * @see #prepareImage(Image, int, int, ImageObserver)
2667   * @see Toolkit#checkImage(Image, int, int, ImageObserver)
2668   * @throws NullPointerException if image is null
2669   */
2670  public int checkImage(Image image, ImageObserver observer)
2671  {
2672    return checkImage(image, -1, -1, observer);
2673  }
2674
2675  /**
2676   * Returns the status of the loading of the specified image. The value
2677   * returned will be those flags defined in <code>ImageObserver</code>.
2678   *
2679   * @param image the image to check on
2680   * @param width the scaled image width
2681   * @param height the scaled image height
2682   * @param observer the observer to notify of image loading progress
2683   * @return the image observer flags indicating the status of the load
2684   * @see #prepareImage(Image, int, int, ImageObserver)
2685   * @see Toolkit#checkImage(Image, int, int, ImageObserver)
2686   */
2687  public int checkImage(Image image, int width, int height,
2688                        ImageObserver observer)
2689  {
2690    // Only heavyweight peers handle this.
2691    ComponentPeer p = peer;
2692    Component comp = this;
2693    while (p instanceof LightweightPeer)
2694      {
2695        comp = comp.parent;
2696        p = comp == null ? null : comp.peer;
2697      }
2698
2699    int retval;
2700    if (p != null)
2701      retval = p.checkImage(image, width, height, observer);
2702    else
2703      retval = getToolkit().checkImage(image, width, height, observer);
2704    return retval;
2705  }
2706
2707  /**
2708   * Sets whether paint messages delivered by the operating system should be
2709   * ignored. This does not affect messages from AWT, except for those
2710   * triggered by OS messages. Setting this to true can allow faster
2711   * performance in full-screen mode or page-flipping.
2712   *
2713   * @param ignoreRepaint the new setting for ignoring repaint events
2714   * @see #getIgnoreRepaint()
2715   * @see BufferStrategy
2716   * @see GraphicsDevice#setFullScreenWindow(Window)
2717   * @since 1.4
2718   */
2719  public void setIgnoreRepaint(boolean ignoreRepaint)
2720  {
2721    this.ignoreRepaint = ignoreRepaint;
2722  }
2723
2724  /**
2725   * Test whether paint events from the operating system are ignored.
2726   *
2727   * @return the status of ignoring paint events
2728   * @see #setIgnoreRepaint(boolean)
2729   * @since 1.4
2730   */
2731  public boolean getIgnoreRepaint()
2732  {
2733    return ignoreRepaint;
2734  }
2735
2736  /**
2737   * Tests whether or not the specified point is contained within this
2738   * component. Coordinates are relative to this component.
2739   *
2740   * @param x the X coordinate of the point to test
2741   * @param y the Y coordinate of the point to test
2742   * @return true if the point is within this component
2743   * @see #getComponentAt(int, int)
2744   */
2745  public boolean contains(int x, int y)
2746  {
2747    return inside (x, y);
2748  }
2749
2750  /**
2751   * Tests whether or not the specified point is contained within this
2752   * component. Coordinates are relative to this component.
2753   *
2754   * @param x the X coordinate of the point to test
2755   * @param y the Y coordinate of the point to test
2756   * @return true if the point is within this component
2757   * @deprecated use {@link #contains(int, int)} instead
2758   */
2759  public boolean inside(int x, int y)
2760  {
2761    return x >= 0 && y >= 0 && x < width && y < height;
2762  }
2763
2764  /**
2765   * Tests whether or not the specified point is contained within this
2766   * component. Coordinates are relative to this component.
2767   *
2768   * @param p the point to test
2769   * @return true if the point is within this component
2770   * @throws NullPointerException if p is null
2771   * @see #getComponentAt(Point)
2772   * @since 1.1
2773   */
2774  public boolean contains(Point p)
2775  {
2776    return contains (p.x, p.y);
2777  }
2778
2779  /**
2780   * Returns the component occupying the position (x,y). This will either
2781   * be this component, an immediate child component, or <code>null</code>
2782   * if neither of the first two occupies the specified location.
2783   *
2784   * @param x the X coordinate to search for components at
2785   * @param y the Y coordinate to search for components at
2786   * @return the component at the specified location, or null
2787   * @see #contains(int, int)
2788   */
2789  public Component getComponentAt(int x, int y)
2790  {
2791    return locate (x, y);
2792  }
2793
2794  /**
2795   * Returns the component occupying the position (x,y). This will either
2796   * be this component, an immediate child component, or <code>null</code>
2797   * if neither of the first two occupies the specified location.
2798   *
2799   * @param x the X coordinate to search for components at
2800   * @param y the Y coordinate to search for components at
2801   * @return the component at the specified location, or null
2802   * @deprecated use {@link #getComponentAt(int, int)} instead
2803   */
2804  public Component locate(int x, int y)
2805  {
2806    return contains (x, y) ? this : null;
2807  }
2808
2809  /**
2810   * Returns the component occupying the position (x,y). This will either
2811   * be this component, an immediate child component, or <code>null</code>
2812   * if neither of the first two occupies the specified location.
2813   *
2814   * @param p the point to search for components at
2815   * @return the component at the specified location, or null
2816   * @throws NullPointerException if p is null
2817   * @see #contains(Point)
2818   * @since 1.1
2819   */
2820  public Component getComponentAt(Point p)
2821  {
2822    return getComponentAt (p.x, p.y);
2823  }
2824
2825  /**
2826   * AWT 1.0 event delivery.
2827   *
2828   * Deliver an AWT 1.0 event to this Component.  This method simply
2829   * calls {@link #postEvent}.
2830   *
2831   * @param e the event to deliver
2832   * @deprecated use {@link #dispatchEvent (AWTEvent)} instead
2833   */
2834  public void deliverEvent (Event e)
2835  {
2836    postEvent (e);
2837  }
2838
2839  /**
2840   * Forwards AWT events to processEvent() if:<ul>
2841   * <li>Events have been enabled for this type of event via
2842   * <code>enableEvents()</code></li>,
2843   * <li>There is at least one registered listener for this type of event</li>
2844   * </ul>
2845   *
2846   * @param e the event to dispatch
2847   */
2848  public final void dispatchEvent(AWTEvent e)
2849  {
2850    // Some subclasses in the AWT package need to override this behavior,
2851    // hence the use of dispatchEventImpl().
2852    dispatchEventImpl(e);
2853  }
2854
2855  /**
2856   * By default, no old mouse events should be ignored.
2857   * This can be overridden by subclasses.
2858   * 
2859   * @return false, no mouse events are ignored.
2860   */
2861  static boolean ignoreOldMouseEvents()
2862  {
2863    return false;
2864  }
2865  
2866  /**
2867   * AWT 1.0 event handler.
2868   *
2869   * This method simply calls handleEvent and returns the result.
2870   *
2871   * @param e the event to handle
2872   * @return true if the event was handled, false otherwise
2873   * @deprecated use {@link #dispatchEvent(AWTEvent)} instead
2874   */
2875  public boolean postEvent (Event e)
2876  {
2877    boolean handled = handleEvent (e);
2878
2879    if (!handled && getParent() != null)
2880      // FIXME: need to translate event coordinates to parent's
2881      // coordinate space.
2882      handled = getParent ().postEvent (e);
2883
2884    return handled;
2885  }
2886
2887  /**
2888   * Adds the specified listener to this component. This is harmless if the
2889   * listener is null, but if the listener has already been registered, it
2890   * will now be registered twice.
2891   *
2892   * @param listener the new listener to add
2893   * @see ComponentEvent
2894   * @see #removeComponentListener(ComponentListener)
2895   * @see #getComponentListeners()
2896   * @since 1.1
2897   */
2898  public synchronized void addComponentListener(ComponentListener listener)
2899  {
2900    if (listener != null)
2901      {
2902        componentListener = AWTEventMulticaster.add(componentListener,
2903                                                    listener);
2904        newEventsOnly = true;
2905      }
2906  }
2907
2908  /**
2909   * Removes the specified listener from the component. This is harmless if
2910   * the listener was not previously registered.
2911   *
2912   * @param listener the listener to remove
2913   * @see ComponentEvent
2914   * @see #addComponentListener(ComponentListener)
2915   * @see #getComponentListeners()
2916   * @since 1.1
2917   */
2918  public synchronized void removeComponentListener(ComponentListener listener)
2919  {
2920    componentListener = AWTEventMulticaster.remove(componentListener, listener);
2921  }
2922
2923  /**
2924   * Returns an array of all specified listeners registered on this component.
2925   *
2926   * @return an array of listeners
2927   * @see #addComponentListener(ComponentListener)
2928   * @see #removeComponentListener(ComponentListener)
2929   * @since 1.4
2930   */
2931  public synchronized ComponentListener[] getComponentListeners()
2932  {
2933    return (ComponentListener[])
2934      AWTEventMulticaster.getListeners(componentListener,
2935                                       ComponentListener.class);
2936  }
2937
2938  /**
2939   * Adds the specified listener to this component. This is harmless if the
2940   * listener is null, but if the listener has already been registered, it
2941   * will now be registered twice.
2942   *
2943   * @param listener the new listener to add
2944   * @see FocusEvent
2945   * @see #removeFocusListener(FocusListener)
2946   * @see #getFocusListeners()
2947   * @since 1.1
2948   */
2949  public synchronized void addFocusListener(FocusListener listener)
2950  {
2951    if (listener != null)
2952      {
2953        focusListener = AWTEventMulticaster.add(focusListener, listener);
2954        newEventsOnly = true;
2955      }
2956  }
2957
2958  /**
2959   * Removes the specified listener from the component. This is harmless if
2960   * the listener was not previously registered.
2961   *
2962   * @param listener the listener to remove
2963   * @see FocusEvent
2964   * @see #addFocusListener(FocusListener)
2965   * @see #getFocusListeners()
2966   * @since 1.1
2967   */
2968  public synchronized void removeFocusListener(FocusListener listener)
2969  {
2970    focusListener = AWTEventMulticaster.remove(focusListener, listener);
2971  }
2972
2973  /**
2974   * Returns an array of all specified listeners registered on this component.
2975   *
2976   * @return an array of listeners
2977   * @see #addFocusListener(FocusListener)
2978   * @see #removeFocusListener(FocusListener)
2979   * @since 1.4
2980   */
2981  public synchronized FocusListener[] getFocusListeners()
2982  {
2983    return (FocusListener[])
2984      AWTEventMulticaster.getListeners(focusListener, FocusListener.class);
2985  }
2986
2987  /**
2988   * Adds the specified listener to this component. This is harmless if the
2989   * listener is null, but if the listener has already been registered, it
2990   * will now be registered twice.
2991   *
2992   * @param listener the new listener to add
2993   * @see HierarchyEvent
2994   * @see #removeHierarchyListener(HierarchyListener)
2995   * @see #getHierarchyListeners()
2996   * @since 1.3
2997   */
2998  public synchronized void addHierarchyListener(HierarchyListener listener)
2999  {
3000    if (listener != null)
3001      {
3002        hierarchyListener = AWTEventMulticaster.add(hierarchyListener,
3003                                                    listener);
3004        newEventsOnly = true;
3005        // Need to lock the tree, otherwise we might end up inconsistent.
3006        synchronized (getTreeLock())
3007        {
3008          numHierarchyListeners++;
3009          if (parent != null)
3010            parent.updateHierarchyListenerCount(AWTEvent.HIERARCHY_EVENT_MASK,
3011                                                1);
3012        }
3013      }
3014  }
3015
3016  /**
3017   * Removes the specified listener from the component. This is harmless if
3018   * the listener was not previously registered.
3019   *
3020   * @param listener the listener to remove
3021   * @see HierarchyEvent
3022   * @see #addHierarchyListener(HierarchyListener)
3023   * @see #getHierarchyListeners()
3024   * @since 1.3
3025   */
3026  public synchronized void removeHierarchyListener(HierarchyListener listener)
3027  {
3028    hierarchyListener = AWTEventMulticaster.remove(hierarchyListener, listener);
3029
3030    // Need to lock the tree, otherwise we might end up inconsistent.
3031    synchronized (getTreeLock())
3032      {
3033        numHierarchyListeners--;
3034        if (parent != null)
3035          parent.updateHierarchyListenerCount(AWTEvent.HIERARCHY_EVENT_MASK,
3036                                              -1);
3037      }
3038  }
3039
3040  /**
3041   * Returns an array of all specified listeners registered on this component.
3042   *
3043   * @return an array of listeners
3044   * @see #addHierarchyListener(HierarchyListener)
3045   * @see #removeHierarchyListener(HierarchyListener)
3046   * @since 1.4
3047   */
3048  public synchronized HierarchyListener[] getHierarchyListeners()
3049  {
3050    return (HierarchyListener[])
3051      AWTEventMulticaster.getListeners(hierarchyListener,
3052                                       HierarchyListener.class);
3053  }
3054
3055  /**
3056   * Adds the specified listener to this component. This is harmless if the
3057   * listener is null, but if the listener has already been registered, it
3058   * will now be registered twice.
3059   *
3060   * @param listener the new listener to add
3061   * @see HierarchyEvent
3062   * @see #removeHierarchyBoundsListener(HierarchyBoundsListener)
3063   * @see #getHierarchyBoundsListeners()
3064   * @since 1.3
3065   */
3066  public synchronized void
3067    addHierarchyBoundsListener(HierarchyBoundsListener listener)
3068  {
3069    if (listener != null)
3070      {
3071        hierarchyBoundsListener =
3072          AWTEventMulticaster.add(hierarchyBoundsListener, listener);
3073        newEventsOnly = true;
3074
3075        // Need to lock the tree, otherwise we might end up inconsistent.
3076        synchronized (getTreeLock())
3077        {
3078          numHierarchyBoundsListeners++;
3079          if (parent != null)
3080            parent.updateHierarchyListenerCount
3081                                     (AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK, 1);
3082        }
3083      }
3084  }
3085
3086  /**
3087   * Removes the specified listener from the component. This is harmless if
3088   * the listener was not previously registered.
3089   *
3090   * @param listener the listener to remove
3091   * @see HierarchyEvent
3092   * @see #addHierarchyBoundsListener(HierarchyBoundsListener)
3093   * @see #getHierarchyBoundsListeners()
3094   * @since 1.3
3095   */
3096  public synchronized void
3097    removeHierarchyBoundsListener(HierarchyBoundsListener listener)
3098  {
3099    hierarchyBoundsListener =
3100      AWTEventMulticaster.remove(hierarchyBoundsListener, listener);
3101
3102    // Need to lock the tree, otherwise we might end up inconsistent.
3103    synchronized (getTreeLock())
3104      {
3105        numHierarchyBoundsListeners--;
3106        if (parent != null)
3107          parent.updateHierarchyListenerCount
3108                                         (AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK,
3109                                          -1);
3110      }
3111  }
3112
3113  /**
3114   * Returns an array of all specified listeners registered on this component.
3115   *
3116   * @return an array of listeners
3117   * @see #addHierarchyBoundsListener(HierarchyBoundsListener)
3118   * @see #removeHierarchyBoundsListener(HierarchyBoundsListener)
3119   * @since 1.4
3120   */
3121  public synchronized HierarchyBoundsListener[] getHierarchyBoundsListeners()
3122  {
3123    return (HierarchyBoundsListener[])
3124      AWTEventMulticaster.getListeners(hierarchyBoundsListener,
3125                                       HierarchyBoundsListener.class);
3126  }
3127
3128  /**
3129   * Fires a HierarchyEvent or HierarchyChangeEvent on this component.
3130   *
3131   * @param id the event id
3132   * @param changed the changed component
3133   * @param parent the parent
3134   * @param flags the event flags
3135   */
3136  void fireHierarchyEvent(int id, Component changed, Container parent,
3137                          long flags)
3138  {
3139    boolean enabled = false;
3140    switch (id)
3141    {
3142      case HierarchyEvent.HIERARCHY_CHANGED:
3143        enabled = hierarchyListener != null
3144                  || (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0;
3145        break;
3146      case HierarchyEvent.ANCESTOR_MOVED:
3147      case HierarchyEvent.ANCESTOR_RESIZED:
3148        enabled = hierarchyBoundsListener != null
3149                  || (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0;
3150        break;
3151      default:
3152        assert false : "Should not reach here";
3153    }
3154    if (enabled)
3155      {
3156        HierarchyEvent ev = new HierarchyEvent(this, id, changed, parent,
3157                                               flags);
3158        dispatchEvent(ev);
3159      }
3160  }
3161
3162  /**
3163   * Adds the specified listener to this component. This is harmless if the
3164   * listener is null, but if the listener has already been registered, it
3165   * will now be registered twice.
3166   *
3167   * @param listener the new listener to add
3168   * @see KeyEvent
3169   * @see #removeKeyListener(KeyListener)
3170   * @see #getKeyListeners()
3171   * @since 1.1
3172   */
3173  public synchronized void addKeyListener(KeyListener listener)
3174  {
3175    if (listener != null)
3176      {
3177        keyListener = AWTEventMulticaster.add(keyListener, listener);
3178        newEventsOnly = true;
3179      }
3180  }
3181
3182  /**
3183   * Removes the specified listener from the component. This is harmless if
3184   * the listener was not previously registered.
3185   *
3186   * @param listener the listener to remove
3187   * @see KeyEvent
3188   * @see #addKeyListener(KeyListener)
3189   * @see #getKeyListeners()
3190   * @since 1.1
3191   */
3192  public synchronized void removeKeyListener(KeyListener listener)
3193  {
3194    keyListener = AWTEventMulticaster.remove(keyListener, listener);
3195  }
3196
3197  /**
3198   * Returns an array of all specified listeners registered on this component.
3199   *
3200   * @return an array of listeners
3201   * @see #addKeyListener(KeyListener)
3202   * @see #removeKeyListener(KeyListener)
3203   * @since 1.4
3204   */
3205  public synchronized KeyListener[] getKeyListeners()
3206  {
3207    return (KeyListener[])
3208      AWTEventMulticaster.getListeners(keyListener, KeyListener.class);
3209  }
3210
3211  /**
3212   * Adds the specified listener to this component. This is harmless if the
3213   * listener is null, but if the listener has already been registered, it
3214   * will now be registered twice.
3215   *
3216   * @param listener the new listener to add
3217   * @see MouseEvent
3218   * @see #removeMouseListener(MouseListener)
3219   * @see #getMouseListeners()
3220   * @since 1.1
3221   */
3222  public synchronized void addMouseListener(MouseListener listener)
3223  {
3224    if (listener != null)
3225      {
3226        mouseListener = AWTEventMulticaster.add(mouseListener, listener);
3227        newEventsOnly = true;
3228      }
3229  }
3230
3231  /**
3232   * Removes the specified listener from the component. This is harmless if
3233   * the listener was not previously registered.
3234   *
3235   * @param listener the listener to remove
3236   * @see MouseEvent
3237   * @see #addMouseListener(MouseListener)
3238   * @see #getMouseListeners()
3239   * @since 1.1
3240   */
3241  public synchronized void removeMouseListener(MouseListener listener)
3242  {
3243    mouseListener = AWTEventMulticaster.remove(mouseListener, listener);
3244  }
3245
3246  /**
3247   * Returns an array of all specified listeners registered on this component.
3248   *
3249   * @return an array of listeners
3250   * @see #addMouseListener(MouseListener)
3251   * @see #removeMouseListener(MouseListener)
3252   * @since 1.4
3253   */
3254  public synchronized MouseListener[] getMouseListeners()
3255  {
3256    return (MouseListener[])
3257      AWTEventMulticaster.getListeners(mouseListener, MouseListener.class);
3258  }
3259
3260  /**
3261   * Adds the specified listener to this component. This is harmless if the
3262   * listener is null, but if the listener has already been registered, it
3263   * will now be registered twice.
3264   *
3265   * @param listener the new listener to add
3266   * @see MouseEvent
3267   * @see #removeMouseMotionListener(MouseMotionListener)
3268   * @see #getMouseMotionListeners()
3269   * @since 1.1
3270   */
3271  public synchronized void addMouseMotionListener(MouseMotionListener listener)
3272  {
3273    if (listener != null)
3274      {
3275        mouseMotionListener = AWTEventMulticaster.add(mouseMotionListener,
3276                                                      listener);
3277        newEventsOnly = true;
3278      }
3279  }
3280
3281  /**
3282   * Removes the specified listener from the component. This is harmless if
3283   * the listener was not previously registered.
3284   *
3285   * @param listener the listener to remove
3286   * @see MouseEvent
3287   * @see #addMouseMotionListener(MouseMotionListener)
3288   * @see #getMouseMotionListeners()
3289   * @since 1.1
3290   */
3291  public synchronized void removeMouseMotionListener(MouseMotionListener listener)
3292  {
3293    mouseMotionListener = AWTEventMulticaster.remove(mouseMotionListener, listener);
3294  }
3295
3296  /**
3297   * Returns an array of all specified listeners registered on this component.
3298   *
3299   * @return an array of listeners
3300   * @see #addMouseMotionListener(MouseMotionListener)
3301   * @see #removeMouseMotionListener(MouseMotionListener)
3302   * @since 1.4
3303   */
3304  public synchronized MouseMotionListener[] getMouseMotionListeners()
3305  {
3306    return (MouseMotionListener[])
3307      AWTEventMulticaster.getListeners(mouseMotionListener,
3308                                       MouseMotionListener.class);
3309  }
3310
3311  /**
3312   * Adds the specified listener to this component. This is harmless if the
3313   * listener is null, but if the listener has already been registered, it
3314   * will now be registered twice.
3315   *
3316   * @param listener the new listener to add
3317   * @see MouseEvent
3318   * @see MouseWheelEvent
3319   * @see #removeMouseWheelListener(MouseWheelListener)
3320   * @see #getMouseWheelListeners()
3321   * @since 1.4
3322   */
3323  public synchronized void addMouseWheelListener(MouseWheelListener listener)
3324  {
3325    if (listener != null)
3326      {
3327        mouseWheelListener = AWTEventMulticaster.add(mouseWheelListener,
3328                                                     listener);
3329        newEventsOnly = true;
3330      }
3331  }
3332
3333  /**
3334   * Removes the specified listener from the component. This is harmless if
3335   * the listener was not previously registered.
3336   *
3337   * @param listener the listener to remove
3338   * @see MouseEvent
3339   * @see MouseWheelEvent
3340   * @see #addMouseWheelListener(MouseWheelListener)
3341   * @see #getMouseWheelListeners()
3342   * @since 1.4
3343   */
3344  public synchronized void removeMouseWheelListener(MouseWheelListener listener)
3345  {
3346    mouseWheelListener = AWTEventMulticaster.remove(mouseWheelListener, listener);
3347  }
3348
3349  /**
3350   * Returns an array of all specified listeners registered on this component.
3351   *
3352   * @return an array of listeners
3353   * @see #addMouseWheelListener(MouseWheelListener)
3354   * @see #removeMouseWheelListener(MouseWheelListener)
3355   * @since 1.4
3356   */
3357  public synchronized MouseWheelListener[] getMouseWheelListeners()
3358  {
3359    return (MouseWheelListener[])
3360      AWTEventMulticaster.getListeners(mouseWheelListener,
3361                                       MouseWheelListener.class);
3362  }
3363
3364  /**
3365   * Adds the specified listener to this component. This is harmless if the
3366   * listener is null, but if the listener has already been registered, it
3367   * will now be registered twice.
3368   *
3369   * @param listener the new listener to add
3370   * @see InputMethodEvent
3371   * @see #removeInputMethodListener(InputMethodListener)
3372   * @see #getInputMethodListeners()
3373   * @see #getInputMethodRequests()
3374   * @since 1.2
3375   */
3376  public synchronized void addInputMethodListener(InputMethodListener listener)
3377  {
3378    if (listener != null)
3379      {
3380        inputMethodListener = AWTEventMulticaster.add(inputMethodListener,
3381                                                      listener);
3382        newEventsOnly = true;
3383      }
3384  }
3385
3386  /**
3387   * Removes the specified listener from the component. This is harmless if
3388   * the listener was not previously registered.
3389   *
3390   * @param listener the listener to remove
3391   * @see InputMethodEvent
3392   * @see #addInputMethodListener(InputMethodListener)
3393   * @see #getInputMethodRequests()
3394   * @since 1.2
3395   */
3396  public synchronized void removeInputMethodListener(InputMethodListener listener)
3397  {
3398    inputMethodListener = AWTEventMulticaster.remove(inputMethodListener, listener);
3399  }
3400
3401  /**
3402   * Returns an array of all specified listeners registered on this component.
3403   *
3404   * @return an array of listeners
3405   * @see #addInputMethodListener(InputMethodListener)
3406   * @see #removeInputMethodListener(InputMethodListener)
3407   * @since 1.4
3408   */
3409  public synchronized InputMethodListener[] getInputMethodListeners()
3410  {
3411    return (InputMethodListener[])
3412      AWTEventMulticaster.getListeners(inputMethodListener,
3413                                       InputMethodListener.class);
3414  }
3415
3416  /**
3417   * Returns all registered {@link EventListener}s of the given 
3418   * <code>listenerType</code>.
3419   *
3420   * @param listenerType the class of listeners to filter (<code>null</code> 
3421   *                     not permitted).
3422   *                     
3423   * @return An array of registered listeners.
3424   * 
3425   * @throws ClassCastException if <code>listenerType</code> does not implement
3426   *                            the {@link EventListener} interface.
3427   * @throws NullPointerException if <code>listenerType</code> is 
3428   *                              <code>null</code>.
3429   *                            
3430   * @see #getComponentListeners()
3431   * @see #getFocusListeners()
3432   * @see #getHierarchyListeners()
3433   * @see #getHierarchyBoundsListeners()
3434   * @see #getKeyListeners()
3435   * @see #getMouseListeners()
3436   * @see #getMouseMotionListeners()
3437   * @see #getMouseWheelListeners()
3438   * @see #getInputMethodListeners()
3439   * @see #getPropertyChangeListeners()
3440   * @since 1.3
3441   */
3442  public <T extends EventListener> T[] getListeners(Class<T> listenerType)
3443  {
3444    if (listenerType == ComponentListener.class)
3445      return (T[]) getComponentListeners();
3446    if (listenerType == FocusListener.class)
3447      return (T[]) getFocusListeners();
3448    if (listenerType == HierarchyListener.class)
3449      return (T[]) getHierarchyListeners();
3450    if (listenerType == HierarchyBoundsListener.class)
3451      return (T[]) getHierarchyBoundsListeners();
3452    if (listenerType == KeyListener.class)
3453      return (T[]) getKeyListeners();
3454    if (listenerType == MouseListener.class)
3455      return (T[]) getMouseListeners();
3456    if (listenerType == MouseMotionListener.class)
3457      return (T[]) getMouseMotionListeners();
3458    if (listenerType == MouseWheelListener.class)
3459      return (T[]) getMouseWheelListeners();
3460    if (listenerType == InputMethodListener.class)
3461      return (T[]) getInputMethodListeners();
3462    if (listenerType == PropertyChangeListener.class)
3463      return (T[]) getPropertyChangeListeners();
3464    return (T[]) Array.newInstance(listenerType, 0);
3465  }
3466
3467  /**
3468   * Returns the input method request handler, for subclasses which support
3469   * on-the-spot text input. By default, input methods are handled by AWT,
3470   * and this returns null.
3471   *
3472   * @return the input method handler, null by default
3473   * @since 1.2
3474   */
3475  public InputMethodRequests getInputMethodRequests()
3476  {
3477    return null;
3478  }
3479
3480  /**
3481   * Gets the input context of this component, which is inherited from the
3482   * parent unless this is overridden.
3483   *
3484   * @return the text input context
3485   * @since 1.2
3486   */
3487  public InputContext getInputContext()
3488  {
3489    return parent == null ? null : parent.getInputContext();
3490  }
3491
3492  /**
3493   * Enables the specified events. The events to enable are specified
3494   * by OR-ing together the desired masks from <code>AWTEvent</code>.
3495   *
3496   * <p>Events are enabled by default when a listener is attached to the
3497   * component for that event type. This method can be used by subclasses
3498   * to ensure the delivery of a specified event regardless of whether
3499   * or not a listener is attached.
3500   *
3501   * @param eventsToEnable the desired events to enable
3502   * @see #processEvent(AWTEvent)
3503   * @see #disableEvents(long)
3504   * @see AWTEvent
3505   * @since 1.1
3506   */
3507  protected final void enableEvents(long eventsToEnable)
3508  {
3509    // Update the counter for hierarchy (bounds) listeners.
3510    if ((eventsToEnable & AWTEvent.HIERARCHY_EVENT_MASK) != 0
3511        && (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) == 0)
3512      {
3513        // Need to lock the tree, otherwise we might end up inconsistent.
3514        synchronized (getTreeLock())
3515          {
3516            numHierarchyListeners++;
3517            if (parent != null)
3518              parent.updateHierarchyListenerCount
3519                                                (AWTEvent.HIERARCHY_EVENT_MASK,
3520                                                 1);
3521          }
3522      }
3523    if ((eventsToEnable & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0
3524        && (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) == 0)
3525      {
3526        // Need to lock the tree, otherwise we might end up inconsistent.
3527        synchronized (getTreeLock())
3528          {
3529            numHierarchyBoundsListeners++;
3530            if (parent != null)
3531              parent.updateHierarchyListenerCount
3532                                         (AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK,
3533                                          1);
3534          }
3535      }
3536
3537    eventMask |= eventsToEnable;
3538    newEventsOnly = true;
3539
3540    // Only heavyweight peers handle this.
3541    ComponentPeer p = peer;
3542    Component comp = this;
3543    while (p instanceof LightweightPeer)
3544      {
3545        comp = comp.parent;
3546        p = comp == null ? null : comp.peer;
3547      }
3548
3549    if (p != null)
3550      p.setEventMask(eventMask);
3551
3552  }
3553
3554  /**
3555   * Disables the specified events. The events to disable are specified
3556   * by OR-ing together the desired masks from <code>AWTEvent</code>.
3557   *
3558   * @param eventsToDisable the desired events to disable
3559   * @see #enableEvents(long)
3560   * @since 1.1
3561   */
3562  protected final void disableEvents(long eventsToDisable)
3563  {
3564    // Update the counter for hierarchy (bounds) listeners.
3565    if ((eventsToDisable & AWTEvent.HIERARCHY_EVENT_MASK) != 0
3566        && (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0)
3567      {
3568        // Need to lock the tree, otherwise we might end up inconsistent.
3569        synchronized (getTreeLock())
3570          {
3571            numHierarchyListeners--;
3572            if (parent != null)
3573              parent.updateHierarchyListenerCount
3574                                                (AWTEvent.HIERARCHY_EVENT_MASK,
3575                                                 -1);
3576          }
3577      }
3578    if ((eventsToDisable & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0
3579        && (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0)
3580      {
3581        // Need to lock the tree, otherwise we might end up inconsistent.
3582        synchronized (getTreeLock())
3583          {
3584            numHierarchyBoundsListeners--;
3585            if (parent != null)
3586              parent.updateHierarchyListenerCount
3587                                         (AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK,
3588                                          -1);
3589          }
3590      }
3591
3592    eventMask &= ~eventsToDisable;
3593
3594    // Only heavyweight peers handle this.
3595    ComponentPeer p = peer;
3596    Component comp = this;
3597    while (p instanceof LightweightPeer)
3598      {
3599        comp = comp.parent;
3600        p = comp == null ? null : comp.peer;
3601      }
3602
3603    if (p != null)
3604      p.setEventMask(eventMask);
3605
3606  }
3607
3608  /**
3609   * This is called by the EventQueue if two events with the same event id
3610   * and owner component are queued. Returns a new combined event, or null if
3611   * no combining is done. The coelesced events are currently mouse moves
3612   * (intermediate ones are discarded) and paint events (a merged paint is
3613   * created in place of the two events).
3614   *
3615   * @param existingEvent the event on the queue
3616   * @param newEvent the new event that might be entered on the queue
3617   * @return null if both events are kept, or the replacement coelesced event
3618   */
3619  protected AWTEvent coalesceEvents(AWTEvent existingEvent, AWTEvent newEvent)
3620  {
3621    AWTEvent coalesced = null;
3622    switch (existingEvent.id)
3623      {
3624      case MouseEvent.MOUSE_MOVED:
3625      case MouseEvent.MOUSE_DRAGGED:
3626        // Just drop the old (intermediate) event and return the new one.
3627        MouseEvent me1 = (MouseEvent) existingEvent;
3628        MouseEvent me2 = (MouseEvent) newEvent;
3629        if (me1.getModifiers() == me2.getModifiers())
3630          coalesced = newEvent;
3631        break;
3632      case PaintEvent.PAINT:
3633      case PaintEvent.UPDATE:
3634        // For heavyweights the EventQueue should ask the peer.
3635        if (peer == null || peer instanceof LightweightPeer)
3636          {
3637            PaintEvent pe1 = (PaintEvent) existingEvent;
3638            PaintEvent pe2 = (PaintEvent) newEvent;
3639            Rectangle r1 = pe1.getUpdateRect();
3640            Rectangle r2 = pe2.getUpdateRect();
3641            if (r1.contains(r2))
3642              coalesced = existingEvent;
3643            else if (r2.contains(r1))
3644              coalesced = newEvent;
3645          }
3646        else
3647          {
3648            // Replace the event and let the heavyweight figure out the expanding
3649            // of the repaint area.
3650            coalesced = newEvent;
3651          }
3652        break;
3653      default:
3654        coalesced = null;
3655      }
3656    return coalesced;
3657  }
3658
3659  /**
3660   * Processes the specified event. In this class, this method simply
3661   * calls one of the more specific event handlers.
3662   *
3663   * @param e the event to process
3664   * @throws NullPointerException if e is null
3665   * @see #processComponentEvent(ComponentEvent)
3666   * @see #processFocusEvent(FocusEvent)
3667   * @see #processKeyEvent(KeyEvent)
3668   * @see #processMouseEvent(MouseEvent)
3669   * @see #processMouseMotionEvent(MouseEvent)
3670   * @see #processInputMethodEvent(InputMethodEvent)
3671   * @see #processHierarchyEvent(HierarchyEvent)
3672   * @see #processMouseWheelEvent(MouseWheelEvent)
3673   * @since 1.1
3674   */
3675  protected void processEvent(AWTEvent e)
3676  {
3677    /* Note: the order of these if statements are
3678       important. Subclasses must be checked first. Eg. MouseEvent
3679       must be checked before ComponentEvent, since a MouseEvent
3680       object is also an instance of a ComponentEvent. */
3681
3682    if (e instanceof FocusEvent)
3683      processFocusEvent((FocusEvent) e);
3684    else if (e instanceof MouseWheelEvent)
3685      processMouseWheelEvent((MouseWheelEvent) e);
3686    else if (e instanceof MouseEvent)
3687      {
3688        if (e.id == MouseEvent.MOUSE_MOVED
3689            || e.id == MouseEvent.MOUSE_DRAGGED)
3690          processMouseMotionEvent((MouseEvent) e);
3691        else
3692          processMouseEvent((MouseEvent) e);
3693      }
3694    else if (e instanceof KeyEvent)
3695      processKeyEvent((KeyEvent) e);
3696    else if (e instanceof InputMethodEvent)
3697      processInputMethodEvent((InputMethodEvent) e);
3698    else if (e instanceof ComponentEvent)
3699      processComponentEvent((ComponentEvent) e);
3700    else if (e instanceof HierarchyEvent)
3701      {
3702        if (e.id == HierarchyEvent.HIERARCHY_CHANGED)
3703          processHierarchyEvent((HierarchyEvent) e);
3704        else
3705          processHierarchyBoundsEvent((HierarchyEvent) e);
3706      }
3707  }
3708
3709  /**
3710   * Called when a component event is dispatched and component events are
3711   * enabled. This method passes the event along to any listeners
3712   * that are attached.
3713   *
3714   * @param e the <code>ComponentEvent</code> to process
3715   * @throws NullPointerException if e is null
3716   * @see ComponentListener
3717   * @see #addComponentListener(ComponentListener)
3718   * @see #enableEvents(long)
3719   * @since 1.1
3720   */
3721  protected void processComponentEvent(ComponentEvent e)
3722  {
3723    if (componentListener == null)
3724      return;
3725    switch (e.id)
3726      {
3727      case ComponentEvent.COMPONENT_HIDDEN:
3728        componentListener.componentHidden(e);
3729        break;
3730      case ComponentEvent.COMPONENT_MOVED:
3731        componentListener.componentMoved(e);
3732        break;
3733      case ComponentEvent.COMPONENT_RESIZED:
3734        componentListener.componentResized(e);
3735        break;
3736      case ComponentEvent.COMPONENT_SHOWN:
3737        componentListener.componentShown(e);
3738        break;
3739      }
3740  }
3741
3742  /**
3743   * Called when a focus event is dispatched and component events are
3744   * enabled. This method passes the event along to any listeners
3745   * that are attached.
3746   *
3747   * @param e the <code>FocusEvent</code> to process
3748   * @throws NullPointerException if e is null
3749   * @see FocusListener
3750   * @see #addFocusListener(FocusListener)
3751   * @see #enableEvents(long)
3752   * @since 1.1
3753   */
3754  protected void processFocusEvent(FocusEvent e)
3755  {
3756    if (focusListener == null)
3757      return;
3758
3759    switch (e.id)
3760      {
3761        case FocusEvent.FOCUS_GAINED:
3762          focusListener.focusGained(e);
3763        break;
3764        case FocusEvent.FOCUS_LOST:
3765          focusListener.focusLost(e);
3766        break;
3767      }
3768  }
3769
3770  /**
3771   * Called when a key event is dispatched and component events are
3772   * enabled. This method passes the event along to any listeners
3773   * that are attached.
3774   *
3775   * @param e the <code>KeyEvent</code> to process
3776   * @throws NullPointerException if e is null
3777   * @see KeyListener
3778   * @see #addKeyListener(KeyListener)
3779   * @see #enableEvents(long)
3780   * @since 1.1
3781   */
3782  protected void processKeyEvent(KeyEvent e)
3783  {
3784    if (keyListener == null)
3785      return;
3786    switch (e.id)
3787      {
3788        case KeyEvent.KEY_PRESSED:
3789          keyListener.keyPressed(e);
3790        break;
3791        case KeyEvent.KEY_RELEASED:
3792          keyListener.keyReleased(e);
3793        break;
3794        case KeyEvent.KEY_TYPED:
3795          keyListener.keyTyped(e);
3796        break;
3797      }
3798  }
3799
3800  /**
3801   * Called when a regular mouse event is dispatched and component events are
3802   * enabled. This method passes the event along to any listeners
3803   * that are attached.
3804   *
3805   * @param e the <code>MouseEvent</code> to process
3806   * @throws NullPointerException if e is null
3807   * @see MouseListener
3808   * @see #addMouseListener(MouseListener)
3809   * @see #enableEvents(long)
3810   * @since 1.1
3811   */
3812  protected void processMouseEvent(MouseEvent e)
3813  {
3814    if (mouseListener == null)
3815      return;
3816    switch (e.id)
3817      {
3818        case MouseEvent.MOUSE_CLICKED:
3819          mouseListener.mouseClicked(e);
3820        break;
3821        case MouseEvent.MOUSE_ENTERED:
3822          if( isLightweight() )
3823            setCursor( getCursor() );
3824          mouseListener.mouseEntered(e);
3825        break;
3826        case MouseEvent.MOUSE_EXITED:
3827          mouseListener.mouseExited(e);
3828        break;
3829        case MouseEvent.MOUSE_PRESSED:
3830          mouseListener.mousePressed(e);
3831        break;
3832        case MouseEvent.MOUSE_RELEASED:
3833          mouseListener.mouseReleased(e);
3834        break;
3835      }
3836  }
3837
3838  /**
3839   * Called when a mouse motion event is dispatched and component events are
3840   * enabled. This method passes the event along to any listeners
3841   * that are attached.
3842   *
3843   * @param e the <code>MouseMotionEvent</code> to process
3844   * @throws NullPointerException if e is null
3845   * @see MouseMotionListener
3846   * @see #addMouseMotionListener(MouseMotionListener)
3847   * @see #enableEvents(long)
3848   * @since 1.1
3849   */
3850  protected void processMouseMotionEvent(MouseEvent e)
3851  {
3852    if (mouseMotionListener == null)
3853      return;
3854    switch (e.id)
3855      {
3856        case MouseEvent.MOUSE_DRAGGED:
3857          mouseMotionListener.mouseDragged(e);
3858        break;
3859        case MouseEvent.MOUSE_MOVED:
3860          mouseMotionListener.mouseMoved(e);
3861        break;
3862      }
3863      e.consume();
3864  }
3865
3866  /**
3867   * Called when a mouse wheel event is dispatched and component events are
3868   * enabled. This method passes the event along to any listeners that are
3869   * attached.
3870   *
3871   * @param e the <code>MouseWheelEvent</code> to process
3872   * @throws NullPointerException if e is null
3873   * @see MouseWheelListener
3874   * @see #addMouseWheelListener(MouseWheelListener)
3875   * @see #enableEvents(long)
3876   * @since 1.4
3877   */
3878  protected void processMouseWheelEvent(MouseWheelEvent e)
3879  {
3880    if (mouseWheelListener != null
3881        && e.id == MouseEvent.MOUSE_WHEEL)
3882    {
3883      mouseWheelListener.mouseWheelMoved(e);
3884      e.consume();
3885    }   
3886  }
3887
3888  /**
3889   * Called when an input method event is dispatched and component events are
3890   * enabled. This method passes the event along to any listeners that are
3891   * attached.
3892   *
3893   * @param e the <code>InputMethodEvent</code> to process
3894   * @throws NullPointerException if e is null
3895   * @see InputMethodListener
3896   * @see #addInputMethodListener(InputMethodListener)
3897   * @see #enableEvents(long)
3898   * @since 1.2
3899   */
3900  protected void processInputMethodEvent(InputMethodEvent e)
3901  {
3902    if (inputMethodListener == null)
3903      return;
3904    switch (e.id)
3905      {
3906        case InputMethodEvent.CARET_POSITION_CHANGED:
3907          inputMethodListener.caretPositionChanged(e);
3908        break;
3909        case InputMethodEvent.INPUT_METHOD_TEXT_CHANGED:
3910          inputMethodListener.inputMethodTextChanged(e);
3911        break;
3912      }
3913  }
3914
3915  /**
3916   * Called when a hierarchy change event is dispatched and component events
3917   * are enabled. This method passes the event along to any listeners that are
3918   * attached.
3919   *
3920   * @param e the <code>HierarchyEvent</code> to process
3921   * @throws NullPointerException if e is null
3922   * @see HierarchyListener
3923   * @see #addHierarchyListener(HierarchyListener)
3924   * @see #enableEvents(long)
3925   * @since 1.3
3926   */
3927  protected void processHierarchyEvent(HierarchyEvent e)
3928  {
3929    if (hierarchyListener == null)
3930      return;
3931    if (e.id == HierarchyEvent.HIERARCHY_CHANGED)
3932      hierarchyListener.hierarchyChanged(e);
3933  }
3934
3935  /**
3936   * Called when a hierarchy bounds event is dispatched and component events
3937   * are enabled. This method passes the event along to any listeners that are
3938   * attached.
3939   *
3940   * @param e the <code>HierarchyEvent</code> to process
3941   * @throws NullPointerException if e is null
3942   * @see HierarchyBoundsListener
3943   * @see #addHierarchyBoundsListener(HierarchyBoundsListener)
3944   * @see #enableEvents(long)
3945   * @since 1.3
3946   */
3947  protected void processHierarchyBoundsEvent(HierarchyEvent e)
3948  {
3949    if (hierarchyBoundsListener == null)
3950      return;
3951    switch (e.id)
3952      {
3953        case HierarchyEvent.ANCESTOR_MOVED:
3954          hierarchyBoundsListener.ancestorMoved(e);
3955        break;
3956        case HierarchyEvent.ANCESTOR_RESIZED:
3957          hierarchyBoundsListener.ancestorResized(e);
3958        break;
3959      }
3960  }
3961
3962  /**
3963   * AWT 1.0 event handler.
3964   *
3965   * This method calls one of the event-specific handler methods.  For
3966   * example for key events, either {@link #keyDown(Event,int)}
3967   * or {@link #keyUp(Event,int)} is called.  A derived
3968   * component can override one of these event-specific methods if it
3969   * only needs to handle certain event types.  Otherwise it can
3970   * override handleEvent itself and handle any event.
3971   *
3972   * @param evt the event to handle
3973   * @return true if the event was handled, false otherwise
3974   * @deprecated use {@link #processEvent(AWTEvent)} instead
3975   */
3976  public boolean handleEvent (Event evt)
3977  {
3978    switch (evt.id)
3979      {
3980        // Handle key events.
3981      case Event.KEY_ACTION:
3982      case Event.KEY_PRESS:
3983        return keyDown (evt, evt.key);
3984      case Event.KEY_ACTION_RELEASE:
3985      case Event.KEY_RELEASE:
3986        return keyUp (evt, evt.key);
3987
3988        // Handle mouse events.
3989      case Event.MOUSE_DOWN:
3990        return mouseDown (evt, evt.x, evt.y);
3991      case Event.MOUSE_UP:
3992        return mouseUp (evt, evt.x, evt.y);
3993      case Event.MOUSE_MOVE:
3994        return mouseMove (evt, evt.x, evt.y);
3995      case Event.MOUSE_DRAG:
3996        return mouseDrag (evt, evt.x, evt.y);
3997      case Event.MOUSE_ENTER:
3998        return mouseEnter (evt, evt.x, evt.y);
3999      case Event.MOUSE_EXIT:
4000        return mouseExit (evt, evt.x, evt.y);
4001
4002        // Handle focus events.
4003      case Event.GOT_FOCUS:
4004        return gotFocus (evt, evt.arg);
4005      case Event.LOST_FOCUS:
4006        return lostFocus (evt, evt.arg);
4007
4008        // Handle action event.
4009      case Event.ACTION_EVENT:
4010        return action (evt, evt.arg);
4011      }
4012    // Unknown event.
4013    return false;
4014  }
4015
4016  /**
4017   * AWT 1.0 MOUSE_DOWN event handler.  This method is meant to be
4018   * overridden by components providing their own MOUSE_DOWN handler.
4019   * The default implementation simply returns false.
4020   *
4021   * @param evt the event to handle
4022   * @param x the x coordinate, ignored
4023   * @param y the y coordinate, ignored
4024   * @return false
4025   * @deprecated use {@link #processMouseEvent(MouseEvent)} instead
4026   */
4027  public boolean mouseDown(Event evt, int x, int y)
4028  {
4029    return false;
4030  }
4031
4032  /**
4033   * AWT 1.0 MOUSE_DRAG event handler.  This method is meant to be
4034   * overridden by components providing their own MOUSE_DRAG handler.
4035   * The default implementation simply returns false.
4036   *
4037   * @param evt the event to handle
4038   * @param x the x coordinate, ignored
4039   * @param y the y coordinate, ignored
4040   * @return false
4041   * @deprecated use {@link #processMouseMotionEvent(MouseEvent)} instead
4042   */
4043  public boolean mouseDrag(Event evt, int x, int y)
4044  {
4045    return false;
4046  }
4047
4048  /**
4049   * AWT 1.0 MOUSE_UP event handler.  This method is meant to be
4050   * overridden by components providing their own MOUSE_UP handler.
4051   * The default implementation simply returns false.
4052   *
4053   * @param evt the event to handle
4054   * @param x the x coordinate, ignored
4055   * @param y the y coordinate, ignored
4056   * @return false
4057   * @deprecated use {@link #processMouseEvent(MouseEvent)} instead
4058   */
4059  public boolean mouseUp(Event evt, int x, int y)
4060  {
4061    return false;
4062  }
4063
4064  /**
4065   * AWT 1.0 MOUSE_MOVE event handler.  This method is meant to be
4066   * overridden by components providing their own MOUSE_MOVE handler.
4067   * The default implementation simply returns false.
4068   *
4069   * @param evt the event to handle
4070   * @param x the x coordinate, ignored
4071   * @param y the y coordinate, ignored
4072   * @return false
4073   * @deprecated use {@link #processMouseMotionEvent(MouseEvent)} instead
4074   */
4075  public boolean mouseMove(Event evt, int x, int y)
4076  {
4077    return false;
4078  }
4079
4080  /**
4081   * AWT 1.0 MOUSE_ENTER event handler.  This method is meant to be
4082   * overridden by components providing their own MOUSE_ENTER handler.
4083   * The default implementation simply returns false.
4084   *
4085   * @param evt the event to handle
4086   * @param x the x coordinate, ignored
4087   * @param y the y coordinate, ignored
4088   * @return false
4089   * @deprecated use {@link #processMouseEvent(MouseEvent)} instead
4090   */
4091  public boolean mouseEnter(Event evt, int x, int y)
4092  {
4093    return false;
4094  }
4095
4096  /**
4097   * AWT 1.0 MOUSE_EXIT event handler.  This method is meant to be
4098   * overridden by components providing their own MOUSE_EXIT handler.
4099   * The default implementation simply returns false.
4100   *
4101   * @param evt the event to handle
4102   * @param x the x coordinate, ignored
4103   * @param y the y coordinate, ignored
4104   * @return false
4105   * @deprecated use {@link #processMouseEvent(MouseEvent)} instead
4106   */
4107  public boolean mouseExit(Event evt, int x, int y)
4108  {
4109    return false;
4110  }
4111
4112  /**
4113   * AWT 1.0 KEY_PRESS and KEY_ACTION event handler.  This method is
4114   * meant to be overridden by components providing their own key
4115   * press handler.  The default implementation simply returns false.
4116   *
4117   * @param evt the event to handle
4118   * @param key the key pressed, ignored
4119   * @return false
4120   * @deprecated use {@link #processKeyEvent(KeyEvent)} instead
4121   */
4122  public boolean keyDown(Event evt, int key)
4123  {
4124    return false;
4125  }
4126
4127  /**
4128   * AWT 1.0 KEY_RELEASE and KEY_ACTION_RELEASE event handler.  This
4129   * method is meant to be overridden by components providing their
4130   * own key release handler.  The default implementation simply
4131   * returns false.
4132   *
4133   * @param evt the event to handle
4134   * @param key the key pressed, ignored
4135   * @return false
4136   * @deprecated use {@link #processKeyEvent(KeyEvent)} instead
4137   */
4138  public boolean keyUp(Event evt, int key)
4139  {
4140    return false;
4141  }
4142
4143  /**
4144   * AWT 1.0 ACTION_EVENT event handler.  This method is meant to be
4145   * overridden by components providing their own action event
4146   * handler.  The default implementation simply returns false.
4147   *
4148   * @param evt the event to handle
4149   * @param what the object acted on, ignored
4150   * @return false
4151   * @deprecated in classes which support actions, use
4152   *             <code>processActionEvent(ActionEvent)</code> instead
4153   */
4154  public boolean action(Event evt, Object what)
4155  {
4156    return false;
4157  }
4158
4159  /**
4160   * Called when the parent of this Component is made visible or when
4161   * the Component is added to an already visible Container and needs
4162   * to be shown.  A native peer - if any - is created at this
4163   * time. This method is called automatically by the AWT system and
4164   * should not be called by user level code.
4165   *
4166   * @see #isDisplayable()
4167   * @see #removeNotify()
4168   */
4169  public void addNotify()
4170  {
4171    // We need to lock the tree here to avoid races and inconsistencies.
4172    synchronized (getTreeLock())
4173      {
4174        if (peer == null)
4175          peer = getToolkit().createComponent(this);
4176        else if (parent != null && parent.isLightweight())
4177          new HeavyweightInLightweightListener(parent);
4178        // Now that all the children has gotten their peers, we should
4179        // have the event mask needed for this component and its
4180        //lightweight subcomponents.
4181        peer.setEventMask(eventMask);
4182
4183        // We used to leave the invalidate() to the peer. However, I put it
4184        // back here for 2 reasons: 1) The RI does call invalidate() from
4185        // addNotify(); 2) The peer shouldn't be bother with validation too
4186        // much.
4187        invalidate();
4188
4189        if (dropTarget != null) 
4190          dropTarget.addNotify(peer);
4191
4192        // Fetch the peerFont for later installation in validate().
4193        peerFont = getFont();
4194
4195        // Notify hierarchy listeners.
4196        long flags = HierarchyEvent.DISPLAYABILITY_CHANGED;
4197        if (isHierarchyVisible())
4198          flags |= HierarchyEvent.SHOWING_CHANGED;
4199        fireHierarchyEvent(HierarchyEvent.HIERARCHY_CHANGED, this, parent,
4200                           flags);
4201      }
4202  }
4203
4204  /**
4205   * Called to inform this component is has been removed from its
4206   * container. Its native peer - if any - is destroyed at this time.
4207   * This method is called automatically by the AWT system and should
4208   * not be called by user level code.
4209   *
4210   * @see #isDisplayable()
4211   * @see #addNotify()
4212   */
4213  public void removeNotify()
4214  {
4215    // We need to lock the tree here to avoid races and inconsistencies.
4216    synchronized (getTreeLock())
4217      {
4218        // We null our peer field before disposing of it, such that if we're
4219        // not the event dispatch thread and the dispatch thread is awoken by
4220        // the dispose call, there will be no race checking the peer's null
4221        // status.
4222
4223        ComponentPeer tmp = peer;
4224        peer = null;
4225        peerFont = null;
4226        if (tmp != null)
4227          {
4228            tmp.hide();
4229            tmp.dispose();
4230          }
4231
4232        // Notify hierarchy listeners.
4233        long flags = HierarchyEvent.DISPLAYABILITY_CHANGED;
4234        if (isHierarchyVisible())
4235          flags |= HierarchyEvent.SHOWING_CHANGED;
4236        fireHierarchyEvent(HierarchyEvent.HIERARCHY_CHANGED, this, parent,
4237                           flags);
4238      }
4239  }
4240
4241  /**
4242   * AWT 1.0 GOT_FOCUS event handler.  This method is meant to be
4243   * overridden by components providing their own GOT_FOCUS handler.
4244   * The default implementation simply returns false.
4245   *
4246   * @param evt the event to handle
4247   * @param what the Object focused, ignored
4248   * @return false
4249   * @deprecated use {@link #processFocusEvent(FocusEvent)} instead
4250   */
4251  public boolean gotFocus(Event evt, Object what)
4252  {
4253    return false;
4254  }
4255
4256  /**
4257   * AWT 1.0 LOST_FOCUS event handler.  This method is meant to be
4258   * overridden by components providing their own LOST_FOCUS handler.
4259   * The default implementation simply returns false.
4260   *
4261   * @param evt the event to handle
4262   * @param what the Object focused, ignored
4263   * @return false
4264   * @deprecated use {@link #processFocusEvent(FocusEvent)} instead
4265   */
4266  public boolean lostFocus(Event evt, Object what)
4267  {
4268    return false;
4269  }
4270
4271  /**
4272   * Tests whether or not this component is in the group that can be
4273   * traversed using the keyboard traversal mechanism (such as the TAB key).
4274   *
4275   * @return true if the component is traversed via the TAB key
4276   * @see #setFocusable(boolean)
4277   * @since 1.1
4278   * @deprecated use {@link #isFocusable()} instead
4279   */
4280  public boolean isFocusTraversable()
4281  {
4282    return enabled && visible && (peer == null || isLightweight() || peer.isFocusTraversable());
4283  }
4284
4285  /**
4286   * Tests if this component can receive focus.
4287   *
4288   * @return true if this component can receive focus
4289   * @since 1.4
4290   */
4291  public boolean isFocusable()
4292  {
4293    return focusable;
4294  }
4295
4296  /**
4297   * Specify whether this component can receive focus. This method also
4298   * sets the {@link #isFocusTraversableOverridden} field to 1, which
4299   * appears to be the undocumented way {@link
4300   * DefaultFocusTraversalPolicy#accept(Component)} determines whether to
4301   * respect the {@link #isFocusable()} method of the component.
4302   *
4303   * @param focusable the new focusable status
4304   * @since 1.4
4305   */
4306  public void setFocusable(boolean focusable)
4307  {
4308    firePropertyChange("focusable", this.focusable, focusable);
4309    this.focusable = focusable;
4310    this.isFocusTraversableOverridden = 1;
4311  }
4312
4313  /**
4314   * Sets the focus traversal keys for one of the three focus
4315   * traversal directions supported by Components:
4316   * {@link KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS},
4317   * {@link KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS}, or
4318   * {@link KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS}. Normally, the
4319   * default values should match the operating system's native
4320   * choices. To disable a given traversal, use
4321   * <code>Collections.EMPTY_SET</code>. The event dispatcher will
4322   * consume PRESSED, RELEASED, and TYPED events for the specified
4323   * key, although focus can only transfer on PRESSED or RELEASED.
4324   *
4325   * <p>The defaults are:
4326   * <table>
4327   *   <th><td>Identifier</td><td>Meaning</td><td>Default</td></th>
4328   *   <tr><td>KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS</td>
4329   *     <td>Normal forward traversal</td>
4330   *     <td>TAB on KEY_PRESSED, Ctrl-TAB on KEY_PRESSED</td></tr>
4331   *   <tr><td>KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS</td>
4332   *     <td>Normal backward traversal</td>
4333   *     <td>Shift-TAB on KEY_PRESSED, Ctrl-Shift-TAB on KEY_PRESSED</td></tr>
4334   *   <tr><td>KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS</td>
4335   *     <td>Go up a traversal cycle</td><td>None</td></tr>
4336   * </table>
4337   *
4338   * If keystrokes is null, this component's focus traversal key set
4339   * is inherited from one of its ancestors.  If none of its ancestors
4340   * has its own set of focus traversal keys, the focus traversal keys
4341   * are set to the defaults retrieved from the current
4342   * KeyboardFocusManager.  If not null, the set must contain only
4343   * AWTKeyStrokes that are not already focus keys and are not
4344   * KEY_TYPED events.
4345   *
4346   * @param id one of FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, or
4347   *        UP_CYCLE_TRAVERSAL_KEYS
4348   * @param keystrokes a set of keys, or null
4349   * @throws IllegalArgumentException if id or keystrokes is invalid
4350   * @see #getFocusTraversalKeys(int)
4351   * @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
4352   * @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
4353   * @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
4354   * @since 1.4
4355   */
4356  public void setFocusTraversalKeys(int id,
4357                                    Set<? extends AWTKeyStroke> keystrokes)
4358  {
4359    if (keystrokes == null)
4360      {
4361        Container parent = getParent ();
4362
4363        while (parent != null)
4364          {
4365            if (parent.areFocusTraversalKeysSet (id))
4366              {
4367                keystrokes = parent.getFocusTraversalKeys (id);
4368                break;
4369              }
4370            parent = parent.getParent ();
4371          }
4372
4373        if (keystrokes == null)
4374          keystrokes = KeyboardFocusManager.getCurrentKeyboardFocusManager ().
4375            getDefaultFocusTraversalKeys (id);
4376      }
4377
4378    Set sa;
4379    Set sb;
4380    String name;
4381    switch (id)
4382      {
4383      case KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS:
4384        sa = getFocusTraversalKeys
4385          (KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS);
4386        sb = getFocusTraversalKeys
4387          (KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS);
4388        name = "forwardFocusTraversalKeys";
4389        break;
4390      case KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS:
4391        sa = getFocusTraversalKeys
4392          (KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS);
4393        sb = getFocusTraversalKeys
4394          (KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS);
4395        name = "backwardFocusTraversalKeys";
4396        break;
4397      case KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS:
4398        sa = getFocusTraversalKeys
4399          (KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS);
4400        sb = getFocusTraversalKeys
4401          (KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS);
4402        name = "upCycleFocusTraversalKeys";
4403        break;
4404      default:
4405        throw new IllegalArgumentException ();
4406      }
4407
4408    int i = keystrokes.size ();
4409    Iterator iter = keystrokes.iterator ();
4410
4411    while (--i >= 0)
4412      {
4413        Object o = iter.next ();
4414        if (!(o instanceof AWTKeyStroke)
4415            || sa.contains (o) || sb.contains (o)
4416            || ((AWTKeyStroke) o).keyCode == KeyEvent.VK_UNDEFINED)
4417          throw new IllegalArgumentException ();
4418      }
4419
4420    if (focusTraversalKeys == null)
4421      focusTraversalKeys = new Set[3];
4422
4423    keystrokes = Collections.unmodifiableSet (new HashSet (keystrokes));
4424    firePropertyChange (name, focusTraversalKeys[id], keystrokes);
4425
4426    focusTraversalKeys[id] = keystrokes;
4427  }
4428
4429  /**
4430   * Returns the set of keys for a given focus traversal action, as
4431   * defined in <code>setFocusTraversalKeys</code>.  If not set, this
4432   * is inherited from the parent component, which may have gotten it
4433   * from the KeyboardFocusManager.
4434   *
4435   * @param id one of FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS,
4436   * or UP_CYCLE_TRAVERSAL_KEYS
4437   *
4438   * @return set of traversal keys
4439   *
4440   * @throws IllegalArgumentException if id is invalid
4441   * 
4442   * @see #setFocusTraversalKeys (int, Set)
4443   * @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
4444   * @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
4445   * @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
4446   * 
4447   * @since 1.4
4448   */
4449  public Set<AWTKeyStroke> getFocusTraversalKeys (int id)
4450  {
4451    if (id != KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS &&
4452        id != KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS &&
4453        id != KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS)
4454      throw new IllegalArgumentException();
4455
4456    Set<AWTKeyStroke> s = null;
4457
4458    if (focusTraversalKeys != null)
4459      s = focusTraversalKeys[id];
4460
4461    if (s == null && parent != null)
4462      s = parent.getFocusTraversalKeys (id);
4463
4464    return s == null ? (KeyboardFocusManager.getCurrentKeyboardFocusManager()
4465                        .getDefaultFocusTraversalKeys(id)) : s;
4466  }
4467
4468  /**
4469   * Tests whether the focus traversal keys for a given action are explicitly
4470   * set or inherited.
4471   *
4472   * @param id one of FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS,
4473   * or UP_CYCLE_TRAVERSAL_KEYS
4474   * @return true if that set is explicitly specified
4475   * @throws IllegalArgumentException if id is invalid
4476   * @see #getFocusTraversalKeys (int)
4477   * @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
4478   * @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
4479   * @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
4480   * @since 1.4
4481   */
4482  public boolean areFocusTraversalKeysSet (int id)
4483  {
4484    if (id != KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS &&
4485        id != KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS &&
4486        id != KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS)
4487      throw new IllegalArgumentException ();
4488
4489    return focusTraversalKeys != null && focusTraversalKeys[id] != null;
4490  }
4491
4492  /**
4493   * Enable or disable focus traversal keys on this Component.  If
4494   * they are, then the keyboard focus manager consumes and acts on
4495   * key press and release events that trigger focus traversal, and
4496   * discards the corresponding key typed events.  If focus traversal
4497   * keys are disabled, then all key events that would otherwise
4498   * trigger focus traversal are sent to this Component.
4499   *
4500   * @param focusTraversalKeysEnabled the new value of the flag
4501   * @see #getFocusTraversalKeysEnabled ()
4502   * @see #setFocusTraversalKeys (int, Set)
4503   * @see #getFocusTraversalKeys (int)
4504   * @since 1.4
4505   */
4506  public void setFocusTraversalKeysEnabled (boolean focusTraversalKeysEnabled)
4507  {
4508    firePropertyChange ("focusTraversalKeysEnabled",
4509                        this.focusTraversalKeysEnabled,
4510                        focusTraversalKeysEnabled);
4511    this.focusTraversalKeysEnabled = focusTraversalKeysEnabled;
4512  }
4513
4514  /**
4515   * Check whether or not focus traversal keys are enabled on this
4516   * Component.  If they are, then the keyboard focus manager consumes
4517   * and acts on key press and release events that trigger focus
4518   * traversal, and discards the corresponding key typed events.  If
4519   * focus traversal keys are disabled, then all key events that would
4520   * otherwise trigger focus traversal are sent to this Component.
4521   *
4522   * @return true if focus traversal keys are enabled
4523   * @see #setFocusTraversalKeysEnabled (boolean)
4524   * @see #setFocusTraversalKeys (int, Set)
4525   * @see #getFocusTraversalKeys (int)
4526   * @since 1.4
4527   */
4528  public boolean getFocusTraversalKeysEnabled ()
4529  {
4530    return focusTraversalKeysEnabled;
4531  }
4532
4533  /**
4534   * Request that this Component be given the keyboard input focus and
4535   * that its top-level ancestor become the focused Window.
4536   *
4537   * For the request to be granted, the Component must be focusable,
4538   * displayable and showing and the top-level Window to which it
4539   * belongs must be focusable.  If the request is initially denied on
4540   * the basis that the top-level Window is not focusable, the request
4541   * will be remembered and granted when the Window does become
4542   * focused.
4543   *
4544   * Never assume that this Component is the focus owner until it
4545   * receives a FOCUS_GAINED event.
4546   *
4547   * The behaviour of this method is platform-dependent.
4548   * {@link #requestFocusInWindow()} should be used instead.
4549   *
4550   * @see #requestFocusInWindow ()
4551   * @see FocusEvent
4552   * @see #addFocusListener (FocusListener)
4553   * @see #isFocusable ()
4554   * @see #isDisplayable ()
4555   * @see KeyboardFocusManager#clearGlobalFocusOwner ()
4556   */
4557  public void requestFocus ()
4558  {
4559    requestFocusImpl(false, true);
4560  }
4561
4562  /**
4563   * Request that this Component be given the keyboard input focus and
4564   * that its top-level ancestor become the focused Window.
4565   *
4566   * For the request to be granted, the Component must be focusable,
4567   * displayable and showing and the top-level Window to which it
4568   * belongs must be focusable.  If the request is initially denied on
4569   * the basis that the top-level Window is not focusable, the request
4570   * will be remembered and granted when the Window does become
4571   * focused.
4572   *
4573   * Never assume that this Component is the focus owner until it
4574   * receives a FOCUS_GAINED event.
4575   *
4576   * The behaviour of this method is platform-dependent.
4577   * {@link #requestFocusInWindow()} should be used instead.
4578   *
4579   * If the return value is false, the request is guaranteed to fail.
4580   * If the return value is true, the request will succeed unless it
4581   * is vetoed or something in the native windowing system intervenes,
4582   * preventing this Component's top-level ancestor from becoming
4583   * focused.  This method is meant to be called by derived
4584   * lightweight Components that want to avoid unnecessary repainting
4585   * when they know a given focus transfer need only be temporary.
4586   *
4587   * @param temporary true if the focus request is temporary
4588   * @return true if the request has a chance of success
4589   * @see #requestFocusInWindow ()
4590   * @see FocusEvent
4591   * @see #addFocusListener (FocusListener)
4592   * @see #isFocusable ()
4593   * @see #isDisplayable ()
4594   * @see KeyboardFocusManager#clearGlobalFocusOwner ()
4595   * @since 1.4
4596   */
4597  protected boolean requestFocus (boolean temporary)
4598  {
4599    return requestFocusImpl(temporary, true);
4600  }
4601
4602  /**
4603   * Request that this component be given the keyboard input focus, if
4604   * its top-level ancestor is the currently focused Window.  A
4605   * <code>FOCUS_GAINED</code> event will be fired if and only if this
4606   * request is successful. To be successful, the component must be
4607   * displayable, showing, and focusable, and its ancestor top-level
4608   * Window must be focused.
4609   *
4610   * If the return value is false, the request is guaranteed to fail.
4611   * If the return value is true, the request will succeed unless it
4612   * is vetoed or something in the native windowing system intervenes,
4613   * preventing this Component's top-level ancestor from becoming
4614   * focused.
4615   *
4616   * @return true if the request has a chance of success
4617   * @see #requestFocus ()
4618   * @see FocusEvent
4619   * @see #addFocusListener (FocusListener)
4620   * @see #isFocusable ()
4621   * @see #isDisplayable ()
4622   * @see KeyboardFocusManager#clearGlobalFocusOwner ()
4623   * @since 1.4
4624   */
4625  public boolean requestFocusInWindow ()
4626  {
4627    return requestFocusImpl(false, false);
4628  }
4629
4630  /**
4631   * Request that this component be given the keyboard input focus, if
4632   * its top-level ancestor is the currently focused Window.  A
4633   * <code>FOCUS_GAINED</code> event will be fired if and only if this
4634   * request is successful. To be successful, the component must be
4635   * displayable, showing, and focusable, and its ancestor top-level
4636   * Window must be focused.
4637   *
4638   * If the return value is false, the request is guaranteed to fail.
4639   * If the return value is true, the request will succeed unless it
4640   * is vetoed or something in the native windowing system intervenes,
4641   * preventing this Component's top-level ancestor from becoming
4642   * focused.  This method is meant to be called by derived
4643   * lightweight Components that want to avoid unnecessary repainting
4644   * when they know a given focus transfer need only be temporary.
4645   *
4646   * @param temporary true if the focus request is temporary
4647   * @return true if the request has a chance of success
4648   * @see #requestFocus ()
4649   * @see FocusEvent
4650   * @see #addFocusListener (FocusListener)
4651   * @see #isFocusable ()
4652   * @see #isDisplayable ()
4653   * @see KeyboardFocusManager#clearGlobalFocusOwner ()
4654   * @since 1.4
4655   */
4656  protected boolean requestFocusInWindow (boolean temporary)
4657  {
4658    return requestFocusImpl(temporary, false);
4659  }
4660
4661  /**
4662   * Helper method for all 4 requestFocus variants.
4663   *
4664   * @param temporary indicates if the focus change is temporary
4665   * @param focusWindow indicates if the window focus may be changed
4666   *
4667   * @return <code>false</code> if the request has been definitely denied,
4668   *         <code>true</code> otherwise
4669   */
4670  private boolean requestFocusImpl(boolean temporary, boolean focusWindow)
4671  {
4672    boolean retval = false;
4673 
4674    // Don't try to focus non-focusable and non-visible components.
4675    if (isFocusable() && isVisible())
4676      {
4677        ComponentPeer myPeer = peer;
4678        if (peer != null)
4679          {
4680            // Find Window ancestor and find out if we're showing while
4681            // doing this.
4682            boolean showing = true;
4683            Component window = this;
4684            while (! (window instanceof Window))
4685              {
4686                if (! window.isVisible())
4687                  showing = false;
4688                window = window.parent;
4689              }
4690            // Don't allow focus when there is no window or the window
4691            // is not focusable.
4692            if (window != null && ((Window) window).isFocusableWindow()
4693                && showing)
4694              {
4695                // Search for nearest heavy ancestor (including this
4696                // component).
4697                Component heavyweightParent = this;
4698                while (heavyweightParent.peer instanceof LightweightPeer)
4699                  heavyweightParent = heavyweightParent.parent;
4700
4701                // Don't allow focus on lightweight components without
4702                // visible heavyweight ancestor
4703                if (heavyweightParent != null && heavyweightParent.isVisible())
4704                  {
4705                    // Don't allow focus when heavyweightParent has no peer.
4706                    myPeer = heavyweightParent.peer;
4707                    if (myPeer != null)
4708                      {
4709                        // Register lightweight focus request.
4710                        if (heavyweightParent != this)
4711                          {
4712                            KeyboardFocusManager
4713                            .addLightweightFocusRequest(heavyweightParent,
4714                                                        this);
4715                          }
4716
4717                        // Try to focus the component.
4718                        long time = EventQueue.getMostRecentEventTime();
4719                        boolean success = myPeer.requestFocus(this, temporary,
4720                                                              focusWindow,
4721                                                              time);
4722                        if (! success)
4723                          {
4724                            // Dequeue key events if focus request failed.
4725                            KeyboardFocusManager kfm =
4726                              KeyboardFocusManager.getCurrentKeyboardFocusManager();
4727                            kfm.dequeueKeyEvents(time, this);
4728                          }
4729                        retval = success;
4730                      }
4731                  }
4732              }
4733          }
4734      }
4735    return retval;
4736  }
4737
4738  /**
4739   * Transfers focus to the next component in the focus traversal
4740   * order, as though this were the current focus owner.
4741   *
4742   * @see #requestFocus()
4743   * @since 1.1
4744   */
4745  public void transferFocus ()
4746  {
4747    nextFocus ();
4748  }
4749
4750  /**
4751   * Returns the root container that owns the focus cycle where this
4752   * component resides. A focus cycle root is in two cycles, one as
4753   * the ancestor, and one as the focusable element; this call always
4754   * returns the ancestor.
4755   *
4756   * @return the ancestor container that owns the focus cycle
4757   * @since 1.4
4758   */
4759  public Container getFocusCycleRootAncestor ()
4760  {
4761    Container parent = getParent ();
4762
4763    while (parent != null && !parent.isFocusCycleRoot())
4764      parent = parent.getParent ();
4765
4766    return parent;
4767  }
4768
4769  /**
4770   * Tests if the container is the ancestor of the focus cycle that
4771   * this component belongs to.
4772   *
4773   * @param c the container to test
4774   * @return true if c is the focus cycle root
4775   * @since 1.4
4776   */
4777  public boolean isFocusCycleRoot (Container c)
4778  {
4779    return c == getFocusCycleRootAncestor ();
4780  }
4781
4782  /**
4783   * AWT 1.0 focus event processor.  Transfers focus to the next
4784   * component in the focus traversal order, as though this were the
4785   * current focus owner.
4786   *
4787   * @deprecated use {@link #transferFocus ()} instead
4788   */
4789  public void nextFocus ()
4790  {
4791    // Find the nearest valid (== showing && focusable && enabled) focus
4792    // cycle root ancestor and the focused component in it.
4793    Container focusRoot = getFocusCycleRootAncestor();
4794    Component focusComp = this;
4795    while (focusRoot != null
4796           && ! (focusRoot.isShowing() && focusRoot.isFocusable()
4797                 && focusRoot.isEnabled()))
4798      {
4799        focusComp = focusRoot;
4800        focusRoot = focusComp.getFocusCycleRootAncestor();
4801      }
4802
4803    if (focusRoot != null)
4804      {
4805        // First try to get the componentBefore from the policy.
4806        FocusTraversalPolicy policy = focusRoot.getFocusTraversalPolicy();
4807        Component nextFocus = policy.getComponentAfter(focusRoot, focusComp);
4808
4809        // If this fails, then ask for the defaultComponent.
4810        if (nextFocus == null)
4811          nextFocus = policy.getDefaultComponent(focusRoot);
4812
4813        // Request focus on this component, if not null.
4814        if (nextFocus != null)
4815          nextFocus.requestFocus();
4816      }
4817  }
4818
4819  /**
4820   * Transfers focus to the previous component in the focus traversal
4821   * order, as though this were the current focus owner.
4822   *
4823   * @see #requestFocus ()
4824   * @since 1.4
4825   */
4826  public void transferFocusBackward ()
4827  {
4828    // Find the nearest valid (== showing && focusable && enabled) focus
4829    // cycle root ancestor and the focused component in it.
4830    Container focusRoot = getFocusCycleRootAncestor();
4831    Component focusComp = this;
4832    while (focusRoot != null
4833           && ! (focusRoot.isShowing() && focusRoot.isFocusable()
4834                 && focusRoot.isEnabled()))
4835      {
4836        focusComp = focusRoot;
4837        focusRoot = focusComp.getFocusCycleRootAncestor();
4838      }
4839
4840    if (focusRoot != null)
4841      {
4842        // First try to get the componentBefore from the policy.
4843        FocusTraversalPolicy policy = focusRoot.getFocusTraversalPolicy();
4844        Component nextFocus = policy.getComponentBefore(focusRoot, focusComp);
4845
4846        // If this fails, then ask for the defaultComponent.
4847        if (nextFocus == null)
4848          nextFocus = policy.getDefaultComponent(focusRoot);
4849
4850        // Request focus on this component, if not null.
4851        if (nextFocus != null)
4852          nextFocus.requestFocus();
4853      }
4854  }
4855
4856  /**
4857   * Transfers focus to the focus cycle root of this component.
4858   * However, if this is a Window, the default focus owner in the
4859   * window in the current focus cycle is focused instead.
4860   *
4861   * @see #requestFocus()
4862   * @see #isFocusCycleRoot(Container)
4863   * @since 1.4
4864   */
4865  public void transferFocusUpCycle ()
4866  {
4867    // Find the nearest focus cycle root ancestor that is itself
4868    // focusable, showing and enabled.
4869    Container focusCycleRoot = getFocusCycleRootAncestor();
4870    while (focusCycleRoot != null &&
4871           ! (focusCycleRoot.isShowing() && focusCycleRoot.isFocusable()
4872              && focusCycleRoot.isEnabled()))
4873      {
4874        focusCycleRoot = focusCycleRoot.getFocusCycleRootAncestor();
4875      }
4876
4877    KeyboardFocusManager fm =
4878      KeyboardFocusManager.getCurrentKeyboardFocusManager();
4879
4880    if (focusCycleRoot != null)
4881      {
4882        // If we found a focus cycle root, then we make this the new
4883        // focused component, and make it's focus cycle root the new
4884        // global focus cycle root. If the found root has no focus cycle
4885        // root ancestor itself, then the component will be both the focused
4886        // component and the new global focus cycle root.
4887        Container focusCycleAncestor =
4888          focusCycleRoot.getFocusCycleRootAncestor();
4889        Container globalFocusCycleRoot;
4890        if (focusCycleAncestor == null)
4891          globalFocusCycleRoot = focusCycleRoot;
4892        else
4893          globalFocusCycleRoot = focusCycleAncestor;
4894
4895        fm.setGlobalCurrentFocusCycleRoot(globalFocusCycleRoot);
4896        focusCycleRoot.requestFocus();
4897      }
4898    else
4899      {
4900        // If this component has no applicable focus cycle root, we try
4901        // find the nearest window and set this as the new global focus cycle
4902        // root and the default focus component of this window the new focused
4903        // component.
4904        Container cont;
4905        if (this instanceof Container)
4906          cont = (Container) this;
4907        else
4908          cont = getParent();
4909
4910        while (cont != null && !(cont instanceof Window))
4911          cont = cont.getParent();
4912
4913        if (cont != null)
4914          {
4915            FocusTraversalPolicy policy = cont.getFocusTraversalPolicy();
4916            Component focusComp = policy.getDefaultComponent(cont);
4917            if (focusComp != null)
4918              {
4919                fm.setGlobalCurrentFocusCycleRoot(cont);
4920                focusComp.requestFocus();
4921              }
4922          }
4923      }
4924  }
4925
4926  /**
4927   * Tests if this component is the focus owner. Use {@link
4928   * #isFocusOwner ()} instead.
4929   *
4930   * @return true if this component owns focus
4931   * @since 1.2
4932   */
4933  public boolean hasFocus ()
4934  {
4935    KeyboardFocusManager manager = KeyboardFocusManager.getCurrentKeyboardFocusManager ();
4936
4937    Component focusOwner = manager.getFocusOwner ();
4938
4939    return this == focusOwner;
4940  }
4941
4942  /**
4943   * Tests if this component is the focus owner.
4944   *
4945   * @return true if this component owns focus
4946   * @since 1.4
4947   */
4948  public boolean isFocusOwner()
4949  {
4950    return hasFocus ();
4951  }
4952
4953  /**
4954   * Adds the specified popup menu to this component.
4955   *
4956   * @param popup the popup menu to be added
4957   * 
4958   * @see #remove(MenuComponent)
4959   * 
4960   * @since 1.1
4961   */
4962  public synchronized void add(PopupMenu popup)
4963  {
4964    if (popups == null)
4965      popups = new Vector();
4966    popups.add(popup);
4967
4968    if (popup.parent != null)
4969      popup.parent.remove(popup);
4970    popup.parent = this;
4971    if (peer != null)
4972      popup.addNotify();
4973  }
4974
4975  /**
4976   * Removes the specified popup menu from this component.
4977   *
4978   * @param popup the popup menu to remove
4979   * @see #add(PopupMenu)
4980   * @since 1.1
4981   */
4982  public synchronized void remove(MenuComponent popup)
4983  {
4984    if (popups != null)
4985      popups.remove(popup);
4986  }
4987
4988  /**
4989   * Returns a debugging string representing this component. The string may
4990   * be empty but not null.
4991   *
4992   * @return a string representing this component
4993   */
4994  protected String paramString()
4995  {
4996    CPStringBuilder param = new CPStringBuilder();
4997    String name = getName();
4998    if (name != null)
4999      param.append(name).append(",");
5000    param.append(x).append(",").append(y).append(",").append(width)
5001      .append("x").append(height);
5002    if (! isValid())
5003      param.append(",invalid");
5004    if (! isVisible())
5005      param.append(",invisible");
5006    if (! isEnabled())
5007      param.append(",disabled");
5008    if (! isOpaque())
5009      param.append(",translucent");
5010    if (isDoubleBuffered())
5011      param.append(",doublebuffered");
5012    if (parent == null)
5013      param.append(",parent=null");
5014    else
5015      param.append(",parent=").append(parent.getName());
5016    return param.toString();
5017  }
5018
5019  /**
5020   * Returns a string representation of this component. This is implemented
5021   * as <code>getClass().getName() + '[' + paramString() + ']'</code>.
5022   *
5023   * @return a string representation of this component
5024   */
5025  public String toString()
5026  {
5027    return getClass().getName() + '[' + paramString() + ']';
5028  }
5029
5030  /**
5031   * Prints a listing of this component to <code>System.out</code>.
5032   *
5033   * @see #list(PrintStream)
5034   */
5035  public void list()
5036  {
5037    list(System.out, 0);
5038  }
5039
5040  /**
5041   * Prints a listing of this component to the specified print stream.
5042   *
5043   * @param out the <code>PrintStream</code> to print to
5044   */
5045  public void list(PrintStream out)
5046  {
5047    list(out, 0);
5048  }
5049
5050  /**
5051   * Prints a listing of this component to the specified print stream,
5052   * starting at the specified indentation point.
5053   *
5054   * @param out the <code>PrintStream</code> to print to
5055   * @param indent the indentation point
5056   */
5057  public void list(PrintStream out, int indent)
5058  {
5059    for (int i = 0; i < indent; ++i)
5060      out.print(' ');
5061    out.println(toString());
5062  }
5063
5064  /**
5065   * Prints a listing of this component to the specified print writer.
5066   *
5067   * @param out the <code>PrintWrinter</code> to print to
5068   * @since 1.1
5069   */
5070  public void list(PrintWriter out)
5071  {
5072    list(out, 0);
5073  }
5074
5075  /**
5076   * Prints a listing of this component to the specified print writer,
5077   * starting at the specified indentation point.
5078   *
5079   * @param out the <code>PrintWriter</code> to print to
5080   * @param indent the indentation point
5081   * @since 1.1
5082   */
5083  public void list(PrintWriter out, int indent)
5084  {
5085    for (int i = 0; i < indent; ++i)
5086      out.print(' ');
5087    out.println(toString());
5088  }
5089
5090  /**
5091   * Adds the specified property listener to this component. This is harmless
5092   * if the listener is null, but if the listener has already been registered,
5093   * it will now be registered twice. The property listener ignores inherited
5094   * properties. Recognized properties include:<br>
5095   * <ul>
5096   * <li>the font (<code>"font"</code>)</li>
5097   * <li>the background color (<code>"background"</code>)</li>
5098   * <li>the foreground color (<code>"foreground"</code>)</li>
5099   * <li>the focusability (<code>"focusable"</code>)</li>
5100   * <li>the focus key traversal enabled state
5101   *     (<code>"focusTraversalKeysEnabled"</code>)</li>
5102   * <li>the set of forward traversal keys
5103   *     (<code>"forwardFocusTraversalKeys"</code>)</li>
5104   * <li>the set of backward traversal keys
5105   *     (<code>"backwardFocusTraversalKeys"</code>)</li>
5106   * <li>the set of up-cycle traversal keys
5107   *     (<code>"upCycleFocusTraversalKeys"</code>)</li>
5108   * </ul>
5109   *
5110   * @param listener the new listener to add
5111   * @see #removePropertyChangeListener(PropertyChangeListener)
5112   * @see #getPropertyChangeListeners()
5113   * @see #addPropertyChangeListener(String, PropertyChangeListener)
5114   * @since 1.1
5115   */
5116  public void addPropertyChangeListener(PropertyChangeListener listener)
5117  {
5118    if (changeSupport == null)
5119      changeSupport = new PropertyChangeSupport(this);
5120    changeSupport.addPropertyChangeListener(listener);
5121  }
5122
5123  /**
5124   * Removes the specified property listener from the component. This is
5125   * harmless if the listener was not previously registered.
5126   *
5127   * @param listener the listener to remove
5128   * @see #addPropertyChangeListener(PropertyChangeListener)
5129   * @see #getPropertyChangeListeners()
5130   * @see #removePropertyChangeListener(String, PropertyChangeListener)
5131   * @since 1.1
5132   */
5133  public void removePropertyChangeListener(PropertyChangeListener listener)
5134  {
5135    if (changeSupport != null)
5136      changeSupport.removePropertyChangeListener(listener);
5137  }
5138
5139  /**
5140   * Returns an array of all specified listeners registered on this component.
5141   *
5142   * @return an array of listeners
5143   * @see #addPropertyChangeListener(PropertyChangeListener)
5144   * @see #removePropertyChangeListener(PropertyChangeListener)
5145   * @see #getPropertyChangeListeners(String)
5146   * @since 1.4
5147   */
5148  public PropertyChangeListener[] getPropertyChangeListeners()
5149  {
5150    return changeSupport == null ? new PropertyChangeListener[0]
5151      : changeSupport.getPropertyChangeListeners();
5152  }
5153
5154  /**
5155   * Adds the specified property listener to this component. This is harmless
5156   * if the listener is null, but if the listener has already been registered,
5157   * it will now be registered twice. The property listener ignores inherited
5158   * properties. The listener is keyed to a single property. Recognized
5159   * properties include:<br>
5160   * <ul>
5161   * <li>the font (<code>"font"</code>)</li>
5162   * <li>the background color (<code>"background"</code>)</li>
5163   * <li>the foreground color (<code>"foreground"</code>)</li>
5164   * <li>the focusability (<code>"focusable"</code>)</li>
5165   * <li>the focus key traversal enabled state
5166   *     (<code>"focusTraversalKeysEnabled"</code>)</li>
5167   * <li>the set of forward traversal keys
5168   *     (<code>"forwardFocusTraversalKeys"</code>)</li>
5169p   * <li>the set of backward traversal keys
5170   *     (<code>"backwardFocusTraversalKeys"</code>)</li>
5171   * <li>the set of up-cycle traversal keys
5172   *     (<code>"upCycleFocusTraversalKeys"</code>)</li>
5173   * </ul>
5174   *
5175   * @param propertyName the property name to filter on
5176   * @param listener the new listener to add
5177   * @see #removePropertyChangeListener(String, PropertyChangeListener)
5178   * @see #getPropertyChangeListeners(String)
5179   * @see #addPropertyChangeListener(PropertyChangeListener)
5180   * @since 1.1
5181   */
5182  public void addPropertyChangeListener(String propertyName,
5183                                        PropertyChangeListener listener)
5184  {
5185    if (changeSupport == null)
5186      changeSupport = new PropertyChangeSupport(this);
5187    changeSupport.addPropertyChangeListener(propertyName, listener);
5188  }
5189
5190  /**
5191   * Removes the specified property listener on a particular property from
5192   * the component. This is harmless if the listener was not previously
5193   * registered.
5194   *
5195   * @param propertyName the property name to filter on
5196   * @param listener the listener to remove
5197   * @see #addPropertyChangeListener(String, PropertyChangeListener)
5198   * @see #getPropertyChangeListeners(String)
5199   * @see #removePropertyChangeListener(PropertyChangeListener)
5200   * @since 1.1
5201   */
5202  public void removePropertyChangeListener(String propertyName,
5203                                           PropertyChangeListener listener)
5204  {
5205    if (changeSupport != null)
5206      changeSupport.removePropertyChangeListener(propertyName, listener);
5207  }
5208
5209  /**
5210   * Returns an array of all specified listeners on the named property that
5211   * are registered on this component.
5212   *
5213   * @return an array of listeners
5214   * @see #addPropertyChangeListener(String, PropertyChangeListener)
5215   * @see #removePropertyChangeListener(String, PropertyChangeListener)
5216   * @see #getPropertyChangeListeners()
5217   * @since 1.4
5218   */
5219  public PropertyChangeListener[] getPropertyChangeListeners(String property)
5220  {
5221    return changeSupport == null ? new PropertyChangeListener[0]
5222      : changeSupport.getPropertyChangeListeners(property);
5223  }
5224
5225  /**
5226   * Report a change in a bound property to any registered property listeners.
5227   *
5228   * @param propertyName the property that changed
5229   * @param oldValue the old property value
5230   * @param newValue the new property value
5231   */
5232  protected void firePropertyChange(String propertyName, Object oldValue,
5233                                    Object newValue)
5234  {
5235    if (changeSupport != null)
5236      changeSupport.firePropertyChange(propertyName, oldValue, newValue);  
5237  }
5238
5239  /**
5240   * Report a change in a bound property to any registered property listeners.
5241   *
5242   * @param propertyName the property that changed
5243   * @param oldValue the old property value
5244   * @param newValue the new property value
5245   */
5246  protected void firePropertyChange(String propertyName, boolean oldValue,
5247                                    boolean newValue)
5248  {
5249    if (changeSupport != null)
5250      changeSupport.firePropertyChange(propertyName, oldValue, newValue);
5251  }
5252
5253  /**
5254   * Report a change in a bound property to any registered property listeners.
5255   *
5256   * @param propertyName the property that changed
5257   * @param oldValue the old property value
5258   * @param newValue the new property value
5259   */
5260  protected void firePropertyChange(String propertyName, int oldValue,
5261                                    int newValue)
5262  {
5263    if (changeSupport != null)
5264      changeSupport.firePropertyChange(propertyName, oldValue, newValue);
5265  }
5266
5267  /**
5268   * Report a change in a bound property to any registered property listeners.
5269   *
5270   * @param propertyName the property that changed
5271   * @param oldValue the old property value
5272   * @param newValue the new property value
5273   *
5274   * @since 1.5
5275   */
5276  public void firePropertyChange(String propertyName, byte oldValue,
5277                                    byte newValue)
5278  {
5279    if (changeSupport != null)
5280      changeSupport.firePropertyChange(propertyName, new Byte(oldValue),
5281                                       new Byte(newValue));
5282  }
5283
5284  /**
5285   * Report a change in a bound property to any registered property listeners.
5286   *
5287   * @param propertyName the property that changed
5288   * @param oldValue the old property value
5289   * @param newValue the new property value
5290   *
5291   * @since 1.5
5292   */
5293  public void firePropertyChange(String propertyName, char oldValue,
5294                                    char newValue)
5295  {
5296    if (changeSupport != null)
5297      changeSupport.firePropertyChange(propertyName, new Character(oldValue),
5298                                       new Character(newValue));
5299  }
5300
5301  /**
5302   * Report a change in a bound property to any registered property listeners.
5303   *
5304   * @param propertyName the property that changed
5305   * @param oldValue the old property value
5306   * @param newValue the new property value
5307   *
5308   * @since 1.5
5309   */
5310  public void firePropertyChange(String propertyName, short oldValue,
5311                                    short newValue)
5312  {
5313    if (changeSupport != null)
5314      changeSupport.firePropertyChange(propertyName, new Short(oldValue),
5315                                       new Short(newValue));
5316  }
5317
5318  /**
5319   * Report a change in a bound property to any registered property listeners.
5320   *
5321   * @param propertyName the property that changed
5322   * @param oldValue the old property value
5323   * @param newValue the new property value
5324   *
5325   * @since 1.5
5326   */
5327  public void firePropertyChange(String propertyName, long oldValue,
5328                                    long newValue)
5329  {
5330    if (changeSupport != null)
5331      changeSupport.firePropertyChange(propertyName, new Long(oldValue),
5332                                       new Long(newValue));
5333  }
5334
5335  /**
5336   * Report a change in a bound property to any registered property listeners.
5337   *
5338   * @param propertyName the property that changed
5339   * @param oldValue the old property value
5340   * @param newValue the new property value
5341   *
5342   * @since 1.5
5343   */
5344  public void firePropertyChange(String propertyName, float oldValue,
5345                                    float newValue)
5346  {
5347    if (changeSupport != null)
5348      changeSupport.firePropertyChange(propertyName, new Float(oldValue),
5349                                       new Float(newValue));
5350  }
5351
5352
5353  /**
5354   * Report a change in a bound property to any registered property listeners.
5355   *
5356   * @param propertyName the property that changed
5357   * @param oldValue the old property value
5358   * @param newValue the new property value
5359   *
5360   * @since 1.5
5361   */
5362  public void firePropertyChange(String propertyName, double oldValue,
5363                                 double newValue)
5364  {
5365    if (changeSupport != null)
5366      changeSupport.firePropertyChange(propertyName, new Double(oldValue),
5367                                       new Double(newValue));
5368  }
5369
5370  /**
5371   * Sets the text layout orientation of this component. New components default
5372   * to UNKNOWN (which behaves like LEFT_TO_RIGHT). This method affects only
5373   * the current component, while
5374   * {@link #applyComponentOrientation(ComponentOrientation)} affects the
5375   * entire hierarchy.
5376   *
5377   * @param o the new orientation (<code>null</code> is accepted)
5378   * @see #getComponentOrientation()
5379   */
5380  public void setComponentOrientation(ComponentOrientation o)
5381  {
5382 
5383    ComponentOrientation oldOrientation = componentOrientation;
5384    componentOrientation = o;
5385    firePropertyChange("componentOrientation", oldOrientation, o);
5386  }
5387
5388  /**
5389   * Determines the text layout orientation used by this component.
5390   *
5391   * @return the component orientation (this can be <code>null</code>)
5392   * @see #setComponentOrientation(ComponentOrientation)
5393   */
5394  public ComponentOrientation getComponentOrientation()
5395  {
5396    return componentOrientation;
5397  }
5398
5399  /**
5400   * Sets the text layout orientation of this component. New components default
5401   * to UNKNOWN (which behaves like LEFT_TO_RIGHT). This method affects the
5402   * entire hierarchy, while
5403   * {@link #setComponentOrientation(ComponentOrientation)} affects only the
5404   * current component.
5405   *
5406   * @param o the new orientation
5407   * @throws NullPointerException if o is null
5408   * @see #getComponentOrientation()
5409   * @since 1.4
5410   */
5411  public void applyComponentOrientation(ComponentOrientation o)
5412  {
5413    setComponentOrientation(o);
5414  }
5415
5416  /**
5417   * Returns the accessibility framework context of this class. Component is
5418   * not accessible, so the default implementation returns null. Subclasses
5419   * must override this behavior, and return an appropriate subclass of
5420   * {@link AccessibleAWTComponent}.
5421   *
5422   * @return the accessibility context
5423   */
5424  public AccessibleContext getAccessibleContext()
5425  {
5426    return null;
5427  }
5428
5429
5430  // Helper methods; some are package visible for use by subclasses.
5431
5432  /**
5433   * Subclasses should override this to return unique component names like
5434   * "menuitem0".
5435   *
5436   * @return the generated name for this component
5437   */
5438  String generateName()
5439  {
5440    // Component is abstract.
5441    return null;
5442  }
5443
5444  /**
5445   * Sets the peer for this component.
5446   *
5447   * @param peer the new peer
5448   */
5449  final void setPeer(ComponentPeer peer)
5450  {
5451    this.peer = peer;
5452  }
5453
5454  /**
5455   * Translate an AWT 1.1 event ({@link AWTEvent}) into an AWT 1.0
5456   * event ({@link Event}).
5457   *
5458   * @param e an AWT 1.1 event to translate
5459   *
5460   * @return an AWT 1.0 event representing e
5461   */
5462  static Event translateEvent (AWTEvent e)
5463  {
5464    Object target = e.getSource ();
5465    Event translated = null;
5466    
5467    if (e instanceof WindowEvent)
5468      {
5469        WindowEvent we = (WindowEvent) e;
5470        int id = we.id;
5471        int newId = 0;
5472        
5473        switch (id)
5474          {
5475          case WindowEvent.WINDOW_DEICONIFIED:
5476            newId = Event.WINDOW_DEICONIFY;
5477            break;
5478          case WindowEvent.WINDOW_CLOSED:
5479          case WindowEvent.WINDOW_CLOSING:
5480            newId = Event.WINDOW_DESTROY;
5481            break;
5482          case WindowEvent.WINDOW_ICONIFIED:
5483            newId = Event.WINDOW_ICONIFY;
5484            break;
5485          case WindowEvent.WINDOW_GAINED_FOCUS:
5486            newId = Event.GOT_FOCUS;
5487            break;
5488          case WindowEvent.WINDOW_LOST_FOCUS:
5489            newId = Event.LOST_FOCUS;
5490            break;
5491          default:
5492            return null;
5493          }
5494
5495        translated = new Event(target, 0, newId, 0, 0, 0, 0);
5496      }
5497    else if (e instanceof InputEvent)
5498      {
5499        InputEvent ie = (InputEvent) e;
5500        long when = ie.getWhen ();
5501
5502        int oldID = 0;
5503        int id = e.getID ();
5504
5505        int oldMods = 0;
5506        int mods = ie.getModifiersEx ();
5507
5508        if ((mods & InputEvent.BUTTON2_DOWN_MASK) != 0)
5509          oldMods |= Event.META_MASK;
5510        else if ((mods & InputEvent.BUTTON3_DOWN_MASK) != 0)
5511          oldMods |= Event.ALT_MASK;
5512
5513        if ((mods & InputEvent.SHIFT_DOWN_MASK) != 0)
5514          oldMods |= Event.SHIFT_MASK;
5515
5516        if ((mods & InputEvent.CTRL_DOWN_MASK) != 0)
5517          oldMods |= Event.CTRL_MASK;
5518
5519        if ((mods & InputEvent.META_DOWN_MASK) != 0)
5520          oldMods |= Event.META_MASK;
5521
5522        if ((mods & InputEvent.ALT_DOWN_MASK) != 0)
5523          oldMods |= Event.ALT_MASK;
5524
5525        if (e instanceof MouseEvent && !ignoreOldMouseEvents())
5526          {
5527            if (id == MouseEvent.MOUSE_PRESSED)
5528              oldID = Event.MOUSE_DOWN;
5529            else if (id == MouseEvent.MOUSE_RELEASED)
5530              oldID = Event.MOUSE_UP;
5531            else if (id == MouseEvent.MOUSE_MOVED)
5532              oldID = Event.MOUSE_MOVE;
5533            else if (id == MouseEvent.MOUSE_DRAGGED)
5534              oldID = Event.MOUSE_DRAG;
5535            else if (id == MouseEvent.MOUSE_ENTERED)
5536              oldID = Event.MOUSE_ENTER;
5537            else if (id == MouseEvent.MOUSE_EXITED)
5538              oldID = Event.MOUSE_EXIT;
5539            else
5540              // No analogous AWT 1.0 mouse event.
5541              return null;
5542
5543            MouseEvent me = (MouseEvent) e;
5544
5545            translated = new Event (target, when, oldID,
5546                                    me.getX (), me.getY (), 0, oldMods);
5547          }
5548        else if (e instanceof KeyEvent)
5549          {
5550            if (id == KeyEvent.KEY_PRESSED)
5551              oldID = Event.KEY_PRESS;
5552            else if (e.getID () == KeyEvent.KEY_RELEASED)
5553              oldID = Event.KEY_RELEASE;
5554            else
5555              // No analogous AWT 1.0 key event.
5556              return null;
5557
5558            int oldKey = 0;
5559            int newKey = ((KeyEvent) e).getKeyCode ();
5560            switch (newKey)
5561              {
5562              case KeyEvent.VK_BACK_SPACE:
5563                oldKey = Event.BACK_SPACE;
5564                break;
5565              case KeyEvent.VK_CAPS_LOCK:
5566                oldKey = Event.CAPS_LOCK;
5567                break;
5568              case KeyEvent.VK_DELETE:
5569                oldKey = Event.DELETE;
5570                break;
5571              case KeyEvent.VK_DOWN:
5572              case KeyEvent.VK_KP_DOWN:
5573                oldKey = Event.DOWN;
5574                break;
5575              case KeyEvent.VK_END:
5576                oldKey = Event.END;
5577                break;
5578              case KeyEvent.VK_ENTER:
5579                oldKey = Event.ENTER;
5580                break;
5581              case KeyEvent.VK_ESCAPE:
5582                oldKey = Event.ESCAPE;
5583                break;
5584              case KeyEvent.VK_F1:
5585                oldKey = Event.F1;
5586                break;
5587              case KeyEvent.VK_F10:
5588                oldKey = Event.F10;
5589                break;
5590              case KeyEvent.VK_F11:
5591                oldKey = Event.F11;
5592                break;
5593              case KeyEvent.VK_F12:
5594                oldKey = Event.F12;
5595                break;
5596              case KeyEvent.VK_F2:
5597                oldKey = Event.F2;
5598                break;
5599              case KeyEvent.VK_F3:
5600                oldKey = Event.F3;
5601                break;
5602              case KeyEvent.VK_F4:
5603                oldKey = Event.F4;
5604                break;
5605              case KeyEvent.VK_F5:
5606                oldKey = Event.F5;
5607                break;
5608              case KeyEvent.VK_F6:
5609                oldKey = Event.F6;
5610                break;
5611              case KeyEvent.VK_F7:
5612                oldKey = Event.F7;
5613                break;
5614              case KeyEvent.VK_F8:
5615                oldKey = Event.F8;
5616                break;
5617              case KeyEvent.VK_F9:
5618                oldKey = Event.F9;
5619                break;
5620              case KeyEvent.VK_HOME:
5621                oldKey = Event.HOME;
5622                break;
5623              case KeyEvent.VK_INSERT:
5624                oldKey = Event.INSERT;
5625                break;
5626              case KeyEvent.VK_LEFT:
5627              case KeyEvent.VK_KP_LEFT:
5628                oldKey = Event.LEFT;
5629                break;
5630              case KeyEvent.VK_NUM_LOCK:
5631                oldKey = Event.NUM_LOCK;
5632                break;
5633              case KeyEvent.VK_PAUSE:
5634                oldKey = Event.PAUSE;
5635                break;
5636              case KeyEvent.VK_PAGE_DOWN:
5637                oldKey = Event.PGDN;
5638                break;
5639              case KeyEvent.VK_PAGE_UP:
5640                oldKey = Event.PGUP;
5641                break;
5642              case KeyEvent.VK_PRINTSCREEN:
5643                oldKey = Event.PRINT_SCREEN;
5644                break;
5645              case KeyEvent.VK_RIGHT:
5646              case KeyEvent.VK_KP_RIGHT:
5647                oldKey = Event.RIGHT;
5648                break;
5649              case KeyEvent.VK_SCROLL_LOCK:
5650                oldKey = Event.SCROLL_LOCK;
5651                break;
5652              case KeyEvent.VK_TAB:
5653                oldKey = Event.TAB;
5654                break;
5655              case KeyEvent.VK_UP:
5656              case KeyEvent.VK_KP_UP:
5657                oldKey = Event.UP;
5658                break;
5659              default:
5660                oldKey = ((KeyEvent) e).getKeyChar();
5661              }
5662
5663            translated = new Event (target, when, oldID,
5664                                    0, 0, oldKey, oldMods);
5665          }
5666      }
5667    else if (e instanceof AdjustmentEvent)
5668      {
5669        AdjustmentEvent ae = (AdjustmentEvent) e;
5670        int type = ae.getAdjustmentType();
5671        int oldType;
5672        if (type == AdjustmentEvent.BLOCK_DECREMENT)
5673          oldType = Event.SCROLL_PAGE_UP;
5674        else if (type == AdjustmentEvent.BLOCK_INCREMENT)
5675          oldType = Event.SCROLL_PAGE_DOWN;
5676        else if (type == AdjustmentEvent.TRACK)
5677          oldType = Event.SCROLL_ABSOLUTE;
5678        else if (type == AdjustmentEvent.UNIT_DECREMENT)
5679          oldType = Event.SCROLL_LINE_UP;
5680        else if (type == AdjustmentEvent.UNIT_INCREMENT)
5681          oldType = Event.SCROLL_LINE_DOWN;
5682        else
5683          oldType = type;
5684        translated = new Event(target, oldType, new Integer(ae.getValue()));
5685      }
5686    else if (e instanceof ActionEvent)
5687      translated = new Event (target, Event.ACTION_EVENT,
5688                              ((ActionEvent) e).getActionCommand ());
5689
5690    return translated;
5691  }
5692
5693  /**
5694   * Implementation of dispatchEvent. Allows trusted package classes
5695   * to dispatch additional events first.  This implementation first
5696   * translates <code>e</code> to an AWT 1.0 event and sends the
5697   * result to {@link #postEvent}.  If the AWT 1.0 event is not
5698   * handled, and events of type <code>e</code> are enabled for this
5699   * component, e is passed on to {@link #processEvent}.
5700   *
5701   * @param e the event to dispatch
5702   */
5703  void dispatchEventImpl(AWTEvent e)
5704  {
5705    // Update the component's knowledge about the size.
5706    // Important: Please look at the big comment in ComponentReshapeEvent
5707    // to learn why we did it this way. If you change this code, make
5708    // sure that the peer->AWT bounds update still works.
5709    // (for instance: http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29448 )
5710    if (e instanceof ComponentReshapeEvent)
5711      {
5712        ComponentReshapeEvent reshape = (ComponentReshapeEvent) e;
5713        x = reshape.x;
5714        y = reshape.y;
5715        width = reshape.width;
5716        height = reshape.height;
5717        return;
5718      }
5719
5720    // Retarget focus events before dispatching it to the KeyboardFocusManager
5721    // in order to handle lightweight components properly.
5722    boolean dispatched = false;
5723    if (! e.isFocusManagerEvent)
5724      {
5725        e = KeyboardFocusManager.retargetFocusEvent(e);
5726        dispatched = KeyboardFocusManager.getCurrentKeyboardFocusManager()
5727                                          .dispatchEvent(e);
5728      }
5729
5730    if (! dispatched)
5731      {
5732        // Give toolkit a chance to dispatch the event
5733        // to globally registered listeners.
5734        Toolkit.getDefaultToolkit().globalDispatchEvent(e);
5735
5736        if (newEventsOnly)
5737          {
5738            if (eventTypeEnabled(e.id))
5739              processEvent(e);
5740          }
5741        else
5742          {
5743            Event oldEvent = translateEvent(e);
5744            if (oldEvent != null)
5745              postEvent (oldEvent);
5746          }
5747        if (peer != null)
5748          peer.handleEvent(e);
5749      }
5750  }
5751
5752  /**
5753   * Tells whether or not an event type is enabled.
5754   */
5755  boolean eventTypeEnabled (int type)
5756  {
5757    if (type > AWTEvent.RESERVED_ID_MAX)
5758      return true;
5759
5760    switch (type)
5761      {
5762      case HierarchyEvent.HIERARCHY_CHANGED:
5763        return (hierarchyListener != null 
5764            || (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0);
5765        
5766      case HierarchyEvent.ANCESTOR_MOVED:
5767      case HierarchyEvent.ANCESTOR_RESIZED:
5768        return (hierarchyBoundsListener != null 
5769            || (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0);
5770        
5771      case ComponentEvent.COMPONENT_HIDDEN:
5772      case ComponentEvent.COMPONENT_MOVED:
5773      case ComponentEvent.COMPONENT_RESIZED:
5774      case ComponentEvent.COMPONENT_SHOWN:
5775        return (componentListener != null
5776                || (eventMask & AWTEvent.COMPONENT_EVENT_MASK) != 0);
5777
5778      case KeyEvent.KEY_PRESSED:
5779      case KeyEvent.KEY_RELEASED:
5780      case KeyEvent.KEY_TYPED:
5781        return (keyListener != null
5782                || (eventMask & AWTEvent.KEY_EVENT_MASK) != 0);
5783
5784      case MouseEvent.MOUSE_CLICKED:
5785      case MouseEvent.MOUSE_ENTERED:
5786      case MouseEvent.MOUSE_EXITED:
5787      case MouseEvent.MOUSE_PRESSED:
5788      case MouseEvent.MOUSE_RELEASED:
5789        return (mouseListener != null
5790                || (eventMask & AWTEvent.MOUSE_EVENT_MASK) != 0);
5791      case MouseEvent.MOUSE_MOVED:
5792      case MouseEvent.MOUSE_DRAGGED:
5793        return (mouseMotionListener != null
5794                || (eventMask & AWTEvent.MOUSE_MOTION_EVENT_MASK) != 0);
5795      case MouseEvent.MOUSE_WHEEL:
5796        return (mouseWheelListener != null
5797                || (eventMask & AWTEvent.MOUSE_WHEEL_EVENT_MASK) != 0);
5798        
5799      case FocusEvent.FOCUS_GAINED:
5800      case FocusEvent.FOCUS_LOST:
5801        return (focusListener != null
5802                || (eventMask & AWTEvent.FOCUS_EVENT_MASK) != 0);
5803
5804      case InputMethodEvent.INPUT_METHOD_TEXT_CHANGED:
5805      case InputMethodEvent.CARET_POSITION_CHANGED:
5806        return (inputMethodListener != null
5807                || (eventMask & AWTEvent.INPUT_METHOD_EVENT_MASK) != 0);
5808        
5809      case PaintEvent.PAINT:
5810      case PaintEvent.UPDATE:
5811        return (eventMask & AWTEvent.PAINT_EVENT_MASK) != 0;
5812        
5813      default:
5814        return false;
5815      }
5816  }
5817
5818  /**
5819   * Returns <code>true</code> when this component and all of its ancestors
5820   * are visible, <code>false</code> otherwise.
5821   *
5822   * @return <code>true</code> when this component and all of its ancestors
5823   *         are visible, <code>false</code> otherwise
5824   */
5825  boolean isHierarchyVisible()
5826  {
5827    boolean visible = isVisible();
5828    Component comp = parent;
5829    while (comp != null && visible)
5830      {
5831        comp = comp.parent;
5832        if (comp != null)
5833          visible = visible && comp.isVisible();
5834      }
5835    return visible;
5836  }
5837
5838  /**
5839   * Returns the mouse pointer position relative to this Component's
5840   * top-left corner.
5841   *
5842   * @return relative mouse pointer position
5843   *
5844   * @throws HeadlessException if in a headless environment
5845   */
5846  public Point getMousePosition() throws HeadlessException
5847  {
5848    return getMousePositionHelper(true);
5849  }
5850
5851  Point getMousePositionHelper(boolean allowChildren) throws HeadlessException
5852  {
5853    if (GraphicsEnvironment.isHeadless())
5854      throw new HeadlessException("can't get mouse position"
5855                                  + " in headless environment");
5856    if (!isShowing())
5857      return null;
5858
5859    Component parent = this;
5860    int windowRelativeXOffset = 0;
5861    int windowRelativeYOffset = 0;
5862    while (parent != null && !(parent instanceof Window))
5863      {
5864        windowRelativeXOffset += parent.getX();
5865        windowRelativeYOffset += parent.getY();
5866        parent = parent.getParent();
5867      }
5868    if (parent == null)
5869      return null;
5870
5871    Window window = (Window) parent;
5872    if (!Toolkit.getDefaultToolkit()
5873        .getMouseInfoPeer().isWindowUnderMouse(window))
5874      return null;
5875
5876    PointerInfo info = MouseInfo.getPointerInfo();
5877    Point mouseLocation = info.getLocation();
5878    Point windowLocation = window.getLocationOnScreen();
5879
5880    int x = mouseLocation.x - windowLocation.x;
5881    int y = mouseLocation.y - windowLocation.y;
5882
5883    if (!mouseOverComponent(window.getComponentAt(x, y), allowChildren))
5884      return null;
5885
5886    return new Point(x - windowRelativeXOffset, y - windowRelativeYOffset);
5887  }
5888
5889  boolean mouseOverComponent(Component component, boolean allowChildren)
5890  {
5891    return component == this;
5892  }
5893
5894  /**
5895   * This method is used to implement transferFocus(). CHILD is the child
5896   * making the request. This is overridden by Container; when called for an
5897   * ordinary component there is no child and so we always return null.
5898   *
5899   * FIXME: is this still needed, in light of focus traversal policies?
5900   *
5901   * @param child the component making the request
5902   * @return the next component to focus on
5903   */
5904  Component findNextFocusComponent(Component child)
5905  {
5906    return null;
5907  }
5908
5909  /**
5910   * Deserializes this component. This regenerates all serializable listeners
5911   * which were registered originally.
5912   *
5913   * @param s the stream to read from
5914   * @throws ClassNotFoundException if deserialization fails
5915   * @throws IOException if the stream fails
5916   */
5917  private void readObject(ObjectInputStream s)
5918    throws ClassNotFoundException, IOException
5919  {
5920    s.defaultReadObject();
5921    String key = (String) s.readObject();
5922    while (key != null)
5923      {
5924        Object listener = s.readObject();
5925        if ("componentL".equals(key))
5926          addComponentListener((ComponentListener) listener);
5927        else if ("focusL".equals(key))
5928          addFocusListener((FocusListener) listener);
5929        else if ("keyL".equals(key))
5930          addKeyListener((KeyListener) listener);
5931        else if ("mouseL".equals(key))
5932          addMouseListener((MouseListener) listener);
5933        else if ("mouseMotionL".equals(key))
5934          addMouseMotionListener((MouseMotionListener) listener);
5935        else if ("inputMethodL".equals(key))
5936          addInputMethodListener((InputMethodListener) listener);
5937        else if ("hierarchyL".equals(key))
5938          addHierarchyListener((HierarchyListener) listener);
5939        else if ("hierarchyBoundsL".equals(key))
5940          addHierarchyBoundsListener((HierarchyBoundsListener) listener);
5941        else if ("mouseWheelL".equals(key))
5942          addMouseWheelListener((MouseWheelListener) listener);
5943        key = (String) s.readObject();
5944      }
5945  }
5946
5947  /**
5948   * Serializes this component. This ignores all listeners which do not
5949   * implement Serializable, but includes those that do.
5950   *
5951   * @param s the stream to write to
5952   * @throws IOException if the stream fails
5953   */
5954  private void writeObject(ObjectOutputStream s) throws IOException
5955  {
5956    s.defaultWriteObject();
5957    AWTEventMulticaster.save(s, "componentL", componentListener);
5958    AWTEventMulticaster.save(s, "focusL", focusListener);
5959    AWTEventMulticaster.save(s, "keyL", keyListener);
5960    AWTEventMulticaster.save(s, "mouseL", mouseListener);
5961    AWTEventMulticaster.save(s, "mouseMotionL", mouseMotionListener);
5962    AWTEventMulticaster.save(s, "inputMethodL", inputMethodListener);
5963    AWTEventMulticaster.save(s, "hierarchyL", hierarchyListener);
5964    AWTEventMulticaster.save(s, "hierarchyBoundsL", hierarchyBoundsListener);
5965    AWTEventMulticaster.save(s, "mouseWheelL", mouseWheelListener);
5966    s.writeObject(null);
5967  }
5968
5969  
5970  // Nested classes.
5971  
5972  /**
5973   * This class fixes the bounds for a Heavyweight component that
5974   * is placed inside a Lightweight container. When the lightweight is
5975   * moved or resized, setBounds for the lightweight peer does nothing.
5976   * Therefore, it was never moved on the screen. This class is 
5977   * attached to the lightweight, and it adjusts the position and size
5978   * of the peer when notified.
5979   * This is the same for show and hide.
5980   */
5981  class HeavyweightInLightweightListener
5982      implements ComponentListener
5983  {
5984    
5985    /**
5986     * Constructor. Adds component listener to lightweight parent.
5987     * 
5988     * @param parent - the lightweight container.
5989     */
5990    public HeavyweightInLightweightListener(Container parent)
5991    {
5992      parent.addComponentListener(this);
5993    }
5994    
5995    /**
5996     * This method is called when the component is resized.
5997     * 
5998     * @param event the <code>ComponentEvent</code> indicating the resize
5999     */
6000    public void componentResized(ComponentEvent event)
6001    {
6002      // Nothing to do here, componentMoved will be called.
6003    }
6004
6005    /**
6006     * This method is called when the component is moved.
6007     * 
6008     * @param event the <code>ComponentEvent</code> indicating the move
6009     */
6010    public void componentMoved(ComponentEvent event)
6011    {
6012      if (peer != null)
6013        peer.setBounds(x, y, width, height);
6014    }
6015
6016    /**
6017     * This method is called when the component is made visible.
6018     * 
6019     * @param event the <code>ComponentEvent</code> indicating the visibility
6020     */
6021    public void componentShown(ComponentEvent event)
6022    {
6023      if (isShowing())
6024        peer.show();
6025    }
6026
6027    /**
6028     * This method is called when the component is hidden.
6029     * 
6030     * @param event the <code>ComponentEvent</code> indicating the visibility
6031     */
6032    public void componentHidden(ComponentEvent event)
6033    {
6034      if (isShowing())
6035        peer.hide();
6036    }
6037  }
6038  
6039  /**
6040   * This class provides accessibility support for subclasses of container.
6041   *
6042   * @author Eric Blake (ebb9@email.byu.edu)
6043   * @since 1.3
6044   * @status updated to 1.4
6045   */
6046  protected abstract class AccessibleAWTComponent extends AccessibleContext
6047    implements Serializable, AccessibleComponent
6048  {
6049    /**
6050     * Compatible with JDK 1.3+.
6051     */
6052    private static final long serialVersionUID = 642321655757800191L;
6053
6054    /**
6055     * Converts show/hide events to PropertyChange events, and is registered
6056     * as a component listener on this component.
6057     *
6058     * @serial the component handler
6059     */
6060    protected ComponentListener accessibleAWTComponentHandler
6061      = new AccessibleAWTComponentHandler();
6062
6063    /**
6064     * Converts focus events to PropertyChange events, and is registered
6065     * as a focus listener on this component.
6066     *
6067     * @serial the focus handler
6068     */
6069    protected FocusListener accessibleAWTFocusHandler
6070      = new AccessibleAWTFocusHandler();
6071
6072    /**
6073     * The default constructor.
6074     */
6075    protected AccessibleAWTComponent()
6076    {
6077      Component.this.addComponentListener(accessibleAWTComponentHandler);
6078      Component.this.addFocusListener(accessibleAWTFocusHandler);
6079    }
6080
6081    /**
6082     * Adds a global property change listener to the accessible component.
6083     *
6084     * @param l the listener to add
6085     * @see #ACCESSIBLE_NAME_PROPERTY
6086     * @see #ACCESSIBLE_DESCRIPTION_PROPERTY
6087     * @see #ACCESSIBLE_STATE_PROPERTY
6088     * @see #ACCESSIBLE_VALUE_PROPERTY
6089     * @see #ACCESSIBLE_SELECTION_PROPERTY
6090     * @see #ACCESSIBLE_TEXT_PROPERTY
6091     * @see #ACCESSIBLE_VISIBLE_DATA_PROPERTY
6092     */
6093    public void addPropertyChangeListener(PropertyChangeListener l)
6094    {
6095      Component.this.addPropertyChangeListener(l);
6096      super.addPropertyChangeListener(l);
6097    }
6098
6099    /**
6100     * Removes a global property change listener from this accessible
6101     * component.
6102     *
6103     * @param l the listener to remove
6104     */
6105    public void removePropertyChangeListener(PropertyChangeListener l)
6106    {
6107      Component.this.removePropertyChangeListener(l);
6108      super.removePropertyChangeListener(l);
6109    }
6110
6111    /**
6112     * Returns the accessible name of this component. It is almost always
6113     * wrong to return getName(), since it is not localized. In fact, for
6114     * things like buttons, this should be the text of the button, not the
6115     * name of the object. The tooltip text might also be appropriate.
6116     *
6117     * @return the name
6118     * @see #setAccessibleName(String)
6119     */
6120    public String getAccessibleName()
6121    {
6122      return accessibleName;
6123    }
6124
6125    /**
6126     * Returns a brief description of this accessible context. This should
6127     * be localized.
6128     *
6129     * @return a description of this component
6130     * @see #setAccessibleDescription(String)
6131     */
6132    public String getAccessibleDescription()
6133    {
6134      return accessibleDescription;
6135    }
6136
6137    /**
6138     * Returns the role of this component.
6139     *
6140     * @return the accessible role
6141     */
6142    public AccessibleRole getAccessibleRole()
6143    {
6144      return AccessibleRole.AWT_COMPONENT;
6145    }
6146
6147    /**
6148     * Returns a state set describing this component's state.
6149     *
6150     * @return a new state set
6151     * @see AccessibleState
6152     */
6153    public AccessibleStateSet getAccessibleStateSet()
6154    {
6155      AccessibleStateSet s = new AccessibleStateSet();
6156      if (Component.this.isEnabled())
6157        s.add(AccessibleState.ENABLED);
6158      if (isFocusable())
6159        s.add(AccessibleState.FOCUSABLE);
6160      if (isFocusOwner())
6161        s.add(AccessibleState.FOCUSED);
6162      // Note: While the java.awt.Component has an 'opaque' property, it
6163      // seems that it is not added to the accessible state set here, even
6164      // if this property is true. However, it is handled for
6165      // javax.swing.JComponent, so we add it there.
6166      if (Component.this.isShowing())
6167        s.add(AccessibleState.SHOWING);
6168      if (Component.this.isVisible())
6169        s.add(AccessibleState.VISIBLE);
6170      return s;
6171    }
6172
6173    /**
6174     * Returns the parent of this component, if it is accessible.
6175     *
6176     * @return the accessible parent
6177     */
6178    public Accessible getAccessibleParent()
6179    {
6180      if (accessibleParent == null)
6181        {
6182          Container parent = getParent();
6183          accessibleParent = parent instanceof Accessible
6184            ? (Accessible) parent : null;
6185        }
6186      return accessibleParent;
6187    }
6188
6189    /**
6190     * Returns the index of this component in its accessible parent.
6191     *
6192     * @return the index, or -1 if the parent is not accessible
6193     * @see #getAccessibleParent()
6194     */
6195    public int getAccessibleIndexInParent()
6196    {
6197      if (getAccessibleParent() == null)
6198        return -1;
6199      AccessibleContext context
6200        = ((Component) accessibleParent).getAccessibleContext();
6201      if (context == null)
6202        return -1;
6203      for (int i = context.getAccessibleChildrenCount(); --i >= 0; )
6204        if (context.getAccessibleChild(i) == Component.this)
6205          return i;
6206      return -1;
6207    }
6208
6209    /**
6210     * Returns the number of children of this component which implement
6211     * Accessible. Subclasses must override this if they can have children.
6212     *
6213     * @return the number of accessible children, default 0
6214     */
6215    public int getAccessibleChildrenCount()
6216    {
6217      return 0;
6218    }
6219
6220    /**
6221     * Returns the ith accessible child. Subclasses must override this if
6222     * they can have children.
6223     *
6224     * @return the ith accessible child, or null
6225     * @see #getAccessibleChildrenCount()
6226     */
6227    public Accessible getAccessibleChild(int i)
6228    {
6229      return null;
6230    }
6231
6232    /**
6233     * Returns the locale of this component.
6234     *
6235     * @return the locale
6236     * @throws IllegalComponentStateException if the locale is unknown
6237     */
6238    public Locale getLocale()
6239    {
6240      return Component.this.getLocale();
6241    }
6242
6243    /**
6244     * Returns this, since it is an accessible component.
6245     *
6246     * @return the accessible component
6247     */
6248    public AccessibleComponent getAccessibleComponent()
6249    {
6250      return this;
6251    }
6252
6253    /**
6254     * Gets the background color.
6255     *
6256     * @return the background color
6257     * @see #setBackground(Color)
6258     */
6259    public Color getBackground()
6260    {
6261      return Component.this.getBackground();
6262    }
6263
6264    /**
6265     * Sets the background color.
6266     *
6267     * @param c the background color
6268     * @see #getBackground()
6269     * @see #isOpaque()
6270     */
6271    public void setBackground(Color c)
6272    {
6273      Component.this.setBackground(c);
6274    }
6275
6276    /**
6277     * Gets the foreground color.
6278     *
6279     * @return the foreground color
6280     * @see #setForeground(Color)
6281     */
6282    public Color getForeground()
6283    {
6284      return Component.this.getForeground();
6285    }
6286
6287    /**
6288     * Sets the foreground color.
6289     *
6290     * @param c the foreground color
6291     * @see #getForeground()
6292     */
6293    public void setForeground(Color c)
6294    {
6295      Component.this.setForeground(c);
6296    }
6297
6298    /**
6299     * Gets the cursor.
6300     *
6301     * @return the cursor
6302     * @see #setCursor(Cursor)
6303     */
6304    public Cursor getCursor()
6305    {
6306      return Component.this.getCursor();
6307    }
6308
6309    /**
6310     * Sets the cursor.
6311     *
6312     * @param cursor the cursor
6313     * @see #getCursor()
6314     */
6315    public void setCursor(Cursor cursor)
6316    {
6317      Component.this.setCursor(cursor);
6318    }
6319
6320    /**
6321     * Gets the font.
6322     *
6323     * @return the font
6324     * @see #setFont(Font)
6325     */
6326    public Font getFont()
6327    {
6328      return Component.this.getFont();
6329    }
6330
6331    /**
6332     * Sets the font.
6333     *
6334     * @param f the font
6335     * @see #getFont()
6336     */
6337    public void setFont(Font f)
6338    {
6339      Component.this.setFont(f);
6340    }
6341
6342    /**
6343     * Gets the font metrics for a font.
6344     *
6345     * @param f the font to look up
6346     * @return its metrics
6347     * @throws NullPointerException if f is null
6348     * @see #getFont()
6349     */
6350    public FontMetrics getFontMetrics(Font f)
6351    {
6352      return Component.this.getFontMetrics(f);
6353    }
6354
6355    /**
6356     * Tests if the component is enabled.
6357     *
6358     * @return true if the component is enabled
6359     * @see #setEnabled(boolean)
6360     * @see #getAccessibleStateSet()
6361     * @see AccessibleState#ENABLED
6362     */
6363    public boolean isEnabled()
6364    {
6365      return Component.this.isEnabled();
6366    }
6367
6368    /**
6369     * Set whether the component is enabled.
6370     *
6371     * @param b the new enabled status
6372     * @see #isEnabled()
6373     */
6374    public void setEnabled(boolean b)
6375    {
6376      Component.this.setEnabled(b);
6377    }
6378
6379    /**
6380     * Test whether the component is visible (not necesarily showing).
6381     *
6382     * @return true if it is visible
6383     * @see #setVisible(boolean)
6384     * @see #getAccessibleStateSet()
6385     * @see AccessibleState#VISIBLE
6386     */
6387    public boolean isVisible()
6388    {
6389      return Component.this.isVisible();
6390    }
6391
6392    /**
6393     * Sets the visibility of this component.
6394     *
6395     * @param b the desired visibility
6396     * @see #isVisible()
6397     */
6398    public void setVisible(boolean b)
6399    {
6400      Component.this.setVisible(b);
6401    }
6402
6403    /**
6404     * Tests if the component is showing.
6405     *
6406     * @return true if this is showing
6407     */
6408    public boolean isShowing()
6409    {
6410      return Component.this.isShowing();
6411    }
6412
6413    /**
6414     * Tests if the point is contained in this component.
6415     *
6416     * @param p the point to check
6417     * @return true if it is contained
6418     * @throws NullPointerException if p is null
6419     */
6420    public boolean contains(Point p)
6421    {
6422      return Component.this.contains(p.x, p.y);
6423    }
6424
6425    /**
6426     * Returns the location of this object on the screen, or null if it is
6427     * not showing.
6428     *
6429     * @return the location relative to screen coordinates, if showing
6430     * @see #getBounds()
6431     * @see #getLocation()
6432     */
6433    public Point getLocationOnScreen()
6434    {
6435      return Component.this.isShowing() ? Component.this.getLocationOnScreen()
6436        : null;
6437    }
6438
6439    /**
6440     * Returns the location of this object relative to its parent's coordinate
6441     * system, or null if it is not showing.
6442     *
6443     * @return the location
6444     * @see #getBounds()
6445     * @see #getLocationOnScreen()
6446     */
6447    public Point getLocation()
6448    {
6449      return Component.this.getLocation();
6450    }
6451
6452    /**
6453     * Sets the location of this relative to its parent's coordinate system.
6454     *
6455     * @param p the location
6456     * @throws NullPointerException if p is null
6457     * @see #getLocation()
6458     */
6459    public void setLocation(Point p)
6460    {
6461      Component.this.setLocation(p.x, p.y);
6462    }
6463
6464    /**
6465     * Gets the bounds of this component, or null if it is not on screen.
6466     *
6467     * @return the bounds
6468     * @see #contains(Point)
6469     * @see #setBounds(Rectangle)
6470     */
6471    public Rectangle getBounds()
6472    {
6473      return Component.this.getBounds();
6474    }
6475
6476    /**
6477     * Sets the bounds of this component.
6478     *
6479     * @param r the bounds
6480     * @throws NullPointerException if r is null
6481     * @see #getBounds()
6482     */
6483    public void setBounds(Rectangle r)
6484    {
6485      Component.this.setBounds(r.x, r.y, r.width, r.height);
6486    }
6487
6488    /**
6489     * Gets the size of this component, or null if it is not showing.
6490     *
6491     * @return the size
6492     * @see #setSize(Dimension)
6493     */
6494    public Dimension getSize()
6495    {
6496      return Component.this.getSize();
6497    }
6498
6499    /**
6500     * Sets the size of this component.
6501     *
6502     * @param d the size
6503     * @throws NullPointerException if d is null
6504     * @see #getSize()
6505     */
6506    public void setSize(Dimension d)
6507    {
6508      Component.this.setSize(d.width, d.height);
6509    }
6510
6511    /**
6512     * Returns the Accessible child at a point relative to the coordinate
6513     * system of this component, if one exists, or null. Since components
6514     * have no children, subclasses must override this to get anything besides
6515     * null.
6516     *
6517     * @param p the point to check
6518     * @return the accessible child at that point
6519     * @throws NullPointerException if p is null
6520     */
6521    public Accessible getAccessibleAt(Point p)
6522    {
6523      return null;
6524    }
6525
6526    /**
6527     * Tests whether this component can accept focus.
6528     *
6529     * @return true if this is focus traversable
6530     * @see #getAccessibleStateSet ()
6531     * @see AccessibleState#FOCUSABLE
6532     * @see AccessibleState#FOCUSED
6533     */
6534    public boolean isFocusTraversable ()
6535    {
6536      return Component.this.isFocusTraversable ();
6537    }
6538
6539    /**
6540     * Requests focus for this component.
6541     *
6542     * @see #isFocusTraversable ()
6543     */
6544    public void requestFocus ()
6545    {
6546      Component.this.requestFocus ();
6547    }
6548
6549    /**
6550     * Adds a focus listener.
6551     *
6552     * @param l the listener to add
6553     */
6554    public void addFocusListener(FocusListener l)
6555    {
6556      Component.this.addFocusListener(l);
6557    }
6558
6559    /**
6560     * Removes a focus listener.
6561     *
6562     * @param l the listener to remove
6563     */
6564    public void removeFocusListener(FocusListener l)
6565    {
6566      Component.this.removeFocusListener(l);
6567    }
6568
6569    /**
6570     * Converts component changes into property changes.
6571     *
6572     * @author Eric Blake (ebb9@email.byu.edu)
6573     * @since 1.3
6574     * @status updated to 1.4
6575     */
6576    protected class AccessibleAWTComponentHandler implements ComponentListener
6577    {
6578      /**
6579       * Default constructor.
6580       */
6581      protected AccessibleAWTComponentHandler()
6582      {
6583        // Nothing to do here.
6584      }
6585
6586      /**
6587       * Convert a component hidden to a property change.
6588       *
6589       * @param e the event to convert
6590       */
6591      public void componentHidden(ComponentEvent e)
6592      {
6593        AccessibleAWTComponent.this.firePropertyChange
6594          (ACCESSIBLE_STATE_PROPERTY, AccessibleState.VISIBLE, null);
6595      }
6596
6597      /**
6598       * Convert a component shown to a property change.
6599       *
6600       * @param e the event to convert
6601       */
6602      public void componentShown(ComponentEvent e)
6603      {
6604        AccessibleAWTComponent.this.firePropertyChange
6605          (ACCESSIBLE_STATE_PROPERTY, null, AccessibleState.VISIBLE);
6606      }
6607
6608      /**
6609       * Moving a component does not affect properties.
6610       *
6611       * @param e ignored
6612       */
6613      public void componentMoved(ComponentEvent e)
6614      {
6615        // Nothing to do here.
6616      }
6617
6618      /**
6619       * Resizing a component does not affect properties.
6620       *
6621       * @param e ignored
6622       */
6623      public void componentResized(ComponentEvent e)
6624      {
6625        // Nothing to do here.
6626      }
6627    } // class AccessibleAWTComponentHandler
6628
6629    /**
6630     * Converts focus changes into property changes.
6631     *
6632     * @author Eric Blake (ebb9@email.byu.edu)
6633     * @since 1.3
6634     * @status updated to 1.4
6635     */
6636    protected class AccessibleAWTFocusHandler implements FocusListener
6637    {
6638      /**
6639       * Default constructor.
6640       */
6641      protected AccessibleAWTFocusHandler()
6642      {
6643        // Nothing to do here.
6644      }
6645
6646      /**
6647       * Convert a focus gained to a property change.
6648       *
6649       * @param e the event to convert
6650       */
6651      public void focusGained(FocusEvent e)
6652      {
6653        AccessibleAWTComponent.this.firePropertyChange
6654          (ACCESSIBLE_STATE_PROPERTY, null, AccessibleState.FOCUSED);
6655      }
6656
6657      /**
6658       * Convert a focus lost to a property change.
6659       *
6660       * @param e the event to convert
6661       */
6662      public void focusLost(FocusEvent e)
6663      {
6664        AccessibleAWTComponent.this.firePropertyChange
6665          (ACCESSIBLE_STATE_PROPERTY, AccessibleState.FOCUSED, null);
6666      }
6667    } // class AccessibleAWTComponentHandler
6668  } // class AccessibleAWTComponent
6669
6670  /**
6671   * This class provides support for blitting offscreen surfaces to a
6672   * component.
6673   *
6674   * @see BufferStrategy
6675   *
6676   * @since 1.4
6677   */
6678  protected class BltBufferStrategy extends BufferStrategy
6679  {
6680    /**
6681     * The capabilities of the image buffer.
6682     */
6683    protected BufferCapabilities caps;
6684
6685    /**
6686     * The back buffers used in this strategy.
6687     */
6688    protected VolatileImage[] backBuffers;
6689
6690    /**
6691     * Whether or not the image buffer resources are allocated and
6692     * ready to be drawn into.
6693     */
6694    protected boolean validatedContents;
6695
6696    /**
6697     * The width of the back buffers.
6698     */
6699    protected int width;
6700
6701    /**
6702     * The height of the back buffers.
6703     */
6704    protected int height;
6705
6706    /**
6707     * The front buffer.
6708     */
6709    private VolatileImage frontBuffer;
6710
6711    /**
6712     * Creates a blitting buffer strategy.
6713     *
6714     * @param numBuffers the number of buffers, including the front
6715     * buffer
6716     * @param caps the capabilities of this strategy
6717     */
6718    protected BltBufferStrategy(int numBuffers, BufferCapabilities caps)
6719    {
6720      this.caps = caps;
6721      createBackBuffers(numBuffers - 1);
6722      width = getWidth();
6723      height = getHeight();
6724    }
6725
6726    /**
6727     * Initializes the backBuffers field with an array of numBuffers
6728     * VolatileImages.
6729     *
6730     * @param numBuffers the number of backbuffers to create
6731     */
6732    protected void createBackBuffers(int numBuffers)
6733    {
6734      GraphicsConfiguration c =
6735        GraphicsEnvironment.getLocalGraphicsEnvironment()
6736        .getDefaultScreenDevice().getDefaultConfiguration();
6737
6738      backBuffers = new VolatileImage[numBuffers];
6739
6740      for (int i = 0; i < numBuffers; i++)
6741        backBuffers[i] = c.createCompatibleVolatileImage(width, height);
6742    }
6743
6744    /**
6745     * Retrieves the capabilities of this buffer strategy.
6746     *
6747     * @return the capabilities of this buffer strategy
6748     */
6749    public BufferCapabilities getCapabilities()
6750    {
6751      return caps;
6752    }
6753
6754    /**
6755     * Retrieves a graphics object that can be used to draw into this
6756     * strategy's image buffer.
6757     *
6758     * @return a graphics object
6759     */
6760    public Graphics getDrawGraphics()
6761    {
6762      // Return the backmost buffer's graphics.
6763      return backBuffers[0].getGraphics();
6764    }
6765
6766    /**
6767     * Bring the contents of the back buffer to the front buffer.
6768     */
6769    public void show()
6770    {
6771      GraphicsConfiguration c =
6772        GraphicsEnvironment.getLocalGraphicsEnvironment()
6773        .getDefaultScreenDevice().getDefaultConfiguration();
6774
6775      // draw the front buffer.
6776      getGraphics().drawImage(backBuffers[backBuffers.length - 1],
6777                              width, height, null);
6778
6779      BufferCapabilities.FlipContents f = getCapabilities().getFlipContents();
6780
6781      // blit the back buffers.
6782      for (int i = backBuffers.length - 1; i > 0 ; i--)
6783        backBuffers[i] = backBuffers[i - 1];
6784
6785      // create new backmost buffer.
6786      if (f == BufferCapabilities.FlipContents.UNDEFINED)
6787        backBuffers[0] = c.createCompatibleVolatileImage(width, height);
6788
6789      // create new backmost buffer and clear it to the background
6790      // color.
6791      if (f == BufferCapabilities.FlipContents.BACKGROUND)
6792        {
6793          backBuffers[0] = c.createCompatibleVolatileImage(width, height);
6794          backBuffers[0].getGraphics().clearRect(0, 0, width, height);
6795        }
6796
6797      // FIXME: set the backmost buffer to the prior contents of the
6798      // front buffer.  How do we retrieve the contents of the front
6799      // buffer?
6800      //
6801      //      if (f == BufferCapabilities.FlipContents.PRIOR)
6802
6803      // set the backmost buffer to a copy of the new front buffer.
6804      if (f == BufferCapabilities.FlipContents.COPIED)
6805        backBuffers[0] = backBuffers[backBuffers.length - 1];
6806    }
6807
6808    /**
6809     * Re-create the image buffer resources if they've been lost.
6810     */
6811    protected void revalidate()
6812    {
6813      GraphicsConfiguration c =
6814        GraphicsEnvironment.getLocalGraphicsEnvironment()
6815        .getDefaultScreenDevice().getDefaultConfiguration();
6816
6817      for (int i = 0; i < backBuffers.length; i++)
6818        {
6819          int result = backBuffers[i].validate(c);
6820          if (result == VolatileImage.IMAGE_INCOMPATIBLE)
6821            backBuffers[i] = c.createCompatibleVolatileImage(width, height);
6822        }
6823      validatedContents = true;
6824    }
6825
6826    /**
6827     * Returns whether or not the image buffer resources have been
6828     * lost.
6829     *
6830     * @return true if the resources have been lost, false otherwise
6831     */
6832    public boolean contentsLost()
6833    {
6834      for (int i = 0; i < backBuffers.length; i++)
6835        {
6836          if (backBuffers[i].contentsLost())
6837            {
6838              validatedContents = false;
6839              return true;
6840            }
6841        }
6842      // we know that the buffer resources are valid now because we
6843      // just checked them
6844      validatedContents = true;
6845      return false;
6846    }
6847
6848    /**
6849     * Returns whether or not the image buffer resources have been
6850     * restored.
6851     *
6852     * @return true if the resources have been restored, false
6853     * otherwise
6854     */
6855    public boolean contentsRestored()
6856    {
6857      GraphicsConfiguration c =
6858        GraphicsEnvironment.getLocalGraphicsEnvironment()
6859        .getDefaultScreenDevice().getDefaultConfiguration();
6860
6861      boolean imageRestored = false;
6862
6863      for (int i = 0; i < backBuffers.length; i++)
6864        {
6865          int result = backBuffers[i].validate(c);
6866          if (result == VolatileImage.IMAGE_RESTORED)
6867            imageRestored = true;
6868          else if (result == VolatileImage.IMAGE_INCOMPATIBLE)
6869            return false;
6870        }
6871      // we know that the buffer resources are valid now because we
6872      // just checked them
6873      validatedContents = true;
6874      return imageRestored;
6875    }
6876  }
6877
6878  /**
6879   * This class provides support for flipping component buffers. It
6880   * can only be used on Canvases and Windows.
6881   *
6882   * @since 1.4
6883   */
6884  protected class FlipBufferStrategy extends BufferStrategy
6885  {
6886    /**
6887     * The number of buffers.
6888     */
6889    protected int numBuffers;
6890
6891    /**
6892     * The capabilities of this buffering strategy.
6893     */
6894    protected BufferCapabilities caps;
6895
6896    /**
6897     * An Image reference to the drawing buffer.
6898     */
6899    protected Image drawBuffer;
6900
6901    /**
6902     * A VolatileImage reference to the drawing buffer.
6903     */
6904    protected VolatileImage drawVBuffer;
6905
6906    /**
6907     * Whether or not the image buffer resources are allocated and
6908     * ready to be drawn into.
6909     */
6910    protected boolean validatedContents;
6911
6912    /**
6913     * The width of the back buffer.
6914     */
6915    private int width;
6916
6917    /**
6918     * The height of the back buffer.
6919     */
6920    private int height;
6921
6922    /**
6923     * Creates a flipping buffer strategy.  The only supported
6924     * strategy for FlipBufferStrategy itself is a double-buffer page
6925     * flipping strategy.  It forms the basis for more complex derived
6926     * strategies.
6927     *
6928     * @param numBuffers the number of buffers
6929     * @param caps the capabilities of this buffering strategy
6930     *
6931     * @throws AWTException if the requested
6932     * number-of-buffers/capabilities combination is not supported
6933     */
6934    protected FlipBufferStrategy(int numBuffers, BufferCapabilities caps)
6935      throws AWTException
6936    {
6937      this.caps = caps;
6938      width = getWidth();
6939      height = getHeight();
6940
6941      if (numBuffers > 1)
6942        createBuffers(numBuffers, caps);
6943      else
6944        {
6945          drawVBuffer = peer.createVolatileImage(width, height);
6946          drawBuffer = drawVBuffer;
6947        }
6948    }
6949
6950    /**
6951     * Creates a multi-buffer flipping strategy.  The number of
6952     * buffers must be greater than one and the buffer capabilities
6953     * must specify page flipping.
6954     *
6955     * @param numBuffers the number of flipping buffers; must be
6956     * greater than one
6957     * @param caps the buffering capabilities; caps.isPageFlipping()
6958     * must return true
6959     *
6960     * @throws IllegalArgumentException if numBuffers is not greater
6961     * than one or if the page flipping capability is not requested
6962     *
6963     * @throws AWTException if the requested flipping strategy is not
6964     * supported
6965     */
6966    protected void createBuffers(int numBuffers, BufferCapabilities caps)
6967      throws AWTException
6968    {
6969      if (numBuffers <= 1)
6970        throw new IllegalArgumentException("FlipBufferStrategy.createBuffers:"
6971                                           + " numBuffers must be greater than"
6972                                           + " one.");
6973
6974      if (!caps.isPageFlipping())
6975        throw new IllegalArgumentException("FlipBufferStrategy.createBuffers:"
6976                                           + " flipping must be a specified"
6977                                           + " capability.");
6978
6979      peer.createBuffers(numBuffers, caps);
6980    }
6981
6982    /**
6983     * Return a direct reference to the back buffer image.
6984     *
6985     * @return a direct reference to the back buffer image.
6986     */
6987    protected Image getBackBuffer()
6988    {
6989      return peer.getBackBuffer();
6990    }
6991
6992    /**
6993     * Perform a flip operation to transfer the contents of the back
6994     * buffer to the front buffer.
6995     */
6996    protected void flip(BufferCapabilities.FlipContents flipAction)
6997    {
6998      peer.flip(flipAction);
6999    }
7000
7001    /**
7002     * Release the back buffer's resources.
7003     */
7004    protected void destroyBuffers()
7005    {
7006      peer.destroyBuffers();
7007    }
7008
7009    /**
7010     * Retrieves the capabilities of this buffer strategy.
7011     *
7012     * @return the capabilities of this buffer strategy
7013     */
7014    public BufferCapabilities getCapabilities()
7015    {
7016      return caps;
7017    }
7018
7019    /**
7020     * Retrieves a graphics object that can be used to draw into this
7021     * strategy's image buffer.
7022     *
7023     * @return a graphics object
7024     */
7025    public Graphics getDrawGraphics()
7026    {
7027      return drawVBuffer.getGraphics();
7028    }
7029
7030    /**
7031     * Re-create the image buffer resources if they've been lost.
7032     */
7033    protected void revalidate()
7034    {
7035      GraphicsConfiguration c =
7036        GraphicsEnvironment.getLocalGraphicsEnvironment()
7037        .getDefaultScreenDevice().getDefaultConfiguration();
7038
7039      if (drawVBuffer.validate(c) == VolatileImage.IMAGE_INCOMPATIBLE)
7040        drawVBuffer = peer.createVolatileImage(width, height);
7041      validatedContents = true;
7042    }
7043
7044    /**
7045     * Returns whether or not the image buffer resources have been
7046     * lost.
7047     *
7048     * @return true if the resources have been lost, false otherwise
7049     */
7050    public boolean contentsLost()
7051    {
7052      if (drawVBuffer.contentsLost())
7053        {
7054          validatedContents = false;
7055          return true;
7056        }
7057      // we know that the buffer resources are valid now because we
7058      // just checked them
7059      validatedContents = true;
7060      return false;
7061    }
7062
7063    /**
7064     * Returns whether or not the image buffer resources have been
7065     * restored.
7066     *
7067     * @return true if the resources have been restored, false
7068     * otherwise
7069     */
7070    public boolean contentsRestored()
7071    {
7072      GraphicsConfiguration c =
7073        GraphicsEnvironment.getLocalGraphicsEnvironment()
7074        .getDefaultScreenDevice().getDefaultConfiguration();
7075
7076      int result = drawVBuffer.validate(c);
7077
7078      boolean imageRestored = false;
7079
7080      if (result == VolatileImage.IMAGE_RESTORED)
7081        imageRestored = true;
7082      else if (result == VolatileImage.IMAGE_INCOMPATIBLE)
7083        return false;
7084
7085      // we know that the buffer resources are valid now because we
7086      // just checked them
7087      validatedContents = true;
7088      return imageRestored;
7089    }
7090
7091    /**
7092     * Bring the contents of the back buffer to the front buffer.
7093     */
7094    public void show()
7095    {
7096      flip(caps.getFlipContents());
7097    }
7098  }
7099}