Source for javax.swing.JComponent

   1: /* JComponent.java -- Every component in swing inherits from this class.
   2:    Copyright (C) 2002, 2004, 2005  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package javax.swing;
  40: 
  41: import java.awt.AWTEvent;
  42: import java.awt.Color;
  43: import java.awt.Component;
  44: import java.awt.Container;
  45: import java.awt.Dimension;
  46: import java.awt.FlowLayout;
  47: import java.awt.Font;
  48: import java.awt.Graphics;
  49: import java.awt.Graphics2D;
  50: import java.awt.Image;
  51: import java.awt.Insets;
  52: import java.awt.Point;
  53: import java.awt.Rectangle;
  54: import java.awt.dnd.DropTarget;
  55: import java.awt.event.ActionEvent;
  56: import java.awt.event.ActionListener;
  57: import java.awt.event.ContainerEvent;
  58: import java.awt.event.ContainerListener;
  59: import java.awt.event.FocusEvent;
  60: import java.awt.event.FocusListener;
  61: import java.awt.event.KeyEvent;
  62: import java.awt.event.MouseEvent;
  63: import java.awt.geom.Rectangle2D;
  64: import java.awt.image.ImageObserver;
  65: import java.awt.peer.LightweightPeer;
  66: import java.beans.PropertyChangeEvent;
  67: import java.beans.PropertyChangeListener;
  68: import java.beans.PropertyVetoException;
  69: import java.beans.VetoableChangeListener;
  70: import java.io.Serializable;
  71: import java.util.EventListener;
  72: import java.util.Hashtable;
  73: import java.util.Locale;
  74: 
  75: import javax.accessibility.Accessible;
  76: import javax.accessibility.AccessibleContext;
  77: import javax.accessibility.AccessibleExtendedComponent;
  78: import javax.accessibility.AccessibleKeyBinding;
  79: import javax.accessibility.AccessibleRole;
  80: import javax.accessibility.AccessibleStateSet;
  81: import javax.swing.border.Border;
  82: import javax.swing.event.AncestorEvent;
  83: import javax.swing.event.AncestorListener;
  84: import javax.swing.event.EventListenerList;
  85: import javax.swing.event.SwingPropertyChangeSupport;
  86: import javax.swing.plaf.ComponentUI;
  87: 
  88: /**
  89:  * Every component in swing inherits from this class (JLabel, JButton, etc).
  90:  * It contains generic methods to manage events, properties and sizes. Actual
  91:  * drawing of the component is channeled to a look-and-feel class that is
  92:  * implemented elsewhere.
  93:  *
  94:  * @author Ronald Veldema (rveldema&064;cs.vu.nl)
  95:  * @author Graydon Hoare (graydon&064;redhat.com)
  96:  */
  97: public abstract class JComponent extends Container implements Serializable
  98: {
  99:   private static final long serialVersionUID = -7908749299918704233L;
 100: 
 101:   /** 
 102:    * Accessibility support is currently missing.
 103:    */
 104:   protected AccessibleContext accessibleContext;
 105: 
 106:   public abstract class AccessibleJComponent 
 107:     extends AccessibleAWTContainer
 108:     implements AccessibleExtendedComponent
 109:   {
 110:     protected class AccessibleFocusHandler 
 111:       implements FocusListener
 112:     {
 113:       protected AccessibleFocusHandler(){}
 114:       public void focusGained(FocusEvent event){}
 115:       public void focusLost(FocusEvent valevent){}
 116:     }
 117: 
 118:     protected class AccessibleContainerHandler 
 119:       implements ContainerListener
 120:     {
 121:       protected AccessibleContainerHandler() {}
 122:       public void componentAdded(ContainerEvent event) {}
 123:       public void componentRemoved(ContainerEvent valevent) {}
 124:     }
 125: 
 126:     private static final long serialVersionUID = -7047089700479897799L;
 127:   
 128:     protected ContainerListener accessibleContainerHandler;
 129:     protected FocusListener accessibleFocusHandler;
 130: 
 131:     protected AccessibleJComponent() {}
 132:     public void addPropertyChangeListener(PropertyChangeListener listener) {}
 133:     public void removePropertyChangeListener(PropertyChangeListener listener) {}
 134:     public int getAccessibleChildrenCount() { return 0; }
 135:     public Accessible getAccessibleChild(int value0) { return null; }
 136:     public AccessibleStateSet getAccessibleStateSet() { return null; } 
 137:     public String getAccessibleName() { return null; }
 138:     public String getAccessibleDescription() { return null; }
 139:     public AccessibleRole getAccessibleRole() { return null; }
 140:     protected String getBorderTitle(Border value0) { return null; }
 141:     public String getToolTipText() { return null; }
 142:     public String getTitledBorderText() { return null; }
 143:     public AccessibleKeyBinding getAccessibleKeyBinding() { return null; }
 144:   }
 145: 
 146:   /** 
 147:    * An explicit value for the component's preferred size; if not set by a
 148:    * user, this is calculated on the fly by delegating to the {@link
 149:    * ComponentUI.getPreferredSize} method on the {@link #ui} property. 
 150:    */
 151:   Dimension preferredSize;
 152: 
 153:   /** 
 154:    * An explicit value for the component's minimum size; if not set by a
 155:    * user, this is calculated on the fly by delegating to the {@link
 156:    * ComponentUI.getMinimumSize} method on the {@link #ui} property. 
 157:    */
 158:   Dimension minimumSize;
 159: 
 160:   /** 
 161:    * An explicit value for the component's maximum size; if not set by a
 162:    * user, this is calculated on the fly by delegating to the {@link
 163:    * ComponentUI.getMaximumSize} method on the {@link #ui} property.
 164:    */
 165:   Dimension maximumSize;
 166: 
 167:   /**
 168:    * A value between 0.0 and 1.0 indicating the preferred horizontal
 169:    * alignment of the component, relative to its siblings. The values
 170:    * {@link #LEFT_ALIGNMENT}, {@link #CENTER_ALIGNMENT}, and {@link
 171:    * #RIGHT_ALIGNMENT} can also be used, as synonyms for <code>0.0</code>,
 172:    * <code>0.5</code>, and <code>1.0</code>, respectively. Not all layout
 173:    * managers use this property.
 174:    *
 175:    * @see #getAlignmentX
 176:    * @see #setAlignmentX
 177:    * @see javax.swing.OverlayLayout
 178:    * @see javax.swing.BoxLayout
 179:    */
 180:   float alignmentX = 0.5f;
 181: 
 182:   /**
 183:    * A value between 0.0 and 1.0 indicating the preferred vertical
 184:    * alignment of the component, relative to its siblings. The values
 185:    * {@link #TOP_ALIGNMENT}, {@link #CENTER_ALIGNMENT}, and {@link
 186:    * #BOTTOM_ALIGNMENT} can also be used, as synonyms for <code>0.0</code>,
 187:    * <code>0.5</code>, and <code>1.0</code>, respectively. Not all layout
 188:    * managers use this property.
 189:    *
 190:    * @see #getAlignmentY
 191:    * @see #setAlignmentY
 192:    * @see javax.swing.OverlayLayout
 193:    * @see javax.swing.BoxLayout
 194:    */
 195:   float alignmentY = 0.5f;
 196: 
 197:   /** 
 198:    * The border painted around this component.
 199:    * 
 200:    * @see #paintBorder
 201:    */
 202:   Border border;
 203: 
 204:   /** 
 205:    * The text to show in the tooltip associated with this component.
 206:    * 
 207:    * @see #setToolTipText
 208:    * @see #getToolTipText
 209:    */
 210:    String toolTipText;
 211: 
 212:   /** 
 213:    * <p>Whether to double buffer this component when painting. This flag
 214:    * should generally be <code>false</code>, except for top level
 215:    * components such as {@link JFrame} or {@link JApplet}.</p>
 216:    *
 217:    * <p>All children of a double buffered component are painted into the
 218:    * double buffer automatically, so only the top widget in a window needs
 219:    * to be double buffered.</p>
 220:    *
 221:    * @see #setDoubleBuffered
 222:    * @see #isDoubleBuffered
 223:    * @see #paintLock
 224:    * @see #paint
 225:    */
 226:   boolean doubleBuffered = false;
 227: 
 228:   /**
 229:    * A set of flags indicating which debugging graphics facilities should
 230:    * be enabled on this component. The values should be a combination of
 231:    * {@link DebugGraphics.NONE_OPTION}, {@link DebugGraphics.LOG_OPTION},
 232:    * {@link DebugGraphics.FLASH_OPTION}, or {@link
 233:    * DebugGraphics.BUFFERED_OPTION}.
 234:    *
 235:    * @see setDebugGraphicsOptions
 236:    * @see getDebugGraphicsOptions
 237:    * @see DebugGraphics
 238:    * @see getComponentGraphics
 239:    */
 240:   int debugGraphicsOptions;
 241: 
 242:   /** 
 243:    * <p>This property controls two independent behaviors simultaneously.</p>
 244:    *
 245:    * <p>First, it controls whether to fill the background of this widget
 246:    * when painting its body. This affects calls to {@link
 247:    * JComponent#paintComponent}, which in turn calls {@link
 248:    * ComponentUI#update} on the component's {@link #ui} property. If the
 249:    * component is opaque during this call, the background will be filled
 250:    * before calling {@link ComponentUI#paint}. This happens merely as a
 251:    * convenience; you may fill the component's background yourself too,
 252:    * but there is no need to do so if you will be filling with the same
 253:    * color.</p>
 254:    *
 255:    * <p>Second, it the opaque property informs swing's repaint system
 256:    * whether it will be necessary to paint the components "underneath" this
 257:    * component, in Z-order. If the component is opaque, it is considered to
 258:    * completely occlude components "underneath" it, so they will not be
 259:    * repainted along with the opaque component.</p>
 260:    *
 261:    * <p>The default value for this property is <code>false</code>, but most
 262:    * components will want to set it to <code>true</code> when installing UI
 263:    * defaults in {@link ComponentUI#installUI}.</p>
 264:    *
 265:    * @see #setOpaque
 266:    * @see #isOpaque
 267:    * @see #paintComponent
 268:    */
 269:   boolean opaque = false;
 270: 
 271:   /** 
 272:    * The user interface delegate for this component. Event delivery and
 273:    * repainting of the component are usually delegated to this object. 
 274:    *
 275:    * @see #setUI
 276:    * @see #getUI
 277:    * @see #updateUI
 278:    */
 279:   protected ComponentUI ui;
 280: 
 281:   /**
 282:    * A hint to the focus system that this component should or should not
 283:    * get focus. If this is <code>false</code>, swing will not try to
 284:    * request focus on this component; if <code>true</code>, swing might
 285:    * try to request focus, but the request might fail. Thus it is only 
 286:    * a hint guiding swing's behavior.
 287:    *
 288:    * @see #requestFocus
 289:    * @see #isRequestFocusEnabled
 290:    * @see #setRequestFocusEnabled
 291:    */
 292:   boolean requestFocusEnabled;
 293: 
 294:   /**
 295:    * Flag indicating behavior of this component when the mouse is dragged
 296:    * outside the component and the mouse <em>stops moving</em>. If
 297:    * <code>true</code>, synthetic mouse events will be delivered on regular
 298:    * timed intervals, continuing off in the direction the mouse exited the
 299:    * component, until the mouse is released or re-enters the component.
 300:    *
 301:    * @see setAutoscrolls
 302:    * @see getAutoscrolls
 303:    */
 304:   boolean autoscrolls = false;
 305: 
 306:   /**
 307:    * Listeners for events other than {@link PropertyChangeEvent} are
 308:    * handled by this listener list. PropertyChangeEvents are handled in
 309:    * {@link #changeSupport}.
 310:    */
 311:   protected EventListenerList listenerList = new EventListenerList();
 312: 
 313:   /** 
 314:    * Support for {@link PropertyChangeEvent} events. This is constructed
 315:    * lazily when the component gets its first {@link
 316:    * PropertyChangeListener} subscription; until then it's an empty slot.
 317:    */
 318:   private SwingPropertyChangeSupport changeSupport;
 319: 
 320: 
 321:   /** 
 322:    * Storage for "client properties", which are key/value pairs associated
 323:    * with this component by a "client", such as a user application or a
 324:    * layout manager. This is lazily constructed when the component gets its
 325:    * first client property.
 326:    */
 327:   private Hashtable clientProperties;
 328:   
 329:   private InputMap inputMap_whenFocused;
 330:   private InputMap inputMap_whenAncestorOfFocused;
 331:   private InputMap inputMap_whenInFocusedWindow;
 332:   private ActionMap actionMap;
 333:   /** @since 1.3 */
 334:   private boolean verifyInputWhenFocusTarget;
 335:   private InputVerifier inputVerifier;
 336: 
 337:   private TransferHandler transferHandler;
 338: 
 339:   /** 
 340:    * A lock held during recursive painting; this is used to serialize
 341:    * access to the double buffer, and also to select the "top level" 
 342:    * object which should acquire the double buffer in a given widget
 343:    * tree (which may have multiple double buffered children).
 344:    *
 345:    * @see #doubleBuffered
 346:    * @see #paint
 347:    */
 348:   private static final Object paintLock = new Object();
 349: 
 350:   /**
 351:    * The default locale of the component.
 352:    * 
 353:    * @see #getDefaultLocale
 354:    * @see #setDefaultLocale
 355:    */
 356:   private static Locale defaultLocale;
 357:   
 358:   public static final String TOOL_TIP_TEXT_KEY = "ToolTipText";
 359: 
 360:   /**
 361:    * Constant used to indicate that no condition has been assigned to a
 362:    * particular action.
 363:    *
 364:    * @see #registerKeyboardAction
 365:    */
 366:   public static final int UNDEFINED_CONDITION = -1;
 367: 
 368:   /**
 369:    * Constant used to indicate that an action should be performed only when 
 370:    * the component has focus.
 371:    *
 372:    * @see #registerKeyboardAction
 373:    */
 374:   public static final int WHEN_FOCUSED = 0;
 375: 
 376:   /**
 377:    * Constant used to indicate that an action should be performed only when 
 378:    * the component is an ancestor of the component which has focus.
 379:    *
 380:    * @see #registerKeyboardAction
 381:    */
 382:   public static final int WHEN_ANCESTOR_OF_FOCUSED_COMPONENT = 1;
 383: 
 384:   /**
 385:    * Constant used to indicate that an action should be performed only when 
 386:    * the component is in the window which has focus.
 387:    *
 388:    * @see #registerKeyboardAction
 389:    */
 390:   public static final int WHEN_IN_FOCUSED_WINDOW = 2;
 391: 
 392:   /**
 393:    * Creates a new <code>JComponent</code> instance.
 394:    */
 395:   public JComponent()
 396:   {
 397:     super();
 398:     super.setLayout(new FlowLayout());
 399:     setDropTarget(new DropTarget());
 400:     defaultLocale = Locale.getDefault();
 401:     debugGraphicsOptions = DebugGraphics.NONE_OPTION;
 402:     setRequestFocusEnabled(true);
 403:   }
 404: 
 405:   /**
 406:    * Helper to lazily construct and return the client properties table.
 407:    * 
 408:    * @return The current client properties table
 409:    *
 410:    * @see #clientProperties
 411:    * @see #getClientProperty
 412:    * @see #putClientProperty
 413:    */
 414:   private Hashtable getClientProperties()
 415:   {
 416:     if (clientProperties == null)
 417:       clientProperties = new Hashtable();
 418:     return clientProperties;
 419:   }
 420: 
 421:   /**
 422:    * Get a client property associated with this component and a particular
 423:    * key.
 424:    *
 425:    * @param key The key with which to look up the client property
 426:    *
 427:    * @return A client property associated with this object and key
 428:    *
 429:    * @see #clientProperties
 430:    * @see #getClientProperties
 431:    * @see #putClientProperty
 432:    */
 433:   public final Object getClientProperty(Object key)
 434:   {
 435:     return getClientProperties().get(key);
 436:   }
 437: 
 438:   /**
 439:    * Add a client property <code>value</code> to this component, associated
 440:    * with <code>key</code>. If there is an existing client property
 441:    * associated with <code>key</code>, it will be replaced.
 442:    *
 443:    * @param key The key of the client property association to add
 444:    * @param value The value of the client property association to add
 445:    *
 446:    * @see #clientProperties
 447:    * @see #getClientProperties
 448:    * @see #getClientProperty
 449:    */
 450:   public final void putClientProperty(Object key, Object value)
 451:   {
 452:     getClientProperties().put(key, value);
 453:   }
 454: 
 455:   /**
 456:    * Unregister an <code>AncestorListener</code>.
 457:    *
 458:    * @param listener The listener to unregister
 459:    * 
 460:    * @see addAncestorListener
 461:    */
 462:   public void removeAncestorListener(AncestorListener listener)
 463:   {
 464:     listenerList.remove(AncestorListener.class, listener);
 465:   }
 466: 
 467:   /**
 468:    * Unregister a <code>PropertyChangeListener</code>.
 469:    *
 470:    * @param listener The listener to register
 471:    *
 472:    * @see #addPropertyChangeListener
 473:    * @see #changeSupport
 474:    */
 475:   public void removePropertyChangeListener(PropertyChangeListener listener)
 476:   {
 477:     if (changeSupport != null)
 478:       changeSupport.removePropertyChangeListener(listener);
 479:   }
 480: 
 481:   /**
 482:    * Unregister a <code>PropertyChangeListener</code>.
 483:    *
 484:    * @param propertyName The property name to unregister the listener from
 485:    * @param listener The listener to unregister
 486:    *
 487:    * @see #addPropertyChangeListener
 488:    * @see #changeSupport
 489:    */
 490:   public void removePropertyChangeListener(String propertyName,
 491:                                            PropertyChangeListener listener)
 492:   {
 493:     if (changeSupport != null)
 494:       changeSupport.removePropertyChangeListener(propertyName, listener);
 495:   }
 496: 
 497:   /**
 498:    * Unregister a <code>VetoableChangeChangeListener</code>.
 499:    *
 500:    * @param listener The listener to unregister
 501:    *
 502:    * @see #addVetoableChangeListener
 503:    */
 504:   public void removeVetoableChangeListener(VetoableChangeListener listener)
 505:   {
 506:     listenerList.remove(VetoableChangeListener.class, listener);
 507:   }
 508: 
 509:   /**
 510:    * Register an <code>AncestorListener</code>.
 511:    *
 512:    * @param listener The listener to register
 513:    *
 514:    * @see #removeVetoableChangeListener
 515:    */
 516:   public void addAncestorListener(AncestorListener listener)
 517:   {
 518:     listenerList.add(AncestorListener.class, listener);
 519:   }
 520: 
 521:   /**
 522:    * Register a <code>PropertyChangeListener</code>. This listener will
 523:    * receive any PropertyChangeEvent, regardless of property name. To
 524:    * listen to a specific property name, use {@link
 525:    * #addPropertyChangeListener(String,PropertyChangeListener)} instead.
 526:    *
 527:    * @param listener The listener to register
 528:    *
 529:    * @see #removePropertyChangeListener
 530:    * @see #changeSupport
 531:    */
 532:   public void addPropertyChangeListener(PropertyChangeListener listener)
 533:   {
 534:     if (changeSupport == null)
 535:       changeSupport = new SwingPropertyChangeSupport(this);
 536:     changeSupport.addPropertyChangeListener(listener);
 537:   }
 538: 
 539:   /**
 540:    * Register a <code>PropertyChangeListener</code> for a specific, named
 541:    * property. To listen to all property changes, regardless of name, use
 542:    * {@link #addPropertyChangeListener(PropertyChangeListener)} instead.
 543:    *
 544:    * @param propertyName The property name to listen to
 545:    * @param listener The listener to register
 546:    *
 547:    * @see #removePropertyChangeListener
 548:    * @see #changeSupport
 549:    */
 550:   public void addPropertyChangeListener(String propertyName,
 551:                                         PropertyChangeListener listener)
 552:   {
 553:     listenerList.add(PropertyChangeListener.class, listener);
 554:   }
 555: 
 556:   /**
 557:    * Register a <code>VetoableChangeListener</code>.
 558:    *
 559:    * @param listener The listener to register
 560:    *
 561:    * @see #removeVetoableChangeListener
 562:    * @see #listenerList
 563:    */
 564:   public void addVetoableChangeListener(VetoableChangeListener listener)
 565:   {
 566:     listenerList.add(VetoableChangeListener.class, listener);
 567:   }
 568: 
 569:   /**
 570:    * Return all registered listeners of a particular type.
 571:    *
 572:    * @param listenerType The type of listener to return
 573:    *
 574:    * @return All listeners in the {@link #listenerList} which 
 575:    * are of the specified type
 576:    *
 577:    * @see #listenerList
 578:    */
 579:   public EventListener[] getListeners(Class listenerType)
 580:   {
 581:     return listenerList.getListeners(listenerType);
 582:   }
 583: 
 584:   /**
 585:    * Return all registered <code>AncestorListener</code> objects.
 586:    *
 587:    * @return The set of <code>AncestorListener</code> objects in {@link
 588:    * #listenerList}
 589:    */
 590:   public AncestorListener[] getAncestorListeners()
 591:   {
 592:     return (AncestorListener[]) getListeners(AncestorListener.class);
 593:   }
 594: 
 595:   /**
 596:    * Return all registered <code>VetoableChangeListener</code> objects.
 597:    *
 598:    * @return The set of <code>VetoableChangeListener</code> objects in {@link
 599:    * #listenerList}
 600:    */
 601:   public VetoableChangeListener[] getVetoableChangeListeners()
 602:   {
 603:     return (VetoableChangeListener[]) getListeners(VetoableChangeListener.class);
 604:   }
 605: 
 606:   /**
 607:    * Return all <code>PropertyChangeListener</code> objects registered to listen
 608:    * for a particular property.
 609:    *
 610:    * @param property The property to return the listeners of
 611:    *
 612:    * @return The set of <code>PropertyChangeListener</code> objects in 
 613:    *     {@link #changeSupport} registered to listen on the specified property
 614:    */
 615:   public PropertyChangeListener[] getPropertyChangeListeners(String property)
 616:   {
 617:     return changeSupport == null ? new PropertyChangeListener[0]
 618:                           : changeSupport.getPropertyChangeListeners(property);
 619:   }
 620: 
 621:   /**
 622:    * A variant of {@link #firePropertyChange(String,Object,Object)} 
 623:    * for properties with <code>boolean</code> values.
 624:    */
 625:   public void firePropertyChange(String propertyName, boolean oldValue,
 626:                                  boolean newValue)
 627:   {
 628:     if (changeSupport != null)
 629:       changeSupport.firePropertyChange(propertyName, Boolean.valueOf(oldValue),
 630:                                        Boolean.valueOf(newValue));
 631:   }
 632: 
 633:   /**
 634:    * A variant of {@link #firePropertyChange(String,Object,Object)} 
 635:    * for properties with <code>byte</code> values.
 636:    */
 637:   public void firePropertyChange(String propertyName, byte oldValue,
 638:                                  byte newValue)
 639:   {
 640:     if (changeSupport != null)
 641:       changeSupport.firePropertyChange(propertyName, new Byte(oldValue),
 642:                                        new Byte(newValue));
 643:   }
 644: 
 645:   /**
 646:    * A variant of {@link #firePropertyChange(String,Object,Object)} 
 647:    * for properties with <code>char</code> values.
 648:    */
 649:   public void firePropertyChange(String propertyName, char oldValue,
 650:                                  char newValue)
 651:   {
 652:     if (changeSupport != null)
 653:       changeSupport.firePropertyChange(propertyName, new Character(oldValue),
 654:                                        new Character(newValue));
 655:   }
 656: 
 657:   /**
 658:    * A variant of {@link #firePropertyChange(String,Object,Object)} 
 659:    * for properties with <code>double</code> values.
 660:    */
 661:   public void firePropertyChange(String propertyName, double oldValue,
 662:                                  double newValue)
 663:   {
 664:     if (changeSupport != null)
 665:       changeSupport.firePropertyChange(propertyName, new Double(oldValue),
 666:                                        new Double(newValue));
 667:   }
 668: 
 669:   /**
 670:    * A variant of {@link #firePropertyChange(String,Object,Object)} 
 671:    * for properties with <code>float</code> values.
 672:    */
 673:   public void firePropertyChange(String propertyName, float oldValue,
 674:                                  float newValue)
 675:   {
 676:     if (changeSupport != null)
 677:       changeSupport.firePropertyChange(propertyName, new Float(oldValue),
 678:                                        new Float(newValue));
 679:   }
 680: 
 681:   /**
 682:    * A variant of {@link #firePropertyChange(String,Object,Object)} 
 683:    * for properties with <code>int</code> values.
 684:    */
 685:   public void firePropertyChange(String propertyName, int oldValue,
 686:                                  int newValue)
 687:   {
 688:     if (changeSupport != null)
 689:       changeSupport.firePropertyChange(propertyName, new Integer(oldValue),
 690:                                        new Integer(newValue));
 691:   }
 692: 
 693:   /**
 694:    * A variant of {@link #firePropertyChange(String,Object,Object)} 
 695:    * for properties with <code>long</code> values.
 696:    */
 697:   public void firePropertyChange(String propertyName, long oldValue,
 698:                                  long newValue)
 699:   {
 700:     if (changeSupport != null)
 701:       changeSupport.firePropertyChange(propertyName, new Long(oldValue),
 702:                                        new Long(newValue));
 703:   }
 704: 
 705:   /**
 706:    * Call {@link PropertyChangeListener#propertyChange} on all listeners
 707:    * registered to listen to a given property. Any method which changes
 708:    * the specified property of this component should call this method.
 709:    *
 710:    * @param propertyName The property which changed
 711:    * @param oldValue The old value of the property
 712:    * @param newValue The new value of the property
 713:    *
 714:    * @see #changeSupport
 715:    * @see #addPropertyChangeListener
 716:    * @see #removePropertyChangeListener
 717:    */
 718:   protected void firePropertyChange(String propertyName, Object oldValue,
 719:                                     Object newValue)
 720:   {
 721:     if (changeSupport != null)
 722:       changeSupport.firePropertyChange(propertyName, oldValue, newValue);
 723:   }
 724: 
 725:   /**
 726:    * A variant of {@link #firePropertyChange(String,Object,Object)} 
 727:    * for properties with <code>short</code> values.
 728:    */
 729:   public void firePropertyChange(String propertyName, short oldValue,
 730:                                  short newValue)
 731:   {
 732:     if (changeSupport != null)
 733:       changeSupport.firePropertyChange(propertyName, new Short(oldValue),
 734:                                        new Short(newValue));
 735:   }
 736: 
 737:   /**
 738:    * Call {@link VetoableChangeListener#vetoableChange} on all listeners
 739:    * registered to listen to a given property. Any method which changes
 740:    * the specified property of this component should call this method.
 741:    *
 742:    * @param propertyName The property which changed
 743:    * @param oldValue The old value of the property
 744:    * @param newValue The new value of the property
 745:    *
 746:    * @throws PropertyVetoException if the change was vetoed by a listener
 747:    *
 748:    * @see addVetoableChangeListener
 749:    * @see removeVetoableChangeListener
 750:    */
 751:   protected void fireVetoableChange(String propertyName, Object oldValue,
 752:                                     Object newValue)
 753:     throws PropertyVetoException
 754:   {
 755:     VetoableChangeListener[] listeners = getVetoableChangeListeners();
 756: 
 757:     PropertyChangeEvent evt = new PropertyChangeEvent(this, propertyName, oldValue, newValue);
 758: 
 759:     for (int i = 0; i < listeners.length; i++)
 760:       listeners[i].vetoableChange(evt);
 761:   }
 762: 
 763:   /**
 764:    * Get the value of the accessibleContext property for this component.
 765:    *
 766:    * @return the current value of the property
 767:    */
 768:   public AccessibleContext getAccessibleContext()
 769:   {
 770:     return null;
 771:   }
 772: 
 773:   /**
 774:    * Get the value of the {@link #alignmentX} property.
 775:    *
 776:    * @return The current value of the property.
 777:    *
 778:    * @see #setAlignmentX
 779:    * @see #alignmentY
 780:    */
 781:   public float getAlignmentX()
 782:   {
 783:     return alignmentX;
 784:   }
 785: 
 786:   /**
 787:    * Get the value of the {@link #alignmentY} property.
 788:    *
 789:    * @return The current value of the property.
 790:    *
 791:    * @see #setAlignmentY
 792:    * @see #alignmentX
 793:    */
 794:   public float getAlignmentY()
 795:   {
 796:     return alignmentY;
 797:   }
 798: 
 799:   /**
 800:    * Get the current value of the {@link #autoscrolls} property.
 801:    *
 802:    * @return The current value of the property
 803:    */
 804:   public boolean getAutoscrolls()
 805:   {
 806:     return autoscrolls;
 807:   }
 808: 
 809:   /**
 810:    * Set the value of the {@link #border} property.
 811:    *   
 812:    * @param newBorder The new value of the property
 813:    *
 814:    * @see #getBorder
 815:    */
 816:   public void setBorder(Border newBorder)
 817:   {
 818:     Border oldBorder = border;
 819:     border = newBorder;
 820:     firePropertyChange("border", oldBorder, newBorder);
 821:   }
 822: 
 823:   /**
 824:    * Get the value of the {@link #border} property.
 825:    *
 826:    * @return The property's current value
 827:    *
 828:    * @see #setBorder
 829:    */
 830:   public Border getBorder()
 831:   {
 832:     return border;
 833:   }
 834: 
 835:   /**
 836:    * Get the component's current bounding box. If a rectangle is provided,
 837:    * use this as the return value (adjusting its fields in place);
 838:    * otherwise (of <code>null</code> is provided) return a new {@link
 839:    * Rectangle}.
 840:    *
 841:    * @param rv Optional return value to use
 842:    *
 843:    * @return A rectangle bounding the component
 844:    */
 845:   public Rectangle getBounds(Rectangle rv)
 846:   {
 847:     if (rv == null)
 848:       return new Rectangle(getX(), getY(), getWidth(), getHeight());
 849:     else
 850:       {
 851:         rv.setBounds(getX(), getY(), getWidth(), getHeight());
 852:         return rv;
 853:       }
 854:   }
 855: 
 856:   /**
 857:    * Prepares a graphics context for painting this object. If {@link
 858:    * #debugGraphicsOptions} is not equal to {@link
 859:    * DebugGraphics#NONE_OPTION}, produce a new {@link DebugGraphics} object
 860:    * wrapping the parameter. Otherwise configure the parameter with this
 861:    * component's foreground color and font.
 862:    *
 863:    * @param g The graphics context to wrap or configure
 864:    *
 865:    * @return A graphics context to paint this object with
 866:    *
 867:    * @see #debugGraphicsOptions
 868:    * @see #paint
 869:    */
 870:   protected Graphics getComponentGraphics(Graphics g)
 871:   {    
 872:     g.setFont (this.getFont());
 873:     g.setColor (this.getForeground());
 874:     return g;
 875:   }
 876: 
 877:   /**
 878:    * Get the value of the {@link #debugGraphicsOptions} property.
 879:    *
 880:    * @return The current value of the property.
 881:    *
 882:    * @see #setDebugGraphicsOptions
 883:    * @see #debugGraphicsOptions
 884:    */
 885:   public int getDebugGraphicsOptions()
 886:   {
 887:     return 0;
 888:   }
 889: 
 890:   /**
 891:    * Get the component's insets, which are calculated from
 892:    * the {@link #border} property. If the border is <code>null</code>,
 893:    * calls {@link Container#getInsets}.
 894:    *
 895:    * @return The component's current insets
 896:    */
 897:   public Insets getInsets()
 898:   {
 899:     if (border == null)
 900:       return super.getInsets();
 901:     return getBorder().getBorderInsets(this);
 902:   }
 903: 
 904:   /**
 905:    * Get the component's insets, which are calculated from the {@link
 906:    * #border} property. If the border is <code>null</code>, calls {@link
 907:    * Container#getInsets}. The passed-in {@link Insets} value will be
 908:    * used as the return value, if possible.
 909:    *
 910:    * @param insets Return value object to reuse, if possible
 911:    *
 912:    * @return The component's current insets
 913:    */
 914:   public Insets getInsets(Insets insets)
 915:   {
 916:     Insets t = getInsets();
 917: 
 918:     if (insets == null)
 919:       return t;
 920: 
 921:     insets.left = t.left;
 922:     insets.right = t.right;
 923:     insets.top = t.top;
 924:     insets.bottom = t.bottom;
 925:     return insets;
 926:   }
 927: 
 928:   /**
 929:    * Get the component's location. The passed-in {@link Point} value
 930:    * will be used as the return value, if possible.
 931:    *
 932:    * @param rv Return value object to reuse, if possible
 933:    *
 934:    * @return The component's current location
 935:    */
 936:   public Point getLocation(Point rv)
 937:   {
 938:     if (rv == null)
 939:       return new Point(getX(), getY());
 940: 
 941:     rv.setLocation(getX(), getY());
 942:     return rv;
 943:   }
 944: 
 945:   /**
 946:    * Get the component's maximum size. If the {@link #maximumSize} property
 947:    * has been explicitly set, it is returned. If the {@link #maximumSize}
 948:    * property has not been set but the {@link ui} property has been, the
 949:    * result of {@link ComponentUI#getMaximumSize} is returned. If neither
 950:    * property has been set, the result of {@link Container#getMaximumSize}
 951:    * is returned.
 952:    *
 953:    * @return The maximum size of the component
 954:    *
 955:    * @see #maximumSize
 956:    * @see #setMaximumSize
 957:    */
 958:   public Dimension getMaximumSize()
 959:   {
 960:     if (maximumSize != null)
 961:       return maximumSize;
 962: 
 963:     if (ui != null)
 964:       {
 965:         Dimension s = ui.getMaximumSize(this);
 966:         if (s != null)
 967:           return s;
 968:       }
 969: 
 970:     Dimension p = super.getMaximumSize();
 971:     return p;
 972:   }
 973: 
 974:   /**
 975:    * Get the component's minimum size. If the {@link #minimumSize} property
 976:    * has been explicitly set, it is returned. If the {@link #minimumSize}
 977:    * property has not been set but the {@link ui} property has been, the
 978:    * result of {@link ComponentUI#getMinimumSize} is returned. If neither
 979:    * property has been set, the result of {@link Container#getMinimumSize}
 980:    * is returned.
 981:    *
 982:    * @return The minimum size of the component
 983:    *
 984:    * @see #minimumSize
 985:    * @see #setMinimumSize
 986:    */
 987:   public Dimension getMinimumSize()
 988:   {
 989:     if (minimumSize != null)
 990:       return minimumSize;
 991: 
 992:     if (ui != null)
 993:       {
 994:         Dimension s = ui.getMinimumSize(this);
 995:         if (s != null)
 996:           return s;
 997:       }
 998: 
 999:     Dimension p = super.getMinimumSize();
1000:     return p;
1001:   }
1002: 
1003:   /**
1004:    * Get the component's preferred size. If the {@link #preferredSize}
1005:    * property has been explicitly set, it is returned. If the {@link
1006:    * #preferredSize} property has not been set but the {@link ui} property
1007:    * has been, the result of {@link ComponentUI#getPreferredSize} is
1008:    * returned. If neither property has been set, the result of {@link
1009:    * Container#getPreferredSize} is returned.
1010:    *
1011:    * @return The preferred size of the component
1012:    *
1013:    * @see #preferredSize
1014:    * @see #setPreferredSize
1015:    */
1016:   public Dimension getPreferredSize()
1017:   {
1018:     Dimension prefSize = null;
1019:     if (preferredSize != null)
1020:       prefSize = preferredSize;
1021: 
1022:     else if (ui != null)
1023:       {
1024:         Dimension s = ui.getPreferredSize(this);
1025:         if (s != null)
1026:           prefSize = s;
1027:       }
1028: 
1029:     if (prefSize == null)
1030:       prefSize = super.getPreferredSize();
1031:     // make sure that prefSize is not smaller than minSize
1032:     if (minimumSize != null && prefSize != null
1033:         && (minimumSize.width > prefSize.width
1034:             || minimumSize.height > prefSize.height))
1035:         prefSize = new Dimension(Math.max(minimumSize.width, prefSize.width),
1036:                                  Math.max(minimumSize.height, prefSize.height));
1037:     return prefSize;
1038:   }
1039: 
1040:   /**
1041:    * Checks if a maximum size was explicitely set on the component.
1042:    *
1043:    * @return <code>true</code> if a maximum size was set,
1044:    * <code>false</code> otherwise
1045:    * 
1046:    * @since 1.3
1047:    */
1048:   public boolean isMaximumSizeSet()
1049:   {
1050:     return maximumSize != null;
1051:   }
1052: 
1053:   /**
1054:    * Checks if a minimum size was explicitely set on the component.
1055:    *
1056:    * @return <code>true</code> if a minimum size was set,
1057:    * <code>false</code> otherwise
1058:    * 
1059:    * @since 1.3
1060:    */
1061:   public boolean isMinimumSizeSet()
1062:   {
1063:     return minimumSize != null;
1064:   }
1065: 
1066:   /**
1067:    * Checks if a preferred size was explicitely set on the component.
1068:    *
1069:    * @return <code>true</code> if a preferred size was set,
1070:    * <code>false</code> otherwise
1071:    * 
1072:    * @since 1.3
1073:    */
1074:   public boolean isPreferredSizeSet()
1075:   {
1076:     return preferredSize != null;
1077:   }
1078:   
1079:   /**
1080:    * Return the value of the {@link #nextFocusableComponent} property.
1081:    *
1082:    * @return The current value of the property, or <code>null</code>
1083:    * if none has been set.
1084:    * 
1085:    * @deprecated See {@link java.awt.FocusTraversalPolicy}
1086:    */
1087:   public Component getNextFocusableComponent()
1088:   {
1089:     return null;
1090:   }
1091: 
1092:   /**
1093:    * Return the set of {@link KeyStroke} objects which are registered
1094:    * to initiate actions on this component.
1095:    *
1096:    * @return An array of the registered keystrokes
1097:    */
1098:   public KeyStroke[] getRegisteredKeyStrokes()
1099:   {
1100:     return null;
1101:   }
1102: 
1103:   /**
1104:    * Returns the first ancestor of this component which is a {@link JRootPane}.
1105:    * Equivalent to calling <code>SwingUtilities.getRootPane(this);</code>.
1106:    *
1107:    * @return An ancestral JRootPane, or <code>null</code> if none exists.
1108:    */
1109:   public JRootPane getRootPane()
1110:   {
1111:     JRootPane p = SwingUtilities.getRootPane(this);
1112:     return p;
1113:   }
1114: 
1115:   /**
1116:    * Get the component's size. The passed-in {@link Dimension} value
1117:    * will be used as the return value, if possible.
1118:    *
1119:    * @param rv Return value object to reuse, if possible
1120:    *
1121:    * @return The component's current size
1122:    */
1123:   public Dimension getSize(Dimension rv)
1124:   {
1125:     if (rv == null)
1126:       return new Dimension(getWidth(), getHeight());
1127:     else
1128:       {
1129:         rv.setSize(getWidth(), getHeight());
1130:         return rv;
1131:       }
1132:   }
1133: 
1134:   /**
1135:    * Return the {@link #toolTip} property of this component, creating it and
1136:    * setting it if it is currently <code>null</code>. This method can be
1137:    * overridden in subclasses which wish to control the exact form of
1138:    * tooltip created.
1139:    *
1140:    * @return The current toolTip
1141:    */
1142:   public JToolTip createToolTip()
1143:   {
1144:     JToolTip toolTip = new JToolTip();
1145:     toolTip.setComponent(this);
1146:     toolTip.setTipText(toolTipText);
1147: 
1148:     return toolTip;
1149:   }
1150: 
1151:   /**
1152:    * Return the location at which the {@link #toolTip} property should be
1153:    * displayed, when triggered by a particular mouse event. 
1154:    *
1155:    * @param event The event the tooltip is being presented in response to
1156:    *
1157:    * @return The point at which to display a tooltip, or <code>null</code>
1158:    *     if swing is to choose a default location.
1159:    */
1160:   public Point getToolTipLocation(MouseEvent event)
1161:   {
1162:     return null;
1163:   }
1164: 
1165:   /**
1166:    * Set the value of the {@link #toolTipText} property.
1167:    *
1168:    * @param text The new property value
1169:    *
1170:    * @see #getToolTipText
1171:    */
1172:   public void setToolTipText(String text)
1173:   {
1174:     if (text == null)
1175:     {
1176:       ToolTipManager.sharedInstance().unregisterComponent(this);
1177:       toolTipText = null;
1178:       return;
1179:     }
1180: 
1181:     // XXX: The tip text doesn't get updated unless you set it to null
1182:     // and then to something not-null. This is consistent with the behaviour
1183:     // of Sun's ToolTipManager.
1184: 
1185:     String oldText = toolTipText;
1186:     toolTipText = text;
1187: 
1188:     if (oldText == null)
1189:       ToolTipManager.sharedInstance().registerComponent(this);
1190:   }
1191: 
1192:   /**
1193:    * Get the value of the {@link #toolTipText} property.
1194:    *
1195:    * @return The current property value
1196:    *
1197:    * @see #setToolTipText
1198:    */
1199:   public String getToolTipText()
1200:   {
1201:     return toolTipText;
1202:   }
1203: 
1204:   /**
1205:    * Get the value of the {@link #toolTipText} property, in response to a
1206:    * particular mouse event.
1207:    *
1208:    * @param event The mouse event which triggered the tooltip
1209:    *
1210:    * @return The current property value
1211:    *
1212:    * @see #setToolTipText
1213:    */
1214:   public String getToolTipText(MouseEvent event)
1215:   {
1216:     return getToolTipText();
1217:   }
1218: 
1219:   /**
1220:    * Return the top level ancestral container (usually a {@link
1221:    * java.awt.Window} or {@link java.awt.Applet}) which this component is
1222:    * contained within, or <code>null</code> if no ancestors exist.
1223:    *
1224:    * @return The top level container, if it exists
1225:    */
1226:   public Container getTopLevelAncestor()
1227:   {
1228:     Container c = getParent();
1229:     for (Container peek = c; peek != null; peek = peek.getParent())
1230:       c = peek;
1231:     return c;
1232:   }
1233: 
1234:   /**
1235:    * Compute the component's visible rectangle, which is defined
1236:    * recursively as either the component's bounds, if it has no parent, or
1237:    * the intersection of the component's bounds with the visible rectangle
1238:    * of its parent.
1239:    *
1240:    * @param rect The return value slot to place the visible rectangle in
1241:    */
1242:   public void computeVisibleRect(Rectangle rect)
1243:   {
1244:     Component c = getParent();
1245:     if (c != null && c instanceof JComponent)
1246:       {
1247:         ((JComponent) c).computeVisibleRect(rect);
1248:         rect.translate(-getX(), -getY());
1249:         Rectangle2D.intersect(rect,
1250:                               new Rectangle(0, 0, getWidth(), getHeight()),
1251:                               rect);
1252:       }
1253:     else
1254:       rect.setRect(0, 0, getWidth(), getHeight());
1255:   }
1256: 
1257:   /**
1258:    * Return the component's visible rectangle in a new {@link Rectangle},
1259:    * rather than via a return slot.
1260:    *
1261:    * @return The component's visible rectangle
1262:    *
1263:    * @see #computeVisibleRect(Rectangle)
1264:    */
1265:   public Rectangle getVisibleRect()
1266:   {
1267:     Rectangle r = new Rectangle();
1268:     computeVisibleRect(r);
1269:     return r;
1270:   }
1271: 
1272:   /**
1273:    * <p>Requests that this component receive input focus, giving window
1274:    * focus to the top level ancestor of this component. Only works on
1275:    * displayable, focusable, visible components.</p>
1276:    *
1277:    * <p>This method should not be called by clients; it is intended for
1278:    * focus implementations. Use {@link Component#requestFocus} instead.</p>
1279:    *
1280:    * @see {@link Component#requestFocus}
1281:    */
1282:   public void grabFocus()
1283:   {
1284:   }
1285: 
1286:   /**
1287:    * Get the value of the {@link #doubleBuffered} property.
1288:    *
1289:    * @return The property's current value
1290:    */
1291:   public boolean isDoubleBuffered()
1292:   {
1293:     return doubleBuffered;
1294:   }
1295: 
1296:   /**
1297:    * Return <code>true</code> if the provided component has no native peer;
1298:    * in other words, if it is a "lightweight component".
1299:    *
1300:    * @param c The component to test for lightweight-ness
1301:    *
1302:    * @return Whether or not the component is lightweight
1303:    */
1304:   public static boolean isLightweightComponent(Component c)
1305:   {
1306:     return c.getPeer() instanceof LightweightPeer;
1307:   }
1308: 
1309:   /**
1310:    * Return <code>true</code> if you wish this component to manage its own
1311:    * focus. In particular: if you want this component to be sent
1312:    * <code>TAB</code> and <code>SHIFT+TAB</code> key events, and to not
1313:    * have its children considered as focus transfer targets. If
1314:    * <code>true</code>, focus traversal around this component changes to
1315:    * <code>CTRL+TAB</code> and <code>CTRL+SHIFT+TAB</code>.
1316:    *
1317:    * @return <code>true</code> if you want this component to manage its own
1318:    *     focus, otherwise (by default) <code>false</code>
1319:    *
1320:    * @deprecated 1.4 Use {@link Component.setFocusTraversalKeys(int,Set)} and
1321:    *     {@link Container.setFocusCycleRoot(boolean)} instead
1322:    */
1323:   public boolean isManagingFocus()
1324:   {
1325:     return false;
1326:   }
1327: 
1328:   /**
1329:    * Return the current value of the {@link opaque} property. 
1330:    *
1331:    * @return The current property value
1332:    */
1333:   public boolean isOpaque()
1334:   {
1335:     return opaque;
1336:   }
1337: 
1338:   /**
1339:    * Return <code>true</code> if the component can guarantee that none of its
1340:    * children will overlap in Z-order. This is a hint to the painting system.
1341:    * The default is to return <code>true</code>, but some components such as
1342:    * {@link JLayeredPane} should override this to return <code>false</code>.
1343:    *
1344:    * @return Whether the component tiles its children
1345:    */
1346:   public boolean isOptimizedDrawingEnabled()
1347:   {
1348:     return true;
1349:   }
1350: 
1351:   /**
1352:    * Return <code>true</code> if this component is currently painting a tile.
1353:    *
1354:    * @return Whether the component is painting a tile
1355:    */
1356:   public boolean isPaintingTile()
1357:   {
1358:     return false;
1359:   }
1360: 
1361:   /**
1362:    * Get the value of the {@link #requestFocusEnabled} property.
1363:    *
1364:    * @return The current value of the property
1365:    */
1366:   public boolean isRequestFocusEnabled()
1367:   {
1368:     return requestFocusEnabled;
1369:   }
1370: 
1371:   /**
1372:    * Return <code>true</code> if this component is a validation root; this
1373:    * will cause calls to {@link #invalidate} in this component's children
1374:    * to be "captured" at this component, and not propagate to its parents.
1375:    * For most components this should return <code>false</code>, but some
1376:    * components such as {@link JViewPort} will want to return
1377:    * <code>true</code>.
1378:    *
1379:    * @return Whether this component is a validation root
1380:    */
1381:   public boolean isValidateRoot()
1382:   {
1383:     return false;
1384:   }
1385: 
1386:   /**
1387:    * <p>Paint the component. This is a delicate process, and should only be
1388:    * called from the repaint thread, under control of the {@link
1389:    * RepaintManager}. Client code should usually call {@link #repaint} to
1390:    * trigger painting.</p>
1391:    *
1392:    * <p>This method will acquire a double buffer from the {@link
1393:    * RepaintManager} if the component's {@link #doubleBuffered} property is
1394:    * <code>true</code> and the <code>paint</code> call is the
1395:    * <em>first</em> recursive <code>paint</code> call inside swing.</p>
1396:    *
1397:    * <p>The method will also modify the provided {@link Graphics} context
1398:    * via the {@link #getComponentGraphics} method. If you want to customize
1399:    * the graphics object used for painting, you should override that method
1400:    * rather than <code>paint</code>.</p>
1401:    *
1402:    * <p>The body of the <code>paint</code> call involves calling {@link
1403:    * #paintComponent}, {@link #paintBorder}, and {@link #paintChildren} in
1404:    * order. If you want to customize painting behavior, you should override
1405:    * one of these methods rather than <code>paint</code>.</p>
1406:    *
1407:    * <p>For more details on the painting sequence, see <a
1408:    * href="http://java.sun.com/products/jfc/tsc/articles/painting/index.html">
1409:    * this article</a>.</p>
1410:    *
1411:    * @param g The graphics context to paint with
1412:    *
1413:    * @see #paintImmediately
1414:    */
1415:   public void paint(Graphics g)
1416:   {
1417:     Graphics g2 = g;
1418:     Image doubleBuffer = null;
1419:     RepaintManager rm = RepaintManager.currentManager(this);
1420: 
1421:     if (isDoubleBuffered()
1422:         && (rm.isDoubleBufferingEnabled())
1423:         && (! Thread.holdsLock(paintLock)))
1424:       {
1425:         doubleBuffer = rm.getOffscreenBuffer(this, getWidth(), getHeight());
1426:       }
1427: 
1428:     synchronized (paintLock)
1429:       {
1430:         if (doubleBuffer != null)
1431:           {
1432:             g2 = doubleBuffer.getGraphics();
1433:             g2.setClip(g.getClipBounds());
1434:           }
1435:           
1436:         g2 = getComponentGraphics(g2);
1437:         paintComponent(g2);
1438:         paintBorder(g2);
1439:         paintChildren(g2);
1440:         
1441:         if (doubleBuffer != null)
1442:           g.drawImage(doubleBuffer, 0, 0, (ImageObserver) null);
1443:       }
1444:   }
1445: 
1446:   /**
1447:    * Paint the component's border. This usually means calling {@link
1448:    * Border#paintBorder} on the {@link #border} property, if it is
1449:    * non-<code>null</code>. You may override this if you wish to customize
1450:    * border painting behavior. The border is painted after the component's
1451:    * body, but before the component's children.
1452:    *
1453:    * @param g The graphics context with which to paint the border
1454:    *
1455:    * @see #paint
1456:    * @see #paintChildren
1457:    * @see #paintComponent
1458:    */
1459:   protected void paintBorder(Graphics g)
1460:   {
1461:     if (getBorder() != null)
1462:       getBorder().paintBorder(this, g, 0, 0, getWidth(), getHeight());
1463:   }
1464: 
1465:   /**
1466:    * Paint the component's children. This usually means calling {@link
1467:    * Container#paint}, which recursively calls {@link #paint} on any of the
1468:    * component's children, with appropriate changes to coordinate space and
1469:    * clipping region. You may override this if you wish to customize
1470:    * children painting behavior. The children are painted after the
1471:    * component's body and border.
1472:    *
1473:    * @param g The graphics context with which to paint the children
1474:    *
1475:    * @see #paint
1476:    * @see #paintBorder
1477:    * @see #paintComponent
1478:    */
1479:   protected void paintChildren(Graphics g)
1480:   {
1481:     super.paint(g);
1482:   }
1483: 
1484:   /**
1485:    * Paint the component's body. This usually means calling {@link
1486:    * ComponentUI#update} on the {@link #ui} property of the component, if
1487:    * it is non-<code>null</code>. You may override this if you wish to
1488:    * customize the component's body-painting behavior. The component's body
1489:    * is painted first, before the border and children.
1490:    *
1491:    * @param g The graphics context with which to paint the body
1492:    *
1493:    * @see #paint
1494:    * @see #paintBorder
1495:    * @see #paintChildren
1496:    */
1497:   protected void paintComponent(Graphics g)
1498:   {
1499:     if (ui != null)
1500:       {
1501:         Graphics g2 = g;
1502:         if (!(g instanceof Graphics2D))
1503:           g2 = g.create();
1504:         ui.update(getComponentGraphics(g2), this);
1505:         if (!(g instanceof Graphics2D))
1506:           g2.dispose();
1507:       }
1508:   }
1509: 
1510:   /**
1511:    * A variant of {@link #paintImmediately(Rectangle)} which takes
1512:    * integer parameters.
1513:    *
1514:    * @param x The left x coordinate of the dirty region
1515:    * @param y The top y coordinate of the dirty region
1516:    * @param w The width of the dirty region
1517:    * @param h The height of the dirty region
1518:    */
1519:   public void paintImmediately(int x, int y, int w, int h)
1520:   {
1521:     paintImmediately(new Rectangle(x, y, w, h));
1522:   }
1523: 
1524:   /**
1525:    * Transform the provided dirty rectangle for this component into the
1526:    * appropriate ancestral {@link JRootPane} and call {@link #paint} on
1527:    * that root pane. This method is called from the {@link RepaintManager}
1528:    * and should always be called within the painting thread.
1529:    *
1530:    * @param r The dirty rectangle to paint
1531:    */
1532:   public void paintImmediately(Rectangle r)
1533:   {
1534:     Component root = SwingUtilities.getRoot(this);
1535:     if (root == null || ! root.isShowing())
1536:       return;
1537:     Graphics g = root.getGraphics();
1538:     if (g == null)
1539:       return;
1540: 
1541:     Rectangle clip = SwingUtilities.convertRectangle(this, r, root);
1542:     g.setClip(clip);
1543:     root.paint(g);
1544:     g.dispose();
1545:   }
1546: 
1547:   /**
1548:    * Return a string representation for this component, for use in
1549:    * debugging.
1550:    *
1551:    * @return A string describing this component.
1552:    */
1553:   protected String paramString()
1554:   {
1555:     StringBuffer sb = new StringBuffer();
1556:     sb.append(super.paramString());
1557:     sb.append(",alignmentX=").append(getAlignmentX());
1558:     sb.append(",alignmentY=").append(getAlignmentY());
1559:     sb.append(",border=");
1560:     if (getBorder() != null)
1561:       sb.append(getBorder());
1562:     sb.append(",maximumSize=");
1563:     if (getMaximumSize() != null)
1564:       sb.append(getMaximumSize());
1565:     sb.append(",minimumSize=");
1566:     if (getMinimumSize() != null)
1567:       sb.append(getMinimumSize());
1568:     sb.append(",preferredSize=");
1569:     if (getPreferredSize() != null)
1570:       sb.append(getPreferredSize());
1571:     return sb.toString();
1572:   }
1573: 
1574:   /**
1575:    * A variant of {@link
1576:    * #registerKeyboardAction(ActionListener,String,KeyStroke,int)} which
1577:    * provides <code>null</code> for the command name.   
1578:    */
1579:   public void registerKeyboardAction(ActionListener act,
1580:                                      KeyStroke stroke, 
1581:                                      int cond)
1582:   {
1583:     registerKeyboardAction(act, null, stroke, cond);
1584:   }
1585: 
1586:   /* 
1587:    * There is some charmingly undocumented behavior sun seems to be using
1588:    * to simulate the old register/unregister keyboard binding API. It's not
1589:    * clear to me why this matters, but we shall endeavour to follow suit.
1590:    *
1591:    * Two main thing seem to be happening when you do registerKeyboardAction():
1592:    * 
1593:    *  - no actionMap() entry gets created, just an entry in inputMap()
1594:    *
1595:    *  - the inputMap() entry is a proxy class which invokes the the
1596:    *  binding's actionListener as a target, and which clobbers the command
1597:    *  name sent in the ActionEvent, providing the binding command name
1598:    *  instead.
1599:    *
1600:    * This much you can work out just by asking the input and action maps
1601:    * what they contain after making bindings, and watching the event which
1602:    * gets delivered to the recipient. Beyond that, it seems to be a
1603:    * sun-private solution so I will only immitate it as much as it matters
1604:    * to external observers.
1605:    */
1606:   private static class ActionListenerProxy
1607:     extends AbstractAction
1608:   {
1609:     ActionListener target;
1610:     String bindingCommandName;
1611: 
1612:     public ActionListenerProxy(ActionListener li, 
1613:                                String cmd)
1614:     {
1615:       target = li;
1616:       bindingCommandName = cmd;
1617:     }
1618: 
1619:     public void actionPerformed(ActionEvent e)
1620:     {
1621:       ActionEvent derivedEvent = new ActionEvent(e.getSource(),
1622:                                                  e.getID(),
1623:                                                  bindingCommandName,
1624:                                                  e.getModifiers());
1625:       target.actionPerformed(derivedEvent);
1626:     }
1627:   }
1628: 
1629:   
1630:   /**
1631:    * An obsolete method to register a keyboard action on this component.
1632:    * You should use <code>getInputMap</code> and <code>getActionMap</code>
1633:    * to fetch mapping tables from keystrokes to commands, and commands to
1634:    * actions, respectively, and modify those mappings directly.
1635:    *
1636:    * @param anAction The action to be registered
1637:    * @param aCommand The command to deliver in the delivered {@link
1638:    *     java.awt.ActionEvent}
1639:    * @param aKeyStroke The keystroke to register on
1640:    * @param aCondition One of the values {@link #UNDEFINED_CONDITION},
1641:    *     {@link #WHEN_ANCESTOR_OF_FOCUSED_COMPONENT}, {@link #WHEN_FOCUSED}, or
1642:    *     {@link #WHEN_IN_FOCUSED_WINDOW}, indicating the condition which must
1643:    *     be met for the action to be fired
1644:    *
1645:    * @see #unregisterKeyboardAction
1646:    * @see #getConditionForKeystroke
1647:    * @see #resetKeyboardActiond
1648:    */
1649:   public void registerKeyboardAction(ActionListener act, 
1650:                                      String cmd,
1651:                                      KeyStroke stroke, 
1652:                                      int cond)
1653:   {
1654:     getInputMap(cond).put(stroke, new ActionListenerProxy(act, cmd));
1655:   }
1656: 
1657:   public final void setInputMap(int condition, InputMap map)
1658:   {
1659:     enableEvents(AWTEvent.KEY_EVENT_MASK);
1660:     switch (condition)
1661:       {
1662:       case WHEN_FOCUSED:
1663:         inputMap_whenFocused = map;
1664:         break;
1665: 
1666:       case WHEN_ANCESTOR_OF_FOCUSED_COMPONENT:
1667:         inputMap_whenAncestorOfFocused = map;
1668:         break;
1669: 
1670:       case WHEN_IN_FOCUSED_WINDOW:
1671:         inputMap_whenInFocusedWindow = map;
1672:         break;
1673:         
1674:       case UNDEFINED_CONDITION:
1675:       default:
1676:         throw new IllegalArgumentException();
1677:       }
1678:   }
1679: 
1680:   public final InputMap getInputMap(int condition)
1681:   {
1682:     enableEvents(AWTEvent.KEY_EVENT_MASK);
1683:     switch (condition)
1684:       {
1685:       case WHEN_FOCUSED:
1686:         if (inputMap_whenFocused == null)
1687:           inputMap_whenFocused = new InputMap();
1688:         return inputMap_whenFocused;
1689: 
1690:       case WHEN_ANCESTOR_OF_FOCUSED_COMPONENT:
1691:         if (inputMap_whenAncestorOfFocused == null)
1692:           inputMap_whenAncestorOfFocused = new InputMap();
1693:         return inputMap_whenAncestorOfFocused;
1694: 
1695:       case WHEN_IN_FOCUSED_WINDOW:
1696:         if (inputMap_whenInFocusedWindow == null)
1697:           inputMap_whenInFocusedWindow = new InputMap();
1698:         return inputMap_whenInFocusedWindow;
1699: 
1700:       case UNDEFINED_CONDITION:
1701:       default:
1702:         return null;
1703:       }
1704:   }
1705: 
1706:   public final InputMap getInputMap()
1707:   {
1708:     return getInputMap(WHEN_FOCUSED);
1709:   }
1710: 
1711:   public final ActionMap getActionMap()
1712:   {
1713:     if (actionMap == null)
1714:       actionMap = new ActionMap();
1715:     return actionMap;
1716:   }
1717: 
1718:   public final void setActionMap(ActionMap map)
1719:   {
1720:     actionMap = map;
1721:   }
1722: 
1723:   /**
1724:    * Return the condition that determines whether a registered action
1725:    * occurs in response to the specified keystroke.
1726:    *
1727:    * @param aKeyStroke The keystroke to return the condition of
1728:    *
1729:    * @return One of the values {@link #UNDEFINED_CONDITION}, {@link
1730:    *     #WHEN_ANCESTOR_OF_FOCUSED_COMPONENT}, {@link #WHEN_FOCUSED}, or {@link
1731:    *     #WHEN_IN_FOCUSED_WINDOW}
1732:    *
1733:    * @deprecated As of 1.3 KeyStrokes can be registered with multiple
1734:    *     simultaneous conditions.
1735:    *
1736:    * @see #registerKeyboardAction   
1737:    * @see #unregisterKeyboardAction   
1738:    * @see #resetKeyboardActiond
1739:    */
1740:   public int getConditionForKeyStroke(KeyStroke ks)
1741:   {
1742:     if (inputMap_whenFocused != null 
1743:         && inputMap_whenFocused.get(ks) != null)
1744:       return WHEN_FOCUSED;
1745:     else if (inputMap_whenAncestorOfFocused != null 
1746:              && inputMap_whenAncestorOfFocused.get(ks) != null)
1747:       return WHEN_ANCESTOR_OF_FOCUSED_COMPONENT;
1748:     else if (inputMap_whenInFocusedWindow != null 
1749:              && inputMap_whenInFocusedWindow.get(ks) != null)
1750:       return WHEN_IN_FOCUSED_WINDOW;
1751:     else
1752:       return UNDEFINED_CONDITION;
1753:   }
1754: 
1755:   /**
1756:    * Get the ActionListener (typically an {@link Action} object) which is
1757:    * associated with a particular keystroke. 
1758:    *
1759:    * @param aKeyStroke The keystroke to retrieve the action of
1760:    *
1761:    * @return The action associated with the specified keystroke
1762:    *
1763:    * @deprecated Use {@link #getActionMap()}
1764:    */
1765:   public ActionListener getActionForKeyStroke(KeyStroke ks)
1766:   {
1767:     Object cmd = getInputMap().get(ks);
1768:     if (cmd != null)
1769:       {
1770:         if (cmd instanceof ActionListenerProxy)
1771:           return (ActionListenerProxy) cmd;
1772:         else if (cmd instanceof String)
1773:           return getActionMap().get(cmd);
1774:       }
1775:     return null;
1776:   }
1777: 
1778:   /**
1779:    * A hook for subclasses which want to customize event processing.
1780:    */
1781:   protected void processComponentKeyEvent(KeyEvent e)
1782:   {
1783:   }
1784: 
1785:   /**
1786:    * Override the default key dispatch system from Component to hook into
1787:    * the swing {@link InputMap} / {@link ActionMap} system.
1788:    *
1789:    * See <a
1790:    * href="http://java.sun.com/products/jfc/tsc/special_report/kestrel/keybindings.html">
1791:    * this report</a> for more details, it's somewhat complex.
1792:    */
1793:   protected void processKeyEvent(KeyEvent e)
1794:   {
1795:     // let the AWT event processing send KeyEvents to registered listeners
1796:     super.processKeyEvent(e);
1797:     processComponentKeyEvent(e);
1798: 
1799:     // FIXME: this needs to be elaborated significantly, to do all the
1800:     // focus / ancestor / window searching for the various binding modes.
1801:     if (! e.isConsumed() &&
1802:         processKeyBinding(KeyStroke.getKeyStrokeForEvent(e), 
1803:                           e, WHEN_FOCUSED, e.getID() == KeyEvent.KEY_PRESSED))
1804:       e.consume();
1805:   }
1806: 
1807:   protected boolean processKeyBinding(KeyStroke ks,
1808:                                       KeyEvent e,
1809:                                       int condition,
1810:                                       boolean pressed)
1811:   { 
1812:     if (isEnabled())
1813:       {
1814:         Action act = null;
1815:         InputMap map = getInputMap(condition);
1816:         if (map != null)
1817:           {
1818:             Object cmd = map.get(ks);
1819:             if (cmd != null)
1820:               {
1821:                 if (cmd instanceof ActionListenerProxy)
1822:                   act = (Action) cmd;
1823:                 else 
1824:                   act = (Action) getActionMap().get(cmd);
1825:               }
1826:           }
1827:         if (act != null && act.isEnabled())
1828:           return SwingUtilities.notifyAction(act, ks, e, this, e.getModifiers());
1829:       }
1830:     return false;
1831:   }
1832:   
1833:   /**
1834:    * Remove a keyboard action registry.
1835:    *
1836:    * @param stroke The keystroke to unregister
1837:    *
1838:    * @see #registerKeyboardAction
1839:    * @see #getConditionForKeystroke
1840:    * @see #resetKeyboardActiond
1841:    */
1842:   public void unregisterKeyboardAction(KeyStroke aKeyStroke)
1843:   {
1844:     // FIXME: Must be implemented.
1845:   }
1846: 
1847: 
1848:   /**
1849:    * Reset all keyboard action registries.
1850:    *
1851:    * @see #registerKeyboardAction
1852:    * @see #unregisterKeyboardAction
1853:    * @see #getConditionForKeystroke
1854:    */
1855:   public void resetKeyboardActions()
1856:   {
1857:     if (inputMap_whenFocused != null)
1858:       inputMap_whenFocused.clear();
1859:     if (inputMap_whenAncestorOfFocused != null)
1860:       inputMap_whenAncestorOfFocused.clear();
1861:     if (inputMap_whenInFocusedWindow != null)
1862:       inputMap_whenInFocusedWindow.clear();
1863:     if (actionMap != null)
1864:       actionMap.clear();
1865:   }
1866: 
1867:   /**
1868:    * Mark the described region of this component as dirty in the current
1869:    * {@link RepaintManager}. This will queue an asynchronous repaint using
1870:    * the system painting thread in the near future.
1871:    *
1872:    * @param tm ignored
1873:    * @param x coordinate of the region to mark as dirty
1874:    * @param y coordinate of the region to mark as dirty
1875:    * @param width dimension of the region to mark as dirty
1876:    * @param height dimension of the region to mark as dirty
1877:    */
1878:   public void repaint(long tm, int x, int y, int width, int height)
1879:   {
1880:     Rectangle dirty = new Rectangle(x, y, width, height);
1881:     Rectangle vis = getVisibleRect();
1882:     dirty = dirty.intersection(vis);
1883:     RepaintManager.currentManager(this).addDirtyRegion(this, dirty.x, dirty.y,
1884:                                                        dirty.width,
1885:                                                        dirty.height);
1886:   }
1887: 
1888:   /**
1889:    * Mark the described region of this component as dirty in the current
1890:    * {@link RepaintManager}. This will queue an asynchronous repaint using
1891:    * the system painting thread in the near future.
1892:    *
1893:    * @param r The rectangle to mark as dirty
1894:    */
1895:   public void repaint(Rectangle r)
1896:   {
1897:     repaint((long) 0, (int) r.getX(), (int) r.getY(), (int) r.getWidth(),
1898:             (int) r.getHeight());
1899:   }
1900: 
1901:   /**
1902:    * Request focus on the default component of this component's {@link
1903:    * FocusTraversalPolicy}.
1904:    *
1905:    * @return The result of {@link #requestFocus}
1906:    *
1907:    * @deprecated Use {@link #requestFocus()} on the default component provided
1908:    *     from the {@link FocusTraversalPolicy} instead.
1909:    */
1910:   public boolean requestDefaultFocus()
1911:   {
1912:     return false;
1913:   }
1914: 
1915:   /**
1916:    * Queue a an invalidation and revalidation of this component, using 
1917:    * {@link RepaintManager#addInvalidComponent}.
1918:    */
1919:   public void revalidate()
1920:   {
1921:     invalidate();
1922:     RepaintManager.currentManager(this).addInvalidComponent(this);
1923:   }
1924: 
1925:   /**
1926:    * Calls <code>scrollRectToVisible</code> on the component's parent. 
1927:    * Components which can service this call should override.
1928:    *
1929:    * @param r The rectangle to make visible
1930:    */
1931:   public void scrollRectToVisible(Rectangle r)
1932:   {
1933:     Component p = getParent();
1934:     if (p instanceof JComponent)
1935:       ((JComponent) p).scrollRectToVisible(r);
1936:   }
1937: 
1938:   /**
1939:    * Set the value of the {@link #alignmentX} property.
1940:    *
1941:    * @param a The new value of the property
1942:    */
1943:   public void setAlignmentX(float a)
1944:   {
1945:     alignmentX = a;
1946:   }
1947: 
1948:   /**
1949:    * Set the value of the {@link #alignmentY} property.
1950:    *
1951:    * @param a The new value of the property
1952:    */
1953:   public void setAlignmentY(float a)
1954:   {
1955:     alignmentY = a;
1956:   }
1957: 
1958:   /**
1959:    * Set the value of the {@link #autoscrolls} property.
1960:    *
1961:    * @param a The new value of the property
1962:    */
1963:   public void setAutoscrolls(boolean a)
1964:   {
1965:     autoscrolls = a;
1966:   }
1967: 
1968:   /**
1969:    * Set the value of the {@link #debugGraphicsOptions} property.
1970:    *
1971:    * @param debugOptions The new value of the property
1972:    */
1973:   public void setDebugGraphicsOptions(int debugOptions)
1974:   {
1975:     debugGraphicsOptions = debugOptions;
1976:   }
1977: 
1978:   /**
1979:    * Set the value of the {@link #doubleBuffered} property.
1980:    *
1981:    * @param db The new value of the property
1982:    */
1983:   public void setDoubleBuffered(boolean db)
1984:   {
1985:     doubleBuffered = db;
1986:   }
1987: 
1988:   /**
1989:    * Set the value of the {@link #enabled} property.
1990:    *
1991:    * @param enable The new value of the property
1992:    */
1993:   public void setEnabled(boolean enable)
1994:   {
1995:     boolean oldEnabled = isEnabled();
1996:     super.setEnabled(enable);
1997:     firePropertyChange("enabled", oldEnabled, enable);
1998:   }
1999: 
2000:   /**
2001:    * Set the value of the {@link #font} property.
2002:    *
2003:    * @param f The new value of the property
2004:    */
2005:   public void setFont(Font f)
2006:   {
2007:     super.setFont(f);
2008:   }
2009: 
2010:   /**
2011:    * Set the value of the {@link #background} property.
2012:    *
2013:    * @param bg The new value of the property
2014:    */
2015:   public void setBackground(Color bg)
2016:   {
2017:     super.setBackground(bg);
2018:   }
2019: 
2020:   /**
2021:    * Set the value of the {@link #foreground} property.
2022:    *
2023:    * @param fg The new value of the property
2024:    */
2025:   public void setForeground(Color fg)
2026:   {
2027:     super.setForeground(fg);
2028:   }
2029: 
2030:   /**
2031:    * Set the value of the {@link #maximumSize} property.
2032:    *
2033:    * @param max The new value of the property
2034:    */
2035:   public void setMaximumSize(Dimension max)
2036:   {
2037:     Dimension oldMaximumSize = maximumSize;
2038:     maximumSize = max;
2039:     firePropertyChange("maximumSize", oldMaximumSize, maximumSize);
2040:   }
2041: 
2042:   /**
2043:    * Set the value of the {@link #minimumSize} property.
2044:    *
2045:    * @param min The new value of the property
2046:    */
2047:   public void setMinimumSize(Dimension min)
2048:   {
2049:     Dimension oldMinimumSize = minimumSize;
2050:     minimumSize = min;
2051:     firePropertyChange("minimumSize", oldMinimumSize, minimumSize);
2052:   }
2053: 
2054:   /**
2055:    * Set the value of the {@link #preferredSize} property.
2056:    *
2057:    * @param pref The new value of the property
2058:    */
2059:   public void setPreferredSize(Dimension pref)
2060:   {
2061:     Dimension oldPreferredSize = preferredSize;
2062:     preferredSize = pref;
2063:     firePropertyChange("preferredSize", oldPreferredSize, preferredSize);
2064:   }
2065: 
2066:   /**
2067:    * Set the specified component to be the next component in the 
2068:    * focus cycle, overriding the {@link FocusTraversalPolicy} for
2069:    * this component.
2070:    *
2071:    * @param aComponent The component to set as the next focusable
2072:    *
2073:    * @deprecated Use FocusTraversalPolicy instead
2074:    */
2075:   public void setNextFocusableComponent(Component aComponent)
2076:   {
2077:   }
2078: 
2079:   /**
2080:    * Set the value of the {@link #requestFocusEnabled} property.
2081:    *
2082:    * @param e The new value of the property
2083:    */
2084:   public void setRequestFocusEnabled(boolean e)
2085:   {
2086:     requestFocusEnabled = e;
2087:   }
2088: 
2089:   /**
2090:    * Get the value of the {@link #transferHandler} property.
2091:    *
2092:    * @return The current value of the property
2093:    *
2094:    * @see ComponentUI#setTransferHandler
2095:    */
2096: 
2097:   public TransferHandler getTransferHandler()
2098:   {
2099:     return transferHandler;
2100:   }
2101: 
2102:   /**
2103:    * Set the value of the {@link #transferHandler} property.
2104:    *
2105:    * @param newHandler The new value of the property
2106:    *
2107:    * @see ComponentUI#getTransferHandler
2108:    */
2109: 
2110:   public void setTransferHandler(TransferHandler newHandler)
2111:   {
2112:     if (transferHandler == newHandler)
2113:       return;
2114: 
2115:     TransferHandler oldHandler = transferHandler;
2116:     transferHandler = newHandler;
2117:     firePropertyChange("transferHandler", oldHandler, newHandler);
2118:   }
2119: 
2120:   /**
2121:    * Set the value of the {@link #opaque} property.
2122:    *
2123:    * @param isOpaque The new value of the property
2124:    *
2125:    * @see ComponentUI#update
2126:    */
2127:   public void setOpaque(boolean isOpaque)
2128:   {
2129:     boolean oldOpaque = opaque;
2130:     opaque = isOpaque;
2131:     firePropertyChange("opaque", oldOpaque, opaque);
2132:   }
2133: 
2134:   /**
2135:    * Set the value of the visible property.
2136:    *
2137:    * @param v The new value of the property
2138:    */
2139:   public void setVisible(boolean v)
2140:   {
2141:     super.setVisible(v);
2142:   }
2143: 
2144:   /**
2145:    * Call {@link paint}. 
2146:    * 
2147:    * @param g The graphics context to paint into
2148:    */
2149:   public void update(Graphics g)
2150:   {
2151:     paint(g);
2152:   }
2153: 
2154:   /**
2155:    * Get the value of the UIClassID property. This property should be a key
2156:    * in the {@link UIDefaults} table managed by {@link UIManager}, the
2157:    * value of which is the name of a class to load for the component's
2158:    * {@link ui} property.
2159:    *
2160:    * @return A "symbolic" name which will map to a class to use for the
2161:    * component's UI, such as <code>"ComponentUI"</code>
2162:    *
2163:    * @see #setUI
2164:    * @see #updateUI
2165:    */
2166:   public String getUIClassID()
2167:   {
2168:     return "ComponentUI";
2169:   }
2170: 
2171:   /**
2172:    * Install a new UI delegate as the component's {@link ui} property. In
2173:    * the process, this will call {@link ComponentUI.uninstallUI} on any
2174:    * existing value for the {@link ui} property, and {@link
2175:    * ComponentUI.installUI} on the new UI delegate.
2176:    *
2177:    * @param newUI The new UI delegate to install
2178:    *
2179:    * @see #updateUI
2180:    * @see #getUIClassID
2181:    */
2182:   protected void setUI(ComponentUI newUI)
2183:   {
2184:     if (ui != null)
2185:       ui.uninstallUI(this);
2186: 
2187:     ComponentUI oldUI = ui;
2188:     ui = newUI;
2189: 
2190:     if (ui != null)
2191:       ui.installUI(this);
2192: 
2193:     firePropertyChange("UI", oldUI, newUI);
2194:     
2195:   }
2196: 
2197:   /**
2198:    * This method should be overridden in subclasses. In JComponent, the
2199:    * method does nothing. In subclasses, it should a UI delegate
2200:    * (corresponding to the symbolic name returned from {@link
2201:    * getUIClassID}) from the {@link UIManager}, and calls {@link setUI}
2202:    * with the new delegate.
2203:    */
2204:   public void updateUI()
2205:   {
2206:     System.out.println("update UI not overwritten in class: " + this);
2207:   }
2208: 
2209:   public static Locale getDefaultLocale()
2210:   {
2211:     return defaultLocale;
2212:   }
2213:   
2214:   public static void setDefaultLocale(Locale l)
2215:   {
2216:     defaultLocale = l;
2217:   }
2218:   
2219:   /**
2220:    * Returns the currently set input verifier for this component.
2221:    *
2222:    * @return the input verifier, or <code>null</code> if none
2223:    */
2224:   public InputVerifier getInputVerifier()
2225:   {
2226:     return inputVerifier;
2227:   }
2228: 
2229:   /**
2230:    * Sets the input verifier to use by this component.
2231:    *
2232:    * @param verifier the input verifier, or <code>null</code>
2233:    */
2234:   public void setInputVerifier(InputVerifier verifier)
2235:   {
2236:     InputVerifier oldVerifier = inputVerifier;
2237:     inputVerifier = verifier;
2238:     firePropertyChange("inputVerifier", oldVerifier, verifier);
2239:   }
2240: 
2241:   /**
2242:    * @since 1.3
2243:    */
2244:   public boolean getVerifyInputWhenFocusTarget()
2245:   {
2246:     return verifyInputWhenFocusTarget;
2247:   }
2248: 
2249:   /**
2250:    * @since 1.3
2251:    */
2252:   public void setVerifyInputWhenFocusTarget(boolean verifyInputWhenFocusTarget)
2253:   {
2254:     if (this.verifyInputWhenFocusTarget == verifyInputWhenFocusTarget)
2255:       return;
2256: 
2257:     this.verifyInputWhenFocusTarget = verifyInputWhenFocusTarget;
2258:     firePropertyChange("verifyInputWhenFocusTarget",
2259:                        ! verifyInputWhenFocusTarget,
2260:                        verifyInputWhenFocusTarget);
2261:   }
2262: 
2263:   /**
2264:    * Requests that this component gets the input focus if the
2265:    * requestFocusEnabled property is set to <code>true</code>.
2266:    * This also means that this component's top-level window becomes
2267:    * the focused window, if that is not already the case.
2268:    *
2269:    * The preconditions that have to be met to become a focus owner is that
2270:    * the component must be displayable, visible and focusable.
2271:    *
2272:    * Note that this signals only a request for becoming focused. There are
2273:    * situations in which it is not possible to get the focus. So developers
2274:    * should not assume that the component has the focus until it receives
2275:    * a {@link java.awt.event.FocusEvent} with a value of
2276:    * {@link java.awt.event.FocusEvent.FOCUS_GAINED}.
2277:    *
2278:    * @see {@link Component#requestFocus()}
2279:    */
2280:   public void requestFocus()
2281:   {
2282:     if (isRequestFocusEnabled())
2283:       super.requestFocus();
2284:   }
2285: 
2286:   /**
2287:    * This method is overridden to make it public so that it can be used
2288:    * by look and feel implementations.
2289:    *
2290:    * You should not use this method directly. Instead you are strongly
2291:    * encouraged to call {@link #requestFocus} or {@link #requestFocusInWindow}
2292:    * instead.
2293:    *
2294:    * @param temporary if the focus change is temporary
2295:    *
2296:    * @return <code>false</code> if the focus change request will definitly
2297:    *     fail, <code>true</code> if it will likely succeed
2298:    *
2299:    * @see {@link Component#requestFocus(boolean)}
2300:    *
2301:    * @since 1.4
2302:    */
2303:   public boolean requestFocus(boolean temporary)
2304:   {
2305:     return super.requestFocus(temporary);
2306:   }
2307: 
2308:   /**
2309:    * Requests that this component gets the input focus if the top level
2310:    * window that contains this component has the focus and the
2311:    * requestFocusEnabled property is set to <code>true</code>.
2312:    *
2313:    * The preconditions that have to be met to become a focus owner is that
2314:    * the component must be displayable, visible and focusable.
2315:    *
2316:    * Note that this signals only a request for becoming focused. There are
2317:    * situations in which it is not possible to get the focus. So developers
2318:    * should not assume that the component has the focus until it receives
2319:    * a {@link java.awt.event.FocusEvent} with a value of
2320:    * {@link java.awt.event.FocusEvent.FOCUS_GAINED}.
2321:    *
2322:    * @return <code>false</code> if the focus change request will definitly
2323:    *     fail, <code>true</code> if it will likely succeed
2324:    *
2325:    * @see {@link Component#requestFocusInWindow()}
2326:    */
2327:   public boolean requestFocusInWindow()
2328:   {
2329:     if (isRequestFocusEnabled())
2330:       return super.requestFocusInWindow();
2331:     else
2332:       return false;
2333:   }
2334: 
2335:   /**
2336:    * This method is overridden to make it public so that it can be used
2337:    * by look and feel implementations.
2338:    *
2339:    * You should not use this method directly. Instead you are strongly
2340:    * encouraged to call {@link #requestFocus} or {@link #requestFocusInWindow}
2341:    * instead.
2342:    *
2343:    * @param temporary if the focus change is temporary
2344:    *
2345:    * @return <code>false</code> if the focus change request will definitly
2346:    *     fail, <code>true</code> if it will likely succeed
2347:    *
2348:    * @see {@link Component#requestFocus(boolean)}
2349:    *
2350:    * @since 1.4
2351:    */
2352:   public boolean requestFocusInWindow(boolean temporary)
2353:   {
2354:     return super.requestFocusInWindow(temporary);
2355:   }
2356: 
2357:   /**
2358:    * Receives notification if this component is added to a parent component.
2359:    *
2360:    * Notification is sent to all registered AncestorListeners about the
2361:    * new parent.
2362:    *
2363:    * This method sets up ActionListeners for all registered KeyStrokes of
2364:    * this component in the chain of parent components.
2365:    *
2366:    * A PropertyChange event is fired to indicate that the ancestor property
2367:    * has changed.
2368:    *
2369:    * This method is used internally and should not be used in applications.
2370:    */
2371:   public void addNotify()
2372:   {
2373:     super.addNotify();
2374: 
2375:     // let parents inherit the keybord mapping
2376:     InputMap input = getInputMap();
2377:     ActionMap actions = getActionMap();
2378: 
2379:     Container parent = getParent();
2380:     while ((parent != null) && (parent instanceof JComponent))
2381:       {
2382:         JComponent jParent = (JComponent) parent;
2383:         InputMap parentInput = jParent.getInputMap();
2384:         ActionMap parentAction = jParent.getActionMap();
2385: 
2386:         KeyStroke[] ikeys = input.keys();
2387:         for (int i = 0; i < ikeys.length; i++)
2388:           {
2389:             Object o = input.get(ikeys[i]);
2390:             parentInput.put(ikeys[i], o);
2391:           }
2392: 
2393:         Object[] akeys = actions.keys();
2394:         for (int i = 0; i < akeys.length; i++)
2395:           {
2396:             Action a = actions.get(akeys[i]);
2397:             parentAction.put(akeys[i], a);
2398:           }
2399: 
2400:         parent = jParent.getParent();
2401:       }
2402: 
2403:     // notify ancestor listeners
2404:     AncestorListener[] ls = getAncestorListeners();
2405:     AncestorEvent ev = new AncestorEvent(this, AncestorEvent.ANCESTOR_ADDED,
2406:                                          this, parent);
2407:     for (int i = 0; i < ls.length; i++)
2408:       {
2409:         ls[i].ancestorAdded(ev);
2410:       }
2411: 
2412:     // fire property change event for 'ancestor'
2413:     firePropertyChange("ancestor", null, parent);
2414:   }
2415: 
2416:   /**
2417:    * Receives notification that this component no longer has a parent.
2418:    *
2419:    * This method sends an AncestorEvent to all registered AncestorListeners,
2420:    * notifying them that the parent is gone.
2421:    *
2422:    * The keybord actions of this component are removed from the parent and
2423:    * its ancestors.
2424:    *
2425:    * A PropertyChangeEvent is fired to indicate that the 'ancestor' property
2426:    * has changed.
2427:    *
2428:    * This method is called before the component is actually removed from
2429:    * its parent, so the parent is still visible through {@link #getParent}.
2430:    */
2431:   public void removeNotify()
2432:   {
2433:     super.removeNotify();
2434: 
2435:     // let parents inherit the keybord mapping
2436:     InputMap input = getInputMap();
2437:     ActionMap actions = getActionMap();
2438: 
2439:     Container parent = getParent();
2440:     while ((parent != null) && (parent instanceof JComponent))
2441:       {
2442:         JComponent jParent = (JComponent) parent;
2443:         InputMap parentInput = jParent.getInputMap();
2444:         ActionMap parentAction = jParent.getActionMap();
2445: 
2446:         KeyStroke[] ikeys = input.allKeys();
2447:         for (int i = 0; i < ikeys.length; i++)
2448:           {
2449:             parentInput.remove(ikeys[i]);
2450:           }
2451: 
2452:         Object[] akeys = actions.allKeys();
2453:         for (int i = 0; i < akeys.length; i++)
2454:           {
2455:             parentAction.remove(akeys[i]);
2456:           }
2457: 
2458:         parent = jParent.getParent();
2459:       }
2460: 
2461:     // notify ancestor listeners
2462:     AncestorListener[] ls = getAncestorListeners();
2463:     AncestorEvent ev = new AncestorEvent(this, AncestorEvent.ANCESTOR_ADDED,
2464:                                          this, parent);
2465:     for (int i = 0; i < ls.length; i++)
2466:       {
2467:         ls[i].ancestorAdded(ev);
2468:       }
2469: 
2470:     // fire property change event for 'ancestor'
2471:     firePropertyChange("ancestor", parent, null);
2472:   }
2473: 
2474:   /**
2475:    * Returns <code>true</code> if the coordinates (x, y) lie within
2476:    * the bounds of this component and <code>false</code> otherwise.
2477:    * x and y are relative to the coordinate space of the component.
2478:    *
2479:    * @param x the X coordinate of the point to check
2480:    * @param y the Y coordinate of the point to check
2481:    *
2482:    * @return <code>true</code> if the specified point lies within the bounds
2483:    *     of this component, <code>false</code> otherwise
2484:    */
2485:   public boolean contains(int x, int y)
2486:   {
2487:     if (ui == null)
2488:       return super.contains(x, y);
2489:     else
2490:       return ui.contains(this, x, y);
2491:   }
2492: 
2493:   /**
2494:    * Disables this component.
2495:    *
2496:    * @deprecated replaced by {@link #setEnabled(boolean)}
2497:    */
2498:   public void disable()
2499:   {
2500:     super.disable();
2501:   }
2502: 
2503:   /**
2504:    * Enables this component.
2505:    *
2506:    * @deprecated replaced by {@link #setEnabled(boolean)}
2507:    */
2508:   public void enable()
2509:   {
2510:     super.enable();
2511:   }
2512: 
2513:   /**
2514:    * Returns the Graphics context for this component. This can be used
2515:    * to draw on a component.
2516:    *
2517:    * @return the Graphics context for this component
2518:    */
2519:   public Graphics getGraphics()
2520:   {
2521:     return super.getGraphics();
2522:   }
2523: 
2524:   /**
2525:    * Returns the X coordinate of the upper left corner of this component.
2526:    * Prefer this method over {@link #getBounds} or {@link #getLocation}
2527:    * because it does not cause any heap allocation.
2528:    *
2529:    * @return the X coordinate of the upper left corner of the component
2530:    */
2531:   public int getX()
2532:   {
2533:     return super.getX();
2534:   }
2535: 
2536:   /**
2537:    * Returns the Y coordinate of the upper left corner of this component.
2538:    * Prefer this method over {@link #getBounds} or {@link #getLocation}
2539:    * because it does not cause any heap allocation.
2540:    *
2541:    * @return the Y coordinate of the upper left corner of the component
2542:    */
2543:   public int getY()
2544:   {
2545:     return super.getY();
2546:   }
2547: 
2548:   /**
2549:    * Returns the height of this component. Prefer this method over
2550:    * {@link #getBounds} or {@link #getSize} because it does not cause
2551:    * any heap allocation.
2552:    *
2553:    * @return the height of the component
2554:    */
2555:   public int getHeight()
2556:   {
2557:     return super.getHeight();
2558:   }
2559: 
2560:   /**
2561:    * Returns the width of this component. Prefer this method over
2562:    * {@link #getBounds} or {@link #getSize} because it does not cause
2563:    * any heap allocation.
2564:    *
2565:    * @return the width of the component
2566:    */
2567:   public int getWidth()
2568:   {
2569:     return super.getWidth();
2570:   }
2571: 
2572:   /**
2573:    * Return all <code>PropertyChangeListener</code> objects registered.
2574:    *
2575:    * @return The set of <code>PropertyChangeListener</code> objects
2576:    */
2577:   public PropertyChangeListener[] getPropertyChangeListeners()
2578:   {
2579:     if (changeSupport == null)
2580:       return new PropertyChangeListener[0];
2581:     else
2582:       return changeSupport.getPropertyChangeListeners();
2583:   }
2584: 
2585:   /**
2586:    * Prints this component to the given Graphics context. A call to this
2587:    * method results in calls to the methods {@link #printComponent},
2588:    * {@link #printBorder} and {@link printChildren} in this order.
2589:    *
2590:    * Double buffering is temporarily turned off so the painting goes directly
2591:    * to the supplied Graphics context.
2592:    *
2593:    * @param g the Graphics context to print onto
2594:    */
2595:   public void print(Graphics g)
2596:   {
2597:     boolean doubleBufferState = isDoubleBuffered();
2598:     setDoubleBuffered(false);
2599:     printComponent(g);
2600:     printBorder(g);
2601:     printChildren(g);
2602:     setDoubleBuffered(doubleBufferState);
2603:   }
2604: 
2605:   /**
2606:    * Prints this component to the given Graphics context. This invokes
2607:    * {@link #print}.
2608:    *
2609:    * @param g the Graphics context to print onto
2610:    */
2611:   public void printAll(Graphics g)
2612:   {
2613:     print(g);
2614:   }
2615: 
2616:   /**
2617:    * Prints this component to the specified Graphics context. The default
2618:    * behaviour is to invoke {@link #paintComponent}. Override this
2619:    * if you want special behaviour for printing.
2620:    *
2621:    * @param g the Graphics context to print onto
2622:    *
2623:    * @since 1.3
2624:    */
2625:   public void printComponent(Graphics g)
2626:   {
2627:     paintComponent(g);
2628:   }
2629: 
2630:   /**
2631:    * Print this component's children to the specified Graphics context.
2632:    * The default behaviour is to invoke {@link #paintChildren}. Override this
2633:    * if you want special behaviour for printing.
2634:    *
2635:    * @param g the Graphics context to print onto
2636:    *
2637:    * @since 1.3
2638:    */
2639:   public void printChildren(Graphics g)
2640:   {
2641:     paintChildren(g);
2642:   }
2643: 
2644:   /**
2645:    * Print this component's border to the specified Graphics context.
2646:    * The default behaviour is to invoke {@link #paintBorder}. Override this
2647:    * if you want special behaviour for printing.
2648:    *
2649:    * @param g the Graphics context to print onto
2650:    *
2651:    * @since 1.3
2652:    */
2653:   public void printBorder(Graphics g)
2654:   {
2655:     paintBorder(g);
2656:   }
2657: 
2658:   /**
2659:    * Processes mouse motion event, like dragging and moving.
2660:    *
2661:    * @param ev the MouseEvent describing the mouse motion
2662:    */
2663:   protected void processMouseMotionEvent(MouseEvent ev)
2664:   {
2665:     super.processMouseMotionEvent(ev);
2666:   }
2667: 
2668:   /**
2669:    * Moves and resizes the component.
2670:    *
2671:    * @param x the new horizontal location
2672:    * @param y the new vertial location
2673:    * @param w the new width
2674:    * @param h the new height
2675:    */
2676:   public void reshape(int x, int y, int w, int h)
2677:   {
2678:     super.reshape(x, y, w, h);
2679:   }
2680: }