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. }