java.awt.event: public class: HierarchyEvent

java.awt.event
public class: HierarchyEvent [javadoc | source]

java.lang.Object
   java.util.EventObject
      java.awt.AWTEvent
         java.awt.event.HierarchyEvent

All Implemented Interfaces:
Serializable

An event which indicates a change to the Component hierarchy to which Component belongs.

Hierarchy Change Events (HierarchyListener)
- addition of an ancestor
- removal of an ancestor
- hierarchy made displayable
- hierarchy made undisplayable
- hierarchy shown on the screen (both visible and displayable)
- hierarchy hidden on the screen (either invisible or undisplayable)
Ancestor Reshape Events (HierarchyBoundsListener)
- an ancestor was resized
- an ancestor was moved

Hierarchy events are provided for notification purposes ONLY. The AWT will automatically handle changes to the hierarchy internally so that GUI layout and displayability works properly regardless of whether a program is receiving these events or not.

This event is generated by a Container object (such as a Panel) when the Container is added, removed, moved, or resized, and passed down the hierarchy. It is also generated by a Component object when that object's addNotify, removeNotify, show, or hide method is called. The {@code ANCESTOR_MOVED} and {@code ANCESTOR_RESIZED} events are dispatched to every HierarchyBoundsListener or HierarchyBoundsAdapter object which registered to receive such events using the Component's addHierarchyBoundsListener method. (HierarchyBoundsAdapter objects implement the HierarchyBoundsListener interface.) The {@code HIERARCHY_CHANGED} events are dispatched to every HierarchyListener object which registered to receive such events using the Component's addHierarchyListener method. Each such listener object gets this HierarchyEvent when the event occurs.

An unspecified behavior will be caused if the {@code id} parameter of any particular {@code HierarchyEvent} instance is not in the range from {@code HIERARCHY_FIRST} to {@code HIERARCHY_LAST}.
The {@code changeFlags} parameter of any {@code HierarchyEvent} instance takes one of the following values:

{@code HierarchyEvent.PARENT_CHANGED}
{@code HierarchyEvent.DISPLAYABILITY_CHANGED}
{@code HierarchyEvent.SHOWING_CHANGED}

Assigning the value different from listed above will cause unspecified behavior.

Also see:

HierarchyListener

HierarchyBoundsAdapter

HierarchyBoundsListener

author: David - Mendenhall

since: 1.3 -

Field Summary
public static final int	HIERARCHY_FIRST	Marks the first integer id for the range of hierarchy event ids.
public static final int	HIERARCHY_CHANGED	The event id indicating that modification was made to the entire hierarchy tree.
public static final int	ANCESTOR_MOVED	The event id indicating an ancestor-Container was moved.
public static final int	ANCESTOR_RESIZED	The event id indicating an ancestor-Container was resized.
public static final int	HIERARCHY_LAST	Marks the last integer id for the range of ancestor event ids.
public static final int	PARENT_CHANGED	A change flag indicates that the `HIERARCHY_CHANGED` event was generated by a reparenting operation.
public static final int	DISPLAYABILITY_CHANGED	A change flag indicates that the `HIERARCHY_CHANGED` event was generated due to the changing of the hierarchy displayability. To discern the current displayability of the hierarchy, call the `Component.isDisplayable` method. Displayability changes occur in response to explicit or implicit calls of the `Component.addNotify` and `Component.removeNotify` methods. Also see: java.awt.Component#isDisplayable() java.awt.Component#addNotify() java.awt.Component#removeNotify()
public static final int	SHOWING_CHANGED	A change flag indicates that the `HIERARCHY_CHANGED` event was generated due to the changing of the hierarchy showing state. To discern the current showing state of the hierarchy, call the `Component.isShowing` method. Showing state changes occur when either the displayability or visibility of the hierarchy occurs. Visibility changes occur in response to explicit or implicit calls of the `Component.show` and `Component.hide` methods. Also see: java.awt.Component#isShowing() java.awt.Component#addNotify() java.awt.Component#removeNotify() java.awt.Component#show() java.awt.Component#hide()
Component	changed
Container	changedParent
long	changeFlags

