1. /*
  2. * @(#)HierarchyEvent.java 1.10 03/01/23
  3. *
  4. * Copyright 2003 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.10, 01/23/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.
  126. *
  127. * @param source the <code>Component</code> object that
  128. * originated the event
  129. * @param id an integer indicating the type of event
  130. * @param changed the <code>Component</code> at the top of
  131. * the hierarchy which was changed
  132. * @param changedParent the parent of <code>changed</code> this
  133. * may be the parent before or after the
  134. * change, depending on the type of change
  135. */
  136. public HierarchyEvent(Component source, int id, Component changed,
  137. Container changedParent) {
  138. super(source, id);
  139. this.changed = changed;
  140. this.changedParent = changedParent;
  141. }
  142. /**
  143. * Constructs an <code>HierarchyEvent</code> object to identify
  144. * a change in the <code>Component</code> hierarchy.
  145. * <p>Note that passing in an invalid <code>id</code> results in
  146. * unspecified behavior.
  147. *
  148. * @param source the <code>Component</code> object that
  149. * originated the event
  150. * @param id an integer indicating the type of event
  151. * @param changed the <code>Component</code> at the top
  152. * of the hierarchy which was changed
  153. * @param changedParent the parent of <code>changed</code> this
  154. * may be the parent before or after the
  155. * change, depending on the type of change
  156. * @param changeFlags a bitmask which indicates the type(s) of
  157. * <code>HIERARCHY_CHANGED</code> events
  158. * represented in this event object
  159. */
  160. public HierarchyEvent(Component source, int id, Component changed,
  161. Container changedParent, long changeFlags) {
  162. super(source, id);
  163. this.changed = changed;
  164. this.changedParent = changedParent;
  165. this.changeFlags = changeFlags;
  166. }
  167. /**
  168. * Returns the originator of the event.
  169. *
  170. * @return the <code>Component</code> object that originated
  171. * the event, or <code>null</code> if the object is not a
  172. * <code>Component</code>.
  173. */
  174. public Component getComponent() {
  175. return (source instanceof Component) ? (Component)source : null;
  176. }
  177. /**
  178. * Returns the Component at the top of the hierarchy which was
  179. * changed.
  180. *
  181. * @return the changed Component
  182. */
  183. public Component getChanged() {
  184. return changed;
  185. }
  186. /**
  187. * Returns the parent of the Component returned by <code>
  188. * getChanged()</code>. For a HIERARCHY_CHANGED event where the
  189. * change was of type PARENT_CHANGED via a call to <code>
  190. * Container.add</code>, the parent returned is the parent
  191. * after the add operation. For a HIERARCHY_CHANGED event where
  192. * the change was of type PARENT_CHANGED via a call to <code>
  193. * Container.remove</code>, the parent returned is the parent
  194. * before the remove operation. For all other events and types,
  195. * the parent returned is the parent during the operation.
  196. *
  197. * @return the parent of the changed Component
  198. */
  199. public Container getChangedParent() {
  200. return changedParent;
  201. }
  202. /**
  203. * Returns a bitmask which indicates the type(s) of
  204. * HIERARCHY_CHANGED events represented in this event object.
  205. * The bits have been bitwise-ored together.
  206. *
  207. * @return the bitmask, or 0 if this is not an HIERARCHY_CHANGED
  208. * event
  209. */
  210. public long getChangeFlags() {
  211. return changeFlags;
  212. }
  213. /**
  214. * Returns a parameter string identifying this event.
  215. * This method is useful for event-logging and for debugging.
  216. *
  217. * @return a string identifying the event and its attributes
  218. */
  219. public String paramString() {
  220. String typeStr;
  221. switch(id) {
  222. case ANCESTOR_MOVED:
  223. typeStr = "ANCESTOR_MOVED ("+changed+","+changedParent+")";
  224. break;
  225. case ANCESTOR_RESIZED:
  226. typeStr = "ANCESTOR_RESIZED ("+changed+","+changedParent+")";
  227. break;
  228. case HIERARCHY_CHANGED: {
  229. typeStr = "HIERARCHY_CHANGED (";
  230. boolean first = true;
  231. if ((changeFlags & PARENT_CHANGED) != 0) {
  232. first = false;
  233. typeStr += "PARENT_CHANGED";
  234. }
  235. if ((changeFlags & DISPLAYABILITY_CHANGED) != 0) {
  236. if (first) {
  237. first = false;
  238. } else {
  239. typeStr += ",";
  240. }
  241. typeStr += "DISPLAYABILITY_CHANGED";
  242. }
  243. if ((changeFlags & SHOWING_CHANGED) != 0) {
  244. if (first) {
  245. first = false;
  246. } else {
  247. typeStr += ",";
  248. }
  249. typeStr += "SHOWING_CHANGED";
  250. }
  251. if (!first) {
  252. typeStr += ",";
  253. }
  254. typeStr += changed + "," + changedParent + ")";
  255. break;
  256. }
  257. default:
  258. typeStr = "unknown type";
  259. }
  260. return typeStr;
  261. }
  262. }