--- a/jdk/src/share/classes/java/awt/event/HierarchyEvent.java Mon Apr 07 16:52:51 2008 +0400
+++ b/jdk/src/share/classes/java/awt/event/HierarchyEvent.java Tue Apr 08 12:46:39 2008 +0400
@@ -1,5 +1,5 @@
/*
- * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 1999-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -31,7 +31,7 @@
/**
* An event which indicates a change to the <code>Component</code>
- * hierarchy to which a <code>Component</code> belongs.
+ * hierarchy to which <code>Component</code> belongs.
* <ul>
* <li>Hierarchy Change Events (HierarchyListener)
* <ul>
@@ -58,16 +58,30 @@
* Container is added, removed, moved, or resized, and passed down the
* hierarchy. It is also generated by a Component object when that object's
* <code>addNotify</code>, <code>removeNotify</code>, <code>show</code>, or
- * <code>hide</code> method is called. ANCESTOR_MOVED and ANCESTOR_RESIZED
+ * <code>hide</code> method is called. The {@code ANCESTOR_MOVED} and
+ * {@code ANCESTOR_RESIZED}
* events are dispatched to every <code>HierarchyBoundsListener</code> or
* <code>HierarchyBoundsAdapter</code> object which registered to receive
* such events using the Component's <code>addHierarchyBoundsListener</code>
* method. (<code>HierarchyBoundsAdapter</code> objects implement the <code>
- * HierarchyBoundsListener</code> interface.) HIERARCHY_CHANGED events are
+ * HierarchyBoundsListener</code> interface.) The {@code HIERARCHY_CHANGED} events are
* dispatched to every <code>HierarchyListener</code> object which registered
* to receive such events using the Component's <code>addHierarchyListener
* </code> method. Each such listener object gets this <code>HierarchyEvent
* </code> when the event occurs.
+ * <p>
+ * 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}.
+ * <br>
+ * The {@code changeFlags} parameter of any {@code HierarchyEvent} instance takes one of the following
+ * values:
+ * <ul>
+ * <li> {@code HierarchyEvent.PARENT_CHANGED}
+ * <li> {@code HierarchyEvent.DISPLAYABILITY_CHANGED}
+ * <li> {@code HierarchyEvent.SHOWING_CHANGED}
+ * </ul>
+ * Assigning the value different from listed above will cause unspecified behavior.
*
* @author David Mendenhall
* @see HierarchyListener
@@ -108,20 +122,20 @@
public static final int HIERARCHY_LAST = ANCESTOR_RESIZED;
/**
- * Indicates that the <code>HIERARCHY_CHANGED</code> event
+ * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
* was generated by a reparenting operation.
*/
public static final int PARENT_CHANGED = 0x1;
/**
- * Indicates that the <code>HIERARCHY_CHANGED</code> event
- * was generated due to a change in the displayability
- * of the hierarchy. To discern the
- * current displayability of the hierarchy, call
- * <code>Component.isDisplayable</code>. Displayability changes occur
- * in response to explicit or implicit calls to
+ * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
+ * was generated due to the changing of the hierarchy displayability.
+ * To discern the
+ * current displayability of the hierarchy, call the
+ * <code>Component.isDisplayable</code> method. Displayability changes occur
+ * in response to explicit or implicit calls of the
* <code>Component.addNotify</code> and
- * <code>Component.removeNotify</code>.
+ * <code>Component.removeNotify</code> methods.
*
* @see java.awt.Component#isDisplayable()
* @see java.awt.Component#addNotify()
@@ -130,15 +144,15 @@
public static final int DISPLAYABILITY_CHANGED = 0x2;
/**
- * Indicates that the <code>HIERARCHY_CHANGED</code> event
- * was generated due to a change in the showing state
- * of the hierarchy. To discern the
- * current showing state of the hierarchy, call
- * <code>Component.isShowing</code>. Showing state changes occur
+ * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
+ * was generated due to the changing of the hierarchy showing state.
+ * To discern the
+ * current showing state of the hierarchy, call the
+ * <code>Component.isShowing</code> 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 to <code>Component.show</code> and
- * <code>Component.hide</code>.
+ * or implicit calls of the <code>Component.show</code> and
+ * <code>Component.hide</code> methods.
*
* @see java.awt.Component#isShowing()
* @see java.awt.Component#addNotify()
@@ -155,20 +169,26 @@
/**
* Constructs an <code>HierarchyEvent</code> object to identify a
* change in the <code>Component</code> hierarchy.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p>This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> object that
+ * @param source The <code>Component</code> object that
* originated the event
- * @param id an integer indicating the type of event
- * @param changed the <code>Component</code> at the top of
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link HierarchyEvent}
+ * @param changed The <code>Component</code> at the top of
* the hierarchy which was changed
- * @param changedParent the parent of <code>changed</code>; this
+ * @param changedParent The parent of the <code>changed</code> component.
+ * This
* may be the parent before or after the
* change, depending on the type of change
- * @throws IllegalArgumentException if <code>source</code> is null
+ * @throws IllegalArgumentException if <code>source</code> is {@code null}
+ * @see #getSource()
+ * @see #getID()
+ * @see #getChanged()
+ * @see #getChangedParent()
*/
public HierarchyEvent(Component source, int id, Component changed,
Container changedParent) {
@@ -180,23 +200,32 @@
/**
* Constructs an <code>HierarchyEvent</code> object to identify
* a change in the <code>Component</code> hierarchy.
- * <p>Note that passing in an invalid <code>id</code> results in
- * unspecified behavior. This method throws an
+ * <p> This method throws an
* <code>IllegalArgumentException</code> if <code>source</code>
* is <code>null</code>.
*
- * @param source the <code>Component</code> object that
+ * @param source The <code>Component</code> object that
* originated the event
- * @param id an integer indicating the type of event
- * @param changed the <code>Component</code> at the top
+ * @param id An integer indicating the type of event.
+ * For information on allowable values, see
+ * the class description for {@link HierarchyEvent}
+ * @param changed The <code>Component</code> at the top
* of the hierarchy which was changed
- * @param changedParent the parent of <code>changed</code>; this
+ * @param changedParent The parent of the <code>changed</code> component.
+ * This
* may be the parent before or after the
* change, depending on the type of change
- * @param changeFlags a bitmask which indicates the type(s) of
- * <code>HIERARCHY_CHANGED</code> events
- * represented in this event object
+ * @param changeFlags A bitmask which indicates the type(s) of
+ * the <code>HIERARCHY_CHANGED</code> events
+ * represented in this event object.
+ * For information on allowable values, see
+ * the class description for {@link HierarchyEvent}
* @throws IllegalArgumentException if <code>source</code> is null
+ * @see #getSource()
+ * @see #getID()
+ * @see #getChanged()
+ * @see #getChangedParent()
+ * @see #getChangeFlags()
*/
public HierarchyEvent(Component source, int id, Component changed,
Container changedParent, long changeFlags) {