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