HierarchyEvent


1   /*
2    * @(#)HierarchyEvent.java  1.12 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt.event;
9   
10  import java.awt.AWTEvent  ;
11  import java.awt.Component  ;
12  import java.awt.Container  ;
13  
14  /**
15   * An event which indicates a change to the <code>Component</code>
16   * hierarchy to which a <code>Component</code> belongs.
17   * <ul>
18   * <li>Hierarchy Change Events (HierarchyListener)
19   *     <ul>
20   *     <li> addition of an ancestor
21   *     <li> removal of an ancestor
22   *     <li> hierarchy made displayable
23   *     <li> hierarchy made undisplayable
24   *     <li> hierarchy shown on the screen (both visible and displayable)
25   *     <li> hierarchy hidden on the screen (either invisible or undisplayable)
26   *     </ul>
27   * <li>Ancestor Reshape Events (HierarchyBoundsListener)
28   *     <ul>
29   *     <li> an ancestor was resized
30   *     <li> an ancestor was moved
31   *     </ul>
32   * </ul>
33   * <p>
34   * Hierarchy events are provided for notification purposes ONLY.
35   * The AWT will automatically handle changes to the hierarchy internally so
36   * that GUI layout and displayability works properly regardless of whether a
37   * program is receiving these events or not.
38   * <p>
39   * This event is generated by a Container object (such as a Panel) when the
40   * Container is added, removed, moved, or resized, and passed down the
41   * hierarchy. It is also generated by a Component object when that object's
42   * <code>addNotify</code>, <code>removeNotify</code>, <code>show</code>, or
43   * <code>hide</code> method is called. ANCESTOR_MOVED and ANCESTOR_RESIZED
44   * events are dispatched to every <code>HierarchyBoundsListener</code> or
45   * <code>HierarchyBoundsAdapter</code> object which registered to receive
46   * such events using the Component's <code>addHierarchyBoundsListener</code>
47   * method. (<code>HierarchyBoundsAdapter</code> objects implement the <code>
48   * HierarchyBoundsListener</code> interface.) HIERARCHY_CHANGED events are
49   * dispatched to every <code>HierarchyListener</code> object which registered
50   * to receive such events using the Component's <code>addHierarchyListener
51   * </code> method. Each such listener object gets this <code>HierarchyEvent
52   * </code> when the event occurs.
53   *
54   * @author  David Mendenhall
55   * @version 1.12, 12/19/03
56   * @see     HierarchyListener
57   * @see     HierarchyBoundsAdapter
58   * @see     HierarchyBoundsListener
59   * @since   1.3
60   */
61  public class HierarchyEvent extends AWTEvent   {
62  
63      /**
64       * Marks the first integer id for the range of hierarchy event ids.
65       */
66      public static final int HIERARCHY_FIRST = 1400; // 1300 used by sun.awt.windows.ModalityEvent
67  
68      /**
69       * The event id indicating that modification was made to the
70       * entire hierarchy tree.
71       */
72      public static final int HIERARCHY_CHANGED = HIERARCHY_FIRST;
73  
74      /**
75       * The event id indicating an ancestor-Container was moved.
76       */
77      public static final int ANCESTOR_MOVED = 1 + HIERARCHY_FIRST;
78  
79      /**
80       * The event id indicating an ancestor-Container was resized.
81       */
82      public static final int ANCESTOR_RESIZED = 2 + HIERARCHY_FIRST;
83  
84      /**
85       * Marks the last integer id for the range of ancestor event ids.
86       */
87      public static final int HIERARCHY_LAST = ANCESTOR_RESIZED;
88  
89      /**
90       * Indicates that the <code>HIERARCHY_CHANGED</code> event
91       * was generated by a reparenting operation.
92       */
93      public static final int PARENT_CHANGED = 0x1;
94  
95      /**
96       * Indicates that the <code>HIERARCHY_CHANGED</code> event
97       * was generated due to a change in the displayability
98       * of the hierarchy.  To discern the
99       * current displayability of the hierarchy, call
100      * <code>Component.isDisplayable</code>. Displayability changes occur
101      * in response to explicit or implicit calls to
102      * <code>Component.addNotify</code> and
103      * <code>Component.removeNotify</code>.
104      *
105      * @see java.awt.Component#isDisplayable()
106      * @see java.awt.Component#addNotify()
107      * @see java.awt.Component#removeNotify()
108      */
109     public static final int DISPLAYABILITY_CHANGED = 0x2;
110 
111     /**
112      * Indicates that the <code>HIERARCHY_CHANGED</code> event
113      * was generated due to a change in the showing state
114      * of the hierarchy. To discern the
115      * current showing state of the hierarchy, call
116      * <code>Component.isShowing</code>. Showing state changes occur
117      * when either the displayability or visibility of the
118      * hierarchy occurs. Visibility changes occur in response to explicit
119      * or implicit calls to <code>Component.show</code> and
120      * <code>Component.hide</code>.
121      *
122      * @see java.awt.Component#isShowing()
123      * @see java.awt.Component#addNotify()
124      * @see java.awt.Component#removeNotify()
125      * @see java.awt.Component#show()
126      * @see java.awt.Component#hide()
127      */
128     public static final int SHOWING_CHANGED = 0x4;
129 
130     Component   changed;
131     Container   changedParent;
132     long      changeFlags;
133 
134     /**
135      * Constructs an <code>HierarchyEvent</code> object to identify a
136      * change in the <code>Component</code> hierarchy.
137      * <p>Note that passing in an invalid <code>id</code> results in
138      * unspecified behavior. This method throws an
139      * <code>IllegalArgumentException</code> if <code>source</code>
140      * is <code>null</code>.
141      *
142      * @param source          the <code>Component</code> object that
143      *                        originated the event
144      * @param id              an integer indicating the type of event
145      * @param changed         the <code>Component</code> at the top of
146      *                        the hierarchy which was changed
147      * @param changedParent   the parent of <code>changed</code>; this
148      *                        may be the parent before or after the
149      *                        change, depending on the type of change
150      * @throws IllegalArgumentException if <code>source</code> is null
151      */
152     public HierarchyEvent(Component   source, int id, Component   changed,
153               Container   changedParent) {
154         super(source, id);
155     this.changed = changed;
156     this.changedParent = changedParent;
157     }
158 
159     /**
160      * Constructs an <code>HierarchyEvent</code> object to identify
161      * a change in the <code>Component</code> hierarchy.
162      * <p>Note that passing in an invalid <code>id</code> results in
163      * unspecified behavior. This method throws an
164      * <code>IllegalArgumentException</code> if <code>source</code>
165      * is <code>null</code>.
166      *
167      * @param source          the <code>Component</code> object that
168      *                        originated the event
169      * @param id              an integer indicating the type of event
170      * @param changed         the <code>Component</code> at the top
171      *                        of the hierarchy which was changed
172      * @param changedParent   the parent of <code>changed</code>; this
173      *                        may be the parent before or after the
174      *                        change, depending on the type of change
175      * @param changeFlags     a bitmask which indicates the type(s) of
176      *                        <code>HIERARCHY_CHANGED</code> events
177      *                        represented in this event object
178      * @throws IllegalArgumentException if <code>source</code> is null
179      */
180     public HierarchyEvent(Component   source, int id, Component   changed,
181               Container   changedParent, long changeFlags) {
182         super(source, id);
183     this.changed = changed;
184     this.changedParent = changedParent;
185     this.changeFlags = changeFlags;
186     }
187 
188     /**
189      * Returns the originator of the event.
190      *
191      * @return the <code>Component</code> object that originated 
192      * the event, or <code>null</code> if the object is not a 
193      * <code>Component</code>.  
194      */
195     public Component   getComponent() {
196         return (source instanceof Component  ) ? (Component  )source : null;
197     }
198 
199     /**
200      * Returns the Component at the top of the hierarchy which was
201      * changed.
202      *
203      * @return the changed Component
204      */
205     public Component   getChanged() {
206         return changed;
207     }
208 
209     /**
210      * Returns the parent of the Component returned by <code>
211      * getChanged()</code>. For a HIERARCHY_CHANGED event where the
212      * change was of type PARENT_CHANGED via a call to <code>
213      * Container.add</code>, the parent returned is the parent
214      * after the add operation. For a HIERARCHY_CHANGED event where
215      * the change was of type PARENT_CHANGED via a call to <code>
216      * Container.remove</code>, the parent returned is the parent
217      * before the remove operation. For all other events and types,
218      * the parent returned is the parent during the operation.
219      *
220      * @return the parent of the changed Component
221      */
222     public Container   getChangedParent() {
223         return changedParent;
224     }
225 
226     /**
227      * Returns a bitmask which indicates the type(s) of
228      * HIERARCHY_CHANGED events represented in this event object.
229      * The bits have been bitwise-ored together.
230      *
231      * @return the bitmask, or 0 if this is not an HIERARCHY_CHANGED
232      * event
233      */
234     public long getChangeFlags() {
235         return changeFlags;
236     }
237 
238     /**
239      * Returns a parameter string identifying this event.
240      * This method is useful for event-logging and for debugging.
241      *
242      * @return a string identifying the event and its attributes
243      */
244     public String   paramString() {
245         String   typeStr;
246     switch(id) {
247       case ANCESTOR_MOVED:
248           typeStr = "ANCESTOR_MOVED ("+changed+","+changedParent+")";
249           break;
250       case ANCESTOR_RESIZED:
251           typeStr = "ANCESTOR_RESIZED ("+changed+","+changedParent+")";
252           break;
253       case HIERARCHY_CHANGED: {
254           typeStr = "HIERARCHY_CHANGED (";
255           boolean first = true;
256           if ((changeFlags & PARENT_CHANGED) != 0) {
257           first = false;
258           typeStr += "PARENT_CHANGED";
259           }
260           if ((changeFlags & DISPLAYABILITY_CHANGED) != 0) {
261           if (first) {
262               first = false;
263           } else {
264               typeStr += ",";
265           }
266           typeStr += "DISPLAYABILITY_CHANGED";
267           }
268           if ((changeFlags & SHOWING_CHANGED) != 0) {
269           if (first) {
270               first = false;
271           } else {
272               typeStr += ",";
273           }
274           typeStr += "SHOWING_CHANGED";
275           }
276           if (!first) {
277           typeStr += ",";
278           }
279           typeStr += changed + "," + changedParent + ")";
280           break;
281       }
282       default:
283           typeStr = "unknown type";
284     }
285     return typeStr;
286     }
287 }
288
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags