Introduction

The Text class implements the IColorable interface. This gives the Text object lots of flexibility in controlling how it will appear.

For information that is general to all IColorables, see the IColorable page.

Default Behavior

By default the Text class has the following IColorable properties:

Notice that the ColorOperation is "ColorTextureAlpha". This means that the Texture will control the transparency (of course, also considering the Text's Alpha property), but the color is controlled purely by the Red, Green, and Blue properties.

Therefore, by default, the Text object will completely ignore color information from its source Texture and use only the three color components that are set.

This can be easily changed, of course. If you want to set the color of your text from its source texture (as might be the case when doing outlined text), consider changing the ColorOperation to Texture or Modulate depending on the effect you are interested in achieving.

Introduction

The AdjustPositionForPixelPerfectDrawing method tells the FlatRedBall Engine to attempt to offset Text objects so that they do not render in-between pixels. This value defaults to true, and in most cases you do not need to adjust it.

When to adjust AdjustPositionForPixelPerfectDrawing

AdjustPositionForPixelPerfectDrawing should be turned off if FlatRedBall is not properly adjusting your Text objects to be pixel perfect. One common scenario for this is if a Text object is on a camera other than the default Camera.

Code Example

The following assumes that "TextInstance" is a valid Text object:

The Font property gets and sets the BitmapFont that the Text will use when it's drawn. This property can be set at any time to change the BitmapFont that the Text object uses.

For more information, see the BitmapFont page

Introduction

The Text object provides functionality for drawing bitmap fonts in 2D and 3D space. It inherits from the class and shares many similarities with the class. Just as the class is associated with the , the Text object is associated with the . Note that most games which use Text do so through Gum instead of using the FlatRedBall Text object.

Creating a Text Instance in Code

The FlatRedBall engine stores a default internally. Any Text object created will use this default . To create a Text object in code, add the following to your Screen's CustomInitialize, or Game1.cs Initialize after initializing FlatRedBall:

A note about persistence

The Text object behaves the same as other FlatRedBall objects which have been added to their respective managers. This means that when you add a Text object, it will be drawn and updated automatically for you until it is removed.

You should not add text every frame

A common mistake is to add and remove text every frame to change what it displays. Instead of doing this, you should set a text's DisplayText property to change what it says. For example:

For more information on the persistence of objects, see . For code example comparing the approach of creating a new text vs. setting the DisplayText, see the .

DisplayText Property

The DisplayText property allows for changing the string that a Text object renders. The following code sets the text depending on whether the user has a gamepad connected: Add the following include statements:

Add the following to the Initialize method after initializing FlatRedBallServices:

Text Object as PositionedObject

Text objects can be positioned just like any PositionedObject. For example, a text object's X and Y values can be set:

For more information on fields and properties, see the .

Text Size

By default Text objects added through the FRB editor are sized to be pixel perfect given the game's resolution. The Text object provides a number of properties for changing size.

TextureScale

TextureScale controls the size of the text relative to its source texture. A TextureScale of 1 results in the text drawing pixel perfect if the game is running at 100% scale. If the game runs at larger scale, then Text using a fixed TextureScale will drawn larger.

SetPixelPerfectScale

The SetPixelPerfectScale function sets the text size to be pixel perfect given the argument camera or layer. The following code sets the Text to be pixel perfect to the main camera:

Note that pixel-perfect text will not appear zoomed if the game settings are zoomed.

Individual Scale Values

The Text object provides three different variables for changing the size of text. These properties are:

• Scale

• Spacing

• NewLineDistance

The following code creates three text objects which have non-default values for these three properties.

Text Members

Inherited Classes and Implemented Interfaces

• - Properties for changing a Text's color.

Related Articles

• - Text implements the IAttachable interface.

Did this article leave any questions unanswered? Post any question in our for a rapid response.

Introduction

The MaxWidth value controls the available area that the Text object can render text inside. The Text object will either wrap or clamp text according to its .

Code Example

Introduction

The DisplayText property controls what a Text object will write to the Screen. The DisplayText property can be set to initially set what the Text will display, and it can be changed at any time. The DisplayText property should be used to change a Text's display instead of re-creating a new Text every frame or whenever the Text changes.

Code Example

The following code shows how to display how much time has been running since the start of the game:

Add the following using statement:

using FlatRedBall.Graphics;

Add the following at class scope:

Text mText;

Add the following to Initialize after initializing FlatRedBall:

string initialDisplay = "0";
mText = TextManager.AddText(initialDisplay);

Add the following to Update:

mText.DisplayText = TimeManager.CurrentTime.ToString();

Introduction

HorizontalAlignment determines how the text aligns itself according to the Text's X position. By default text is left justified, so the left side of the first letter will be placed at the Text's X value.

Code Example

The Text object's X value marks the left side of the text object by default - that is, text is left justified by default. This justification or alignment can be changed. The following code creates three text objects with different HorizontalAlignment.

Text leftJustified = TextManager.AddText("Left justified");
leftJustified.Y = 30;

Text centerJustified = TextManager.AddText("Center Justified");
centerJustified.HorizontalAlignment = HorizontalAlignment.Center;

Text rightJustified = TextManager.AddText("Right Justified");
rightJustified.HorizontalAlignment = HorizontalAlignment.Right;
rightJustified.Y = -30;

The dotted line above shows the X position of the Text objects.

Introduction

The MaxWidthBehavior controls how the Text object displays its DisplayText when it is longer than the MaxWidth. MaxWidthBehavior is an enumeration. Available values are:

• Chop

• Wrap

The default behavior is Chop.

Code Example

The following code creates 2 Text objects. It assumes a 3D camera.

Text clampText = TextManager.AddText(
    "Hello I am some long text.  I need to be long so that I extend past the max width");
clampText.MaxWidth = 10;

Text wrapText = TextManager.AddText(
    "Hello I am some long text.  I need to be long so that I extend past the max width");
wrapText.MaxWidthBehavior = MaxWidthBehavior.Wrap;
wrapText.MaxWidth = 10;
wrapText.Y = -5;

The InsertNewLines method modifies the Text's DisplayText property by inserting the newline character ('\n') to prevent the text from exceeding the argument maxWidth. The maxWidth property is in absolute world units.

Add the following using statements:

Add the following to Initialize after initializing FlatRedBall:

Additional Information

• - See the BitmapFont class for determining the unit-size of your text.

Width returns the distance in absolute world coordinates from the left side of the Text instance to the right. This value reacts to font size, word wrapping, and the Text's property.

The SetColor method can be used to set all 3 components of a Text's color values. The end result of calling this function is the same as setting the individual components. In other words:

is the same as:

For more information on how the Red, Green, and Blue colors impact rendering, see the .

The NumberOfLines property returns the number of lines that the Text object will occupy when rendering. this value corresponds to the number of newline characters in the text object ('\n'). Newline characters can be added manually to the DisplayText property, by calling , or automatically according to the Text's .

Introduction

The GetWidth method returns the width of a piece of text. The GetWidth method returns the width of text, and can accept a variety of arguments. The overloads provide flexibility depending on how much information is needed.

Overloads

public static float GetWidth(string text)

public static float GetWidth(string text, float spacing)

public static float GetWidth(string text, float spacing, BitmapFont font)

public static float GetWidth(string text, float spacing, BitmapFont font, int startIndex, int count)

public static float GetWidth(string text, float spacing, BitmapFont font, int startIndex, int count, List<float> widthList)

public static float GetWidth(Text text)

Code Example

The following code creates a Text object and a Line which can be moved between letters with the left and right arrows on the keyboard:

Add the following using statements:

using FlatRedBall.Graphics;
using FlatRedBall.Math.Geometry;
using FlatRedBall.Input;

Add the following to your Game or Screen's class scope:

Text mText;
int mIndex = 0;
Line mLine;

Add the following to your Game's Initialize or Screen's CustomInitialize:

mText = TextManager.AddText("Hello I am a string");
mLine = ShapeManager.AddLine();
mLine.SetFromAbsoluteEndpoints(
    new Vector3(0, 1, 0),
    new Vector3(0, -1, 0));

Add the following to your Game's Update or Screen's CustomActivity:

if (InputManager.Keyboard.KeyPushed(Keys.Right))
{
    mIndex++;
    if (mIndex > mText.DisplayText.Length)
    {
        mIndex--;
    }
    UpdateToIndex();
}
if (InputManager.Keyboard.KeyPushed(Keys.Left))
{
    mIndex--;
    if (mIndex < 0)
    {
        mIndex = 0;
    }
    UpdateToIndex();
}

Add the following function at class scope:

private void UpdateToIndex()
{
    float position = TextManager.GetWidth(
        mText.DisplayText, mText.Spacing, mText.Font, 0, mIndex);

    mLine.X = mText.X + position;
}

Introduction

The NewlineDistance property sets the amount of spacing between lines on a Text object. This value is set according to the Camera/Layer settings automatically when the Text is added to managers, but it can be modified after the fact to adjust spacing.

Code Example (2D Camera/Layer)

The default setup for FlatRedBall is to be in 2D coordinates. If so, then NewlineDistance will be measured in pixels. The following code creates two Text objects and shows how to adjust their NewlineDistance:

// Assuming a 2D camera:
Text text = TextManager.AddText("Regular\nnewline");

Text otherText = TextManager.AddText("Modified\nnewline");
otherText.X = 150;
otherText.NewLineDistance = 30;

Code Example (3D Camera/Layer)

The following code creates two Text objects and shows how to adjust their NewlineDistance. Note that this example was made with a 3D camera.

Text text = TextManager.AddText("Regular\nnewline");
// In a 3D camera, we need to set this to false if we want accurate NewlineDistances
text.AdjustPositionForPixelPerfectDrawing = false;

Text otherText = TextManager.AddText("Modified\nnewline");
otherText.X = 10;
otherText.NewLineDistance = 3;
otherText.AdjustPositionForPixelPerfectDrawing = false;

NewlineDistance rounds to whole numbers if AdjustPositionForPixelPerfectDrawing is true

Text object are designed to work in 2D coordinates by default. Therefore, NewlineDistance will round to the nearest integer value. To change this, you can set the Texts' AdjustPositionForPixelPerfectDrawing to false. The reason this happens is because if you are dealing with Text that has multiple lines and it is going to scroll vertically (like on a credits screen), then individual lines may appear to jitter when the text scrolls. If you are using 3D text, then you most likely do not want it to be adjusted for pixel perfect drawing anyway, so setting AdjustPositionForPixelPerfectDrawing to false will both resolve this issue and potential other issues with rendering te a Text object on a 3D Camera/Layer.

Introduction

The ScaleX and ScaleY properties are read-only properties in the Text class. You may be familiar with these properties through classes such as Sprite or AxisAlignedRectangle. Unlike those classes, the Text class's ScaleX and ScaleY properties are only used to read the dimensions of the Text object, not to set it. To set the size of your Text, you need to use the Scale, Spacing, and NewlineDistance properties. You can find out more about them here.

Scale and Position

If you've read about the IScalable interface, then you're likely familiar with the concept of Scale. To help you remember, Scale is the measure from the center of an object to its edge. Another way to put it is ScaleX is half of an object's width and ScaleY is half of an object's height. In most cases, the center of an object is the same as its Position. Therefore, adding or subtracting Scale from an object's position will give you its edges. This is not the case with Text objects because of the HorizontalAlignment and VerticalAlignment properties. Therefore, to find the center of your Text object, you should use the HorizontalCenter and VerticalCenter properties.

Code example

The following code creates two Text objects. It then creates two AxisAlignedRectangles which show the bounds of the Text object using ScaleX/ScaleY and HorizontalCenter/VerticalCenter properties. Add the following include statements:

using FlatRedBall.Math.Geometry;
using FlatRedBall.Graphics;

Add the following to the Initialize method after initializing FlatRedBallServices:

 Text text1 = TextManager.AddText("Short text");

 Text text2 = TextManager.AddText("Some longer text");
 text2.Y = -4;

 // Now create the AxisAlignedRectangles using the scale and position of the
 // texts we just created:
 AxisAlignedRectangle aaRect1 = ShapeManager.AddAxisAlignedRectangle();
 aaRect1.X = text1.HorizontalCenter;
 aaRect1.Y = text1.VerticalCenter;
 aaRect1.ScaleX = text1.ScaleX;
 aaRect1.ScaleY = text1.ScaleY;

 AxisAlignedRectangle aaRect2 = ShapeManager.AddAxisAlignedRectangle();
 aaRect2.X = text2.HorizontalCenter;
 aaRect2.Y = text2.VerticalCenter;
 aaRect2.ScaleX = text2.ScaleX;
 aaRect2.ScaleY = text2.ScaleY;

Introduction

VerticalAlignment determines how the text aligns itself according to the Text's Y position. By default text uses VerticalAlignment.Center, so the center of Y value of the Text will represent its center vertically.

Code Example

The Text object's Y value determines the position of the Text along with the Text's VerticalAlignment. Changing the VerticalAlignment will change the visible Y position of the text even though the Y value will be the same. The following code creates three Text objects with different VerticalAlignments.

Text topJustified = TextManager.AddText("Top justified");
topJustified.X = -5;
topJustified.VerticalAlignment = VerticalAlignment.Top;

Text centerJustified = TextManager.AddText("Center Justified");
centerJustified.VerticalAlignment = VerticalAlignment.Center;;

Text bottomJustified = TextManager.AddText("Bottom Justified");
bottomJustified.VerticalAlignment = VerticalAlignment.Bottom;
bottomJustified.X = 6;

Introduction

SetPixelPerfectScale is a method which will adjust a Text object so that it renders pixel-perfect on the argument Camera. This method is automatically called on Text objects when added to the FlatRedBall.Graphics.TextManager. For more information on this behavior, see the AddText page. In the simplest situations this function will automatically be called for you and you won't need to do anything to have Text appear properly. For more information on when to call this function, see the next section. SetPixelPerfectScale sets the following properties on the Text instance that calls it:

• Scale

• Spacing

• NewlineDistance

Common usage

You will not need to use SetPixelPerfectScale if you create a Text and do not adjust the Text object or the Camera after the Text object has been instantiated. However, you will need to call this method if any of the following modifications are made:

• The Camera's Z value is changed (assuming the Camera is 3D)

• The Camera's Orthogonal values are changed (assuming the Camera is Orthogonal)

• The Text's Z is changed (assuming the Camera is 3D)

• The Text is attached to an object with a different Z value than the Text (assuming the Camera is 3D)

• The Text is added to a Layer that uses a custom coordinate system (such as 2D Layers in Glue)

Glue uses SetPixelPerfectScale

Glue assumes that Text objects should be drawn pixel-perfect, so it calls SetPixelPerfectScale on Text objects after they are initialized in generated code. This means that you don't have to call SetPixelPerfectScale on Texts which are added through Glue, unless modifications are made after the generated code has executed.

Code Example

The following code shows how to use SetPixelPerfectScale:

Text text = TextManager.AddText("Hello");
text.Z = 5; // the Z has been modified, so let's adjust the scale

// If the Text were added to a Layer, then pass the Layer as the argument instead of the Camera
text.SetPixelPerfectScale(SpriteManager.Camera);

Moving 3D Camera Exaple

Text objects are true 3D objects - they can be scaled, rotated, and positioned in 3D space. Similarly, they are affected by their distance from the camera. If a Text object moves closer to a 3D Camera, or similarly if a 3D Camera moves closer to a Text object, it will apparently change size. This is often undesirable. Therefore, to "counter" the size change of a Text object when a 3D Camera changes its distance (often Z value), the Text's Scale, Spacing, and NewLineDistance must change. The SetPixelPerfectScale greatly simplifies this process. The following code creates 3 Text objects and sets the Camera's velocity so that it is slowly moving forward. One Text object remains unchanged while the other changes its size every frame by calling SetPixelPerfectScale. Add the following to a Screen's CustomInitialize Initialize method:

Camera.Main.Orthogonal = false;

text1 = TextManager.AddText("I'll stay the same size.");
text1.HorizontalAlignment = HorizontalAlignment.Center;

text2 = TextManager.AddText("I'll get resized.");
text2.HorizontalAlignment = HorizontalAlignment.Center;
text2.Y = 2;
  
// Make the camera move forward slowly.
SpriteManager.Camera.ZVelocity = -.6f;

Add the following to the same Screens' CustomActivity:

text2.SetPixelPerfectScale(SpriteManager.Camera);