acm.graphics
Class GPen

java.lang.Object
  |
  +--acm.graphics.GObject
        |
        +--acm.graphics.GPen

public class GPen extends GObject

The GPen class simulates a pen drawing on a canvas. As with the other graphical objects in the acm.graphics package, you use this class by constructing a new GPen object and adding that object to a GCanvas. You can move the pen on the canvas by using the methods setLocation and move and then draw lines using drawLine. The GPen object remembers the series of lines and can therefore repaint the screen image when necessary.

Constructor Summary

GPen()

GPen(double x, double y)

Method Summary

void	drawLine(double dx, double dy) Draws a line segment with displacements dx and dy.
void	drawPolarLine(double r, double theta) Draws a line segment using displacements given in polar coordinates.
void	endFilledRegion() Ends the definition of a region and fills it with the current color.
void	erasePath() Erases the entire path drawn by the pen but does not change its position.
GRectangle	getBounds() Returns the bounding box for the entire figure traced by the pen.
Color	getFillColor() Returns the color used to display the filled region of this object.
Image	getPenImage() Returns the image used to draw the pen when setPenVisible has been called.
double	getSpeed() Returns the current speed of the pen.
void	hidePen() Makes the pen itself invisible.
boolean	isPenVisible() Returns whether the pen is visible.
void	scale(double sx, double sy) Sets the scale factors sx and sy.
void	setColor(Color color) Sets the color of the pen.
void	setFillColor(Color color) Sets the color used to fill a region.
void	setLocation(double x, double y) Moves the pen to the point (x, y) without drawing a line.
void	setPenImage(Image image) Sets the image of the pen to be the specified image.
void	setSpeed(double speed) Sets the speed of the pen, which must be a number between 0 (slowest) and 1 (fastest).
void	showPen() Makes the pen itself visible.
void	startFilledRegion() Starts defining a region that will be filled with the current color.

Inherited Method Summary

Color	getColor() Returns the color used to display this object.
double	getHeight() Returns the height of this object as a double-precision value, which is defined to be the height of the bounding box.
GPoint	getLocation() Returns the location of this object as a GPoint.
GDimension	getSize() Returns the size of the bounding box for this object.
double	getWidth() Returns the width of this object as a double-precision value, which is defined to be the width of the bounding box.
double	getX() Returns the x-coordinate of the object.
double	getY() Returns the y-coordinate of the object.
boolean	isVisible() Checks to see whether the trace of the pen is visible.
void	move(double dx, double dy) Moves the pen on the screen by the specified displacements without drawing a line.
void	movePolar(double r, double theta) Moves the pen using displacements given in polar coordinates without drawing a line.
void	sendBackward() Moves this object one step toward the back in the z dimension.
void	sendForward() Moves this object one step toward the front in the z dimension.
void	sendToBack() Moves this object to the back of the display in the z dimension.
void	sendToFront() Moves this object to the front of the display in the z dimension.
void	setLocation(GPoint pt) Sets the location of this object to the specified point.
void	setVisible(boolean visible) Sets whether the trace of the pen is visible.

Constructor Detail

public GPen()

Creates a new GPen object with an empty path.

Usage:

GPen gpen = new GPen();

public GPen(double x, double y)

Creates a new GPen object with an empty path, initially positioned at the point (x, y).

Usage:

GPen gpen = new GPen(x, y);

Parameters:

x	The initial x coordinate of the pen
y	The initial y coordinate of the pen

Method Detail

public void drawLine(double dx, double dy)

Draws a line segment with displacements dx and dy. Drawing a line leaves the pen positioned at the end of the line segment, so that the next call to drawLine will continue from where this one finished.

Usage:

drawLine(dx, dy);

Parameters:

dx	The extent of the line in the x direction
dy	The extent of the line in the y direction

public final void drawPolarLine(double r, double theta)

Draws a line segment using displacements given in polar coordinates. The parameter r specifies the length of the line segment, and theta specifies the angle at which the line is drawn. The angle is measured in degrees increasing counterclockwise from the +x axis. Thus, the call

drawPolarLine(1.0, 0);

draws a line extending rightward one inch from the current point. Similarly

drawPolarLine(2.0, 135);

draws a two-inch line extending to the northwest from the current point.

Usage:

drawPolarLine(r, theta);

Parameters:

r	The length of the line segment
theta	The angle at which to draw the line, measured in degrees increasing counterclockwise from the +x axis

public void endFilledRegion()

Ends the definition of a region and fills it with the current color.

Usage:

gpen.endFilledRegion();

public void erasePath()

Erases the entire path drawn by the pen but does not change its position.

Usage:

gpen.erasePath();

public GRectangle getBounds()

Returns the bounding box for the entire figure traced by the pen.

Usage:	bounds = getBounds();
Returns:	A GRectangle representing the bounding box

public Color getFillColor()

Returns the color used to display the filled region of this object. If none has been set, getFillColor returns the color of the object.

Usage:	Color color = gpen.getFillColor();
Returns:	The color used to display the filled region of this object

public Image getPenImage()

Returns the image used to draw the pen when setPenVisible has been called.

public double getSpeed()

Returns the current speed of the pen.

Usage:	double speed = getSpeed();
Returns:	The current speed of the pen (0 is slowest, 1 is fastest)

public void hidePen()

Makes the pen itself invisible.

Usage:

gpen.showPen();

public boolean isPenVisible()

Returns whether the pen is visible.

Usage:	if (isPenVisible(visible)) . . .
Returns:	true if the pen is visible, otherwise false

public void scale(double sx, double sy)

Sets the scale factors sx and sy. Scaling a GPen object changes the location of points as well the size of line segments. This behavior seems counterintuitive for a pen installed directly in a GCanvas, but is quite useful when a GPen is embedded in a compound object.

Usage:

gpen.scale(sx, sy);

Parameters:

sx	The factor used to scale all coordinates in the x direction
sy	The factor used to scale all coordinates in the y direction

public void setColor(Color color)

Sets the color of the pen.

Usage:

gpen.setColor(color);

Parameter:

color

The new color for the pen

public void setFillColor(Color color)

Sets the color used to fill a region.

Usage:

gpen.setFillColor(color);

Parameter:

color

The new color used to fill a region

public void setLocation(double x, double y)

Moves the pen to the point (x, y) without drawing a line.

Usage:

gpen.setLocation(x, y);

Parameters:

x	The x-coordinate of the new position
y	The y-coordinate of the new position

public void setPenImage(Image image)

Sets the image of the pen to be the specified image. This image is drawn with its center at the pen position.

Usage:

pen.setPenImage(image);

Parameter:

The	new image to use for the pen

public void setSpeed(double speed)

Sets the speed of the pen, which must be a number between 0 (slowest) and 1 (fastest). Setting speed to a value less than one makes the pen move slowly, thereby making it easy to see exactly how a figure is being drawn.

Usage:

setSpeed(speed);

Parameter:

speed

The speed of the pen (0 is slowest, 1 is fastest)

public void showPen()

Makes the pen itself visible. If the pen is visible, the drawPen method will be called at the end of painting the path to show the current location.

Usage:

gpen.showPen();

public void startFilledRegion()

Starts defining a region that will be filled with the current color. Any line segments drawn between now and the matching call to endFilledRegion will be used to create a polygon that is then filled.

Usage:

gpen.startFilledRegion();