acm.graphics
Class GCanvas

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--acm.graphics.GCanvas

public class GCanvas extends Container implements GContainer

The GCanvas class is a lightweight component that also serves as a container for graphical objects. As such, this class provides the link between graphical objects and the window system. Conceptually, the GCanvas provides a background canvas to which other graphical objects can be added.

Field Summary

static int	BACK_TO_FRONT Specifies that iterators should run from back to front
static int	FRONT_TO_BACK Specifies that iterators should run from front to back

Constructor Summary

GCanvas()

Method Summary

Component	add(Component comp) Adds the component to this canvas without changing its location.
void	add(Component comp, double x, double y) Adds the component to this canvas and sets its location to the point (x, y).
void	add(Component comp, java.awt.Point pt) Adds the component to this canvas and sets its location to the specified point.
void	add(GObject gobj) Adds the graphical object to this canvas without changing its location.
void	add(GObject gobj, double x, double y) Adds the graphical object to this canvas and sets its location to the point (x, y).
void	add(GObject gobj, java.awt.Point pt) Adds the graphical object to this canvas and sets its location to the specified point.
GObject	getElement(int index) Returns the graphical object at the specified index, numbering from back to front in the stacking order.
GObject	getElementAt(double x, double y) Returns the topmost graphical object that contains the point (x, y), or null if no such object exists.
GObject	getElementAt(Point pt) Returns the topmost graphical object that contains the specified point, or null if no such object exists.
int	getElementCount() Returns the number of graphical objects stored in this GCanvas.
int	getHeight() Returns the height of this canvas in pixels.
int	getWidth() Returns the width of this canvas in pixels.
boolean	isAutoRepaintEnabled() Returns the current setting of the auto-repaint flag as described in setAutoRepaintEnabled.
boolean	isOpaque() Returns a boolean value indicating whether this canvas is opaque.
Iterator	iterator() Returns an Iterator that cycles through the elements within this container in the default direction, which is from back to front.
Iterator	iterator(int direction) Returns an Iterator that cycles through the elements within this container in the specified direction, which must be one of the constants FRONT_TO_BACK or BACK_TO_FRONT.
void	onMouseClicked(double x, double y) This method is invoked automatically whenever a mouse click occurs in the canvas.
void	onMouseDragged(double x, double y) This method is invoked automatically whenever a mouse click occurs in the canvas.
void	onMouseMoved(double x, double y) This method is invoked automatically whenever a mouse click occurs in the canvas.
void	onMousePressed(double x, double y) This method is invoked automatically whenever a mouse click occurs in the canvas.
void	onMouseReleased(double x, double y) This method is invoked automatically whenever a mouse click occurs in the canvas.
void	paint(Graphics g) Paints the canvas.
void	remove(GObject gobj) Removes a graphical object from this GCanvas.
void	removeAll() Removes all graphical objects from this GCanvas.
void	setAutoRepaintEnabled(boolean state) Changes the setting of the auto-repaint flag.
void	setOpaque(boolean flag) Sets a flag indicating whether this canvas is opaque, which means that it obscures anything behind it.

Field Detail

public static final int BACK_TO_FRONT

Specifies that iterators should run from back to front

public static final int FRONT_TO_BACK

Specifies that iterators should run from front to back

Constructor Detail

public GCanvas()

Creates a new GCanvas that contains no objects.

Usage:

GCanvas gc = new GCanvas();

Method Detail

public Component add(Component comp)

Adds the component to this canvas without changing its location. If the component has no size, its size is set to its preferred size. The return type is Component to match the method in the Container class, but the result is typically ignored.

Usage:

gc.add(comp);

Parameter:

comp	The component to add

public final void add(java.awt.Component comp, double x, double y)

Adds the component to this canvas and sets its location to the point (x, y).

Usage:

gc.add(comp, x, y);

Parameters:

comp	The component to add
x	The new x-coordinate for the object
y	The new y-coordinate for the object

public final void add(java.awt.Component comp, Point pt)

Adds the component to this canvas and sets its location to the specified point.

Usage:

gc.add(comp, pt);

Parameters:

comp	The component to add
pt	A Point object giving the coordinates of the point

public void add(GObject gobj)

Adds the graphical object to this canvas without changing its location.

Usage:

gc.add(gobj);

Parameter:

gobj	The graphical object to add

Specified by:

add in interface GContainer

public void add(GObject gobj, double x, double y)

Adds the graphical object to this canvas and sets its location to the point (x, y).

Usage:

gc.add(gobj, x, y);

Parameters:

gobj	The graphical object to add
x	The new x-coordinate for the object
y	The new y-coordinate for the object

Specified by:

add in interface GContainer

public final void add(GObject gobj, Point pt)

Adds the graphical object to this canvas and sets its location to the specified point.

Usage:

gc.add(gobj, pt);

Parameters:

gobj	The graphical object to add
pt	A Point object giving the coordinates of the point

Specified by:

add in interface GContainer

public GObject getElement(int index)

Returns the graphical object at the specified index, numbering from back to front in the stacking order.

Usage:

GObject gobj = gc.getElement(index);

Parameter:

index

The index of the component to return

Returns:

The graphical object at the specified index

Specified by:

getElement in interface GContainer

public GObject getElementAt(double x, double y)

Returns the topmost graphical object that contains the point (x, y), or null if no such object exists.

Usage:

GObject gobj = gc.getElementAt(x, y);

Parameters:

x	The x-coordinate of the point being tested
y	The y-coordinate of the point being tested

Returns:

The graphical object at the specified location, or null if no such object exists

