1 /*
2 * Copyright (c) 1995, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.awt;
26
27 import java.io.PrintStream;
28 import java.io.PrintWriter;
29 import java.util.Objects;
30 import java.util.Vector;
31 import java.util.Locale;
32 import java.util.EventListener;
33 import java.util.HashSet;
34 import java.util.Map;
35 import java.util.Set;
36 import java.util.Collections;
37 import java.awt.peer.ComponentPeer;
38 import java.awt.peer.ContainerPeer;
39 import java.awt.peer.LightweightPeer;
40 import java.awt.image.BufferStrategy;
41 import java.awt.image.ImageObserver;
42 import java.awt.image.ImageProducer;
43 import java.awt.image.ColorModel;
44 import java.awt.image.VolatileImage;
45 import java.awt.event.*;
46 import java.io.Serializable;
47 import java.io.ObjectOutputStream;
48 import java.io.ObjectInputStream;
49 import java.io.IOException;
50 import java.beans.PropertyChangeListener;
51 import java.beans.PropertyChangeSupport;
52 import java.beans.Transient;
53 import java.awt.im.InputContext;
54 import java.awt.im.InputMethodRequests;
55 import java.awt.dnd.DropTarget;
56 import java.security.AccessController;
57 import java.security.AccessControlContext;
58 import javax.accessibility.*;
59 import java.applet.Applet;
60 import javax.swing.JComponent;
61 import javax.swing.JRootPane;
62
63 import sun.awt.ComponentFactory;
64 import sun.security.action.GetPropertyAction;
65 import sun.awt.AppContext;
66 import sun.awt.AWTAccessor;
67 import sun.awt.ConstrainableGraphics;
68 import sun.awt.SubRegionShowable;
69 import sun.awt.SunToolkit;
70 import sun.awt.EmbeddedFrame;
71 import sun.awt.dnd.SunDropTargetEvent;
72 import sun.awt.im.CompositionArea;
73 import sun.font.FontManager;
74 import sun.font.FontManagerFactory;
75 import sun.font.SunFontManager;
76 import sun.java2d.SunGraphics2D;
77 import sun.java2d.pipe.Region;
78 import sun.awt.image.VSyncedBSManager;
79 import sun.java2d.pipe.hw.ExtendedBufferCapabilities;
80 import static sun.java2d.pipe.hw.ExtendedBufferCapabilities.VSyncType.*;
81 import sun.awt.RequestFocusController;
82 import sun.java2d.SunGraphicsEnvironment;
83 import sun.swing.SwingAccessor;
84 import sun.util.logging.PlatformLogger;
85
86 /**
87 * A <em>component</em> is an object having a graphical representation
88 * that can be displayed on the screen and that can interact with the
89 * user. Examples of components are the buttons, checkboxes, and scrollbars
90 * of a typical graphical user interface. <p>
91 * The {@code Component} class is the abstract superclass of
92 * the nonmenu-related Abstract Window Toolkit components. Class
93 * {@code Component} can also be extended directly to create a
94 * lightweight component. A lightweight component is a component that is
95 * not associated with a native window. On the contrary, a heavyweight
96 * component is associated with a native window. The {@link #isLightweight()}
97 * method may be used to distinguish between the two kinds of the components.
98 * <p>
99 * Lightweight and heavyweight components may be mixed in a single component
100 * hierarchy. However, for correct operating of such a mixed hierarchy of
101 * components, the whole hierarchy must be valid. When the hierarchy gets
102 * invalidated, like after changing the bounds of components, or
103 * adding/removing components to/from containers, the whole hierarchy must be
104 * validated afterwards by means of the {@link Container#validate()} method
105 * invoked on the top-most invalid container of the hierarchy.
106 *
107 * <h3>Serialization</h3>
108 * It is important to note that only AWT listeners which conform
109 * to the {@code Serializable} protocol will be saved when
110 * the object is stored. If an AWT object has listeners that
111 * aren't marked serializable, they will be dropped at
112 * {@code writeObject} time. Developers will need, as always,
113 * to consider the implications of making an object serializable.
114 * One situation to watch out for is this:
115 * <pre>
116 * import java.awt.*;
117 * import java.awt.event.*;
118 * import java.io.Serializable;
119 *
120 * class MyApp implements ActionListener, Serializable
121 * {
122 * BigObjectThatShouldNotBeSerializedWithAButton bigOne;
123 * Button aButton = new Button();
124 *
125 * MyApp()
126 * {
127 * // Oops, now aButton has a listener with a reference
128 * // to bigOne!
129 * aButton.addActionListener(this);
130 * }
131 *
132 * public void actionPerformed(ActionEvent e)
133 * {
134 * System.out.println("Hello There");
135 * }
136 * }
137 * </pre>
138 * In this example, serializing {@code aButton} by itself
139 * will cause {@code MyApp} and everything it refers to
140 * to be serialized as well. The problem is that the listener
141 * is serializable by coincidence, not by design. To separate
142 * the decisions about {@code MyApp} and the
143 * {@code ActionListener} being serializable one can use a
144 * nested class, as in the following example:
145 * <pre>
146 * import java.awt.*;
147 * import java.awt.event.*;
148 * import java.io.Serializable;
149 *
150 * class MyApp implements java.io.Serializable
151 * {
152 * BigObjectThatShouldNotBeSerializedWithAButton bigOne;
153 * Button aButton = new Button();
154 *
155 * static class MyActionListener implements ActionListener
156 * {
157 * public void actionPerformed(ActionEvent e)
158 * {
159 * System.out.println("Hello There");
160 * }
161 * }
162 *
163 * MyApp()
164 * {
165 * aButton.addActionListener(new MyActionListener());
166 * }
167 * }
168 * </pre>
169 * <p>
170 * <b>Note</b>: For more information on the paint mechanisms utilized
171 * by AWT and Swing, including information on how to write the most
172 * efficient painting code, see
173 * <a href="http://www.oracle.com/technetwork/java/painting-140037.html">Painting in AWT and Swing</a>.
174 * <p>
175 * For details on the focus subsystem, see
176 * <a href="http://docs.oracle.com/javase/tutorial/uiswing/misc/focus.html">
177 * How to Use the Focus Subsystem</a>,
178 * a section in <em>The Java Tutorial</em>, and the
179 * <a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
180 * for more information.
181 *
182 * @author Arthur van Hoff
183 * @author Sami Shaio
184 */
185 public abstract class Component implements ImageObserver, MenuContainer,
186 Serializable
187 {
188
189 private static final PlatformLogger log = PlatformLogger.getLogger("java.awt.Component");
190 private static final PlatformLogger eventLog = PlatformLogger.getLogger("java.awt.event.Component");
191 private static final PlatformLogger focusLog = PlatformLogger.getLogger("java.awt.focus.Component");
192 private static final PlatformLogger mixingLog = PlatformLogger.getLogger("java.awt.mixing.Component");
193
194 /**
195 * The peer of the component. The peer implements the component's
196 * behavior. The peer is set when the {@code Component} is
197 * added to a container that also is a peer.
198 * @see #addNotify
199 * @see #removeNotify
200 */
201 transient volatile ComponentPeer peer;
202
203 /**
204 * The parent of the object. It may be {@code null}
205 * for top-level components.
206 * @see #getParent
207 */
208 transient Container parent;
209
210 /**
211 * The {@code AppContext} of the component. Applets/Plugin may
212 * change the AppContext.
213 */
214 transient AppContext appContext;
215
216 /**
217 * The x position of the component in the parent's coordinate system.
218 *
219 * @serial
220 * @see #getLocation
221 */
222 int x;
223
224 /**
225 * The y position of the component in the parent's coordinate system.
226 *
227 * @serial
228 * @see #getLocation
229 */
230 int y;
231
232 /**
233 * The width of the component.
234 *
235 * @serial
236 * @see #getSize
237 */
238 int width;
239
240 /**
241 * The height of the component.
242 *
243 * @serial
244 * @see #getSize
245 */
246 int height;
247
248 /**
249 * The foreground color for this component.
250 * {@code foreground} can be {@code null}.
251 *
252 * @serial
253 * @see #getForeground
254 * @see #setForeground
255 */
256 Color foreground;
257
258 /**
259 * The background color for this component.
260 * {@code background} can be {@code null}.
261 *
262 * @serial
263 * @see #getBackground
264 * @see #setBackground
265 */
266 Color background;
267
268 /**
269 * The font used by this component.
270 * The {@code font} can be {@code null}.
271 *
272 * @serial
273 * @see #getFont
274 * @see #setFont
275 */
276 volatile Font font;
277
278 /**
279 * The font which the peer is currently using.
280 * ({@code null} if no peer exists.)
281 */
282 Font peerFont;
283
284 /**
285 * The cursor displayed when pointer is over this component.
286 * This value can be {@code null}.
287 *
288 * @serial
289 * @see #getCursor
290 * @see #setCursor
291 */
292 Cursor cursor;
293
294 /**
295 * The locale for the component.
296 *
297 * @serial
298 * @see #getLocale
299 * @see #setLocale
300 */
301 Locale locale;
302
303 /**
304 * A reference to a {@code GraphicsConfiguration} object
305 * used to describe the characteristics of a graphics
306 * destination.
307 * This value can be {@code null}.
308 *
309 * @since 1.3
310 * @serial
311 * @see GraphicsConfiguration
312 * @see #getGraphicsConfiguration
313 */
314 private transient volatile GraphicsConfiguration graphicsConfig;
315
316 /**
317 * A reference to a {@code BufferStrategy} object
318 * used to manipulate the buffers on this component.
319 *
320 * @since 1.4
321 * @see java.awt.image.BufferStrategy
322 * @see #getBufferStrategy()
323 */
324 transient BufferStrategy bufferStrategy = null;
325
326 /**
327 * True when the object should ignore all repaint events.
328 *
329 * @since 1.4
330 * @serial
331 * @see #setIgnoreRepaint
332 * @see #getIgnoreRepaint
333 */
334 boolean ignoreRepaint = false;
335
336 /**
337 * True when the object is visible. An object that is not
338 * visible is not drawn on the screen.
339 *
340 * @serial
341 * @see #isVisible
342 * @see #setVisible
343 */
344 boolean visible = true;
345
346 /**
347 * True when the object is enabled. An object that is not
348 * enabled does not interact with the user.
349 *
350 * @serial
351 * @see #isEnabled
352 * @see #setEnabled
353 */
354 boolean enabled = true;
355
356 /**
357 * True when the object is valid. An invalid object needs to
358 * be laid out. This flag is set to false when the object
359 * size is changed.
360 *
361 * @serial
362 * @see #isValid
363 * @see #validate
364 * @see #invalidate
365 */
366 private volatile boolean valid = false;
367
368 /**
369 * The {@code DropTarget} associated with this component.
370 *
371 * @since 1.2
372 * @serial
373 * @see #setDropTarget
374 * @see #getDropTarget
375 */
376 DropTarget dropTarget;
377
378 /**
379 * @serial
380 * @see #add
381 */
382 Vector<PopupMenu> popups;
383
384 /**
385 * A component's name.
386 * This field can be {@code null}.
387 *
388 * @serial
389 * @see #getName
390 * @see #setName(String)
391 */
392 private String name;
393
394 /**
395 * A bool to determine whether the name has
396 * been set explicitly. {@code nameExplicitlySet} will
397 * be false if the name has not been set and
398 * true if it has.
399 *
400 * @serial
401 * @see #getName
402 * @see #setName(String)
403 */
404 private boolean nameExplicitlySet = false;
405
406 /**
407 * Indicates whether this Component can be focused.
408 *
409 * @serial
410 * @see #setFocusable
411 * @see #isFocusable
412 * @since 1.4
413 */
414 private boolean focusable = true;
415
416 private static final int FOCUS_TRAVERSABLE_UNKNOWN = 0;
417 private static final int FOCUS_TRAVERSABLE_DEFAULT = 1;
418 private static final int FOCUS_TRAVERSABLE_SET = 2;
419
420 /**
421 * Tracks whether this Component is relying on default focus traversability.
422 *
423 * @serial
424 * @since 1.4
425 */
426 private int isFocusTraversableOverridden = FOCUS_TRAVERSABLE_UNKNOWN;
427
428 /**
429 * The focus traversal keys. These keys will generate focus traversal
430 * behavior for Components for which focus traversal keys are enabled. If a
431 * value of null is specified for a traversal key, this Component inherits
432 * that traversal key from its parent. If all ancestors of this Component
433 * have null specified for that traversal key, then the current
434 * KeyboardFocusManager's default traversal key is used.
435 *
436 * @serial
437 * @see #setFocusTraversalKeys
438 * @see #getFocusTraversalKeys
439 * @since 1.4
440 */
441 Set<AWTKeyStroke>[] focusTraversalKeys;
442
443 private static final String[] focusTraversalKeyPropertyNames = {
444 "forwardFocusTraversalKeys",
445 "backwardFocusTraversalKeys",
446 "upCycleFocusTraversalKeys",
447 "downCycleFocusTraversalKeys"
448 };
449
450 /**
451 * Indicates whether focus traversal keys are enabled for this Component.
452 * Components for which focus traversal keys are disabled receive key
453 * events for focus traversal keys. Components for which focus traversal
454 * keys are enabled do not see these events; instead, the events are
455 * automatically converted to traversal operations.
456 *
457 * @serial
458 * @see #setFocusTraversalKeysEnabled
459 * @see #getFocusTraversalKeysEnabled
460 * @since 1.4
461 */
462 private boolean focusTraversalKeysEnabled = true;
463
464 /**
465 * The locking object for AWT component-tree and layout operations.
466 *
467 * @see #getTreeLock
468 */
469 static final Object LOCK = new AWTTreeLock();
470 static class AWTTreeLock {}
471
472 /*
473 * The component's AccessControlContext.
474 */
475 private transient volatile AccessControlContext acc =
476 AccessController.getContext();
477
478 /**
479 * Minimum size.
480 * (This field perhaps should have been transient).
481 *
482 * @serial
483 */
484 Dimension minSize;
485
486 /**
487 * Whether or not setMinimumSize has been invoked with a non-null value.
488 */
489 boolean minSizeSet;
490
491 /**
492 * Preferred size.
493 * (This field perhaps should have been transient).
494 *
495 * @serial
496 */
497 Dimension prefSize;
498
499 /**
500 * Whether or not setPreferredSize has been invoked with a non-null value.
501 */
502 boolean prefSizeSet;
503
504 /**
505 * Maximum size
506 *
507 * @serial
508 */
509 Dimension maxSize;
510
511 /**
512 * Whether or not setMaximumSize has been invoked with a non-null value.
513 */
514 boolean maxSizeSet;
515
516 /**
517 * The orientation for this component.
518 * @see #getComponentOrientation
519 * @see #setComponentOrientation
520 */
521 transient ComponentOrientation componentOrientation
522 = ComponentOrientation.UNKNOWN;
523
524 /**
525 * {@code newEventsOnly} will be true if the event is
526 * one of the event types enabled for the component.
527 * It will then allow for normal processing to
528 * continue. If it is false the event is passed
529 * to the component's parent and up the ancestor
530 * tree until the event has been consumed.
531 *
532 * @serial
533 * @see #dispatchEvent
534 */
535 boolean newEventsOnly = false;
536 transient ComponentListener componentListener;
537 transient FocusListener focusListener;
538 transient HierarchyListener hierarchyListener;
539 transient HierarchyBoundsListener hierarchyBoundsListener;
540 transient KeyListener keyListener;
541 transient MouseListener mouseListener;
542 transient MouseMotionListener mouseMotionListener;
543 transient MouseWheelListener mouseWheelListener;
544 transient InputMethodListener inputMethodListener;
545
546 /** Internal, constants for serialization */
547 static final String actionListenerK = "actionL";
548 static final String adjustmentListenerK = "adjustmentL";
549 static final String componentListenerK = "componentL";
550 static final String containerListenerK = "containerL";
551 static final String focusListenerK = "focusL";
552 static final String itemListenerK = "itemL";
553 static final String keyListenerK = "keyL";
554 static final String mouseListenerK = "mouseL";
555 static final String mouseMotionListenerK = "mouseMotionL";
556 static final String mouseWheelListenerK = "mouseWheelL";
557 static final String textListenerK = "textL";
558 static final String ownedWindowK = "ownedL";
559 static final String windowListenerK = "windowL";
560 static final String inputMethodListenerK = "inputMethodL";
561 static final String hierarchyListenerK = "hierarchyL";
562 static final String hierarchyBoundsListenerK = "hierarchyBoundsL";
563 static final String windowStateListenerK = "windowStateL";
564 static final String windowFocusListenerK = "windowFocusL";
565
566 /**
567 * The {@code eventMask} is ONLY set by subclasses via
568 * {@code enableEvents}.
569 * The mask should NOT be set when listeners are registered
570 * so that we can distinguish the difference between when
571 * listeners request events and subclasses request them.
572 * One bit is used to indicate whether input methods are
573 * enabled; this bit is set by {@code enableInputMethods} and is
574 * on by default.
575 *
576 * @serial
577 * @see #enableInputMethods
578 * @see AWTEvent
579 */
580 long eventMask = AWTEvent.INPUT_METHODS_ENABLED_MASK;
581
582 /**
583 * Static properties for incremental drawing.
584 * @see #imageUpdate
585 */
586 static boolean isInc;
587 static int incRate;
588 static {
589 /* ensure that the necessary native libraries are loaded */
590 Toolkit.loadLibraries();
591 /* initialize JNI field and method ids */
592 if (!GraphicsEnvironment.isHeadless()) {
593 initIDs();
594 }
595
596 String s = java.security.AccessController.doPrivileged(
597 new GetPropertyAction("awt.image.incrementaldraw"));
598 isInc = (s == null || s.equals("true"));
599
600 s = java.security.AccessController.doPrivileged(
601 new GetPropertyAction("awt.image.redrawrate"));
602 incRate = (s != null) ? Integer.parseInt(s) : 100;
603 }
604
605 /**
606 * Ease-of-use constant for {@code getAlignmentY()}.
607 * Specifies an alignment to the top of the component.
608 * @see #getAlignmentY
609 */
610 public static final float TOP_ALIGNMENT = 0.0f;
611
612 /**
613 * Ease-of-use constant for {@code getAlignmentY} and
614 * {@code getAlignmentX}. Specifies an alignment to
615 * the center of the component
616 * @see #getAlignmentX
617 * @see #getAlignmentY
618 */
619 public static final float CENTER_ALIGNMENT = 0.5f;
620
621 /**
622 * Ease-of-use constant for {@code getAlignmentY}.
623 * Specifies an alignment to the bottom of the component.
624 * @see #getAlignmentY
625 */
626 public static final float BOTTOM_ALIGNMENT = 1.0f;
627
628 /**
629 * Ease-of-use constant for {@code getAlignmentX}.
630 * Specifies an alignment to the left side of the component.
631 * @see #getAlignmentX
632 */
633 public static final float LEFT_ALIGNMENT = 0.0f;
634
635 /**
636 * Ease-of-use constant for {@code getAlignmentX}.
637 * Specifies an alignment to the right side of the component.
638 * @see #getAlignmentX
639 */
640 public static final float RIGHT_ALIGNMENT = 1.0f;
641
642 /*
643 * JDK 1.1 serialVersionUID
644 */
645 private static final long serialVersionUID = -7644114512714619750L;
646
647 /**
648 * If any {@code PropertyChangeListeners} have been registered,
649 * the {@code changeSupport} field describes them.
650 *
651 * @serial
652 * @since 1.2
653 * @see #addPropertyChangeListener
654 * @see #removePropertyChangeListener
655 * @see #firePropertyChange
656 */
657 private PropertyChangeSupport changeSupport;
658
659 /*
660 * In some cases using "this" as an object to synchronize by
661 * can lead to a deadlock if client code also uses synchronization
662 * by a component object. For every such situation revealed we should
663 * consider possibility of replacing "this" with the package private
664 * objectLock object introduced below. So far there are 3 issues known:
665 * - CR 6708322 (the getName/setName methods);
666 * - CR 6608764 (the PropertyChangeListener machinery);
667 * - CR 7108598 (the Container.paint/KeyboardFocusManager.clearMostRecentFocusOwner methods).
668 *
669 * Note: this field is considered final, though readObject() prohibits
670 * initializing final fields.
671 */
672 private transient Object objectLock = new Object();
673 Object getObjectLock() {
674 return objectLock;
675 }
676
677 /*
678 * Returns the acc this component was constructed with.
679 */
680 final AccessControlContext getAccessControlContext() {
681 if (acc == null) {
682 throw new SecurityException("Component is missing AccessControlContext");
683 }
684 return acc;
685 }
686
687 boolean isPacked = false;
688
689 /**
690 * Pseudoparameter for direct Geometry API (setLocation, setBounds setSize
691 * to signal setBounds what's changing. Should be used under TreeLock.
692 * This is only needed due to the inability to change the cross-calling
693 * order of public and deprecated methods.
694 */
695 private int boundsOp = ComponentPeer.DEFAULT_OPERATION;
696
697 /**
698 * Enumeration of the common ways the baseline of a component can
699 * change as the size changes. The baseline resize behavior is
700 * primarily for layout managers that need to know how the
701 * position of the baseline changes as the component size changes.
702 * In general the baseline resize behavior will be valid for sizes
703 * greater than or equal to the minimum size (the actual minimum
704 * size; not a developer specified minimum size). For sizes
705 * smaller than the minimum size the baseline may change in a way
706 * other than the baseline resize behavior indicates. Similarly,
707 * as the size approaches {@code Integer.MAX_VALUE} and/or
708 * {@code Short.MAX_VALUE} the baseline may change in a way
709 * other than the baseline resize behavior indicates.
710 *
711 * @see #getBaselineResizeBehavior
712 * @see #getBaseline(int,int)
713 * @since 1.6
714 */
715 public enum BaselineResizeBehavior {
716 /**
717 * Indicates the baseline remains fixed relative to the
718 * y-origin. That is, {@code getBaseline} returns
719 * the same value regardless of the height or width. For example, a
720 * {@code JLabel} containing non-empty text with a
721 * vertical alignment of {@code TOP} should have a
722 * baseline type of {@code CONSTANT_ASCENT}.
723 */
724 CONSTANT_ASCENT,
725
726 /**
727 * Indicates the baseline remains fixed relative to the height
728 * and does not change as the width is varied. That is, for
729 * any height H the difference between H and
730 * {@code getBaseline(w, H)} is the same. For example, a
731 * {@code JLabel} containing non-empty text with a
732 * vertical alignment of {@code BOTTOM} should have a
733 * baseline type of {@code CONSTANT_DESCENT}.
734 */
735 CONSTANT_DESCENT,
736
737 /**
738 * Indicates the baseline remains a fixed distance from
739 * the center of the component. That is, for any height H the
740 * difference between {@code getBaseline(w, H)} and
741 * {@code H / 2} is the same (plus or minus one depending upon
742 * rounding error).
743 * <p>
744 * Because of possible rounding errors it is recommended
745 * you ask for the baseline with two consecutive heights and use
746 * the return value to determine if you need to pad calculations
747 * by 1. The following shows how to calculate the baseline for
748 * any height:
749 * <pre>
750 * Dimension preferredSize = component.getPreferredSize();
751 * int baseline = getBaseline(preferredSize.width,
752 * preferredSize.height);
753 * int nextBaseline = getBaseline(preferredSize.width,
754 * preferredSize.height + 1);
755 * // Amount to add to height when calculating where baseline
756 * // lands for a particular height:
757 * int padding = 0;
758 * // Where the baseline is relative to the mid point
759 * int baselineOffset = baseline - height / 2;
760 * if (preferredSize.height % 2 == 0 &&
761 * baseline != nextBaseline) {
762 * padding = 1;
763 * }
764 * else if (preferredSize.height % 2 == 1 &&
765 * baseline == nextBaseline) {
766 * baselineOffset--;
767 * padding = 1;
768 * }
769 * // The following calculates where the baseline lands for
770 * // the height z:
771 * int calculatedBaseline = (z + padding) / 2 + baselineOffset;
772 * </pre>
773 */
774 CENTER_OFFSET,
775
776 /**
777 * Indicates the baseline resize behavior can not be expressed using
778 * any of the other constants. This may also indicate the baseline
779 * varies with the width of the component. This is also returned
780 * by components that do not have a baseline.
781 */
782 OTHER
783 }
784
785 /*
786 * The shape set with the applyCompoundShape() method. It includes the result
787 * of the HW/LW mixing related shape computation. It may also include
788 * the user-specified shape of the component.
789 * The 'null' value means the component has normal shape (or has no shape at all)
790 * and applyCompoundShape() will skip the following shape identical to normal.
791 */
792 private transient Region compoundShape = null;
793
794 /*
795 * Represents the shape of this lightweight component to be cut out from
796 * heavyweight components should they intersect. Possible values:
797 * 1. null - consider the shape rectangular
798 * 2. EMPTY_REGION - nothing gets cut out (children still get cut out)
799 * 3. non-empty - this shape gets cut out.
800 */
801 private transient Region mixingCutoutRegion = null;
802
803 /*
804 * Indicates whether addNotify() is complete
805 * (i.e. the peer is created).
806 */
807 private transient boolean isAddNotifyComplete = false;
808
809 /**
810 * Should only be used in subclass getBounds to check that part of bounds
811 * is actually changing
812 */
813 int getBoundsOp() {
814 assert Thread.holdsLock(getTreeLock());
815 return boundsOp;
816 }
817
818 void setBoundsOp(int op) {
819 assert Thread.holdsLock(getTreeLock());
820 if (op == ComponentPeer.RESET_OPERATION) {
821 boundsOp = ComponentPeer.DEFAULT_OPERATION;
822 } else
823 if (boundsOp == ComponentPeer.DEFAULT_OPERATION) {
824 boundsOp = op;
825 }
826 }
827
828 // Whether this Component has had the background erase flag
829 // specified via SunToolkit.disableBackgroundErase(). This is
830 // needed in order to make this function work on X11 platforms,
831 // where currently there is no chance to interpose on the creation
832 // of the peer and therefore the call to XSetBackground.
833 transient boolean backgroundEraseDisabled;
834
835 static {
836 AWTAccessor.setComponentAccessor(new AWTAccessor.ComponentAccessor() {
837 public void setBackgroundEraseDisabled(Component comp, boolean disabled) {
838 comp.backgroundEraseDisabled = disabled;
839 }
840 public boolean getBackgroundEraseDisabled(Component comp) {
841 return comp.backgroundEraseDisabled;
842 }
843 public Rectangle getBounds(Component comp) {
844 return new Rectangle(comp.x, comp.y, comp.width, comp.height);
845 }
846 public void setGraphicsConfiguration(Component comp,
847 GraphicsConfiguration gc)
848 {
849 comp.setGraphicsConfiguration(gc);
850 }
851 public void requestFocus(Component comp, FocusEvent.Cause cause) {
852 comp.requestFocus(cause);
853 }
854 public boolean canBeFocusOwner(Component comp) {
855 return comp.canBeFocusOwner();
856 }
857
858 public boolean isVisible(Component comp) {
859 return comp.isVisible_NoClientCode();
860 }
861 public void setRequestFocusController
862 (RequestFocusController requestController)
863 {
864 Component.setRequestFocusController(requestController);
865 }
866 public AppContext getAppContext(Component comp) {
867 return comp.appContext;
868 }
869 public void setAppContext(Component comp, AppContext appContext) {
870 comp.appContext = appContext;
871 }
872 public Container getParent(Component comp) {
873 return comp.getParent_NoClientCode();
874 }
875 public void setParent(Component comp, Container parent) {
876 comp.parent = parent;
877 }
878 public void setSize(Component comp, int width, int height) {
879 comp.width = width;
880 comp.height = height;
881 }
882 public Point getLocation(Component comp) {
883 return comp.location_NoClientCode();
884 }
885 public void setLocation(Component comp, int x, int y) {
886 comp.x = x;
887 comp.y = y;
888 }
889 public boolean isEnabled(Component comp) {
890 return comp.isEnabledImpl();
891 }
892 public boolean isDisplayable(Component comp) {
893 return comp.peer != null;
894 }
895 public Cursor getCursor(Component comp) {
896 return comp.getCursor_NoClientCode();
897 }
898 @SuppressWarnings("unchecked")
899 public <T extends ComponentPeer> T getPeer(Component comp) {
900 return (T) comp.peer;
901 }
902 public void setPeer(Component comp, ComponentPeer peer) {
903 comp.peer = peer;
904 }
905 public boolean isLightweight(Component comp) {
906 return (comp.peer instanceof LightweightPeer);
907 }
908 public boolean getIgnoreRepaint(Component comp) {
909 return comp.ignoreRepaint;
910 }
911 public int getWidth(Component comp) {
912 return comp.width;
913 }
914 public int getHeight(Component comp) {
915 return comp.height;
916 }
917 public int getX(Component comp) {
918 return comp.x;
919 }
920 public int getY(Component comp) {
921 return comp.y;
922 }
923 public Color getForeground(Component comp) {
924 return comp.foreground;
925 }
926 public Color getBackground(Component comp) {
927 return comp.background;
928 }
929 public void setBackground(Component comp, Color background) {
930 comp.background = background;
931 }
932 public Font getFont(Component comp) {
933 return comp.getFont_NoClientCode();
934 }
935 public void processEvent(Component comp, AWTEvent e) {
936 comp.processEvent(e);
937 }
938
939 public AccessControlContext getAccessControlContext(Component comp) {
940 return comp.getAccessControlContext();
941 }
942
943 public void revalidateSynchronously(Component comp) {
944 comp.revalidateSynchronously();
945 }
946
947 @Override
948 public void createBufferStrategy(Component comp, int numBuffers,
949 BufferCapabilities caps) throws AWTException {
950 comp.createBufferStrategy(numBuffers, caps);
951 }
952
953 @Override
954 public BufferStrategy getBufferStrategy(Component comp) {
955 return comp.getBufferStrategy();
956 }
957 });
958 }
959
960 /**
961 * Constructs a new component. Class {@code Component} can be
962 * extended directly to create a lightweight component that does not
963 * utilize an opaque native window. A lightweight component must be
964 * hosted by a native container somewhere higher up in the component
965 * tree (for example, by a {@code Frame} object).
966 */
967 protected Component() {
968 appContext = AppContext.getAppContext();
969 }
970
971 @SuppressWarnings({"rawtypes", "unchecked"})
972 void initializeFocusTraversalKeys() {
973 focusTraversalKeys = new Set[3];
974 }
975
976 /**
977 * Constructs a name for this component. Called by {@code getName}
978 * when the name is {@code null}.
979 */
980 String constructComponentName() {
981 return null; // For strict compliance with prior platform versions, a Component
982 // that doesn't set its name should return null from
983 // getName()
984 }
985
986 /**
987 * Gets the name of the component.
988 * @return this component's name
989 * @see #setName
990 * @since 1.1
991 */
992 public String getName() {
993 if (name == null && !nameExplicitlySet) {
994 synchronized(getObjectLock()) {
995 if (name == null && !nameExplicitlySet)
996 name = constructComponentName();
997 }
998 }
999 return name;
1000 }
1001
1002 /**
1003 * Sets the name of the component to the specified string.
1004 * @param name the string that is to be this
1005 * component's name
1006 * @see #getName
1007 * @since 1.1
1008 */
1009 public void setName(String name) {
1010 String oldName;
1011 synchronized(getObjectLock()) {
1012 oldName = this.name;
1013 this.name = name;
1014 nameExplicitlySet = true;
1015 }
1016 firePropertyChange("name", oldName, name);
1017 }
1018
1019 /**
1020 * Gets the parent of this component.
1021 * @return the parent container of this component
1022 * @since 1.0
1023 */
1024 public Container getParent() {
1025 return getParent_NoClientCode();
1026 }
1027
1028 // NOTE: This method may be called by privileged threads.
1029 // This functionality is implemented in a package-private method
1030 // to insure that it cannot be overridden by client subclasses.
1031 // DO NOT INVOKE CLIENT CODE ON THIS THREAD!
1032 final Container getParent_NoClientCode() {
1033 return parent;
1034 }
1035
1036 // This method is overridden in the Window class to return null,
1037 // because the parent field of the Window object contains
1038 // the owner of the window, not its parent.
1039 Container getContainer() {
1040 return getParent_NoClientCode();
1041 }
1042
1043 /**
1044 * Associate a {@code DropTarget} with this component.
1045 * The {@code Component} will receive drops only if it
1046 * is enabled.
1047 *
1048 * @see #isEnabled
1049 * @param dt The DropTarget
1050 */
1051
1052 public synchronized void setDropTarget(DropTarget dt) {
1053 if (dt == dropTarget || (dropTarget != null && dropTarget.equals(dt)))
1054 return;
1055
1056 DropTarget old;
1057
1058 if ((old = dropTarget) != null) {
1059 dropTarget.removeNotify();
1060
1061 DropTarget t = dropTarget;
1062
1063 dropTarget = null;
1064
1065 try {
1066 t.setComponent(null);
1067 } catch (IllegalArgumentException iae) {
1068 // ignore it.
1069 }
1070 }
1071
1072 // if we have a new one, and we have a peer, add it!
1073
1074 if ((dropTarget = dt) != null) {
1075 try {
1076 dropTarget.setComponent(this);
1077 dropTarget.addNotify();
1078 } catch (IllegalArgumentException iae) {
1079 if (old != null) {
1080 try {
1081 old.setComponent(this);
1082 dropTarget.addNotify();
1083 } catch (IllegalArgumentException iae1) {
1084 // ignore it!
1085 }
1086 }
1087 }
1088 }
1089 }
1090
1091 /**
1092 * Gets the {@code DropTarget} associated with this
1093 * {@code Component}.
1094 *
1095 * @return the drop target
1096 */
1097
1098 public synchronized DropTarget getDropTarget() { return dropTarget; }
1099
1100 /**
1101 * Gets the {@code GraphicsConfiguration} associated with this
1102 * {@code Component}.
1103 * If the {@code Component} has not been assigned a specific
1104 * {@code GraphicsConfiguration},
1105 * the {@code GraphicsConfiguration} of the
1106 * {@code Component} object's top-level container is
1107 * returned.
1108 * If the {@code Component} has been created, but not yet added
1109 * to a {@code Container}, this method returns {@code null}.
1110 *
1111 * @return the {@code GraphicsConfiguration} used by this
1112 * {@code Component} or {@code null}
1113 * @since 1.3
1114 */
1115 public GraphicsConfiguration getGraphicsConfiguration() {
1116 return getGraphicsConfiguration_NoClientCode();
1117 }
1118
1119 final GraphicsConfiguration getGraphicsConfiguration_NoClientCode() {
1120 return graphicsConfig;
1121 }
1122
1123 void setGraphicsConfiguration(GraphicsConfiguration gc) {
1124 synchronized(getTreeLock()) {
1125 if (updateGraphicsData(gc)) {
1126 removeNotify();
1127 addNotify();
1128 }
1129 }
1130 }
1131
1132 boolean updateGraphicsData(GraphicsConfiguration gc) {
1133 checkTreeLock();
1134
1135 if (graphicsConfig == gc) {
1136 return false;
1137 }
1138
1139 graphicsConfig = gc;
1140
1141 ComponentPeer peer = this.peer;
1142 if (peer != null) {
1143 return peer.updateGraphicsData(gc);
1144 }
1145 return false;
1146 }
1147
1148 /**
1149 * Checks that this component's {@code GraphicsDevice}
1150 * {@code idString} matches the string argument.
1151 */
1152 void checkGD(String stringID) {
1153 if (graphicsConfig != null) {
1154 if (!graphicsConfig.getDevice().getIDstring().equals(stringID)) {
1155 throw new IllegalArgumentException(
1156 "adding a container to a container on a different GraphicsDevice");
1157 }
1158 }
1159 }
1160
1161 /**
1162 * Gets this component's locking object (the object that owns the thread
1163 * synchronization monitor) for AWT component-tree and layout
1164 * operations.
1165 * @return this component's locking object
1166 */
1167 public final Object getTreeLock() {
1168 return LOCK;
1169 }
1170
1171 final void checkTreeLock() {
1172 if (!Thread.holdsLock(getTreeLock())) {
1173 throw new IllegalStateException("This function should be called while holding treeLock");
1174 }
1175 }
1176
1177 /**
1178 * Gets the toolkit of this component. Note that
1179 * the frame that contains a component controls which
1180 * toolkit is used by that component. Therefore if the component
1181 * is moved from one frame to another, the toolkit it uses may change.
1182 * @return the toolkit of this component
1183 * @since 1.0
1184 */
1185 public Toolkit getToolkit() {
1186 return getToolkitImpl();
1187 }
1188
1189 /*
1190 * This is called by the native code, so client code can't
1191 * be called on the toolkit thread.
1192 */
1193 final Toolkit getToolkitImpl() {
1194 Container parent = this.parent;
1195 if (parent != null) {
1196 return parent.getToolkitImpl();
1197 }
1198 return Toolkit.getDefaultToolkit();
1199 }
1200
1201 final ComponentFactory getComponentFactory() {
1202 final Toolkit toolkit = getToolkit();
1203 if (toolkit instanceof ComponentFactory) {
1204 return (ComponentFactory) toolkit;
1205 }
1206 throw new AWTError("UI components are unsupported by: " + toolkit);
1207 }
1208
1209 /**
1210 * Determines whether this component is valid. A component is valid
1211 * when it is correctly sized and positioned within its parent
1212 * container and all its children are also valid.
1213 * In order to account for peers' size requirements, components are invalidated
1214 * before they are first shown on the screen. By the time the parent container
1215 * is fully realized, all its components will be valid.
1216 * @return {@code true} if the component is valid, {@code false}
1217 * otherwise
1218 * @see #validate
1219 * @see #invalidate
1220 * @since 1.0
1221 */
1222 public boolean isValid() {
1223 return (peer != null) && valid;
1224 }
1225
1226 /**
1227 * Determines whether this component is displayable. A component is
1228 * displayable when it is connected to a native screen resource.
1229 * <p>
1230 * A component is made displayable either when it is added to
1231 * a displayable containment hierarchy or when its containment
1232 * hierarchy is made displayable.
1233 * A containment hierarchy is made displayable when its ancestor
1234 * window is either packed or made visible.
1235 * <p>
1236 * A component is made undisplayable either when it is removed from
1237 * a displayable containment hierarchy or when its containment hierarchy
1238 * is made undisplayable. A containment hierarchy is made
1239 * undisplayable when its ancestor window is disposed.
1240 *
1241 * @return {@code true} if the component is displayable,
1242 * {@code false} otherwise
1243 * @see Container#add(Component)
1244 * @see Window#pack
1245 * @see Window#show
1246 * @see Container#remove(Component)
1247 * @see Window#dispose
1248 * @since 1.2
1249 */
1250 public boolean isDisplayable() {
1251 return peer != null;
1252 }
1253
1254 /**
1255 * Determines whether this component should be visible when its
1256 * parent is visible. Components are
1257 * initially visible, with the exception of top level components such
1258 * as {@code Frame} objects.
1259 * @return {@code true} if the component is visible,
1260 * {@code false} otherwise
1261 * @see #setVisible
1262 * @since 1.0
1263 */
1264 @Transient
1265 public boolean isVisible() {
1266 return isVisible_NoClientCode();
1267 }
1268 final boolean isVisible_NoClientCode() {
1269 return visible;
1270 }
1271
1272 /**
1273 * Determines whether this component will be displayed on the screen.
1274 * @return {@code true} if the component and all of its ancestors
1275 * until a toplevel window or null parent are visible,
1276 * {@code false} otherwise
1277 */
1278 boolean isRecursivelyVisible() {
1279 return visible && (parent == null || parent.isRecursivelyVisible());
1280 }
1281
1282 /**
1283 * Determines the bounds of a visible part of the component relative to its
1284 * parent.
1285 *
1286 * @return the visible part of bounds
1287 */
1288 private Rectangle getRecursivelyVisibleBounds() {
1289 final Component container = getContainer();
1290 final Rectangle bounds = getBounds();
1291 if (container == null) {
1292 // we are top level window or haven't a container, return our bounds
1293 return bounds;
1294 }
1295 // translate the container's bounds to our coordinate space
1296 final Rectangle parentsBounds = container.getRecursivelyVisibleBounds();
1297 parentsBounds.setLocation(0, 0);
1298 return parentsBounds.intersection(bounds);
1299 }
1300
1301 /**
1302 * Translates absolute coordinates into coordinates in the coordinate
1303 * space of this component.
1304 */
1305 Point pointRelativeToComponent(Point absolute) {
1306 Point compCoords = getLocationOnScreen();
1307 return new Point(absolute.x - compCoords.x,
1308 absolute.y - compCoords.y);
1309 }
1310
1311 /**
1312 * Assuming that mouse location is stored in PointerInfo passed
1313 * to this method, it finds a Component that is in the same
1314 * Window as this Component and is located under the mouse pointer.
1315 * If no such Component exists, null is returned.
1316 * NOTE: this method should be called under the protection of
1317 * tree lock, as it is done in Component.getMousePosition() and
1318 * Container.getMousePosition(boolean).
1319 */
1320 Component findUnderMouseInWindow(PointerInfo pi) {
1321 if (!isShowing()) {
1322 return null;
1323 }
1324 Window win = getContainingWindow();
1325 Toolkit toolkit = Toolkit.getDefaultToolkit();
1326 if (!(toolkit instanceof ComponentFactory)) {
1327 return null;
1328 }
1329 if (!((ComponentFactory) toolkit).getMouseInfoPeer().isWindowUnderMouse(win)) {
1330 return null;
1331 }
1332 final boolean INCLUDE_DISABLED = true;
1333 Point relativeToWindow = win.pointRelativeToComponent(pi.getLocation());
1334 Component inTheSameWindow = win.findComponentAt(relativeToWindow.x,
1335 relativeToWindow.y,
1336 INCLUDE_DISABLED);
1337 return inTheSameWindow;
1338 }
1339
1340 /**
1341 * Returns the position of the mouse pointer in this {@code Component}'s
1342 * coordinate space if the {@code Component} is directly under the mouse
1343 * pointer, otherwise returns {@code null}.
1344 * If the {@code Component} is not showing on the screen, this method
1345 * returns {@code null} even if the mouse pointer is above the area
1346 * where the {@code Component} would be displayed.
1347 * If the {@code Component} is partially or fully obscured by other
1348 * {@code Component}s or native windows, this method returns a non-null
1349 * value only if the mouse pointer is located above the unobscured part of the
1350 * {@code Component}.
1351 * <p>
1352 * For {@code Container}s it returns a non-null value if the mouse is
1353 * above the {@code Container} itself or above any of its descendants.
1354 * Use {@link Container#getMousePosition(boolean)} if you need to exclude children.
1355 * <p>
1356 * Sometimes the exact mouse coordinates are not important, and the only thing
1357 * that matters is whether a specific {@code Component} is under the mouse
1358 * pointer. If the return value of this method is {@code null}, mouse
1359 * pointer is not directly above the {@code Component}.
1360 *
1361 * @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true
1362 * @see #isShowing
1363 * @see Container#getMousePosition
1364 * @return mouse coordinates relative to this {@code Component}, or null
1365 * @since 1.5
1366 */
1367 public Point getMousePosition() throws HeadlessException {
1368 if (GraphicsEnvironment.isHeadless()) {
1369 throw new HeadlessException();
1370 }
1371
1372 PointerInfo pi = java.security.AccessController.doPrivileged(
1373 new java.security.PrivilegedAction<PointerInfo>() {
1374 public PointerInfo run() {
1375 return MouseInfo.getPointerInfo();
1376 }
1377 }
1378 );
1379
1380 synchronized (getTreeLock()) {
1381 Component inTheSameWindow = findUnderMouseInWindow(pi);
1382 if (!isSameOrAncestorOf(inTheSameWindow, true)) {
1383 return null;
1384 }
1385 return pointRelativeToComponent(pi.getLocation());
1386 }
1387 }
1388
1389 /**
1390 * Overridden in Container. Must be called under TreeLock.
1391 */
1392 boolean isSameOrAncestorOf(Component comp, boolean allowChildren) {
1393 return comp == this;
1394 }
1395
1396 /**
1397 * Determines whether this component is showing on screen. This means
1398 * that the component must be visible, and it must be in a container
1399 * that is visible and showing.
1400 * <p>
1401 * <strong>Note:</strong> sometimes there is no way to detect whether the
1402 * {@code Component} is actually visible to the user. This can happen when:
1403 * <ul>
1404 * <li>the component has been added to a visible {@code ScrollPane} but
1405 * the {@code Component} is not currently in the scroll pane's view port.
1406 * <li>the {@code Component} is obscured by another {@code Component} or
1407 * {@code Container}.
1408 * </ul>
1409 * @return {@code true} if the component is showing,
1410 * {@code false} otherwise
1411 * @see #setVisible
1412 * @since 1.0
1413 */
1414 public boolean isShowing() {
1415 if (visible && (peer != null)) {
1416 Container parent = this.parent;
1417 return (parent == null) || parent.isShowing();
1418 }
1419 return false;
1420 }
1421
1422 /**
1423 * Determines whether this component is enabled. An enabled component
1424 * can respond to user input and generate events. Components are
1425 * enabled initially by default. A component may be enabled or disabled by
1426 * calling its {@code setEnabled} method.
1427 * @return {@code true} if the component is enabled,
1428 * {@code false} otherwise
1429 * @see #setEnabled
1430 * @since 1.0
1431 */
1432 public boolean isEnabled() {
1433 return isEnabledImpl();
1434 }
1435
1436 /*
1437 * This is called by the native code, so client code can't
1438 * be called on the toolkit thread.
1439 */
1440 final boolean isEnabledImpl() {
1441 return enabled;
1442 }
1443
1444 /**
1445 * Enables or disables this component, depending on the value of the
1446 * parameter {@code b}. An enabled component can respond to user
1447 * input and generate events. Components are enabled initially by default.
1448 *
1449 * <p>Note: Disabling a lightweight component does not prevent it from
1450 * receiving MouseEvents.
1451 * <p>Note: Disabling a heavyweight container prevents all components
1452 * in this container from receiving any input events. But disabling a
1453 * lightweight container affects only this container.
1454 *
1455 * @param b If {@code true}, this component is
1456 * enabled; otherwise this component is disabled
1457 * @see #isEnabled
1458 * @see #isLightweight
1459 * @since 1.1
1460 */
1461 public void setEnabled(boolean b) {
1462 enable(b);
1463 }
1464
1465 /**
1466 * @deprecated As of JDK version 1.1,
1467 * replaced by {@code setEnabled(boolean)}.
1468 */
1469 @Deprecated
1470 public void enable() {
1471 if (!enabled) {
1472 synchronized (getTreeLock()) {
1473 enabled = true;
1474 ComponentPeer peer = this.peer;
1475 if (peer != null) {
1476 peer.setEnabled(true);
1477 if (visible && !getRecursivelyVisibleBounds().isEmpty()) {
1478 updateCursorImmediately();
1479 }
1480 }
1481 }
1482 if (accessibleContext != null) {
1483 accessibleContext.firePropertyChange(
1484 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
1485 null, AccessibleState.ENABLED);
1486 }
1487 }
1488 }
1489
1490 /**
1491 * Enables or disables this component.
1492 *
1493 * @param b {@code true} to enable this component;
1494 * otherwise {@code false}
1495 *
1496 * @deprecated As of JDK version 1.1,
1497 * replaced by {@code setEnabled(boolean)}.
1498 */
1499 @Deprecated
1500 public void enable(boolean b) {
1501 if (b) {
1502 enable();
1503 } else {
1504 disable();
1505 }
1506 }
1507
1508 /**
1509 * @deprecated As of JDK version 1.1,
1510 * replaced by {@code setEnabled(boolean)}.
1511 */
1512 @Deprecated
1513 public void disable() {
1514 if (enabled) {
1515 KeyboardFocusManager.clearMostRecentFocusOwner(this);
1516 synchronized (getTreeLock()) {
1517 enabled = false;
1518 // A disabled lw container is allowed to contain a focus owner.
1519 if ((isFocusOwner() || (containsFocus() && !isLightweight())) &&
1520 KeyboardFocusManager.isAutoFocusTransferEnabled())
1521 {
1522 // Don't clear the global focus owner. If transferFocus
1523 // fails, we want the focus to stay on the disabled
1524 // Component so that keyboard traversal, et. al. still
1525 // makes sense to the user.
1526 transferFocus(false);
1527 }
1528 ComponentPeer peer = this.peer;
1529 if (peer != null) {
1530 peer.setEnabled(false);
1531 if (visible && !getRecursivelyVisibleBounds().isEmpty()) {
1532 updateCursorImmediately();
1533 }
1534 }
1535 }
1536 if (accessibleContext != null) {
1537 accessibleContext.firePropertyChange(
1538 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
1539 null, AccessibleState.ENABLED);
1540 }
1541 }
1542 }
1543
1544 /**
1545 * Returns true if this component is painted to an offscreen image
1546 * ("buffer") that's copied to the screen later. Component
1547 * subclasses that support double buffering should override this
1548 * method to return true if double buffering is enabled.
1549 *
1550 * @return false by default
1551 */
1552 public boolean isDoubleBuffered() {
1553 return false;
1554 }
1555
1556 /**
1557 * Enables or disables input method support for this component. If input
1558 * method support is enabled and the component also processes key events,
1559 * incoming events are offered to
1560 * the current input method and will only be processed by the component or
1561 * dispatched to its listeners if the input method does not consume them.
1562 * By default, input method support is enabled.
1563 *
1564 * @param enable true to enable, false to disable
1565 * @see #processKeyEvent
1566 * @since 1.2
1567 */
1568 public void enableInputMethods(boolean enable) {
1569 if (enable) {
1570 if ((eventMask & AWTEvent.INPUT_METHODS_ENABLED_MASK) != 0)
1571 return;
1572
1573 // If this component already has focus, then activate the
1574 // input method by dispatching a synthesized focus gained
1575 // event.
1576 if (isFocusOwner()) {
1577 InputContext inputContext = getInputContext();
1578 if (inputContext != null) {
1579 FocusEvent focusGainedEvent =
1580 new FocusEvent(this, FocusEvent.FOCUS_GAINED);
1581 inputContext.dispatchEvent(focusGainedEvent);
1582 }
1583 }
1584
1585 eventMask |= AWTEvent.INPUT_METHODS_ENABLED_MASK;
1586 } else {
1587 if ((eventMask & AWTEvent.INPUT_METHODS_ENABLED_MASK) != 0) {
1588 InputContext inputContext = getInputContext();
1589 if (inputContext != null) {
1590 inputContext.endComposition();
1591 inputContext.removeNotify(this);
1592 }
1593 }
1594 eventMask &= ~AWTEvent.INPUT_METHODS_ENABLED_MASK;
1595 }
1596 }
1597
1598 /**
1599 * Shows or hides this component depending on the value of parameter
1600 * {@code b}.
1601 * <p>
1602 * This method changes layout-related information, and therefore,
1603 * invalidates the component hierarchy.
1604 *
1605 * @param b if {@code true}, shows this component;
1606 * otherwise, hides this component
1607 * @see #isVisible
1608 * @see #invalidate
1609 * @since 1.1
1610 */
1611 public void setVisible(boolean b) {
1612 show(b);
1613 }
1614
1615 /**
1616 * @deprecated As of JDK version 1.1,
1617 * replaced by {@code setVisible(boolean)}.
1618 */
1619 @Deprecated
1620 public void show() {
1621 if (!visible) {
1622 synchronized (getTreeLock()) {
1623 visible = true;
1624 mixOnShowing();
1625 ComponentPeer peer = this.peer;
1626 if (peer != null) {
1627 peer.setVisible(true);
1628 createHierarchyEvents(HierarchyEvent.HIERARCHY_CHANGED,
1629 this, parent,
1630 HierarchyEvent.SHOWING_CHANGED,
1631 Toolkit.enabledOnToolkit(AWTEvent.HIERARCHY_EVENT_MASK));
1632 if (peer instanceof LightweightPeer) {
1633 repaint();
1634 }
1635 updateCursorImmediately();
1636 }
1637
1638 if (componentListener != null ||
1639 (eventMask & AWTEvent.COMPONENT_EVENT_MASK) != 0 ||
1640 Toolkit.enabledOnToolkit(AWTEvent.COMPONENT_EVENT_MASK)) {
1641 ComponentEvent e = new ComponentEvent(this,
1642 ComponentEvent.COMPONENT_SHOWN);
1643 Toolkit.getEventQueue().postEvent(e);
1644 }
1645 }
1646 Container parent = this.parent;
1647 if (parent != null) {
1648 parent.invalidate();
1649 }
1650 }
1651 }
1652
1653 /**
1654 * Makes this component visible or invisible.
1655 *
1656 * @param b {@code true} to make this component visible;
1657 * otherwise {@code false}
1658 *
1659 * @deprecated As of JDK version 1.1,
1660 * replaced by {@code setVisible(boolean)}.
1661 */
1662 @Deprecated
1663 public void show(boolean b) {
1664 if (b) {
1665 show();
1666 } else {
1667 hide();
1668 }
1669 }
1670
1671 boolean containsFocus() {
1672 return isFocusOwner();
1673 }
1674
1675 void clearMostRecentFocusOwnerOnHide() {
1676 KeyboardFocusManager.clearMostRecentFocusOwner(this);
1677 }
1678
1679 void clearCurrentFocusCycleRootOnHide() {
1680 /* do nothing */
1681 }
1682
1683 /**
1684 * @deprecated As of JDK version 1.1,
1685 * replaced by {@code setVisible(boolean)}.
1686 */
1687 @Deprecated
1688 public void hide() {
1689 isPacked = false;
1690
1691 if (visible) {
1692 clearCurrentFocusCycleRootOnHide();
1693 clearMostRecentFocusOwnerOnHide();
1694 synchronized (getTreeLock()) {
1695 visible = false;
1696 mixOnHiding(isLightweight());
1697 if (containsFocus() && KeyboardFocusManager.isAutoFocusTransferEnabled()) {
1698 transferFocus(true);
1699 }
1700 ComponentPeer peer = this.peer;
1701 if (peer != null) {
1702 peer.setVisible(false);
1703 createHierarchyEvents(HierarchyEvent.HIERARCHY_CHANGED,
1704 this, parent,
1705 HierarchyEvent.SHOWING_CHANGED,
1706 Toolkit.enabledOnToolkit(AWTEvent.HIERARCHY_EVENT_MASK));
1707 if (peer instanceof LightweightPeer) {
1708 repaint();
1709 }
1710 updateCursorImmediately();
1711 }
1712 if (componentListener != null ||
1713 (eventMask & AWTEvent.COMPONENT_EVENT_MASK) != 0 ||
1714 Toolkit.enabledOnToolkit(AWTEvent.COMPONENT_EVENT_MASK)) {
1715 ComponentEvent e = new ComponentEvent(this,
1716 ComponentEvent.COMPONENT_HIDDEN);
1717 Toolkit.getEventQueue().postEvent(e);
1718 }
1719 }
1720 Container parent = this.parent;
1721 if (parent != null) {
1722 parent.invalidate();
1723 }
1724 }
1725 }
1726
1727 /**
1728 * Gets the foreground color of this component.
1729 * @return this component's foreground color; if this component does
1730 * not have a foreground color, the foreground color of its parent
1731 * is returned
1732 * @see #setForeground
1733 * @since 1.0
1734 */
1735 @Transient
1736 public Color getForeground() {
1737 Color foreground = this.foreground;
1738 if (foreground != null) {
1739 return foreground;
1740 }
1741 Container parent = this.parent;
1742 return (parent != null) ? parent.getForeground() : null;
1743 }
1744
1745 /**
1746 * Sets the foreground color of this component.
1747 * @param c the color to become this component's
1748 * foreground color; if this parameter is {@code null}
1749 * then this component will inherit
1750 * the foreground color of its parent
1751 * @see #getForeground
1752 * @since 1.0
1753 */
1754 public void setForeground(Color c) {
1755 Color oldColor = foreground;
1756 ComponentPeer peer = this.peer;
1757 foreground = c;
1758 if (peer != null) {
1759 c = getForeground();
1760 if (c != null) {
1761 peer.setForeground(c);
1762 }
1763 }
1764 // This is a bound property, so report the change to
1765 // any registered listeners. (Cheap if there are none.)
1766 firePropertyChange("foreground", oldColor, c);
1767 }
1768
1769 /**
1770 * Returns whether the foreground color has been explicitly set for this
1771 * Component. If this method returns {@code false}, this Component is
1772 * inheriting its foreground color from an ancestor.
1773 *
1774 * @return {@code true} if the foreground color has been explicitly
1775 * set for this Component; {@code false} otherwise.
1776 * @since 1.4
1777 */
1778 public boolean isForegroundSet() {
1779 return (foreground != null);
1780 }
1781
1782 /**
1783 * Gets the background color of this component.
1784 * @return this component's background color; if this component does
1785 * not have a background color,
1786 * the background color of its parent is returned
1787 * @see #setBackground
1788 * @since 1.0
1789 */
1790 @Transient
1791 public Color getBackground() {
1792 Color background = this.background;
1793 if (background != null) {
1794 return background;
1795 }
1796 Container parent = this.parent;
1797 return (parent != null) ? parent.getBackground() : null;
1798 }
1799
1800 /**
1801 * Sets the background color of this component.
1802 * <p>
1803 * The background color affects each component differently and the
1804 * parts of the component that are affected by the background color
1805 * may differ between operating systems.
1806 *
1807 * @param c the color to become this component's color;
1808 * if this parameter is {@code null}, then this
1809 * component will inherit the background color of its parent
1810 * @see #getBackground
1811 * @since 1.0
1812 */
1813 public void setBackground(Color c) {
1814 Color oldColor = background;
1815 ComponentPeer peer = this.peer;
1816 background = c;
1817 if (peer != null) {
1818 c = getBackground();
1819 if (c != null) {
1820 peer.setBackground(c);
1821 }
1822 }
1823 // This is a bound property, so report the change to
1824 // any registered listeners. (Cheap if there are none.)
1825 firePropertyChange("background", oldColor, c);
1826 }
1827
1828 /**
1829 * Returns whether the background color has been explicitly set for this
1830 * Component. If this method returns {@code false}, this Component is
1831 * inheriting its background color from an ancestor.
1832 *
1833 * @return {@code true} if the background color has been explicitly
1834 * set for this Component; {@code false} otherwise.
1835 * @since 1.4
1836 */
1837 public boolean isBackgroundSet() {
1838 return (background != null);
1839 }
1840
1841 /**
1842 * Gets the font of this component.
1843 * @return this component's font; if a font has not been set
1844 * for this component, the font of its parent is returned
1845 * @see #setFont
1846 * @since 1.0
1847 */
1848 @Transient
1849 public Font getFont() {
1850 return getFont_NoClientCode();
1851 }
1852
1853 // NOTE: This method may be called by privileged threads.
1854 // This functionality is implemented in a package-private method
1855 // to insure that it cannot be overridden by client subclasses.
1856 // DO NOT INVOKE CLIENT CODE ON THIS THREAD!
1857 final Font getFont_NoClientCode() {
1858 Font font = this.font;
1859 if (font != null) {
1860 return font;
1861 }
1862 Container parent = this.parent;
1863 return (parent != null) ? parent.getFont_NoClientCode() : null;
1864 }
1865
1866 /**
1867 * Sets the font of this component.
1868 * <p>
1869 * This method changes layout-related information, and therefore,
1870 * invalidates the component hierarchy.
1871 *
1872 * @param f the font to become this component's font;
1873 * if this parameter is {@code null} then this
1874 * component will inherit the font of its parent
1875 * @see #getFont
1876 * @see #invalidate
1877 * @since 1.0
1878 */
1879 public void setFont(Font f) {
1880 Font oldFont, newFont;
1881 synchronized(getTreeLock()) {
1882 oldFont = font;
1883 newFont = font = f;
1884 ComponentPeer peer = this.peer;
1885 if (peer != null) {
1886 f = getFont();
1887 if (f != null) {
1888 peer.setFont(f);
1889 peerFont = f;
1890 }
1891 }
1892 }
1893 // This is a bound property, so report the change to
1894 // any registered listeners. (Cheap if there are none.)
1895 firePropertyChange("font", oldFont, newFont);
1896
1897 // This could change the preferred size of the Component.
1898 // Fix for 6213660. Should compare old and new fonts and do not
1899 // call invalidate() if they are equal.
1900 if (f != oldFont && (oldFont == null ||
1901 !oldFont.equals(f))) {
1902 invalidateIfValid();
1903 }
1904 }
1905
1906 /**
1907 * Returns whether the font has been explicitly set for this Component. If
1908 * this method returns {@code false}, this Component is inheriting its
1909 * font from an ancestor.
1910 *
1911 * @return {@code true} if the font has been explicitly set for this
1912 * Component; {@code false} otherwise.
1913 * @since 1.4
1914 */
1915 public boolean isFontSet() {
1916 return (font != null);
1917 }
1918
1919 /**
1920 * Gets the locale of this component.
1921 * @return this component's locale; if this component does not
1922 * have a locale, the locale of its parent is returned
1923 * @see #setLocale
1924 * @exception IllegalComponentStateException if the {@code Component}
1925 * does not have its own locale and has not yet been added to
1926 * a containment hierarchy such that the locale can be determined
1927 * from the containing parent
1928 * @since 1.1
1929 */
1930 public Locale getLocale() {
1931 Locale locale = this.locale;
1932 if (locale != null) {
1933 return locale;
1934 }
1935 Container parent = this.parent;
1936
1937 if (parent == null) {
1938 throw new IllegalComponentStateException("This component must have a parent in order to determine its locale");
1939 } else {
1940 return parent.getLocale();
1941 }
1942 }
1943
1944 /**
1945 * Sets the locale of this component. This is a bound property.
1946 * <p>
1947 * This method changes layout-related information, and therefore,
1948 * invalidates the component hierarchy.
1949 *
1950 * @param l the locale to become this component's locale
1951 * @see #getLocale
1952 * @see #invalidate
1953 * @since 1.1
1954 */
1955 public void setLocale(Locale l) {
1956 Locale oldValue = locale;
1957 locale = l;
1958
1959 // This is a bound property, so report the change to
1960 // any registered listeners. (Cheap if there are none.)
1961 firePropertyChange("locale", oldValue, l);
1962
1963 // This could change the preferred size of the Component.
1964 invalidateIfValid();
1965 }
1966
1967 /**
1968 * Gets the instance of {@code ColorModel} used to display
1969 * the component on the output device.
1970 * @return the color model used by this component
1971 * @see java.awt.image.ColorModel
1972 * @see java.awt.peer.ComponentPeer#getColorModel()
1973 * @see Toolkit#getColorModel()
1974 * @since 1.0
1975 */
1976 public ColorModel getColorModel() {
1977 ComponentPeer peer = this.peer;
1978 if ((peer != null) && ! (peer instanceof LightweightPeer)) {
1979 return peer.getColorModel();
1980 } else if (GraphicsEnvironment.isHeadless()) {
1981 return ColorModel.getRGBdefault();
1982 } // else
1983 return getToolkit().getColorModel();
1984 }
1985
1986 /**
1987 * Gets the location of this component in the form of a
1988 * point specifying the component's top-left corner.
1989 * The location will be relative to the parent's coordinate space.
1990 * <p>
1991 * Due to the asynchronous nature of native event handling, this
1992 * method can return outdated values (for instance, after several calls
1993 * of {@code setLocation()} in rapid succession). For this
1994 * reason, the recommended method of obtaining a component's position is
1995 * within {@code java.awt.event.ComponentListener.componentMoved()},
1996 * which is called after the operating system has finished moving the
1997 * component.
1998 * </p>
1999 * @return an instance of {@code Point} representing
2000 * the top-left corner of the component's bounds in
2001 * the coordinate space of the component's parent
2002 * @see #setLocation
2003 * @see #getLocationOnScreen
2004 * @since 1.1
2005 */
2006 public Point getLocation() {
2007 return location();
2008 }
2009
2010 /**
2011 * Gets the location of this component in the form of a point
2012 * specifying the component's top-left corner in the screen's
2013 * coordinate space.
2014 * @return an instance of {@code Point} representing
2015 * the top-left corner of the component's bounds in the
2016 * coordinate space of the screen
2017 * @throws IllegalComponentStateException if the
2018 * component is not showing on the screen
2019 * @see #setLocation
2020 * @see #getLocation
2021 */
2022 public Point getLocationOnScreen() {
2023 synchronized (getTreeLock()) {
2024 return getLocationOnScreen_NoTreeLock();
2025 }
2026 }
2027
2028 /*
2029 * a package private version of getLocationOnScreen
2030 * used by GlobalCursormanager to update cursor
2031 */
2032 final Point getLocationOnScreen_NoTreeLock() {
2033
2034 if (peer != null && isShowing()) {
2035 if (peer instanceof LightweightPeer) {
2036 // lightweight component location needs to be translated
2037 // relative to a native component.
2038 Container host = getNativeContainer();
2039 Point pt = host.peer.getLocationOnScreen();
2040 for(Component c = this; c != host; c = c.getParent()) {
2041 pt.x += c.x;
2042 pt.y += c.y;
2043 }
2044 return pt;
2045 } else {
2046 Point pt = peer.getLocationOnScreen();
2047 return pt;
2048 }
2049 } else {
2050 throw new IllegalComponentStateException("component must be showing on the screen to determine its location");
2051 }
2052 }
2053
2054
2055 /**
2056 * Returns the location of this component's top left corner.
2057 *
2058 * @return the location of this component's top left corner
2059 * @deprecated As of JDK version 1.1,
2060 * replaced by {@code getLocation()}.
2061 */
2062 @Deprecated
2063 public Point location() {
2064 return location_NoClientCode();
2065 }
2066
2067 private Point location_NoClientCode() {
2068 return new Point(x, y);
2069 }
2070
2071 /**
2072 * Moves this component to a new location. The top-left corner of
2073 * the new location is specified by the {@code x} and {@code y}
2074 * parameters in the coordinate space of this component's parent.
2075 * <p>
2076 * This method changes layout-related information, and therefore,
2077 * invalidates the component hierarchy.
2078 *
2079 * @param x the <i>x</i>-coordinate of the new location's
2080 * top-left corner in the parent's coordinate space
2081 * @param y the <i>y</i>-coordinate of the new location's
2082 * top-left corner in the parent's coordinate space
2083 * @see #getLocation
2084 * @see #setBounds
2085 * @see #invalidate
2086 * @since 1.1
2087 */
2088 public void setLocation(int x, int y) {
2089 move(x, y);
2090 }
2091
2092 /**
2093 * Moves this component to a new location.
2094 *
2095 * @param x the <i>x</i>-coordinate of the new location's
2096 * top-left corner in the parent's coordinate space
2097 * @param y the <i>y</i>-coordinate of the new location's
2098 * top-left corner in the parent's coordinate space
2099 *
2100 * @deprecated As of JDK version 1.1,
2101 * replaced by {@code setLocation(int, int)}.
2102 */
2103 @Deprecated
2104 public void move(int x, int y) {
2105 synchronized(getTreeLock()) {
2106 setBoundsOp(ComponentPeer.SET_LOCATION);
2107 setBounds(x, y, width, height);
2108 }
2109 }
2110
2111 /**
2112 * Moves this component to a new location. The top-left corner of
2113 * the new location is specified by point {@code p}. Point
2114 * {@code p} is given in the parent's coordinate space.
2115 * <p>
2116 * This method changes layout-related information, and therefore,
2117 * invalidates the component hierarchy.
2118 *
2119 * @param p the point defining the top-left corner
2120 * of the new location, given in the coordinate space of this
2121 * component's parent
2122 * @see #getLocation
2123 * @see #setBounds
2124 * @see #invalidate
2125 * @since 1.1
2126 */
2127 public void setLocation(Point p) {
2128 setLocation(p.x, p.y);
2129 }
2130
2131 /**
2132 * Returns the size of this component in the form of a
2133 * {@code Dimension} object. The {@code height}
2134 * field of the {@code Dimension} object contains
2135 * this component's height, and the {@code width}
2136 * field of the {@code Dimension} object contains
2137 * this component's width.
2138 * @return a {@code Dimension} object that indicates the
2139 * size of this component
2140 * @see #setSize
2141 * @since 1.1
2142 */
2143 public Dimension getSize() {
2144 return size();
2145 }
2146
2147 /**
2148 * Returns the size of this component in the form of a
2149 * {@code Dimension} object.
2150 *
2151 * @return the {@code Dimension} object that indicates the
2152 * size of this component
2153 * @deprecated As of JDK version 1.1,
2154 * replaced by {@code getSize()}.
2155 */
2156 @Deprecated
2157 public Dimension size() {
2158 return new Dimension(width, height);
2159 }
2160
2161 /**
2162 * Resizes this component so that it has width {@code width}
2163 * and height {@code height}.
2164 * <p>
2165 * This method changes layout-related information, and therefore,
2166 * invalidates the component hierarchy.
2167 *
2168 * @param width the new width of this component in pixels
2169 * @param height the new height of this component in pixels
2170 * @see #getSize
2171 * @see #setBounds
2172 * @see #invalidate
2173 * @since 1.1
2174 */
2175 public void setSize(int width, int height) {
2176 resize(width, height);
2177 }
2178
2179 /**
2180 * Resizes this component.
2181 *
2182 * @param width the new width of the component
2183 * @param height the new height of the component
2184 * @deprecated As of JDK version 1.1,
2185 * replaced by {@code setSize(int, int)}.
2186 */
2187 @Deprecated
2188 public void resize(int width, int height) {
2189 synchronized(getTreeLock()) {
2190 setBoundsOp(ComponentPeer.SET_SIZE);
2191 setBounds(x, y, width, height);
2192 }
2193 }
2194
2195 /**
2196 * Resizes this component so that it has width {@code d.width}
2197 * and height {@code d.height}.
2198 * <p>
2199 * This method changes layout-related information, and therefore,
2200 * invalidates the component hierarchy.
2201 *
2202 * @param d the dimension specifying the new size
2203 * of this component
2204 * @throws NullPointerException if {@code d} is {@code null}
2205 * @see #setSize
2206 * @see #setBounds
2207 * @see #invalidate
2208 * @since 1.1
2209 */
2210 public void setSize(Dimension d) {
2211 resize(d);
2212 }
2213
2214 /**
2215 * Resizes this component so that it has width {@code d.width}
2216 * and height {@code d.height}.
2217 *
2218 * @param d the new size of this component
2219 * @deprecated As of JDK version 1.1,
2220 * replaced by {@code setSize(Dimension)}.
2221 */
2222 @Deprecated
2223 public void resize(Dimension d) {
2224 setSize(d.width, d.height);
2225 }
2226
2227 /**
2228 * Gets the bounds of this component in the form of a
2229 * {@code Rectangle} object. The bounds specify this
2230 * component's width, height, and location relative to
2231 * its parent.
2232 * @return a rectangle indicating this component's bounds
2233 * @see #setBounds
2234 * @see #getLocation
2235 * @see #getSize
2236 */
2237 public Rectangle getBounds() {
2238 return bounds();
2239 }
2240
2241 /**
2242 * Returns the bounding rectangle of this component.
2243 *
2244 * @return the bounding rectangle for this component
2245 * @deprecated As of JDK version 1.1,
2246 * replaced by {@code getBounds()}.
2247 */
2248 @Deprecated
2249 public Rectangle bounds() {
2250 return new Rectangle(x, y, width, height);
2251 }
2252
2253 /**
2254 * Moves and resizes this component. The new location of the top-left
2255 * corner is specified by {@code x} and {@code y}, and the
2256 * new size is specified by {@code width} and {@code height}.
2257 * <p>
2258 * This method changes layout-related information, and therefore,
2259 * invalidates the component hierarchy.
2260 *
2261 * @param x the new <i>x</i>-coordinate of this component
2262 * @param y the new <i>y</i>-coordinate of this component
2263 * @param width the new {@code width} of this component
2264 * @param height the new {@code height} of this
2265 * component
2266 * @see #getBounds
2267 * @see #setLocation(int, int)
2268 * @see #setLocation(Point)
2269 * @see #setSize(int, int)
2270 * @see #setSize(Dimension)
2271 * @see #invalidate
2272 * @since 1.1
2273 */
2274 public void setBounds(int x, int y, int width, int height) {
2275 reshape(x, y, width, height);
2276 }
2277
2278 /**
2279 * Reshapes the bounding rectangle for this component.
2280 *
2281 * @param x the <i>x</i> coordinate of the upper left corner of the rectangle
2282 * @param y the <i>y</i> coordinate of the upper left corner of the rectangle
2283 * @param width the width of the rectangle
2284 * @param height the height of the rectangle
2285 *
2286 * @deprecated As of JDK version 1.1,
2287 * replaced by {@code setBounds(int, int, int, int)}.
2288 */
2289 @Deprecated
2290 public void reshape(int x, int y, int width, int height) {
2291 synchronized (getTreeLock()) {
2292 try {
2293 setBoundsOp(ComponentPeer.SET_BOUNDS);
2294 boolean resized = (this.width != width) || (this.height != height);
2295 boolean moved = (this.x != x) || (this.y != y);
2296 if (!resized && !moved) {
2297 return;
2298 }
2299 int oldX = this.x;
2300 int oldY = this.y;
2301 int oldWidth = this.width;
2302 int oldHeight = this.height;
2303 this.x = x;
2304 this.y = y;
2305 this.width = width;
2306 this.height = height;
2307
2308 if (resized) {
2309 isPacked = false;
2310 }
2311
2312 boolean needNotify = true;
2313 mixOnReshaping();
2314 if (peer != null) {
2315 // LightweightPeer is an empty stub so can skip peer.reshape
2316 if (!(peer instanceof LightweightPeer)) {
2317 reshapeNativePeer(x, y, width, height, getBoundsOp());
2318 // Check peer actually changed coordinates
2319 resized = (oldWidth != this.width) || (oldHeight != this.height);
2320 moved = (oldX != this.x) || (oldY != this.y);
2321 // fix for 5025858: do not send ComponentEvents for toplevel
2322 // windows here as it is done from peer or native code when
2323 // the window is really resized or moved, otherwise some
2324 // events may be sent twice
2325 if (this instanceof Window) {
2326 needNotify = false;
2327 }
2328 }
2329 if (resized) {
2330 invalidate();
2331 }
2332 if (parent != null) {
2333 parent.invalidateIfValid();
2334 }
2335 }
2336 if (needNotify) {
2337 notifyNewBounds(resized, moved);
2338 }
2339 repaintParentIfNeeded(oldX, oldY, oldWidth, oldHeight);
2340 } finally {
2341 setBoundsOp(ComponentPeer.RESET_OPERATION);
2342 }
2343 }
2344 }
2345
2346 private void repaintParentIfNeeded(int oldX, int oldY, int oldWidth,
2347 int oldHeight)
2348 {
2349 if (parent != null && peer instanceof LightweightPeer && isShowing()) {
2350 // Have the parent redraw the area this component occupied.
2351 parent.repaint(oldX, oldY, oldWidth, oldHeight);
2352 // Have the parent redraw the area this component *now* occupies.
2353 repaint();
2354 }
2355 }
2356
2357 private void reshapeNativePeer(int x, int y, int width, int height, int op) {
2358 // native peer might be offset by more than direct
2359 // parent since parent might be lightweight.
2360 int nativeX = x;
2361 int nativeY = y;
2362 for (Component c = parent;
2363 (c != null) && (c.peer instanceof LightweightPeer);
2364 c = c.parent)
2365 {
2366 nativeX += c.x;
2367 nativeY += c.y;
2368 }
2369 peer.setBounds(nativeX, nativeY, width, height, op);
2370 }
2371
2372 @SuppressWarnings("deprecation")
2373 private void notifyNewBounds(boolean resized, boolean moved) {
2374 if (componentListener != null
2375 || (eventMask & AWTEvent.COMPONENT_EVENT_MASK) != 0
2376 || Toolkit.enabledOnToolkit(AWTEvent.COMPONENT_EVENT_MASK))
2377 {
2378 if (resized) {
2379 ComponentEvent e = new ComponentEvent(this,
2380 ComponentEvent.COMPONENT_RESIZED);
2381 Toolkit.getEventQueue().postEvent(e);
2382 }
2383 if (moved) {
2384 ComponentEvent e = new ComponentEvent(this,
2385 ComponentEvent.COMPONENT_MOVED);
2386 Toolkit.getEventQueue().postEvent(e);
2387 }
2388 } else {
2389 if (this instanceof Container && ((Container)this).countComponents() > 0) {
2390 boolean enabledOnToolkit =
2391 Toolkit.enabledOnToolkit(AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK);
2392 if (resized) {
2393
2394 ((Container)this).createChildHierarchyEvents(
2395 HierarchyEvent.ANCESTOR_RESIZED, 0, enabledOnToolkit);
2396 }
2397 if (moved) {
2398 ((Container)this).createChildHierarchyEvents(
2399 HierarchyEvent.ANCESTOR_MOVED, 0, enabledOnToolkit);
2400 }
2401 }
2402 }
2403 }
2404
2405 /**
2406 * Moves and resizes this component to conform to the new
2407 * bounding rectangle {@code r}. This component's new
2408 * position is specified by {@code r.x} and {@code r.y},
2409 * and its new size is specified by {@code r.width} and
2410 * {@code r.height}
2411 * <p>
2412 * This method changes layout-related information, and therefore,
2413 * invalidates the component hierarchy.
2414 *
2415 * @param r the new bounding rectangle for this component
2416 * @throws NullPointerException if {@code r} is {@code null}
2417 * @see #getBounds
2418 * @see #setLocation(int, int)
2419 * @see #setLocation(Point)
2420 * @see #setSize(int, int)
2421 * @see #setSize(Dimension)
2422 * @see #invalidate
2423 * @since 1.1
2424 */
2425 public void setBounds(Rectangle r) {
2426 setBounds(r.x, r.y, r.width, r.height);
2427 }
2428
2429
2430 /**
2431 * Returns the current x coordinate of the components origin.
2432 * This method is preferable to writing
2433 * {@code component.getBounds().x},
2434 * or {@code component.getLocation().x} because it doesn't
2435 * cause any heap allocations.
2436 *
2437 * @return the current x coordinate of the components origin
2438 * @since 1.2
2439 */
2440 public int getX() {
2441 return x;
2442 }
2443
2444
2445 /**
2446 * Returns the current y coordinate of the components origin.
2447 * This method is preferable to writing
2448 * {@code component.getBounds().y},
2449 * or {@code component.getLocation().y} because it
2450 * doesn't cause any heap allocations.
2451 *
2452 * @return the current y coordinate of the components origin
2453 * @since 1.2
2454 */
2455 public int getY() {
2456 return y;
2457 }
2458
2459
2460 /**
2461 * Returns the current width of this component.
2462 * This method is preferable to writing
2463 * {@code component.getBounds().width},
2464 * or {@code component.getSize().width} because it
2465 * doesn't cause any heap allocations.
2466 *
2467 * @return the current width of this component
2468 * @since 1.2
2469 */
2470 public int getWidth() {
2471 return width;
2472 }
2473
2474
2475 /**
2476 * Returns the current height of this component.
2477 * This method is preferable to writing
2478 * {@code component.getBounds().height},
2479 * or {@code component.getSize().height} because it
2480 * doesn't cause any heap allocations.
2481 *
2482 * @return the current height of this component
2483 * @since 1.2
2484 */
2485 public int getHeight() {
2486 return height;
2487 }
2488
2489 /**
2490 * Stores the bounds of this component into "return value" <b>rv</b> and
2491 * return <b>rv</b>. If rv is {@code null} a new
2492 * {@code Rectangle} is allocated.
2493 * This version of {@code getBounds} is useful if the caller
2494 * wants to avoid allocating a new {@code Rectangle} object
2495 * on the heap.
2496 *
2497 * @param rv the return value, modified to the components bounds
2498 * @return rv
2499 */
2500 public Rectangle getBounds(Rectangle rv) {
2501 if (rv == null) {
2502 return new Rectangle(getX(), getY(), getWidth(), getHeight());
2503 }
2504 else {
2505 rv.setBounds(getX(), getY(), getWidth(), getHeight());
2506 return rv;
2507 }
2508 }
2509
2510 /**
2511 * Stores the width/height of this component into "return value" <b>rv</b>
2512 * and return <b>rv</b>. If rv is {@code null} a new
2513 * {@code Dimension} object is allocated. This version of
2514 * {@code getSize} is useful if the caller wants to avoid
2515 * allocating a new {@code Dimension} object on the heap.
2516 *
2517 * @param rv the return value, modified to the components size
2518 * @return rv
2519 */
2520 public Dimension getSize(Dimension rv) {
2521 if (rv == null) {
2522 return new Dimension(getWidth(), getHeight());
2523 }
2524 else {
2525 rv.setSize(getWidth(), getHeight());
2526 return rv;
2527 }
2528 }
2529
2530 /**
2531 * Stores the x,y origin of this component into "return value" <b>rv</b>
2532 * and return <b>rv</b>. If rv is {@code null} a new
2533 * {@code Point} is allocated.
2534 * This version of {@code getLocation} is useful if the
2535 * caller wants to avoid allocating a new {@code Point}
2536 * object on the heap.
2537 *
2538 * @param rv the return value, modified to the components location
2539 * @return rv
2540 */
2541 public Point getLocation(Point rv) {
2542 if (rv == null) {
2543 return new Point(getX(), getY());
2544 }
2545 else {
2546 rv.setLocation(getX(), getY());
2547 return rv;
2548 }
2549 }
2550
2551 /**
2552 * Returns true if this component is completely opaque, returns
2553 * false by default.
2554 * <p>
2555 * An opaque component paints every pixel within its
2556 * rectangular region. A non-opaque component paints only some of
2557 * its pixels, allowing the pixels underneath it to "show through".
2558 * A component that does not fully paint its pixels therefore
2559 * provides a degree of transparency.
2560 * <p>
2561 * Subclasses that guarantee to always completely paint their
2562 * contents should override this method and return true.
2563 *
2564 * @return true if this component is completely opaque
2565 * @see #isLightweight
2566 * @since 1.2
2567 */
2568 public boolean isOpaque() {
2569 if (peer == null) {
2570 return false;
2571 }
2572 else {
2573 return !isLightweight();
2574 }
2575 }
2576
2577
2578 /**
2579 * A lightweight component doesn't have a native toolkit peer.
2580 * Subclasses of {@code Component} and {@code Container},
2581 * other than the ones defined in this package like {@code Button}
2582 * or {@code Scrollbar}, are lightweight.
2583 * All of the Swing components are lightweights.
2584 * <p>
2585 * This method will always return {@code false} if this component
2586 * is not displayable because it is impossible to determine the
2587 * weight of an undisplayable component.
2588 *
2589 * @return true if this component has a lightweight peer; false if
2590 * it has a native peer or no peer
2591 * @see #isDisplayable
2592 * @since 1.2
2593 */
2594 public boolean isLightweight() {
2595 return peer instanceof LightweightPeer;
2596 }
2597
2598
2599 /**
2600 * Sets the preferred size of this component to a constant
2601 * value. Subsequent calls to {@code getPreferredSize} will always
2602 * return this value. Setting the preferred size to {@code null}
2603 * restores the default behavior.
2604 *
2605 * @param preferredSize The new preferred size, or null
2606 * @see #getPreferredSize
2607 * @see #isPreferredSizeSet
2608 * @since 1.5
2609 */
2610 public void setPreferredSize(Dimension preferredSize) {
2611 Dimension old;
2612 // If the preferred size was set, use it as the old value, otherwise
2613 // use null to indicate we didn't previously have a set preferred
2614 // size.
2615 if (prefSizeSet) {
2616 old = this.prefSize;
2617 }
2618 else {
2619 old = null;
2620 }
2621 this.prefSize = preferredSize;
2622 prefSizeSet = (preferredSize != null);
2623 firePropertyChange("preferredSize", old, preferredSize);
2624 }
2625
2626
2627 /**
2628 * Returns true if the preferred size has been set to a
2629 * non-{@code null} value otherwise returns false.
2630 *
2631 * @return true if {@code setPreferredSize} has been invoked
2632 * with a non-null value.
2633 * @since 1.5
2634 */
2635 public boolean isPreferredSizeSet() {
2636 return prefSizeSet;
2637 }
2638
2639
2640 /**
2641 * Gets the preferred size of this component.
2642 * @return a dimension object indicating this component's preferred size
2643 * @see #getMinimumSize
2644 * @see LayoutManager
2645 */
2646 public Dimension getPreferredSize() {
2647 return preferredSize();
2648 }
2649
2650
2651 /**
2652 * Returns the component's preferred size.
2653 *
2654 * @return the component's preferred size
2655 * @deprecated As of JDK version 1.1,
2656 * replaced by {@code getPreferredSize()}.
2657 */
2658 @Deprecated
2659 public Dimension preferredSize() {
2660 /* Avoid grabbing the lock if a reasonable cached size value
2661 * is available.
2662 */
2663 Dimension dim = prefSize;
2664 if (dim == null || !(isPreferredSizeSet() || isValid())) {
2665 synchronized (getTreeLock()) {
2666 prefSize = (peer != null) ?
2667 peer.getPreferredSize() :
2668 getMinimumSize();
2669 dim = prefSize;
2670 }
2671 }
2672 return new Dimension(dim);
2673 }
2674
2675 /**
2676 * Sets the minimum size of this component to a constant
2677 * value. Subsequent calls to {@code getMinimumSize} will always
2678 * return this value. Setting the minimum size to {@code null}
2679 * restores the default behavior.
2680 *
2681 * @param minimumSize the new minimum size of this component
2682 * @see #getMinimumSize
2683 * @see #isMinimumSizeSet
2684 * @since 1.5
2685 */
2686 public void setMinimumSize(Dimension minimumSize) {
2687 Dimension old;
2688 // If the minimum size was set, use it as the old value, otherwise
2689 // use null to indicate we didn't previously have a set minimum
2690 // size.
2691 if (minSizeSet) {
2692 old = this.minSize;
2693 }
2694 else {
2695 old = null;
2696 }
2697 this.minSize = minimumSize;
2698 minSizeSet = (minimumSize != null);
2699 firePropertyChange("minimumSize", old, minimumSize);
2700 }
2701
2702 /**
2703 * Returns whether or not {@code setMinimumSize} has been
2704 * invoked with a non-null value.
2705 *
2706 * @return true if {@code setMinimumSize} has been invoked with a
2707 * non-null value.
2708 * @since 1.5
2709 */
2710 public boolean isMinimumSizeSet() {
2711 return minSizeSet;
2712 }
2713
2714 /**
2715 * Gets the minimum size of this component.
2716 * @return a dimension object indicating this component's minimum size
2717 * @see #getPreferredSize
2718 * @see LayoutManager
2719 */
2720 public Dimension getMinimumSize() {
2721 return minimumSize();
2722 }
2723
2724 /**
2725 * Returns the minimum size of this component.
2726 *
2727 * @return the minimum size of this component
2728 * @deprecated As of JDK version 1.1,
2729 * replaced by {@code getMinimumSize()}.
2730 */
2731 @Deprecated
2732 public Dimension minimumSize() {
2733 /* Avoid grabbing the lock if a reasonable cached size value
2734 * is available.
2735 */
2736 Dimension dim = minSize;
2737 if (dim == null || !(isMinimumSizeSet() || isValid())) {
2738 synchronized (getTreeLock()) {
2739 minSize = (peer != null) ?
2740 peer.getMinimumSize() :
2741 size();
2742 dim = minSize;
2743 }
2744 }
2745 return new Dimension(dim);
2746 }
2747
2748 /**
2749 * Sets the maximum size of this component to a constant
2750 * value. Subsequent calls to {@code getMaximumSize} will always
2751 * return this value. Setting the maximum size to {@code null}
2752 * restores the default behavior.
2753 *
2754 * @param maximumSize a {@code Dimension} containing the
2755 * desired maximum allowable size
2756 * @see #getMaximumSize
2757 * @see #isMaximumSizeSet
2758 * @since 1.5
2759 */
2760 public void setMaximumSize(Dimension maximumSize) {
2761 // If the maximum size was set, use it as the old value, otherwise
2762 // use null to indicate we didn't previously have a set maximum
2763 // size.
2764 Dimension old;
2765 if (maxSizeSet) {
2766 old = this.maxSize;
2767 }
2768 else {
2769 old = null;
2770 }
2771 this.maxSize = maximumSize;
2772 maxSizeSet = (maximumSize != null);
2773 firePropertyChange("maximumSize", old, maximumSize);
2774 }
2775
2776 /**
2777 * Returns true if the maximum size has been set to a non-{@code null}
2778 * value otherwise returns false.
2779 *
2780 * @return true if {@code maximumSize} is non-{@code null},
2781 * false otherwise
2782 * @since 1.5
2783 */
2784 public boolean isMaximumSizeSet() {
2785 return maxSizeSet;
2786 }
2787
2788 /**
2789 * Gets the maximum size of this component.
2790 * @return a dimension object indicating this component's maximum size
2791 * @see #getMinimumSize
2792 * @see #getPreferredSize
2793 * @see LayoutManager
2794 */
2795 public Dimension getMaximumSize() {
2796 if (isMaximumSizeSet()) {
2797 return new Dimension(maxSize);
2798 }
2799 return new Dimension(Short.MAX_VALUE, Short.MAX_VALUE);
2800 }
2801
2802 /**
2803 * Returns the alignment along the x axis. This specifies how
2804 * the component would like to be aligned relative to other
2805 * components. The value should be a number between 0 and 1
2806 * where 0 represents alignment along the origin, 1 is aligned
2807 * the furthest away from the origin, 0.5 is centered, etc.
2808 *
2809 * @return the horizontal alignment of this component
2810 */
2811 public float getAlignmentX() {
2812 return CENTER_ALIGNMENT;
2813 }
2814
2815 /**
2816 * Returns the alignment along the y axis. This specifies how
2817 * the component would like to be aligned relative to other
2818 * components. The value should be a number between 0 and 1
2819 * where 0 represents alignment along the origin, 1 is aligned
2820 * the furthest away from the origin, 0.5 is centered, etc.
2821 *
2822 * @return the vertical alignment of this component
2823 */
2824 public float getAlignmentY() {
2825 return CENTER_ALIGNMENT;
2826 }
2827
2828 /**
2829 * Returns the baseline. The baseline is measured from the top of
2830 * the component. This method is primarily meant for
2831 * {@code LayoutManager}s to align components along their
2832 * baseline. A return value less than 0 indicates this component
2833 * does not have a reasonable baseline and that
2834 * {@code LayoutManager}s should not align this component on
2835 * its baseline.
2836 * <p>
2837 * The default implementation returns -1. Subclasses that support
2838 * baseline should override appropriately. If a value >= 0 is
2839 * returned, then the component has a valid baseline for any
2840 * size >= the minimum size and {@code getBaselineResizeBehavior}
2841 * can be used to determine how the baseline changes with size.
2842 *
2843 * @param width the width to get the baseline for
2844 * @param height the height to get the baseline for
2845 * @return the baseline or < 0 indicating there is no reasonable
2846 * baseline
2847 * @throws IllegalArgumentException if width or height is < 0
2848 * @see #getBaselineResizeBehavior
2849 * @see java.awt.FontMetrics
2850 * @since 1.6
2851 */
2852 public int getBaseline(int width, int height) {
2853 if (width < 0 || height < 0) {
2854 throw new IllegalArgumentException(
2855 "Width and height must be >= 0");
2856 }
2857 return -1;
2858 }
2859
2860 /**
2861 * Returns an enum indicating how the baseline of the component
2862 * changes as the size changes. This method is primarily meant for
2863 * layout managers and GUI builders.
2864 * <p>
2865 * The default implementation returns
2866 * {@code BaselineResizeBehavior.OTHER}. Subclasses that have a
2867 * baseline should override appropriately. Subclasses should
2868 * never return {@code null}; if the baseline can not be
2869 * calculated return {@code BaselineResizeBehavior.OTHER}. Callers
2870 * should first ask for the baseline using
2871 * {@code getBaseline} and if a value >= 0 is returned use
2872 * this method. It is acceptable for this method to return a
2873 * value other than {@code BaselineResizeBehavior.OTHER} even if
2874 * {@code getBaseline} returns a value less than 0.
2875 *
2876 * @return an enum indicating how the baseline changes as the component
2877 * size changes
2878 * @see #getBaseline(int, int)
2879 * @since 1.6
2880 */
2881 public BaselineResizeBehavior getBaselineResizeBehavior() {
2882 return BaselineResizeBehavior.OTHER;
2883 }
2884
2885 /**
2886 * Prompts the layout manager to lay out this component. This is
2887 * usually called when the component (more specifically, container)
2888 * is validated.
2889 * @see #validate
2890 * @see LayoutManager
2891 */
2892 public void doLayout() {
2893 layout();
2894 }
2895
2896 /**
2897 * @deprecated As of JDK version 1.1,
2898 * replaced by {@code doLayout()}.
2899 */
2900 @Deprecated
2901 public void layout() {
2902 }
2903
2904 /**
2905 * Validates this component.
2906 * <p>
2907 * The meaning of the term <i>validating</i> is defined by the ancestors of
2908 * this class. See {@link Container#validate} for more details.
2909 *
2910 * @see #invalidate
2911 * @see #doLayout()
2912 * @see LayoutManager
2913 * @see Container#validate
2914 * @since 1.0
2915 */
2916 public void validate() {
2917 synchronized (getTreeLock()) {
2918 ComponentPeer peer = this.peer;
2919 boolean wasValid = isValid();
2920 if (!wasValid && peer != null) {
2921 Font newfont = getFont();
2922 Font oldfont = peerFont;
2923 if (newfont != oldfont && (oldfont == null
2924 || !oldfont.equals(newfont))) {
2925 peer.setFont(newfont);
2926 peerFont = newfont;
2927 }
2928 peer.layout();
2929 }
2930 valid = true;
2931 if (!wasValid) {
2932 mixOnValidating();
2933 }
2934 }
2935 }
2936
2937 /**
2938 * Invalidates this component and its ancestors.
2939 * <p>
2940 * By default, all the ancestors of the component up to the top-most
2941 * container of the hierarchy are marked invalid. If the {@code
2942 * java.awt.smartInvalidate} system property is set to {@code true},
2943 * invalidation stops on the nearest validate root of this component.
2944 * Marking a container <i>invalid</i> indicates that the container needs to
2945 * be laid out.
2946 * <p>
2947 * This method is called automatically when any layout-related information
2948 * changes (e.g. setting the bounds of the component, or adding the
2949 * component to a container).
2950 * <p>
2951 * This method might be called often, so it should work fast.
2952 *
2953 * @see #validate
2954 * @see #doLayout
2955 * @see LayoutManager
2956 * @see java.awt.Container#isValidateRoot
2957 * @since 1.0
2958 */
2959 public void invalidate() {
2960 synchronized (getTreeLock()) {
2961 /* Nullify cached layout and size information.
2962 * For efficiency, propagate invalidate() upwards only if
2963 * some other component hasn't already done so first.
2964 */
2965 valid = false;
2966 if (!isPreferredSizeSet()) {
2967 prefSize = null;
2968 }
2969 if (!isMinimumSizeSet()) {
2970 minSize = null;
2971 }
2972 if (!isMaximumSizeSet()) {
2973 maxSize = null;
2974 }
2975 invalidateParent();
2976 }
2977 }
2978
2979 /**
2980 * Invalidates the parent of this component if any.
2981 *
2982 * This method MUST BE invoked under the TreeLock.
2983 */
2984 void invalidateParent() {
2985 if (parent != null) {
2986 parent.invalidateIfValid();
2987 }
2988 }
2989
2990 /** Invalidates the component unless it is already invalid.
2991 */
2992 final void invalidateIfValid() {
2993 if (isValid()) {
2994 invalidate();
2995 }
2996 }
2997
2998 /**
2999 * Revalidates the component hierarchy up to the nearest validate root.
3000 * <p>
3001 * This method first invalidates the component hierarchy starting from this
3002 * component up to the nearest validate root. Afterwards, the component
3003 * hierarchy is validated starting from the nearest validate root.
3004 * <p>
3005 * This is a convenience method supposed to help application developers
3006 * avoid looking for validate roots manually. Basically, it's equivalent to
3007 * first calling the {@link #invalidate()} method on this component, and
3008 * then calling the {@link #validate()} method on the nearest validate
3009 * root.
3010 *
3011 * @see Container#isValidateRoot
3012 * @since 1.7
3013 */
3014 public void revalidate() {
3015 revalidateSynchronously();
3016 }
3017
3018 /**
3019 * Revalidates the component synchronously.
3020 */
3021 final void revalidateSynchronously() {
3022 synchronized (getTreeLock()) {
3023 invalidate();
3024
3025 Container root = getContainer();
3026 if (root == null) {
3027 // There's no parents. Just validate itself.
3028 validate();
3029 } else {
3030 while (!root.isValidateRoot()) {
3031 if (root.getContainer() == null) {
3032 // If there's no validate roots, we'll validate the
3033 // topmost container
3034 break;
3035 }
3036
3037 root = root.getContainer();
3038 }
3039
3040 root.validate();
3041 }
3042 }
3043 }
3044
3045 /**
3046 * Creates a graphics context for this component. This method will
3047 * return {@code null} if this component is currently not
3048 * displayable.
3049 * @return a graphics context for this component, or {@code null}
3050 * if it has none
3051 * @see #paint
3052 * @since 1.0
3053 */
3054 public Graphics getGraphics() {
3055 if (peer instanceof LightweightPeer) {
3056 // This is for a lightweight component, need to
3057 // translate coordinate spaces and clip relative
3058 // to the parent.
3059 if (parent == null) return null;
3060 Graphics g = parent.getGraphics();
3061 if (g == null) return null;
3062 if (g instanceof ConstrainableGraphics) {
3063 ((ConstrainableGraphics) g).constrain(x, y, width, height);
3064 } else {
3065 g.translate(x,y);
3066 g.setClip(0, 0, width, height);
3067 }
3068 g.setFont(getFont());
3069 return g;
3070 } else {
3071 ComponentPeer peer = this.peer;
3072 return (peer != null) ? peer.getGraphics() : null;
3073 }
3074 }
3075
3076 final Graphics getGraphics_NoClientCode() {
3077 ComponentPeer peer = this.peer;
3078 if (peer instanceof LightweightPeer) {
3079 // This is for a lightweight component, need to
3080 // translate coordinate spaces and clip relative
3081 // to the parent.
3082 Container parent = this.parent;
3083 if (parent == null) return null;
3084 Graphics g = parent.getGraphics_NoClientCode();
3085 if (g == null) return null;
3086 if (g instanceof ConstrainableGraphics) {
3087 ((ConstrainableGraphics) g).constrain(x, y, width, height);
3088 } else {
3089 g.translate(x,y);
3090 g.setClip(0, 0, width, height);
3091 }
3092 g.setFont(getFont_NoClientCode());
3093 return g;
3094 } else {
3095 return (peer != null) ? peer.getGraphics() : null;
3096 }
3097 }
3098
3099 /**
3100 * Gets the font metrics for the specified font.
3101 * Warning: Since Font metrics are affected by the
3102 * {@link java.awt.font.FontRenderContext FontRenderContext} and
3103 * this method does not provide one, it can return only metrics for
3104 * the default render context which may not match that used when
3105 * rendering on the Component if {@link Graphics2D} functionality is being
3106 * used. Instead metrics can be obtained at rendering time by calling
3107 * {@link Graphics#getFontMetrics()} or text measurement APIs on the
3108 * {@link Font Font} class.
3109 * @param font the font for which font metrics is to be
3110 * obtained
3111 * @return the font metrics for {@code font}
3112 * @see #getFont
3113 * @see java.awt.peer.ComponentPeer#getFontMetrics(Font)
3114 * @see Toolkit#getFontMetrics(Font)
3115 * @since 1.0
3116 */
3117 public FontMetrics getFontMetrics(Font font) {
3118 // This is an unsupported hack, but left in for a customer.
3119 // Do not remove.
3120 FontManager fm = FontManagerFactory.getInstance();
3121 if (fm instanceof SunFontManager
3122 && ((SunFontManager) fm).usePlatformFontMetrics()) {
3123
3124 if (peer != null &&
3125 !(peer instanceof LightweightPeer)) {
3126 return peer.getFontMetrics(font);
3127 }
3128 }
3129 return sun.font.FontDesignMetrics.getMetrics(font);
3130 }
3131
3132 /**
3133 * Sets the cursor image to the specified cursor. This cursor
3134 * image is displayed when the {@code contains} method for
3135 * this component returns true for the current cursor location, and
3136 * this Component is visible, displayable, and enabled. Setting the
3137 * cursor of a {@code Container} causes that cursor to be displayed
3138 * within all of the container's subcomponents, except for those
3139 * that have a non-{@code null} cursor.
3140 * <p>
3141 * The method may have no visual effect if the Java platform
3142 * implementation and/or the native system do not support
3143 * changing the mouse cursor shape.
3144 * @param cursor One of the constants defined
3145 * by the {@code Cursor} class;
3146 * if this parameter is {@code null}
3147 * then this component will inherit
3148 * the cursor of its parent
3149 * @see #isEnabled
3150 * @see #isShowing
3151 * @see #getCursor
3152 * @see #contains
3153 * @see Toolkit#createCustomCursor
3154 * @see Cursor
3155 * @since 1.1
3156 */
3157 public void setCursor(Cursor cursor) {
3158 this.cursor = cursor;
3159 updateCursorImmediately();
3160 }
3161
3162 /**
3163 * Updates the cursor. May not be invoked from the native
3164 * message pump.
3165 */
3166 final void updateCursorImmediately() {
3167 if (peer instanceof LightweightPeer) {
3168 Container nativeContainer = getNativeContainer();
3169
3170 if (nativeContainer == null) return;
3171
3172 ComponentPeer cPeer = nativeContainer.peer;
3173
3174 if (cPeer != null) {
3175 cPeer.updateCursorImmediately();
3176 }
3177 } else if (peer != null) {
3178 peer.updateCursorImmediately();
3179 }
3180 }
3181
3182 /**
3183 * Gets the cursor set in the component. If the component does
3184 * not have a cursor set, the cursor of its parent is returned.
3185 * If no cursor is set in the entire hierarchy,
3186 * {@code Cursor.DEFAULT_CURSOR} is returned.
3187 *
3188 * @return the cursor for this component
3189 * @see #setCursor
3190 * @since 1.1
3191 */
3192 public Cursor getCursor() {
3193 return getCursor_NoClientCode();
3194 }
3195
3196 final Cursor getCursor_NoClientCode() {
3197 Cursor cursor = this.cursor;
3198 if (cursor != null) {
3199 return cursor;
3200 }
3201 Container parent = this.parent;
3202 if (parent != null) {
3203 return parent.getCursor_NoClientCode();
3204 } else {
3205 return Cursor.getPredefinedCursor(Cursor.DEFAULT_CURSOR);
3206 }
3207 }
3208
3209 /**
3210 * Returns whether the cursor has been explicitly set for this Component.
3211 * If this method returns {@code false}, this Component is inheriting
3212 * its cursor from an ancestor.
3213 *
3214 * @return {@code true} if the cursor has been explicitly set for this
3215 * Component; {@code false} otherwise.
3216 * @since 1.4
3217 */
3218 public boolean isCursorSet() {
3219 return (cursor != null);
3220 }
3221
3222 /**
3223 * Paints this component.
3224 * <p>
3225 * This method is called when the contents of the component should
3226 * be painted; such as when the component is first being shown or
3227 * is damaged and in need of repair. The clip rectangle in the
3228 * {@code Graphics} parameter is set to the area
3229 * which needs to be painted.
3230 * Subclasses of {@code Component} that override this
3231 * method need not call {@code super.paint(g)}.
3232 * <p>
3233 * For performance reasons, {@code Component}s with zero width
3234 * or height aren't considered to need painting when they are first shown,
3235 * and also aren't considered to need repair.
3236 * <p>
3237 * <b>Note</b>: For more information on the paint mechanisms utilitized
3238 * by AWT and Swing, including information on how to write the most
3239 * efficient painting code, see
3240 * <a href="http://www.oracle.com/technetwork/java/painting-140037.html">Painting in AWT and Swing</a>.
3241 *
3242 * @param g the graphics context to use for painting
3243 * @see #update
3244 * @since 1.0
3245 */
3246 public void paint(Graphics g) {
3247 }
3248
3249 /**
3250 * Updates this component.
3251 * <p>
3252 * If this component is not a lightweight component, the
3253 * AWT calls the {@code update} method in response to
3254 * a call to {@code repaint}. You can assume that
3255 * the background is not cleared.
3256 * <p>
3257 * The {@code update} method of {@code Component}
3258 * calls this component's {@code paint} method to redraw
3259 * this component. This method is commonly overridden by subclasses
3260 * which need to do additional work in response to a call to
3261 * {@code repaint}.
3262 * Subclasses of Component that override this method should either
3263 * call {@code super.update(g)}, or call {@code paint(g)}
3264 * directly from their {@code update} method.
3265 * <p>
3266 * The origin of the graphics context, its
3267 * ({@code 0}, {@code 0}) coordinate point, is the
3268 * top-left corner of this component. The clipping region of the
3269 * graphics context is the bounding rectangle of this component.
3270 *
3271 * <p>
3272 * <b>Note</b>: For more information on the paint mechanisms utilitized
3273 * by AWT and Swing, including information on how to write the most
3274 * efficient painting code, see
3275 * <a href="http://www.oracle.com/technetwork/java/painting-140037.html">Painting in AWT and Swing</a>.
3276 *
3277 * @param g the specified context to use for updating
3278 * @see #paint
3279 * @see #repaint()
3280 * @since 1.0
3281 */
3282 public void update(Graphics g) {
3283 paint(g);
3284 }
3285
3286 /**
3287 * Paints this component and all of its subcomponents.
3288 * <p>
3289 * The origin of the graphics context, its
3290 * ({@code 0}, {@code 0}) coordinate point, is the
3291 * top-left corner of this component. The clipping region of the
3292 * graphics context is the bounding rectangle of this component.
3293 *
3294 * @param g the graphics context to use for painting
3295 * @see #paint
3296 * @since 1.0
3297 */
3298 public void paintAll(Graphics g) {
3299 if (isShowing()) {
3300 GraphicsCallback.PeerPaintCallback.getInstance().
3301 runOneComponent(this, new Rectangle(0, 0, width, height),
3302 g, g.getClip(),
3303 GraphicsCallback.LIGHTWEIGHTS |
3304 GraphicsCallback.HEAVYWEIGHTS);
3305 }
3306 }
3307
3308 /**
3309 * Simulates the peer callbacks into java.awt for painting of
3310 * lightweight Components.
3311 * @param g the graphics context to use for painting
3312 * @see #paintAll
3313 */
3314 void lightweightPaint(Graphics g) {
3315 paint(g);
3316 }
3317
3318 /**
3319 * Paints all the heavyweight subcomponents.
3320 */
3321 void paintHeavyweightComponents(Graphics g) {
3322 }
3323
3324 /**
3325 * Repaints this component.
3326 * <p>
3327 * If this component is a lightweight component, this method
3328 * causes a call to this component's {@code paint}
3329 * method as soon as possible. Otherwise, this method causes
3330 * a call to this component's {@code update} method as soon
3331 * as possible.
3332 * <p>
3333 * <b>Note</b>: For more information on the paint mechanisms utilitized
3334 * by AWT and Swing, including information on how to write the most
3335 * efficient painting code, see
3336 * <a href="http://www.oracle.com/technetwork/java/painting-140037.html">Painting in AWT and Swing</a>.
3337
3338 *
3339 * @see #update(Graphics)
3340 * @since 1.0
3341 */
3342 public void repaint() {
3343 repaint(0, 0, 0, width, height);
3344 }
3345
3346 /**
3347 * Repaints the component. If this component is a lightweight
3348 * component, this results in a call to {@code paint}
3349 * within {@code tm} milliseconds.
3350 * <p>
3351 * <b>Note</b>: For more information on the paint mechanisms utilitized
3352 * by AWT and Swing, including information on how to write the most
3353 * efficient painting code, see
3354 * <a href="http://www.oracle.com/technetwork/java/painting-140037.html">Painting in AWT and Swing</a>.
3355 *
3356 * @param tm maximum time in milliseconds before update
3357 * @see #paint
3358 * @see #update(Graphics)
3359 * @since 1.0
3360 */
3361 public void repaint(long tm) {
3362 repaint(tm, 0, 0, width, height);
3363 }
3364
3365 /**
3366 * Repaints the specified rectangle of this component.
3367 * <p>
3368 * If this component is a lightweight component, this method
3369 * causes a call to this component's {@code paint} method
3370 * as soon as possible. Otherwise, this method causes a call to
3371 * this component's {@code update} method as soon as possible.
3372 * <p>
3373 * <b>Note</b>: For more information on the paint mechanisms utilitized
3374 * by AWT and Swing, including information on how to write the most
3375 * efficient painting code, see
3376 * <a href="http://www.oracle.com/technetwork/java/painting-140037.html">Painting in AWT and Swing</a>.
3377 *
3378 * @param x the <i>x</i> coordinate
3379 * @param y the <i>y</i> coordinate
3380 * @param width the width
3381 * @param height the height
3382 * @see #update(Graphics)
3383 * @since 1.0
3384 */
3385 public void repaint(int x, int y, int width, int height) {
3386 repaint(0, x, y, width, height);
3387 }
3388
3389 /**
3390 * Repaints the specified rectangle of this component within
3391 * {@code tm} milliseconds.
3392 * <p>
3393 * If this component is a lightweight component, this method causes
3394 * a call to this component's {@code paint} method.
3395 * Otherwise, this method causes a call to this component's
3396 * {@code update} method.
3397 * <p>
3398 * <b>Note</b>: For more information on the paint mechanisms utilitized
3399 * by AWT and Swing, including information on how to write the most
3400 * efficient painting code, see
3401 * <a href="http://www.oracle.com/technetwork/java/painting-140037.html">Painting in AWT and Swing</a>.
3402 *
3403 * @param tm maximum time in milliseconds before update
3404 * @param x the <i>x</i> coordinate
3405 * @param y the <i>y</i> coordinate
3406 * @param width the width
3407 * @param height the height
3408 * @see #update(Graphics)
3409 * @since 1.0
3410 */
3411 public void repaint(long tm, int x, int y, int width, int height) {
3412 if (this.peer instanceof LightweightPeer) {
3413 // Needs to be translated to parent coordinates since
3414 // a parent native container provides the actual repaint
3415 // services. Additionally, the request is restricted to
3416 // the bounds of the component.
3417 if (parent != null) {
3418 if (x < 0) {
3419 width += x;
3420 x = 0;
3421 }
3422 if (y < 0) {
3423 height += y;
3424 y = 0;
3425 }
3426
3427 int pwidth = (width > this.width) ? this.width : width;
3428 int pheight = (height > this.height) ? this.height : height;
3429
3430 if (pwidth <= 0 || pheight <= 0) {
3431 return;
3432 }
3433
3434 int px = this.x + x;
3435 int py = this.y + y;
3436 parent.repaint(tm, px, py, pwidth, pheight);
3437 }
3438 } else {
3439 if (isVisible() && (this.peer != null) &&
3440 (width > 0) && (height > 0)) {
3441 PaintEvent e = new PaintEvent(this, PaintEvent.UPDATE,
3442 new Rectangle(x, y, width, height));
3443 SunToolkit.postEvent(SunToolkit.targetToAppContext(this), e);
3444 }
3445 }
3446 }
3447
3448 /**
3449 * Prints this component. Applications should override this method
3450 * for components that must do special processing before being
3451 * printed or should be printed differently than they are painted.
3452 * <p>
3453 * The default implementation of this method calls the
3454 * {@code paint} method.
3455 * <p>
3456 * The origin of the graphics context, its
3457 * ({@code 0}, {@code 0}) coordinate point, is the
3458 * top-left corner of this component. The clipping region of the
3459 * graphics context is the bounding rectangle of this component.
3460 * @param g the graphics context to use for printing
3461 * @see #paint(Graphics)
3462 * @since 1.0
3463 */
3464 public void print(Graphics g) {
3465 paint(g);
3466 }
3467
3468 /**
3469 * Prints this component and all of its subcomponents.
3470 * <p>
3471 * The origin of the graphics context, its
3472 * ({@code 0}, {@code 0}) coordinate point, is the
3473 * top-left corner of this component. The clipping region of the
3474 * graphics context is the bounding rectangle of this component.
3475 * @param g the graphics context to use for printing
3476 * @see #print(Graphics)
3477 * @since 1.0
3478 */
3479 public void printAll(Graphics g) {
3480 if (isShowing()) {
3481 GraphicsCallback.PeerPrintCallback.getInstance().
3482 runOneComponent(this, new Rectangle(0, 0, width, height),
3483 g, g.getClip(),
3484 GraphicsCallback.LIGHTWEIGHTS |
3485 GraphicsCallback.HEAVYWEIGHTS);
3486 }
3487 }
3488
3489 /**
3490 * Simulates the peer callbacks into java.awt for printing of
3491 * lightweight Components.
3492 * @param g the graphics context to use for printing
3493 * @see #printAll
3494 */
3495 void lightweightPrint(Graphics g) {
3496 print(g);
3497 }
3498
3499 /**
3500 * Prints all the heavyweight subcomponents.
3501 */
3502 void printHeavyweightComponents(Graphics g) {
3503 }
3504
3505 private Insets getInsets_NoClientCode() {
3506 ComponentPeer peer = this.peer;
3507 if (peer instanceof ContainerPeer) {
3508 return (Insets)((ContainerPeer)peer).getInsets().clone();
3509 }
3510 return new Insets(0, 0, 0, 0);
3511 }
3512
3513 /**
3514 * Repaints the component when the image has changed.
3515 * This {@code imageUpdate} method of an {@code ImageObserver}
3516 * is called when more information about an
3517 * image which had been previously requested using an asynchronous
3518 * routine such as the {@code drawImage} method of
3519 * {@code Graphics} becomes available.
3520 * See the definition of {@code imageUpdate} for
3521 * more information on this method and its arguments.
3522 * <p>
3523 * The {@code imageUpdate} method of {@code Component}
3524 * incrementally draws an image on the component as more of the bits
3525 * of the image are available.
3526 * <p>
3527 * If the system property {@code awt.image.incrementaldraw}
3528 * is missing or has the value {@code true}, the image is
3529 * incrementally drawn. If the system property has any other value,
3530 * then the image is not drawn until it has been completely loaded.
3531 * <p>
3532 * Also, if incremental drawing is in effect, the value of the
3533 * system property {@code awt.image.redrawrate} is interpreted
3534 * as an integer to give the maximum redraw rate, in milliseconds. If
3535 * the system property is missing or cannot be interpreted as an
3536 * integer, the redraw rate is once every 100ms.
3537 * <p>
3538 * The interpretation of the {@code x}, {@code y},
3539 * {@code width}, and {@code height} arguments depends on
3540 * the value of the {@code infoflags} argument.
3541 *
3542 * @param img the image being observed
3543 * @param infoflags see {@code imageUpdate} for more information
3544 * @param x the <i>x</i> coordinate
3545 * @param y the <i>y</i> coordinate
3546 * @param w the width
3547 * @param h the height
3548 * @return {@code false} if the infoflags indicate that the
3549 * image is completely loaded; {@code true} otherwise.
3550 *
3551 * @see java.awt.image.ImageObserver
3552 * @see Graphics#drawImage(Image, int, int, Color, java.awt.image.ImageObserver)
3553 * @see Graphics#drawImage(Image, int, int, java.awt.image.ImageObserver)
3554 * @see Graphics#drawImage(Image, int, int, int, int, Color, java.awt.image.ImageObserver)
3555 * @see Graphics#drawImage(Image, int, int, int, int, java.awt.image.ImageObserver)
3556 * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
3557 * @since 1.0
3558 */
3559 public boolean imageUpdate(Image img, int infoflags,
3560 int x, int y, int w, int h) {
3561 int rate = -1;
3562 if ((infoflags & (FRAMEBITS|ALLBITS)) != 0) {
3563 rate = 0;
3564 } else if ((infoflags & SOMEBITS) != 0) {
3565 if (isInc) {
3566 rate = incRate;
3567 if (rate < 0) {
3568 rate = 0;
3569 }
3570 }
3571 }
3572 if (rate >= 0) {
3573 repaint(rate, 0, 0, width, height);
3574 }
3575 return (infoflags & (ALLBITS|ABORT)) == 0;
3576 }
3577
3578 /**
3579 * Creates an image from the specified image producer.
3580 * @param producer the image producer
3581 * @return the image produced
3582 * @since 1.0
3583 */
3584 public Image createImage(ImageProducer producer) {
3585 ComponentPeer peer = this.peer;
3586 if ((peer != null) && ! (peer instanceof LightweightPeer)) {
3587 return peer.createImage(producer);
3588 }
3589 return getToolkit().createImage(producer);
3590 }
3591
3592 /**
3593 * Creates an off-screen drawable image to be used for double buffering.
3594 *
3595 * @param width the specified width
3596 * @param height the specified height
3597 * @return an off-screen drawable image, which can be used for double
3598 * buffering. The {@code null} value if the component is not
3599 * displayable or {@code GraphicsEnvironment.isHeadless()} returns
3600 * {@code true}.
3601 * @see #isDisplayable
3602 * @see GraphicsEnvironment#isHeadless
3603 * @since 1.0
3604 */
3605 public Image createImage(int width, int height) {
3606 ComponentPeer peer = this.peer;
3607 if (peer instanceof LightweightPeer) {
3608 if (parent != null) { return parent.createImage(width, height); }
3609 else { return null;}
3610 } else {
3611 return (peer != null) ? peer.createImage(width, height) : null;
3612 }
3613 }
3614
3615 /**
3616 * Creates a volatile off-screen drawable image to be used for double
3617 * buffering.
3618 *
3619 * @param width the specified width
3620 * @param height the specified height
3621 * @return an off-screen drawable image, which can be used for double
3622 * buffering. The {@code null} value if the component is not
3623 * displayable or {@code GraphicsEnvironment.isHeadless()} returns
3624 * {@code true}.
3625 * @see java.awt.image.VolatileImage
3626 * @see #isDisplayable
3627 * @see GraphicsEnvironment#isHeadless
3628 * @since 1.4
3629 */
3630 public VolatileImage createVolatileImage(int width, int height) {
3631 ComponentPeer peer = this.peer;
3632 if (peer instanceof LightweightPeer) {
3633 if (parent != null) {
3634 return parent.createVolatileImage(width, height);
3635 }
3636 else { return null;}
3637 } else {
3638 return (peer != null) ?
3639 peer.createVolatileImage(width, height) : null;
3640 }
3641 }
3642
3643 /**
3644 * Creates a volatile off-screen drawable image, with the given
3645 * capabilities. The contents of this image may be lost at any time due to
3646 * operating system issues, so the image must be managed via the
3647 * {@code VolatileImage} interface.
3648 *
3649 * @param width the specified width
3650 * @param height the specified height
3651 * @param caps the image capabilities
3652 * @return a VolatileImage object, which can be used to manage surface
3653 * contents loss and capabilities. The {@code null} value if the
3654 * component is not displayable or
3655 * {@code GraphicsEnvironment.isHeadless()} returns {@code true}.
3656 * @throws AWTException if an image with the specified capabilities cannot
3657 * be created
3658 * @see java.awt.image.VolatileImage
3659 * @since 1.4
3660 */
3661 public VolatileImage createVolatileImage(int width, int height,
3662 ImageCapabilities caps)
3663 throws AWTException {
3664 // REMIND : check caps
3665 return createVolatileImage(width, height);
3666 }
3667
3668 /**
3669 * Prepares an image for rendering on this component. The image
3670 * data is downloaded asynchronously in another thread and the
3671 * appropriate screen representation of the image is generated.
3672 * @param image the {@code Image} for which to
3673 * prepare a screen representation
3674 * @param observer the {@code ImageObserver} object
3675 * to be notified as the image is being prepared
3676 * @return {@code true} if the image has already been fully
3677 * prepared; {@code false} otherwise
3678 * @since 1.0
3679 */
3680 public boolean prepareImage(Image image, ImageObserver observer) {
3681 return prepareImage(image, -1, -1, observer);
3682 }
3683
3684 /**
3685 * Prepares an image for rendering on this component at the
3686 * specified width and height.
3687 * <p>
3688 * The image data is downloaded asynchronously in another thread,
3689 * and an appropriately scaled screen representation of the image is
3690 * generated.
3691 * @param image the instance of {@code Image}
3692 * for which to prepare a screen representation
3693 * @param width the width of the desired screen representation
3694 * @param height the height of the desired screen representation
3695 * @param observer the {@code ImageObserver} object
3696 * to be notified as the image is being prepared
3697 * @return {@code true} if the image has already been fully
3698 * prepared; {@code false} otherwise
3699 * @see java.awt.image.ImageObserver
3700 * @since 1.0
3701 */
3702 public boolean prepareImage(Image image, int width, int height,
3703 ImageObserver observer) {
3704 ComponentPeer peer = this.peer;
3705 if (peer instanceof LightweightPeer) {
3706 return (parent != null)
3707 ? parent.prepareImage(image, width, height, observer)
3708 : getToolkit().prepareImage(image, width, height, observer);
3709 } else {
3710 return (peer != null)
3711 ? peer.prepareImage(image, width, height, observer)
3712 : getToolkit().prepareImage(image, width, height, observer);
3713 }
3714 }
3715
3716 /**
3717 * Returns the status of the construction of a screen representation
3718 * of the specified image.
3719 * <p>
3720 * This method does not cause the image to begin loading. An
3721 * application must use the {@code prepareImage} method
3722 * to force the loading of an image.
3723 * <p>
3724 * Information on the flags returned by this method can be found
3725 * with the discussion of the {@code ImageObserver} interface.
3726 * @param image the {@code Image} object whose status
3727 * is being checked
3728 * @param observer the {@code ImageObserver}
3729 * object to be notified as the image is being prepared
3730 * @return the bitwise inclusive <b>OR</b> of
3731 * {@code ImageObserver} flags indicating what
3732 * information about the image is currently available
3733 * @see #prepareImage(Image, int, int, java.awt.image.ImageObserver)
3734 * @see Toolkit#checkImage(Image, int, int, java.awt.image.ImageObserver)
3735 * @see java.awt.image.ImageObserver
3736 * @since 1.0
3737 */
3738 public int checkImage(Image image, ImageObserver observer) {
3739 return checkImage(image, -1, -1, observer);
3740 }
3741
3742 /**
3743 * Returns the status of the construction of a screen representation
3744 * of the specified image.
3745 * <p>
3746 * This method does not cause the image to begin loading. An
3747 * application must use the {@code prepareImage} method
3748 * to force the loading of an image.
3749 * <p>
3750 * The {@code checkImage} method of {@code Component}
3751 * calls its peer's {@code checkImage} method to calculate
3752 * the flags. If this component does not yet have a peer, the
3753 * component's toolkit's {@code checkImage} method is called
3754 * instead.
3755 * <p>
3756 * Information on the flags returned by this method can be found
3757 * with the discussion of the {@code ImageObserver} interface.
3758 * @param image the {@code Image} object whose status
3759 * is being checked
3760 * @param width the width of the scaled version
3761 * whose status is to be checked
3762 * @param height the height of the scaled version
3763 * whose status is to be checked
3764 * @param observer the {@code ImageObserver} object
3765 * to be notified as the image is being prepared
3766 * @return the bitwise inclusive <b>OR</b> of
3767 * {@code ImageObserver} flags indicating what
3768 * information about the image is currently available
3769 * @see #prepareImage(Image, int, int, java.awt.image.ImageObserver)
3770 * @see Toolkit#checkImage(Image, int, int, java.awt.image.ImageObserver)
3771 * @see java.awt.image.ImageObserver
3772 * @since 1.0
3773 */
3774 public int checkImage(Image image, int width, int height,
3775 ImageObserver observer) {
3776 ComponentPeer peer = this.peer;
3777 if (peer instanceof LightweightPeer) {
3778 return (parent != null)
3779 ? parent.checkImage(image, width, height, observer)
3780 : getToolkit().checkImage(image, width, height, observer);
3781 } else {
3782 return (peer != null)
3783 ? peer.checkImage(image, width, height, observer)
3784 : getToolkit().checkImage(image, width, height, observer);
3785 }
3786 }
3787
3788 /**
3789 * Creates a new strategy for multi-buffering on this component.
3790 * Multi-buffering is useful for rendering performance. This method
3791 * attempts to create the best strategy available with the number of
3792 * buffers supplied. It will always create a {@code BufferStrategy}
3793 * with that number of buffers.
3794 * A page-flipping strategy is attempted first, then a blitting strategy
3795 * using accelerated buffers. Finally, an unaccelerated blitting
3796 * strategy is used.
3797 * <p>
3798 * Each time this method is called,
3799 * the existing buffer strategy for this component is discarded.
3800 * @param numBuffers number of buffers to create, including the front buffer
3801 * @exception IllegalArgumentException if numBuffers is less than 1.
3802 * @exception IllegalStateException if the component is not displayable
3803 * @see #isDisplayable
3804 * @see Window#getBufferStrategy()
3805 * @see Canvas#getBufferStrategy()
3806 * @since 1.4
3807 */
3808 void createBufferStrategy(int numBuffers) {
3809 BufferCapabilities bufferCaps;
3810 if (numBuffers > 1) {
3811 // Try to create a page-flipping strategy
3812 bufferCaps = new BufferCapabilities(new ImageCapabilities(true),
3813 new ImageCapabilities(true),
3814 BufferCapabilities.FlipContents.UNDEFINED);
3815 try {
3816 createBufferStrategy(numBuffers, bufferCaps);
3817 return; // Success
3818 } catch (AWTException e) {
3819 // Failed
3820 }
3821 }
3822 // Try a blitting (but still accelerated) strategy
3823 bufferCaps = new BufferCapabilities(new ImageCapabilities(true),
3824 new ImageCapabilities(true),
3825 null);
3826 try {
3827 createBufferStrategy(numBuffers, bufferCaps);
3828 return; // Success
3829 } catch (AWTException e) {
3830 // Failed
3831 }
3832 // Try an unaccelerated blitting strategy
3833 bufferCaps = new BufferCapabilities(new ImageCapabilities(false),
3834 new ImageCapabilities(false),
3835 null);
3836 try {
3837 createBufferStrategy(numBuffers, bufferCaps);
3838 return; // Success
3839 } catch (AWTException e) {
3840 // Code should never reach here (an unaccelerated blitting
3841 // strategy should always work)
3842 throw new InternalError("Could not create a buffer strategy", e);
3843 }
3844 }
3845
3846 /**
3847 * Creates a new strategy for multi-buffering on this component with the
3848 * required buffer capabilities. This is useful, for example, if only
3849 * accelerated memory or page flipping is desired (as specified by the
3850 * buffer capabilities).
3851 * <p>
3852 * Each time this method
3853 * is called, {@code dispose} will be invoked on the existing
3854 * {@code BufferStrategy}.
3855 * @param numBuffers number of buffers to create
3856 * @param caps the required capabilities for creating the buffer strategy;
3857 * cannot be {@code null}
3858 * @exception AWTException if the capabilities supplied could not be
3859 * supported or met; this may happen, for example, if there is not enough
3860 * accelerated memory currently available, or if page flipping is specified
3861 * but not possible.
3862 * @exception IllegalArgumentException if numBuffers is less than 1, or if
3863 * caps is {@code null}
3864 * @see Window#getBufferStrategy()
3865 * @see Canvas#getBufferStrategy()
3866 * @since 1.4
3867 */
3868 void createBufferStrategy(int numBuffers,
3869 BufferCapabilities caps) throws AWTException {
3870 // Check arguments
3871 if (numBuffers < 1) {
3872 throw new IllegalArgumentException(
3873 "Number of buffers must be at least 1");
3874 }
3875 if (caps == null) {
3876 throw new IllegalArgumentException("No capabilities specified");
3877 }
3878 // Destroy old buffers
3879 if (bufferStrategy != null) {
3880 bufferStrategy.dispose();
3881 }
3882 if (numBuffers == 1) {
3883 bufferStrategy = new SingleBufferStrategy(caps);
3884 } else {
3885 SunGraphicsEnvironment sge = (SunGraphicsEnvironment)
3886 GraphicsEnvironment.getLocalGraphicsEnvironment();
3887 if (!caps.isPageFlipping() && sge.isFlipStrategyPreferred(peer)) {
3888 caps = new ProxyCapabilities(caps);
3889 }
3890 // assert numBuffers > 1;
3891 if (caps.isPageFlipping()) {
3892 bufferStrategy = new FlipSubRegionBufferStrategy(numBuffers, caps);
3893 } else {
3894 bufferStrategy = new BltSubRegionBufferStrategy(numBuffers, caps);
3895 }
3896 }
3897 }
3898
3899 /**
3900 * This is a proxy capabilities class used when a FlipBufferStrategy
3901 * is created instead of the requested Blit strategy.
3902 *
3903 * @see sun.java2d.SunGraphicsEnvironment#isFlipStrategyPreferred(ComponentPeer)
3904 */
3905 private class ProxyCapabilities extends ExtendedBufferCapabilities {
3906 private BufferCapabilities orig;
3907 private ProxyCapabilities(BufferCapabilities orig) {
3908 super(orig.getFrontBufferCapabilities(),
3909 orig.getBackBufferCapabilities(),
3910 orig.getFlipContents() ==
3911 BufferCapabilities.FlipContents.BACKGROUND ?
3912 BufferCapabilities.FlipContents.BACKGROUND :
3913 BufferCapabilities.FlipContents.COPIED);
3914 this.orig = orig;
3915 }
3916 }
3917
3918 /**
3919 * @return the buffer strategy used by this component
3920 * @see Window#createBufferStrategy
3921 * @see Canvas#createBufferStrategy
3922 * @since 1.4
3923 */
3924 BufferStrategy getBufferStrategy() {
3925 return bufferStrategy;
3926 }
3927
3928 /**
3929 * @return the back buffer currently used by this component's
3930 * BufferStrategy. If there is no BufferStrategy or no
3931 * back buffer, this method returns null.
3932 */
3933 Image getBackBuffer() {
3934 if (bufferStrategy != null) {
3935 if (bufferStrategy instanceof BltBufferStrategy) {
3936 BltBufferStrategy bltBS = (BltBufferStrategy)bufferStrategy;
3937 return bltBS.getBackBuffer();
3938 } else if (bufferStrategy instanceof FlipBufferStrategy) {
3939 FlipBufferStrategy flipBS = (FlipBufferStrategy)bufferStrategy;
3940 return flipBS.getBackBuffer();
3941 }
3942 }
3943 return null;
3944 }
3945
3946 /**
3947 * Inner class for flipping buffers on a component. That component must
3948 * be a {@code Canvas} or {@code Window} or {@code Applet}.
3949 * @see Canvas
3950 * @see Window
3951 * @see Applet
3952 * @see java.awt.image.BufferStrategy
3953 * @author Michael Martak
3954 * @since 1.4
3955 */
3956 protected class FlipBufferStrategy extends BufferStrategy {
3957 /**
3958 * The number of buffers
3959 */
3960 protected int numBuffers; // = 0
3961 /**
3962 * The buffering capabilities
3963 */
3964 protected BufferCapabilities caps; // = null
3965 /**
3966 * The drawing buffer
3967 */
3968 protected Image drawBuffer; // = null
3969 /**
3970 * The drawing buffer as a volatile image
3971 */
3972 protected VolatileImage drawVBuffer; // = null
3973 /**
3974 * Whether or not the drawing buffer has been recently restored from
3975 * a lost state.
3976 */
3977 protected boolean validatedContents; // = false
3978
3979 /**
3980 * Size of the back buffers. (Note: these fields were added in 6.0
3981 * but kept package-private to avoid exposing them in the spec.
3982 * None of these fields/methods really should have been marked
3983 * protected when they were introduced in 1.4, but now we just have
3984 * to live with that decision.)
3985 */
3986
3987 /**
3988 * The width of the back buffers
3989 */
3990 int width;
3991
3992 /**
3993 * The height of the back buffers
3994 */
3995 int height;
3996
3997 /**
3998 * Creates a new flipping buffer strategy for this component.
3999 * The component must be a {@code Canvas} or {@code Window} or
4000 * {@code Applet}.
4001 * @see Canvas
4002 * @see Window
4003 * @see Applet
4004 * @param numBuffers the number of buffers
4005 * @param caps the capabilities of the buffers
4006 * @exception AWTException if the capabilities supplied could not be
4007 * supported or met
4008 * @exception ClassCastException if the component is not a canvas or
4009 * window.
4010 * @exception IllegalStateException if the component has no peer
4011 * @exception IllegalArgumentException if {@code numBuffers} is less than two,
4012 * or if {@code BufferCapabilities.isPageFlipping} is not
4013 * {@code true}.
4014 * @see #createBuffers(int, BufferCapabilities)
4015 */
4016 @SuppressWarnings("deprecation")
4017 protected FlipBufferStrategy(int numBuffers, BufferCapabilities caps)
4018 throws AWTException
4019 {
4020 if (!(Component.this instanceof Window) &&
4021 !(Component.this instanceof Canvas) &&
4022 !(Component.this instanceof Applet))
4023 {
4024 throw new ClassCastException(
4025 "Component must be a Canvas or Window or Applet");
4026 }
4027 this.numBuffers = numBuffers;
4028 this.caps = caps;
4029 createBuffers(numBuffers, caps);
4030 }
4031
4032 /**
4033 * Creates one or more complex, flipping buffers with the given
4034 * capabilities.
4035 * @param numBuffers number of buffers to create; must be greater than
4036 * one
4037 * @param caps the capabilities of the buffers.
4038 * {@code BufferCapabilities.isPageFlipping} must be
4039 * {@code true}.
4040 * @exception AWTException if the capabilities supplied could not be
4041 * supported or met
4042 * @exception IllegalStateException if the component has no peer
4043 * @exception IllegalArgumentException if numBuffers is less than two,
4044 * or if {@code BufferCapabilities.isPageFlipping} is not
4045 * {@code true}.
4046 * @see java.awt.BufferCapabilities#isPageFlipping()
4047 */
4048 protected void createBuffers(int numBuffers, BufferCapabilities caps)
4049 throws AWTException
4050 {
4051 if (numBuffers < 2) {
4052 throw new IllegalArgumentException(
4053 "Number of buffers cannot be less than two");
4054 } else if (peer == null) {
4055 throw new IllegalStateException(
4056 "Component must have a valid peer");
4057 } else if (caps == null || !caps.isPageFlipping()) {
4058 throw new IllegalArgumentException(
4059 "Page flipping capabilities must be specified");
4060 }
4061
4062 // save the current bounds
4063 width = getWidth();
4064 height = getHeight();
4065
4066 if (drawBuffer != null) {
4067 // dispose the existing backbuffers
4068 drawBuffer = null;
4069 drawVBuffer = null;
4070 destroyBuffers();
4071 // ... then recreate the backbuffers
4072 }
4073
4074 if (caps instanceof ExtendedBufferCapabilities) {
4075 ExtendedBufferCapabilities ebc =
4076 (ExtendedBufferCapabilities)caps;
4077 if (ebc.getVSync() == VSYNC_ON) {
4078 // if this buffer strategy is not allowed to be v-synced,
4079 // change the caps that we pass to the peer but keep on
4080 // trying to create v-synced buffers;
4081 // do not throw IAE here in case it is disallowed, see
4082 // ExtendedBufferCapabilities for more info
4083 if (!VSyncedBSManager.vsyncAllowed(this)) {
4084 caps = ebc.derive(VSYNC_DEFAULT);
4085 }
4086 }
4087 }
4088
4089 peer.createBuffers(numBuffers, caps);
4090 updateInternalBuffers();
4091 }
4092
4093 /**
4094 * Updates internal buffers (both volatile and non-volatile)
4095 * by requesting the back-buffer from the peer.
4096 */
4097 private void updateInternalBuffers() {
4098 // get the images associated with the draw buffer
4099 drawBuffer = getBackBuffer();
4100 if (drawBuffer instanceof VolatileImage) {
4101 drawVBuffer = (VolatileImage)drawBuffer;
4102 } else {
4103 drawVBuffer = null;
4104 }
4105 }
4106
4107 /**
4108 * @return direct access to the back buffer, as an image.
4109 * @exception IllegalStateException if the buffers have not yet
4110 * been created
4111 */
4112 protected Image getBackBuffer() {
4113 if (peer != null) {
4114 return peer.getBackBuffer();
4115 } else {
4116 throw new IllegalStateException(
4117 "Component must have a valid peer");
4118 }
4119 }
4120
4121 /**
4122 * Flipping moves the contents of the back buffer to the front buffer,
4123 * either by copying or by moving the video pointer.
4124 * @param flipAction an integer value describing the flipping action
4125 * for the contents of the back buffer. This should be one of the
4126 * values of the {@code BufferCapabilities.FlipContents}
4127 * property.
4128 * @exception IllegalStateException if the buffers have not yet
4129 * been created
4130 * @see java.awt.BufferCapabilities#getFlipContents()
4131 */
4132 protected void flip(BufferCapabilities.FlipContents flipAction) {
4133 if (peer != null) {
4134 Image backBuffer = getBackBuffer();
4135 if (backBuffer != null) {
4136 peer.flip(0, 0,
4137 backBuffer.getWidth(null),
4138 backBuffer.getHeight(null), flipAction);
4139 }
4140 } else {
4141 throw new IllegalStateException(
4142 "Component must have a valid peer");
4143 }
4144 }
4145
4146 void flipSubRegion(int x1, int y1, int x2, int y2,
4147 BufferCapabilities.FlipContents flipAction)
4148 {
4149 if (peer != null) {
4150 peer.flip(x1, y1, x2, y2, flipAction);
4151 } else {
4152 throw new IllegalStateException(
4153 "Component must have a valid peer");
4154 }
4155 }
4156
4157 /**
4158 * Destroys the buffers created through this object
4159 */
4160 protected void destroyBuffers() {
4161 VSyncedBSManager.releaseVsync(this);
4162 if (peer != null) {
4163 peer.destroyBuffers();
4164 } else {
4165 throw new IllegalStateException(
4166 "Component must have a valid peer");
4167 }
4168 }
4169
4170 /**
4171 * @return the buffering capabilities of this strategy
4172 */
4173 public BufferCapabilities getCapabilities() {
4174 if (caps instanceof ProxyCapabilities) {
4175 return ((ProxyCapabilities)caps).orig;
4176 } else {
4177 return caps;
4178 }
4179 }
4180
4181 /**
4182 * @return the graphics on the drawing buffer. This method may not
4183 * be synchronized for performance reasons; use of this method by multiple
4184 * threads should be handled at the application level. Disposal of the
4185 * graphics object must be handled by the application.
4186 */
4187 public Graphics getDrawGraphics() {
4188 revalidate();
4189 return drawBuffer.getGraphics();
4190 }
4191
4192 /**
4193 * Restore the drawing buffer if it has been lost
4194 */
4195 protected void revalidate() {
4196 revalidate(true);
4197 }
4198
4199 void revalidate(boolean checkSize) {
4200 validatedContents = false;
4201
4202 if (checkSize && (getWidth() != width || getHeight() != height)) {
4203 // component has been resized; recreate the backbuffers
4204 try {
4205 createBuffers(numBuffers, caps);
4206 } catch (AWTException e) {
4207 // shouldn't be possible
4208 }
4209 validatedContents = true;
4210 }
4211
4212 // get the buffers from the peer every time since they
4213 // might have been replaced in response to a display change event
4214 updateInternalBuffers();
4215
4216 // now validate the backbuffer
4217 if (drawVBuffer != null) {
4218 GraphicsConfiguration gc =
4219 getGraphicsConfiguration_NoClientCode();
4220 int returnCode = drawVBuffer.validate(gc);
4221 if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) {
4222 try {
4223 createBuffers(numBuffers, caps);
4224 } catch (AWTException e) {
4225 // shouldn't be possible
4226 }
4227 if (drawVBuffer != null) {
4228 // backbuffers were recreated, so validate again
4229 drawVBuffer.validate(gc);
4230 }
4231 validatedContents = true;
4232 } else if (returnCode == VolatileImage.IMAGE_RESTORED) {
4233 validatedContents = true;
4234 }
4235 }
4236 }
4237
4238 /**
4239 * @return whether the drawing buffer was lost since the last call to
4240 * {@code getDrawGraphics}
4241 */
4242 public boolean contentsLost() {
4243 if (drawVBuffer == null) {
4244 return false;
4245 }
4246 return drawVBuffer.contentsLost();
4247 }
4248
4249 /**
4250 * @return whether the drawing buffer was recently restored from a lost
4251 * state and reinitialized to the default background color (white)
4252 */
4253 public boolean contentsRestored() {
4254 return validatedContents;
4255 }
4256
4257 /**
4258 * Makes the next available buffer visible by either blitting or
4259 * flipping.
4260 */
4261 public void show() {
4262 flip(caps.getFlipContents());
4263 }
4264
4265 /**
4266 * Makes specified region of the next available buffer visible
4267 * by either blitting or flipping.
4268 */
4269 void showSubRegion(int x1, int y1, int x2, int y2) {
4270 flipSubRegion(x1, y1, x2, y2, caps.getFlipContents());
4271 }
4272
4273 /**
4274 * {@inheritDoc}
4275 * @since 1.6
4276 */
4277 public void dispose() {
4278 if (Component.this.bufferStrategy == this) {
4279 Component.this.bufferStrategy = null;
4280 if (peer != null) {
4281 destroyBuffers();
4282 }
4283 }
4284 }
4285
4286 } // Inner class FlipBufferStrategy
4287
4288 /**
4289 * Inner class for blitting offscreen surfaces to a component.
4290 *
4291 * @author Michael Martak
4292 * @since 1.4
4293 */
4294 protected class BltBufferStrategy extends BufferStrategy {
4295
4296 /**
4297 * The buffering capabilities
4298 */
4299 protected BufferCapabilities caps; // = null
4300 /**
4301 * The back buffers
4302 */
4303 protected VolatileImage[] backBuffers; // = null
4304 /**
4305 * Whether or not the drawing buffer has been recently restored from
4306 * a lost state.
4307 */
4308 protected boolean validatedContents; // = false
4309 /**
4310 * Width of the back buffers
4311 */
4312 protected int width;
4313 /**
4314 * Height of the back buffers
4315 */
4316 protected int height;
4317
4318 /**
4319 * Insets for the hosting Component. The size of the back buffer
4320 * is constrained by these.
4321 */
4322 private Insets insets;
4323
4324 /**
4325 * Creates a new blt buffer strategy around a component
4326 * @param numBuffers number of buffers to create, including the
4327 * front buffer
4328 * @param caps the capabilities of the buffers
4329 */
4330 protected BltBufferStrategy(int numBuffers, BufferCapabilities caps) {
4331 this.caps = caps;
4332 createBackBuffers(numBuffers - 1);
4333 }
4334
4335 /**
4336 * {@inheritDoc}
4337 * @since 1.6
4338 */
4339 public void dispose() {
4340 if (backBuffers != null) {
4341 for (int counter = backBuffers.length - 1; counter >= 0;
4342 counter--) {
4343 if (backBuffers[counter] != null) {
4344 backBuffers[counter].flush();
4345 backBuffers[counter] = null;
4346 }
4347 }
4348 }
4349 if (Component.this.bufferStrategy == this) {
4350 Component.this.bufferStrategy = null;
4351 }
4352 }
4353
4354 /**
4355 * Creates the back buffers
4356 *
4357 * @param numBuffers the number of buffers to create
4358 */
4359 protected void createBackBuffers(int numBuffers) {
4360 if (numBuffers == 0) {
4361 backBuffers = null;
4362 } else {
4363 // save the current bounds
4364 width = getWidth();
4365 height = getHeight();
4366 insets = getInsets_NoClientCode();
4367 int iWidth = width - insets.left - insets.right;
4368 int iHeight = height - insets.top - insets.bottom;
4369
4370 // It is possible for the component's width and/or height
4371 // to be 0 here. Force the size of the backbuffers to
4372 // be > 0 so that creating the image won't fail.
4373 iWidth = Math.max(1, iWidth);
4374 iHeight = Math.max(1, iHeight);
4375 if (backBuffers == null) {
4376 backBuffers = new VolatileImage[numBuffers];
4377 } else {
4378 // flush any existing backbuffers
4379 for (int i = 0; i < numBuffers; i++) {
4380 if (backBuffers[i] != null) {
4381 backBuffers[i].flush();
4382 backBuffers[i] = null;
4383 }
4384 }
4385 }
4386
4387 // create the backbuffers
4388 for (int i = 0; i < numBuffers; i++) {
4389 backBuffers[i] = createVolatileImage(iWidth, iHeight);
4390 }
4391 }
4392 }
4393
4394 /**
4395 * @return the buffering capabilities of this strategy
4396 */
4397 public BufferCapabilities getCapabilities() {
4398 return caps;
4399 }
4400
4401 /**
4402 * @return the draw graphics
4403 */
4404 public Graphics getDrawGraphics() {
4405 revalidate();
4406 Image backBuffer = getBackBuffer();
4407 if (backBuffer == null) {
4408 return getGraphics();
4409 }
4410 SunGraphics2D g = (SunGraphics2D)backBuffer.getGraphics();
4411 g.constrain(-insets.left, -insets.top,
4412 backBuffer.getWidth(null) + insets.left,
4413 backBuffer.getHeight(null) + insets.top);
4414 return g;
4415 }
4416
4417 /**
4418 * @return direct access to the back buffer, as an image.
4419 * If there is no back buffer, returns null.
4420 */
4421 Image getBackBuffer() {
4422 if (backBuffers != null) {
4423 return backBuffers[backBuffers.length - 1];
4424 } else {
4425 return null;
4426 }
4427 }
4428
4429 /**
4430 * Makes the next available buffer visible.
4431 */
4432 public void show() {
4433 showSubRegion(insets.left, insets.top,
4434 width - insets.right,
4435 height - insets.bottom);
4436 }
4437
4438 /**
4439 * Package-private method to present a specific rectangular area
4440 * of this buffer. This class currently shows only the entire
4441 * buffer, by calling showSubRegion() with the full dimensions of
4442 * the buffer. Subclasses (e.g., BltSubRegionBufferStrategy
4443 * and FlipSubRegionBufferStrategy) may have region-specific show
4444 * methods that call this method with actual sub regions of the
4445 * buffer.
4446 */
4447 void showSubRegion(int x1, int y1, int x2, int y2) {
4448 if (backBuffers == null) {
4449 return;
4450 }
4451 // Adjust location to be relative to client area.
4452 x1 -= insets.left;
4453 x2 -= insets.left;
4454 y1 -= insets.top;
4455 y2 -= insets.top;
4456 Graphics g = getGraphics_NoClientCode();
4457 if (g == null) {
4458 // Not showing, bail
4459 return;
4460 }
4461 try {
4462 // First image copy is in terms of Frame's coordinates, need
4463 // to translate to client area.
4464 g.translate(insets.left, insets.top);
4465 for (int i = 0; i < backBuffers.length; i++) {
4466 g.drawImage(backBuffers[i],
4467 x1, y1, x2, y2,
4468 x1, y1, x2, y2,
4469 null);
4470 g.dispose();
4471 g = null;
4472 g = backBuffers[i].getGraphics();
4473 }
4474 } finally {
4475 if (g != null) {
4476 g.dispose();
4477 }
4478 }
4479 }
4480
4481 /**
4482 * Restore the drawing buffer if it has been lost
4483 */
4484 protected void revalidate() {
4485 revalidate(true);
4486 }
4487
4488 void revalidate(boolean checkSize) {
4489 validatedContents = false;
4490
4491 if (backBuffers == null) {
4492 return;
4493 }
4494
4495 if (checkSize) {
4496 Insets insets = getInsets_NoClientCode();
4497 if (getWidth() != width || getHeight() != height ||
4498 !insets.equals(this.insets)) {
4499 // component has been resized; recreate the backbuffers
4500 createBackBuffers(backBuffers.length);
4501 validatedContents = true;
4502 }
4503 }
4504
4505 // now validate the backbuffer
4506 GraphicsConfiguration gc = getGraphicsConfiguration_NoClientCode();
4507 int returnCode =
4508 backBuffers[backBuffers.length - 1].validate(gc);
4509 if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) {
4510 if (checkSize) {
4511 createBackBuffers(backBuffers.length);
4512 // backbuffers were recreated, so validate again
4513 backBuffers[backBuffers.length - 1].validate(gc);
4514 }
4515 // else case means we're called from Swing on the toolkit
4516 // thread, don't recreate buffers as that'll deadlock
4517 // (creating VolatileImages invokes getting GraphicsConfig
4518 // which grabs treelock).
4519 validatedContents = true;
4520 } else if (returnCode == VolatileImage.IMAGE_RESTORED) {
4521 validatedContents = true;
4522 }
4523 }
4524
4525 /**
4526 * @return whether the drawing buffer was lost since the last call to
4527 * {@code getDrawGraphics}
4528 */
4529 public boolean contentsLost() {
4530 if (backBuffers == null) {
4531 return false;
4532 } else {
4533 return backBuffers[backBuffers.length - 1].contentsLost();
4534 }
4535 }
4536
4537 /**
4538 * @return whether the drawing buffer was recently restored from a lost
4539 * state and reinitialized to the default background color (white)
4540 */
4541 public boolean contentsRestored() {
4542 return validatedContents;
4543 }
4544 } // Inner class BltBufferStrategy
4545
4546 /**
4547 * Private class to perform sub-region flipping.
4548 */
4549 private class FlipSubRegionBufferStrategy extends FlipBufferStrategy
4550 implements SubRegionShowable
4551 {
4552
4553 protected FlipSubRegionBufferStrategy(int numBuffers,
4554 BufferCapabilities caps)
4555 throws AWTException
4556 {
4557 super(numBuffers, caps);
4558 }
4559
4560 public void show(int x1, int y1, int x2, int y2) {
4561 showSubRegion(x1, y1, x2, y2);
4562 }
4563
4564 // This is invoked by Swing on the toolkit thread.
4565 public boolean showIfNotLost(int x1, int y1, int x2, int y2) {
4566 if (!contentsLost()) {
4567 showSubRegion(x1, y1, x2, y2);
4568 return !contentsLost();
4569 }
4570 return false;
4571 }
4572 }
4573
4574 /**
4575 * Private class to perform sub-region blitting. Swing will use
4576 * this subclass via the SubRegionShowable interface in order to
4577 * copy only the area changed during a repaint.
4578 * See javax.swing.BufferStrategyPaintManager.
4579 */
4580 private class BltSubRegionBufferStrategy extends BltBufferStrategy
4581 implements SubRegionShowable
4582 {
4583
4584 protected BltSubRegionBufferStrategy(int numBuffers,
4585 BufferCapabilities caps)
4586 {
4587 super(numBuffers, caps);
4588 }
4589
4590 public void show(int x1, int y1, int x2, int y2) {
4591 showSubRegion(x1, y1, x2, y2);
4592 }
4593
4594 // This method is called by Swing on the toolkit thread.
4595 public boolean showIfNotLost(int x1, int y1, int x2, int y2) {
4596 if (!contentsLost()) {
4597 showSubRegion(x1, y1, x2, y2);
4598 return !contentsLost();
4599 }
4600 return false;
4601 }
4602 }
4603
4604 /**
4605 * Inner class for flipping buffers on a component. That component must
4606 * be a {@code Canvas} or {@code Window}.
4607 * @see Canvas
4608 * @see Window
4609 * @see java.awt.image.BufferStrategy
4610 * @author Michael Martak
4611 * @since 1.4
4612 */
4613 private class SingleBufferStrategy extends BufferStrategy {
4614
4615 private BufferCapabilities caps;
4616
4617 public SingleBufferStrategy(BufferCapabilities caps) {
4618 this.caps = caps;
4619 }
4620 public BufferCapabilities getCapabilities() {
4621 return caps;
4622 }
4623 public Graphics getDrawGraphics() {
4624 return getGraphics();
4625 }
4626 public boolean contentsLost() {
4627 return false;
4628 }
4629 public boolean contentsRestored() {
4630 return false;
4631 }
4632 public void show() {
4633 // Do nothing
4634 }
4635 } // Inner class SingleBufferStrategy
4636
4637 /**
4638 * Sets whether or not paint messages received from the operating system
4639 * should be ignored. This does not affect paint events generated in
4640 * software by the AWT, unless they are an immediate response to an
4641 * OS-level paint message.
4642 * <p>
4643 * This is useful, for example, if running under full-screen mode and
4644 * better performance is desired, or if page-flipping is used as the
4645 * buffer strategy.
4646 *
4647 * @param ignoreRepaint {@code true} if the paint messages from the OS
4648 * should be ignored; otherwise {@code false}
4649 *
4650 * @since 1.4
4651 * @see #getIgnoreRepaint
4652 * @see Canvas#createBufferStrategy
4653 * @see Window#createBufferStrategy
4654 * @see java.awt.image.BufferStrategy
4655 * @see GraphicsDevice#setFullScreenWindow
4656 */
4657 public void setIgnoreRepaint(boolean ignoreRepaint) {
4658 this.ignoreRepaint = ignoreRepaint;
4659 }
4660
4661 /**
4662 * @return whether or not paint messages received from the operating system
4663 * should be ignored.
4664 *
4665 * @since 1.4
4666 * @see #setIgnoreRepaint
4667 */
4668 public boolean getIgnoreRepaint() {
4669 return ignoreRepaint;
4670 }
4671
4672 /**
4673 * Checks whether this component "contains" the specified point,
4674 * where {@code x} and {@code y} are defined to be
4675 * relative to the coordinate system of this component.
4676 *
4677 * @param x the <i>x</i> coordinate of the point
4678 * @param y the <i>y</i> coordinate of the point
4679 * @return {@code true} if the point is within the component;
4680 * otherwise {@code false}
4681 * @see #getComponentAt(int, int)
4682 * @since 1.1
4683 */
4684 public boolean contains(int x, int y) {
4685 return inside(x, y);
4686 }
4687
4688 /**
4689 * Checks whether the point is inside of this component.
4690 *
4691 * @param x the <i>x</i> coordinate of the point
4692 * @param y the <i>y</i> coordinate of the point
4693 * @return {@code true} if the point is within the component;
4694 * otherwise {@code false}
4695 * @deprecated As of JDK version 1.1,
4696 * replaced by contains(int, int).
4697 */
4698 @Deprecated
4699 public boolean inside(int x, int y) {
4700 return (x >= 0) && (x < width) && (y >= 0) && (y < height);
4701 }
4702
4703 /**
4704 * Checks whether this component "contains" the specified point,
4705 * where the point's <i>x</i> and <i>y</i> coordinates are defined
4706 * to be relative to the coordinate system of this component.
4707 *
4708 * @param p the point
4709 * @return {@code true} if the point is within the component;
4710 * otherwise {@code false}
4711 * @throws NullPointerException if {@code p} is {@code null}
4712 * @see #getComponentAt(Point)
4713 * @since 1.1
4714 */
4715 public boolean contains(Point p) {
4716 return contains(p.x, p.y);
4717 }
4718
4719 /**
4720 * Determines if this component or one of its immediate
4721 * subcomponents contains the (<i>x</i>, <i>y</i>) location,
4722 * and if so, returns the containing component. This method only
4723 * looks one level deep. If the point (<i>x</i>, <i>y</i>) is
4724 * inside a subcomponent that itself has subcomponents, it does not
4725 * go looking down the subcomponent tree.
4726 * <p>
4727 * The {@code locate} method of {@code Component} simply
4728 * returns the component itself if the (<i>x</i>, <i>y</i>)
4729 * coordinate location is inside its bounding box, and {@code null}
4730 * otherwise.
4731 * @param x the <i>x</i> coordinate
4732 * @param y the <i>y</i> coordinate
4733 * @return the component or subcomponent that contains the
4734 * (<i>x</i>, <i>y</i>) location;
4735 * {@code null} if the location
4736 * is outside this component
4737 * @see #contains(int, int)
4738 * @since 1.0
4739 */
4740 public Component getComponentAt(int x, int y) {
4741 return locate(x, y);
4742 }
4743
4744 /**
4745 * Returns the component occupying the position specified (this component,
4746 * or immediate child component, or null if neither
4747 * of the first two occupies the location).
4748 *
4749 * @param x the <i>x</i> coordinate to search for components at
4750 * @param y the <i>y</i> coordinate to search for components at
4751 * @return the component at the specified location or {@code null}
4752 * @deprecated As of JDK version 1.1,
4753 * replaced by getComponentAt(int, int).
4754 */
4755 @Deprecated
4756 public Component locate(int x, int y) {
4757 return contains(x, y) ? this : null;
4758 }
4759
4760 /**
4761 * Returns the component or subcomponent that contains the
4762 * specified point.
4763 * @param p the point
4764 * @return the component at the specified location or {@code null}
4765 * @see java.awt.Component#contains
4766 * @since 1.1
4767 */
4768 public Component getComponentAt(Point p) {
4769 return getComponentAt(p.x, p.y);
4770 }
4771
4772 /**
4773 * @param e the event to deliver
4774 * @deprecated As of JDK version 1.1,
4775 * replaced by {@code dispatchEvent(AWTEvent e)}.
4776 */
4777 @Deprecated
4778 public void deliverEvent(Event e) {
4779 postEvent(e);
4780 }
4781
4782 /**
4783 * Dispatches an event to this component or one of its sub components.
4784 * Calls {@code processEvent} before returning for 1.1-style
4785 * events which have been enabled for the {@code Component}.
4786 * @param e the event
4787 */
4788 public final void dispatchEvent(AWTEvent e) {
4789 dispatchEventImpl(e);
4790 }
4791
4792 @SuppressWarnings("deprecation")
4793 void dispatchEventImpl(AWTEvent e) {
4794 int id = e.getID();
4795
4796 // Check that this component belongs to this app-context
4797 AppContext compContext = appContext;
4798 if (compContext != null && !compContext.equals(AppContext.getAppContext())) {
4799 if (eventLog.isLoggable(PlatformLogger.Level.FINE)) {
4800 eventLog.fine("Event " + e + " is being dispatched on the wrong AppContext");
4801 }
4802 }
4803
4804 if (eventLog.isLoggable(PlatformLogger.Level.FINEST)) {
4805 eventLog.finest("{0}", e);
4806 }
4807
4808 /*
4809 * 0. Set timestamp and modifiers of current event.
4810 */
4811 if (!(e instanceof KeyEvent)) {
4812 // Timestamp of a key event is set later in DKFM.preDispatchKeyEvent(KeyEvent).
4813 EventQueue.setCurrentEventAndMostRecentTime(e);
4814 }
4815
4816 /*
4817 * 1. Pre-dispatchers. Do any necessary retargeting/reordering here
4818 * before we notify AWTEventListeners.
4819 */
4820
4821 if (e instanceof SunDropTargetEvent) {
4822 ((SunDropTargetEvent)e).dispatch();
4823 return;
4824 }
4825
4826 if (!e.focusManagerIsDispatching) {
4827 // Invoke the private focus retargeting method which provides
4828 // lightweight Component support
4829 if (e.isPosted) {
4830 e = KeyboardFocusManager.retargetFocusEvent(e);
4831 e.isPosted = true;
4832 }
4833
4834 // Now, with the event properly targeted to a lightweight
4835 // descendant if necessary, invoke the public focus retargeting
4836 // and dispatching function
4837 if (KeyboardFocusManager.getCurrentKeyboardFocusManager().
4838 dispatchEvent(e))
4839 {
4840 return;
4841 }
4842 }
4843 if ((e instanceof FocusEvent) && focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
4844 focusLog.finest("" + e);
4845 }
4846 // MouseWheel may need to be retargeted here so that
4847 // AWTEventListener sees the event go to the correct
4848 // Component. If the MouseWheelEvent needs to go to an ancestor,
4849 // the event is dispatched to the ancestor, and dispatching here
4850 // stops.
4851 if (id == MouseEvent.MOUSE_WHEEL &&
4852 (!eventTypeEnabled(id)) &&
4853 (peer != null && !peer.handlesWheelScrolling()) &&
4854 (dispatchMouseWheelToAncestor((MouseWheelEvent)e)))
4855 {
4856 return;
4857 }
4858
4859 /*
4860 * 2. Allow the Toolkit to pass this to AWTEventListeners.
4861 */
4862 Toolkit toolkit = Toolkit.getDefaultToolkit();
4863 toolkit.notifyAWTEventListeners(e);
4864
4865
4866 /*
4867 * 3. If no one has consumed a key event, allow the
4868 * KeyboardFocusManager to process it.
4869 */
4870 if (!e.isConsumed()) {
4871 if (e instanceof java.awt.event.KeyEvent) {
4872 KeyboardFocusManager.getCurrentKeyboardFocusManager().
4873 processKeyEvent(this, (KeyEvent)e);
4874 if (e.isConsumed()) {
4875 return;
4876 }
4877 }
4878 }
4879
4880 /*
4881 * 4. Allow input methods to process the event
4882 */
4883 if (areInputMethodsEnabled()) {
4884 // We need to pass on InputMethodEvents since some host
4885 // input method adapters send them through the Java
4886 // event queue instead of directly to the component,
4887 // and the input context also handles the Java composition window
4888 if(((e instanceof InputMethodEvent) && !(this instanceof CompositionArea))
4889 ||
4890 // Otherwise, we only pass on input and focus events, because
4891 // a) input methods shouldn't know about semantic or component-level events
4892 // b) passing on the events takes time
4893 // c) isConsumed() is always true for semantic events.
4894 (e instanceof InputEvent) || (e instanceof FocusEvent)) {
4895 InputContext inputContext = getInputContext();
4896
4897
4898 if (inputContext != null) {
4899 inputContext.dispatchEvent(e);
4900 if (e.isConsumed()) {
4901 if ((e instanceof FocusEvent) && focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
4902 focusLog.finest("3579: Skipping " + e);
4903 }
4904 return;
4905 }
4906 }
4907 }
4908 } else {
4909 // When non-clients get focus, we need to explicitly disable the native
4910 // input method. The native input method is actually not disabled when
4911 // the active/passive/peered clients loose focus.
4912 if (id == FocusEvent.FOCUS_GAINED) {
4913 InputContext inputContext = getInputContext();
4914 if (inputContext != null && inputContext instanceof sun.awt.im.InputContext) {
4915 ((sun.awt.im.InputContext)inputContext).disableNativeIM();
4916 }
4917 }
4918 }
4919
4920
4921 /*
4922 * 5. Pre-process any special events before delivery
4923 */
4924 switch(id) {
4925 // Handling of the PAINT and UPDATE events is now done in the
4926 // peer's handleEvent() method so the background can be cleared
4927 // selectively for non-native components on Windows only.
4928 // - Fred.Ecks@Eng.sun.com, 5-8-98
4929
4930 case KeyEvent.KEY_PRESSED:
4931 case KeyEvent.KEY_RELEASED:
4932 Container p = (Container)((this instanceof Container) ? this : parent);
4933 if (p != null) {
4934 p.preProcessKeyEvent((KeyEvent)e);
4935 if (e.isConsumed()) {
4936 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
4937 focusLog.finest("Pre-process consumed event");
4938 }
4939 return;
4940 }
4941 }
4942 break;
4943
4944 default:
4945 break;
4946 }
4947
4948 /*
4949 * 6. Deliver event for normal processing
4950 */
4951 if (newEventsOnly) {
4952 // Filtering needs to really be moved to happen at a lower
4953 // level in order to get maximum performance gain; it is
4954 // here temporarily to ensure the API spec is honored.
4955 //
4956 if (eventEnabled(e)) {
4957 processEvent(e);
4958 }
4959 } else if (id == MouseEvent.MOUSE_WHEEL) {
4960 // newEventsOnly will be false for a listenerless ScrollPane, but
4961 // MouseWheelEvents still need to be dispatched to it so scrolling
4962 // can be done.
4963 autoProcessMouseWheel((MouseWheelEvent)e);
4964 } else if (!(e instanceof MouseEvent && !postsOldMouseEvents())) {
4965 //
4966 // backward compatibility
4967 //
4968 Event olde = e.convertToOld();
4969 if (olde != null) {
4970 int key = olde.key;
4971 int modifiers = olde.modifiers;
4972
4973 postEvent(olde);
4974 if (olde.isConsumed()) {
4975 e.consume();
4976 }
4977 // if target changed key or modifier values, copy them
4978 // back to original event
4979 //
4980 switch(olde.id) {
4981 case Event.KEY_PRESS:
4982 case Event.KEY_RELEASE:
4983 case Event.KEY_ACTION:
4984 case Event.KEY_ACTION_RELEASE:
4985 if (olde.key != key) {
4986 ((KeyEvent)e).setKeyChar(olde.getKeyEventChar());
4987 }
4988 if (olde.modifiers != modifiers) {
4989 ((KeyEvent)e).setModifiers(olde.modifiers);
4990 }
4991 break;
4992 default:
4993 break;
4994 }
4995 }
4996 }
4997
4998 /*
4999 * 9. Allow the peer to process the event.
5000 * Except KeyEvents, they will be processed by peer after
5001 * all KeyEventPostProcessors
5002 * (see DefaultKeyboardFocusManager.dispatchKeyEvent())
5003 */
5004 if (!(e instanceof KeyEvent)) {
5005 ComponentPeer tpeer = peer;
5006 if (e instanceof FocusEvent && (tpeer == null || tpeer instanceof LightweightPeer)) {
5007 // if focus owner is lightweight then its native container
5008 // processes event
5009 Component source = (Component)e.getSource();
5010 if (source != null) {
5011 Container target = source.getNativeContainer();
5012 if (target != null) {
5013 tpeer = target.peer;
5014 }
5015 }
5016 }
5017 if (tpeer != null) {
5018 tpeer.handleEvent(e);
5019 }
5020 }
5021 } // dispatchEventImpl()
5022
5023 /*
5024 * If newEventsOnly is false, method is called so that ScrollPane can
5025 * override it and handle common-case mouse wheel scrolling. NOP
5026 * for Component.
5027 */
5028 void autoProcessMouseWheel(MouseWheelEvent e) {}
5029
5030 /*
5031 * Dispatch given MouseWheelEvent to the first ancestor for which
5032 * MouseWheelEvents are enabled.
5033 *
5034 * Returns whether or not event was dispatched to an ancestor
5035 */
5036 @SuppressWarnings("deprecation")
5037 boolean dispatchMouseWheelToAncestor(MouseWheelEvent e) {
5038 int newX, newY;
5039 newX = e.getX() + getX(); // Coordinates take into account at least
5040 newY = e.getY() + getY(); // the cursor's position relative to this
5041 // Component (e.getX()), and this Component's
5042 // position relative to its parent.
5043 MouseWheelEvent newMWE;
5044
5045 if (eventLog.isLoggable(PlatformLogger.Level.FINEST)) {
5046 eventLog.finest("dispatchMouseWheelToAncestor");
5047 eventLog.finest("orig event src is of " + e.getSource().getClass());
5048 }
5049
5050 /* parent field for Window refers to the owning Window.
5051 * MouseWheelEvents should NOT be propagated into owning Windows
5052 */
5053 synchronized (getTreeLock()) {
5054 Container anc = getParent();
5055 while (anc != null && !anc.eventEnabled(e)) {
5056 // fix coordinates to be relative to new event source
5057 newX += anc.getX();
5058 newY += anc.getY();
5059
5060 if (!(anc instanceof Window)) {
5061 anc = anc.getParent();
5062 }
5063 else {
5064 break;
5065 }
5066 }
5067
5068 if (eventLog.isLoggable(PlatformLogger.Level.FINEST)) {
5069 eventLog.finest("new event src is " + anc.getClass());
5070 }
5071
5072 if (anc != null && anc.eventEnabled(e)) {
5073 // Change event to be from new source, with new x,y
5074 // For now, just create a new event - yucky
5075
5076 newMWE = new MouseWheelEvent(anc, // new source
5077 e.getID(),
5078 e.getWhen(),
5079 e.getModifiers(),
5080 newX, // x relative to new source
5081 newY, // y relative to new source
5082 e.getXOnScreen(),
5083 e.getYOnScreen(),
5084 e.getClickCount(),
5085 e.isPopupTrigger(),
5086 e.getScrollType(),
5087 e.getScrollAmount(),
5088 e.getWheelRotation(),
5089 e.getPreciseWheelRotation());
5090 ((AWTEvent)e).copyPrivateDataInto(newMWE);
5091 // When dispatching a wheel event to
5092 // ancestor, there is no need trying to find descendant
5093 // lightweights to dispatch event to.
5094 // If we dispatch the event to toplevel ancestor,
5095 // this could enclose the loop: 6480024.
5096 anc.dispatchEventToSelf(newMWE);
5097 if (newMWE.isConsumed()) {
5098 e.consume();
5099 }
5100 return true;
5101 }
5102 }
5103 return false;
5104 }
5105
5106 boolean areInputMethodsEnabled() {
5107 // in 1.2, we assume input method support is required for all
5108 // components that handle key events, but components can turn off
5109 // input methods by calling enableInputMethods(false).
5110 return ((eventMask & AWTEvent.INPUT_METHODS_ENABLED_MASK) != 0) &&
5111 ((eventMask & AWTEvent.KEY_EVENT_MASK) != 0 || keyListener != null);
5112 }
5113
5114 // REMIND: remove when filtering is handled at lower level
5115 boolean eventEnabled(AWTEvent e) {
5116 return eventTypeEnabled(e.id);
5117 }
5118
5119 boolean eventTypeEnabled(int type) {
5120 switch(type) {
5121 case ComponentEvent.COMPONENT_MOVED:
5122 case ComponentEvent.COMPONENT_RESIZED:
5123 case ComponentEvent.COMPONENT_SHOWN:
5124 case ComponentEvent.COMPONENT_HIDDEN:
5125 if ((eventMask & AWTEvent.COMPONENT_EVENT_MASK) != 0 ||
5126 componentListener != null) {
5127 return true;
5128 }
5129 break;
5130 case FocusEvent.FOCUS_GAINED:
5131 case FocusEvent.FOCUS_LOST:
5132 if ((eventMask & AWTEvent.FOCUS_EVENT_MASK) != 0 ||
5133 focusListener != null) {
5134 return true;
5135 }
5136 break;
5137 case KeyEvent.KEY_PRESSED:
5138 case KeyEvent.KEY_RELEASED:
5139 case KeyEvent.KEY_TYPED:
5140 if ((eventMask & AWTEvent.KEY_EVENT_MASK) != 0 ||
5141 keyListener != null) {
5142 return true;
5143 }
5144 break;
5145 case MouseEvent.MOUSE_PRESSED:
5146 case MouseEvent.MOUSE_RELEASED:
5147 case MouseEvent.MOUSE_ENTERED:
5148 case MouseEvent.MOUSE_EXITED:
5149 case MouseEvent.MOUSE_CLICKED:
5150 if ((eventMask & AWTEvent.MOUSE_EVENT_MASK) != 0 ||
5151 mouseListener != null) {
5152 return true;
5153 }
5154 break;
5155 case MouseEvent.MOUSE_MOVED:
5156 case MouseEvent.MOUSE_DRAGGED:
5157 if ((eventMask & AWTEvent.MOUSE_MOTION_EVENT_MASK) != 0 ||
5158 mouseMotionListener != null) {
5159 return true;
5160 }
5161 break;
5162 case MouseEvent.MOUSE_WHEEL:
5163 if ((eventMask & AWTEvent.MOUSE_WHEEL_EVENT_MASK) != 0 ||
5164 mouseWheelListener != null) {
5165 return true;
5166 }
5167 break;
5168 case InputMethodEvent.INPUT_METHOD_TEXT_CHANGED:
5169 case InputMethodEvent.CARET_POSITION_CHANGED:
5170 if ((eventMask & AWTEvent.INPUT_METHOD_EVENT_MASK) != 0 ||
5171 inputMethodListener != null) {
5172 return true;
5173 }
5174 break;
5175 case HierarchyEvent.HIERARCHY_CHANGED:
5176 if ((eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0 ||
5177 hierarchyListener != null) {
5178 return true;
5179 }
5180 break;
5181 case HierarchyEvent.ANCESTOR_MOVED:
5182 case HierarchyEvent.ANCESTOR_RESIZED:
5183 if ((eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0 ||
5184 hierarchyBoundsListener != null) {
5185 return true;
5186 }
5187 break;
5188 case ActionEvent.ACTION_PERFORMED:
5189 if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0) {
5190 return true;
5191 }
5192 break;
5193 case TextEvent.TEXT_VALUE_CHANGED:
5194 if ((eventMask & AWTEvent.TEXT_EVENT_MASK) != 0) {
5195 return true;
5196 }
5197 break;
5198 case ItemEvent.ITEM_STATE_CHANGED:
5199 if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0) {
5200 return true;
5201 }
5202 break;
5203 case AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED:
5204 if ((eventMask & AWTEvent.ADJUSTMENT_EVENT_MASK) != 0) {
5205 return true;
5206 }
5207 break;
5208 default:
5209 break;
5210 }
5211 //
5212 // Always pass on events defined by external programs.
5213 //
5214 if (type > AWTEvent.RESERVED_ID_MAX) {
5215 return true;
5216 }
5217 return false;
5218 }
5219
5220 /**
5221 * @deprecated As of JDK version 1.1,
5222 * replaced by dispatchEvent(AWTEvent).
5223 */
5224 @Deprecated
5225 public boolean postEvent(Event e) {
5226 ComponentPeer peer = this.peer;
5227
5228 if (handleEvent(e)) {
5229 e.consume();
5230 return true;
5231 }
5232
5233 Component parent = this.parent;
5234 int eventx = e.x;
5235 int eventy = e.y;
5236 if (parent != null) {
5237 e.translate(x, y);
5238 if (parent.postEvent(e)) {
5239 e.consume();
5240 return true;
5241 }
5242 // restore coords
5243 e.x = eventx;
5244 e.y = eventy;
5245 }
5246 return false;
5247 }
5248
5249 // Event source interfaces
5250
5251 /**
5252 * Adds the specified component listener to receive component events from
5253 * this component.
5254 * If listener {@code l} is {@code null},
5255 * no exception is thrown and no action is performed.
5256 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5257 * >AWT Threading Issues</a> for details on AWT's threading model.
5258 *
5259 * @param l the component listener
5260 * @see java.awt.event.ComponentEvent
5261 * @see java.awt.event.ComponentListener
5262 * @see #removeComponentListener
5263 * @see #getComponentListeners
5264 * @since 1.1
5265 */
5266 public synchronized void addComponentListener(ComponentListener l) {
5267 if (l == null) {
5268 return;
5269 }
5270 componentListener = AWTEventMulticaster.add(componentListener, l);
5271 newEventsOnly = true;
5272 }
5273
5274 /**
5275 * Removes the specified component listener so that it no longer
5276 * receives component events from this component. This method performs
5277 * no function, nor does it throw an exception, if the listener
5278 * specified by the argument was not previously added to this component.
5279 * If listener {@code l} is {@code null},
5280 * no exception is thrown and no action is performed.
5281 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5282 * >AWT Threading Issues</a> for details on AWT's threading model.
5283 * @param l the component listener
5284 * @see java.awt.event.ComponentEvent
5285 * @see java.awt.event.ComponentListener
5286 * @see #addComponentListener
5287 * @see #getComponentListeners
5288 * @since 1.1
5289 */
5290 public synchronized void removeComponentListener(ComponentListener l) {
5291 if (l == null) {
5292 return;
5293 }
5294 componentListener = AWTEventMulticaster.remove(componentListener, l);
5295 }
5296
5297 /**
5298 * Returns an array of all the component listeners
5299 * registered on this component.
5300 *
5301 * @return all {@code ComponentListener}s of this component
5302 * or an empty array if no component
5303 * listeners are currently registered
5304 *
5305 * @see #addComponentListener
5306 * @see #removeComponentListener
5307 * @since 1.4
5308 */
5309 public synchronized ComponentListener[] getComponentListeners() {
5310 return getListeners(ComponentListener.class);
5311 }
5312
5313 /**
5314 * Adds the specified focus listener to receive focus events from
5315 * this component when this component gains input focus.
5316 * If listener {@code l} is {@code null},
5317 * no exception is thrown and no action is performed.
5318 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5319 * >AWT Threading Issues</a> for details on AWT's threading model.
5320 *
5321 * @param l the focus listener
5322 * @see java.awt.event.FocusEvent
5323 * @see java.awt.event.FocusListener
5324 * @see #removeFocusListener
5325 * @see #getFocusListeners
5326 * @since 1.1
5327 */
5328 public synchronized void addFocusListener(FocusListener l) {
5329 if (l == null) {
5330 return;
5331 }
5332 focusListener = AWTEventMulticaster.add(focusListener, l);
5333 newEventsOnly = true;
5334
5335 // if this is a lightweight component, enable focus events
5336 // in the native container.
5337 if (peer instanceof LightweightPeer) {
5338 parent.proxyEnableEvents(AWTEvent.FOCUS_EVENT_MASK);
5339 }
5340 }
5341
5342 /**
5343 * Removes the specified focus listener so that it no longer
5344 * receives focus events from this component. This method performs
5345 * no function, nor does it throw an exception, if the listener
5346 * specified by the argument was not previously added to this component.
5347 * If listener {@code l} is {@code null},
5348 * no exception is thrown and no action is performed.
5349 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5350 * >AWT Threading Issues</a> for details on AWT's threading model.
5351 *
5352 * @param l the focus listener
5353 * @see java.awt.event.FocusEvent
5354 * @see java.awt.event.FocusListener
5355 * @see #addFocusListener
5356 * @see #getFocusListeners
5357 * @since 1.1
5358 */
5359 public synchronized void removeFocusListener(FocusListener l) {
5360 if (l == null) {
5361 return;
5362 }
5363 focusListener = AWTEventMulticaster.remove(focusListener, l);
5364 }
5365
5366 /**
5367 * Returns an array of all the focus listeners
5368 * registered on this component.
5369 *
5370 * @return all of this component's {@code FocusListener}s
5371 * or an empty array if no component
5372 * listeners are currently registered
5373 *
5374 * @see #addFocusListener
5375 * @see #removeFocusListener
5376 * @since 1.4
5377 */
5378 public synchronized FocusListener[] getFocusListeners() {
5379 return getListeners(FocusListener.class);
5380 }
5381
5382 /**
5383 * Adds the specified hierarchy listener to receive hierarchy changed
5384 * events from this component when the hierarchy to which this container
5385 * belongs changes.
5386 * If listener {@code l} is {@code null},
5387 * no exception is thrown and no action is performed.
5388 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5389 * >AWT Threading Issues</a> for details on AWT's threading model.
5390 *
5391 * @param l the hierarchy listener
5392 * @see java.awt.event.HierarchyEvent
5393 * @see java.awt.event.HierarchyListener
5394 * @see #removeHierarchyListener
5395 * @see #getHierarchyListeners
5396 * @since 1.3
5397 */
5398 public void addHierarchyListener(HierarchyListener l) {
5399 if (l == null) {
5400 return;
5401 }
5402 boolean notifyAncestors;
5403 synchronized (this) {
5404 notifyAncestors =
5405 (hierarchyListener == null &&
5406 (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) == 0);
5407 hierarchyListener = AWTEventMulticaster.add(hierarchyListener, l);
5408 notifyAncestors = (notifyAncestors && hierarchyListener != null);
5409 newEventsOnly = true;
5410 }
5411 if (notifyAncestors) {
5412 synchronized (getTreeLock()) {
5413 adjustListeningChildrenOnParent(AWTEvent.HIERARCHY_EVENT_MASK,
5414 1);
5415 }
5416 }
5417 }
5418
5419 /**
5420 * Removes the specified hierarchy listener so that it no longer
5421 * receives hierarchy changed events from this component. This method
5422 * performs no function, nor does it throw an exception, if the listener
5423 * specified by the argument was not previously added to this component.
5424 * If listener {@code l} is {@code null},
5425 * no exception is thrown and no action is performed.
5426 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5427 * >AWT Threading Issues</a> for details on AWT's threading model.
5428 *
5429 * @param l the hierarchy listener
5430 * @see java.awt.event.HierarchyEvent
5431 * @see java.awt.event.HierarchyListener
5432 * @see #addHierarchyListener
5433 * @see #getHierarchyListeners
5434 * @since 1.3
5435 */
5436 public void removeHierarchyListener(HierarchyListener l) {
5437 if (l == null) {
5438 return;
5439 }
5440 boolean notifyAncestors;
5441 synchronized (this) {
5442 notifyAncestors =
5443 (hierarchyListener != null &&
5444 (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) == 0);
5445 hierarchyListener =
5446 AWTEventMulticaster.remove(hierarchyListener, l);
5447 notifyAncestors = (notifyAncestors && hierarchyListener == null);
5448 }
5449 if (notifyAncestors) {
5450 synchronized (getTreeLock()) {
5451 adjustListeningChildrenOnParent(AWTEvent.HIERARCHY_EVENT_MASK,
5452 -1);
5453 }
5454 }
5455 }
5456
5457 /**
5458 * Returns an array of all the hierarchy listeners
5459 * registered on this component.
5460 *
5461 * @return all of this component's {@code HierarchyListener}s
5462 * or an empty array if no hierarchy
5463 * listeners are currently registered
5464 *
5465 * @see #addHierarchyListener
5466 * @see #removeHierarchyListener
5467 * @since 1.4
5468 */
5469 public synchronized HierarchyListener[] getHierarchyListeners() {
5470 return getListeners(HierarchyListener.class);
5471 }
5472
5473 /**
5474 * Adds the specified hierarchy bounds listener to receive hierarchy
5475 * bounds events from this component when the hierarchy to which this
5476 * container belongs changes.
5477 * If listener {@code l} is {@code null},
5478 * no exception is thrown and no action is performed.
5479 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5480 * >AWT Threading Issues</a> for details on AWT's threading model.
5481 *
5482 * @param l the hierarchy bounds listener
5483 * @see java.awt.event.HierarchyEvent
5484 * @see java.awt.event.HierarchyBoundsListener
5485 * @see #removeHierarchyBoundsListener
5486 * @see #getHierarchyBoundsListeners
5487 * @since 1.3
5488 */
5489 public void addHierarchyBoundsListener(HierarchyBoundsListener l) {
5490 if (l == null) {
5491 return;
5492 }
5493 boolean notifyAncestors;
5494 synchronized (this) {
5495 notifyAncestors =
5496 (hierarchyBoundsListener == null &&
5497 (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) == 0);
5498 hierarchyBoundsListener =
5499 AWTEventMulticaster.add(hierarchyBoundsListener, l);
5500 notifyAncestors = (notifyAncestors &&
5501 hierarchyBoundsListener != null);
5502 newEventsOnly = true;
5503 }
5504 if (notifyAncestors) {
5505 synchronized (getTreeLock()) {
5506 adjustListeningChildrenOnParent(
5507 AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK, 1);
5508 }
5509 }
5510 }
5511
5512 /**
5513 * Removes the specified hierarchy bounds listener so that it no longer
5514 * receives hierarchy bounds events from this component. This method
5515 * performs no function, nor does it throw an exception, if the listener
5516 * specified by the argument was not previously added to this component.
5517 * If listener {@code l} is {@code null},
5518 * no exception is thrown and no action is performed.
5519 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5520 * >AWT Threading Issues</a> for details on AWT's threading model.
5521 *
5522 * @param l the hierarchy bounds listener
5523 * @see java.awt.event.HierarchyEvent
5524 * @see java.awt.event.HierarchyBoundsListener
5525 * @see #addHierarchyBoundsListener
5526 * @see #getHierarchyBoundsListeners
5527 * @since 1.3
5528 */
5529 public void removeHierarchyBoundsListener(HierarchyBoundsListener l) {
5530 if (l == null) {
5531 return;
5532 }
5533 boolean notifyAncestors;
5534 synchronized (this) {
5535 notifyAncestors =
5536 (hierarchyBoundsListener != null &&
5537 (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) == 0);
5538 hierarchyBoundsListener =
5539 AWTEventMulticaster.remove(hierarchyBoundsListener, l);
5540 notifyAncestors = (notifyAncestors &&
5541 hierarchyBoundsListener == null);
5542 }
5543 if (notifyAncestors) {
5544 synchronized (getTreeLock()) {
5545 adjustListeningChildrenOnParent(
5546 AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK, -1);
5547 }
5548 }
5549 }
5550
5551 // Should only be called while holding the tree lock
5552 int numListening(long mask) {
5553 // One mask or the other, but not neither or both.
5554 if (eventLog.isLoggable(PlatformLogger.Level.FINE)) {
5555 if ((mask != AWTEvent.HIERARCHY_EVENT_MASK) &&
5556 (mask != AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK))
5557 {
5558 eventLog.fine("Assertion failed");
5559 }
5560 }
5561 if ((mask == AWTEvent.HIERARCHY_EVENT_MASK &&
5562 (hierarchyListener != null ||
5563 (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0)) ||
5564 (mask == AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK &&
5565 (hierarchyBoundsListener != null ||
5566 (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0))) {
5567 return 1;
5568 } else {
5569 return 0;
5570 }
5571 }
5572
5573 // Should only be called while holding tree lock
5574 int countHierarchyMembers() {
5575 return 1;
5576 }
5577 // Should only be called while holding the tree lock
5578 int createHierarchyEvents(int id, Component changed,
5579 Container changedParent, long changeFlags,
5580 boolean enabledOnToolkit) {
5581 switch (id) {
5582 case HierarchyEvent.HIERARCHY_CHANGED:
5583 if (hierarchyListener != null ||
5584 (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0 ||
5585 enabledOnToolkit) {
5586 HierarchyEvent e = new HierarchyEvent(this, id, changed,
5587 changedParent,
5588 changeFlags);
5589 dispatchEvent(e);
5590 return 1;
5591 }
5592 break;
5593 case HierarchyEvent.ANCESTOR_MOVED:
5594 case HierarchyEvent.ANCESTOR_RESIZED:
5595 if (eventLog.isLoggable(PlatformLogger.Level.FINE)) {
5596 if (changeFlags != 0) {
5597 eventLog.fine("Assertion (changeFlags == 0) failed");
5598 }
5599 }
5600 if (hierarchyBoundsListener != null ||
5601 (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0 ||
5602 enabledOnToolkit) {
5603 HierarchyEvent e = new HierarchyEvent(this, id, changed,
5604 changedParent);
5605 dispatchEvent(e);
5606 return 1;
5607 }
5608 break;
5609 default:
5610 // assert false
5611 if (eventLog.isLoggable(PlatformLogger.Level.FINE)) {
5612 eventLog.fine("This code must never be reached");
5613 }
5614 break;
5615 }
5616 return 0;
5617 }
5618
5619 /**
5620 * Returns an array of all the hierarchy bounds listeners
5621 * registered on this component.
5622 *
5623 * @return all of this component's {@code HierarchyBoundsListener}s
5624 * or an empty array if no hierarchy bounds
5625 * listeners are currently registered
5626 *
5627 * @see #addHierarchyBoundsListener
5628 * @see #removeHierarchyBoundsListener
5629 * @since 1.4
5630 */
5631 public synchronized HierarchyBoundsListener[] getHierarchyBoundsListeners() {
5632 return getListeners(HierarchyBoundsListener.class);
5633 }
5634
5635 /*
5636 * Should only be called while holding the tree lock.
5637 * It's added only for overriding in java.awt.Window
5638 * because parent in Window is owner.
5639 */
5640 void adjustListeningChildrenOnParent(long mask, int num) {
5641 if (parent != null) {
5642 parent.adjustListeningChildren(mask, num);
5643 }
5644 }
5645
5646 /**
5647 * Adds the specified key listener to receive key events from
5648 * this component.
5649 * If l is null, no exception is thrown and no action is performed.
5650 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5651 * >AWT Threading Issues</a> for details on AWT's threading model.
5652 *
5653 * @param l the key listener.
5654 * @see java.awt.event.KeyEvent
5655 * @see java.awt.event.KeyListener
5656 * @see #removeKeyListener
5657 * @see #getKeyListeners
5658 * @since 1.1
5659 */
5660 public synchronized void addKeyListener(KeyListener l) {
5661 if (l == null) {
5662 return;
5663 }
5664 keyListener = AWTEventMulticaster.add(keyListener, l);
5665 newEventsOnly = true;
5666
5667 // if this is a lightweight component, enable key events
5668 // in the native container.
5669 if (peer instanceof LightweightPeer) {
5670 parent.proxyEnableEvents(AWTEvent.KEY_EVENT_MASK);
5671 }
5672 }
5673
5674 /**
5675 * Removes the specified key listener so that it no longer
5676 * receives key events from this component. This method performs
5677 * no function, nor does it throw an exception, if the listener
5678 * specified by the argument was not previously added to this component.
5679 * If listener {@code l} is {@code null},
5680 * no exception is thrown and no action is performed.
5681 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5682 * >AWT Threading Issues</a> for details on AWT's threading model.
5683 *
5684 * @param l the key listener
5685 * @see java.awt.event.KeyEvent
5686 * @see java.awt.event.KeyListener
5687 * @see #addKeyListener
5688 * @see #getKeyListeners
5689 * @since 1.1
5690 */
5691 public synchronized void removeKeyListener(KeyListener l) {
5692 if (l == null) {
5693 return;
5694 }
5695 keyListener = AWTEventMulticaster.remove(keyListener, l);
5696 }
5697
5698 /**
5699 * Returns an array of all the key listeners
5700 * registered on this component.
5701 *
5702 * @return all of this component's {@code KeyListener}s
5703 * or an empty array if no key
5704 * listeners are currently registered
5705 *
5706 * @see #addKeyListener
5707 * @see #removeKeyListener
5708 * @since 1.4
5709 */
5710 public synchronized KeyListener[] getKeyListeners() {
5711 return getListeners(KeyListener.class);
5712 }
5713
5714 /**
5715 * Adds the specified mouse listener to receive mouse events from
5716 * this component.
5717 * If listener {@code l} is {@code null},
5718 * no exception is thrown and no action is performed.
5719 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5720 * >AWT Threading Issues</a> for details on AWT's threading model.
5721 *
5722 * @param l the mouse listener
5723 * @see java.awt.event.MouseEvent
5724 * @see java.awt.event.MouseListener
5725 * @see #removeMouseListener
5726 * @see #getMouseListeners
5727 * @since 1.1
5728 */
5729 public synchronized void addMouseListener(MouseListener l) {
5730 if (l == null) {
5731 return;
5732 }
5733 mouseListener = AWTEventMulticaster.add(mouseListener,l);
5734 newEventsOnly = true;
5735
5736 // if this is a lightweight component, enable mouse events
5737 // in the native container.
5738 if (peer instanceof LightweightPeer) {
5739 parent.proxyEnableEvents(AWTEvent.MOUSE_EVENT_MASK);
5740 }
5741 }
5742
5743 /**
5744 * Removes the specified mouse listener so that it no longer
5745 * receives mouse events from this component. This method performs
5746 * no function, nor does it throw an exception, if the listener
5747 * specified by the argument was not previously added to this component.
5748 * If listener {@code l} is {@code null},
5749 * no exception is thrown and no action is performed.
5750 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5751 * >AWT Threading Issues</a> for details on AWT's threading model.
5752 *
5753 * @param l the mouse listener
5754 * @see java.awt.event.MouseEvent
5755 * @see java.awt.event.MouseListener
5756 * @see #addMouseListener
5757 * @see #getMouseListeners
5758 * @since 1.1
5759 */
5760 public synchronized void removeMouseListener(MouseListener l) {
5761 if (l == null) {
5762 return;
5763 }
5764 mouseListener = AWTEventMulticaster.remove(mouseListener, l);
5765 }
5766
5767 /**
5768 * Returns an array of all the mouse listeners
5769 * registered on this component.
5770 *
5771 * @return all of this component's {@code MouseListener}s
5772 * or an empty array if no mouse
5773 * listeners are currently registered
5774 *
5775 * @see #addMouseListener
5776 * @see #removeMouseListener
5777 * @since 1.4
5778 */
5779 public synchronized MouseListener[] getMouseListeners() {
5780 return getListeners(MouseListener.class);
5781 }
5782
5783 /**
5784 * Adds the specified mouse motion listener to receive mouse motion
5785 * events from this component.
5786 * If listener {@code l} is {@code null},
5787 * no exception is thrown and no action is performed.
5788 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5789 * >AWT Threading Issues</a> for details on AWT's threading model.
5790 *
5791 * @param l the mouse motion listener
5792 * @see java.awt.event.MouseEvent
5793 * @see java.awt.event.MouseMotionListener
5794 * @see #removeMouseMotionListener
5795 * @see #getMouseMotionListeners
5796 * @since 1.1
5797 */
5798 public synchronized void addMouseMotionListener(MouseMotionListener l) {
5799 if (l == null) {
5800 return;
5801 }
5802 mouseMotionListener = AWTEventMulticaster.add(mouseMotionListener,l);
5803 newEventsOnly = true;
5804
5805 // if this is a lightweight component, enable mouse events
5806 // in the native container.
5807 if (peer instanceof LightweightPeer) {
5808 parent.proxyEnableEvents(AWTEvent.MOUSE_MOTION_EVENT_MASK);
5809 }
5810 }
5811
5812 /**
5813 * Removes the specified mouse motion listener so that it no longer
5814 * receives mouse motion events from this component. This method performs
5815 * no function, nor does it throw an exception, if the listener
5816 * specified by the argument was not previously added to this component.
5817 * If listener {@code l} is {@code null},
5818 * no exception is thrown and no action is performed.
5819 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5820 * >AWT Threading Issues</a> for details on AWT's threading model.
5821 *
5822 * @param l the mouse motion listener
5823 * @see java.awt.event.MouseEvent
5824 * @see java.awt.event.MouseMotionListener
5825 * @see #addMouseMotionListener
5826 * @see #getMouseMotionListeners
5827 * @since 1.1
5828 */
5829 public synchronized void removeMouseMotionListener(MouseMotionListener l) {
5830 if (l == null) {
5831 return;
5832 }
5833 mouseMotionListener = AWTEventMulticaster.remove(mouseMotionListener, l);
5834 }
5835
5836 /**
5837 * Returns an array of all the mouse motion listeners
5838 * registered on this component.
5839 *
5840 * @return all of this component's {@code MouseMotionListener}s
5841 * or an empty array if no mouse motion
5842 * listeners are currently registered
5843 *
5844 * @see #addMouseMotionListener
5845 * @see #removeMouseMotionListener
5846 * @since 1.4
5847 */
5848 public synchronized MouseMotionListener[] getMouseMotionListeners() {
5849 return getListeners(MouseMotionListener.class);
5850 }
5851
5852 /**
5853 * Adds the specified mouse wheel listener to receive mouse wheel events
5854 * from this component. Containers also receive mouse wheel events from
5855 * sub-components.
5856 * <p>
5857 * For information on how mouse wheel events are dispatched, see
5858 * the class description for {@link MouseWheelEvent}.
5859 * <p>
5860 * If l is {@code null}, no exception is thrown and no
5861 * action is performed.
5862 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5863 * >AWT Threading Issues</a> for details on AWT's threading model.
5864 *
5865 * @param l the mouse wheel listener
5866 * @see java.awt.event.MouseWheelEvent
5867 * @see java.awt.event.MouseWheelListener
5868 * @see #removeMouseWheelListener
5869 * @see #getMouseWheelListeners
5870 * @since 1.4
5871 */
5872 public synchronized void addMouseWheelListener(MouseWheelListener l) {
5873 if (l == null) {
5874 return;
5875 }
5876 mouseWheelListener = AWTEventMulticaster.add(mouseWheelListener,l);
5877 newEventsOnly = true;
5878
5879 // if this is a lightweight component, enable mouse events
5880 // in the native container.
5881 if (peer instanceof LightweightPeer) {
5882 parent.proxyEnableEvents(AWTEvent.MOUSE_WHEEL_EVENT_MASK);
5883 }
5884 }
5885
5886 /**
5887 * Removes the specified mouse wheel listener so that it no longer
5888 * receives mouse wheel events from this component. This method performs
5889 * no function, nor does it throw an exception, if the listener
5890 * specified by the argument was not previously added to this component.
5891 * If l is null, no exception is thrown and no action is performed.
5892 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5893 * >AWT Threading Issues</a> for details on AWT's threading model.
5894 *
5895 * @param l the mouse wheel listener.
5896 * @see java.awt.event.MouseWheelEvent
5897 * @see java.awt.event.MouseWheelListener
5898 * @see #addMouseWheelListener
5899 * @see #getMouseWheelListeners
5900 * @since 1.4
5901 */
5902 public synchronized void removeMouseWheelListener(MouseWheelListener l) {
5903 if (l == null) {
5904 return;
5905 }
5906 mouseWheelListener = AWTEventMulticaster.remove(mouseWheelListener, l);
5907 }
5908
5909 /**
5910 * Returns an array of all the mouse wheel listeners
5911 * registered on this component.
5912 *
5913 * @return all of this component's {@code MouseWheelListener}s
5914 * or an empty array if no mouse wheel
5915 * listeners are currently registered
5916 *
5917 * @see #addMouseWheelListener
5918 * @see #removeMouseWheelListener
5919 * @since 1.4
5920 */
5921 public synchronized MouseWheelListener[] getMouseWheelListeners() {
5922 return getListeners(MouseWheelListener.class);
5923 }
5924
5925 /**
5926 * Adds the specified input method listener to receive
5927 * input method events from this component. A component will
5928 * only receive input method events from input methods
5929 * if it also overrides {@code getInputMethodRequests} to return an
5930 * {@code InputMethodRequests} instance.
5931 * If listener {@code l} is {@code null},
5932 * no exception is thrown and no action is performed.
5933 * <p>Refer to <a href="{@docRoot}/java/awt/doc-files/AWTThreadIssues.html#ListenersThreads"
5934 * >AWT Threading Issues</a> for details on AWT's threading model.
5935 *
5936 * @param l the input method listener
5937 * @see java.awt.event.InputMethodEvent
5938 * @see java.awt.event.InputMethodListener
5939 * @see #removeInputMethodListener
5940 * @see #getInputMethodListeners
5941 * @see #getInputMethodRequests
5942 * @since 1.2
5943 */
5944 public synchronized void addInputMethodListener(InputMethodListener l) {
5945 if (l == null) {
5946 return;
5947 }
5948 inputMethodListener = AWTEventMulticaster.add(inputMethodListener, l);
5949 newEventsOnly = true;
5950 }
5951
5952 /**
5953 * Removes the specified input method listener so that it no longer
5954 * receives input method events from this component. This method performs
5955 * no function, nor does it throw an exception, if the listener
5956 * specified by the argument was not previously added to this component.
5957 * If listener {@code l} is {@code null},
5958 * no exception is thrown and no action is performed.
5959 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
5960 * >AWT Threading Issues</a> for details on AWT's threading model.
5961 *
5962 * @param l the input method listener
5963 * @see java.awt.event.InputMethodEvent
5964 * @see java.awt.event.InputMethodListener
5965 * @see #addInputMethodListener
5966 * @see #getInputMethodListeners
5967 * @since 1.2
5968 */
5969 public synchronized void removeInputMethodListener(InputMethodListener l) {
5970 if (l == null) {
5971 return;
5972 }
5973 inputMethodListener = AWTEventMulticaster.remove(inputMethodListener, l);
5974 }
5975
5976 /**
5977 * Returns an array of all the input method listeners
5978 * registered on this component.
5979 *
5980 * @return all of this component's {@code InputMethodListener}s
5981 * or an empty array if no input method
5982 * listeners are currently registered
5983 *
5984 * @see #addInputMethodListener
5985 * @see #removeInputMethodListener
5986 * @since 1.4
5987 */
5988 public synchronized InputMethodListener[] getInputMethodListeners() {
5989 return getListeners(InputMethodListener.class);
5990 }
5991
5992 /**
5993 * Returns an array of all the objects currently registered
5994 * as <code><em>Foo</em>Listener</code>s
5995 * upon this {@code Component}.
5996 * <code><em>Foo</em>Listener</code>s are registered using the
5997 * <code>add<em>Foo</em>Listener</code> method.
5998 *
5999 * <p>
6000 * You can specify the {@code listenerType} argument
6001 * with a class literal, such as
6002 * <code><em>Foo</em>Listener.class</code>.
6003 * For example, you can query a
6004 * {@code Component c}
6005 * for its mouse listeners with the following code:
6006 *
6007 * <pre>MouseListener[] mls = (MouseListener[])(c.getListeners(MouseListener.class));</pre>
6008 *
6009 * If no such listeners exist, this method returns an empty array.
6010 *
6011 * @param <T> the type of the listeners
6012 * @param listenerType the type of listeners requested; this parameter
6013 * should specify an interface that descends from
6014 * {@code java.util.EventListener}
6015 * @return an array of all objects registered as
6016 * <code><em>Foo</em>Listener</code>s on this component,
6017 * or an empty array if no such listeners have been added
6018 * @exception ClassCastException if {@code listenerType}
6019 * doesn't specify a class or interface that implements
6020 * {@code java.util.EventListener}
6021 * @throws NullPointerException if {@code listenerType} is {@code null}
6022 * @see #getComponentListeners
6023 * @see #getFocusListeners
6024 * @see #getHierarchyListeners
6025 * @see #getHierarchyBoundsListeners
6026 * @see #getKeyListeners
6027 * @see #getMouseListeners
6028 * @see #getMouseMotionListeners
6029 * @see #getMouseWheelListeners
6030 * @see #getInputMethodListeners
6031 * @see #getPropertyChangeListeners
6032 *
6033 * @since 1.3
6034 */
6035 @SuppressWarnings("unchecked")
6036 public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
6037 EventListener l = null;
6038 if (listenerType == ComponentListener.class) {
6039 l = componentListener;
6040 } else if (listenerType == FocusListener.class) {
6041 l = focusListener;
6042 } else if (listenerType == HierarchyListener.class) {
6043 l = hierarchyListener;
6044 } else if (listenerType == HierarchyBoundsListener.class) {
6045 l = hierarchyBoundsListener;
6046 } else if (listenerType == KeyListener.class) {
6047 l = keyListener;
6048 } else if (listenerType == MouseListener.class) {
6049 l = mouseListener;
6050 } else if (listenerType == MouseMotionListener.class) {
6051 l = mouseMotionListener;
6052 } else if (listenerType == MouseWheelListener.class) {
6053 l = mouseWheelListener;
6054 } else if (listenerType == InputMethodListener.class) {
6055 l = inputMethodListener;
6056 } else if (listenerType == PropertyChangeListener.class) {
6057 return (T[])getPropertyChangeListeners();
6058 }
6059 return AWTEventMulticaster.getListeners(l, listenerType);
6060 }
6061
6062 /**
6063 * Gets the input method request handler which supports
6064 * requests from input methods for this component. A component
6065 * that supports on-the-spot text input must override this
6066 * method to return an {@code InputMethodRequests} instance.
6067 * At the same time, it also has to handle input method events.
6068 *
6069 * @return the input method request handler for this component,
6070 * {@code null} by default
6071 * @see #addInputMethodListener
6072 * @since 1.2
6073 */
6074 public InputMethodRequests getInputMethodRequests() {
6075 return null;
6076 }
6077
6078 /**
6079 * Gets the input context used by this component for handling
6080 * the communication with input methods when text is entered
6081 * in this component. By default, the input context used for
6082 * the parent component is returned. Components may
6083 * override this to return a private input context.
6084 *
6085 * @return the input context used by this component;
6086 * {@code null} if no context can be determined
6087 * @since 1.2
6088 */
6089 public InputContext getInputContext() {
6090 Container parent = this.parent;
6091 if (parent == null) {
6092 return null;
6093 } else {
6094 return parent.getInputContext();
6095 }
6096 }
6097
6098 /**
6099 * Enables the events defined by the specified event mask parameter
6100 * to be delivered to this component.
6101 * <p>
6102 * Event types are automatically enabled when a listener for
6103 * that event type is added to the component.
6104 * <p>
6105 * This method only needs to be invoked by subclasses of
6106 * {@code Component} which desire to have the specified event
6107 * types delivered to {@code processEvent} regardless of whether
6108 * or not a listener is registered.
6109 * @param eventsToEnable the event mask defining the event types
6110 * @see #processEvent
6111 * @see #disableEvents
6112 * @see AWTEvent
6113 * @since 1.1
6114 */
6115 protected final void enableEvents(long eventsToEnable) {
6116 long notifyAncestors = 0;
6117 synchronized (this) {
6118 if ((eventsToEnable & AWTEvent.HIERARCHY_EVENT_MASK) != 0 &&
6119 hierarchyListener == null &&
6120 (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) == 0) {
6121 notifyAncestors |= AWTEvent.HIERARCHY_EVENT_MASK;
6122 }
6123 if ((eventsToEnable & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0 &&
6124 hierarchyBoundsListener == null &&
6125 (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) == 0) {
6126 notifyAncestors |= AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK;
6127 }
6128 eventMask |= eventsToEnable;
6129 newEventsOnly = true;
6130 }
6131
6132 // if this is a lightweight component, enable mouse events
6133 // in the native container.
6134 if (peer instanceof LightweightPeer) {
6135 parent.proxyEnableEvents(eventMask);
6136 }
6137 if (notifyAncestors != 0) {
6138 synchronized (getTreeLock()) {
6139 adjustListeningChildrenOnParent(notifyAncestors, 1);
6140 }
6141 }
6142 }
6143
6144 /**
6145 * Disables the events defined by the specified event mask parameter
6146 * from being delivered to this component.
6147 * @param eventsToDisable the event mask defining the event types
6148 * @see #enableEvents
6149 * @since 1.1
6150 */
6151 protected final void disableEvents(long eventsToDisable) {
6152 long notifyAncestors = 0;
6153 synchronized (this) {
6154 if ((eventsToDisable & AWTEvent.HIERARCHY_EVENT_MASK) != 0 &&
6155 hierarchyListener == null &&
6156 (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0) {
6157 notifyAncestors |= AWTEvent.HIERARCHY_EVENT_MASK;
6158 }
6159 if ((eventsToDisable & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK)!=0 &&
6160 hierarchyBoundsListener == null &&
6161 (eventMask & AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK) != 0) {
6162 notifyAncestors |= AWTEvent.HIERARCHY_BOUNDS_EVENT_MASK;
6163 }
6164 eventMask &= ~eventsToDisable;
6165 }
6166 if (notifyAncestors != 0) {
6167 synchronized (getTreeLock()) {
6168 adjustListeningChildrenOnParent(notifyAncestors, -1);
6169 }
6170 }
6171 }
6172
6173 transient sun.awt.EventQueueItem[] eventCache;
6174
6175 /**
6176 * @see #isCoalescingEnabled
6177 * @see #checkCoalescing
6178 */
6179 private transient boolean coalescingEnabled = checkCoalescing();
6180
6181 /**
6182 * Weak map of known coalesceEvent overriders.
6183 * Value indicates whether overriden.
6184 * Bootstrap classes are not included.
6185 */
6186 private static final Map<Class<?>, Boolean> coalesceMap =
6187 new java.util.WeakHashMap<Class<?>, Boolean>();
6188
6189 /**
6190 * Indicates whether this class overrides coalesceEvents.
6191 * It is assumed that all classes that are loaded from the bootstrap
6192 * do not.
6193 * The bootstrap class loader is assumed to be represented by null.
6194 * We do not check that the method really overrides
6195 * (it might be static, private or package private).
6196 */
6197 private boolean checkCoalescing() {
6198 if (getClass().getClassLoader()==null) {
6199 return false;
6200 }
6201 final Class<? extends Component> clazz = getClass();
6202 synchronized (coalesceMap) {
6203 // Check cache.
6204 Boolean value = coalesceMap.get(clazz);
6205 if (value != null) {
6206 return value;
6207 }
6208
6209 // Need to check non-bootstraps.
6210 Boolean enabled = java.security.AccessController.doPrivileged(
6211 new java.security.PrivilegedAction<Boolean>() {
6212 public Boolean run() {
6213 return isCoalesceEventsOverriden(clazz);
6214 }
6215 }
6216 );
6217 coalesceMap.put(clazz, enabled);
6218 return enabled;
6219 }
6220 }
6221
6222 /**
6223 * Parameter types of coalesceEvents(AWTEvent,AWTEVent).
6224 */
6225 private static final Class<?>[] coalesceEventsParams = {
6226 AWTEvent.class, AWTEvent.class
6227 };
6228
6229 /**
6230 * Indicates whether a class or its superclasses override coalesceEvents.
6231 * Must be called with lock on coalesceMap and privileged.
6232 * @see #checkCoalescing
6233 */
6234 private static boolean isCoalesceEventsOverriden(Class<?> clazz) {
6235 assert Thread.holdsLock(coalesceMap);
6236
6237 // First check superclass - we may not need to bother ourselves.
6238 Class<?> superclass = clazz.getSuperclass();
6239 if (superclass == null) {
6240 // Only occurs on implementations that
6241 // do not use null to represent the bootstrap class loader.
6242 return false;
6243 }
6244 if (superclass.getClassLoader() != null) {
6245 Boolean value = coalesceMap.get(superclass);
6246 if (value == null) {
6247 // Not done already - recurse.
6248 if (isCoalesceEventsOverriden(superclass)) {
6249 coalesceMap.put(superclass, true);
6250 return true;
6251 }
6252 } else if (value) {
6253 return true;
6254 }
6255 }
6256
6257 try {
6258 // Throws if not overriden.
6259 clazz.getDeclaredMethod(
6260 "coalesceEvents", coalesceEventsParams
6261 );
6262 return true;
6263 } catch (NoSuchMethodException e) {
6264 // Not present in this class.
6265 return false;
6266 }
6267 }
6268
6269 /**
6270 * Indicates whether coalesceEvents may do something.
6271 */
6272 final boolean isCoalescingEnabled() {
6273 return coalescingEnabled;
6274 }
6275
6276
6277 /**
6278 * Potentially coalesce an event being posted with an existing
6279 * event. This method is called by {@code EventQueue.postEvent}
6280 * if an event with the same ID as the event to be posted is found in
6281 * the queue (both events must have this component as their source).
6282 * This method either returns a coalesced event which replaces
6283 * the existing event (and the new event is then discarded), or
6284 * {@code null} to indicate that no combining should be done
6285 * (add the second event to the end of the queue). Either event
6286 * parameter may be modified and returned, as the other one is discarded
6287 * unless {@code null} is returned.
6288 * <p>
6289 * This implementation of {@code coalesceEvents} coalesces
6290 * two event types: mouse move (and drag) events,
6291 * and paint (and update) events.
6292 * For mouse move events the last event is always returned, causing
6293 * intermediate moves to be discarded. For paint events, the new
6294 * event is coalesced into a complex {@code RepaintArea} in the peer.
6295 * The new {@code AWTEvent} is always returned.
6296 *
6297 * @param existingEvent the event already on the {@code EventQueue}
6298 * @param newEvent the event being posted to the
6299 * {@code EventQueue}
6300 * @return a coalesced event, or {@code null} indicating that no
6301 * coalescing was done
6302 */
6303 protected AWTEvent coalesceEvents(AWTEvent existingEvent,
6304 AWTEvent newEvent) {
6305 return null;
6306 }
6307
6308 /**
6309 * Processes events occurring on this component. By default this
6310 * method calls the appropriate
6311 * <code>process<event type>Event</code>
6312 * method for the given class of event.
6313 * <p>Note that if the event parameter is {@code null}
6314 * the behavior is unspecified and may result in an
6315 * exception.
6316 *
6317 * @param e the event
6318 * @see #processComponentEvent
6319 * @see #processFocusEvent
6320 * @see #processKeyEvent
6321 * @see #processMouseEvent
6322 * @see #processMouseMotionEvent
6323 * @see #processInputMethodEvent
6324 * @see #processHierarchyEvent
6325 * @see #processMouseWheelEvent
6326 * @since 1.1
6327 */
6328 protected void processEvent(AWTEvent e) {
6329 if (e instanceof FocusEvent) {
6330 processFocusEvent((FocusEvent)e);
6331
6332 } else if (e instanceof MouseEvent) {
6333 switch(e.getID()) {
6334 case MouseEvent.MOUSE_PRESSED:
6335 case MouseEvent.MOUSE_RELEASED:
6336 case MouseEvent.MOUSE_CLICKED:
6337 case MouseEvent.MOUSE_ENTERED:
6338 case MouseEvent.MOUSE_EXITED:
6339 processMouseEvent((MouseEvent)e);
6340 break;
6341 case MouseEvent.MOUSE_MOVED:
6342 case MouseEvent.MOUSE_DRAGGED:
6343 processMouseMotionEvent((MouseEvent)e);
6344 break;
6345 case MouseEvent.MOUSE_WHEEL:
6346 processMouseWheelEvent((MouseWheelEvent)e);
6347 break;
6348 }
6349
6350 } else if (e instanceof KeyEvent) {
6351 processKeyEvent((KeyEvent)e);
6352
6353 } else if (e instanceof ComponentEvent) {
6354 processComponentEvent((ComponentEvent)e);
6355 } else if (e instanceof InputMethodEvent) {
6356 processInputMethodEvent((InputMethodEvent)e);
6357 } else if (e instanceof HierarchyEvent) {
6358 switch (e.getID()) {
6359 case HierarchyEvent.HIERARCHY_CHANGED:
6360 processHierarchyEvent((HierarchyEvent)e);
6361 break;
6362 case HierarchyEvent.ANCESTOR_MOVED:
6363 case HierarchyEvent.ANCESTOR_RESIZED:
6364 processHierarchyBoundsEvent((HierarchyEvent)e);
6365 break;
6366 }
6367 }
6368 }
6369
6370 /**
6371 * Processes component events occurring on this component by
6372 * dispatching them to any registered
6373 * {@code ComponentListener} objects.
6374 * <p>
6375 * This method is not called unless component events are
6376 * enabled for this component. Component events are enabled
6377 * when one of the following occurs:
6378 * <ul>
6379 * <li>A {@code ComponentListener} object is registered
6380 * via {@code addComponentListener}.
6381 * <li>Component events are enabled via {@code enableEvents}.
6382 * </ul>
6383 * <p>Note that if the event parameter is {@code null}
6384 * the behavior is unspecified and may result in an
6385 * exception.
6386 *
6387 * @param e the component event
6388 * @see java.awt.event.ComponentEvent
6389 * @see java.awt.event.ComponentListener
6390 * @see #addComponentListener
6391 * @see #enableEvents
6392 * @since 1.1
6393 */
6394 protected void processComponentEvent(ComponentEvent e) {
6395 ComponentListener listener = componentListener;
6396 if (listener != null) {
6397 int id = e.getID();
6398 switch(id) {
6399 case ComponentEvent.COMPONENT_RESIZED:
6400 listener.componentResized(e);
6401 break;
6402 case ComponentEvent.COMPONENT_MOVED:
6403 listener.componentMoved(e);
6404 break;
6405 case ComponentEvent.COMPONENT_SHOWN:
6406 listener.componentShown(e);
6407 break;
6408 case ComponentEvent.COMPONENT_HIDDEN:
6409 listener.componentHidden(e);
6410 break;
6411 }
6412 }
6413 }
6414
6415 /**
6416 * Processes focus events occurring on this component by
6417 * dispatching them to any registered
6418 * {@code FocusListener} objects.
6419 * <p>
6420 * This method is not called unless focus events are
6421 * enabled for this component. Focus events are enabled
6422 * when one of the following occurs:
6423 * <ul>
6424 * <li>A {@code FocusListener} object is registered
6425 * via {@code addFocusListener}.
6426 * <li>Focus events are enabled via {@code enableEvents}.
6427 * </ul>
6428 * <p>
6429 * If focus events are enabled for a {@code Component},
6430 * the current {@code KeyboardFocusManager} determines
6431 * whether or not a focus event should be dispatched to
6432 * registered {@code FocusListener} objects. If the
6433 * events are to be dispatched, the {@code KeyboardFocusManager}
6434 * calls the {@code Component}'s {@code dispatchEvent}
6435 * method, which results in a call to the {@code Component}'s
6436 * {@code processFocusEvent} method.
6437 * <p>
6438 * If focus events are enabled for a {@code Component}, calling
6439 * the {@code Component}'s {@code dispatchEvent} method
6440 * with a {@code FocusEvent} as the argument will result in a
6441 * call to the {@code Component}'s {@code processFocusEvent}
6442 * method regardless of the current {@code KeyboardFocusManager}.
6443 *
6444 * <p>Note that if the event parameter is {@code null}
6445 * the behavior is unspecified and may result in an
6446 * exception.
6447 *
6448 * @param e the focus event
6449 * @see java.awt.event.FocusEvent
6450 * @see java.awt.event.FocusListener
6451 * @see java.awt.KeyboardFocusManager
6452 * @see #addFocusListener
6453 * @see #enableEvents
6454 * @see #dispatchEvent
6455 * @since 1.1
6456 */
6457 protected void processFocusEvent(FocusEvent e) {
6458 FocusListener listener = focusListener;
6459 if (listener != null) {
6460 int id = e.getID();
6461 switch(id) {
6462 case FocusEvent.FOCUS_GAINED:
6463 listener.focusGained(e);
6464 break;
6465 case FocusEvent.FOCUS_LOST:
6466 listener.focusLost(e);
6467 break;
6468 }
6469 }
6470 }
6471
6472 /**
6473 * Processes key events occurring on this component by
6474 * dispatching them to any registered
6475 * {@code KeyListener} objects.
6476 * <p>
6477 * This method is not called unless key events are
6478 * enabled for this component. Key events are enabled
6479 * when one of the following occurs:
6480 * <ul>
6481 * <li>A {@code KeyListener} object is registered
6482 * via {@code addKeyListener}.
6483 * <li>Key events are enabled via {@code enableEvents}.
6484 * </ul>
6485 *
6486 * <p>
6487 * If key events are enabled for a {@code Component},
6488 * the current {@code KeyboardFocusManager} determines
6489 * whether or not a key event should be dispatched to
6490 * registered {@code KeyListener} objects. The
6491 * {@code DefaultKeyboardFocusManager} will not dispatch
6492 * key events to a {@code Component} that is not the focus
6493 * owner or is not showing.
6494 * <p>
6495 * As of J2SE 1.4, {@code KeyEvent}s are redirected to
6496 * the focus owner. Please see the
6497 * <a href="doc-files/FocusSpec.html">Focus Specification</a>
6498 * for further information.
6499 * <p>
6500 * Calling a {@code Component}'s {@code dispatchEvent}
6501 * method with a {@code KeyEvent} as the argument will
6502 * result in a call to the {@code Component}'s
6503 * {@code processKeyEvent} method regardless of the
6504 * current {@code KeyboardFocusManager} as long as the
6505 * component is showing, focused, and enabled, and key events
6506 * are enabled on it.
6507 * <p>If the event parameter is {@code null}
6508 * the behavior is unspecified and may result in an
6509 * exception.
6510 *
6511 * @param e the key event
6512 * @see java.awt.event.KeyEvent
6513 * @see java.awt.event.KeyListener
6514 * @see java.awt.KeyboardFocusManager
6515 * @see java.awt.DefaultKeyboardFocusManager
6516 * @see #processEvent
6517 * @see #dispatchEvent
6518 * @see #addKeyListener
6519 * @see #enableEvents
6520 * @see #isShowing
6521 * @since 1.1
6522 */
6523 protected void processKeyEvent(KeyEvent e) {
6524 KeyListener listener = keyListener;
6525 if (listener != null) {
6526 int id = e.getID();
6527 switch(id) {
6528 case KeyEvent.KEY_TYPED:
6529 listener.keyTyped(e);
6530 break;
6531 case KeyEvent.KEY_PRESSED:
6532 listener.keyPressed(e);
6533 break;
6534 case KeyEvent.KEY_RELEASED:
6535 listener.keyReleased(e);
6536 break;
6537 }
6538 }
6539 }
6540
6541 /**
6542 * Processes mouse events occurring on this component by
6543 * dispatching them to any registered
6544 * {@code MouseListener} objects.
6545 * <p>
6546 * This method is not called unless mouse events are
6547 * enabled for this component. Mouse events are enabled
6548 * when one of the following occurs:
6549 * <ul>
6550 * <li>A {@code MouseListener} object is registered
6551 * via {@code addMouseListener}.
6552 * <li>Mouse events are enabled via {@code enableEvents}.
6553 * </ul>
6554 * <p>Note that if the event parameter is {@code null}
6555 * the behavior is unspecified and may result in an
6556 * exception.
6557 *
6558 * @param e the mouse event
6559 * @see java.awt.event.MouseEvent
6560 * @see java.awt.event.MouseListener
6561 * @see #addMouseListener
6562 * @see #enableEvents
6563 * @since 1.1
6564 */
6565 protected void processMouseEvent(MouseEvent e) {
6566 MouseListener listener = mouseListener;
6567 if (listener != null) {
6568 int id = e.getID();
6569 switch(id) {
6570 case MouseEvent.MOUSE_PRESSED:
6571 listener.mousePressed(e);
6572 break;
6573 case MouseEvent.MOUSE_RELEASED:
6574 listener.mouseReleased(e);
6575 break;
6576 case MouseEvent.MOUSE_CLICKED:
6577 listener.mouseClicked(e);
6578 break;
6579 case MouseEvent.MOUSE_EXITED:
6580 listener.mouseExited(e);
6581 break;
6582 case MouseEvent.MOUSE_ENTERED:
6583 listener.mouseEntered(e);
6584 break;
6585 }
6586 }
6587 }
6588
6589 /**
6590 * Processes mouse motion events occurring on this component by
6591 * dispatching them to any registered
6592 * {@code MouseMotionListener} objects.
6593 * <p>
6594 * This method is not called unless mouse motion events are
6595 * enabled for this component. Mouse motion events are enabled
6596 * when one of the following occurs:
6597 * <ul>
6598 * <li>A {@code MouseMotionListener} object is registered
6599 * via {@code addMouseMotionListener}.
6600 * <li>Mouse motion events are enabled via {@code enableEvents}.
6601 * </ul>
6602 * <p>Note that if the event parameter is {@code null}
6603 * the behavior is unspecified and may result in an
6604 * exception.
6605 *
6606 * @param e the mouse motion event
6607 * @see java.awt.event.MouseEvent
6608 * @see java.awt.event.MouseMotionListener
6609 * @see #addMouseMotionListener
6610 * @see #enableEvents
6611 * @since 1.1
6612 */
6613 protected void processMouseMotionEvent(MouseEvent e) {
6614 MouseMotionListener listener = mouseMotionListener;
6615 if (listener != null) {
6616 int id = e.getID();
6617 switch(id) {
6618 case MouseEvent.MOUSE_MOVED:
6619 listener.mouseMoved(e);
6620 break;
6621 case MouseEvent.MOUSE_DRAGGED:
6622 listener.mouseDragged(e);
6623 break;
6624 }
6625 }
6626 }
6627
6628 /**
6629 * Processes mouse wheel events occurring on this component by
6630 * dispatching them to any registered
6631 * {@code MouseWheelListener} objects.
6632 * <p>
6633 * This method is not called unless mouse wheel events are
6634 * enabled for this component. Mouse wheel events are enabled
6635 * when one of the following occurs:
6636 * <ul>
6637 * <li>A {@code MouseWheelListener} object is registered
6638 * via {@code addMouseWheelListener}.
6639 * <li>Mouse wheel events are enabled via {@code enableEvents}.
6640 * </ul>
6641 * <p>
6642 * For information on how mouse wheel events are dispatched, see
6643 * the class description for {@link MouseWheelEvent}.
6644 * <p>
6645 * Note that if the event parameter is {@code null}
6646 * the behavior is unspecified and may result in an
6647 * exception.
6648 *
6649 * @param e the mouse wheel event
6650 * @see java.awt.event.MouseWheelEvent
6651 * @see java.awt.event.MouseWheelListener
6652 * @see #addMouseWheelListener
6653 * @see #enableEvents
6654 * @since 1.4
6655 */
6656 protected void processMouseWheelEvent(MouseWheelEvent e) {
6657 MouseWheelListener listener = mouseWheelListener;
6658 if (listener != null) {
6659 int id = e.getID();
6660 switch(id) {
6661 case MouseEvent.MOUSE_WHEEL:
6662 listener.mouseWheelMoved(e);
6663 break;
6664 }
6665 }
6666 }
6667
6668 boolean postsOldMouseEvents() {
6669 return false;
6670 }
6671
6672 /**
6673 * Processes input method events occurring on this component by
6674 * dispatching them to any registered
6675 * {@code InputMethodListener} objects.
6676 * <p>
6677 * This method is not called unless input method events
6678 * are enabled for this component. Input method events are enabled
6679 * when one of the following occurs:
6680 * <ul>
6681 * <li>An {@code InputMethodListener} object is registered
6682 * via {@code addInputMethodListener}.
6683 * <li>Input method events are enabled via {@code enableEvents}.
6684 * </ul>
6685 * <p>Note that if the event parameter is {@code null}
6686 * the behavior is unspecified and may result in an
6687 * exception.
6688 *
6689 * @param e the input method event
6690 * @see java.awt.event.InputMethodEvent
6691 * @see java.awt.event.InputMethodListener
6692 * @see #addInputMethodListener
6693 * @see #enableEvents
6694 * @since 1.2
6695 */
6696 protected void processInputMethodEvent(InputMethodEvent e) {
6697 InputMethodListener listener = inputMethodListener;
6698 if (listener != null) {
6699 int id = e.getID();
6700 switch (id) {
6701 case InputMethodEvent.INPUT_METHOD_TEXT_CHANGED:
6702 listener.inputMethodTextChanged(e);
6703 break;
6704 case InputMethodEvent.CARET_POSITION_CHANGED:
6705 listener.caretPositionChanged(e);
6706 break;
6707 }
6708 }
6709 }
6710
6711 /**
6712 * Processes hierarchy events occurring on this component by
6713 * dispatching them to any registered
6714 * {@code HierarchyListener} objects.
6715 * <p>
6716 * This method is not called unless hierarchy events
6717 * are enabled for this component. Hierarchy events are enabled
6718 * when one of the following occurs:
6719 * <ul>
6720 * <li>An {@code HierarchyListener} object is registered
6721 * via {@code addHierarchyListener}.
6722 * <li>Hierarchy events are enabled via {@code enableEvents}.
6723 * </ul>
6724 * <p>Note that if the event parameter is {@code null}
6725 * the behavior is unspecified and may result in an
6726 * exception.
6727 *
6728 * @param e the hierarchy event
6729 * @see java.awt.event.HierarchyEvent
6730 * @see java.awt.event.HierarchyListener
6731 * @see #addHierarchyListener
6732 * @see #enableEvents
6733 * @since 1.3
6734 */
6735 protected void processHierarchyEvent(HierarchyEvent e) {
6736 HierarchyListener listener = hierarchyListener;
6737 if (listener != null) {
6738 int id = e.getID();
6739 switch (id) {
6740 case HierarchyEvent.HIERARCHY_CHANGED:
6741 listener.hierarchyChanged(e);
6742 break;
6743 }
6744 }
6745 }
6746
6747 /**
6748 * Processes hierarchy bounds events occurring on this component by
6749 * dispatching them to any registered
6750 * {@code HierarchyBoundsListener} objects.
6751 * <p>
6752 * This method is not called unless hierarchy bounds events
6753 * are enabled for this component. Hierarchy bounds events are enabled
6754 * when one of the following occurs:
6755 * <ul>
6756 * <li>An {@code HierarchyBoundsListener} object is registered
6757 * via {@code addHierarchyBoundsListener}.
6758 * <li>Hierarchy bounds events are enabled via {@code enableEvents}.
6759 * </ul>
6760 * <p>Note that if the event parameter is {@code null}
6761 * the behavior is unspecified and may result in an
6762 * exception.
6763 *
6764 * @param e the hierarchy event
6765 * @see java.awt.event.HierarchyEvent
6766 * @see java.awt.event.HierarchyBoundsListener
6767 * @see #addHierarchyBoundsListener
6768 * @see #enableEvents
6769 * @since 1.3
6770 */
6771 protected void processHierarchyBoundsEvent(HierarchyEvent e) {
6772 HierarchyBoundsListener listener = hierarchyBoundsListener;
6773 if (listener != null) {
6774 int id = e.getID();
6775 switch (id) {
6776 case HierarchyEvent.ANCESTOR_MOVED:
6777 listener.ancestorMoved(e);
6778 break;
6779 case HierarchyEvent.ANCESTOR_RESIZED:
6780 listener.ancestorResized(e);
6781 break;
6782 }
6783 }
6784 }
6785
6786 /**
6787 * @param evt the event to handle
6788 * @return {@code true} if the event was handled, {@code false} otherwise
6789 * @deprecated As of JDK version 1.1
6790 * replaced by processEvent(AWTEvent).
6791 */
6792 @Deprecated
6793 public boolean handleEvent(Event evt) {
6794 switch (evt.id) {
6795 case Event.MOUSE_ENTER:
6796 return mouseEnter(evt, evt.x, evt.y);
6797
6798 case Event.MOUSE_EXIT:
6799 return mouseExit(evt, evt.x, evt.y);
6800
6801 case Event.MOUSE_MOVE:
6802 return mouseMove(evt, evt.x, evt.y);
6803
6804 case Event.MOUSE_DOWN:
6805 return mouseDown(evt, evt.x, evt.y);
6806
6807 case Event.MOUSE_DRAG:
6808 return mouseDrag(evt, evt.x, evt.y);
6809
6810 case Event.MOUSE_UP:
6811 return mouseUp(evt, evt.x, evt.y);
6812
6813 case Event.KEY_PRESS:
6814 case Event.KEY_ACTION:
6815 return keyDown(evt, evt.key);
6816
6817 case Event.KEY_RELEASE:
6818 case Event.KEY_ACTION_RELEASE:
6819 return keyUp(evt, evt.key);
6820
6821 case Event.ACTION_EVENT:
6822 return action(evt, evt.arg);
6823 case Event.GOT_FOCUS:
6824 return gotFocus(evt, evt.arg);
6825 case Event.LOST_FOCUS:
6826 return lostFocus(evt, evt.arg);
6827 }
6828 return false;
6829 }
6830
6831 /**
6832 * @param evt the event to handle
6833 * @param x the x coordinate
6834 * @param y the y coordinate
6835 * @return {@code false}
6836 * @deprecated As of JDK version 1.1,
6837 * replaced by processMouseEvent(MouseEvent).
6838 */
6839 @Deprecated
6840 public boolean mouseDown(Event evt, int x, int y) {
6841 return false;
6842 }
6843
6844 /**
6845 * @param evt the event to handle
6846 * @param x the x coordinate
6847 * @param y the y coordinate
6848 * @return {@code false}
6849 * @deprecated As of JDK version 1.1,
6850 * replaced by processMouseMotionEvent(MouseEvent).
6851 */
6852 @Deprecated
6853 public boolean mouseDrag(Event evt, int x, int y) {
6854 return false;
6855 }
6856
6857 /**
6858 * @param evt the event to handle
6859 * @param x the x coordinate
6860 * @param y the y coordinate
6861 * @return {@code false}
6862 * @deprecated As of JDK version 1.1,
6863 * replaced by processMouseEvent(MouseEvent).
6864 */
6865 @Deprecated
6866 public boolean mouseUp(Event evt, int x, int y) {
6867 return false;
6868 }
6869
6870 /**
6871 * @param evt the event to handle
6872 * @param x the x coordinate
6873 * @param y the y coordinate
6874 * @return {@code false}
6875 * @deprecated As of JDK version 1.1,
6876 * replaced by processMouseMotionEvent(MouseEvent).
6877 */
6878 @Deprecated
6879 public boolean mouseMove(Event evt, int x, int y) {
6880 return false;
6881 }
6882
6883 /**
6884 * @param evt the event to handle
6885 * @param x the x coordinate
6886 * @param y the y coordinate
6887 * @return {@code false}
6888 * @deprecated As of JDK version 1.1,
6889 * replaced by processMouseEvent(MouseEvent).
6890 */
6891 @Deprecated
6892 public boolean mouseEnter(Event evt, int x, int y) {
6893 return false;
6894 }
6895
6896 /**
6897 * @param evt the event to handle
6898 * @param x the x coordinate
6899 * @param y the y coordinate
6900 * @return {@code false}
6901 * @deprecated As of JDK version 1.1,
6902 * replaced by processMouseEvent(MouseEvent).
6903 */
6904 @Deprecated
6905 public boolean mouseExit(Event evt, int x, int y) {
6906 return false;
6907 }
6908
6909 /**
6910 * @param evt the event to handle
6911 * @param key the key pressed
6912 * @return {@code false}
6913 * @deprecated As of JDK version 1.1,
6914 * replaced by processKeyEvent(KeyEvent).
6915 */
6916 @Deprecated
6917 public boolean keyDown(Event evt, int key) {
6918 return false;
6919 }
6920
6921 /**
6922 * @param evt the event to handle
6923 * @param key the key pressed
6924 * @return {@code false}
6925 * @deprecated As of JDK version 1.1,
6926 * replaced by processKeyEvent(KeyEvent).
6927 */
6928 @Deprecated
6929 public boolean keyUp(Event evt, int key) {
6930 return false;
6931 }
6932
6933 /**
6934 * @param evt the event to handle
6935 * @param what the object acted on
6936 * @return {@code false}
6937 * @deprecated As of JDK version 1.1,
6938 * should register this component as ActionListener on component
6939 * which fires action events.
6940 */
6941 @Deprecated
6942 public boolean action(Event evt, Object what) {
6943 return false;
6944 }
6945
6946 /**
6947 * Makes this {@code Component} displayable by connecting it to a
6948 * native screen resource.
6949 * This method is called internally by the toolkit and should
6950 * not be called directly by programs.
6951 * <p>
6952 * This method changes layout-related information, and therefore,
6953 * invalidates the component hierarchy.
6954 *
6955 * @see #isDisplayable
6956 * @see #removeNotify
6957 * @see #invalidate
6958 * @since 1.0
6959 */
6960 public void addNotify() {
6961 synchronized (getTreeLock()) {
6962 ComponentPeer peer = this.peer;
6963 if (peer == null || peer instanceof LightweightPeer){
6964 if (peer == null) {
6965 // Update both the Component's peer variable and the local
6966 // variable we use for thread safety.
6967 this.peer = peer = getComponentFactory().createComponent(this);
6968 }
6969
6970 // This is a lightweight component which means it won't be
6971 // able to get window-related events by itself. If any
6972 // have been enabled, then the nearest native container must
6973 // be enabled.
6974 if (parent != null) {
6975 long mask = 0;
6976 if ((mouseListener != null) || ((eventMask & AWTEvent.MOUSE_EVENT_MASK) != 0)) {
6977 mask |= AWTEvent.MOUSE_EVENT_MASK;
6978 }
6979 if ((mouseMotionListener != null) ||
6980 ((eventMask & AWTEvent.MOUSE_MOTION_EVENT_MASK) != 0)) {
6981 mask |= AWTEvent.MOUSE_MOTION_EVENT_MASK;
6982 }
6983 if ((mouseWheelListener != null ) ||
6984 ((eventMask & AWTEvent.MOUSE_WHEEL_EVENT_MASK) != 0)) {
6985 mask |= AWTEvent.MOUSE_WHEEL_EVENT_MASK;
6986 }
6987 if (focusListener != null || (eventMask & AWTEvent.FOCUS_EVENT_MASK) != 0) {
6988 mask |= AWTEvent.FOCUS_EVENT_MASK;
6989 }
6990 if (keyListener != null || (eventMask & AWTEvent.KEY_EVENT_MASK) != 0) {
6991 mask |= AWTEvent.KEY_EVENT_MASK;
6992 }
6993 if (mask != 0) {
6994 parent.proxyEnableEvents(mask);
6995 }
6996 }
6997 } else {
6998 // It's native. If the parent is lightweight it will need some
6999 // help.
7000 Container parent = getContainer();
7001 if (parent != null && parent.isLightweight()) {
7002 relocateComponent();
7003 if (!parent.isRecursivelyVisibleUpToHeavyweightContainer())
7004 {
7005 peer.setVisible(false);
7006 }
7007 }
7008 }
7009 invalidate();
7010
7011 int npopups = (popups != null? popups.size() : 0);
7012 for (int i = 0 ; i < npopups ; i++) {
7013 PopupMenu popup = popups.elementAt(i);
7014 popup.addNotify();
7015 }
7016
7017 if (dropTarget != null) dropTarget.addNotify();
7018
7019 peerFont = getFont();
7020
7021 if (getContainer() != null && !isAddNotifyComplete) {
7022 getContainer().increaseComponentCount(this);
7023 }
7024
7025
7026 // Update stacking order
7027 updateZOrder();
7028
7029 if (!isAddNotifyComplete) {
7030 mixOnShowing();
7031 }
7032
7033 isAddNotifyComplete = true;
7034
7035 if (hierarchyListener != null ||
7036 (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0 ||
7037 Toolkit.enabledOnToolkit(AWTEvent.HIERARCHY_EVENT_MASK)) {
7038 HierarchyEvent e =
7039 new HierarchyEvent(this, HierarchyEvent.HIERARCHY_CHANGED,
7040 this, parent,
7041 HierarchyEvent.DISPLAYABILITY_CHANGED |
7042 ((isRecursivelyVisible())
7043 ? HierarchyEvent.SHOWING_CHANGED
7044 : 0));
7045 dispatchEvent(e);
7046 }
7047 }
7048 }
7049
7050 /**
7051 * Makes this {@code Component} undisplayable by destroying it native
7052 * screen resource.
7053 * <p>
7054 * This method is called by the toolkit internally and should
7055 * not be called directly by programs. Code overriding
7056 * this method should call {@code super.removeNotify} as
7057 * the first line of the overriding method.
7058 *
7059 * @see #isDisplayable
7060 * @see #addNotify
7061 * @since 1.0
7062 */
7063 public void removeNotify() {
7064 KeyboardFocusManager.clearMostRecentFocusOwner(this);
7065 if (KeyboardFocusManager.getCurrentKeyboardFocusManager().
7066 getPermanentFocusOwner() == this)
7067 {
7068 KeyboardFocusManager.getCurrentKeyboardFocusManager().
7069 setGlobalPermanentFocusOwner(null);
7070 }
7071
7072 synchronized (getTreeLock()) {
7073 if (isFocusOwner() && KeyboardFocusManager.isAutoFocusTransferEnabledFor(this)) {
7074 transferFocus(true);
7075 }
7076
7077 if (getContainer() != null && isAddNotifyComplete) {
7078 getContainer().decreaseComponentCount(this);
7079 }
7080
7081 int npopups = (popups != null? popups.size() : 0);
7082 for (int i = 0 ; i < npopups ; i++) {
7083 PopupMenu popup = popups.elementAt(i);
7084 popup.removeNotify();
7085 }
7086 // If there is any input context for this component, notify
7087 // that this component is being removed. (This has to be done
7088 // before hiding peer.)
7089 if ((eventMask & AWTEvent.INPUT_METHODS_ENABLED_MASK) != 0) {
7090 InputContext inputContext = getInputContext();
7091 if (inputContext != null) {
7092 inputContext.removeNotify(this);
7093 }
7094 }
7095
7096 ComponentPeer p = peer;
7097 if (p != null) {
7098 boolean isLightweight = isLightweight();
7099
7100 if (bufferStrategy instanceof FlipBufferStrategy) {
7101 ((FlipBufferStrategy)bufferStrategy).destroyBuffers();
7102 }
7103
7104 if (dropTarget != null) dropTarget.removeNotify();
7105
7106 // Hide peer first to stop system events such as cursor moves.
7107 if (visible) {
7108 p.setVisible(false);
7109 }
7110
7111 peer = null; // Stop peer updates.
7112 peerFont = null;
7113
7114 Toolkit.getEventQueue().removeSourceEvents(this, false);
7115 KeyboardFocusManager.getCurrentKeyboardFocusManager().
7116 discardKeyEvents(this);
7117
7118 p.dispose();
7119
7120 mixOnHiding(isLightweight);
7121
7122 isAddNotifyComplete = false;
7123 // Nullifying compoundShape means that the component has normal shape
7124 // (or has no shape at all).
7125 this.compoundShape = null;
7126 }
7127
7128 if (hierarchyListener != null ||
7129 (eventMask & AWTEvent.HIERARCHY_EVENT_MASK) != 0 ||
7130 Toolkit.enabledOnToolkit(AWTEvent.HIERARCHY_EVENT_MASK)) {
7131 HierarchyEvent e =
7132 new HierarchyEvent(this, HierarchyEvent.HIERARCHY_CHANGED,
7133 this, parent,
7134 HierarchyEvent.DISPLAYABILITY_CHANGED |
7135 ((isRecursivelyVisible())
7136 ? HierarchyEvent.SHOWING_CHANGED
7137 : 0));
7138 dispatchEvent(e);
7139 }
7140 }
7141 }
7142
7143 /**
7144 * @param evt the event to handle
7145 * @param what the object focused
7146 * @return {@code false}
7147 * @deprecated As of JDK version 1.1,
7148 * replaced by processFocusEvent(FocusEvent).
7149 */
7150 @Deprecated
7151 public boolean gotFocus(Event evt, Object what) {
7152 return false;
7153 }
7154
7155 /**
7156 * @param evt the event to handle
7157 * @param what the object focused
7158 * @return {@code false}
7159 * @deprecated As of JDK version 1.1,
7160 * replaced by processFocusEvent(FocusEvent).
7161 */
7162 @Deprecated
7163 public boolean lostFocus(Event evt, Object what) {
7164 return false;
7165 }
7166
7167 /**
7168 * Returns whether this {@code Component} can become the focus
7169 * owner.
7170 *
7171 * @return {@code true} if this {@code Component} is
7172 * focusable; {@code false} otherwise
7173 * @see #setFocusable
7174 * @since 1.1
7175 * @deprecated As of 1.4, replaced by {@code isFocusable()}.
7176 */
7177 @Deprecated
7178 public boolean isFocusTraversable() {
7179 if (isFocusTraversableOverridden == FOCUS_TRAVERSABLE_UNKNOWN) {
7180 isFocusTraversableOverridden = FOCUS_TRAVERSABLE_DEFAULT;
7181 }
7182 return focusable;
7183 }
7184
7185 /**
7186 * Returns whether this Component can be focused.
7187 *
7188 * @return {@code true} if this Component is focusable;
7189 * {@code false} otherwise.
7190 * @see #setFocusable
7191 * @since 1.4
7192 */
7193 public boolean isFocusable() {
7194 return isFocusTraversable();
7195 }
7196
7197 /**
7198 * Sets the focusable state of this Component to the specified value. This
7199 * value overrides the Component's default focusability.
7200 *
7201 * @param focusable indicates whether this Component is focusable
7202 * @see #isFocusable
7203 * @since 1.4
7204 */
7205 public void setFocusable(boolean focusable) {
7206 boolean oldFocusable;
7207 synchronized (this) {
7208 oldFocusable = this.focusable;
7209 this.focusable = focusable;
7210 }
7211 isFocusTraversableOverridden = FOCUS_TRAVERSABLE_SET;
7212
7213 firePropertyChange("focusable", oldFocusable, focusable);
7214 if (oldFocusable && !focusable) {
7215 if (isFocusOwner() && KeyboardFocusManager.isAutoFocusTransferEnabled()) {
7216 transferFocus(true);
7217 }
7218 KeyboardFocusManager.clearMostRecentFocusOwner(this);
7219 }
7220 }
7221
7222 final boolean isFocusTraversableOverridden() {
7223 return (isFocusTraversableOverridden != FOCUS_TRAVERSABLE_DEFAULT);
7224 }
7225
7226 /**
7227 * Sets the focus traversal keys for a given traversal operation for this
7228 * Component.
7229 * <p>
7230 * The default values for a Component's focus traversal keys are
7231 * implementation-dependent. Sun recommends that all implementations for a
7232 * particular native platform use the same default values. The
7233 * recommendations for Windows and Unix are listed below. These
7234 * recommendations are used in the Sun AWT implementations.
7235 *
7236 * <table class="striped">
7237 * <caption>Recommended default values for a Component's focus traversal
7238 * keys</caption>
7239 * <thead>
7240 * <tr>
7241 * <th>Identifier</th>
7242 * <th>Meaning</th>
7243 * <th>Default</th>
7244 * </tr>
7245 * </thead>
7246 * <tbody>
7247 * <tr>
7248 * <td>KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS</td>
7249 * <td>Normal forward keyboard traversal</td>
7250 * <td>TAB on KEY_PRESSED, CTRL-TAB on KEY_PRESSED</td>
7251 * </tr>
7252 * <tr>
7253 * <td>KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS</td>
7254 * <td>Normal reverse keyboard traversal</td>
7255 * <td>SHIFT-TAB on KEY_PRESSED, CTRL-SHIFT-TAB on KEY_PRESSED</td>
7256 * </tr>
7257 * <tr>
7258 * <td>KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS</td>
7259 * <td>Go up one focus traversal cycle</td>
7260 * <td>none</td>
7261 * </tr>
7262 * </tbody>
7263 * </table>
7264 *
7265 * To disable a traversal key, use an empty Set; Collections.EMPTY_SET is
7266 * recommended.
7267 * <p>
7268 * Using the AWTKeyStroke API, client code can specify on which of two
7269 * specific KeyEvents, KEY_PRESSED or KEY_RELEASED, the focus traversal
7270 * operation will occur. Regardless of which KeyEvent is specified,
7271 * however, all KeyEvents related to the focus traversal key, including the
7272 * associated KEY_TYPED event, will be consumed, and will not be dispatched
7273 * to any Component. It is a runtime error to specify a KEY_TYPED event as
7274 * mapping to a focus traversal operation, or to map the same event to
7275 * multiple default focus traversal operations.
7276 * <p>
7277 * If a value of null is specified for the Set, this Component inherits the
7278 * Set from its parent. If all ancestors of this Component have null
7279 * specified for the Set, then the current KeyboardFocusManager's default
7280 * Set is used.
7281 * <p>
7282 * This method may throw a {@code ClassCastException} if any {@code Object}
7283 * in {@code keystrokes} is not an {@code AWTKeyStroke}.
7284 *
7285 * @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
7286 * KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
7287 * KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
7288 * @param keystrokes the Set of AWTKeyStroke for the specified operation
7289 * @see #getFocusTraversalKeys
7290 * @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
7291 * @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
7292 * @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
7293 * @throws IllegalArgumentException if id is not one of
7294 * KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
7295 * KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
7296 * KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or if keystrokes
7297 * contains null, or if any keystroke represents a KEY_TYPED event,
7298 * or if any keystroke already maps to another focus traversal
7299 * operation for this Component
7300 * @since 1.4
7301 */
7302 public void setFocusTraversalKeys(int id,
7303 Set<? extends AWTKeyStroke> keystrokes)
7304 {
7305 if (id < 0 || id >= KeyboardFocusManager.TRAVERSAL_KEY_LENGTH - 1) {
7306 throw new IllegalArgumentException("invalid focus traversal key identifier");
7307 }
7308
7309 setFocusTraversalKeys_NoIDCheck(id, keystrokes);
7310 }
7311
7312 /**
7313 * Returns the Set of focus traversal keys for a given traversal operation
7314 * for this Component. (See
7315 * {@code setFocusTraversalKeys} for a full description of each key.)
7316 * <p>
7317 * If a Set of traversal keys has not been explicitly defined for this
7318 * Component, then this Component's parent's Set is returned. If no Set
7319 * has been explicitly defined for any of this Component's ancestors, then
7320 * the current KeyboardFocusManager's default Set is returned.
7321 *
7322 * @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
7323 * KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
7324 * KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
7325 * @return the Set of AWTKeyStrokes for the specified operation. The Set
7326 * will be unmodifiable, and may be empty. null will never be
7327 * returned.
7328 * @see #setFocusTraversalKeys
7329 * @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
7330 * @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
7331 * @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
7332 * @throws IllegalArgumentException if id is not one of
7333 * KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
7334 * KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
7335 * KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
7336 * @since 1.4
7337 */
7338 public Set<AWTKeyStroke> getFocusTraversalKeys(int id) {
7339 if (id < 0 || id >= KeyboardFocusManager.TRAVERSAL_KEY_LENGTH - 1) {
7340 throw new IllegalArgumentException("invalid focus traversal key identifier");
7341 }
7342
7343 return getFocusTraversalKeys_NoIDCheck(id);
7344 }
7345
7346 // We define these methods so that Container does not need to repeat this
7347 // code. Container cannot call super.<method> because Container allows
7348 // DOWN_CYCLE_TRAVERSAL_KEY while Component does not. The Component method
7349 // would erroneously generate an IllegalArgumentException for
7350 // DOWN_CYCLE_TRAVERSAL_KEY.
7351 final void setFocusTraversalKeys_NoIDCheck(int id, Set<? extends AWTKeyStroke> keystrokes) {
7352 Set<AWTKeyStroke> oldKeys;
7353
7354 synchronized (this) {
7355 if (focusTraversalKeys == null) {
7356 initializeFocusTraversalKeys();
7357 }
7358
7359 if (keystrokes != null) {
7360 for (AWTKeyStroke keystroke : keystrokes ) {
7361
7362 if (keystroke == null) {
7363 throw new IllegalArgumentException("cannot set null focus traversal key");
7364 }
7365
7366 if (keystroke.getKeyChar() != KeyEvent.CHAR_UNDEFINED) {
7367 throw new IllegalArgumentException("focus traversal keys cannot map to KEY_TYPED events");
7368 }
7369
7370 for (int i = 0; i < focusTraversalKeys.length; i++) {
7371 if (i == id) {
7372 continue;
7373 }
7374
7375 if (getFocusTraversalKeys_NoIDCheck(i).contains(keystroke))
7376 {
7377 throw new IllegalArgumentException("focus traversal keys must be unique for a Component");
7378 }
7379 }
7380 }
7381 }
7382
7383 oldKeys = focusTraversalKeys[id];
7384 focusTraversalKeys[id] = (keystrokes != null)
7385 ? Collections.unmodifiableSet(new HashSet<AWTKeyStroke>(keystrokes))
7386 : null;
7387 }
7388
7389 firePropertyChange(focusTraversalKeyPropertyNames[id], oldKeys,
7390 keystrokes);
7391 }
7392 final Set<AWTKeyStroke> getFocusTraversalKeys_NoIDCheck(int id) {
7393 // Okay to return Set directly because it is an unmodifiable view
7394 @SuppressWarnings("unchecked")
7395 Set<AWTKeyStroke> keystrokes = (focusTraversalKeys != null)
7396 ? focusTraversalKeys[id]
7397 : null;
7398
7399 if (keystrokes != null) {
7400 return keystrokes;
7401 } else {
7402 Container parent = this.parent;
7403 if (parent != null) {
7404 return parent.getFocusTraversalKeys(id);
7405 } else {
7406 return KeyboardFocusManager.getCurrentKeyboardFocusManager().
7407 getDefaultFocusTraversalKeys(id);
7408 }
7409 }
7410 }
7411
7412 /**
7413 * Returns whether the Set of focus traversal keys for the given focus
7414 * traversal operation has been explicitly defined for this Component. If
7415 * this method returns {@code false}, this Component is inheriting the
7416 * Set from an ancestor, or from the current KeyboardFocusManager.
7417 *
7418 * @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
7419 * KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
7420 * KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
7421 * @return {@code true} if the Set of focus traversal keys for the
7422 * given focus traversal operation has been explicitly defined for
7423 * this Component; {@code false} otherwise.
7424 * @throws IllegalArgumentException if id is not one of
7425 * KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
7426 * KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or
7427 * KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
7428 * @since 1.4
7429 */
7430 public boolean areFocusTraversalKeysSet(int id) {
7431 if (id < 0 || id >= KeyboardFocusManager.TRAVERSAL_KEY_LENGTH - 1) {
7432 throw new IllegalArgumentException("invalid focus traversal key identifier");
7433 }
7434
7435 return (focusTraversalKeys != null && focusTraversalKeys[id] != null);
7436 }
7437
7438 /**
7439 * Sets whether focus traversal keys are enabled for this Component.
7440 * Components for which focus traversal keys are disabled receive key
7441 * events for focus traversal keys. Components for which focus traversal
7442 * keys are enabled do not see these events; instead, the events are
7443 * automatically converted to traversal operations.
7444 *
7445 * @param focusTraversalKeysEnabled whether focus traversal keys are
7446 * enabled for this Component
7447 * @see #getFocusTraversalKeysEnabled
7448 * @see #setFocusTraversalKeys
7449 * @see #getFocusTraversalKeys
7450 * @since 1.4
7451 */
7452 public void setFocusTraversalKeysEnabled(boolean
7453 focusTraversalKeysEnabled) {
7454 boolean oldFocusTraversalKeysEnabled;
7455 synchronized (this) {
7456 oldFocusTraversalKeysEnabled = this.focusTraversalKeysEnabled;
7457 this.focusTraversalKeysEnabled = focusTraversalKeysEnabled;
7458 }
7459 firePropertyChange("focusTraversalKeysEnabled",
7460 oldFocusTraversalKeysEnabled,
7461 focusTraversalKeysEnabled);
7462 }
7463
7464 /**
7465 * Returns whether focus traversal keys are enabled for this Component.
7466 * Components for which focus traversal keys are disabled receive key
7467 * events for focus traversal keys. Components for which focus traversal
7468 * keys are enabled do not see these events; instead, the events are
7469 * automatically converted to traversal operations.
7470 *
7471 * @return whether focus traversal keys are enabled for this Component
7472 * @see #setFocusTraversalKeysEnabled
7473 * @see #setFocusTraversalKeys
7474 * @see #getFocusTraversalKeys
7475 * @since 1.4
7476 */
7477 public boolean getFocusTraversalKeysEnabled() {
7478 return focusTraversalKeysEnabled;
7479 }
7480
7481 /**
7482 * Requests that this Component get the input focus, and that this
7483 * Component's top-level ancestor become the focused Window. This
7484 * component must be displayable, focusable, visible and all of
7485 * its ancestors (with the exception of the top-level Window) must
7486 * be visible for the request to be granted. Every effort will be
7487 * made to honor the request; however, in some cases it may be
7488 * impossible to do so. Developers must never assume that this
7489 * Component is the focus owner until this Component receives a
7490 * FOCUS_GAINED event. If this request is denied because this
7491 * Component's top-level Window cannot become the focused Window,
7492 * the request will be remembered and will be granted when the
7493 * Window is later focused by the user.
7494 * <p>
7495 * This method cannot be used to set the focus owner to no Component at
7496 * all. Use {@code KeyboardFocusManager.clearGlobalFocusOwner()}
7497 * instead.
7498 * <p>
7499 * Because the focus behavior of this method is platform-dependent,
7500 * developers are strongly encouraged to use
7501 * {@code requestFocusInWindow} when possible.
7502 *
7503 * <p>Note: Not all focus transfers result from invoking this method. As
7504 * such, a component may receive focus without this or any of the other
7505 * {@code requestFocus} methods of {@code Component} being invoked.
7506 *
7507 * @see #requestFocusInWindow
7508 * @see java.awt.event.FocusEvent
7509 * @see #addFocusListener
7510 * @see #isFocusable
7511 * @see #isDisplayable
7512 * @see KeyboardFocusManager#clearGlobalFocusOwner
7513 * @since 1.0
7514 */
7515 public void requestFocus() {
7516 requestFocusHelper(false, true);
7517 }
7518
7519
7520 /**
7521 * Requests by the reason of {@code cause} that this Component get the input
7522 * focus, and that this Component's top-level ancestor become the
7523 * focused Window. This component must be displayable, focusable, visible
7524 * and all of its ancestors (with the exception of the top-level Window)
7525 * must be visible for the request to be granted. Every effort will be
7526 * made to honor the request; however, in some cases it may be
7527 * impossible to do so. Developers must never assume that this
7528 * Component is the focus owner until this Component receives a
7529 * FOCUS_GAINED event.
7530 * <p>
7531 * The focus request effect may also depend on the provided
7532 * cause value. If this request is succeed the {@code FocusEvent}
7533 * generated in the result will receive the cause value specified as the
7534 * argument of method. If this request is denied because this Component's
7535 * top-level Window cannot become the focused Window, the request will be
7536 * remembered and will be granted when the Window is later focused by the
7537 * user.
7538 * <p>
7539 * This method cannot be used to set the focus owner to no Component at
7540 * all. Use {@code KeyboardFocusManager.clearGlobalFocusOwner()}
7541 * instead.
7542 * <p>
7543 * Because the focus behavior of this method is platform-dependent,
7544 * developers are strongly encouraged to use
7545 * {@code requestFocusInWindow(FocusEvent.Cause)} when possible.
7546 *
7547 * <p>Note: Not all focus transfers result from invoking this method. As
7548 * such, a component may receive focus without this or any of the other
7549 * {@code requestFocus} methods of {@code Component} being invoked.
7550 *
7551 * @param cause the cause why the focus is requested
7552 * @see FocusEvent
7553 * @see FocusEvent.Cause
7554 * @see #requestFocusInWindow(FocusEvent.Cause)
7555 * @see java.awt.event.FocusEvent
7556 * @see #addFocusListener
7557 * @see #isFocusable
7558 * @see #isDisplayable
7559 * @see KeyboardFocusManager#clearGlobalFocusOwner
7560 * @since 9
7561 */
7562 public void requestFocus(FocusEvent.Cause cause) {
7563 requestFocusHelper(false, true, cause);
7564 }
7565
7566 /**
7567 * Requests that this {@code Component} get the input focus,
7568 * and that this {@code Component}'s top-level ancestor
7569 * become the focused {@code Window}. This component must be
7570 * displayable, focusable, visible and all of its ancestors (with
7571 * the exception of the top-level Window) must be visible for the
7572 * request to be granted. Every effort will be made to honor the
7573 * request; however, in some cases it may be impossible to do
7574 * so. Developers must never assume that this component is the
7575 * focus owner until this component receives a FOCUS_GAINED
7576 * event. If this request is denied because this component's
7577 * top-level window cannot become the focused window, the request
7578 * will be remembered and will be granted when the window is later
7579 * focused by the user.
7580 * <p>
7581 * This method returns a boolean value. If {@code false} is returned,
7582 * the request is <b>guaranteed to fail</b>. If {@code true} is
7583 * returned, the request will succeed <b>unless</b> it is vetoed, or an
7584 * extraordinary event, such as disposal of the component's peer, occurs
7585 * before the request can be granted by the native windowing system. Again,
7586 * while a return value of {@code true} indicates that the request is
7587 * likely to succeed, developers must never assume that this component is
7588 * the focus owner until this component receives a FOCUS_GAINED event.
7589 * <p>
7590 * This method cannot be used to set the focus owner to no component at
7591 * all. Use {@code KeyboardFocusManager.clearGlobalFocusOwner}
7592 * instead.
7593 * <p>
7594 * Because the focus behavior of this method is platform-dependent,
7595 * developers are strongly encouraged to use
7596 * {@code requestFocusInWindow} when possible.
7597 * <p>
7598 * Every effort will be made to ensure that {@code FocusEvent}s
7599 * generated as a
7600 * result of this request will have the specified temporary value. However,
7601 * because specifying an arbitrary temporary state may not be implementable
7602 * on all native windowing systems, correct behavior for this method can be
7603 * guaranteed only for lightweight {@code Component}s.
7604 * This method is not intended
7605 * for general use, but exists instead as a hook for lightweight component
7606 * libraries, such as Swing.
7607 *
7608 * <p>Note: Not all focus transfers result from invoking this method. As
7609 * such, a component may receive focus without this or any of the other
7610 * {@code requestFocus} methods of {@code Component} being invoked.
7611 *
7612 * @param temporary true if the focus change is temporary,
7613 * such as when the window loses the focus; for
7614 * more information on temporary focus changes see the
7615 *<a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
7616 * @return {@code false} if the focus change request is guaranteed to
7617 * fail; {@code true} if it is likely to succeed
7618 * @see java.awt.event.FocusEvent
7619 * @see #addFocusListener
7620 * @see #isFocusable
7621 * @see #isDisplayable
7622 * @see KeyboardFocusManager#clearGlobalFocusOwner
7623 * @since 1.4
7624 */
7625 protected boolean requestFocus(boolean temporary) {
7626 return requestFocusHelper(temporary, true);
7627 }
7628
7629 /**
7630 * Requests by the reason of {@code cause} that this {@code Component} get
7631 * the input focus, and that this {@code Component}'s top-level ancestor
7632 * become the focused {@code Window}. This component must be
7633 * displayable, focusable, visible and all of its ancestors (with
7634 * the exception of the top-level Window) must be visible for the
7635 * request to be granted. Every effort will be made to honor the
7636 * request; however, in some cases it may be impossible to do
7637 * so. Developers must never assume that this component is the
7638 * focus owner until this component receives a FOCUS_GAINED
7639 * event. If this request is denied because this component's
7640 * top-level window cannot become the focused window, the request
7641 * will be remembered and will be granted when the window is later
7642 * focused by the user.
7643 * <p>
7644 * This method returns a boolean value. If {@code false} is returned,
7645 * the request is <b>guaranteed to fail</b>. If {@code true} is
7646 * returned, the request will succeed <b>unless</b> it is vetoed, or an
7647 * extraordinary event, such as disposal of the component's peer, occurs
7648 * before the request can be granted by the native windowing system. Again,
7649 * while a return value of {@code true} indicates that the request is
7650 * likely to succeed, developers must never assume that this component is
7651 * the focus owner until this component receives a FOCUS_GAINED event.
7652 * <p>
7653 * The focus request effect may also depend on the provided
7654 * cause value. If this request is succeed the {FocusEvent}
7655 * generated in the result will receive the cause value specified as the
7656 * argument of the method.
7657 * <p>
7658 * This method cannot be used to set the focus owner to no component at
7659 * all. Use {@code KeyboardFocusManager.clearGlobalFocusOwner}
7660 * instead.
7661 * <p>
7662 * Because the focus behavior of this method is platform-dependent,
7663 * developers are strongly encouraged to use
7664 * {@code requestFocusInWindow} when possible.
7665 * <p>
7666 * Every effort will be made to ensure that {@code FocusEvent}s
7667 * generated as a
7668 * result of this request will have the specified temporary value. However,
7669 * because specifying an arbitrary temporary state may not be implementable
7670 * on all native windowing systems, correct behavior for this method can be
7671 * guaranteed only for lightweight {@code Component}s.
7672 * This method is not intended
7673 * for general use, but exists instead as a hook for lightweight component
7674 * libraries, such as Swing.
7675 * <p>
7676 * Note: Not all focus transfers result from invoking this method. As
7677 * such, a component may receive focus without this or any of the other
7678 * {@code requestFocus} methods of {@code Component} being invoked.
7679 *
7680 * @param temporary true if the focus change is temporary,
7681 * such as when the window loses the focus; for
7682 * more information on temporary focus changes see the
7683 *<a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
7684 *
7685 * @param cause the cause why the focus is requested
7686 * @return {@code false} if the focus change request is guaranteed to
7687 * fail; {@code true} if it is likely to succeed
7688 * @see FocusEvent
7689 * @see FocusEvent.Cause
7690 * @see #addFocusListener
7691 * @see #isFocusable
7692 * @see #isDisplayable
7693 * @see KeyboardFocusManager#clearGlobalFocusOwner
7694 * @since 9
7695 */
7696 protected boolean requestFocus(boolean temporary, FocusEvent.Cause cause) {
7697 return requestFocusHelper(temporary, true, cause);
7698 }
7699
7700 /**
7701 * Requests that this Component get the input focus, if this
7702 * Component's top-level ancestor is already the focused
7703 * Window. This component must be displayable, focusable, visible
7704 * and all of its ancestors (with the exception of the top-level
7705 * Window) must be visible for the request to be granted. Every
7706 * effort will be made to honor the request; however, in some
7707 * cases it may be impossible to do so. Developers must never
7708 * assume that this Component is the focus owner until this
7709 * Component receives a FOCUS_GAINED event.
7710 * <p>
7711 * This method returns a boolean value. If {@code false} is returned,
7712 * the request is <b>guaranteed to fail</b>. If {@code true} is
7713 * returned, the request will succeed <b>unless</b> it is vetoed, or an
7714 * extraordinary event, such as disposal of the Component's peer, occurs
7715 * before the request can be granted by the native windowing system. Again,
7716 * while a return value of {@code true} indicates that the request is
7717 * likely to succeed, developers must never assume that this Component is
7718 * the focus owner until this Component receives a FOCUS_GAINED event.
7719 * <p>
7720 * This method cannot be used to set the focus owner to no Component at
7721 * all. Use {@code KeyboardFocusManager.clearGlobalFocusOwner()}
7722 * instead.
7723 * <p>
7724 * The focus behavior of this method can be implemented uniformly across
7725 * platforms, and thus developers are strongly encouraged to use this
7726 * method over {@code requestFocus} when possible. Code which relies
7727 * on {@code requestFocus} may exhibit different focus behavior on
7728 * different platforms.
7729 *
7730 * <p>Note: Not all focus transfers result from invoking this method. As
7731 * such, a component may receive focus without this or any of the other
7732 * {@code requestFocus} methods of {@code Component} being invoked.
7733 *
7734 * @return {@code false} if the focus change request is guaranteed to
7735 * fail; {@code true} if it is likely to succeed
7736 * @see #requestFocus
7737 * @see java.awt.event.FocusEvent
7738 * @see #addFocusListener
7739 * @see #isFocusable
7740 * @see #isDisplayable
7741 * @see KeyboardFocusManager#clearGlobalFocusOwner
7742 * @since 1.4
7743 */
7744 public boolean requestFocusInWindow() {
7745 return requestFocusHelper(false, false);
7746 }
7747
7748 /**
7749 * Requests by the reason of {@code cause} that this Component get the input
7750 * focus, if this Component's top-level ancestor is already the focused
7751 * Window. This component must be displayable, focusable, visible
7752 * and all of its ancestors (with the exception of the top-level
7753 * Window) must be visible for the request to be granted. Every
7754 * effort will be made to honor the request; however, in some
7755 * cases it may be impossible to do so. Developers must never
7756 * assume that this Component is the focus owner until this
7757 * Component receives a FOCUS_GAINED event.
7758 * <p>
7759 * This method returns a boolean value. If {@code false} is returned,
7760 * the request is <b>guaranteed to fail</b>. If {@code true} is
7761 * returned, the request will succeed <b>unless</b> it is vetoed, or an
7762 * extraordinary event, such as disposal of the Component's peer, occurs
7763 * before the request can be granted by the native windowing system. Again,
7764 * while a return value of {@code true} indicates that the request is
7765 * likely to succeed, developers must never assume that this Component is
7766 * the focus owner until this Component receives a FOCUS_GAINED event.
7767 * <p>
7768 * The focus request effect may also depend on the provided
7769 * cause value. If this request is succeed the {@code FocusEvent}
7770 * generated in the result will receive the cause value specified as the
7771 * argument of the method.
7772 * <p>
7773 * This method cannot be used to set the focus owner to no Component at
7774 * all. Use {@code KeyboardFocusManager.clearGlobalFocusOwner()}
7775 * instead.
7776 * <p>
7777 * The focus behavior of this method can be implemented uniformly across
7778 * platforms, and thus developers are strongly encouraged to use this
7779 * method over {@code requestFocus(FocusEvent.Cause)} when possible.
7780 * Code which relies on {@code requestFocus(FocusEvent.Cause)} may exhibit
7781 * different focus behavior on different platforms.
7782 *
7783 * <p>Note: Not all focus transfers result from invoking this method. As
7784 * such, a component may receive focus without this or any of the other
7785 * {@code requestFocus} methods of {@code Component} being invoked.
7786 *
7787 * @param cause the cause why the focus is requested
7788 * @return {@code false} if the focus change request is guaranteed to
7789 * fail; {@code true} if it is likely to succeed
7790 * @see #requestFocus(FocusEvent.Cause)
7791 * @see FocusEvent
7792 * @see FocusEvent.Cause
7793 * @see java.awt.event.FocusEvent
7794 * @see #addFocusListener
7795 * @see #isFocusable
7796 * @see #isDisplayable
7797 * @see KeyboardFocusManager#clearGlobalFocusOwner
7798 * @since 9
7799 */
7800 public boolean requestFocusInWindow(FocusEvent.Cause cause) {
7801 return requestFocusHelper(false, false, cause);
7802 }
7803
7804 /**
7805 * Requests that this {@code Component} get the input focus,
7806 * if this {@code Component}'s top-level ancestor is already
7807 * the focused {@code Window}. This component must be
7808 * displayable, focusable, visible and all of its ancestors (with
7809 * the exception of the top-level Window) must be visible for the
7810 * request to be granted. Every effort will be made to honor the
7811 * request; however, in some cases it may be impossible to do
7812 * so. Developers must never assume that this component is the
7813 * focus owner until this component receives a FOCUS_GAINED event.
7814 * <p>
7815 * This method returns a boolean value. If {@code false} is returned,
7816 * the request is <b>guaranteed to fail</b>. If {@code true} is
7817 * returned, the request will succeed <b>unless</b> it is vetoed, or an
7818 * extraordinary event, such as disposal of the component's peer, occurs
7819 * before the request can be granted by the native windowing system. Again,
7820 * while a return value of {@code true} indicates that the request is
7821 * likely to succeed, developers must never assume that this component is
7822 * the focus owner until this component receives a FOCUS_GAINED event.
7823 * <p>
7824 * This method cannot be used to set the focus owner to no component at
7825 * all. Use {@code KeyboardFocusManager.clearGlobalFocusOwner}
7826 * instead.
7827 * <p>
7828 * The focus behavior of this method can be implemented uniformly across
7829 * platforms, and thus developers are strongly encouraged to use this
7830 * method over {@code requestFocus} when possible. Code which relies
7831 * on {@code requestFocus} may exhibit different focus behavior on
7832 * different platforms.
7833 * <p>
7834 * Every effort will be made to ensure that {@code FocusEvent}s
7835 * generated as a
7836 * result of this request will have the specified temporary value. However,
7837 * because specifying an arbitrary temporary state may not be implementable
7838 * on all native windowing systems, correct behavior for this method can be
7839 * guaranteed only for lightweight components. This method is not intended
7840 * for general use, but exists instead as a hook for lightweight component
7841 * libraries, such as Swing.
7842 *
7843 * <p>Note: Not all focus transfers result from invoking this method. As
7844 * such, a component may receive focus without this or any of the other
7845 * {@code requestFocus} methods of {@code Component} being invoked.
7846 *
7847 * @param temporary true if the focus change is temporary,
7848 * such as when the window loses the focus; for
7849 * more information on temporary focus changes see the
7850 *<a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
7851 * @return {@code false} if the focus change request is guaranteed to
7852 * fail; {@code true} if it is likely to succeed
7853 * @see #requestFocus
7854 * @see java.awt.event.FocusEvent
7855 * @see #addFocusListener
7856 * @see #isFocusable
7857 * @see #isDisplayable
7858 * @see KeyboardFocusManager#clearGlobalFocusOwner
7859 * @since 1.4
7860 */
7861 protected boolean requestFocusInWindow(boolean temporary) {
7862 return requestFocusHelper(temporary, false);
7863 }
7864
7865 boolean requestFocusInWindow(boolean temporary, FocusEvent.Cause cause) {
7866 return requestFocusHelper(temporary, false, cause);
7867 }
7868
7869 final boolean requestFocusHelper(boolean temporary,
7870 boolean focusedWindowChangeAllowed) {
7871 return requestFocusHelper(temporary, focusedWindowChangeAllowed, FocusEvent.Cause.UNKNOWN);
7872 }
7873
7874 final boolean requestFocusHelper(boolean temporary,
7875 boolean focusedWindowChangeAllowed,
7876 FocusEvent.Cause cause)
7877 {
7878 // 1) Check if the event being dispatched is a system-generated mouse event.
7879 AWTEvent currentEvent = EventQueue.getCurrentEvent();
7880 if (currentEvent instanceof MouseEvent &&
7881 SunToolkit.isSystemGenerated(currentEvent))
7882 {
7883 // 2) Sanity check: if the mouse event component source belongs to the same containing window.
7884 Component source = ((MouseEvent)currentEvent).getComponent();
7885 if (source == null || source.getContainingWindow() == getContainingWindow()) {
7886 focusLog.finest("requesting focus by mouse event \"in window\"");
7887
7888 // If both the conditions are fulfilled the focus request should be strictly
7889 // bounded by the toplevel window. It's assumed that the mouse event activates
7890 // the window (if it wasn't active) and this makes it possible for a focus
7891 // request with a strong in-window requirement to change focus in the bounds
7892 // of the toplevel. If, by any means, due to asynchronous nature of the event
7893 // dispatching mechanism, the window happens to be natively inactive by the time
7894 // this focus request is eventually handled, it should not re-activate the
7895 // toplevel. Otherwise the result may not meet user expectations. See 6981400.
7896 focusedWindowChangeAllowed = false;
7897 }
7898 }
7899 if (!isRequestFocusAccepted(temporary, focusedWindowChangeAllowed, cause)) {
7900 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7901 focusLog.finest("requestFocus is not accepted");
7902 }
7903 return false;
7904 }
7905 // Update most-recent map
7906 KeyboardFocusManager.setMostRecentFocusOwner(this);
7907
7908 Component window = this;
7909 while ( (window != null) && !(window instanceof Window)) {
7910 if (!window.isVisible()) {
7911 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7912 focusLog.finest("component is recursively invisible");
7913 }
7914 return false;
7915 }
7916 window = window.parent;
7917 }
7918
7919 ComponentPeer peer = this.peer;
7920 Component heavyweight = (peer instanceof LightweightPeer)
7921 ? getNativeContainer() : this;
7922 if (heavyweight == null || !heavyweight.isVisible()) {
7923 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7924 focusLog.finest("Component is not a part of visible hierarchy");
7925 }
7926 return false;
7927 }
7928 peer = heavyweight.peer;
7929 if (peer == null) {
7930 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7931 focusLog.finest("Peer is null");
7932 }
7933 return false;
7934 }
7935
7936 // Focus this Component
7937 long time = 0;
7938 if (EventQueue.isDispatchThread()) {
7939 time = Toolkit.getEventQueue().getMostRecentKeyEventTime();
7940 } else {
7941 // A focus request made from outside EDT should not be associated with any event
7942 // and so its time stamp is simply set to the current time.
7943 time = System.currentTimeMillis();
7944 }
7945
7946 boolean success = peer.requestFocus
7947 (this, temporary, focusedWindowChangeAllowed, time, cause);
7948 if (!success) {
7949 KeyboardFocusManager.getCurrentKeyboardFocusManager
7950 (appContext).dequeueKeyEvents(time, this);
7951 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7952 focusLog.finest("Peer request failed");
7953 }
7954 } else {
7955 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7956 focusLog.finest("Pass for " + this);
7957 }
7958 }
7959 return success;
7960 }
7961
7962 private boolean isRequestFocusAccepted(boolean temporary,
7963 boolean focusedWindowChangeAllowed,
7964 FocusEvent.Cause cause)
7965 {
7966 if (!isFocusable() || !isVisible()) {
7967 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7968 focusLog.finest("Not focusable or not visible");
7969 }
7970 return false;
7971 }
7972
7973 ComponentPeer peer = this.peer;
7974 if (peer == null) {
7975 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7976 focusLog.finest("peer is null");
7977 }
7978 return false;
7979 }
7980
7981 Window window = getContainingWindow();
7982 if (window == null || !window.isFocusableWindow()) {
7983 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
7984 focusLog.finest("Component doesn't have toplevel");
7985 }
7986 return false;
7987 }
7988
7989 // We have passed all regular checks for focus request,
7990 // now let's call RequestFocusController and see what it says.
7991 Component focusOwner = KeyboardFocusManager.getMostRecentFocusOwner(window);
7992 if (focusOwner == null) {
7993 // sometimes most recent focus owner may be null, but focus owner is not
7994 // e.g. we reset most recent focus owner if user removes focus owner
7995 focusOwner = KeyboardFocusManager.getCurrentKeyboardFocusManager().getFocusOwner();
7996 if (focusOwner != null && focusOwner.getContainingWindow() != window) {
7997 focusOwner = null;
7998 }
7999 }
8000
8001 if (focusOwner == this || focusOwner == null) {
8002 // Controller is supposed to verify focus transfers and for this it
8003 // should know both from and to components. And it shouldn't verify
8004 // transfers from when these components are equal.
8005 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
8006 focusLog.finest("focus owner is null or this");
8007 }
8008 return true;
8009 }
8010
8011 if (FocusEvent.Cause.ACTIVATION == cause) {
8012 // we shouldn't call RequestFocusController in case we are
8013 // in activation. We do request focus on component which
8014 // has got temporary focus lost and then on component which is
8015 // most recent focus owner. But most recent focus owner can be
8016 // changed by requestFocusXXX() call only, so this transfer has
8017 // been already approved.
8018 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
8019 focusLog.finest("cause is activation");
8020 }
8021 return true;
8022 }
8023
8024 boolean ret = Component.requestFocusController.acceptRequestFocus(focusOwner,
8025 this,
8026 temporary,
8027 focusedWindowChangeAllowed,
8028 cause);
8029 if (focusLog.isLoggable(PlatformLogger.Level.FINEST)) {
8030 focusLog.finest("RequestFocusController returns {0}", ret);
8031 }
8032
8033 return ret;
8034 }
8035
8036 private static RequestFocusController requestFocusController = new DummyRequestFocusController();
8037
8038 // Swing access this method through reflection to implement InputVerifier's functionality.
8039 // Perhaps, we should make this method public (later ;)
8040 private static class DummyRequestFocusController implements RequestFocusController {
8041 public boolean acceptRequestFocus(Component from, Component to,
8042 boolean temporary, boolean focusedWindowChangeAllowed,
8043 FocusEvent.Cause cause)
8044 {
8045 return true;
8046 }
8047 };
8048
8049 static synchronized void setRequestFocusController(RequestFocusController requestController)
8050 {
8051 if (requestController == null) {
8052 requestFocusController = new DummyRequestFocusController();
8053 } else {
8054 requestFocusController = requestController;
8055 }
8056 }
8057
8058 /**
8059 * Returns the Container which is the focus cycle root of this Component's
8060 * focus traversal cycle. Each focus traversal cycle has only a single
8061 * focus cycle root and each Component which is not a Container belongs to
8062 * only a single focus traversal cycle. Containers which are focus cycle
8063 * roots belong to two cycles: one rooted at the Container itself, and one
8064 * rooted at the Container's nearest focus-cycle-root ancestor. For such
8065 * Containers, this method will return the Container's nearest focus-cycle-
8066 * root ancestor.
8067 *
8068 * @return this Component's nearest focus-cycle-root ancestor
8069 * @see Container#isFocusCycleRoot()
8070 * @since 1.4
8071 */
8072 public Container getFocusCycleRootAncestor() {
8073 Container rootAncestor = this.parent;
8074 while (rootAncestor != null && !rootAncestor.isFocusCycleRoot()) {
8075 rootAncestor = rootAncestor.parent;
8076 }
8077 return rootAncestor;
8078 }
8079
8080 /**
8081 * Returns whether the specified Container is the focus cycle root of this
8082 * Component's focus traversal cycle. Each focus traversal cycle has only
8083 * a single focus cycle root and each Component which is not a Container
8084 * belongs to only a single focus traversal cycle.
8085 *
8086 * @param container the Container to be tested
8087 * @return {@code true} if the specified Container is a focus-cycle-
8088 * root of this Component; {@code false} otherwise
8089 * @see Container#isFocusCycleRoot()
8090 * @since 1.4
8091 */
8092 public boolean isFocusCycleRoot(Container container) {
8093 Container rootAncestor = getFocusCycleRootAncestor();
8094 return (rootAncestor == container);
8095 }
8096
8097 Container getTraversalRoot() {
8098 return getFocusCycleRootAncestor();
8099 }
8100
8101 /**
8102 * Transfers the focus to the next component, as though this Component were
8103 * the focus owner.
8104 * @see #requestFocus()
8105 * @since 1.1
8106 */
8107 public void transferFocus() {
8108 nextFocus();
8109 }
8110
8111 /**
8112 * @deprecated As of JDK version 1.1,
8113 * replaced by transferFocus().
8114 */
8115 @Deprecated
8116 public void nextFocus() {
8117 transferFocus(false);
8118 }
8119
8120 boolean transferFocus(boolean clearOnFailure) {
8121 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8122 focusLog.finer("clearOnFailure = " + clearOnFailure);
8123 }
8124 Component toFocus = getNextFocusCandidate();
8125 boolean res = false;
8126 if (toFocus != null && !toFocus.isFocusOwner() && toFocus != this) {
8127 res = toFocus.requestFocusInWindow(FocusEvent.Cause.TRAVERSAL_FORWARD);
8128 }
8129 if (clearOnFailure && !res) {
8130 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8131 focusLog.finer("clear global focus owner");
8132 }
8133 KeyboardFocusManager.getCurrentKeyboardFocusManager().clearGlobalFocusOwnerPriv();
8134 }
8135 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8136 focusLog.finer("returning result: " + res);
8137 }
8138 return res;
8139 }
8140
8141 @SuppressWarnings("deprecation")
8142 final Component getNextFocusCandidate() {
8143 Container rootAncestor = getTraversalRoot();
8144 Component comp = this;
8145 while (rootAncestor != null &&
8146 !(rootAncestor.isShowing() && rootAncestor.canBeFocusOwner()))
8147 {
8148 comp = rootAncestor;
8149 rootAncestor = comp.getFocusCycleRootAncestor();
8150 }
8151 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8152 focusLog.finer("comp = " + comp + ", root = " + rootAncestor);
8153 }
8154 Component candidate = null;
8155 if (rootAncestor != null) {
8156 FocusTraversalPolicy policy = rootAncestor.getFocusTraversalPolicy();
8157 Component toFocus = policy.getComponentAfter(rootAncestor, comp);
8158 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8159 focusLog.finer("component after is " + toFocus);
8160 }
8161 if (toFocus == null) {
8162 toFocus = policy.getDefaultComponent(rootAncestor);
8163 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8164 focusLog.finer("default component is " + toFocus);
8165 }
8166 }
8167 if (toFocus == null) {
8168 Applet applet = EmbeddedFrame.getAppletIfAncestorOf(this);
8169 if (applet != null) {
8170 toFocus = applet;
8171 }
8172 }
8173 candidate = toFocus;
8174 }
8175 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8176 focusLog.finer("Focus transfer candidate: " + candidate);
8177 }
8178 return candidate;
8179 }
8180
8181 /**
8182 * Transfers the focus to the previous component, as though this Component
8183 * were the focus owner.
8184 * @see #requestFocus()
8185 * @since 1.4
8186 */
8187 public void transferFocusBackward() {
8188 transferFocusBackward(false);
8189 }
8190
8191 boolean transferFocusBackward(boolean clearOnFailure) {
8192 Container rootAncestor = getTraversalRoot();
8193 Component comp = this;
8194 while (rootAncestor != null &&
8195 !(rootAncestor.isShowing() && rootAncestor.canBeFocusOwner()))
8196 {
8197 comp = rootAncestor;
8198 rootAncestor = comp.getFocusCycleRootAncestor();
8199 }
8200 boolean res = false;
8201 if (rootAncestor != null) {
8202 FocusTraversalPolicy policy = rootAncestor.getFocusTraversalPolicy();
8203 Component toFocus = policy.getComponentBefore(rootAncestor, comp);
8204 if (toFocus == null) {
8205 toFocus = policy.getDefaultComponent(rootAncestor);
8206 }
8207 if (toFocus != null) {
8208 res = toFocus.requestFocusInWindow(FocusEvent.Cause.TRAVERSAL_BACKWARD);
8209 }
8210 }
8211 if (clearOnFailure && !res) {
8212 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8213 focusLog.finer("clear global focus owner");
8214 }
8215 KeyboardFocusManager.getCurrentKeyboardFocusManager().clearGlobalFocusOwnerPriv();
8216 }
8217 if (focusLog.isLoggable(PlatformLogger.Level.FINER)) {
8218 focusLog.finer("returning result: " + res);
8219 }
8220 return res;
8221 }
8222
8223 /**
8224 * Transfers the focus up one focus traversal cycle. Typically, the focus
8225 * owner is set to this Component's focus cycle root, and the current focus
8226 * cycle root is set to the new focus owner's focus cycle root. If,
8227 * however, this Component's focus cycle root is a Window, then the focus
8228 * owner is set to the focus cycle root's default Component to focus, and
8229 * the current focus cycle root is unchanged.
8230 *
8231 * @see #requestFocus()
8232 * @see Container#isFocusCycleRoot()
8233 * @see Container#setFocusCycleRoot(boolean)
8234 * @since 1.4
8235 */
8236 public void transferFocusUpCycle() {
8237 Container rootAncestor;
8238 for (rootAncestor = getFocusCycleRootAncestor();
8239 rootAncestor != null && !(rootAncestor.isShowing() &&
8240 rootAncestor.isFocusable() &&
8241 rootAncestor.isEnabled());
8242 rootAncestor = rootAncestor.getFocusCycleRootAncestor()) {
8243 }
8244
8245 if (rootAncestor != null) {
8246 Container rootAncestorRootAncestor =
8247 rootAncestor.getFocusCycleRootAncestor();
8248 Container fcr = (rootAncestorRootAncestor != null) ?
8249 rootAncestorRootAncestor : rootAncestor;
8250
8251 KeyboardFocusManager.getCurrentKeyboardFocusManager().
8252 setGlobalCurrentFocusCycleRootPriv(fcr);
8253 rootAncestor.requestFocus(FocusEvent.Cause.TRAVERSAL_UP);
8254 } else {
8255 Window window = getContainingWindow();
8256
8257 if (window != null) {
8258 Component toFocus = window.getFocusTraversalPolicy().
8259 getDefaultComponent(window);
8260 if (toFocus != null) {
8261 KeyboardFocusManager.getCurrentKeyboardFocusManager().
8262 setGlobalCurrentFocusCycleRootPriv(window);
8263 toFocus.requestFocus(FocusEvent.Cause.TRAVERSAL_UP);
8264 }
8265 }
8266 }
8267 }
8268
8269 /**
8270 * Returns {@code true} if this {@code Component} is the
8271 * focus owner. This method is obsolete, and has been replaced by
8272 * {@code isFocusOwner()}.
8273 *
8274 * @return {@code true} if this {@code Component} is the
8275 * focus owner; {@code false} otherwise
8276 * @since 1.2
8277 */
8278 public boolean hasFocus() {
8279 return (KeyboardFocusManager.getCurrentKeyboardFocusManager().
8280 getFocusOwner() == this);
8281 }
8282
8283 /**
8284 * Returns {@code true} if this {@code Component} is the
8285 * focus owner.
8286 *
8287 * @return {@code true} if this {@code Component} is the
8288 * focus owner; {@code false} otherwise
8289 * @since 1.4
8290 */
8291 public boolean isFocusOwner() {
8292 return hasFocus();
8293 }
8294
8295 /*
8296 * Used to disallow auto-focus-transfer on disposal of the focus owner
8297 * in the process of disposing its parent container.
8298 */
8299 private boolean autoFocusTransferOnDisposal = true;
8300
8301 void setAutoFocusTransferOnDisposal(boolean value) {
8302 autoFocusTransferOnDisposal = value;
8303 }
8304
8305 boolean isAutoFocusTransferOnDisposal() {
8306 return autoFocusTransferOnDisposal;
8307 }
8308
8309 /**
8310 * Adds the specified popup menu to the component.
8311 * @param popup the popup menu to be added to the component.
8312 * @see #remove(MenuComponent)
8313 * @exception NullPointerException if {@code popup} is {@code null}
8314 * @since 1.1
8315 */
8316 public void add(PopupMenu popup) {
8317 synchronized (getTreeLock()) {
8318 if (popup.parent != null) {
8319 popup.parent.remove(popup);
8320 }
8321 if (popups == null) {
8322 popups = new Vector<PopupMenu>();
8323 }
8324 popups.addElement(popup);
8325 popup.parent = this;
8326
8327 if (peer != null) {
8328 if (popup.peer == null) {
8329 popup.addNotify();
8330 }
8331 }
8332 }
8333 }
8334
8335 /**
8336 * Removes the specified popup menu from the component.
8337 * @param popup the popup menu to be removed
8338 * @see #add(PopupMenu)
8339 * @since 1.1
8340 */
8341 @SuppressWarnings("unchecked")
8342 public void remove(MenuComponent popup) {
8343 synchronized (getTreeLock()) {
8344 if (popups == null) {
8345 return;
8346 }
8347 int index = popups.indexOf(popup);
8348 if (index >= 0) {
8349 PopupMenu pmenu = (PopupMenu)popup;
8350 if (pmenu.peer != null) {
8351 pmenu.removeNotify();
8352 }
8353 pmenu.parent = null;
8354 popups.removeElementAt(index);
8355 if (popups.size() == 0) {
8356 popups = null;
8357 }
8358 }
8359 }
8360 }
8361
8362 /**
8363 * Returns a string representing the state of this component. This
8364 * method is intended to be used only for debugging purposes, and the
8365 * content and format of the returned string may vary between
8366 * implementations. The returned string may be empty but may not be
8367 * {@code null}.
8368 *
8369 * @return a string representation of this component's state
8370 * @since 1.0
8371 */
8372 protected String paramString() {
8373 final String thisName = Objects.toString(getName(), "");
8374 final String invalid = isValid() ? "" : ",invalid";
8375 final String hidden = visible ? "" : ",hidden";
8376 final String disabled = enabled ? "" : ",disabled";
8377 return thisName + ',' + x + ',' + y + ',' + width + 'x' + height
8378 + invalid + hidden + disabled;
8379 }
8380
8381 /**
8382 * Returns a string representation of this component and its values.
8383 * @return a string representation of this component
8384 * @since 1.0
8385 */
8386 public String toString() {
8387 return getClass().getName() + '[' + paramString() + ']';
8388 }
8389
8390 /**
8391 * Prints a listing of this component to the standard system output
8392 * stream {@code System.out}.
8393 * @see java.lang.System#out
8394 * @since 1.0
8395 */
8396 public void list() {
8397 list(System.out, 0);
8398 }
8399
8400 /**
8401 * Prints a listing of this component to the specified output
8402 * stream.
8403 * @param out a print stream
8404 * @throws NullPointerException if {@code out} is {@code null}
8405 * @since 1.0
8406 */
8407 public void list(PrintStream out) {
8408 list(out, 0);
8409 }
8410
8411 /**
8412 * Prints out a list, starting at the specified indentation, to the
8413 * specified print stream.
8414 * @param out a print stream
8415 * @param indent number of spaces to indent
8416 * @see java.io.PrintStream#println(java.lang.Object)
8417 * @throws NullPointerException if {@code out} is {@code null}
8418 * @since 1.0
8419 */
8420 public void list(PrintStream out, int indent) {
8421 for (int i = 0 ; i < indent ; i++) {
8422 out.print(" ");
8423 }
8424 out.println(this);
8425 }
8426
8427 /**
8428 * Prints a listing to the specified print writer.
8429 * @param out the print writer to print to
8430 * @throws NullPointerException if {@code out} is {@code null}
8431 * @since 1.1
8432 */
8433 public void list(PrintWriter out) {
8434 list(out, 0);
8435 }
8436
8437 /**
8438 * Prints out a list, starting at the specified indentation, to
8439 * the specified print writer.
8440 * @param out the print writer to print to
8441 * @param indent the number of spaces to indent
8442 * @throws NullPointerException if {@code out} is {@code null}
8443 * @see java.io.PrintStream#println(java.lang.Object)
8444 * @since 1.1
8445 */
8446 public void list(PrintWriter out, int indent) {
8447 for (int i = 0 ; i < indent ; i++) {
8448 out.print(" ");
8449 }
8450 out.println(this);
8451 }
8452
8453 /*
8454 * Fetches the native container somewhere higher up in the component
8455 * tree that contains this component.
8456 */
8457 final Container getNativeContainer() {
8458 Container p = getContainer();
8459 while (p != null && p.peer instanceof LightweightPeer) {
8460 p = p.getContainer();
8461 }
8462 return p;
8463 }
8464
8465 /**
8466 * Adds a PropertyChangeListener to the listener list. The listener is
8467 * registered for all bound properties of this class, including the
8468 * following:
8469 * <ul>
8470 * <li>this Component's font ("font")</li>
8471 * <li>this Component's background color ("background")</li>
8472 * <li>this Component's foreground color ("foreground")</li>
8473 * <li>this Component's focusability ("focusable")</li>
8474 * <li>this Component's focus traversal keys enabled state
8475 * ("focusTraversalKeysEnabled")</li>
8476 * <li>this Component's Set of FORWARD_TRAVERSAL_KEYS
8477 * ("forwardFocusTraversalKeys")</li>
8478 * <li>this Component's Set of BACKWARD_TRAVERSAL_KEYS
8479 * ("backwardFocusTraversalKeys")</li>
8480 * <li>this Component's Set of UP_CYCLE_TRAVERSAL_KEYS
8481 * ("upCycleFocusTraversalKeys")</li>
8482 * <li>this Component's preferred size ("preferredSize")</li>
8483 * <li>this Component's minimum size ("minimumSize")</li>
8484 * <li>this Component's maximum size ("maximumSize")</li>
8485 * <li>this Component's name ("name")</li>
8486 * </ul>
8487 * Note that if this {@code Component} is inheriting a bound property, then no
8488 * event will be fired in response to a change in the inherited property.
8489 * <p>
8490 * If {@code listener} is {@code null},
8491 * no exception is thrown and no action is performed.
8492 *
8493 * @param listener the property change listener to be added
8494 *
8495 * @see #removePropertyChangeListener
8496 * @see #getPropertyChangeListeners
8497 * @see #addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)
8498 */
8499 public void addPropertyChangeListener(
8500 PropertyChangeListener listener) {
8501 synchronized (getObjectLock()) {
8502 if (listener == null) {
8503 return;
8504 }
8505 if (changeSupport == null) {
8506 changeSupport = new PropertyChangeSupport(this);
8507 }
8508 changeSupport.addPropertyChangeListener(listener);
8509 }
8510 }
8511
8512 /**
8513 * Removes a PropertyChangeListener from the listener list. This method
8514 * should be used to remove PropertyChangeListeners that were registered
8515 * for all bound properties of this class.
8516 * <p>
8517 * If listener is null, no exception is thrown and no action is performed.
8518 *
8519 * @param listener the PropertyChangeListener to be removed
8520 *
8521 * @see #addPropertyChangeListener
8522 * @see #getPropertyChangeListeners
8523 * @see #removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
8524 */
8525 public void removePropertyChangeListener(
8526 PropertyChangeListener listener) {
8527 synchronized (getObjectLock()) {
8528 if (listener == null || changeSupport == null) {
8529 return;
8530 }
8531 changeSupport.removePropertyChangeListener(listener);
8532 }
8533 }
8534
8535 /**
8536 * Returns an array of all the property change listeners
8537 * registered on this component.
8538 *
8539 * @return all of this component's {@code PropertyChangeListener}s
8540 * or an empty array if no property change
8541 * listeners are currently registered
8542 *
8543 * @see #addPropertyChangeListener
8544 * @see #removePropertyChangeListener
8545 * @see #getPropertyChangeListeners(java.lang.String)
8546 * @see java.beans.PropertyChangeSupport#getPropertyChangeListeners
8547 * @since 1.4
8548 */
8549 public PropertyChangeListener[] getPropertyChangeListeners() {
8550 synchronized (getObjectLock()) {
8551 if (changeSupport == null) {
8552 return new PropertyChangeListener[0];
8553 }
8554 return changeSupport.getPropertyChangeListeners();
8555 }
8556 }
8557
8558 /**
8559 * Adds a PropertyChangeListener to the listener list for a specific
8560 * property. The specified property may be user-defined, or one of the
8561 * following:
8562 * <ul>
8563 * <li>this Component's font ("font")</li>
8564 * <li>this Component's background color ("background")</li>
8565 * <li>this Component's foreground color ("foreground")</li>
8566 * <li>this Component's focusability ("focusable")</li>
8567 * <li>this Component's focus traversal keys enabled state
8568 * ("focusTraversalKeysEnabled")</li>
8569 * <li>this Component's Set of FORWARD_TRAVERSAL_KEYS
8570 * ("forwardFocusTraversalKeys")</li>
8571 * <li>this Component's Set of BACKWARD_TRAVERSAL_KEYS
8572 * ("backwardFocusTraversalKeys")</li>
8573 * <li>this Component's Set of UP_CYCLE_TRAVERSAL_KEYS
8574 * ("upCycleFocusTraversalKeys")</li>
8575 * </ul>
8576 * Note that if this {@code Component} is inheriting a bound property, then no
8577 * event will be fired in response to a change in the inherited property.
8578 * <p>
8579 * If {@code propertyName} or {@code listener} is {@code null},
8580 * no exception is thrown and no action is taken.
8581 *
8582 * @param propertyName one of the property names listed above
8583 * @param listener the property change listener to be added
8584 *
8585 * @see #removePropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)
8586 * @see #getPropertyChangeListeners(java.lang.String)
8587 * @see #addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)
8588 */
8589 public void addPropertyChangeListener(
8590 String propertyName,
8591 PropertyChangeListener listener) {
8592 synchronized (getObjectLock()) {
8593 if (listener == null) {
8594 return;
8595 }
8596 if (changeSupport == null) {
8597 changeSupport = new PropertyChangeSupport(this);
8598 }
8599 changeSupport.addPropertyChangeListener(propertyName, listener);
8600 }
8601 }
8602
8603 /**
8604 * Removes a {@code PropertyChangeListener} from the listener
8605 * list for a specific property. This method should be used to remove
8606 * {@code PropertyChangeListener}s
8607 * that were registered for a specific bound property.
8608 * <p>
8609 * If {@code propertyName} or {@code listener} is {@code null},
8610 * no exception is thrown and no action is taken.
8611 *
8612 * @param propertyName a valid property name
8613 * @param listener the PropertyChangeListener to be removed
8614 *
8615 * @see #addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)
8616 * @see #getPropertyChangeListeners(java.lang.String)
8617 * @see #removePropertyChangeListener(java.beans.PropertyChangeListener)
8618 */
8619 public void removePropertyChangeListener(
8620 String propertyName,
8621 PropertyChangeListener listener) {
8622 synchronized (getObjectLock()) {
8623 if (listener == null || changeSupport == null) {
8624 return;
8625 }
8626 changeSupport.removePropertyChangeListener(propertyName, listener);
8627 }
8628 }
8629
8630 /**
8631 * Returns an array of all the listeners which have been associated
8632 * with the named property.
8633 *
8634 * @param propertyName the property name
8635 * @return all of the {@code PropertyChangeListener}s associated with
8636 * the named property; if no such listeners have been added or
8637 * if {@code propertyName} is {@code null}, an empty
8638 * array is returned
8639 *
8640 * @see #addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)
8641 * @see #removePropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)
8642 * @see #getPropertyChangeListeners
8643 * @since 1.4
8644 */
8645 public PropertyChangeListener[] getPropertyChangeListeners(String propertyName) {
8646 synchronized (getObjectLock()) {
8647 if (changeSupport == null) {
8648 return new PropertyChangeListener[0];
8649 }
8650 return changeSupport.getPropertyChangeListeners(propertyName);
8651 }
8652 }
8653
8654 /**
8655 * Support for reporting bound property changes for Object properties.
8656 * This method can be called when a bound property has changed and it will
8657 * send the appropriate PropertyChangeEvent to any registered
8658 * PropertyChangeListeners.
8659 *
8660 * @param propertyName the property whose value has changed
8661 * @param oldValue the property's previous value
8662 * @param newValue the property's new value
8663 */
8664 protected void firePropertyChange(String propertyName,
8665 Object oldValue, Object newValue) {
8666 PropertyChangeSupport changeSupport;
8667 synchronized (getObjectLock()) {
8668 changeSupport = this.changeSupport;
8669 }
8670 if (changeSupport == null ||
8671 (oldValue != null && newValue != null && oldValue.equals(newValue))) {
8672 return;
8673 }
8674 changeSupport.firePropertyChange(propertyName, oldValue, newValue);
8675 }
8676
8677 /**
8678 * Support for reporting bound property changes for boolean properties.
8679 * This method can be called when a bound property has changed and it will
8680 * send the appropriate PropertyChangeEvent to any registered
8681 * PropertyChangeListeners.
8682 *
8683 * @param propertyName the property whose value has changed
8684 * @param oldValue the property's previous value
8685 * @param newValue the property's new value
8686 * @since 1.4
8687 */
8688 protected void firePropertyChange(String propertyName,
8689 boolean oldValue, boolean newValue) {
8690 PropertyChangeSupport changeSupport = this.changeSupport;
8691 if (changeSupport == null || oldValue == newValue) {
8692 return;
8693 }
8694 changeSupport.firePropertyChange(propertyName, oldValue, newValue);
8695 }
8696
8697 /**
8698 * Support for reporting bound property changes for integer properties.
8699 * This method can be called when a bound property has changed and it will
8700 * send the appropriate PropertyChangeEvent to any registered
8701 * PropertyChangeListeners.
8702 *
8703 * @param propertyName the property whose value has changed
8704 * @param oldValue the property's previous value
8705 * @param newValue the property's new value
8706 * @since 1.4
8707 */
8708 protected void firePropertyChange(String propertyName,
8709 int oldValue, int newValue) {
8710 PropertyChangeSupport changeSupport = this.changeSupport;
8711 if (changeSupport == null || oldValue == newValue) {
8712 return;
8713 }
8714 changeSupport.firePropertyChange(propertyName, oldValue, newValue);
8715 }
8716
8717 /**
8718 * Reports a bound property change.
8719 *
8720 * @param propertyName the programmatic name of the property
8721 * that was changed
8722 * @param oldValue the old value of the property (as a byte)
8723 * @param newValue the new value of the property (as a byte)
8724 * @see #firePropertyChange(java.lang.String, java.lang.Object,
8725 * java.lang.Object)
8726 * @since 1.5
8727 */
8728 public void firePropertyChange(String propertyName, byte oldValue, byte newValue) {
8729 if (changeSupport == null || oldValue == newValue) {
8730 return;
8731 }
8732 firePropertyChange(propertyName, Byte.valueOf(oldValue), Byte.valueOf(newValue));
8733 }
8734
8735 /**
8736 * Reports a bound property change.
8737 *
8738 * @param propertyName the programmatic name of the property
8739 * that was changed
8740 * @param oldValue the old value of the property (as a char)
8741 * @param newValue the new value of the property (as a char)
8742 * @see #firePropertyChange(java.lang.String, java.lang.Object,
8743 * java.lang.Object)
8744 * @since 1.5
8745 */
8746 public void firePropertyChange(String propertyName, char oldValue, char newValue) {
8747 if (changeSupport == null || oldValue == newValue) {
8748 return;
8749 }
8750 firePropertyChange(propertyName, Character.valueOf(oldValue), Character.valueOf(newValue));
8751 }
8752
8753 /**
8754 * Reports a bound property change.
8755 *
8756 * @param propertyName the programmatic name of the property
8757 * that was changed
8758 * @param oldValue the old value of the property (as a short)
8759 * @param newValue the new value of the property (as a short)
8760 * @see #firePropertyChange(java.lang.String, java.lang.Object,
8761 * java.lang.Object)
8762 * @since 1.5
8763 */
8764 public void firePropertyChange(String propertyName, short oldValue, short newValue) {
8765 if (changeSupport == null || oldValue == newValue) {
8766 return;
8767 }
8768 firePropertyChange(propertyName, Short.valueOf(oldValue), Short.valueOf(newValue));
8769 }
8770
8771
8772 /**
8773 * Reports a bound property change.
8774 *
8775 * @param propertyName the programmatic name of the property
8776 * that was changed
8777 * @param oldValue the old value of the property (as a long)
8778 * @param newValue the new value of the property (as a long)
8779 * @see #firePropertyChange(java.lang.String, java.lang.Object,
8780 * java.lang.Object)
8781 * @since 1.5
8782 */
8783 public void firePropertyChange(String propertyName, long oldValue, long newValue) {
8784 if (changeSupport == null || oldValue == newValue) {
8785 return;
8786 }
8787 firePropertyChange(propertyName, Long.valueOf(oldValue), Long.valueOf(newValue));
8788 }
8789
8790 /**
8791 * Reports a bound property change.
8792 *
8793 * @param propertyName the programmatic name of the property
8794 * that was changed
8795 * @param oldValue the old value of the property (as a float)
8796 * @param newValue the new value of the property (as a float)
8797 * @see #firePropertyChange(java.lang.String, java.lang.Object,
8798 * java.lang.Object)
8799 * @since 1.5
8800 */
8801 public void firePropertyChange(String propertyName, float oldValue, float newValue) {
8802 if (changeSupport == null || oldValue == newValue) {
8803 return;
8804 }
8805 firePropertyChange(propertyName, Float.valueOf(oldValue), Float.valueOf(newValue));
8806 }
8807
8808 /**
8809 * Reports a bound property change.
8810 *
8811 * @param propertyName the programmatic name of the property
8812 * that was changed
8813 * @param oldValue the old value of the property (as a double)
8814 * @param newValue the new value of the property (as a double)
8815 * @see #firePropertyChange(java.lang.String, java.lang.Object,
8816 * java.lang.Object)
8817 * @since 1.5
8818 */
8819 public void firePropertyChange(String propertyName, double oldValue, double newValue) {
8820 if (changeSupport == null || oldValue == newValue) {
8821 return;
8822 }
8823 firePropertyChange(propertyName, Double.valueOf(oldValue), Double.valueOf(newValue));
8824 }
8825
8826
8827 // Serialization support.
8828
8829 /**
8830 * Component Serialized Data Version.
8831 *
8832 * @serial
8833 */
8834 private int componentSerializedDataVersion = 4;
8835
8836 /**
8837 * This hack is for Swing serialization. It will invoke
8838 * the Swing package private method {@code compWriteObjectNotify}.
8839 */
8840 private void doSwingSerialization() {
8841 if (!(this instanceof JComponent)) {
8842 return;
8843 }
8844 @SuppressWarnings("deprecation")
8845 Package swingPackage = Package.getPackage("javax.swing");
8846 // For Swing serialization to correctly work Swing needs to
8847 // be notified before Component does it's serialization. This
8848 // hack accommodates this.
8849 //
8850 // Swing classes MUST be loaded by the bootstrap class loader,
8851 // otherwise we don't consider them.
8852 for (Class<?> klass = Component.this.getClass(); klass != null;
8853 klass = klass.getSuperclass()) {
8854 if (klass.getPackage() == swingPackage &&
8855 klass.getClassLoader() == null) {
8856
8857 SwingAccessor.getJComponentAccessor()
8858 .compWriteObjectNotify((JComponent) this);
8859 return;
8860 }
8861 }
8862 }
8863
8864 /**
8865 * Writes default serializable fields to stream. Writes
8866 * a variety of serializable listeners as optional data.
8867 * The non-serializable listeners are detected and
8868 * no attempt is made to serialize them.
8869 *
8870 * @param s the {@code ObjectOutputStream} to write
8871 * @serialData {@code null} terminated sequence of
8872 * 0 or more pairs; the pair consists of a {@code String}
8873 * and an {@code Object}; the {@code String} indicates
8874 * the type of object and is one of the following (as of 1.4):
8875 * {@code componentListenerK} indicating an
8876 * {@code ComponentListener} object;
8877 * {@code focusListenerK} indicating an
8878 * {@code FocusListener} object;
8879 * {@code keyListenerK} indicating an
8880 * {@code KeyListener} object;
8881 * {@code mouseListenerK} indicating an
8882 * {@code MouseListener} object;
8883 * {@code mouseMotionListenerK} indicating an
8884 * {@code MouseMotionListener} object;
8885 * {@code inputMethodListenerK} indicating an
8886 * {@code InputMethodListener} object;
8887 * {@code hierarchyListenerK} indicating an
8888 * {@code HierarchyListener} object;
8889 * {@code hierarchyBoundsListenerK} indicating an
8890 * {@code HierarchyBoundsListener} object;
8891 * {@code mouseWheelListenerK} indicating an
8892 * {@code MouseWheelListener} object
8893 * @serialData an optional {@code ComponentOrientation}
8894 * (after {@code inputMethodListener}, as of 1.2)
8895 *
8896 * @see AWTEventMulticaster#save(java.io.ObjectOutputStream, java.lang.String, java.util.EventListener)
8897 * @see #componentListenerK
8898 * @see #focusListenerK
8899 * @see #keyListenerK
8900 * @see #mouseListenerK
8901 * @see #mouseMotionListenerK
8902 * @see #inputMethodListenerK
8903 * @see #hierarchyListenerK
8904 * @see #hierarchyBoundsListenerK
8905 * @see #mouseWheelListenerK
8906 * @see #readObject(ObjectInputStream)
8907 */
8908 private void writeObject(ObjectOutputStream s)
8909 throws IOException
8910 {
8911 doSwingSerialization();
8912
8913 s.defaultWriteObject();
8914
8915 AWTEventMulticaster.save(s, componentListenerK, componentListener);
8916 AWTEventMulticaster.save(s, focusListenerK, focusListener);
8917 AWTEventMulticaster.save(s, keyListenerK, keyListener);
8918 AWTEventMulticaster.save(s, mouseListenerK, mouseListener);
8919 AWTEventMulticaster.save(s, mouseMotionListenerK, mouseMotionListener);
8920 AWTEventMulticaster.save(s, inputMethodListenerK, inputMethodListener);
8921
8922 s.writeObject(null);
8923 s.writeObject(componentOrientation);
8924
8925 AWTEventMulticaster.save(s, hierarchyListenerK, hierarchyListener);
8926 AWTEventMulticaster.save(s, hierarchyBoundsListenerK,
8927 hierarchyBoundsListener);
8928 s.writeObject(null);
8929
8930 AWTEventMulticaster.save(s, mouseWheelListenerK, mouseWheelListener);
8931 s.writeObject(null);
8932
8933 }
8934
8935 /**
8936 * Reads the {@code ObjectInputStream} and if it isn't
8937 * {@code null} adds a listener to receive a variety
8938 * of events fired by the component.
8939 * Unrecognized keys or values will be ignored.
8940 *
8941 * @param s the {@code ObjectInputStream} to read
8942 * @see #writeObject(ObjectOutputStream)
8943 */
8944 private void readObject(ObjectInputStream s)
8945 throws ClassNotFoundException, IOException
8946 {
8947 objectLock = new Object();
8948
8949 acc = AccessController.getContext();
8950
8951 s.defaultReadObject();
8952
8953 appContext = AppContext.getAppContext();
8954 coalescingEnabled = checkCoalescing();
8955 if (componentSerializedDataVersion < 4) {
8956 // These fields are non-transient and rely on default
8957 // serialization. However, the default values are insufficient,
8958 // so we need to set them explicitly for object data streams prior
8959 // to 1.4.
8960 focusable = true;
8961 isFocusTraversableOverridden = FOCUS_TRAVERSABLE_UNKNOWN;
8962 initializeFocusTraversalKeys();
8963 focusTraversalKeysEnabled = true;
8964 }
8965
8966 Object keyOrNull;
8967 while(null != (keyOrNull = s.readObject())) {
8968 String key = ((String)keyOrNull).intern();
8969
8970 if (componentListenerK == key)
8971 addComponentListener((ComponentListener)(s.readObject()));
8972
8973 else if (focusListenerK == key)
8974 addFocusListener((FocusListener)(s.readObject()));
8975
8976 else if (keyListenerK == key)
8977 addKeyListener((KeyListener)(s.readObject()));
8978
8979 else if (mouseListenerK == key)
8980 addMouseListener((MouseListener)(s.readObject()));
8981
8982 else if (mouseMotionListenerK == key)
8983 addMouseMotionListener((MouseMotionListener)(s.readObject()));
8984
8985 else if (inputMethodListenerK == key)
8986 addInputMethodListener((InputMethodListener)(s.readObject()));
8987
8988 else // skip value for unrecognized key
8989 s.readObject();
8990
8991 }
8992
8993 // Read the component's orientation if it's present
8994 Object orient = null;
8995
8996 try {
8997 orient = s.readObject();
8998 } catch (java.io.OptionalDataException e) {
8999 // JDK 1.1 instances will not have this optional data.
9000 // e.eof will be true to indicate that there is no more
9001 // data available for this object.
9002 // If e.eof is not true, throw the exception as it
9003 // might have been caused by reasons unrelated to
9004 // componentOrientation.
9005
9006 if (!e.eof) {
9007 throw (e);
9008 }
9009 }
9010
9011 if (orient != null) {
9012 componentOrientation = (ComponentOrientation)orient;
9013 } else {
9014 componentOrientation = ComponentOrientation.UNKNOWN;
9015 }
9016
9017 try {
9018 while(null != (keyOrNull = s.readObject())) {
9019 String key = ((String)keyOrNull).intern();
9020
9021 if (hierarchyListenerK == key) {
9022 addHierarchyListener((HierarchyListener)(s.readObject()));
9023 }
9024 else if (hierarchyBoundsListenerK == key) {
9025 addHierarchyBoundsListener((HierarchyBoundsListener)
9026 (s.readObject()));
9027 }
9028 else {
9029 // skip value for unrecognized key
9030 s.readObject();
9031 }
9032 }
9033 } catch (java.io.OptionalDataException e) {
9034 // JDK 1.1/1.2 instances will not have this optional data.
9035 // e.eof will be true to indicate that there is no more
9036 // data available for this object.
9037 // If e.eof is not true, throw the exception as it
9038 // might have been caused by reasons unrelated to
9039 // hierarchy and hierarchyBounds listeners.
9040
9041 if (!e.eof) {
9042 throw (e);
9043 }
9044 }
9045
9046 try {
9047 while (null != (keyOrNull = s.readObject())) {
9048 String key = ((String)keyOrNull).intern();
9049
9050 if (mouseWheelListenerK == key) {
9051 addMouseWheelListener((MouseWheelListener)(s.readObject()));
9052 }
9053 else {
9054 // skip value for unrecognized key
9055 s.readObject();
9056 }
9057 }
9058 } catch (java.io.OptionalDataException e) {
9059 // pre-1.3 instances will not have this optional data.
9060 // e.eof will be true to indicate that there is no more
9061 // data available for this object.
9062 // If e.eof is not true, throw the exception as it
9063 // might have been caused by reasons unrelated to
9064 // mouse wheel listeners
9065
9066 if (!e.eof) {
9067 throw (e);
9068 }
9069 }
9070
9071 if (popups != null) {
9072 int npopups = popups.size();
9073 for (int i = 0 ; i < npopups ; i++) {
9074 PopupMenu popup = popups.elementAt(i);
9075 popup.parent = this;
9076 }
9077 }
9078 }
9079
9080 /**
9081 * Sets the language-sensitive orientation that is to be used to order
9082 * the elements or text within this component. Language-sensitive
9083 * {@code LayoutManager} and {@code Component}
9084 * subclasses will use this property to
9085 * determine how to lay out and draw components.
9086 * <p>
9087 * At construction time, a component's orientation is set to
9088 * {@code ComponentOrientation.UNKNOWN},
9089 * indicating that it has not been specified
9090 * explicitly. The UNKNOWN orientation behaves the same as
9091 * {@code ComponentOrientation.LEFT_TO_RIGHT}.
9092 * <p>
9093 * To set the orientation of a single component, use this method.
9094 * To set the orientation of an entire component
9095 * hierarchy, use
9096 * {@link #applyComponentOrientation applyComponentOrientation}.
9097 * <p>
9098 * This method changes layout-related information, and therefore,
9099 * invalidates the component hierarchy.
9100 *
9101 * @param o the orientation to be set
9102 *
9103 * @see ComponentOrientation
9104 * @see #invalidate
9105 *
9106 * @author Laura Werner, IBM
9107 */
9108 public void setComponentOrientation(ComponentOrientation o) {
9109 ComponentOrientation oldValue = componentOrientation;
9110 componentOrientation = o;
9111
9112 // This is a bound property, so report the change to
9113 // any registered listeners. (Cheap if there are none.)
9114 firePropertyChange("componentOrientation", oldValue, o);
9115
9116 // This could change the preferred size of the Component.
9117 invalidateIfValid();
9118 }
9119
9120 /**
9121 * Retrieves the language-sensitive orientation that is to be used to order
9122 * the elements or text within this component. {@code LayoutManager}
9123 * and {@code Component}
9124 * subclasses that wish to respect orientation should call this method to
9125 * get the component's orientation before performing layout or drawing.
9126 *
9127 * @return the orientation to order the elements or text
9128 * @see ComponentOrientation
9129 *
9130 * @author Laura Werner, IBM
9131 */
9132 public ComponentOrientation getComponentOrientation() {
9133 return componentOrientation;
9134 }
9135
9136 /**
9137 * Sets the {@code ComponentOrientation} property of this component
9138 * and all components contained within it.
9139 * <p>
9140 * This method changes layout-related information, and therefore,
9141 * invalidates the component hierarchy.
9142 *
9143 *
9144 * @param orientation the new component orientation of this component and
9145 * the components contained within it.
9146 * @exception NullPointerException if {@code orientation} is null.
9147 * @see #setComponentOrientation
9148 * @see #getComponentOrientation
9149 * @see #invalidate
9150 * @since 1.4
9151 */
9152 public void applyComponentOrientation(ComponentOrientation orientation) {
9153 if (orientation == null) {
9154 throw new NullPointerException();
9155 }
9156 setComponentOrientation(orientation);
9157 }
9158
9159 final boolean canBeFocusOwner() {
9160 // It is enabled, visible, focusable.
9161 if (isEnabled() && isDisplayable() && isVisible() && isFocusable()) {
9162 return true;
9163 }
9164 return false;
9165 }
9166
9167 /**
9168 * Checks that this component meets the prerequisites to be focus owner:
9169 * - it is enabled, visible, focusable
9170 * - it's parents are all enabled and showing
9171 * - top-level window is focusable
9172 * - if focus cycle root has DefaultFocusTraversalPolicy then it also checks that this policy accepts
9173 * this component as focus owner
9174 * @since 1.5
9175 */
9176 final boolean canBeFocusOwnerRecursively() {
9177 // - it is enabled, visible, focusable
9178 if (!canBeFocusOwner()) {
9179 return false;
9180 }
9181
9182 // - it's parents are all enabled and showing
9183 synchronized(getTreeLock()) {
9184 if (parent != null) {
9185 return parent.canContainFocusOwner(this);
9186 }
9187 }
9188 return true;
9189 }
9190
9191 /**
9192 * Fix the location of the HW component in a LW container hierarchy.
9193 */
9194 final void relocateComponent() {
9195 synchronized (getTreeLock()) {
9196 if (peer == null) {
9197 return;
9198 }
9199 int nativeX = x;
9200 int nativeY = y;
9201 for (Component cont = getContainer();
9202 cont != null && cont.isLightweight();
9203 cont = cont.getContainer())
9204 {
9205 nativeX += cont.x;
9206 nativeY += cont.y;
9207 }
9208 peer.setBounds(nativeX, nativeY, width, height,
9209 ComponentPeer.SET_LOCATION);
9210 }
9211 }
9212
9213 /**
9214 * Returns the {@code Window} ancestor of the component.
9215 * @return Window ancestor of the component or component by itself if it is Window;
9216 * null, if component is not a part of window hierarchy
9217 */
9218 Window getContainingWindow() {
9219 return SunToolkit.getContainingWindow(this);
9220 }
9221
9222 /**
9223 * Initialize JNI field and method IDs
9224 */
9225 private static native void initIDs();
9226
9227 /*
9228 * --- Accessibility Support ---
9229 *
9230 * Component will contain all of the methods in interface Accessible,
9231 * though it won't actually implement the interface - that will be up
9232 * to the individual objects which extend Component.
9233 */
9234
9235 /**
9236 * The {@code AccessibleContext} associated with this {@code Component}.
9237 */
9238 protected AccessibleContext accessibleContext = null;
9239
9240 /**
9241 * Gets the {@code AccessibleContext} associated
9242 * with this {@code Component}.
9243 * The method implemented by this base
9244 * class returns null. Classes that extend {@code Component}
9245 * should implement this method to return the
9246 * {@code AccessibleContext} associated with the subclass.
9247 *
9248 *
9249 * @return the {@code AccessibleContext} of this
9250 * {@code Component}
9251 * @since 1.3
9252 */
9253 public AccessibleContext getAccessibleContext() {
9254 return accessibleContext;
9255 }
9256
9257 /**
9258 * Inner class of Component used to provide default support for
9259 * accessibility. This class is not meant to be used directly by
9260 * application developers, but is instead meant only to be
9261 * subclassed by component developers.
9262 * <p>
9263 * The class used to obtain the accessible role for this object.
9264 * @since 1.3
9265 */
9266 protected abstract class AccessibleAWTComponent extends AccessibleContext
9267 implements Serializable, AccessibleComponent {
9268
9269 private static final long serialVersionUID = 642321655757800191L;
9270
9271 /**
9272 * Though the class is abstract, this should be called by
9273 * all sub-classes.
9274 */
9275 protected AccessibleAWTComponent() {
9276 }
9277
9278 /**
9279 * Number of PropertyChangeListener objects registered. It's used
9280 * to add/remove ComponentListener and FocusListener to track
9281 * target Component's state.
9282 */
9283 private transient volatile int propertyListenersCount = 0;
9284
9285 /**
9286 * A component listener to track show/hide/resize events
9287 * and convert them to PropertyChange events.
9288 */
9289 protected ComponentListener accessibleAWTComponentHandler = null;
9290
9291 /**
9292 * A listener to track focus events
9293 * and convert them to PropertyChange events.
9294 */
9295 protected FocusListener accessibleAWTFocusHandler = null;
9296
9297 /**
9298 * Fire PropertyChange listener, if one is registered,
9299 * when shown/hidden..
9300 * @since 1.3
9301 */
9302 protected class AccessibleAWTComponentHandler implements ComponentListener {
9303 public void componentHidden(ComponentEvent e) {
9304 if (accessibleContext != null) {
9305 accessibleContext.firePropertyChange(
9306 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
9307 AccessibleState.VISIBLE, null);
9308 }
9309 }
9310
9311 public void componentShown(ComponentEvent e) {
9312 if (accessibleContext != null) {
9313 accessibleContext.firePropertyChange(
9314 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
9315 null, AccessibleState.VISIBLE);
9316 }
9317 }
9318
9319 public void componentMoved(ComponentEvent e) {
9320 }
9321
9322 public void componentResized(ComponentEvent e) {
9323 }
9324 } // inner class AccessibleAWTComponentHandler
9325
9326
9327 /**
9328 * Fire PropertyChange listener, if one is registered,
9329 * when focus events happen
9330 * @since 1.3
9331 */
9332 protected class AccessibleAWTFocusHandler implements FocusListener {
9333 public void focusGained(FocusEvent event) {
9334 if (accessibleContext != null) {
9335 accessibleContext.firePropertyChange(
9336 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
9337 null, AccessibleState.FOCUSED);
9338 }
9339 }
9340 public void focusLost(FocusEvent event) {
9341 if (accessibleContext != null) {
9342 accessibleContext.firePropertyChange(
9343 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
9344 AccessibleState.FOCUSED, null);
9345 }
9346 }
9347 } // inner class AccessibleAWTFocusHandler
9348
9349
9350 /**
9351 * Adds a {@code PropertyChangeListener} to the listener list.
9352 *
9353 * @param listener the property change listener to be added
9354 */
9355 public void addPropertyChangeListener(PropertyChangeListener listener) {
9356 if (accessibleAWTComponentHandler == null) {
9357 accessibleAWTComponentHandler = new AccessibleAWTComponentHandler();
9358 }
9359 if (accessibleAWTFocusHandler == null) {
9360 accessibleAWTFocusHandler = new AccessibleAWTFocusHandler();
9361 }
9362 if (propertyListenersCount++ == 0) {
9363 Component.this.addComponentListener(accessibleAWTComponentHandler);
9364 Component.this.addFocusListener(accessibleAWTFocusHandler);
9365 }
9366 super.addPropertyChangeListener(listener);
9367 }
9368
9369 /**
9370 * Remove a PropertyChangeListener from the listener list.
9371 * This removes a PropertyChangeListener that was registered
9372 * for all properties.
9373 *
9374 * @param listener The PropertyChangeListener to be removed
9375 */
9376 public void removePropertyChangeListener(PropertyChangeListener listener) {
9377 if (--propertyListenersCount == 0) {
9378 Component.this.removeComponentListener(accessibleAWTComponentHandler);
9379 Component.this.removeFocusListener(accessibleAWTFocusHandler);
9380 }
9381 super.removePropertyChangeListener(listener);
9382 }
9383
9384 // AccessibleContext methods
9385 //
9386 /**
9387 * Gets the accessible name of this object. This should almost never
9388 * return {@code java.awt.Component.getName()},
9389 * as that generally isn't a localized name,
9390 * and doesn't have meaning for the user. If the
9391 * object is fundamentally a text object (e.g. a menu item), the
9392 * accessible name should be the text of the object (e.g. "save").
9393 * If the object has a tooltip, the tooltip text may also be an
9394 * appropriate String to return.
9395 *
9396 * @return the localized name of the object -- can be
9397 * {@code null} if this
9398 * object does not have a name
9399 * @see javax.accessibility.AccessibleContext#setAccessibleName
9400 */
9401 public String getAccessibleName() {
9402 return accessibleName;
9403 }
9404
9405 /**
9406 * Gets the accessible description of this object. This should be
9407 * a concise, localized description of what this object is - what
9408 * is its meaning to the user. If the object has a tooltip, the
9409 * tooltip text may be an appropriate string to return, assuming
9410 * it contains a concise description of the object (instead of just
9411 * the name of the object - e.g. a "Save" icon on a toolbar that
9412 * had "save" as the tooltip text shouldn't return the tooltip
9413 * text as the description, but something like "Saves the current
9414 * text document" instead).
9415 *
9416 * @return the localized description of the object -- can be
9417 * {@code null} if this object does not have a description
9418 * @see javax.accessibility.AccessibleContext#setAccessibleDescription
9419 */
9420 public String getAccessibleDescription() {
9421 return accessibleDescription;
9422 }
9423
9424 /**
9425 * Gets the role of this object.
9426 *
9427 * @return an instance of {@code AccessibleRole}
9428 * describing the role of the object
9429 * @see javax.accessibility.AccessibleRole
9430 */
9431 public AccessibleRole getAccessibleRole() {
9432 return AccessibleRole.AWT_COMPONENT;
9433 }
9434
9435 /**
9436 * Gets the state of this object.
9437 *
9438 * @return an instance of {@code AccessibleStateSet}
9439 * containing the current state set of the object
9440 * @see javax.accessibility.AccessibleState
9441 */
9442 public AccessibleStateSet getAccessibleStateSet() {
9443 return Component.this.getAccessibleStateSet();
9444 }
9445
9446 /**
9447 * Gets the {@code Accessible} parent of this object.
9448 * If the parent of this object implements {@code Accessible},
9449 * this method should simply return {@code getParent}.
9450 *
9451 * @return the {@code Accessible} parent of this
9452 * object -- can be {@code null} if this
9453 * object does not have an {@code Accessible} parent
9454 */
9455 public Accessible getAccessibleParent() {
9456 if (accessibleParent != null) {
9457 return accessibleParent;
9458 } else {
9459 Container parent = getParent();
9460 if (parent instanceof Accessible) {
9461 return (Accessible) parent;
9462 }
9463 }
9464 return null;
9465 }
9466
9467 /**
9468 * Gets the index of this object in its accessible parent.
9469 *
9470 * @return the index of this object in its parent; or -1 if this
9471 * object does not have an accessible parent
9472 * @see #getAccessibleParent
9473 */
9474 public int getAccessibleIndexInParent() {
9475 return Component.this.getAccessibleIndexInParent();
9476 }
9477
9478 /**
9479 * Returns the number of accessible children in the object. If all
9480 * of the children of this object implement {@code Accessible},
9481 * then this method should return the number of children of this object.
9482 *
9483 * @return the number of accessible children in the object
9484 */
9485 public int getAccessibleChildrenCount() {
9486 return 0; // Components don't have children
9487 }
9488
9489 /**
9490 * Returns the nth {@code Accessible} child of the object.
9491 *
9492 * @param i zero-based index of child
9493 * @return the nth {@code Accessible} child of the object
9494 */
9495 public Accessible getAccessibleChild(int i) {
9496 return null; // Components don't have children
9497 }
9498
9499 /**
9500 * Returns the locale of this object.
9501 *
9502 * @return the locale of this object
9503 */
9504 public Locale getLocale() {
9505 return Component.this.getLocale();
9506 }
9507
9508 /**
9509 * Gets the {@code AccessibleComponent} associated
9510 * with this object if one exists.
9511 * Otherwise return {@code null}.
9512 *
9513 * @return the component
9514 */
9515 public AccessibleComponent getAccessibleComponent() {
9516 return this;
9517 }
9518
9519
9520 // AccessibleComponent methods
9521 //
9522 /**
9523 * Gets the background color of this object.
9524 *
9525 * @return the background color, if supported, of the object;
9526 * otherwise, {@code null}
9527 */
9528 public Color getBackground() {
9529 return Component.this.getBackground();
9530 }
9531
9532 /**
9533 * Sets the background color of this object.
9534 * (For transparency, see {@code isOpaque}.)
9535 *
9536 * @param c the new {@code Color} for the background
9537 * @see Component#isOpaque
9538 */
9539 public void setBackground(Color c) {
9540 Component.this.setBackground(c);
9541 }
9542
9543 /**
9544 * Gets the foreground color of this object.
9545 *
9546 * @return the foreground color, if supported, of the object;
9547 * otherwise, {@code null}
9548 */
9549 public Color getForeground() {
9550 return Component.this.getForeground();
9551 }
9552
9553 /**
9554 * Sets the foreground color of this object.
9555 *
9556 * @param c the new {@code Color} for the foreground
9557 */
9558 public void setForeground(Color c) {
9559 Component.this.setForeground(c);
9560 }
9561
9562 /**
9563 * Gets the {@code Cursor} of this object.
9564 *
9565 * @return the {@code Cursor}, if supported,
9566 * of the object; otherwise, {@code null}
9567 */
9568 public Cursor getCursor() {
9569 return Component.this.getCursor();
9570 }
9571
9572 /**
9573 * Sets the {@code Cursor} of this object.
9574 * <p>
9575 * The method may have no visual effect if the Java platform
9576 * implementation and/or the native system do not support
9577 * changing the mouse cursor shape.
9578 * @param cursor the new {@code Cursor} for the object
9579 */
9580 public void setCursor(Cursor cursor) {
9581 Component.this.setCursor(cursor);
9582 }
9583
9584 /**
9585 * Gets the {@code Font} of this object.
9586 *
9587 * @return the {@code Font}, if supported,
9588 * for the object; otherwise, {@code null}
9589 */
9590 public Font getFont() {
9591 return Component.this.getFont();
9592 }
9593
9594 /**
9595 * Sets the {@code Font} of this object.
9596 *
9597 * @param f the new {@code Font} for the object
9598 */
9599 public void setFont(Font f) {
9600 Component.this.setFont(f);
9601 }
9602
9603 /**
9604 * Gets the {@code FontMetrics} of this object.
9605 *
9606 * @param f the {@code Font}
9607 * @return the {@code FontMetrics}, if supported,
9608 * the object; otherwise, {@code null}
9609 * @see #getFont
9610 */
9611 public FontMetrics getFontMetrics(Font f) {
9612 if (f == null) {
9613 return null;
9614 } else {
9615 return Component.this.getFontMetrics(f);
9616 }
9617 }
9618
9619 /**
9620 * Determines if the object is enabled.
9621 *
9622 * @return true if object is enabled; otherwise, false
9623 */
9624 public boolean isEnabled() {
9625 return Component.this.isEnabled();
9626 }
9627
9628 /**
9629 * Sets the enabled state of the object.
9630 *
9631 * @param b if true, enables this object; otherwise, disables it
9632 */
9633 public void setEnabled(boolean b) {
9634 boolean old = Component.this.isEnabled();
9635 Component.this.setEnabled(b);
9636 if (b != old) {
9637 if (accessibleContext != null) {
9638 if (b) {
9639 accessibleContext.firePropertyChange(
9640 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
9641 null, AccessibleState.ENABLED);
9642 } else {
9643 accessibleContext.firePropertyChange(
9644 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
9645 AccessibleState.ENABLED, null);
9646 }
9647 }
9648 }
9649 }
9650
9651 /**
9652 * Determines if the object is visible. Note: this means that the
9653 * object intends to be visible; however, it may not in fact be
9654 * showing on the screen because one of the objects that this object
9655 * is contained by is not visible. To determine if an object is
9656 * showing on the screen, use {@code isShowing}.
9657 *
9658 * @return true if object is visible; otherwise, false
9659 */
9660 public boolean isVisible() {
9661 return Component.this.isVisible();
9662 }
9663
9664 /**
9665 * Sets the visible state of the object.
9666 *
9667 * @param b if true, shows this object; otherwise, hides it
9668 */
9669 public void setVisible(boolean b) {
9670 boolean old = Component.this.isVisible();
9671 Component.this.setVisible(b);
9672 if (b != old) {
9673 if (accessibleContext != null) {
9674 if (b) {
9675 accessibleContext.firePropertyChange(
9676 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
9677 null, AccessibleState.VISIBLE);
9678 } else {
9679 accessibleContext.firePropertyChange(
9680 AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
9681 AccessibleState.VISIBLE, null);
9682 }
9683 }
9684 }
9685 }
9686
9687 /**
9688 * Determines if the object is showing. This is determined by checking
9689 * the visibility of the object and ancestors of the object. Note:
9690 * this will return true even if the object is obscured by another
9691 * (for example, it happens to be underneath a menu that was pulled
9692 * down).
9693 *
9694 * @return true if object is showing; otherwise, false
9695 */
9696 public boolean isShowing() {
9697 return Component.this.isShowing();
9698 }
9699
9700 /**
9701 * Checks whether the specified point is within this object's bounds,
9702 * where the point's x and y coordinates are defined to be relative to
9703 * the coordinate system of the object.
9704 *
9705 * @param p the {@code Point} relative to the
9706 * coordinate system of the object
9707 * @return true if object contains {@code Point}; otherwise false
9708 */
9709 public boolean contains(Point p) {
9710 return Component.this.contains(p);
9711 }
9712
9713 /**
9714 * Returns the location of the object on the screen.
9715 *
9716 * @return location of object on screen -- can be
9717 * {@code null} if this object is not on the screen
9718 */
9719 public Point getLocationOnScreen() {
9720 synchronized (Component.this.getTreeLock()) {
9721 if (Component.this.isShowing()) {
9722 return Component.this.getLocationOnScreen();
9723 } else {
9724 return null;
9725 }
9726 }
9727 }
9728
9729 /**
9730 * Gets the location of the object relative to the parent in the form
9731 * of a point specifying the object's top-left corner in the screen's
9732 * coordinate space.
9733 *
9734 * @return an instance of Point representing the top-left corner of
9735 * the object's bounds in the coordinate space of the screen;
9736 * {@code null} if this object or its parent are not on the screen
9737 */
9738 public Point getLocation() {
9739 return Component.this.getLocation();
9740 }
9741
9742 /**
9743 * Sets the location of the object relative to the parent.
9744 * @param p the coordinates of the object
9745 */
9746 public void setLocation(Point p) {
9747 Component.this.setLocation(p);
9748 }
9749
9750 /**
9751 * Gets the bounds of this object in the form of a Rectangle object.
9752 * The bounds specify this object's width, height, and location
9753 * relative to its parent.
9754 *
9755 * @return a rectangle indicating this component's bounds;
9756 * {@code null} if this object is not on the screen
9757 */
9758 public Rectangle getBounds() {
9759 return Component.this.getBounds();
9760 }
9761
9762 /**
9763 * Sets the bounds of this object in the form of a
9764 * {@code Rectangle} object.
9765 * The bounds specify this object's width, height, and location
9766 * relative to its parent.
9767 *
9768 * @param r a rectangle indicating this component's bounds
9769 */
9770 public void setBounds(Rectangle r) {
9771 Component.this.setBounds(r);
9772 }
9773
9774 /**
9775 * Returns the size of this object in the form of a
9776 * {@code Dimension} object. The height field of the
9777 * {@code Dimension} object contains this object's
9778 * height, and the width field of the {@code Dimension}
9779 * object contains this object's width.
9780 *
9781 * @return a {@code Dimension} object that indicates
9782 * the size of this component; {@code null} if
9783 * this object is not on the screen
9784 */
9785 public Dimension getSize() {
9786 return Component.this.getSize();
9787 }
9788
9789 /**
9790 * Resizes this object so that it has width and height.
9791 *
9792 * @param d the dimension specifying the new size of the object
9793 */
9794 public void setSize(Dimension d) {
9795 Component.this.setSize(d);
9796 }
9797
9798 /**
9799 * Returns the {@code Accessible} child,
9800 * if one exists, contained at the local
9801 * coordinate {@code Point}. Otherwise returns
9802 * {@code null}.
9803 *
9804 * @param p the point defining the top-left corner of
9805 * the {@code Accessible}, given in the
9806 * coordinate space of the object's parent
9807 * @return the {@code Accessible}, if it exists,
9808 * at the specified location; else {@code null}
9809 */
9810 public Accessible getAccessibleAt(Point p) {
9811 return null; // Components don't have children
9812 }
9813
9814 /**
9815 * Returns whether this object can accept focus or not.
9816 *
9817 * @return true if object can accept focus; otherwise false
9818 */
9819 public boolean isFocusTraversable() {
9820 return Component.this.isFocusTraversable();
9821 }
9822
9823 /**
9824 * Requests focus for this object.
9825 */
9826 public void requestFocus() {
9827 Component.this.requestFocus();
9828 }
9829
9830 /**
9831 * Adds the specified focus listener to receive focus events from this
9832 * component.
9833 *
9834 * @param l the focus listener
9835 */
9836 public void addFocusListener(FocusListener l) {
9837 Component.this.addFocusListener(l);
9838 }
9839
9840 /**
9841 * Removes the specified focus listener so it no longer receives focus
9842 * events from this component.
9843 *
9844 * @param l the focus listener
9845 */
9846 public void removeFocusListener(FocusListener l) {
9847 Component.this.removeFocusListener(l);
9848 }
9849
9850 } // inner class AccessibleAWTComponent
9851
9852
9853 /**
9854 * Gets the index of this object in its accessible parent.
9855 * If this object does not have an accessible parent, returns
9856 * -1.
9857 *
9858 * @return the index of this object in its accessible parent
9859 */
9860 int getAccessibleIndexInParent() {
9861 synchronized (getTreeLock()) {
9862
9863 AccessibleContext accContext = getAccessibleContext();
9864 if (accContext == null) {
9865 return -1;
9866 }
9867
9868 Accessible parent = accContext.getAccessibleParent();
9869 if (parent == null) {
9870 return -1;
9871 }
9872
9873 accContext = parent.getAccessibleContext();
9874 for (int i = 0; i < accContext.getAccessibleChildrenCount(); i++) {
9875 if (this.equals(accContext.getAccessibleChild(i))) {
9876 return i;
9877 }
9878 }
9879
9880 return -1;
9881 }
9882 }
9883
9884 /**
9885 * Gets the current state set of this object.
9886 *
9887 * @return an instance of {@code AccessibleStateSet}
9888 * containing the current state set of the object
9889 * @see AccessibleState
9890 */
9891 AccessibleStateSet getAccessibleStateSet() {
9892 synchronized (getTreeLock()) {
9893 AccessibleStateSet states = new AccessibleStateSet();
9894 if (this.isEnabled()) {
9895 states.add(AccessibleState.ENABLED);
9896 }
9897 if (this.isFocusTraversable()) {
9898 states.add(AccessibleState.FOCUSABLE);
9899 }
9900 if (this.isVisible()) {
9901 states.add(AccessibleState.VISIBLE);
9902 }
9903 if (this.isShowing()) {
9904 states.add(AccessibleState.SHOWING);
9905 }
9906 if (this.isFocusOwner()) {
9907 states.add(AccessibleState.FOCUSED);
9908 }
9909 if (this instanceof Accessible) {
9910 AccessibleContext ac = ((Accessible) this).getAccessibleContext();
9911 if (ac != null) {
9912 Accessible ap = ac.getAccessibleParent();
9913 if (ap != null) {
9914 AccessibleContext pac = ap.getAccessibleContext();
9915 if (pac != null) {
9916 AccessibleSelection as = pac.getAccessibleSelection();
9917 if (as != null) {
9918 states.add(AccessibleState.SELECTABLE);
9919 int i = ac.getAccessibleIndexInParent();
9920 if (i >= 0) {
9921 if (as.isAccessibleChildSelected(i)) {
9922 states.add(AccessibleState.SELECTED);
9923 }
9924 }
9925 }
9926 }
9927 }
9928 }
9929 }
9930 if (Component.isInstanceOf(this, "javax.swing.JComponent")) {
9931 if (((javax.swing.JComponent) this).isOpaque()) {
9932 states.add(AccessibleState.OPAQUE);
9933 }
9934 }
9935 return states;
9936 }
9937 }
9938
9939 /**
9940 * Checks that the given object is instance of the given class.
9941 * @param obj Object to be checked
9942 * @param className The name of the class. Must be fully-qualified class name.
9943 * @return true, if this object is instanceof given class,
9944 * false, otherwise, or if obj or className is null
9945 */
9946 static boolean isInstanceOf(Object obj, String className) {
9947 if (obj == null) return false;
9948 if (className == null) return false;
9949
9950 Class<?> cls = obj.getClass();
9951 while (cls != null) {
9952 if (cls.getName().equals(className)) {
9953 return true;
9954 }
9955 cls = cls.getSuperclass();
9956 }
9957 return false;
9958 }
9959
9960
9961 // ************************** MIXING CODE *******************************
9962
9963 /**
9964 * Check whether we can trust the current bounds of the component.
9965 * The return value of false indicates that the container of the
9966 * component is invalid, and therefore needs to be laid out, which would
9967 * probably mean changing the bounds of its children.
9968 * Null-layout of the container or absence of the container mean
9969 * the bounds of the component are final and can be trusted.
9970 */
9971 final boolean areBoundsValid() {
9972 Container cont = getContainer();
9973 return cont == null || cont.isValid() || cont.getLayout() == null;
9974 }
9975
9976 /**
9977 * Applies the shape to the component
9978 * @param shape Shape to be applied to the component
9979 */
9980 void applyCompoundShape(Region shape) {
9981 checkTreeLock();
9982
9983 if (!areBoundsValid()) {
9984 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
9985 mixingLog.fine("this = " + this + "; areBoundsValid = " + areBoundsValid());
9986 }
9987 return;
9988 }
9989
9990 if (!isLightweight()) {
9991 ComponentPeer peer = this.peer;
9992 if (peer != null) {
9993 // The Region class has some optimizations. That's why
9994 // we should manually check whether it's empty and
9995 // substitute the object ourselves. Otherwise we end up
9996 // with some incorrect Region object with loX being
9997 // greater than the hiX for instance.
9998 if (shape.isEmpty()) {
9999 shape = Region.EMPTY_REGION;
10000 }
10001
10002
10003 // Note: the shape is not really copied/cloned. We create
10004 // the Region object ourselves, so there's no any possibility
10005 // to modify the object outside of the mixing code.
10006 // Nullifying compoundShape means that the component has normal shape
10007 // (or has no shape at all).
10008 if (shape.equals(getNormalShape())) {
10009 if (this.compoundShape == null) {
10010 return;
10011 }
10012 this.compoundShape = null;
10013 peer.applyShape(null);
10014 } else {
10015 if (shape.equals(getAppliedShape())) {
10016 return;
10017 }
10018 this.compoundShape = shape;
10019 Point compAbsolute = getLocationOnWindow();
10020 if (mixingLog.isLoggable(PlatformLogger.Level.FINER)) {
10021 mixingLog.fine("this = " + this +
10022 "; compAbsolute=" + compAbsolute + "; shape=" + shape);
10023 }
10024 peer.applyShape(shape.getTranslatedRegion(-compAbsolute.x, -compAbsolute.y));
10025 }
10026 }
10027 }
10028 }
10029
10030 /**
10031 * Returns the shape previously set with applyCompoundShape().
10032 * If the component is LW or no shape was applied yet,
10033 * the method returns the normal shape.
10034 */
10035 private Region getAppliedShape() {
10036 checkTreeLock();
10037 //XXX: if we allow LW components to have a shape, this must be changed
10038 return (this.compoundShape == null || isLightweight()) ? getNormalShape() : this.compoundShape;
10039 }
10040
10041 Point getLocationOnWindow() {
10042 checkTreeLock();
10043 Point curLocation = getLocation();
10044
10045 for (Container parent = getContainer();
10046 parent != null && !(parent instanceof Window);
10047 parent = parent.getContainer())
10048 {
10049 curLocation.x += parent.getX();
10050 curLocation.y += parent.getY();
10051 }
10052
10053 return curLocation;
10054 }
10055
10056 /**
10057 * Returns the full shape of the component located in window coordinates
10058 */
10059 final Region getNormalShape() {
10060 checkTreeLock();
10061 //XXX: we may take into account a user-specified shape for this component
10062 Point compAbsolute = getLocationOnWindow();
10063 return
10064 Region.getInstanceXYWH(
10065 compAbsolute.x,
10066 compAbsolute.y,
10067 getWidth(),
10068 getHeight()
10069 );
10070 }
10071
10072 /**
10073 * Returns the "opaque shape" of the component.
10074 *
10075 * The opaque shape of a lightweight components is the actual shape that
10076 * needs to be cut off of the heavyweight components in order to mix this
10077 * lightweight component correctly with them.
10078 *
10079 * The method is overriden in the java.awt.Container to handle non-opaque
10080 * containers containing opaque children.
10081 *
10082 * See 6637655 for details.
10083 */
10084 Region getOpaqueShape() {
10085 checkTreeLock();
10086 if (mixingCutoutRegion != null) {
10087 return mixingCutoutRegion;
10088 } else {
10089 return getNormalShape();
10090 }
10091 }
10092
10093 final int getSiblingIndexAbove() {
10094 checkTreeLock();
10095 Container parent = getContainer();
10096 if (parent == null) {
10097 return -1;
10098 }
10099
10100 int nextAbove = parent.getComponentZOrder(this) - 1;
10101
10102 return nextAbove < 0 ? -1 : nextAbove;
10103 }
10104
10105 final ComponentPeer getHWPeerAboveMe() {
10106 checkTreeLock();
10107
10108 Container cont = getContainer();
10109 int indexAbove = getSiblingIndexAbove();
10110
10111 while (cont != null) {
10112 for (int i = indexAbove; i > -1; i--) {
10113 Component comp = cont.getComponent(i);
10114 if (comp != null && comp.isDisplayable() && !comp.isLightweight()) {
10115 return comp.peer;
10116 }
10117 }
10118 // traversing the hierarchy up to the closest HW container;
10119 // further traversing may return a component that is not actually
10120 // a native sibling of this component and this kind of z-order
10121 // request may not be allowed by the underlying system (6852051).
10122 if (!cont.isLightweight()) {
10123 break;
10124 }
10125
10126 indexAbove = cont.getSiblingIndexAbove();
10127 cont = cont.getContainer();
10128 }
10129
10130 return null;
10131 }
10132
10133 final int getSiblingIndexBelow() {
10134 checkTreeLock();
10135 Container parent = getContainer();
10136 if (parent == null) {
10137 return -1;
10138 }
10139
10140 int nextBelow = parent.getComponentZOrder(this) + 1;
10141
10142 return nextBelow >= parent.getComponentCount() ? -1 : nextBelow;
10143 }
10144
10145 final boolean isNonOpaqueForMixing() {
10146 return mixingCutoutRegion != null &&
10147 mixingCutoutRegion.isEmpty();
10148 }
10149
10150 private Region calculateCurrentShape() {
10151 checkTreeLock();
10152 Region s = getNormalShape();
10153
10154 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10155 mixingLog.fine("this = " + this + "; normalShape=" + s);
10156 }
10157
10158 if (getContainer() != null) {
10159 Component comp = this;
10160 Container cont = comp.getContainer();
10161
10162 while (cont != null) {
10163 for (int index = comp.getSiblingIndexAbove(); index != -1; --index) {
10164 /* It is assumed that:
10165 *
10166 * getComponent(getContainer().getComponentZOrder(comp)) == comp
10167 *
10168 * The assumption has been made according to the current
10169 * implementation of the Container class.
10170 */
10171 Component c = cont.getComponent(index);
10172 if (c.isLightweight() && c.isShowing()) {
10173 s = s.getDifference(c.getOpaqueShape());
10174 }
10175 }
10176
10177 if (cont.isLightweight()) {
10178 s = s.getIntersection(cont.getNormalShape());
10179 } else {
10180 break;
10181 }
10182
10183 comp = cont;
10184 cont = cont.getContainer();
10185 }
10186 }
10187
10188 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10189 mixingLog.fine("currentShape=" + s);
10190 }
10191
10192 return s;
10193 }
10194
10195 void applyCurrentShape() {
10196 checkTreeLock();
10197 if (!areBoundsValid()) {
10198 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10199 mixingLog.fine("this = " + this + "; areBoundsValid = " + areBoundsValid());
10200 }
10201 return; // Because applyCompoundShape() ignores such components anyway
10202 }
10203 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10204 mixingLog.fine("this = " + this);
10205 }
10206 applyCompoundShape(calculateCurrentShape());
10207 }
10208
10209 final void subtractAndApplyShape(Region s) {
10210 checkTreeLock();
10211
10212 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10213 mixingLog.fine("this = " + this + "; s=" + s);
10214 }
10215
10216 applyCompoundShape(getAppliedShape().getDifference(s));
10217 }
10218
10219 private final void applyCurrentShapeBelowMe() {
10220 checkTreeLock();
10221 Container parent = getContainer();
10222 if (parent != null && parent.isShowing()) {
10223 // First, reapply shapes of my siblings
10224 parent.recursiveApplyCurrentShape(getSiblingIndexBelow());
10225
10226 // Second, if my container is non-opaque, reapply shapes of siblings of my container
10227 Container parent2 = parent.getContainer();
10228 while (!parent.isOpaque() && parent2 != null) {
10229 parent2.recursiveApplyCurrentShape(parent.getSiblingIndexBelow());
10230
10231 parent = parent2;
10232 parent2 = parent.getContainer();
10233 }
10234 }
10235 }
10236
10237 final void subtractAndApplyShapeBelowMe() {
10238 checkTreeLock();
10239 Container parent = getContainer();
10240 if (parent != null && isShowing()) {
10241 Region opaqueShape = getOpaqueShape();
10242
10243 // First, cut my siblings
10244 parent.recursiveSubtractAndApplyShape(opaqueShape, getSiblingIndexBelow());
10245
10246 // Second, if my container is non-opaque, cut siblings of my container
10247 Container parent2 = parent.getContainer();
10248 while (!parent.isOpaque() && parent2 != null) {
10249 parent2.recursiveSubtractAndApplyShape(opaqueShape, parent.getSiblingIndexBelow());
10250
10251 parent = parent2;
10252 parent2 = parent.getContainer();
10253 }
10254 }
10255 }
10256
10257 void mixOnShowing() {
10258 synchronized (getTreeLock()) {
10259 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10260 mixingLog.fine("this = " + this);
10261 }
10262 if (!isMixingNeeded()) {
10263 return;
10264 }
10265 if (isLightweight()) {
10266 subtractAndApplyShapeBelowMe();
10267 } else {
10268 applyCurrentShape();
10269 }
10270 }
10271 }
10272
10273 void mixOnHiding(boolean isLightweight) {
10274 // We cannot be sure that the peer exists at this point, so we need the argument
10275 // to find out whether the hiding component is (well, actually was) a LW or a HW.
10276 synchronized (getTreeLock()) {
10277 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10278 mixingLog.fine("this = " + this + "; isLightweight = " + isLightweight);
10279 }
10280 if (!isMixingNeeded()) {
10281 return;
10282 }
10283 if (isLightweight) {
10284 applyCurrentShapeBelowMe();
10285 }
10286 }
10287 }
10288
10289 void mixOnReshaping() {
10290 synchronized (getTreeLock()) {
10291 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10292 mixingLog.fine("this = " + this);
10293 }
10294 if (!isMixingNeeded()) {
10295 return;
10296 }
10297 if (isLightweight()) {
10298 applyCurrentShapeBelowMe();
10299 } else {
10300 applyCurrentShape();
10301 }
10302 }
10303 }
10304
10305 void mixOnZOrderChanging(int oldZorder, int newZorder) {
10306 synchronized (getTreeLock()) {
10307 boolean becameHigher = newZorder < oldZorder;
10308 Container parent = getContainer();
10309
10310 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10311 mixingLog.fine("this = " + this +
10312 "; oldZorder=" + oldZorder + "; newZorder=" + newZorder + "; parent=" + parent);
10313 }
10314 if (!isMixingNeeded()) {
10315 return;
10316 }
10317 if (isLightweight()) {
10318 if (becameHigher) {
10319 if (parent != null && isShowing()) {
10320 parent.recursiveSubtractAndApplyShape(getOpaqueShape(), getSiblingIndexBelow(), oldZorder);
10321 }
10322 } else {
10323 if (parent != null) {
10324 parent.recursiveApplyCurrentShape(oldZorder, newZorder);
10325 }
10326 }
10327 } else {
10328 if (becameHigher) {
10329 applyCurrentShape();
10330 } else {
10331 if (parent != null) {
10332 Region shape = getAppliedShape();
10333
10334 for (int index = oldZorder; index < newZorder; index++) {
10335 Component c = parent.getComponent(index);
10336 if (c.isLightweight() && c.isShowing()) {
10337 shape = shape.getDifference(c.getOpaqueShape());
10338 }
10339 }
10340 applyCompoundShape(shape);
10341 }
10342 }
10343 }
10344 }
10345 }
10346
10347 void mixOnValidating() {
10348 // This method gets overriden in the Container. Obviously, a plain
10349 // non-container components don't need to handle validation.
10350 }
10351
10352 final boolean isMixingNeeded() {
10353 if (SunToolkit.getSunAwtDisableMixing()) {
10354 if (mixingLog.isLoggable(PlatformLogger.Level.FINEST)) {
10355 mixingLog.finest("this = " + this + "; Mixing disabled via sun.awt.disableMixing");
10356 }
10357 return false;
10358 }
10359 if (!areBoundsValid()) {
10360 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10361 mixingLog.fine("this = " + this + "; areBoundsValid = " + areBoundsValid());
10362 }
10363 return false;
10364 }
10365 Window window = getContainingWindow();
10366 if (window != null) {
10367 if (!window.hasHeavyweightDescendants() || !window.hasLightweightDescendants() || window.isDisposing()) {
10368 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10369 mixingLog.fine("containing window = " + window +
10370 "; has h/w descendants = " + window.hasHeavyweightDescendants() +
10371 "; has l/w descendants = " + window.hasLightweightDescendants() +
10372 "; disposing = " + window.isDisposing());
10373 }
10374 return false;
10375 }
10376 } else {
10377 if (mixingLog.isLoggable(PlatformLogger.Level.FINE)) {
10378 mixingLog.fine("this = " + this + "; containing window is null");
10379 }
10380 return false;
10381 }
10382 return true;
10383 }
10384
10385 /**
10386 * Sets a 'mixing-cutout' shape for this lightweight component.
10387 *
10388 * This method is used exclusively for the purposes of the
10389 * Heavyweight/Lightweight Components Mixing feature and will
10390 * have no effect if applied to a heavyweight component.
10391 *
10392 * By default a lightweight component is treated as an opaque rectangle for
10393 * the purposes of the Heavyweight/Lightweight Components Mixing feature.
10394 * This method enables developers to set an arbitrary shape to be cut out
10395 * from heavyweight components positioned underneath the lightweight
10396 * component in the z-order.
10397 * <p>
10398 * The {@code shape} argument may have the following values:
10399 * <ul>
10400 * <li>{@code null} - reverts the default cutout shape (the rectangle equal
10401 * to the component's {@code getBounds()})
10402 * <li><i>empty-shape</i> - does not cut out anything from heavyweight
10403 * components. This makes this lightweight component effectively
10404 * transparent. Note that descendants of the lightweight component still
10405 * affect the shapes of heavyweight components. An example of an
10406 * <i>empty-shape</i> is {@code new Rectangle()}.
10407 * <li><i>non-empty-shape</i> - the given shape will be cut out from
10408 * heavyweight components.
10409 * </ul>
10410 * <p>
10411 * The most common example when the 'mixing-cutout' shape is needed is a
10412 * glass pane component. The {@link JRootPane#setGlassPane} method
10413 * automatically sets the <i>empty-shape</i> as the 'mixing-cutout' shape
10414 * for the given glass pane component. If a developer needs some other
10415 * 'mixing-cutout' shape for the glass pane (which is rare), this must be
10416 * changed manually after installing the glass pane to the root pane.
10417 *
10418 * @param shape the new 'mixing-cutout' shape
10419 * @since 9
10420 */
10421 public void setMixingCutoutShape(Shape shape) {
10422 Region region = shape == null ? null : Region.getInstance(shape, null);
10423
10424 synchronized (getTreeLock()) {
10425 boolean needShowing = false;
10426 boolean needHiding = false;
10427
10428 if (!isNonOpaqueForMixing()) {
10429 needHiding = true;
10430 }
10431
10432 mixingCutoutRegion = region;
10433
10434 if (!isNonOpaqueForMixing()) {
10435 needShowing = true;
10436 }
10437
10438 if (isMixingNeeded()) {
10439 if (needHiding) {
10440 mixOnHiding(isLightweight());
10441 }
10442 if (needShowing) {
10443 mixOnShowing();
10444 }
10445 }
10446 }
10447 }
10448
10449 // ****************** END OF MIXING CODE ********************************
10450
10451 // Note that the method is overriden in the Window class,
10452 // a window doesn't need to be updated in the Z-order.
10453 void updateZOrder() {
10454 peer.setZOrder(getHWPeerAboveMe());
10455 }
10456
10457 }