Text

The Text class is how you display written messages in your window. You can control font, size, and style, and color of the message, with all the options you normally expect from a word-proccessing program; you can also specify how the text should be aligned both vertically and horizontally. All these properties, and the message itself, can be changed by method calls, so that you can update what the text says as the program runs.

Although each Text object can have only one style, color, and font, it is possible to chain together multiple Texts, setting a different style for each, so that you have a longer message where different sections have different styles. Another thing that makes Text interesting is that instead of simply placing some text at a point, you can choose to wrap it onto a line or inside of some shape; so, for example, you can take a long string of text and have it automatically broken up into lines so that it fits within a FilledOval or the sketch of a Turtle.

Table of Contents

1. Creating a Text and updating the message

Your browser doesn't do Java.
ClickCounter.java
There are two types of constructors that you will use for Text. The first type takes a Location at which to place the Text, either as a Location object or as an x and y:

public Text(<Something> text, double x, double y, DrawingCanvas canvas)
public Text(<Something> text, double x, double y, Color color, DrawingCanvas canvas)
public Text(<Something> text, Location point, DrawingCanvas canvas)
public Text(<Something> text, Location point, Color color, DrawingCanvas canvas)

Here, by <Something> I just mean that the thing given as the text need not be a String, although it usually will be. You can pass along a numerical value of some sort, or an object to be converted to a String by its toString() method. Of course, in the end, whatever you pass along will end up as a String. You can retrieve and set the text later using these methods:

public String getText()
public void setText(String message)

The text will actually be drawn above and to the left of the location you specify; you can change this alignment after constructing it, as discussed below.

So, for example, this code creates a Text that says "Hello, World!", but when the user clicks, this is changed to say, "Goodbye, cruel world!"

private Text text;

public void begin() {
   text = new Text("Hello World!", 100, 100, canvas);
}
public void onMousePress(Location point) {
   text.setText("Goodbye, cruel world!");
}

2. Attaching a Text to another object

Your browser doesn't do Java.
WrappedCounter.java
Your browser doesn't do Java.
Gettysburg.java
Your browser doesn't do Java.
LineText.java
In the ClickCounter demo in the section above, you probably noticed that the text soon goes off the edge of the screen. You might like it to behave in the same way as a word processor, wrapping the text around to the next line when a line is too long, as seen in the WrappedCounter demo to the right.

One way to do this would be to explicitly include the special "\n" newline instruction in the text every few counts to make it break there. But it would be much nicer if we could just give the computer a shape to place the text inside and have it automatically wrap.

public Text(<Something> text, DrawableInterface basis, DrawingCanvas canvas)
public Text(<Something> text, DrawableInterface basis, Color color, DrawingCanvas canvas)

The basis here is a shape that will define the space the text has to lay itself out in. But what exactly is a DrawableInterface? You could read more about the Drawable Interfaces, but basically what you need to know is that it's nothing new - it's a name that stands for any of the objects that can show up on the canvas.

You can see examples to the right of wrapping a Text onto a FilledOval and wrapping it onto a Line. The Line behaves more like placing the Text at a Location in that there is no line wrapping; lines break only at a "\n". However, it does have the nice feature of rotating the text to line up with the line; try dragging the endpoints of the line and see what happens.

You can retrieve the "basis" object of a Text with this method:

public DrawableInterface getBasis()

This method will return null if this text was simply placed at a location. If this Text is chained on to another Text, as discussed below, the basis of the first text in the chain will be returned.

3. Setting the font, style and color of a Text

You can get and set the color of a Text in the same way as any other object:

public void setColor(Color color)
public Color getColor()

You can read more about working with Color if you need to.

Text also allows you to change its font, style, and size:

public void setFont(String fontName)
public void setBold(boolean b)
public void setItalic(boolean i)
public void setBold()
public void setItalic()
public void setPlain()
public void setFontSize(int size)

If you know a bit about the Font object, you can make this easier for yourself by creating a single Font that sets all these properties, and then sending it to the Text. You can also retrieve the Text's style as a Font object:

public void setFont(Font font)
public Font getFont()

So, if I want to make my Text be red, bold, Courier font, size 20, I can do this...

text.setColor(Color.RED);
text.setBold(true);
text.setFont("Courier");
text.setFontSize(20);

... or I could just do this:

text.setColor(Color.RED);
text.setFont(Font.decode("Courier-BOLD-20"));

Also, if you want to find out anything about the font and style of a Text object, you will have to make use of a Font object, because getFont() is the only way to retrieve this information:

int size = text.getFont().getFontSize();

4. Chaining many styled Text objects together

Your browser doesn't do Java.
HoverText.java
Sometimes you will want to have multiple styles in the same Text object. You may just want to make one word bold, or you may want to do something with many different styles, colors, and sizes, as you saw in my example of wrapping to a line. You may even want to change the style of part of the text when an event happens - try hovering over the green words in the demo to the right.

Since Text only has one style and color across its entire string, if you want to have multiple styles, you will actually use multiple Text objects. If you create a new Text and pass long an existing Text object as its basis, it will insert at the end of that Text rather than positioning itself independently. So, for example, this code will create text that looks like "RED and BLUE":

Text start = new Text("RED", 100, 100, Color.RED, canvas);
Text middle = new Text(" and ", start, canvas);
Text end = new Text("BLUE", middle, Color.BLUE, canvas);

You have to be somewhat careful what text you connect to what. Remember, the Text you are creating will insert itself after the Text you give it to be its basis. So, for example, if I had passed start as the basis of the last Text instead of middle, I would get text looking like "REDBLUE and ".

If you have several Text objects chained together like this, you can ask one of them to retrieve the previous or next one:

public Text getNext()
public Text getPrevious()

These methods will return null if there is no further text in the requested direction.

5. Setting the alignment of a Text

Your browser doesn't do Java.
TextAlign.java
Just as in a word processing program, you have the option to align text however you wish. Alignment is specified in terms of which side the text is aligned along. So, for example, the text you are reading now is left-aligned, because the left edge of the paragraph makes a straight line up against the left edge of your window.

public void setAlignment(double horizontalAlign, double verticalAlign)
public double getHorizontalAlignment()
public double getVerticalAlignment()

The horizontal and vertical alignment are specified with double values, where -1 is left or top and 1 is right or bottom. In actual practice, you will usually use constants in the Text class that stand for these values; this makes it easier to read your code. But if you ever need an alignment that isn't exactly one of those three, know that the option exists to pass along a different double value.

text.setAlignment(Text.CENTER, Text.TOP);
if(text.getVerticalAlignment() == Text.TOP) {
   ...

Since the alignment specifies which edge the text is aligned along, it may be a bit confusing how it works when you are aligning to a point or a line. For example, aligning along the TOP actually puts your text below a point or line that is its basis. Try out the applet to the right to get an idea of what this looks like.

If you have a Text comprised of many Text's chained together, as described in the previous section, they all share one alignment. Setting or getting the alignment of any one of them refers to this shared alignment.

6. Complete listing of the Text specification

Here are all the constructors and methods in the Text class that aren't among the Shared Shape Methods. Text also has most of the methods of Rectangular Shapes, except that it can't be resized.

public Text(<Something> text, double x, double y, DrawingCanvas canvas)
public Text(<Something> text, double x, double y, Color color, DrawingCanvas canvas)
public Text(<Something> text, Location point, DrawingCanvas canvas)
public Text(<Something> text, Location point, Color color, DrawingCanvas canvas)
public Text(<Something> text, DrawableInterface basis, DrawingCanvas canvas)
public Text(<Something> text, DrawableInterface basis, Color color, DrawingCanvas canvas)

public DrawableInterface getBasis()

public void setFont(String fontName)
public void setBold(boolean b)
public void setItalic(boolean i)
public void setBold()
public void setItalic()
public void setPlain()
public void setFontSize(int size)
public void setFont(Font font)
public Font getFont()

public Text getNext()
public Text getPrevious()

public void setAlignment(double horizontalAlign, double verticalAlign)
public double getHorizontalAlignment()
public double getVerticalAlignment()