Start of AWT merge with Classpath:

	* Makefile.in: Rebuilt.
	* Makefile.am (awt_java_source_files): Reference files in
	gnu/java/awt, not gnu/gcj/awt.
	* java/awt/image/BufferedImage.java: Updated copyright.
	* java/awt/image/ComponentColorModel.java: Updated copyright.
	* java/awt/image/ComponentSampleModel.java: Updated copyright.
	* java/awt/image/DataBuffer.java: Updated copyright.
	* java/awt/image/DataBufferByte.java: Updated copyright.
	* java/awt/image/DataBufferInt.java: Updated copyright.
	* java/awt/image/DataBufferUShort.java: Updated copyright.
	* java/awt/image/IndexColorModel.java: Updated copyright.
	* java/awt/image/PackedColorModel.java: Updated copyright.
	* java/awt/image/Raster.java: Updated copyright.
	* java/awt/image/RasterOp.java: Updated copyright.
	* java/awt/image/SampleModel.java: Updated copyright.
	* java/awt/image/SinglePixelPackedSampleModel.java: Updated copyright.
	* java/awt/image/WritableRaster.java: Updated copyright.
	* java/awt/color/ColorSpace.java: Updated copyright.
	* java/awt/color/ICC_ColorSpace.java: Updated copyright
	* java/awt/color/ICC_Profile.java: Updated copyright.
	* java/awt/event/HierarchyBoundsAdapter.java: Updated copyright.
	* java/awt/event/HierarchyBoundsListener.java: Updated copyright.
	* java/awt/event/HierarchyEvent.java: Updated copyright.
	* java/awt/event/HierarchyListener.java: Updated copyright.
	* java/awt/geom/AffineTransform.java: Updated copyright.
	* java/awt/geom/Dimension2D.java: Updated copyright.
	* java/awt/geom/Ellipse2D.java: Updated copyright.
	* java/awt/geom/IllegalPathStateException.java: Updated copyright.
	* java/awt/geom/Line2D.java: Updated copyright.
	* java/awt/geom/NoninvertibleTransformException.java: Updated
	copyright.
	* java/awt/geom/PathIterator.java: Updated copyright.
	* java/awt/geom/Point2D.java: Updated copyright.
	* java/awt/geom/Rectangle2D.java: Updated copyright.
	* java/awt/geom/RectangularShape.java: Updated copyright.
	* java/awt/geom/RoundRectangle2D.java: Updated copyright.
	* java/awt/Toolkit.java: Updated import for file moves.
	* java/awt/Rectangle.java: Updated copyright; added javadoc from
	Classpath.
	(hashCode): New method from Classpath.
	* java/awt/Graphics2D.java: Updated copyright.
	* java/awt/Transparency.java: Updated copyright.
	* java/awt/Paint.java: Updated copyright.
	* java/awt/Graphics.java: New version from Classpath.
	* java/awt/EventDispatchThread.java: Updated copyright.
	* java/awt/CardLayout.java (layoutContainer): Don't skip invisible
	children.
	(gotoComponent): Wrap around on next/previous.
	* gnu/gcj/awt/BitMaskExtent.java: Removed.
	* gnu/gcj/awt/Buffers.java: Removed.
	* gnu/gcj/awt/ComponentDataBlitOp.java: Removed.
	* gnu/gcj/awt/GLightweightPeer.java: Removed.
	* gnu/java/awt/BitMaskExtent.java: Added.
	* gnu/java/awt/Buffers.java: Added.
	* gnu/java/awt/ComponentDataBlitOp.java: Added.
	* gnu/java/awt/GLightweightPeer.java: Added.
	* java/awt/geom/Line2D.java (clone): Ignore
	CloneNotSupportedException.
	* gnu/gcj/awt/GLightweightPeer.java (getColorModel): New method.
	* java/awt/Frame.java: Merged with Classpath.
	* java/awt/RenderingHints.java: Copyright update.
	* java/awt/Paint.java: Copyright update.
	* java/awt/image/DirectColorModel.java: Merged with Classpath.
	* java/awt/image/ColorModel.java: Merged with Classpath.
	* java/awt/Window.java (show): New Implementation from Classpath.
	(isShowing): Use super.isShowing().
	* java/awt/EventQueue.java: Merged with Classpath.
	* java/awt/AWTEventMulticaster.java (save): Throw
	RuntimeException.
	(saveInternal): Likewise.
	* java/awt/AWTEvent.java: Now implements Serializable.
	* java/awt/Event.java: Copyright update.
	* java/awt/peer/ComponentPeer.java: Merged with Classpath.
	* java/awt/image/BufferedImage.java: Copyright update.
	* java/awt/GraphicsConfiguration.java: Copyright update.
	* java/awt/Component.java: (addNotify): Don't call
	addNotifyContainerChildren().
	(addNotifyContainerChildren): Removed.
	(setPeer): New method from Classpath.
	(setTreeLock): Likewise.
	(setVisible): Rewrote.
	(show): Use it.
	(hide): Likewise.
	(validate): Set `valid'.
	(checkImage(Image,ImageObserver)): Implementation from Classpath.
	(createImage(ImageProducer)): Likewise.
	(prepareImage): Likewise.
	* java/awt/Container.java (addImpl): Handle case where constraint
	is not a String.  Post event via system event queue.
	(remove): Post event via system event queue.
	(validateTree): Only validate child if it is invalid.
	(getAlignmentX): Call super method as default.
	(getAlignmentY): Likewise.
	(addContainerListener): Now synchronized.
	(removeContainerListener): Likewise.
	(addNotifyContainerChildren): Now private.
	* java/awt/ComponentOrientation.java: Updated copyright.  Added
	@author.
	* java/awt/FlowLayout.java (serialVersionUID): New field.
	(setAlignment): Better exception message.
	(layoutContainer): Don't compute component's preferred size unless
	we're going to use it.
	* java/awt/BorderLayout.java (AFTER_LAST_LINE, AFTER_LINE_ENDS,
	BEFORE_FIRST_LINE, BEFORE_LINE_BEGINS): New constants.
	(firstLine, lastLine, firstItem, lastItem): New fields.
	(addLayoutComponent): Handle case where constraints is null.
	Also, handle relative locations.
	(removeLayoutComponent): Handle relative locations.
	(MIN, MAX, PREF): New constants.
	(calcCompSize): New method.
	(calcSize): New method.
	(minimumLayoutSize): Use it.
	(preferredLayoutSize): Likewise.
	(maximumLayoutSize): Likewise.
	(toString): Include more information.
	(setBounds): New method.
	(layoutContainer): Use libgcj implementation; extended to handle
	relative locations.

From-SVN: r48896

1 files changed, 430 insertions, 50 deletions

diff --git a/libjava/java/awt/Container.java b/libjava/java/awt/Container.java
index 595c6bfcf82..5fd9e942098 100644
--- a/libjava/java/awt/Container.java
+++ b/libjava/java/awt/Container.java
@@ -1,10 +1,27 @@
-/* Copyright (C) 1999, 2000  Free Software Foundation
+/* Copyright (C) 1999, 2000, 2002  Free Software Foundation
 
-   This file is part of libjava.
+This file is part of GNU Classpath.
 
-This software is copyrighted work licensed under the terms of the
-Libjava License.  Please consult the file "LIBJAVA_LICENSE" for
-details.  */
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
 
 package java.awt;
 
@@ -31,21 +48,46 @@ public class Container extends Component
   /* Anything else is non-serializable, and should be declared "transient". */
   transient ContainerListener containerListener;  
 
+  /**
+   * Default constructor for subclasses.
+   */
   public Container()
   {
   }
 
+  /**
+   * Returns the number of components in this container.
+   *
+   * @return The number of components in this container.
+   */
   public int getComponentCount()
   {
     return ncomponents;
   }
 
-  /** @deprecated Use getComponentCount() instead. */
+  /**
+   * Returns the number of components in this container.
+   *
+   * @return The number of components in this container.
+   *
+   * @deprecated This method is deprecated in favor of 
+   * <code>getComponentCount()</code>.
+   */
   public int countComponents()
   {
     return ncomponents;
   }
 
+  /**
+   * Returns the component at the specified index.
+   *
+   * @param index The index of the component to retrieve.
+   *
+   * @return The requested component.
+   *
+   * @exception ArrayIndexOutOfBoundsException If the specified index is not
+   * valid.
+   */
   public Component getComponent (int n)
   {
     if (n < 0 || n >= ncomponents)
@@ -53,6 +95,11 @@ public class Container extends Component
     return component[n];
   }
 
+  /**
+   * Returns an array of the components in this container.
+   *
+   * @return The components in this container.
+   */
   public Component[] getComponents()
   {
     Component[] result = new Component[ncomponents];
@@ -61,51 +108,130 @@ public class Container extends Component
     return result;
   }
 
+  /**
+   * Returns the insets for this container, which is the space used for
+   * borders, the margin, etc.
+   *
+   * @return The insets for this container.
+   */
   public Insets getInsets()
   {
     if (peer == null)
-	return new Insets(0, 0, 0, 0);
-	
+      return new Insets(0, 0, 0, 0);
     return ((ContainerPeer) peer).getInsets();
   }
 
-  /** @deprecated Use getInsets() instead. */
+  /**
+   * Returns the insets for this container, which is the space used for
+   * borders, the margin, etc.
+   *
+   * @return The insets for this container.
+   *
+   * @deprecated This method is deprecated in favor of
+   * <code>getInsets()</code>.
+   */
   public Insets insets()
   {
     return getInsets();
   }
-  
+
+  /**
+   * Adds the specified component to this container at the end of the
+   * component list.
+   *
+   * @param component The component to add to the container.
+   *
+   * @return The same component that was added.
+   */
   public Component add (Component comp)
   {
     addImpl (comp, null, -1);
     return comp;
   }
 
+  /**
+   * Adds the specified component to the container at the end of the
+   * component list.  This method should not be used. Instead, use
+   * <code>add(Component, Object</code>.
+   *
+   * @param name FIXME
+   * @param component The component to be added.
+   *
+   * @return The same component that was added.
+   */
   public Component add (String name, Component comp)
   {
     addImpl (comp, name, -1);
     return comp;
   }
 
+  /**
+   * Adds the specified component to this container at the specified index
+   * in the component list.
+   *
+   * @param component The component to be added.
+   * @param index The index in the component list to insert this child
+   * at, or -1 to add at the end of the list.
+   *
+   * @return The same component that was added.
+   *
+   * @param throws ArrayIndexOutOfBounds If the specified index is invalid.
+   */
   public Component add (Component comp, int index)
   {
     addImpl (comp, null, index);
     return comp;
   }
 
+  /**
+   * Adds the specified component to this container at the end of the
+   * component list.  The layout manager will use the specified constraints
+   * when laying out this component.
+   *
+   * @param component The component to be added to this container.
+   * @param constraints The layout constraints for this component.
+   */
   public void add (Component comp, Object constraints)
   {
     addImpl (comp, constraints, -1);
   }
 
+  /**
+   * Adds the specified component to this container at the specified index
+   * in the component list.  The layout manager will use the specified
+   * constraints when layout out this component.
+   *
+   * @param component The component to be added.
+   * @param constraints The layout constraints for this component.
+   * @param index The index in the component list to insert this child
+   * at, or -1 to add at the end of the list.
+   *
+   * @param throws ArrayIndexOutOfBounds If the specified index is invalid.
+   */
   public void add (Component comp, Object constraints, int index)
   {
     addImpl (comp, constraints, index);
   }
 
+  /**
+   * This method is called by all the <code>add()</code> methods to perform
+   * the actual adding of the component.  Subclasses who wish to perform
+   * their own processing when a component is added should override this
+   * method.  Any subclass doing this must call the superclass version of
+   * this method in order to ensure proper functioning of the container.
+   *
+   * @param component The component to be added.
+   * @param constraints The layout constraints for this component, or
+   * <code>null</code> if there are no constraints.
+   * @param index The index in the component list to insert this child
+   * at, or -1 to add at the end of the list.
+   *
+   * @param throws ArrayIndexOutOfBounds If the specified index is invalid.
+   */
   protected void addImpl (Component comp, Object constraints, int index)
   {
     if (index > ncomponents
+	|| (index < 0 && index != -1)
 	|| comp instanceof Window
 	|| (comp instanceof Container
 	    && ((Container) comp).isAncestorOf (this)))
@@ -151,21 +277,29 @@ public class Container extends Component
     // Notify the layout manager.
     if (layoutMgr != null)
       {
-	if (constraints != null && layoutMgr instanceof LayoutManager2)
+	if (layoutMgr instanceof LayoutManager2)
 	  {
 	    LayoutManager2 lm2 = (LayoutManager2) layoutMgr;
 	    lm2.addLayoutComponent (comp, constraints);
 	  }
-	else
+	else if (constraints instanceof String)
 	  layoutMgr.addLayoutComponent ((String) constraints, comp);
+	else
+	  layoutMgr.addLayoutComponent (null, comp);
       }
 
+    // Post event to notify of adding the container.
     ContainerEvent ce = new ContainerEvent (this,
 					    ContainerEvent.COMPONENT_ADDED,
 					    comp);
-    dispatchEvent (ce);
+    getToolkit().getSystemEventQueue().postEvent(ce);
   }
 
+  /**
+   * Removes the component at the specified index from this container.
+   *
+   * @param index The index of the component to remove.
+   */
   public void remove (int index)
   {
     Component r = component[index];
@@ -181,12 +315,18 @@ public class Container extends Component
     if (layoutMgr != null)
       layoutMgr.removeLayoutComponent (r);
 
+    // Post event to notify of adding the container.
     ContainerEvent ce = new ContainerEvent (this,
 					    ContainerEvent.COMPONENT_REMOVED,
 					    r);
-    dispatchEvent (ce);
+    getToolkit().getSystemEventQueue().postEvent(ce);
   }
 
+  /**
+   * Removes the specified component from this container.
+   *
+   * @return component The component to remove from this container.
+   */
   public void remove (Component comp)
   {
     for (int i = 0; i < ncomponents; ++i)
@@ -199,51 +339,89 @@ public class Container extends Component
       }
   }
 
+  /**
+   * Removes all components from this container.
+   */
   public void removeAll()
   {
     while (ncomponents > 0)
       remove (0);
   }
 
+  /**
+   * Returns the current layout manager for this container.
+   *
+   * @return The layout manager for this container.
+   */
   public LayoutManager getLayout()
   {
     return layoutMgr;
   }
 
+  /**
+   * Sets the layout manager for this container to the specified layout
+   * manager.
+   *
+   * @param mgr The new layout manager for this container.
+   */
   public void setLayout(LayoutManager mgr)
   {
     layoutMgr = mgr;
     invalidate ();
   }
 
+  /**
+   * Layout the components in this container.
+   */
   public void doLayout()
   {
     if (layoutMgr != null)
       layoutMgr.layoutContainer (this);
   }
 
-  /** @deprecated Use doLayout() instead. */
+  /**
+   * Layout the components in this container.
+   *
+   * @deprecated This method is deprecated in favor of
+   * <code>doLayout()</code>.
+   */
   public void layout()
   {
     doLayout();
   }
 
+  /**
+   * Invalidates this container to indicate that it (and all parent
+   * containers) need to be laid out.
+   */
   public void invalidate()
   {
     super.invalidate ();
   }
 
+  /**
+   * Re-lays out the components in this container.
+   */
   public void validate()
   {
-    if (! isValid ())
+    // FIXME: use the tree lock?
+    synchronized (this)
       {
-	validateTree ();
+	if (! isValid ())
+	  {
+	    validateTree ();
+	  }
       }
   }
 
+  /**
+   * Recursively validates the container tree, recomputing any invalid
+   * layouts.
+   */
   protected void validateTree()
   {
-    if (valid) return; 
+    if (valid)
+      return; 
 
     ContainerPeer cPeer = null;
     if ((peer != null) && !(peer instanceof LightweightPeer))
@@ -256,16 +434,19 @@ public class Container extends Component
     for (int i = 0; i < ncomponents; ++i)
       {
 	Component comp = component[i];
-	if (comp instanceof Container)
-	  {
-	    ((Container) comp).validateTree();
-	  }
-	else
+	if (! comp.isValid ())
 	  {
-	    component[i].validate();
+	    if (comp instanceof Container)
+	      {
+		((Container) comp).validateTree();
+	      }
+	    else
+	      {
+		component[i].validate();
+	      }
 	  }
       }
-    
+
     /* children will call invalidate() when they are layed out. It
        is therefore imporant that valid is not set to true
        before after the children has been layed out. */
@@ -281,6 +462,11 @@ public class Container extends Component
     // FIXME, should invalidate all children with font == null
   }
 
+  /**
+   * Returns the preferred size of this container.
+   *
+   * @return The preferred size of this container.
+   */
   public Dimension getPreferredSize()
   {
     if (layoutMgr != null)
@@ -288,13 +474,25 @@ public class Container extends Component
     else
       return super.getPreferredSize ();
   }
-  
-  /** @deprecated Use getPreferredSize() instead */
+
+  /**
+   * Returns the preferred size of this container.
+   *
+   * @return The preferred size of this container.
+   * 
+   * @deprecated This method is deprecated in favor of 
+   * <code>getPreferredSize()</code>.
+   */
   public Dimension preferredSize()
   {
     return getPreferredSize();
   }
-  
+
+  /**
+   * Returns the minimum size of this container.
+   *
+   * @return The minimum size of this container.
+   */
   public Dimension getMinimumSize()
   {
     if (layoutMgr != null)
@@ -302,13 +500,25 @@ public class Container extends Component
     else
       return super.getMinimumSize ();
   }
-  
-  /** @deprecated Use getMinimumSize() instead */
+
+  /**
+   * Returns the minimum size of this container.
+   *
+   * @return The minimum size of this container.
+   * 
+   * @deprecated This method is deprecated in favor of 
+   * <code>getMinimumSize()</code>.
+   */
   public Dimension minimumSize()
   {
     return getMinimumSize();
   }
-  
+
+  /**
+   * Returns the maximum size of this container.
+   *
+   * @return The maximum size of this container.
+   */
   public Dimension getMaximumSize()
   {
     if (layoutMgr != null && layoutMgr instanceof LayoutManager2)
@@ -320,6 +530,13 @@ public class Container extends Component
       return super.getMaximumSize ();
   }
 
+  /**
+   * Returns the preferred alignment along the X axis.  This is a value
+   * between 0 and 1 where 0 represents alignment flush left and
+   * 1 means alignment flush right, and 0.5 means centered.
+   *
+   * @return The preferred alignment along the X axis.
+   */
   public float getAlignmentX()
   {
     if (layoutMgr instanceof LayoutManager2)
@@ -328,9 +545,16 @@ public class Container extends Component
 	return lm2.getLayoutAlignmentX (this);
       }
     else
-      return CENTER_ALIGNMENT;
+      return super.getAlignmentX();
   }
 
+  /**
+   * Returns the preferred alignment along the Y axis.  This is a value
+   * between 0 and 1 where 0 represents alignment flush top and
+   * 1 means alignment flush bottom, and 0.5 means centered.
+   *
+   * @return The preferred alignment along the Y axis.
+   */
   public float getAlignmentY()
   {
     if (layoutMgr instanceof LayoutManager2)
@@ -339,9 +563,18 @@ public class Container extends Component
 	return lm2.getLayoutAlignmentY (this);
       }
     else
-      return CENTER_ALIGNMENT;
+      return super.getAlignmentY();
   }
 
+  /**
+   * Paints this container.  The implementation of this method in this
+   * class forwards to any lightweight components in this container.  If
+   * this method is subclassed, this method should still be invoked as
+   * a superclass method so that lightweight components are properly
+   * drawn.
+   *
+   * @param graphics The graphics context for this paint job.
+   */
   public void paint(Graphics g)
   {
     if (!isShowing())
@@ -365,7 +598,7 @@ public class Container extends Component
    * be visited.
    */
   private void visitChildren(Graphics gfx, GfxVisitor visitor,
-		     boolean lightweightOnly)
+			     boolean lightweightOnly)
   {
     // FIXME: do locking
 
@@ -408,29 +641,57 @@ public class Container extends Component
     visitor.visit(comp, gfx2);
   }
 
+  /**
+   * Updates this container.  The implementation of this method in this
+   * class forwards to any lightweight components in this container.  If
+   * this method is subclassed, this method should still be invoked as
+   * a superclass method so that lightweight components are properly
+   * drawn.
+   *
+   * @param graphics The graphics context for this update.
+   */
   public void update(Graphics g)
   {
     super.update(g);
   }
 
+  /**
+   * Prints this container.  The implementation of this method in this
+   * class forwards to any lightweight components in this container.  If
+   * this method is subclassed, this method should still be invoked as
+   * a superclass method so that lightweight components are properly
+   * drawn.
+   *
+   * @param graphics The graphics context for this print job.
+   */
   public void print(Graphics g)
   {
     super.print(g);
     visitChildren(g, GfxPrintVisitor.INSTANCE, true);
   }
 
+  /**
+   * Paints all of the components in this container.
+   *
+   * @param graphics The graphics context for this paint job.
+   */
   public void paintComponents(Graphics g)
   {
     super.paint(g);
     visitChildren(g, GfxPaintAllVisitor.INSTANCE, true);
   }
 
+  /**
+   * Prints all of the components in this container.
+   *
+   * @param graphics The graphics context for this print job.
+   */
   public void printComponents(Graphics g)
   {
     super.paint(g);
     visitChildren(g, GfxPrintAllVisitor.INSTANCE, true);
   }
-  
+
   void dispatchEventImpl(AWTEvent e)
   {
     if ((e.id <= ContainerEvent.CONTAINER_LAST
@@ -438,15 +699,28 @@ public class Container extends Component
 	&& (containerListener != null
 	    || (eventMask & AWTEvent.CONTAINER_EVENT_MASK) != 0))
       processEvent(e); 
-    else super.dispatchEventImpl(e);
+    else
+      super.dispatchEventImpl(e);
   }  
 
-  public void addContainerListener(ContainerListener l)
+  /**
+   * Adds the specified container listener to this object's list of
+   * container listeners.
+   *
+   * @param listener The listener to add.
+   */
+  public synchronized void addContainerListener(ContainerListener l)
   {
     containerListener = AWTEventMulticaster.add (containerListener, l);
   }
 
-  public void removeContainerListener(ContainerListener l)
+  /**
+   * Removes the specified container listener from this object's list of
+   * container listeners.
+   *
+   * @param listener The listener to remove.
+   */
+  public synchronized void removeContainerListener(ContainerListener l)
   {
     containerListener = AWTEventMulticaster.remove(containerListener, l);
   }
@@ -458,35 +732,70 @@ public class Container extends Component
       return getListenersImpl(listenerType, containerListener);
     else return super.getListeners(listenerType);
   }
-  
+
+  /**
+   * Processes the specified event.  This method calls
+   * <code>processContainerEvent()</code> if this method is a
+   * <code>ContainerEvent</code>, otherwise it calls the superclass
+   * method.
+   *
+   * @param event The event to be processed.
+   */
   protected void processEvent(AWTEvent e)
   {
     if (e instanceof ContainerEvent)
       processContainerEvent((ContainerEvent) e);
     else super.processEvent(e);
   }
-  
+
+  /**
+   * Called when a container event occurs if container events are enabled.
+   * This method calls any registered listeners.
+   *
+   * @param event The event that occurred.
+   */
   protected void processContainerEvent(ContainerEvent e)
   {
     if (containerListener == null)
       return;
     switch (e.id)
       {
-	case ContainerEvent.COMPONENT_ADDED:
-	  containerListener.componentAdded(e);
+      case ContainerEvent.COMPONENT_ADDED:
+	containerListener.componentAdded(e);
 	break;
 
-	case ContainerEvent.COMPONENT_REMOVED:
-	  containerListener.componentRemoved(e);
+      case ContainerEvent.COMPONENT_REMOVED:
+	containerListener.componentRemoved(e);
 	break;    
       }
   }
 
-  /** @deprecated */
+  /**
+   * AWT 1.0 event processor.
+   *
+   * @param event The event that occurred.
+   *
+   * @deprecated This method is deprecated in favor of 
+   * <code>dispatchEvent()</code>.
+   */
   public void deliverEvent(Event e)
   {
   }
-  
+
+  /**
+   * Returns the component located at the specified point.  This is done
+   * by checking whether or not a child component claims to contain this
+   * point.  The first child component that does is returned.  If no
+   * child component claims the point, the container itself is returned,
+   * unless the point does not exist within this container, in which
+   * case <code>null</code> is returned.
+   *
+   * @param x The X coordinate of the point.
+   * @param y The Y coordinate of the point.
+   *
+   * @return The component containing the specified point, or
+   * <code>null</code> if there is no such point.
+   */
   public Component getComponentAt (int x, int y)
   {
     if (! contains (x, y))
@@ -505,12 +814,40 @@ public class Container extends Component
     return this;
   }
 
-  /** @deprecated Use getComponentAt() instead */
+  /**
+   * Returns the component located at the specified point.  This is done
+   * by checking whether or not a child component claims to contain this
+   * point.  The first child component that does is returned.  If no
+   * child component claims the point, the container itself is returned,
+   * unless the point does not exist within this container, in which
+   * case <code>null</code> is returned.
+   *
+   * @param point The point to return the component at.
+   *
+   * @return The component containing the specified point, or <code>null</code>
+   * if there is no such point.
+   *
+   * @deprecated This method is deprecated in favor of
+   * <code>getComponentAt(int, int)</code>.
+   */
   public Component locate(int x, int y)
   {
     return getComponentAt(x, y);
   }
 
+  /**
+   * Returns the component located at the specified point.  This is done
+   * by checking whether or not a child component claims to contain this
+   * point.  The first child component that does is returned.  If no
+   * child component claims the point, the container itself is returned,
+   * unless the point does not exist within this container, in which
+   * case <code>null</code> is returned.
+   *
+   * @param point The point to return the component at.
+   *
+   * @return The component containing the specified point, or <code>null</code>
+   * if there is no such point.
+   */
   public Component getComponentAt(Point p)
   {
     return getComponentAt(p.x, p.y);
@@ -550,12 +887,21 @@ public class Container extends Component
     return findComponentAt(p.x, p.y);
   }
 
+  /**
+   * Called when this container is added to another container to inform it
+   * to create its peer.  Peers for any child components will also be
+   * created.
+   */
   public void addNotify ()
   {
-    super.addNotify();
+    if (peer == null)
+      {
+	addNotifyContainerChildren ();
+	super.addNotify();
+      }
   }
 
-  void addNotifyContainerChildren()
+  private void addNotifyContainerChildren()
   {
     for (int i = ncomponents;  --i >= 0; )
       {
@@ -565,6 +911,11 @@ public class Container extends Component
       }
   }
 
+  /**
+   * Called when this container is removed from its parent container to
+   * inform it to destroy its peer.  This causes the peers of all child
+   * component to be destroyed as well.
+   */
   public void removeNotify()
   {
     for (int i = 0; i < ncomponents; ++i)
@@ -572,6 +923,15 @@ public class Container extends Component
     super.removeNotify();
   }
 
+  /**
+   * Tests whether or not the specified component is contained within
+   * this components subtree.
+   *
+   * @param component The component to test.
+   *
+   * @return <code>true</code> if this container is an ancestor of the
+   * specified component, <code>false</code>.
+   */
   public boolean isAncestorOf (Component comp)
   {
     for (;;)
@@ -584,6 +944,12 @@ public class Container extends Component
       }
   }
 
+  /**
+   * Returns a string representing the state of this container for
+   * debugging purposes.
+   *
+   * @return A string representing the state of this container.
+   */
   protected String paramString()
   {
     String param = super.paramString();
@@ -592,7 +958,14 @@ public class Container extends Component
 
     return param;
   }
-  
+
+  /**
+   * Writes a listing of this container to the specified stream starting
+   * at the specified indentation point.
+   *
+   * @param stream The <code>PrintStream</code> to write to.
+   * @param indent The indentation point.
+   */
   public void list (PrintStream out, int indent)
   {
     super.list (out, indent);
@@ -600,6 +973,13 @@ public class Container extends Component
       component[i].list (out, indent + 2);
   }
 
+  /**
+   * Writes a listing of this container to the specified stream starting
+   * at the specified indentation point.
+   *
+   * @param stream The <code>PrintWriter</code> to write to.
+   * @param indent The indentation point.
+   */
   public void list(PrintWriter out, int indent)
   {
     super.list (out, indent);