Component can also be extended directly to create a
* lightweight component. A lightweight component is a component that is
- * not associated with a native opaque window.
+ * not associated with a native window. On the contrary, a heavyweight
+ * component is associated with a native window. The {@link #isLightweight()}
+ * method may be used to distinguish between the two kinds of the components.
+ * + * Lightweight and heavyweight components may be mixed in a single component + * hierarchy. However, for correct operating of such a mixed hierarchy of + * components, the whole hierarchy must be valid. When the hierarchy gets + * invalidated, like after changing the bounds of components, or + * adding/removing components to/from containers, the whole hierarchy must be + * validated afterwards by means of the {@link Container#validate()} method + * invoked on the top-most invalid container of the hierarchy. *
*
b.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param b if true, shows this component;
* otherwise, hides this component
* @see #isVisible
+ * @see #invalidate
* @since JDK1.1
*/
public void setVisible(boolean b) {
@@ -1750,10 +1765,15 @@
/**
* Sets the font of this component.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param f the font to become this component's font;
* if this parameter is null then this
* component will inherit the font of its parent
* @see #getFont
+ * @see #invalidate
* @since JDK1.0
* @beaninfo
* bound: true
@@ -1827,8 +1847,13 @@
/**
* Sets the locale of this component. This is a bound property.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param l the locale to become this component's locale
* @see #getLocale
+ * @see #invalidate
* @since JDK1.1
*/
public void setLocale(Locale l) {
@@ -1948,12 +1973,17 @@
* Moves this component to a new location. The top-left corner of
* the new location is specified by the x and y
* parameters in the coordinate space of this component's parent.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param x the x-coordinate of the new location's
* top-left corner in the parent's coordinate space
* @param y the y-coordinate of the new location's
* top-left corner in the parent's coordinate space
* @see #getLocation
* @see #setBounds
+ * @see #invalidate
* @since JDK1.1
*/
public void setLocation(int x, int y) {
@@ -1976,11 +2006,16 @@
* Moves this component to a new location. The top-left corner of
* the new location is specified by point p. Point
* p is given in the parent's coordinate space.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param p the point defining the top-left corner
* of the new location, given in the coordinate space of this
* component's parent
* @see #getLocation
* @see #setBounds
+ * @see #invalidate
* @since JDK1.1
*/
public void setLocation(Point p) {
@@ -2015,10 +2050,15 @@
/**
* Resizes this component so that it has width width
* and height height.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param width the new width of this component in pixels
* @param height the new height of this component in pixels
* @see #getSize
* @see #setBounds
+ * @see #invalidate
* @since JDK1.1
*/
public void setSize(int width, int height) {
@@ -2040,10 +2080,15 @@
/**
* Resizes this component so that it has width d.width
* and height d.height.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param d the dimension specifying the new size
* of this component
* @see #setSize
* @see #setBounds
+ * @see #invalidate
* @since JDK1.1
*/
public void setSize(Dimension d) {
@@ -2086,6 +2131,10 @@
* Moves and resizes this component. The new location of the top-left
* corner is specified by x and y, and the
* new size is specified by width and height.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
* @param x the new x-coordinate of this component
* @param y the new y-coordinate of this component
* @param width the new width of this component
@@ -2096,6 +2145,7 @@
* @see #setLocation(Point)
* @see #setSize(int, int)
* @see #setSize(Dimension)
+ * @see #invalidate
* @since JDK1.1
*/
public void setBounds(int x, int y, int width, int height) {
@@ -2228,12 +2278,17 @@
* position is specified by r.x and r.y,
* and its new size is specified by r.width and
* r.height
+ *
+ * This method changes layout-related information, and therefore, + * invalidates the component hierarchy. + * * @param r the new bounding rectangle for this component * @see #getBounds * @see #setLocation(int, int) * @see #setLocation(Point) * @see #setSize(int, int) * @see #setSize(Dimension) + * @see #invalidate * @since JDK1.1 */ public void setBounds(Rectangle r) { @@ -6618,8 +6673,13 @@ * native screen resource. * This method is called internally by the toolkit and should * not be called directly by programs. + *
+ * This method changes layout-related information, and therefore, + * invalidates the component hierarchy. + * * @see #isDisplayable * @see #removeNotify + * @see #invalidate * @since JDK1.0 */ public void addNotify() { @@ -8586,8 +8646,13 @@ * To set the orientation of an entire component * hierarchy, use * {@link #applyComponentOrientation applyComponentOrientation}. + *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
*
* @see ComponentOrientation
+ * @see #invalidate
*
* @author Laura Werner, IBM
* @beaninfo
@@ -8623,12 +8688,17 @@
/**
* Sets the ComponentOrientation property of this component
* and all components contained within it.
+ *
+ * This method changes layout-related information, and therefore,
+ * invalidates the component hierarchy.
+ *
*
* @param orientation the new component orientation of this component and
* the components contained within it.
* @exception NullPointerException if orientation is null.
* @see #setComponentOrientation
* @see #getComponentOrientation
+ * @see #invalidate
* @since 1.4
*/
public void applyComponentOrientation(ComponentOrientation orientation) {
diff -r 81c02474a2c9 -r 0ce65d9e45e2 jdk/src/share/classes/java/awt/Container.java
--- 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}.
*
- * Note: If a component has been added to a container that
- * has been displayed, validate must be
- * called on that container to display the new component.
- * If multiple components are being added, you can improve
- * efficiency by calling validate 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 @@
*
* This method is obsolete as of 1.1. Please use the
* method add(Component, Object) instead.
+ *
+ * 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}. *
- * Note: If a component has been added to a container that
- * has been displayed, validate must be
- * called on that container to display the new component.
- * If multiple components are being added, you can improve
- * efficiency by calling validate 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 comp
* @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-Container components.
*
+ * This method changes layout-related information, and therefore, + * invalidates the component hierarchy. + *
* Note: Not all platforms support changing the z-order of
* heavyweight components from one container into another without
* the call to removeNotify. There is no way to detect
@@ -723,6 +732,7 @@
* @exception IllegalArgumentException if adding a Window
* 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}.
*
- * Note: If a component has been added to a container that
- * has been displayed, validate must be
- * called on that container to display the new component.
- * If multiple components are being added, you can improve
- * efficiency by calling validate 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}.
*
- * Note: If a component has been added to a container that
- * has been displayed, validate must be
- * called on that container to display the new component.
- * If multiple components are being added, you can improve
- * efficiency by calling validate 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 @@
* super.addImpl(comp, constraints, index)
*
*
+ * 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
* removeLayoutComponent method.
+ *
+ * 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. * - *
- * 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
* removeLayoutComponent method.
- *
*
- * 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
* removeLayoutComponent method.
+ *
+ * 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. + *
+ * 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 @@ *
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. + *
+ * 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. + *
+ * 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 ComponentOrientation property of this container
* and all components contained within it.
+ *
+ * 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 orientation is null.
* @see Component#setComponentOrientation
* @see Component#getComponentOrientation
+ * @see #invalidate
* @since 1.4
*/
public void applyComponentOrientation(ComponentOrientation o) {