Fields inherited from java.awt.AWTEvent:
id, consumed, focusManagerIsDispatching, isPosted, COMPONENT_EVENT_MASK, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, WINDOW_EVENT_MASK, ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, ITEM_EVENT_MASK, TEXT_EVENT_MASK, INPUT_METHOD_EVENT_MASK, INPUT_METHODS_ENABLED_MASK, PAINT_EVENT_MASK, INVOCATION_EVENT_MASK, HIERARCHY_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, WINDOW_STATE_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, RESERVED_ID_MAX

Fields inherited from java.awt.AWTEvent:

id, consumed, focusManagerIsDispatching, isPosted, COMPONENT_EVENT_MASK, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, WINDOW_EVENT_MASK, ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, ITEM_EVENT_MASK, TEXT_EVENT_MASK, INPUT_METHOD_EVENT_MASK, INPUT_METHODS_ENABLED_MASK, PAINT_EVENT_MASK, INVOCATION_EVENT_MASK, HIERARCHY_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, WINDOW_STATE_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, RESERVED_ID_MAX

Fields inherited from java.util.EventObject:
source

Constructor:

Constructor:
public HierarchyEvent(Component source, int id, Component changed, Container changedParent) { super(source, id); this.changed = changed; this.changedParent = changedParent; } Constructs an `HierarchyEvent` object to identify a change in the `Component` hierarchy. This method throws an `IllegalArgumentException` if `source` is `null`. Parameters: `source` - The `Component` object that originated the event `id` - An integer indicating the type of event. For information on allowable values, see the class description for HierarchyEvent `changed` - The `Component` at the top of the hierarchy which was changed `changedParent` - The parent of the `changed` component. This may be the parent before or after the change, depending on the type of change Throws: `IllegalArgumentException` - if `source` is {@code null} Also see: getSource() getID() getChanged() getChangedParent()
public HierarchyEvent(Component source, int id, Component changed, Container changedParent, long changeFlags) { super(source, id); this.changed = changed; this.changedParent = changedParent; this.changeFlags = changeFlags; } Constructs an `HierarchyEvent` object to identify a change in the `Component` hierarchy. This method throws an `IllegalArgumentException` if `source` is `null`. Parameters: `source` - The `Component` object that originated the event `id` - An integer indicating the type of event. For information on allowable values, see the class description for HierarchyEvent `changed` - The `Component` at the top of the hierarchy which was changed `changedParent` - The parent of the `changed` component. This may be the parent before or after the change, depending on the type of change `changeFlags` - A bitmask which indicates the type(s) of the `HIERARCHY_CHANGED` events represented in this event object. For information on allowable values, see the class description for HierarchyEvent Throws: `IllegalArgumentException` - if `source` is null Also see: getSource() getID() getChanged() getChangedParent() getChangeFlags()

 public HierarchyEvent(Component source,
    int id,
    Component changed,
    Container changedParent) {
                                                                                                                                                                                                                                                                                                                 
        super(source, id);
        this.changed = changed;
        this.changedParent = changedParent;
}

HierarchyEvent

Component

This method throws an IllegalArgumentException if source is null.

Parameters:

source - The Component object that originated the event

id - An integer indicating the type of event. For information on allowable values, see the class description for HierarchyEvent

changed - The Component at the top of the hierarchy which was changed

changedParent - The parent of the changed component. This may be the parent before or after the change, depending on the type of change

Throws:

IllegalArgumentException - if source is {@code null}

Also see:

 public HierarchyEvent(Component source,
    int id,
    Component changed,
    Container changedParent,
    long changeFlags) {
        super(source, id);
        this.changed = changed;
        this.changedParent = changedParent;
        this.changeFlags = changeFlags;
}

HierarchyEvent

Component

This method throws an IllegalArgumentException if source is null.

Parameters:

source - The Component object that originated the event

id - An integer indicating the type of event. For information on allowable values, see the class description for HierarchyEvent

changed - The Component at the top of the hierarchy which was changed

changedParent - The parent of the changed component. This may be the parent before or after the change, depending on the type of change

changeFlags - A bitmask which indicates the type(s) of the HIERARCHY_CHANGED events represented in this event object. For information on allowable values, see the class description for HierarchyEvent

Throws:

IllegalArgumentException - if source is null

