acm.graphics
Class GString

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

public class GString extends GObject

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

To use the GString class, the first step is to construct a new GString object and add it to an existing GCanvas (assumed here to be stored in the variable gc), as follows: GString gstr = new GString("Hello, world."); gc.add(gstr, 50, 60); This code creates a GString containing the string "Hello, world." and installs it in the GCanvas so that its origin is at the point (50, 60), 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: gstr.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: gstr.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 translate 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: gstr.translate(50, 0); As you can see from the diagram, the string is clipped by the edges of the canvas.

For a GString 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: gstr.setLocation((gc.getWidth() - gstr.getWidth()) / 2, 60);

As a final example, you can use the setString method to change the character string that the GString displays. Thus, if you call gstr.setString("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

static Font

DEFAULT_FONT The default font used to display strings.

Constructor Summary

GString(String str)

Method Summary

double	getAscent() Returns the distance this string extends above the baseline.
Rectangle	getBounds() Returns a Rectangle 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 GString is displayed.
FontMetrics	getFontMetrics() Returns a FontMetrics object describing the dimensions of this string.
double	getHeight() Returns the height of this string in pixels, as it appears on the display.
Dimension	getSize() Returns the size of this string, which is set by changing the contents and font rather than by calling setSize, which is disabled for this class.
String	getString() Returns the string displayed by this object.
double	getWidth() Returns the width of this string in pixels, as it appears (or would appear) on the display.
void	paint(Graphics g) Implements the paint operation for this graphical object.
void	setFont(Font font) Changes the font used to display the GString.
void	setString(String str) Changes the string stored within the GString 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. [Inherited from GObject]
void	addMouseMotionListener(MouseMotionListener listener) Adds a mouse motion listener to this graphical object. [Inherited from GObject]
boolean	contains(double x, double y) Checks to see whether a point is inside the object. [Inherited from GObject]
Color	getColor() Returns the color used to display 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	removeMouseListener(MouseListener listener) Removes a mouse listener from this graphical object. [Inherited from GObject]
void	removeMouseMotionListener(MouseMotionListener listener) Removes a mouse motion listener from this graphical object. [Inherited from GObject]
void	setColor(Color c) Sets the color used to display this object. [Inherited from GObject]
void	setLocation(double x, double y) Sets the location of this object to the point (x, y). [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]

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 GString(String str)

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

Usage:

GString gstr = new GString(str);

Parameter:

str	The initial contents of the GString

Method Detail

public double getAscent()

Returns the distance this string extends above the baseline.

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

public Rectangle getBounds()

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

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

public double getDescent()

Returns the distance this string descends below the baseline.

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

public Font getFont()

Returns the font in which the GString is displayed.

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

public FontMetrics getFontMetrics()

Returns a FontMetrics object describing the dimensions of this string.

public double getHeight()

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

Usage:	double height = gstr.getHeight();
Returns:	The height of this string in pixels

public Dimension getSize()

Returns the size of this string, which is set by changing the contents and font rather than by calling setSize, which is disabled for this class.

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

public String getString()

Returns the string displayed by this object.

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

public double getWidth()

Returns the width of this string in pixels, as it appears (or would appear) on the display.

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

public void paint(Graphics g)

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

public void setFont(Font font)

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

Usage:

gstr.setFont(font);

Parameter:

font	A Font object describing the new font

public void setString(String str)

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

Usage:

gstr.setString(str);

Parameter:

str	The new string to display