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} 34 * hierarchy to which {@code Component} 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 removeNotify}, {@code show}, or 61 * {@code hide} method is called. The {@code ANCESTOR_MOVED} and 62 * {@code ANCESTOR_RESIZED} 63 * events are dispatched to every {@code HierarchyBoundsListener} or 64 * {@code HierarchyBoundsAdapter} object which registered to receive 65 * such events using the Component's {@code addHierarchyBoundsListener} 66 * method. ({@code HierarchyBoundsAdapter} objects implement the 67 * {@code HierarchyBoundsListener} interface.) The {@code HIERARCHY_CHANGED} events are 68 * dispatched to every {@code HierarchyListener} object which registered 69 * to receive such events using the Component's {@code addHierarchyListener} 70 * method. Each such listener object gets this {@code HierarchyEvent} 71 * 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} 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} 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} method. Displayability changes occur 136 * in response to explicit or implicit calls of the 137 * {@code Component.addNotify} and 138 * {@code Component.removeNotify} 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} 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} 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} and 155 * {@code Component.hide} 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} object to identify a 171 * change in the {@code Component} hierarchy. 172 * <p>This method throws an 173 * {@code IllegalArgumentException} if {@code source} 174 * is {@code null}. 175 * 176 * @param source The {@code Component} 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} at the top of 182 * the hierarchy which was changed 183 * @param changedParent The parent of the {@code changed} 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} is {@code null} 188 * @see #getSource() 189 * @see #getID() 190 * @see #getChanged() 191 * @see #getChangedParent() 192 */ HierarchyEvent(Component source, int id, Component changed, Container changedParent)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} object to identify 202 * a change in the {@code Component} hierarchy. 203 * <p> This method throws an 204 * {@code IllegalArgumentException} if {@code source} 205 * is {@code null}. 206 * 207 * @param source The {@code Component} 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} at the top 213 * of the hierarchy which was changed 214 * @param changedParent The parent of the {@code changed} 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} 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} is null 224 * @see #getSource() 225 * @see #getID() 226 * @see #getChanged() 227 * @see #getChangedParent() 228 * @see #getChangeFlags() 229 */ HierarchyEvent(Component source, int id, Component changed, Container changedParent, long changeFlags)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} object that originated 242 * the event, or {@code null} if the object is not a 243 * {@code Component}. 244 */ getComponent()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 */ getChanged()255 public Component getChanged() { 256 return changed; 257 } 258 259 /** 260 * Returns the parent of the Component returned by 261 * {@code getChanged()}. For a HIERARCHY_CHANGED event where the 262 * change was of type PARENT_CHANGED via a call to 263 * {@code Container.add}, 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 266 * {@code Container.remove}, 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 */ getChangedParent()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 */ getChangeFlags()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 */ paramString()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 } 338