Specified by:

getElementAt in interface GContainer

public final GObject getElementAt(Point pt)

Returns the topmost graphical object that contains the specified point, or null if no such object exists.

Usage:

GObject gobj = gc.getElementAt(pt);

Parameter:

pt	The coordinates being tested

Returns:

The graphical object at the specified location, or null if no such object exists

Specified by:

getElementAt in interface GContainer

public int getElementCount()

Returns the number of graphical objects stored in this GCanvas.

Usage:	int n = gc.getElementCount();
Returns:	The number of graphical objects in this GCanvas
Specified by:	getElementCount in interface GContainer

public int getHeight()

Returns the height of this canvas in pixels. This method is defined in JDK 1.2 components, but not in earlier ones. Defining this method here makes this entry available in all browsers.

Usage:	int height = gc.getHeight();
Returns:	The height of this canvas in pixels

public int getWidth()

Returns the width of this canvas in pixels. This method is defined in JDK 1.2 components, but not in earlier ones. Defining this method here makes this entry available in all browsers.

Usage:	int width = gc.getWidth();
Returns:	The width of this canvas

public boolean isAutoRepaintEnabled()

Returns the current setting of the auto-repaint flag as described in setAutoRepaintEnabled.

Usage:	if (gc.isAutoRepaintEnabled()) . . .
Returns:	true if auto-repaint mode is enabled, and false otherwise

public boolean isOpaque()

Returns a boolean value indicating whether this canvas is opaque.

public Iterator iterator()

Returns an Iterator that cycles through the elements within this container in the default direction, which is from back to front. You can also run the iterator in the opposite direction by using the iterator(direction) form of this method.

Applets that want to run in browsers, however, should avoid using this method, because Iterator is not supported on 1.1 browsers. For maximum portability, you should rely instead on the getElementCount and getElement methods, which provide the same functionality in a browser-compatible way.

Usage:	Iterator i = gc.iterator();
Returns:	An Iterator ranging over the elements of the container from back to front

public Iterator iterator(int direction)

Returns an Iterator that cycles through the elements within this container in the specified direction, which must be one of the constants FRONT_TO_BACK or BACK_TO_FRONT.

for (Iterator i = gc.iterator(direction); i.hasNext(); )

Applets that want to run in browsers, however, should avoid using this method, because Iterator is not supported on 1.1 browsers. For maximum portability, you should rely instead on the getElementCount and getElement methods, which provide the same functionality in a browser-compatible way.

Usage:	Iterator i = gc.iterator(direction);
Returns:	An Iterator ranging over the elements of the container in the specified direction

public void onMouseClicked(double x, double y)

This method is invoked automatically whenever a mouse click occurs in the canvas. Subclasses can override this method to respond to mouse clicks.

Usage:

gc.onMouseClicked(x, y);

Parameters:

x	The x-coordinate at which the mouse event occurred
y	The y-coordinate at which the mouse event occurred

public void onMouseDragged(double x, double y)

This method is invoked automatically whenever a mouse click occurs in the canvas. Subclasses can override this method to respond to mouse clicks.

Usage:

gc.onMouseDragged(x, y);

Parameters:

x	The x-coordinate at which the mouse event occurred
y	The y-coordinate at which the mouse event occurred

public void onMouseMoved(double x, double y)

This method is invoked automatically whenever a mouse click occurs in the canvas. Subclasses can override this method to respond to mouse clicks.

Usage:

gc.onMouseMoved(x, y);

Parameters:

x	The x-coordinate at which the mouse event occurred
y	The y-coordinate at which the mouse event occurred

public void onMousePressed(double x, double y)

This method is invoked automatically whenever a mouse click occurs in the canvas. Subclasses can override this method to respond to mouse clicks.

Usage:

gc.onMousePressed(x, y);

Parameters:

x	The x-coordinate at which the mouse event occurred
y	The y-coordinate at which the mouse event occurred

public void onMouseReleased(double x, double y)

This method is invoked automatically whenever a mouse click occurs in the canvas. Subclasses can override this method to respond to mouse clicks.

Usage:

gc.onMouseReleased(x, y);

Parameters:

x	The x-coordinate at which the mouse event occurred
y	The y-coordinate at which the mouse event occurred

public void paint(Graphics g)

Paints the canvas. This method is not ordinarily called by clients.

public void remove(GObject gobj)

Removes a graphical object from this GCanvas.

Usage:

gc.remove(gobj);

Parameter:

gobj	The graphical object to remove

Specified by:

remove in interface GContainer

public void removeAll()

Removes all graphical objects from this GCanvas.

Usage:	gc.removeAll();
Specified by:	removeAll in interface GContainer Overrides: removeAll in class java.awt.Container

public void setAutoRepaintEnabled(boolean state)

Changes the setting of the auto-repaint flag. By default, any change to a graphical object contained in this canvas automatically triggers a repaint of the canvas as a whole. While this behavior makes it much easier to use the package, it has the disadvantage that repaint requests come much more frequently than necessary. You can disable this feature by calling setAutoRepaintEnabled(false), but you must then make explicit calls to repaint() whenever you want to update the display. The advantage of this model is that you can then make many different changes and have them all appear at once with a single repaint call.

Usage:

gc.setAutoRepaintEnabled(state);

Parameter:

state

true to enable auto-repaint mode, and false to disable it

public void setOpaque(boolean flag)

Sets a flag indicating whether this canvas is opaque, which means that it obscures anything behind it. Setting this flag to false makes the GCanvas transparent, so that any other lightweight components behind it show through.