diff options
Diffstat (limited to 'libjava/java/awt/Component.java')
| -rw-r--r-- | libjava/java/awt/Component.java | 1165 |
1 files changed, 1012 insertions, 153 deletions
diff --git a/libjava/java/awt/Component.java b/libjava/java/awt/Component.java index 0feb69451aa..8f79f8a1d66 100644 --- a/libjava/java/awt/Component.java +++ b/libjava/java/awt/Component.java @@ -1,10 +1,27 @@ -/* Copyright (C) 1999, 2000, 2001 Free Software Foundation +/* Copyright (C) 1999, 2000, 2001, 2002 Free Software Foundation - This file is part of libgcj. +This file is part of GNU Classpath. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_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; import java.awt.event.*; @@ -34,13 +51,41 @@ import java.beans.PropertyChangeListener; public abstract class Component implements ImageObserver, MenuContainer, java.io.Serializable { + /** + * Constant returned by the <code>getAlignmentY</code> method to indicate + * that the component wishes to be aligned to the bottom relative to + * other components. + */ + public static final float BOTTOM_ALIGNMENT = (float)1.0; + + /** + * Constant returned by the <code>getAlignmentY</code> and + * <code>getAlignmentX</code> methods to indicate + * that the component wishes to be aligned to the center relative to + * other components. + */ + public static final float CENTER_ALIGNMENT = (float)0.5; + + /** + * Constant returned by the <code>getAlignmentY</code> method to indicate + * that the component wishes to be aligned to the top relative to + * other components. + */ + public static final float TOP_ALIGNMENT = (float)0.0; - /* Constants for use with getAlignmentX()/getAlignmentY(). */ - public static final float BOTTOM_ALIGNMENT = 1.0f, - CENTER_ALIGNMENT = 0.5f, - LEFT_ALIGNMENT = 0.0f, - RIGHT_ALIGNMENT = 1.0f, - TOP_ALIGNMENT = 0.0f; + /** + * Constant returned by the <code>getAlignmentX</code> method to indicate + * that the component wishes to be aligned to the right relative to + * other components. + */ + public static final float RIGHT_ALIGNMENT = (float)1.0; + + /** + * Constant returned by the <code>getAlignmentX</code> method to indicate + * that the component wishes to be aligned to the left relative to + * other components. + */ + public static final float LEFT_ALIGNMENT = (float)0.0; /* Make the treelock a String so that it can easily be identified in debug dumps. We clone the String in order to avoid a conflict in @@ -92,17 +137,30 @@ public abstract class Component implements ImageObserver, MenuContainer, transient ComponentOrientation orientation = ComponentOrientation.UNKNOWN; + /** + * Default constructor for subclasses. + */ protected Component() { } + /** + * Returns the name of this component. + * + * @return The name of this component. + */ public String getName() { if (name == null && !nameExplicitlySet) name = generateName(); return name; } - + + /** + * Sets the name of this component to the specified name. + * + * @param name The new name of this component. + */ public void setName(String name) { nameExplicitlySet = true; @@ -117,19 +175,35 @@ public abstract class Component implements ImageObserver, MenuContainer, // Component is abstract. return null; } - + + /** + * Returns the parent of this component. + * + * @return The parent of this component. + */ public Container getParent() { return parent; } - - /** @deprecated */ - // However, Classpath's Gtk peers rely on it. + + // Sets the peer for this component. + final void setPeer (ComponentPeer peer) + { + this.peer = peer; + } + + /** + * Returns the native windowing system peer for this component. + * + * @return The peer for this component. + * @deprecated + */ + // Classpath's Gtk peers rely on this. public java.awt.peer.ComponentPeer getPeer() { return peer; } - + // FIXME: java.awt.dnd classes not yet implemented /* public void setDropTarget(DropTarget dt) @@ -167,11 +241,28 @@ public abstract class Component implements ImageObserver, MenuContainer, return null; } + /** + * Returns the object used for synchronization locks on this component + * when performing tree and layout functions. + * + * @return The synchronization lock for this component. + */ public final Object getTreeLock() { return treeLock; } + // The sync lock object for this component. + final void setTreeLock(Object tree_lock) + { + this.treeLock = tree_lock; + } + + /** + * Returns the toolkit in use for this component. + * + * @return The toolkit for this component. + */ public Toolkit getToolkit() { if (peer != null) @@ -185,6 +276,13 @@ public abstract class Component implements ImageObserver, MenuContainer, return Toolkit.getDefaultToolkit (); } + /** + * Tests whether or not this component is valid. A invalid component needs + * to have its layout redone. + * + * @return <code>true</code> if this component is valid, <code>false</code> + * otherwise. + */ public boolean isValid() { return valid; @@ -197,12 +295,26 @@ public abstract class Component implements ImageObserver, MenuContainer, return parent.isDisplayable(); return false; } - + + /** + * Tests whether or not this component is visible. + * + * @return <code>true</code> if the component is visible, + * <code>false</code> otherwise. + */ public boolean isVisible() { return visible; } - + + /** + * Tests whether or not this component is actually being shown on + * the screen. This will be true if and only if it this component is + * visible and its parent components are all visible. + * + * @return <code>true</code> if the component is showing on the screen, + * <code>false</code> otherwise. + */ public boolean isShowing() { if (! visible || peer == null) @@ -210,82 +322,132 @@ public abstract class Component implements ImageObserver, MenuContainer, return parent == null ? true : parent.isShowing (); } - + + /** + * Tests whether or not this component is enabled. + * + * @return <code>true</code> if the component is enabled, + * <code>false</code> otherwise. + */ public boolean isEnabled() { return enabled; } - + + /** + * Enables or disables this component. + * + * @param enabled <code>true</code> to enable this component, + * <code>false</code> to disable it. + * + * @deprecated Deprecated in favor of <code>setEnabled()</code>. + */ public void setEnabled(boolean b) { this.enabled = b; if (peer != null) peer.setEnabled(b); } - - /** @deprecated */ + + /** + * Enables this component. + * + * @deprecated Deprecated in favor of <code>setEnabled()</code>. + */ public void enable() { setEnabled(true); } - - /** @deprecated */ + + /** + * Enables or disables this component. + * + * @param enabled <code>true</code> to enable this component, + * <code>false</code> to disable it. + * + * @deprecated Deprecated in favor of <code>setEnabled()</code>. + */ public void enable(boolean b) { setEnabled(b); } - - /** @deprecated */ + + /** + * Disables this component. + * + * @deprecated Deprecated in favor of <code>setEnabled()</code>. + */ public void disable() { setEnabled(false); } - + public boolean isDoubleBuffered() { return false; } - + /** @since 1.2 */ public void enableInputMethods(boolean enable) { // FIXME } - - /** @specnote Inspection by subclassing shows that Sun's implementation - calls show(boolean) which then calls show() or hide(). It is - the show() method that is overriden in subclasses like Window. - We do the same to preserve compatibility for subclasses. */ + + /** + * Makes this component visible or invisible. + * + * @param visible <code>true</code> to make this component visible, + * </code>false</code> to make it invisible. + * @specnote Inspection by subclassing shows that Sun's implementation + * calls show(boolean) which then calls show() or hide(). It is + * the show() method that is overriden in subclasses like Window. + * We do the same to preserve compatibility for subclasses. + */ public void setVisible(boolean b) { - show (b); + if (peer != null) + peer.setVisible (b); + this.visible = b; } - - /** @deprecated */ + + /** + * Makes this component visible on the screen. + * + * @deprecated Deprecated in favor of <code>setVisible()</code>. + */ public void show() { - if (peer != null) - peer.setVisible(true); - this.visible = true; + setVisible (true); } - - /** @deprecated */ + + /** + * Makes this component visible or invisible. + * + * @param visible <code>true</code> to make this component visible, + * </code>false</code> to make it invisible. + * + * @deprecated Deprecated in favor of <code>setVisible()</code>. + */ public void show(boolean b) { - if (b) - show(); - else - hide(); + setVisible (b); } - - /** @deprecated */ + + /** + * Hides this component so that it is no longer shown on the screen. + * + * @deprecated Deprecated in favor of <code>setVisible()</code>. + */ public void hide() { - if (peer != null) - peer.setVisible(false); - this.visible = false; + setVisible (false); } - + + /** + * Returns this component's foreground color. + * + * @return This component's foreground color. + */ public Color getForeground() { if (foreground != null) @@ -294,7 +456,12 @@ public abstract class Component implements ImageObserver, MenuContainer, return parent.getForeground(); return null; } - + + /** + * Sets this component's foreground color to the specified color. + * + * @param foreground_color The new foreground color. + */ public void setForeground(Color c) { if (peer != null) @@ -302,10 +469,14 @@ public abstract class Component implements ImageObserver, MenuContainer, this.foreground = c; } - /** @return the background color of the component. null may be - returned instead of the actual background color, if this - method is called before the component is added to the - component hierarchy. */ + /** + * Returns this component's background color. + * + * @return the background color of the component. null may be + * returned instead of the actual background color, if this + * method is called before the component is added to the + * component hierarchy. + */ public Color getBackground() { if (background != null) @@ -314,14 +485,24 @@ public abstract class Component implements ImageObserver, MenuContainer, return parent.getBackground(); return null; } - + + /** + * Sets this component's background color to the specified color. + * + * @param background_color The new background color + */ public void setBackground(Color c) { if (peer != null) peer.setBackground(c); this.background = c; } - + + /** + * Returns the font in use for this component. + * + * @return The font for this component. + */ public Font getFont() { if (font != null) @@ -330,7 +511,12 @@ public abstract class Component implements ImageObserver, MenuContainer, return parent.getFont(); return null; } - + + /** + * Sets the font for this component to the specified font. + * + * @param font The new font for this component. + */ public void setFont(Font f) { if (peer != null) @@ -338,6 +524,13 @@ public abstract class Component implements ImageObserver, MenuContainer, this.font = f; } + /** + * Returns the locale for this component. If this component does not + * have a locale, the locale of the parent component is returned. If the + * component has no parent, the system default locale is returned. + * + * @return The locale for this component. + */ public Locale getLocale() throws IllegalComponentStateException { if (locale != null) @@ -347,16 +540,26 @@ public abstract class Component implements ImageObserver, MenuContainer, ("Component has no parent: Can not determine Locale"); return parent.getLocale(); } - + + /** + * Sets the locale for this component to the specified locale. + * + * @param locale The new locale for this component. + */ public void setLocale(Locale l) { this.locale = l; - + /* new writing/layout direction perhaps, or make more/less room for localized text labels */ invalidate(); } - + + /** + * Returns the color model of the device this componet is displayed on. + * + * @return This object's color model. + */ public ColorModel getColorModel() { GraphicsConfiguration config = getGraphicsConfiguration(); @@ -367,11 +570,23 @@ public abstract class Component implements ImageObserver, MenuContainer, return getToolkit().getColorModel(); } + /** + * Returns the location of this component's top left corner relative to + * its parent component. + * + * @return The location of this component. + */ public Point getLocation() { return new Point(x, y); } + /** + * Returns the location of this component's top left corner in screen + * coordinates. + * + * @return The location of this component in screen coordinates. + */ public Point getLocationOnScreen() { if (! isShowing ()) @@ -381,47 +596,93 @@ public abstract class Component implements ImageObserver, MenuContainer, return peer.getLocationOnScreen (); } - /** @deprecated Use getLocation() instead. */ + /** + * Returns the location of this component's top left corner relative to + * its parent component. + * + * @return The location of this component. + * + * @deprecated This method is deprecated in favor of + * <code>getLocation()</code>. + */ public Point location() { return getLocation(); } + /** + * Moves this component to the specified location. The coordinates are + * the new upper left corner of this component. + * + * @param x The new X coordinate of this component. + * @param y The new Y coordinate of this component. + */ public void setLocation (int x, int y) { if ((this.x == x) && (this.y == y)) return; - + invalidate(); - + this.x = x; this.y = y; if (peer != null) peer.setBounds(x, y, width, height); } - /** @deprecated */ + /** + * Moves this component to the specified location. The coordinates are + * the new upper left corner of this component. + * + * @param x The new X coordinate of this component. + * @param y The new Y coordinate of this component. + * + * @deprecated Deprecated in favor for <code>setLocation</code>. + */ public void move(int x, int y) { setLocation(x,y); } - + + /** + * Moves this component to the specified location. The coordinates are + * the new upper left corner of this component. + * + * @param p New coordinates for this component. + */ public void setLocation(Point p) { setLocation(p.x, p.y); } - + + /** + * Returns the size of this object. + * + * @return The size of this object. + */ public Dimension getSize() { return new Dimension(width, height); } - - /** @deprecated */ + + /** + * Returns the size of this object. + * + * @return The size of this object. + * + * @deprecated This method is deprecated in favor of <code>getSize</code>. + */ public Dimension size() { return getSize(); } - + + /** + * Sets the size of this component to the specified width and height. + * + * @param width The new width of this component. + * @param height The new height of this component. + */ public void setSize(int width, int height) { if ((this.width == width) && (this.height == height)) @@ -434,35 +695,78 @@ public abstract class Component implements ImageObserver, MenuContainer, if (peer != null) peer.setBounds(x, y, width, height); } - - /** @deprecated */ + + /** + * Sets the size of this component to the specified value. + * + * @param width The new width of the component. + * @param height The new height of the component. + * + * @deprecated This method is deprecated in favor of <code>setSize</code>. + */ public void resize(int width, int height) { setSize(width, height); } - + + /** + * Sets the size of this component to the specified value. + * + * @param dim The new size of this component. + */ public void setSize(Dimension d) { setSize(d.width, d.height); } - /** @deprecated */ + /** + * Sets the size of this component to the specified value. + * + * @param dim The new size of this component. + * + * @deprecated This method is deprecated in favor of <code>setSize</code>. + */ public void resize(Dimension d) { setSize(d.width, d.height); } + /** + * Returns a bounding rectangle for this component. Note that the + * returned rectange is relative to this component's parent, not to + * the screen. + * + * @return The bounding rectangle for this component. + */ public Rectangle getBounds() { return new Rectangle (x, y, width, height); } - /** @deprecated */ + /** + * Returns a bounding rectangle for this component. Note that the + * returned rectange is relative to this component's parent, not to + * the screen. + * + * @return The bounding rectangle for this component. + * + * @deprecated Deprecated in favor of <code>getBounds()</code>. + */ public Rectangle bounds() { return getBounds(); } - + + /** + * Sets the bounding rectangle for this component to the specified + * values. Note that these coordinates are relative to the parent, + * not to the screen. + * + * @param x The X coordinate of the upper left corner of the rectangle. + * @param y The Y coordinate of the upper left corner of the rectangle. + * @param width The width of the rectangle. + * @param height The height of the rectangle. + */ public void setBounds(int x, int y, int w, int h) { if (this.x == x @@ -481,13 +785,32 @@ public abstract class Component implements ImageObserver, MenuContainer, if (peer != null) peer.setBounds(x, y, w, h); } - - /** @deprecated */ + + /** + * Sets the bounding rectangle for this component to the specified + * values. Note that these coordinates are relative to the parent, + * not to the screen. + * + * @param x The X coordinate of the upper left corner of the rectangle. + * @param y The Y coordinate of the upper left corner of the rectangle. + * @param width The width of the rectangle. + * @param height The height of the rectangle. + * + * @deprecated This method is deprecated in favor of + * <code>setBounds(int, int, int, int)</code>. + */ public void reshape(int x, int y, int width, int height) { setBounds(x, y, width, height); } - + + /** + * Sets the bounding rectangle for this component to the specified + * rectangle. Note that these coordinates are relative to the parent, + * not to the screen. + * + * @param bounding_rectangle The new bounding rectangle. + */ public void setBounds(Rectangle r) { setBounds(r.x, r.y, r.width, r.height); @@ -557,7 +880,12 @@ public abstract class Component implements ImageObserver, MenuContainer, { return (peer != null) && (peer instanceof LightweightPeer); } - + + /** + * Returns the component's preferred size. + * + * @return The component's preferred size. + */ public Dimension getPreferredSize() { if (peer == null) @@ -566,12 +894,23 @@ public abstract class Component implements ImageObserver, MenuContainer, return peer.getPreferredSize(); } - /** @deprecated */ + /** + * Returns the component's preferred size. + * + * @return The component's preferred size. + * + * @deprecated Deprecated in favor of <code>getPreferredSize()</code>. + */ public Dimension preferredSize() { return getPreferredSize(); } - + + /** + * Returns the component's minimum size. + * + * @return The component's minimum size. + */ public Dimension getMinimumSize() { if (peer == null) @@ -580,43 +919,82 @@ public abstract class Component implements ImageObserver, MenuContainer, return peer.getMinimumSize(); } - /** @deprecated */ + /** + * Returns the component's minimum size. + * + * @return The component's minimum size. + * + * @deprecated Deprecated in favor of <code>getMinimumSize()</code> + */ public Dimension minimumSize() { return getMinimumSize(); } + /** + * Returns the component's maximum size. + * + * @return The component's maximum size. + */ public Dimension getMaximumSize() { return new Dimension(Integer.MAX_VALUE, Integer.MAX_VALUE); } + /** + * Returns the preferred horizontal alignment of this component. The + * value returned will be one of the constants defined in this class. + * + * @return The preferred horizontal alignment of this component. + */ public float getAlignmentX() { return CENTER_ALIGNMENT; } + /** + * Returns the preferred vertical alignment of this component. The + * value returned will be one of the constants defined in this class. + * + * @return The preferred vertical alignment of this component. + */ public float getAlignmentY() { return CENTER_ALIGNMENT; } + /** + * Calls the layout manager to re-layout the component. This is called + * during validation of a container in most cases. + */ public void doLayout() { // nothing to do unless we're a container } - - /** @deprecated */ + + /** + * Calls the layout manager to re-layout the component. This is called + * during validation of a container in most cases. + * + * @deprecated This method is deprecated in favor of <code>doLayout()</code>. + */ public void layout() { doLayout(); } - + + /** + * Called to ensure that the layout for this component is valid. + */ public void validate() { - // nothing to do unless we're a container + valid = true; } - + + /** + * Invalidates this component and all of its parent components. This will + * cause them to have their layout redone. + */ public void invalidate() { valid = false; @@ -625,6 +1003,12 @@ public abstract class Component implements ImageObserver, MenuContainer, parent.invalidate (); } + /** + * Returns a graphics object for this component. Returns <code>null</code> + * if this component is not currently displayed on the screen. + * + * @return A graphics object for this component. + */ public Graphics getGraphics() { if (peer != null) @@ -646,7 +1030,14 @@ public abstract class Component implements ImageObserver, MenuContainer, } return null; } - + + /** + * Returns the font metrics for the specified font in this component. + * + * @param font The font to retrieve metrics for. + * + * @return The font metrics for the specified font. + */ public FontMetrics getFontMetrics(Font font) { if (peer == null) @@ -654,6 +1045,11 @@ public abstract class Component implements ImageObserver, MenuContainer, return peer.getFontMetrics (font); } + /** + * Sets the cursor for this component to the specified cursor. + * + * @param cursor The new cursor for this component. + */ public void setCursor(Cursor cursor) { this.cursor = cursor; @@ -661,20 +1057,45 @@ public abstract class Component implements ImageObserver, MenuContainer, peer.setCursor (cursor); } + /** + * Returns the cursor for this component. + * + * @return The cursor for this component. + */ public Cursor getCursor() { return this.cursor; } - + + /** + * Paints this component on the screen. The clipping region in the + * graphics context will indicate the region that requires painting. + * + * @param graphics The graphics context for this paint job. + */ public void paint(Graphics g) - { + { } - + + /** + * Updates this component. This method fills the component + * with the background color, then sets the foreground color of the + * specified graphics context to the foreground color of this component + * and calls the <code>paint()</code> method. + * // FIXME: What are the coords relative to? + * + * @param graphics The graphics context for this update. + */ public void update(Graphics g) { paint(g); } - + + /** + * Paints this entire component, including any sub-components. + * + * @param graphics The graphics context for this paint job. + */ public void paintAll(Graphics g) { if (!visible) @@ -684,22 +1105,60 @@ public abstract class Component implements ImageObserver, MenuContainer, peer.paint(g); paint(g); } - + + /** + * Repaint this entire component. The <code>update()</code> method + * on this component will be called as soon as possible. + * // FIXME: What are the coords relative to? + */ public void repaint() { repaint(0, 0, 0, getWidth(), getHeight()); } - + + /** + * Repaint this entire component. The <code>update()</code> method + * on this component will be called in approximate the specified number + * of milliseconds. + * // FIXME: What are the coords relative to? + * + * @param tm The number of milliseconds before this component should + * be repainted. + */ public void repaint(long tm) { repaint(tm, 0, 0, getWidth(), getHeight()); } - + + /** + * Repaints the specified rectangular region within this component. + * This <code>update</code> method on this component will be called as + * soon as possible. + * // FIXME: What are the coords relative to? + * + * @param x The X coordinate of the upper left of the region to repaint + * @param y The Y coordinate of the upper left of the region to repaint + * @param width The width of the region to repaint. + * @param height The height of the region to repaint. + */ public void repaint(int x, int y, int width, int height) { repaint(0, x, y, width, height); } - + + /** + * Repaints the specified rectangular region within this component. + * This <code>update</code> method on this component will be called in + * approximately the specified number of milliseconds. + * // FIXME: What are the coords relative to? + * + * @param tm The number of milliseconds before this component should + * be repainted. + * @param x The X coordinate of the upper left of the region to repaint + * @param y The Y coordinate of the upper left of the region to repaint + * @param width The width of the region to repaint. + * @param height The height of the region to repaint. + */ public void repaint(long tm, int x, int y, int width, int height) { // Handle lightweight repainting by forwarding to native parent @@ -714,16 +1173,46 @@ public abstract class Component implements ImageObserver, MenuContainer, peer.repaint(tm, x, y, width, height); } + /** + * Prints this component. This method is + * provided so that printing can be done in a different manner from + * painting. However, the implementation in this class simply calls + * the <code>paint()</code> method. + * + * @param graphics The graphics context of the print device. + */ public void print(Graphics g) { paint(g); } + /** + * Prints this component, including all sub-components. This method is + * provided so that printing can be done in a different manner from + * painting. However, the implementation in this class simply calls + * the <code>paintAll()</code> method. + * + * @param graphics The graphics context of the print device. + */ public void printAll(Graphics g) { paintAll(g); } + /** + * Called when an image has changed so that this component is + * repainted. + * + * @param image The image that has been updated. + * @param flags Flags as specified in <code>ImageObserver</code>. + * @param x The X coordinate + * @param y The Y coordinate + * @param width The width + * @param height The height + * + * @return <code>true</code> if the image has been fully loaded, + * <code>false</code> otherwise. + */ public boolean imageUpdate (Image img, int infoflags, int x, int y, int w, int h) { @@ -731,58 +1220,160 @@ public abstract class Component implements ImageObserver, MenuContainer, return false; } + /** + * Creates an image from the specified producer. + * + * @param producer The image procedure to create the image from. + * + * @return The resulting image. + */ public Image createImage(ImageProducer producer) { - // FIXME - return null; + return peer.createImage(producer); } + /** + * Creates an image with the specified width and height for use in + * double buffering. + * + * @param width The width of the image. + * @param height The height of the image. + * + * @return The requested image. + */ public Image createImage(int width, int height) { return getGraphicsConfiguration().createCompatibleImage(width, height); } + /** + * Prepares the specified image for rendering on this component. + * + * @param image The image to prepare for rendering. + * @param observer The image observer to notify of the status of the + * image preparation. + * + * @return <code>true</code> if the image is already fully prepared + * for rendering, <code>false</code> otherwise. + */ public boolean prepareImage(Image image, ImageObserver observer) { - // FIXME - return false; + return prepareImage(image, image.getWidth(observer), + image.getHeight(observer), observer); } - public boolean prepareImage(Image image, int width, int height, ImageObserver observer) + /** + * Prepares the specified image for rendering on this component at the + * specified scaled width and height + * + * @param image The image to prepare for rendering. + * @param width The scaled width of the image. + * @param height The scaled height of the image. + * @param observer The image observer to notify of the status of the + * image preparation. + * + * @return <code>true</code> if the image is already fully prepared + * for rendering, <code>false</code> otherwise. + */ + public boolean prepareImage(Image image, int width, int height, + ImageObserver observer) { - // FIXME - return false; + return peer.prepareImage(image, width, height, observer); } + /** + * Returns the status of the loading of the specified image. The value + * returned will be those flags defined in <code>ImageObserver</code>. + * + * @param image The image to check on. + * @param observer The observer to be notified as the image loading + * progresses. + * + * @return The image observer flags indicating the status of the load. + */ public int checkImage(Image image, ImageObserver observer) { - // FIXME - return 0; + return checkImage(image, image.getWidth(observer), + image.getHeight(observer), observer); } - public int checkImage (Image image, int width, int height, ImageObserver observer) + /** + * Returns the status of the loading of the specified image. The value + * returned will be those flags defined in <code>ImageObserver</code>. + * + * @param image The image to check on. + * @param width The scaled image width. + * @param height The scaled image height. + * @param observer The observer to be notified as the image loading + * progresses. + * + * @return The image observer flags indicating the status of the load. + */ + public int checkImage (Image image, int width, int height, + ImageObserver observer) { if (peer != null) return peer.checkImage (image, width, height, observer); return getToolkit ().checkImage (image, width, height, observer); } + /** + * Tests whether or not the specified point is contained within this + * component. Coordinates are relative to this component. + * + * @param x The X coordinate of the point to test. + * @param y The Y coordinate of the point to test. + * + * @return <code>true</code> if the point is within this component, + * <code>false</code> otherwise. + */ public boolean contains (int x, int y) { return (x >= 0) && (y >= 0) && (x < width) && (y < height); } - /** @deprecated */ + /** + * Tests whether or not the specified point is contained within this + * component. Coordinates are relative to this component. + * + * @param x The X coordinate of the point to test. + * @param y The Y coordinate of the point to test. + * + * @return <code>true</code> if the point is within this component, + * <code>false</code> otherwise. + * + * @deprecated Deprecated in favor of <code>contains(int, int)</code>. + */ public boolean inside(int x, int y) { return contains(x,y); } + /** + * Tests whether or not the specified point is contained within this + * component. Coordinates are relative to this component. + * + * @param point The point to test. + * + * @return <code>true</code> if the point is within this component, + * <code>false</code> otherwise. + */ public boolean contains(Point p) { return contains(p.x, p.y); } + /** + * Returns the component occupying the position (x,y). This will either + * be this component, an immediate child component, or <code>null</code> + * if neither of the first two occupies the specified location. + * + * @param x The X coordinate to search for components at. + * @param y The Y coordinate to search for components at. + * + * @return The component at the specified location, for <code>null</code> + * if there is none. + */ public Component getComponentAt(int x, int y) { if (contains(x,y)) @@ -790,21 +1381,47 @@ public abstract class Component implements ImageObserver, MenuContainer, return null; } - /** @deprecated */ + /** + * Returns the component occupying the position (x,y). This will either + * be this component, an immediate child component, or <code>null</code> + * if neither of the first two occupies the specified location. + * + * @param x The X coordinate to search for components at. + * @param y The Y coordinate to search for components at. + * + * @return The component at the specified location, for <code>null</code> + * if there is none. + * + * @deprecated The method is deprecated in favor of + * <code>getComponentAt()</code>. + */ public Component locate(int x, int y) { return getComponentAt(x, y); } + /** + * Returns the component occupying the specified point This will either + * be this component, an immediate child component, or <code>null</code> + * if neither of the first two occupies the specified location. + * + * @param point The point to search for components at. + * + * @return The component at the specified location, for <code>null</code> + * if there is none. + */ public Component getComponentAt(Point p) { return getComponentAt(p.x, p.y); } - /** @deprecated */ + /** + * AWT 1.0 event dispatcher. + * + * @deprecated Deprecated in favor of <code>dispatchEvent()</code>. + */ public void deliverEvent(Event e) { - } /** Forward AWT events to processEvent() if: @@ -812,6 +1429,8 @@ public abstract class Component implements ImageObserver, MenuContainer, * OR: * - There is at least one registered listener for this type of event * + * @param event The event to dispatch + * * @specnote This method is final, but we need to be able to * override it in order to handle other event types in our * subclasses. The solution is to define a second, non-final @@ -870,31 +1489,55 @@ public abstract class Component implements ImageObserver, MenuContainer, processEvent(e); } - /** @deprecated */ + /** + * AWT 1.0 event dispatcher. + * + * @deprecated Deprecated in favor of <code>dispatchEvent()</code>. + */ public boolean postEvent(Event e) { return false; } - + + /** + * Adds the specified listener to this component. + * + * @param listener The new listener to add. + */ public synchronized void addComponentListener(ComponentListener l) { componentListener = AWTEventMulticaster.add(componentListener, l); if (componentListener != null) enableEvents(AWTEvent.COMPONENT_EVENT_MASK); } - + + /** + * Removes the specified listener from the component. + * + * @param listener The listener to remove. + */ public synchronized void removeComponentListener(ComponentListener l) { componentListener = AWTEventMulticaster.remove(componentListener, l); } - + + /** + * Adds the specified listener to this component. + * + * @param listener The new listener to add. + */ public synchronized void addFocusListener(FocusListener l) { focusListener = AWTEventMulticaster.add(focusListener, l); if (focusListener != null) enableEvents(AWTEvent.FOCUS_EVENT_MASK); } - + + /** + * Removes the specified listener from the component. + * + * @param listener The listener to remove. + */ public synchronized void removeFocusListener(FocusListener l) { focusListener = AWTEventMulticaster.remove(focusListener, l); @@ -931,6 +1574,11 @@ public abstract class Component implements ImageObserver, MenuContainer, AWTEventMulticaster.remove(hierarchyBoundsListener, l); } + /** + * Adds the specified listener to this component. + * + * @param listener The new listener to add. + */ public synchronized void addKeyListener(KeyListener l) { keyListener = AWTEventMulticaster.add(keyListener, l); @@ -938,11 +1586,21 @@ public abstract class Component implements ImageObserver, MenuContainer, enableEvents(AWTEvent.KEY_EVENT_MASK); } + /** + * Removes the specified listener from the component. + * + * @param listener The listener to remove. + */ public synchronized void removeKeyListener(KeyListener l) { keyListener = AWTEventMulticaster.remove(keyListener, l); } + /** + * Adds the specified listener to this component. + * + * @param listener The new listener to add. + */ public synchronized void addMouseListener(MouseListener l) { mouseListener = AWTEventMulticaster.add(mouseListener, l); @@ -950,11 +1608,21 @@ public abstract class Component implements ImageObserver, MenuContainer, enableEvents(AWTEvent.MOUSE_EVENT_MASK); } + /** + * Removes the specified listener from the component. + * + * @param listener The listener to remove. + */ public synchronized void removeMouseListener(MouseListener l) { mouseListener = AWTEventMulticaster.remove(mouseListener, l); } + /** + * Adds the specified listener to this component. + * + * @param listener The new listener to add. + */ public synchronized void addMouseMotionListener(MouseMotionListener l) { mouseMotionListener = AWTEventMulticaster.add(mouseMotionListener, l); @@ -962,6 +1630,11 @@ public abstract class Component implements ImageObserver, MenuContainer, enableEvents(AWTEvent.MOUSE_EVENT_MASK); } + /** + * Removes the specified listener from the component. + * + * @param listener The listener to remove. + */ public synchronized void removeMouseMotionListener(MouseMotionListener l) { mouseMotionListener = AWTEventMulticaster.remove(mouseMotionListener, l); @@ -1043,6 +1716,17 @@ public abstract class Component implements ImageObserver, MenuContainer, // // public InputContext getInputContext() + /** + * Enables the specified events. The events to enable are specified + * by OR-ing together the desired masks from <code>AWTEvent</code>. + * <p> + * Events are enabled by default when a listener is attached to the + * component for that event type. This method can be used by subclasses + * to ensure the delivery of a specified event regardless of whether + * or not a listener is attached. + * + * @param enable_events The desired events to enable. + */ protected final void enableEvents(long eventsToEnable) { eventMask |= eventsToEnable; @@ -1060,6 +1744,12 @@ public abstract class Component implements ImageObserver, MenuContainer, peer.setEventMask (eventMask); } + /** + * Disables the specified events. The events to disable are specified + * by OR-ing together the desired masks from <code>AWTEvent</code>. + * + * @param disable_events The desired events to disable. + */ protected final void disableEvents(long eventsToDisable) { eventMask &= ~eventsToDisable; @@ -1111,7 +1801,6 @@ public abstract class Component implements ImageObserver, MenuContainer, * +--+ * </pre> */ - private PaintEvent coalescePaintEvents(PaintEvent queuedEvent, PaintEvent newEvent) { @@ -1132,12 +1821,12 @@ public abstract class Component implements ImageObserver, MenuContainer, return newEvent; } - - - - /** Forward event to the appropriate processXXXEvent method based on the - * event type. - */ + /** + * Processes the specified event. In this class, this method simply + * calls one of the more specific event handlers. + * + * @param event The event to process. + */ protected void processEvent(AWTEvent e) { @@ -1172,7 +1861,14 @@ public abstract class Component implements ImageObserver, MenuContainer, processHierarchyBoundsEvent((HierarchyEvent) e); } } - + + /** + * Called when a component event is dispatched and component events are + * enabled. This method passes the event along to any listeners + * that are attached. + * + * @param event The <code>ComponentEvent</code> to process. + */ protected void processComponentEvent(ComponentEvent e) { if (componentListener == null) @@ -1196,7 +1892,14 @@ public abstract class Component implements ImageObserver, MenuContainer, break; } } - + + /** + * Called when a focus event is dispatched and component events are + * enabled. This method passes the event along to any listeners + * that are attached. + * + * @param event The <code>FocusEvent</code> to process. + */ protected void processFocusEvent(FocusEvent e) { if (focusListener == null) @@ -1211,7 +1914,14 @@ public abstract class Component implements ImageObserver, MenuContainer, break; } } - + + /** + * Called when a key event is dispatched and component events are + * enabled. This method passes the event along to any listeners + * that are attached. + * + * @param event The <code>KeyEvent</code> to process. + */ protected void processKeyEvent(KeyEvent e) { if (keyListener == null) @@ -1229,7 +1939,14 @@ public abstract class Component implements ImageObserver, MenuContainer, break; } } - + + /** + * Called when a regular mouse event is dispatched and component events are + * enabled. This method passes the event along to any listeners + * that are attached. + * + * @param event The <code>MouseEvent</code> to process. + */ protected void processMouseEvent(MouseEvent e) { if (mouseListener == null) @@ -1254,6 +1971,13 @@ public abstract class Component implements ImageObserver, MenuContainer, } } + /** + * Called when a mouse motion event is dispatched and component events are + * enabled. This method passes the event along to any listeners + * that are attached. + * + * @param event The <code>MouseMotionEvent</code> to process. + */ protected void processMouseMotionEvent(MouseEvent e) { if (mouseMotionListener == null) @@ -1268,7 +1992,7 @@ public abstract class Component implements ImageObserver, MenuContainer, break; } } - + /** @since 1.2 */ protected void processInputMethodEvent(InputMethodEvent e) { @@ -1332,77 +2056,119 @@ public abstract class Component implements ImageObserver, MenuContainer, throw new IllegalArgumentException("unknown paint event"); } } - - /** @deprecated */ + + /** + * AWT 1.0 event processor. + * + * @deprecated Deprecated in favor of <code>processEvent</code>. + */ public boolean handleEvent(Event evt) { return false; } - - /** @deprecated */ + + /** + * AWT 1.0 mouse event. + * + * @deprecated Deprecated in favor of <code>processMouseEvent()</code>. + */ public boolean mouseDown(Event evt, int x, int y) { return false; } - /** @deprecated */ + /** + * AWT 1.0 mouse event. + * + * @deprecated Deprecated in favor of <code>processMouseMotionEvent()</code>. + */ public boolean mouseDrag(Event evt, int x, int y) { return false; } - /** @deprecated */ + /** + * AWT 1.0 mouse event. + * + * @deprecated Deprecated in favor of <code>processMouseEvent()</code>. + */ public boolean mouseUp(Event evt, int x, int y) { return false; } - /** @deprecated */ + /** + * AWT 1.0 mouse event. + * + * @deprecated Deprecated in favor of <code>processMouseMotionEvent()</code>. + */ public boolean mouseMove(Event evt, int x, int y) { return false; } - /** @deprecated */ + /** + * AWT 1.0 mouse event. + * + * @deprecated Deprecated in favor of <code>processMouseEvent()</code>. + */ public boolean mouseEnter(Event evt, int x, int y) { return false; } - /** @deprecated */ + /** + * AWT 1.0 mouse event. + * + * @deprecated Deprecated in favor of <code>processMouseEvent()</code>. + */ public boolean mouseExit(Event evt, int x, int y) { return false; } - /** @deprecated */ + /** + * AWT 1.0 key press event. + * + * @deprecated Deprecated in favor of <code>processKeyEvent</code>. + */ public boolean keyDown(Event evt, int key) { return false; } - /** @deprecated */ + /** + * AWT 1.0 key press event. + * + * @deprecated Deprecated in favor of <code>processKeyEvent</code>. + */ public boolean keyUp(Event evt, int key) { return false; } - /** @deprecated */ + /** + * AWT 1.0 action event processor. + * + * @deprecated Deprecated in favor of the <code>ActionListener</code> + * interface. + */ public boolean action(Event evt, Object what) { return false; } + /** + * Called to inform this component it has been added to a container. + * A native peer - if any - is created at this time. This method is + * called automatically by the AWT system and should not be called by + * user level code. + */ public void addNotify() { if (peer == null) peer = getToolkit().createComponent(this); - /* Add notify children using a template method, so that it is - possible to ensure that the new event mask delivered to the - peer. */ - addNotifyContainerChildren(); - /* Now that all the children has gotten their peers, we should have the event mask needed for this component and its lightweight subcomponents. */ @@ -1415,11 +2181,12 @@ public abstract class Component implements ImageObserver, MenuContainer, etc. */ } - void addNotifyContainerChildren() - { - // nothing to do unless we're a container - } - + /** + * Called to inform this component is has been removed from its + * container. Its native peer - if any - is destroyed at this time. + * This method is called automatically by the AWT system and should + * not be called by user level code. + */ public void removeNotify() { if (peer != null) @@ -1439,11 +2206,24 @@ public abstract class Component implements ImageObserver, MenuContainer, return false; } + /** + * Tests whether or not this component is in the group that can + * be traversed using the keyboard traversal mechanism (such as the TAB + * key). + * + * @return <code>true</code> if the component is traversed via the TAB + * key, <code>false</code> otherwise. + */ public boolean isFocusTraversable() { return enabled && visible && (peer == null || peer.isFocusTraversable ()); } + /** + * Requests that this component be given focus. The <code>gotFocus()</code> + * method on this event will be called when and if this request was + * successful. + */ public void requestFocus() { // If there's no peer then this component can't get the focus. We @@ -1461,6 +2241,9 @@ public abstract class Component implements ImageObserver, MenuContainer, return null; } + /** + * Transfers focus to the next component in the focus traversal order. + */ public void transferFocus() { Component next; @@ -1472,7 +2255,11 @@ public abstract class Component implements ImageObserver, MenuContainer, next.requestFocus (); } - /** @deprecated */ + /** + * AWT 1.0 focus event processor. + * + * @deprecated Deprecated in favor of <code>transferFocus()</code>. + */ public void nextFocus() { transferFocus(); @@ -1484,6 +2271,11 @@ public abstract class Component implements ImageObserver, MenuContainer, return hasFocus; } + /** + * Adds the specified popup menu to this component. + * + * @param menu The popup menu to be added. + */ public synchronized void add(PopupMenu popup) { if (popups == null) @@ -1491,11 +2283,21 @@ public abstract class Component implements ImageObserver, MenuContainer, popups.addElement(popup); } + /** + * Removes the specified popup menu from this component. + * + * @param menu The popup menu to remove. + */ public synchronized void remove(MenuComponent popup) { popups.removeElement(popup); } + /** + * Returns a debugging string representing this component. + * + * @return A string representing this component. + */ protected String paramString() { StringBuffer param = new StringBuffer(); @@ -1527,21 +2329,41 @@ public abstract class Component implements ImageObserver, MenuContainer, return param.toString(); } + /** + * Returns a string representation of this component. + * + * @return A string representation of this component + */ public String toString() { return this.getClass().getName() + "[" + paramString() + "]"; } + /** + * Prints a listing of this component to the standard output. + */ public void list () { list (System.out, 0); } + /** + * Prints a listing of this component to the specified print stream. + * + * @param stream The <code>PrintStream</code> to print to. + */ public void list (PrintStream out) { list (out, 0); } + /** + * Prints a listing of this component to the specified print stream, + * starting at the specified indentation point. + * + * @param stream The <code>PrintStream</code> to print to. + * @param indent The indentation point. + */ public void list (PrintStream out, int indent) { for (int i = 0; i < indent; ++i) @@ -1549,11 +2371,23 @@ public abstract class Component implements ImageObserver, MenuContainer, out.println (toString ()); } + /** + * Prints a listing of this component to the specified print writer. + * + * @param writer The <code>PrintWrinter</code> to print to. + */ public void list (PrintWriter out) { list (out, 0); } + /** + * Prints a listing of this component to the specified print writer, + * starting at the specified indentation point. + * + * @param writer The <code>PrintWriter</code> to print to. + * @param indent The indentation point. + */ public void list (PrintWriter out, int indent) { for (int i = 0; i < indent; ++i) @@ -1612,4 +2446,29 @@ public abstract class Component implements ImageObserver, MenuContainer, return accessibleContext; } */ + +/** + * AWT 1.0 focus event processor. + * + * @deprecated Deprecated in favor of <code>processFocusEvent</code>. + +public boolean +gotFocus(Event event, Object what) +{ + return(true); +} +*/ + +/** + * AWT 1.0 focus event processor. + * + * @deprecated Deprecated in favor of <code>processFocusEvent</code>. + +public boolean +lostFocus(Event event, Object what) +{ + return(true); +} +*/ + } |