1. /*

  2.  * @(#)HierarchyEvent.java	1.5 00/02/02

  3.  *

  4.  * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.awt.event;

  12. 

  13. import java.awt.AWTEvent;

  14. import java.awt.Component;

  15. import java.awt.Container;

  16. 

  17. /**

  18.  * An event which indicates a change to the Component hierarchy to which

  19.  * a Component belongs.

  20.  * <ul>

  21.  * <li>Hierarchy Change Events (HierarchyListener)

  22.  *     <ul>

  23.  *     <li> addition of an ancestor

  24.  *     <li> removal of an ancestor

  25.  *     <li> hierarchy made displayable

  26.  *     <li> hierarchy made undisplayable

  27.  *     <li> hierarchy shown on the screen (both visible and displayable)

  28.  *     <li> hierarchy hidden on the screen (either invisible or undisplayable)

  29.  *     </ul>

  30.  * <li>Ancestor Reshape Events (HierarchyBoundsListener)

  31.  *     <ul>

  32.  *     <li> an ancestor was resized

  33.  *     <li> an ancestor was moved

  34.  *     </ul>

  35.  * </ul>

  36.  * <p>

  37.  * Hierarchy events are provided for notification purposes ONLY;

  38.  * The AWT will automatically handle changes to the hierarchy internally so

  39.  * that GUI layout and displayability works properly regardless of whether a

  40.  * program is receiving these events or not.

  41.  * <p>

  42.  * This event is generated by a Container object (such as a Panel) when the

  43.  * Container is added, removed, moved, or resized, and passed down the

  44.  * hierarchy. It is also generated by a Component object when that object's

  45.  * <code>addNotify</code>, <code>removeNotify</code>, <code>show</code>, or

  46.  * <code>hide</code> method is called. ANCESTOR_MOVED and ANCESTOR_RESIZED

  47.  * events are dispatched to every <code>HierarchyBoundsListener</code> or

  48.  * <code>HierarchyBoundsAdapter</code> object which registered to receive

  49.  * such events using the Component's <code>addHierarchyBoundsListener</code>

  50.  * method. (<code>HierarchyBoundsAdapter</code> objects implement the <code>

  51.  * HierarchyBoundsListener</code> interface.) HIERARCHY_CHANGED events are

  52.  * dispatched to every <code>HierarchyListener</code> object which registered

  53.  * to receive such events using the Component's <code>addHierarchyListener

  54.  * </code> method. Each such listener object gets this <code>HierarchyEvent

  55.  * </code> when the event occurs.

  56.  *

  57.  * @author	David Mendenhall

  58.  * @version	1.5, 02/02/00

  59.  * @see		HierarchyListener

  60.  * @see		HierarchyBoundsAdapter

  61.  * @see		HierarchyBoundsListener

  62.  * @since 	1.3

  63.  */

  64. public class HierarchyEvent extends AWTEvent {

  65. 

  66.     /**

  67.      * Marks the first integer id for the range of hierarchy event ids.

  68.      */

  69.     public static final int HIERARCHY_FIRST = 1400; // 1300 used by sun.awt.windows.ModalityEvent

  70. 

  71.     /**

  72.      * A modification was made to the entire hierarchy tree.

  73.      */

  74.     public static final int HIERARCHY_CHANGED = HIERARCHY_FIRST;

  75. 

  76.     /**

  77.      * An ancestor-Container was moved.

  78.      */

  79.     public static final int ANCESTOR_MOVED = 1 + HIERARCHY_FIRST;

  80. 

  81.     /**

  82.      * An ancestor-Container was resized.

  83.      */

  84.     public static final int ANCESTOR_RESIZED = 2 + HIERARCHY_FIRST;

  85. 

  86.     /**

  87.      * Marks the last integer id for the range of ancestor event ids.

  88.      */

  89.     public static final int HIERARCHY_LAST = ANCESTOR_RESIZED;

  90. 

  91.     /**

  92.      * The hierarchy changed through a reparent operation.

  93.      */

  94.     public static final int PARENT_CHANGED = 0x1;

  95. 

  96.     /**

  97.      * The displayability of the hierarchy changed. To discern the

  98.      * current displayability of the hierarchy, call

  99.      * Component.isDisplayable(). Displayability changes occur

  100.      * in response to explicit or implicit calls to

  101.      * Component.addNotify() and Component.removeNotify().

  102.      *

  103.      * @see java.awt.Component#isDisplayable()

  104.      * @see java.awt.Component#addNotify()

  105.      * @see java.awt.Component#removeNotify()

  106.      */

  107.     public static final int DISPLAYABILITY_CHANGED = 0x2;

  108. 

  109.     /**

  110.      * The showing state of the hierarchy changed. To discern the

  111.      * current showing state of the hierarchy, call

  112.      * Component.isShowing(). Showing state changes occur

  113.      * when either the displayability or visibility of the

  114.      * hierarchy occurs. Displayability changes occur

  115.      * in response to explicit or implicit calls to

  116.      * Component.addNotify() and Component.removeNotify().

  117.      * Visibility changes occur in response to explicit

  118.      * or implicit calls to Component.show() and

  119.      * Component.hide().

  120.      *

  121.      * @see java.awt.Component#isShowing()

  122.      * @see java.awt.Component#addNotify()

  123.      * @see java.awt.Component#removeNotify()

  124.      * @see java.awt.Component#show()

  125.      * @see java.awt.Component#hide()

  126.      */

  127.     public static final int SHOWING_CHANGED = 0x4;

  128. 

  129.     Component changed;

  130.     Container changedParent;

  131.     long      changeFlags;

  132. 

  133.     /**

  134.      * Constructs an HierarchyEvent object to identify a change in the

  135.      * Component hierarchy.

  136.      *

  137.      * @param source          the Component object that originated the event

  138.      * @param id              an integer indicating the type of event

  139.      * @param changed         the Component at the top of the hierarchy 

  140.      *                        which was changed

  141.      * @param changedParent   the parent of <code>changed</code>. This

  142.      *                        may be the parent before or after the

  143.      *                        change, depending on the type of change.

  144.      */

  145.     public HierarchyEvent(Component source, int id, Component changed,

  146. 			  Container changedParent) {

  147.         super(source, id);

  148. 	this.changed = changed;

  149. 	this.changedParent = changedParent;

  150.     }

  151. 

  152.     /**

  153.      * Constructs an HierarchyEvent object to identify a change in the

  154.      * Component hierarchy.

  155.      *

  156.      * @param source          the Component object that originated the event

  157.      * @param id              an integer indicating the type of event

  158.      * @param changed         the Component at the top of the hierarchy 

  159.      *                        which was changed

  160.      * @param changedParent   the parent of <code>changed</code>. This

  161.      *                        may be the parent before or after the

  162.      *                        change, depending on the type of change.

  163.      * @param changeFlags     a bitmask which indicates the type(s) of

  164.      *                        HIERARCHY_CHANGED events represented in

  165.      *                        this event object

  166.      */

  167.     public HierarchyEvent(Component source, int id, Component changed,

  168. 			  Container changedParent, long changeFlags) {

  169.         super(source, id);

  170. 	this.changed = changed;

  171. 	this.changedParent = changedParent;

  172. 	this.changeFlags = changeFlags;

  173.     }

  174. 

  175.     /**

  176.      * Returns the originator of the event.

  177.      *

  178.      * @return the Component object that originated the event

  179.      */

  180.     public Component getComponent() {

  181.         return (Component)getSource();

  182.     }

  183. 

  184.     /**

  185.      * Returns the Component at the top of the hierarchy which was

  186.      * changed.

  187.      *

  188.      * @return the changed Component

  189.      */

  190.     public Component getChanged() {

  191.         return changed;

  192.     }

  193. 

  194.     /**

  195.      * Returns the parent of the Component returned by <code>

  196.      * getChanged()</code>. For a HIERARCHY_CHANGED event where the

  197.      * change was of type PARENT_CHANGED via a call to <code>

  198.      * Container.add</code>, the parent returned is the parent

  199.      * after the add operation. For a HIERARCHY_CHANGED event where

  200.      * the change was of type PARENT_CHANGED via a call to <code>

  201.      * Container.remove</code>, the parent returned is the parent

  202.      * before the remove operation. For all other events and types,

  203.      * the parent returned is the parent during the operation.

  204.      *

  205.      * @return the parent of the changed Component

  206.      */

  207.     public Container getChangedParent() {

  208.         return changedParent;

  209.     }

  210. 

  211.     /**

  212.      * Returns a bitmask which indicates the type(s) of

  213.      * HIERARCHY_CHANGED events represented in this event object.

  214.      * The bits have been bitwise-ored together.

  215.      *

  216.      * @return the bitmask, or 0 if this is not an HIERARCHY_CHANGED

  217.      * event

  218.      */

  219.     public long getChangeFlags() {

  220.         return changeFlags;

  221.     }

  222. 

  223.     /**

  224.      * Returns a parameter string identifying this event.

  225.      * This method is useful for event-logging and for debugging.

  226.      *

  227.      * @return a string identifying the event and its attributes

  228.      */

  229.     public String paramString() {

  230.         String typeStr;

  231. 	switch(id) {

  232. 	  case ANCESTOR_MOVED:

  233. 	      typeStr = "ANCESTOR_MOVED ("+changed+","+changedParent+")";

  234. 	      break;

  235. 	  case ANCESTOR_RESIZED:

  236. 	      typeStr = "ANCESTOR_RESIZED ("+changed+","+changedParent+")";

  237. 	      break;

  238. 	  case HIERARCHY_CHANGED: {

  239. 	      typeStr = "HIERARCHY_CHANGED (";

  240. 	      boolean first = true;

  241. 	      if ((changeFlags & PARENT_CHANGED) != 0) {

  242. 		  first = false;

  243. 		  typeStr += "PARENT_CHANGED";

  244. 	      }

  245. 	      if ((changeFlags & DISPLAYABILITY_CHANGED) != 0) {

  246. 		  if (first) {

  247. 		      first = false;

  248. 		  } else {

  249. 		      typeStr += ",";

  250. 		  }

  251. 		  typeStr += "DISPLAYABILITY_CHANGED";

  252. 	      }

  253. 	      if ((changeFlags & SHOWING_CHANGED) != 0) {

  254. 		  if (first) {

  255. 		      first = false;

  256. 		  } else {

  257. 		      typeStr += ",";

  258. 		  }

  259. 		  typeStr += "SHOWING_CHANGED";

  260. 	      }

  261. 	      if (!first) {

  262. 		  typeStr += ",";

  263. 	      }

  264. 	      typeStr += changed + "," + changedParent + ")";

  265. 	      break;

  266. 	  }

  267. 	  default:

  268. 	      typeStr = "unknown type";

  269. 	}

  270. 	return typeStr;

  271.     }

  272. }