acm.graphics
Class GLabel

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

public class GLabel extends GObject

The GLabel class is a graphical object whose appearance consists of a text string.

To use the GLabel class, the first step is to construct a new GLabel object and add it to an existing GCanvas (assumed here to be stored in the variable gc), as follows: GLabel glabel = new GLabel("Hello, world.", 50, 60); gc.add(glabel); This code creates a GLabel containing the string "Hello, world." with its origin at the point (50, 60) and installs the label in the GCanvas as shown in the figure to the right.

Most graphical objects in Java use the upper left corner of the figure to define their location. Strings, however, work differently. The location at which a string is displayed is always taken to be at the leftmost edge of the first character along what is called the baseline, which is the line on which the uppercase letters sit. Some lowercase letters (g, j, p, q, and y) descend below the baseline, as do several special characters like the comma. The location of the start of the string and the concept of the baseline are illustrated in the diagram to the right.

Unless you specify otherwise, a string is displayed in a standard font, which is defined in this class as the constant DEFAULT_FONT. You can change the appearance, style, and size of the string by using the setFont method, which takes a Font as its argument, as defined in the java.awt package. For example, to change the string so that it uses a boldface serif type face at a larger point size, you could execute the following code: glabel.setFont(new Font("Serif", Font.BOLD, 18)); Note that changing the font can change the displayed size of the string, which will be reflected in calls to getWidth or getSize.

Just as with other objects of the GObject class, you can change the color of the displayed text by invoking the setColor method, which takes a Color as its argument, as defined in the java.awt package. Thus, the following statement changes the text color to blue: glabel.setColor(Color.blue);

Once installed on the canvas, you can move a string using either the setLocation method, which moves an object to a specific position, or the move method, which moves an object relative to its current position. To move the string rightward 50 pixels, for example, you could use the following statement: glabel.move(50, 0); As you can see from the diagram, the string is clipped by the edges of the canvas.

For a GLabel object, one of the operations you will often want to perform is to center the string relative to a particular position, such as the center of the screen. To do so, the simplest approach is to use the getWidth method to find the width of the string in pixels, and then start the string half that distance to the left of the central point. Thus, the following setLocation call centers the string horizontally in the GCanvas: glabel.setLocation((gc.getWidth() - glabel.getWidth()) / 2, 60);

As a final example, you can use the setLabel method to change the character string that the GLabel displays. Thus, if you call glabel.setLabel("Hi!"); the string "Hello, world." gets replaced by "Hi!". The position of the string doesn’t change, so that you would then need to repeat the centering operation if you wanted this string to appear in the middle of the window.

Field Summary

Font	DEFAULT_FONT The default font used to display strings.

Constructor Summary

GLabel(String str)

GLabel(String str, double x, double y)

Method Summary

double	getAscent() Returns the distance this string extends above the baseline.
GRectangle	getBounds() Returns a GRectangle that specifies the bounding box for the string.
double	getDescent() Returns the distance this string descends below the baseline.
Font	getFont() Returns the font in which the GLabel is displayed.
double	getHeight() Returns the height of this string, as it appears on the display.
String	getLabel() Returns the string displayed by this object.
double	getWidth() Returns the width of this string, as it appears on the display.
void	setFont(Font font) Changes the font used to display the GLabel.
void	setFont(String str) Changes the font used to display the GLabel as specified by the string str, which is interpreted in the style of Font.decode.
void	setLabel(String str) Changes the string stored within the GLabel object, so that a new text string appears on the display.

Inherited Method Summary

void	addMouseListener(MouseListener listener) Adds a mouse listener to this graphical object.
void	addMouseMotionListener(MouseMotionListener listener) Adds a mouse motion listener to this graphical object.
boolean	contains(GPoint pt) Checks to see whether a point is inside the object.
boolean	contains(double x, double y) Checks to see whether a point is "inside" the string, which is defined to be inside the bounding rectangle.
Color	getColor() Returns the color used to display the text of the GLabel.
GPoint	getLocation() Returns the location of the GLabel as a GPoint object.
GDimension	getSize() Returns the size of the bounding box for this object.
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 GLabel is visible.
void	move(double dx, double dy) Moves the object on the screen using the displacements dx and dy.
void	movePolar(double r, double theta) Moves the object using displacements given in polar coordinates.
void	removeMouseListener(MouseListener listener) Removes a mouse listener from this graphical object.
void	removeMouseMotionListener(MouseMotionListener listener) Removes a mouse motion listener from this graphical object.
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	setColor(Color color) Sets the color used to display the text of the GLabel.
void	setLocation(GPoint pt) Sets the location of this object to the specified point.
void	setLocation(double x, double y) Sets the location of the GLabel to the point (x, y). For a GLabel, the location is the point on the text baseline at which the text starts.
void	setVisible(boolean visible) Sets the visibility status of the GLabel.

Field Detail

public static final Font DEFAULT_FONT

The default font used to display strings. You can change the font by invoking the setFont method.

Constructor Detail

public GLabel(String str)

Creates a new GLabel object initialized to contain the specified string.

Usage:

GLabel glabel = new GLabel(str);

Parameter:

str	The initial contents of the GLabel

public GLabel(String str, double x, double y)

Creates a new GLabel object with its baseline origin at the specified position.

Usage:

GLabel glabel = new GLabel(str, x, y);

Parameters:

str	The initial contents of the GLabel
x	The x-coordinate of the label origin
y	The y-coordinate of the baseline for the label

Method Detail

public double getAscent()

Returns the distance this string extends above the baseline.

Usage:	double ascent = glabel.getAscent();
Returns:	The ascent of this string in pixels

public GRectangle getBounds()

Returns a GRectangle that specifies the bounding box for the string.

Usage:	GRectangle bounds = glabel.getBounds();
Returns:	The bounding box for this object

public double getDescent()

Returns the distance this string descends below the baseline.

Usage:	double descent = glabel.getDescent();
Returns:	The descent of this string in pixels

public Font getFont()

Returns the font in which the GLabel is displayed.

Usage:	Font font = glabel.getFont();
Returns:	The font in use by this object

public double getHeight()

Returns the height of this string, as it appears on the display.

Usage:	double height = glabel.getHeight();
Returns:	The height of this string

public String getLabel()

Returns the string displayed by this object.

Usage:	String str = glabel.getLabel();
Returns:	The string displayed by this object

public double getWidth()

Returns the width of this string, as it appears on the display.

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

public void setFont(Font font)

Changes the font used to display the GLabel. This call will usually change the size of the displayed object and will therefore affect the result of calls to getSize and getBounds.

Usage:

glabel.setFont(font);

Parameter:

font	A Font object indicating the new font

public void setFont(String str)

Changes the font used to display the GLabel as specified by the string str, which is interpreted in the style of Font.decode. The usual format of the font string is

familycode>-stylecode>-size where both style and size are optional. If any of these parts are specified as an asterisk, the existing value is retained.

Usage:

glabel.setFont(str);

Parameter:

str	A String specifying the new font

public void setLabel(String str)

Changes the string stored within the GLabel object, so that a new text string appears on the display.

Usage:

glabel.setLabel(str);

Parameter:

str	The new string to display