diff options
Diffstat (limited to 'libjava/java/awt/Container.java')
| -rw-r--r-- | libjava/java/awt/Container.java | 480 |
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); |