Also see:

Method from java.awt.event.HierarchyEvent Summary:
getChangeFlags, getChanged, getChangedParent, getComponent, paramString

Methods from java.awt.AWTEvent:
consume, convertToOld, copyPrivateDataInto, dispatched, getID, isConsumed, paramString, setSource, toString

Methods from java.util.EventObject:
getSource, toString

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from java.awt.event.HierarchyEvent Detail:
public long getChangeFlags() { return changeFlags; } Returns a bitmask which indicates the type(s) of HIERARCHY_CHANGED events represented in this event object. The bits have been bitwise-ored together.
public Component getChanged() { return changed; } Returns the Component at the top of the hierarchy which was changed.
public Container getChangedParent() { return changedParent; } Returns the parent of the Component returned by `getChanged()`. For a HIERARCHY_CHANGED event where the change was of type PARENT_CHANGED via a call to `Container.add`, the parent returned is the parent after the add operation. For a HIERARCHY_CHANGED event where the change was of type PARENT_CHANGED via a call to `Container.remove`, the parent returned is the parent before the remove operation. For all other events and types, the parent returned is the parent during the operation.
public Component getComponent() { return (source instanceof Component) ? (Component)source : null; } Returns the originator of the event.
public String paramString() { String typeStr; switch(id) { case ANCESTOR_MOVED: typeStr = "ANCESTOR_MOVED ("+changed+","+changedParent+")"; break; case ANCESTOR_RESIZED: typeStr = "ANCESTOR_RESIZED ("+changed+","+changedParent+")"; break; case HIERARCHY_CHANGED: { typeStr = "HIERARCHY_CHANGED ("; boolean first = true; if ((changeFlags & PARENT_CHANGED) != 0) { first = false; typeStr += "PARENT_CHANGED"; } if ((changeFlags & DISPLAYABILITY_CHANGED) != 0) { if (first) { first = false; } else { typeStr += ","; } typeStr += "DISPLAYABILITY_CHANGED"; } if ((changeFlags & SHOWING_CHANGED) != 0) { if (first) { first = false; } else { typeStr += ","; } typeStr += "SHOWING_CHANGED"; } if (!first) { typeStr += ","; } typeStr += changed + "," + changedParent + ")"; break; } default: typeStr = "unknown type"; } return typeStr; } Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.

Method from java.awt.event.HierarchyEvent Detail:

 public long getChangeFlags() {
        return changeFlags;
}

Returns a bitmask which indicates the type(s) of HIERARCHY_CHANGED events represented in this event object. The bits have been bitwise-ored together.

 public Component getChanged() {
        return changed;
}

Returns the Component at the top of the hierarchy which was changed.

 public Container getChangedParent() {
        return changedParent;
}


getChanged()


Container.add


Container.remove

 public Component getComponent() {
        return (source instanceof Component) ? (Component)source : null;
}

Returns the originator of the event.

 public String paramString() {
        String typeStr;
        switch(id) {
          case ANCESTOR_MOVED:
              typeStr = "ANCESTOR_MOVED ("+changed+","+changedParent+")";
              break;
          case ANCESTOR_RESIZED:
              typeStr = "ANCESTOR_RESIZED ("+changed+","+changedParent+")";
              break;
          case HIERARCHY_CHANGED: {
              typeStr = "HIERARCHY_CHANGED (";
              boolean first = true;
              if ((changeFlags & PARENT_CHANGED) != 0) {
                  first = false;
                  typeStr += "PARENT_CHANGED";
              }
              if ((changeFlags & DISPLAYABILITY_CHANGED) != 0) {
                  if (first) {
                      first = false;
                  } else {
                      typeStr += ",";
                  }
                  typeStr += "DISPLAYABILITY_CHANGED";
              }
              if ((changeFlags & SHOWING_CHANGED) != 0) {
                  if (first) {
                      first = false;
                  } else {
                      typeStr += ",";
                  }
                  typeStr += "SHOWING_CHANGED";
              }
              if (!first) {
                  typeStr += ",";
              }
              typeStr += changed + "," + changedParent + ")";
              break;
          }
          default:
              typeStr = "unknown type";
        }
        return typeStr;
}

Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.