1 /*
2 * Copyright 1999-2008 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.awt.event;
27
28 import java.awt.AWTEvent;
29 import java.awt.Component;
30 import java.awt.Container;
31
32 /**
33 * An event which indicates a change to the <code>Component</code>
34 * hierarchy to which <code>Component</code> belongs.
35 * <ul>
36 * <li>Hierarchy Change Events (HierarchyListener)
37 * <ul>
38 * <li> addition of an ancestor
39 * <li> removal of an ancestor
40 * <li> hierarchy made displayable
41 * <li> hierarchy made undisplayable
42 * <li> hierarchy shown on the screen (both visible and displayable)
43 * <li> hierarchy hidden on the screen (either invisible or undisplayable)
44 * </ul>
45 * <li>Ancestor Reshape Events (HierarchyBoundsListener)
46 * <ul>
47 * <li> an ancestor was resized
48 * <li> an ancestor was moved
49 * </ul>
50 * </ul>
51 * <p>
52 * Hierarchy events are provided for notification purposes ONLY.
53 * The AWT will automatically handle changes to the hierarchy internally so
54 * that GUI layout and displayability works properly regardless of whether a
55 * program is receiving these events or not.
56 * <p>
57 * This event is generated by a Container object (such as a Panel) when the
58 * Container is added, removed, moved, or resized, and passed down the
59 * hierarchy. It is also generated by a Component object when that object's
60 * <code>addNotify</code>, <code>removeNotify</code>, <code>show</code>, or
61 * <code>hide</code> method is called. The {@code ANCESTOR_MOVED} and
62 * {@code ANCESTOR_RESIZED}
63 * events are dispatched to every <code>HierarchyBoundsListener</code> or
64 * <code>HierarchyBoundsAdapter</code> object which registered to receive
65 * such events using the Component's <code>addHierarchyBoundsListener</code>
66 * method. (<code>HierarchyBoundsAdapter</code> objects implement the <code>
67 * HierarchyBoundsListener</code> interface.) The {@code HIERARCHY_CHANGED} events are
68 * dispatched to every <code>HierarchyListener</code> object which registered
69 * to receive such events using the Component's <code>addHierarchyListener
70 * </code> method. Each such listener object gets this <code>HierarchyEvent
71 * </code> when the event occurs.
72 * <p>
73 * An unspecified behavior will be caused if the {@code id} parameter
74 * of any particular {@code HierarchyEvent} instance is not
75 * in the range from {@code HIERARCHY_FIRST} to {@code HIERARCHY_LAST}.
76 * <br>
77 * The {@code changeFlags} parameter of any {@code HierarchyEvent} instance takes one of the following
78 * values:
79 * <ul>
80 * <li> {@code HierarchyEvent.PARENT_CHANGED}
81 * <li> {@code HierarchyEvent.DISPLAYABILITY_CHANGED}
82 * <li> {@code HierarchyEvent.SHOWING_CHANGED}
83 * </ul>
84 * Assigning the value different from listed above will cause unspecified behavior.
85 *
86 * @author David Mendenhall
87 * @see HierarchyListener
88 * @see HierarchyBoundsAdapter
89 * @see HierarchyBoundsListener
90 * @since 1.3
91 */
92 public class HierarchyEvent extends AWTEvent {
93 /*
94 * serialVersionUID
95 */
96 private static final long serialVersionUID = -5337576970038043990L;
97
98 /**
99 * Marks the first integer id for the range of hierarchy event ids.
100 */
101 public static final int HIERARCHY_FIRST = 1400; // 1300 used by sun.awt.windows.ModalityEvent
102
103 /**
104 * The event id indicating that modification was made to the
105 * entire hierarchy tree.
106 */
107 public static final int HIERARCHY_CHANGED = HIERARCHY_FIRST;
108
109 /**
110 * The event id indicating an ancestor-Container was moved.
111 */
112 public static final int ANCESTOR_MOVED = 1 + HIERARCHY_FIRST;
113
114 /**
115 * The event id indicating an ancestor-Container was resized.
116 */
117 public static final int ANCESTOR_RESIZED = 2 + HIERARCHY_FIRST;
118
119 /**
120 * Marks the last integer id for the range of ancestor event ids.
121 */
122 public static final int HIERARCHY_LAST = ANCESTOR_RESIZED;
123
124 /**
125 * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
126 * was generated by a reparenting operation.
127 */
128 public static final int PARENT_CHANGED = 0x1;
129
130 /**
131 * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
132 * was generated due to the changing of the hierarchy displayability.
133 * To discern the
134 * current displayability of the hierarchy, call the
135 * <code>Component.isDisplayable</code> method. Displayability changes occur
136 * in response to explicit or implicit calls of the
137 * <code>Component.addNotify</code> and
138 * <code>Component.removeNotify</code> methods.
139 *
140 * @see java.awt.Component#isDisplayable()
141 * @see java.awt.Component#addNotify()
142 * @see java.awt.Component#removeNotify()
143 */
144 public static final int DISPLAYABILITY_CHANGED = 0x2;
145
146 /**
147 * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
148 * was generated due to the changing of the hierarchy showing state.
149 * To discern the
150 * current showing state of the hierarchy, call the
151 * <code>Component.isShowing</code> method. Showing state changes occur
152 * when either the displayability or visibility of the
153 * hierarchy occurs. Visibility changes occur in response to explicit
154 * or implicit calls of the <code>Component.show</code> and
155 * <code>Component.hide</code> methods.
156 *
157 * @see java.awt.Component#isShowing()
158 * @see java.awt.Component#addNotify()
159 * @see java.awt.Component#removeNotify()
160 * @see java.awt.Component#show()
161 * @see java.awt.Component#hide()
162 */
163 public static final int SHOWING_CHANGED = 0x4;
164
165 Component changed;
166 Container changedParent;
167 long changeFlags;
168
169 /**
170 * Constructs an <code>HierarchyEvent</code> object to identify a
171 * change in the <code>Component</code> hierarchy.
172 * <p>This method throws an
173 * <code>IllegalArgumentException</code> if <code>source</code>
174 * is <code>null</code>.
175 *
176 * @param source The <code>Component</code> object that
177 * originated the event
178 * @param id An integer indicating the type of event.
179 * For information on allowable values, see
180 * the class description for {@link HierarchyEvent}
181 * @param changed The <code>Component</code> at the top of
182 * the hierarchy which was changed
183 * @param changedParent The parent of the <code>changed</code> component.
184 * This
185 * may be the parent before or after the
186 * change, depending on the type of change
187 * @throws IllegalArgumentException if <code>source</code> is {@code null}
188 * @see #getSource()
189 * @see #getID()
190 * @see #getChanged()
191 * @see #getChangedParent()
192 */
193 public HierarchyEvent(Component source, int id, Component changed,
194 Container changedParent) {
195 super(source, id);
196 this.changed = changed;
197 this.changedParent = changedParent;
198 }
199
200 /**
201 * Constructs an <code>HierarchyEvent</code> object to identify
202 * a change in the <code>Component</code> hierarchy.
203 * <p> This method throws an
204 * <code>IllegalArgumentException</code> if <code>source</code>
205 * is <code>null</code>.
206 *
207 * @param source The <code>Component</code> object that
208 * originated the event
209 * @param id An integer indicating the type of event.
210 * For information on allowable values, see
211 * the class description for {@link HierarchyEvent}
212 * @param changed The <code>Component</code> at the top
213 * of the hierarchy which was changed
214 * @param changedParent The parent of the <code>changed</code> component.
215 * This
216 * may be the parent before or after the
217 * change, depending on the type of change
218 * @param changeFlags A bitmask which indicates the type(s) of
219 * the <code>HIERARCHY_CHANGED</code> events
220 * represented in this event object.
221 * For information on allowable values, see
222 * the class description for {@link HierarchyEvent}
223 * @throws IllegalArgumentException if <code>source</code> is null
224 * @see #getSource()
225 * @see #getID()
226 * @see #getChanged()
227 * @see #getChangedParent()
228 * @see #getChangeFlags()
229 */
230 public HierarchyEvent(Component source, int id, Component changed,
231 Container changedParent, long changeFlags) {
232 super(source, id);
233 this.changed = changed;
234 this.changedParent = changedParent;
235 this.changeFlags = changeFlags;
236 }
237
238 /**
239 * Returns the originator of the event.
240 *
241 * @return the <code>Component</code> object that originated
242 * the event, or <code>null</code> if the object is not a
243 * <code>Component</code>.
244 */
245 public Component getComponent() {
246 return (source instanceof Component) ? (Component)source : null;
247 }
248
249 /**
250 * Returns the Component at the top of the hierarchy which was
251 * changed.
252 *
253 * @return the changed Component
254 */
255 public Component getChanged() {
256 return changed;
257 }
258
259 /**
260 * Returns the parent of the Component returned by <code>
261 * getChanged()</code>. For a HIERARCHY_CHANGED event where the
262 * change was of type PARENT_CHANGED via a call to <code>
263 * Container.add</code>, the parent returned is the parent
264 * after the add operation. For a HIERARCHY_CHANGED event where
265 * the change was of type PARENT_CHANGED via a call to <code>
266 * Container.remove</code>, the parent returned is the parent
267 * before the remove operation. For all other events and types,
268 * the parent returned is the parent during the operation.
269 *
270 * @return the parent of the changed Component
271 */
272 public Container getChangedParent() {
273 return changedParent;
274 }
275
276 /**
277 * Returns a bitmask which indicates the type(s) of
278 * HIERARCHY_CHANGED events represented in this event object.
279 * The bits have been bitwise-ored together.
280 *
281 * @return the bitmask, or 0 if this is not an HIERARCHY_CHANGED
282 * event
283 */
284 public long getChangeFlags() {
285 return changeFlags;
286 }
287
288 /**
289 * Returns a parameter string identifying this event.
290 * This method is useful for event-logging and for debugging.
291 *
292 * @return a string identifying the event and its attributes
293 */
294 public String paramString() {
295 String typeStr;
296 switch(id) {
297 case ANCESTOR_MOVED:
298 typeStr = "ANCESTOR_MOVED ("+changed+","+changedParent+")";
299 break;
300 case ANCESTOR_RESIZED:
301 typeStr = "ANCESTOR_RESIZED ("+changed+","+changedParent+")";
302 break;
303 case HIERARCHY_CHANGED: {
304 typeStr = "HIERARCHY_CHANGED (";
305 boolean first = true;
306 if ((changeFlags & PARENT_CHANGED) != 0) {
307 first = false;
308 typeStr += "PARENT_CHANGED";
309 }
310 if ((changeFlags & DISPLAYABILITY_CHANGED) != 0) {
311 if (first) {
312 first = false;
313 } else {
314 typeStr += ",";
315 }
316 typeStr += "DISPLAYABILITY_CHANGED";
317 }
318 if ((changeFlags & SHOWING_CHANGED) != 0) {
319 if (first) {
320 first = false;
321 } else {
322 typeStr += ",";
323 }
324 typeStr += "SHOWING_CHANGED";
325 }
326 if (!first) {
327 typeStr += ",";
328 }
329 typeStr += changed + "," + changedParent + ")";
330 break;
331 }
332 default:
333 typeStr = "unknown type";
334 }
335 return typeStr;
336 }
337 }
Save This Page