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 translate 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

static double	angle(double x, double y) Returns the angle in degrees from the origin to the point (x, y).
static double	cosD(double angle) Returns the trigonometric sine of its argument where angle is expressed in degrees.
static double	distance(double x, double y) Computes the distance between the origin and the point (x, y).
static double	distance(double x0, double y0, double x1, double y1) Computes the distance between the points (x0, y0) and (x1, y1).
void	drawLine(double dx, double dy) Draws a line segment with displacements dx and dy.
void	drawLineUsingPolarCoordinates(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	eraseAll() Erases the entire path drawn by the pen and returns it to the origin.
Rectangle	getBounds() Returns the bounding box for the entire figure traced by the pen.
double	getDelay() Returns the current delay set by in milliseconds.
double	getHeight() Returns the height of this bounding box covered by the pen trace.
Image	getPenImage() Returns the image used to draw the pen when setPenVisible has been called.
Dimension	getSize() Returns the size of this bounding box covered by the pen trace.
double	getWidth() Returns the width of this bounding box covered by the pen trace.
boolean	isPenVisible() Returns whether the pen is visible.
void	paint(Graphics g) Implements the paint operation for this graphical object.
void	scale(double sx, double sy) Sets the scale factors sx and sy.
void	setColor(Color color) Sets the color of the pen.
void	setDelay(double delayTime) Sets a delay factor for each motion of the pen, specified in milliseconds.
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	setPenVisible(boolean visible) Sets whether the pen itself is visible.
static double	sinD(double angle) Returns the trigonometric sine of its argument where angle is expressed in degrees.
void	startFilledRegion() Starts defining a region that will be filled with the current color.
static double	tanD(double angle) Returns the trigonometric sine of its argument where angle is expressed in degrees.
static double	toDegrees(double radians) Converts an angle from radians to degrees.
static double	toRadians(double degrees) Converts an angle from degrees to radians.
void	translateUsingPolarCoordinates(double r, double theta) Moves the pen using displacements given in polar coordinates without drawing a line.

Inherited Method Summary

Color	getColor() Returns the color used to display this object. [Inherited from GObject]
Color	getFillColor() Returns the color used to display the filled region of this object. [Inherited from GObject]
Point	getLocation() Returns the nearest Point corresponding to the location of this object. [Inherited from GObject]
double	getX() Returns the x-coordinate of the object. [Inherited from GObject]
double	getY() Returns the y-coordinate of the object. [Inherited from GObject]
boolean	isVisible() Checks to see whether this object is visible. [Inherited from GObject]
void	moveToBack() Moves this object to the back of the display in stacking order. [Inherited from GObject]
void	moveToFront() Moves this object to the front of the display in stacking order. [Inherited from GObject]
void	scale(double sf) Scales the object on the screen by the scale factor sf, which applies in both dimensions. [Inherited from GObject]
void	setVisible(boolean visible) Sets whether this object is visible. [Inherited from GObject]
void	translate(double dx, double dy) Moves the object on the screen using the displacements dx and dy. [Inherited from GObject]

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 static double angle(double x, double y)

Returns the angle in degrees from the origin to the point (x, y). This method is easier to use than atan2 because it specifies the displacements in the usual x/y order and because it takes care of the fact that the Java coordinate system is flipped.

public static double cosD(double angle)

Returns the trigonometric sine of its argument where angle is expressed in degrees.

public static double distance(double x, double y)

Computes the distance between the origin and the point (x, y).

public static double distance(double x0, double y0, double x1, double y1)

Computes the distance between the points (x0, y0) and (x1, y1).

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 endpoint, 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 void drawLineUsingPolarCoordinates(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

drawLineUsingPolarCoordinates(1.0, 0);

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

drawLineUsingPolarCoordinates(2.0, 135);

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

Usage:

drawLineUsingPolarCoordinates(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 eraseAll()

Erases the entire path drawn by the pen and returns it to the origin.

Usage:

gpen.eraseAll();

public Rectangle getBounds()

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

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

public double getDelay()

Returns the current delay set by in milliseconds.

Usage:	double delayTime = getDelay();
Returns:	The delay time in milliseconds

public double getHeight()

Returns the height of this bounding box covered by the pen trace.

Usage:	double height = gpen.getHeight();
Returns:	The height of this object on the screen

public Image getPenImage()

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

public Dimension getSize()

Returns the size of this bounding box covered by the pen trace.

Usage:	Dimension size = gpen.getSize();
Returns:	The size of this object

public double getWidth()

Returns the width of this bounding box covered by the pen trace.

Usage:	double width = gpen.getWidth();
Returns:	The width of this object

public boolean isPenVisible()

Returns whether the pen is visible.

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

public void paint(Graphics g)

Implements the paint operation for this graphical object. This method is not called directly by clients.

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 setDelay(double delayTime)

Sets a delay factor for each motion of the pen, specified in milliseconds. Setting this parameter to a nonzero value makes the pen move slowly through the figure, thereby making it easy to see exactly how a figure is being drawn.

Usage:

setDelay(delayTime);

Parameter:

delayTime

The number of milliseconds to delay whenever the pen moves or draws a line

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 setPenVisible(boolean visible)

Sets whether the pen itself is 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.setPenVisible(visible);

Parameter:

visible

true to show the pen, false to hide it

public static double sinD(double angle)

Returns the trigonometric sine of its argument where angle is expressed in degrees.

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();

public static double tanD(double angle)

Returns the trigonometric sine of its argument where angle is expressed in degrees.

public static double toDegrees(double radians)

Converts an angle from radians to degrees. This method is defined in the Math class, but was added only in JDK1.2, which is not supported in all browsers.

public static double toRadians(double degrees)

Converts an angle from degrees to radians. This method is defined in the Math class, but was added only in JDK1.2, which is not supported in all browsers.

public void translateUsingPolarCoordinates(double r, double theta)

Moves the pen using displacements given in polar coordinates without drawing a line. 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.

Usage:

translateUsingPolarCoordinates(r, theta);

Parameters:

r	The length of the pen motion
theta	The angle at which to move the pen, measured in degrees increasing counterclockwise from the +x axis