--- a/jdk/src/share/classes/java/awt/Container.java Fri Sep 04 14:50:58 2009 +0400
+++ b/jdk/src/share/classes/java/awt/Container.java Tue Sep 15 16:15:36 2009 +0400
@@ -381,16 +381,15 @@
* Appends the specified component to the end of this container.
* This is a convenience method for {@link #addImpl}.
* <p>
- * Note: If a component has been added to a container that
- * has been displayed, <code>validate</code> must be
- * called on that container to display the new component.
- * If multiple components are being added, you can improve
- * efficiency by calling <code>validate</code> only once,
- * after all the components have been added.
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * display the added component.
*
* @param comp the component to be added
* @exception NullPointerException if {@code comp} is {@code null}
* @see #addImpl
+ * @see #invalidate
* @see #validate
* @see javax.swing.JComponent#revalidate()
* @return the component argument
@@ -406,8 +405,15 @@
* <p>
* This method is obsolete as of 1.1. Please use the
* method <code>add(Component, Object)</code> instead.
+ * <p>
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * display the added component.
+ *
* @exception NullPointerException if {@code comp} is {@code null}
* @see #add(Component, Object)
+ * @see #invalidate
*/
public Component add(String name, Component comp) {
addImpl(comp, name, -1);
@@ -419,12 +425,11 @@
* position.
* This is a convenience method for {@link #addImpl}.
* <p>
- * Note: If a component has been added to a container that
- * has been displayed, <code>validate</code> must be
- * called on that container to display the new component.
- * If multiple components are being added, you can improve
- * efficiency by calling <code>validate</code> only once,
- * after all the components have been added.
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * display the added component.
+ *
*
* @param comp the component to be added
* @param index the position at which to insert the component,
@@ -435,6 +440,7 @@
* @return the component <code>comp</code>
* @see #addImpl
* @see #remove
+ * @see #invalidate
* @see #validate
* @see javax.swing.JComponent#revalidate()
*/
@@ -700,6 +706,9 @@
* This property is guaranteed to apply only to lightweight
* non-<code>Container</code> components.
* <p>
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ * <p>
* <b>Note</b>: Not all platforms support changing the z-order of
* heavyweight components from one container into another without
* the call to <code>removeNotify</code>. There is no way to detect
@@ -723,6 +732,7 @@
* @exception IllegalArgumentException if adding a <code>Window</code>
* to a container
* @see #getComponentZOrder(java.awt.Component)
+ * @see #invalidate
* @since 1.5
*/
public void setComponentZOrder(Component comp, int index) {
@@ -923,18 +933,18 @@
* this container's layout using the specified constraints object.
* This is a convenience method for {@link #addImpl}.
* <p>
- * Note: If a component has been added to a container that
- * has been displayed, <code>validate</code> must be
- * called on that container to display the new component.
- * If multiple components are being added, you can improve
- * efficiency by calling <code>validate</code> only once,
- * after all the components have been added.
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * display the added component.
+ *
*
* @param comp the component to be added
* @param constraints an object expressing
* layout contraints for this component
* @exception NullPointerException if {@code comp} is {@code null}
* @see #addImpl
+ * @see #invalidate
* @see #validate
* @see javax.swing.JComponent#revalidate()
* @see LayoutManager
@@ -951,12 +961,11 @@
* the specified constraints object.
* This is a convenience method for {@link #addImpl}.
* <p>
- * Note: If a component has been added to a container that
- * has been displayed, <code>validate</code> must be
- * called on that container to display the new component.
- * If multiple components are being added, you can improve
- * efficiency by calling <code>validate</code> only once,
- * after all the components have been added.
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * display the added component.
+ *
*
* @param comp the component to be added
* @param constraints an object expressing layout contraints for this
@@ -967,6 +976,7 @@
* @exception IllegalArgumentException if {@code index} is invalid (see
* {@link #addImpl} for details)
* @see #addImpl
+ * @see #invalidate
* @see #validate
* @see javax.swing.JComponent#revalidate()
* @see #remove
@@ -1014,6 +1024,11 @@
* <code>super.addImpl(comp, constraints, index)</code>
* </blockquote>
* <p>
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * display the added component.
+ *
* @param comp the component to be added
* @param constraints an object expressing layout constraints
* for this component
@@ -1033,6 +1048,7 @@
* @see #add(Component)
* @see #add(Component, int)
* @see #add(Component, java.lang.Object)
+ * @see #invalidate
* @see LayoutManager
* @see LayoutManager2
* @since JDK1.1
@@ -1145,19 +1161,18 @@
* This method also notifies the layout manager to remove the
* component from this container's layout via the
* <code>removeLayoutComponent</code> method.
+ * <p>
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * reflect the changes.
*
- * <p>
- * Note: If a component has been removed from a container that
- * had been displayed, {@link #validate} must be
- * called on that container to reflect changes.
- * If multiple components are being removed, you can improve
- * efficiency by calling {@link #validate} only once,
- * after all the components have been removed.
*
* @param index the index of the component to be removed
* @throws ArrayIndexOutOfBoundsException if {@code index} is not in
* range {@code [0, getComponentCount()-1]}
* @see #add
+ * @see #invalidate
* @see #validate
* @see #getComponentCount
* @since JDK1.1
@@ -1209,17 +1224,15 @@
* This method also notifies the layout manager to remove the
* component from this container's layout via the
* <code>removeLayoutComponent</code> method.
- *
* <p>
- * Note: If a component has been removed from a container that
- * had been displayed, {@link #validate} must be
- * called on that container to reflect changes.
- * If multiple components are being removed, you can improve
- * efficiency by calling {@link #validate} only once,
- * after all the components have been removed.
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * reflect the changes.
*
* @param comp the component to be removed
* @see #add
+ * @see #invalidate
* @see #validate
* @see #remove(int)
*/
@@ -1239,8 +1252,15 @@
* This method also notifies the layout manager to remove the
* components from this container's layout via the
* <code>removeLayoutComponent</code> method.
+ * <p>
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy. If the container has already been
+ * displayed, the hierarchy must be validated thereafter in order to
+ * reflect the changes.
+ *
* @see #add
* @see #remove
+ * @see #invalidate
*/
public void removeAll() {
synchronized (getTreeLock()) {
@@ -1432,9 +1452,14 @@
/**
* Sets the layout manager for this container.
+ * <p>
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param mgr the specified layout manager
* @see #doLayout
* @see #getLayout
+ * @see #invalidate
*/
public void setLayout(LayoutManager mgr) {
layoutMgr = mgr;
@@ -1502,9 +1527,17 @@
* <p>If this {@code Container} is not valid, this method invokes
* the {@code validateTree} method and marks this {@code Container}
* as valid. Otherwise, no action is performed.
+ * <p>
+ * Note that the {@code invalidate()} method may invalidate not only the
+ * component it is called upon, but also the parents of the component.
+ * Therefore, to restore the validity of the hierarchy, the {@code
+ * validate()} method must be invoked on the top-most invalid container of
+ * the hierarchy. For performance reasons a developer may postpone the
+ * validation of the hierarchy till a bunch of layout-related operations
+ * completes, e.g. after adding all the children to the container.
*
* @see #add(java.awt.Component)
- * @see Component#invalidate
+ * @see #invalidate
* @see javax.swing.JComponent#revalidate()
* @see #validateTree
*/
@@ -1588,8 +1621,13 @@
/**
* Sets the font of this container.
+ * <p>
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param f The font to become this container's font.
* @see Component#getFont
+ * @see #invalidate
* @since JDK1.0
*/
public void setFont(Font f) {
@@ -3386,12 +3424,16 @@
/**
* Sets the <code>ComponentOrientation</code> property of this container
* and all components contained within it.
+ * <p>
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
*
* @param o the new component orientation of this container and
* the components contained within it.
* @exception NullPointerException if <code>orientation</code> is null.
* @see Component#setComponentOrientation
* @see Component#getComponentOrientation
+ * @see #invalidate
* @since 1.4
*/
public void applyComponentOrientation(ComponentOrientation o) {