Label

Introduction

Label provides a way to display a string to the user. Unlike TextBox, Labels cannot be changed by typing on the keyboard.

Code Example: Adding a Label

The following code adds a Label instance to the root:

// Initialize
var label = new Label();
label.AddToRoot();
label.Text = "This is a Gum label";

Try on XnaFiddle.NET

Label in Gum

Text Wrapping

By default a Label sizes itself to fit its text content, so text does not wrap. To enable wrapping, give the Label a fixed width by setting its WidthUnits to Absolute and specifying a Width value. The height can remain RelativeToChildren so the Label grows vertically as needed.

// Initialize
var label = new Label();
label.AddToRoot();
label.Text = "This is a long string of text that will wrap to multiple lines when the label has a fixed width.";
label.Visual.Width = 200;
label.Visual.WidthUnits = Gum.DataTypes.DimensionUnitType.Absolute;
label.Visual.HeightUnits = Gum.DataTypes.DimensionUnitType.RelativeToChildren;

Try on XnaFiddle.NET

Text Alignment

The horizontal and vertical alignment of the text within the Label's bounding box is controlled through the HorizontalAlignment and VerticalAlignment properties on the TextComponent. Cast TextComponent to TextRuntime to access these properties.

// Initialize
var label = new Label();
label.AddToRoot();
label.Text = "Centered text";
label.Visual.Width = 300;
label.Visual.WidthUnits = Gum.DataTypes.DimensionUnitType.Absolute;
label.Visual.Height = 100;
label.Visual.HeightUnits = Gum.DataTypes.DimensionUnitType.Absolute;
var textRuntime = (Gum.GueDeriving.TextRuntime)label.TextComponent;
textRuntime.HorizontalAlignment = RenderingLibrary.Graphics.HorizontalAlignment.Center;
textRuntime.VerticalAlignment = RenderingLibrary.Graphics.VerticalAlignment.Center;

Try on XnaFiddle.NET

Auto-Sizing to Text Content

By default a Label's WidthUnits and HeightUnits are set to RelativeToChildren, which means the Label automatically sizes to match its text. When you change Text, the Label grows or shrinks to fit the new content with no additional code required.

// Initialize
var label = new Label();
label.AddToRoot();
// By default a Label sizes to its text content
label.Text = "Short text";
// Assign longer text and the label grows automatically
label.Text = "This is a much longer string of text";

Try on XnaFiddle.NET

To constrain a Label to a fixed size and prevent it from growing with its content, set WidthUnits to Absolute and assign an explicit Width.