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

TextInstance.AdjustPositionForPixelPerfectDrawing = false;

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

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

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 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 MaxWidthBehavior controls how the Text object displays its when it is longer than the . 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.

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

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

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.

NewlineDistance rounds to whole numbers if AdjustPositionForPixelPerfectDrawing is true

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:

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

Related Articles

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 or . 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 .

Scale and Position

If you've read about the 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 and properties. Therefore, to find the center of your Text object, you should use the and properties.

Code example

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

Add the following to the Initialize method after initializing FlatRedBallServices:

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 DisplayText 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:

TextInstance.SetColor(0, 1, .5f);

is the same as:

TextInstance.Red = 0;
TextInstance.Green = 1;
TextInstance.Blue = .5f;

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

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 . For more information on this behavior, see . 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:

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:

Moving 3D Camera Exaple

Add the following to the same Screens' CustomActivity:

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.