View Javadoc
1   /*
2    * Copyright (c) 1999, 2008, 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  
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 }