Text

Introduction

Text objects have a Text property which controls the displayed text. By default this value is set to "Hello".

Changing Text

The Text property can be changed in the multi-line edit window.

Text will wrap according to the Text object's Width.

The enter key can be used to add new lines to text.

Text Wrapping

Text instances can optionally wrap their text based on width units. By default Text instances use a Width Units of Relative to Children which means the text does not wrap.

Width Units of Relative to Children

This Width Units results in the Text automatically resizing itself in response to its Text variable, resulting in no wrapping.

Changing the Text results in making the Text instance wider and does not wrap

Any other Width Unit can be used to make the text wrap. For example, setting Width Units to Absolute and changing Width results in wrapping.

Absolute Width can make Text wrap

For a deeper dive into Width Units, see the Width Units page.

Using BBCode for Inline Styling

Gum text supports inline styling using BBCode-like syntax. To add inline styling, surround text with variable assignment tags as shown in the following screenshot:

Red color using BBCode syntax

The following table shows the available variables that can be used for inline styling:

Tag	Example	Result
Color	This is [Color=orange]orange[/Color] text.
Red Green Blue	This is [Red=0][Green=128][Blue=255]light blue[/Red][/Green][/Blue] text.
FontScale	This is [FontScale=2]big[/FontScale] text.
IsBold	This is [IsBold=true]bold[/IsBold] text.
IsItalic	This is [IsItalic=true]italic[/IsItalic] text.
Font	This is [Font=Papyrus]Papyrus[/Font] text.
FontSize	This is [FontSize=36]bigger[/FontSize] text.
OutlineThickness	This is [OutlineThickness=2]outlined[/OutlineThickness] text.

Note that changing Font and FontSize results in new Fonts created in the Font Cache.

BBCode can span multiple lines, whether the newlines happen due to line wrapping or through the addition of newlines in the text.

Text object with inline styling and explicit line breaks

Multiple tags can overlap each other allowing you to combine tags for a single piece of text. For example, the following sets text to both bold and orange:

This is [Color=Orange][IsBold=true]bold and orange[/Color][/IsBold] text.

Styled text that is bold and orange.

Styles can contain other styles as many levels deep as necessary.

This [Color=Orange]is orange, [IsBold=true]bold[/IsBold], and [IsItalic=true]italic[/IsItalic][/Color] text.    

BBCode Color and Alpha

Color values can be specified using named colors or individual Red, Green, and Blue values.

Color values can be specified using any of the standard XNA color values, as listed here: https://docs.monogame.net/api/Microsoft.Xna.Framework.Color.html

MonoGame adds MonoGameOrange which is not available in other XNA-likes such as KNI and FNA. Gum UI uses KNI for rendering, so this property is not available in the Gum UI tool, but is available at runtime if you are using MonoGame.

If you need precise color values, then you should use the individual Red, Green, and Blue values.

Keep in mind that if a color value is not specified, then the default for that Text instance is used.

For example, a Text's Red may have Red, Green, Blue values of 255, 0, 0 as shown in the following image:

Text with explicitly set Red, Green, and Blue values

If its Green value is set in BBCode, the green value from BBCode overrides the Green variable value, but the Red and Blue values from its variables persist. BBCode values are applied after all variables.

Green value of 200 overriding the default value of 0

Similarly, if a Color tag is used, then the BBCode color specified overrides all color variable values. This includes Red, Green, Blue, and Alpha. The following image is a yellow text with an Alpha value of 15, resulting in text that is almost completely transparent:

Yellow text with an alpha of 15

By specifying a Color value in BBCode, the Alpha value is also overwritten, as shown in the following image:

Green overrides Alpha

To preserve alpha, the individual Red, Green, and Blue values must be specified.

Specifying only Red, Green, and Blue preserves the previously-set Alpha value