Introduction

Components in a Gum project can be instantiated in custom code. Note that this is not a requirement to use a component since you can also add an instance of the component in your screen.

Code Example - Instantiating a Component

Before instantiating a component, you must first load the project using the standard .gumx loading code as shown in the following code block:

var gumProject = GumProjectSave.Load("GumProject.gumx", out _);
ObjectFinder.Self.GumProjectSave = gumProject;
gumProject.Initialize();

Once you have instantiated your project, you can create a component as shown in the following code:

// This assumes that your project has at least 1 component
gumProject.Components.First()
    .ToGraphicalUiElement(SystemManagers.Default, addToManagers:true);

The Components property contains a list of all components, so you can also access components by name or other property. For example, the First method can be used to find a component by name as shown in the following code:

var componentSave = ObjectFinder.Self.GumProjectSave.Components
    .First(item => item.Name == "ColoredRectangleComponent");

var componentRuntime = componentSave.ToGraphicalUiElement(SystemManagers.Default, addToManagers: true);
// the componentRuntime can be modified here

Note that the name passed to the First method should match the name given in Gum. For example, in this case the code searches for a component named ColoredRectangleComponent.

If a component is in a folder, then its name is the qualified name relative to the Components folder. For example, the following component's name at runtime is "Buttons/StandardButton"

The ToGraphicalUiElement method can automatically add the component to the root for rendering, or alternatively it can be added to an existing container. If adding to an existing container, then the ToGraphicalUiElement's addToManagers parameter should be false as shown in the following code:

var component = var componentSave = ObjectFinder.Self.GumProjectSave.Components
    .First(item => item.Name == "MyComponent");
    
var componentRuntime = componentSave.ToGraphicalUiElement(
    SystemManagers.Default, addToManagers: false);
// This assumes that container has been directly added to managers, or is a 
// child of a root container which has been added to managers:
container.Children.Add(componentRuntime);

Troubleshooting Component Creation

If your component is not visible, this may be a file issue. By default Gum project loading will not throw exceptions on missing files, and it will attempt to re-create missing file components. For more information, see the Troubleshooting section in the Loading .gumx page.

SetProperty

The SetProperty method can be used to set properties on components which are not natively part of GraphicalUiElement. This is useful in the following situations:

• Setting a property which may not exist on all GraphicalUiElements, such as the Text property on a GraphicalUiElement for a Text standard element

• Setting a property which has been exposed

If a GraphicalUiElement is a Text instance, the Text property can be assigned through SetProperty as shown in the following code:

myTextInstance.SetProperty("Text", "I'm set in code");

If a component has an exposed variable, then this variable can be assigned through SetProperty. For example, consider the following component which exposes its Text variable:

This can be assigned through the SetProperty. Be sure to use the name exactly as it appears in Gum:

myExposedVariableComponentInstance.SetProperty("Text", "I'm set in code");

Apply State

States can be applied in code by string (unqualified name), or by accessing the state on the backing ComponentSave. Note, this can also be performed on screens and standards.

 var setMeInCode = currentScreenElement.GetGraphicalUiElementByName("SetMeInCode");

 // States can be found in the Gum element's Categories and applied:
 var stateToSet = setMeInCode.ElementSave.Categories
     .FirstOrDefault(item => item.Name == "RightSideCategory")
     .States.Find(item => item.Name == "Blue");
 setMeInCode.ApplyState(stateToSet);

 // Alternatively states can be set in an "unqualified" way, which can be easier, but can 
 // result in unexpected behavior if there are multiple states with the same name:
 setMeInCode.ApplyState("Green");

 // states can be constructed dynamically too. This state makes the SetMeInCode instance bigger:
 var dynamicState = new StateSave();
 dynamicState.Variables.Add(new VariableSave()
 {
     Value = 300f,
     Name = "Width",
     Type = "float",
     // values can exist on a state but be "disabled"
     SetsValue = true
 });
 dynamicState.Variables.Add(new VariableSave()
 {
     Value = 250f,
     Name = "Height",
     Type = "float",
     SetsValue = true
 });
 setMeInCode.ApplyState(dynamicState);

The ColoredRectangleRuntime object can be used to draw a solid (filled) rectangle of any color. To draw a rectangle outline (not filled in), see the RectangleRuntime type.

Code Example

The following code creates a ColoredRectangleRuntime:

var coloredRectangleInstance = new ColoredRectangleRuntime();
coloredRectangleInstance.Width = 120;
coloredRectangleInstance.Height = 24;
coloredRectangleInstance.Color = Color.White; // This is a Microsoft.Xna.Framework.Color
container.Children.Add(coloredRectangleInstance);

Introduction

MonoGameGum provides common runtime types which can be used to build your layouts. The runtime objects correspond to the standard objects in the Gum tool. These provide a type-safe, expressive way of creating and working with Gum. The following runtime objects exist:

• ColoredRectangleRuntime

• ContainerRuntime

• NineSliceRuntime

• SpriteRuntime

• TextRuntime

Notice that at the time of this writing, only a subset of Gum standard types are available. This is likely to expand over time.

All runtime objects inherit from GraphicalUiElement, which is the base class for all Gum objects. Therefore, all runtime objects share the same properties for position (such as X and XUnits), size (such as Width and WidthUnits), and rotation.

For a reference to the type of properties available on GraphicalUiElement, see the Gum Elements General Properties section. For information about working with GraphicalUiElement properties in code, see the GraphicalUiElement reference.

Introduction

The InteractiveGue class provides a base class for custom runtimes which need to interact with the cursor. All visuals for Gum Forms should implement InteractiveGue.

Introduction

The CurrentInputReceiver property gets and sets the current object which is receiving input from the keyboard. Only one element can be the CurrentInputReceiver at one time, but this property may be null if no elements are receiving input.

This property can be set in a number of ways:

1. Forms objects such as TextBox set themselves as the CurrentInputReceiver when clicked

2. Setting IsFocused = true on some Forms objects such as TextBoxes sets this

3. Explicitly setting CurrentInputReceiver sets this value, but keep in mind that doing so may not result in objects updating their states appropriately, so this typically should be assigned internally

Introduction

ContainerRuntime is a GraphicalUiElement-inheriting object used to organize and perform layout on a specific group of objects. Examples of when to use a container include:

• Providing margins inside the screen or another container

• Aligning or orienting children along a common position

• Changing children layout types, such as stacking children horizontally inside a parent container which stacks its children vertically

• To inject spacing between objects when using ratio width or height

ContainerRuntime instances have no visuals, so they cannot be directly observed in game.

Example - Creating a ContainerRuntime

To create a ContainerRuntime, instantiate it and add it to the managers as shown in the following code:

var container = new ContainerRuntime();
container.Width = 150; // by default, containers use absolute width...
container.Height = 150; // ...and height.
container.AddToManagers(SystemManagers.Default, null);

Children (Containers as Parents)

Containers are usually used as parents for other runtime objects. To add another runtime instance to a container, add it to the Children list as shown in the following code:

var parentContainer = new ContainerRuntime();
parentContainer.AddToManagers(SystemManagers.Default, null);

var childText = new TextRuntime();
childText.Text = "I am a child TextRuntime";
parentContainer.Children.Add(childText);

Notice that only the parent object needs to have its AddToManagers method called. Any child added to a parent which has been added to managers is automatically added as well. This membership is cascaded through all children, so if your project has a single root object, then only that root object needs to be added (or removed) from managers.

The following code shows a parent container added to managers. The child container and child text do not need to be added to managers:

var parentContainer = new ContainerRuntime();
parentContainer.AddToManagers(SystemManagers.Default, null);

var childContainer = new ContainerRuntime();
// By adding the childContainer to the parentContainer, we do not need
// to call childContainer.AddToManagers
parentContainer.Children.Add(childContainer);

var textRuntime = new TextRuntime();
textRuntime.Text = "I do not need my AddToManagers method called either.";
childContainer.Children.Add(textRuntime);

Introduction

The RollOverBubbling event is raised whenever the cursor rolls over an InteractiveGue. A roll is defined as the cursor being positioned over the bounds of an InteractiveGue when the cursor's X or Y values have changed.

This event is raised top-down, with children object having the first opportunity to handle the event. If the event is not handled by the child, then parents have the opportunity to handle the event. If the RoutedEventArgs Handled property is set to true, then no parents receive the event.

Code Example - Scrolling with Cursor Press

The following code shows how to implement ListBox scrolling using the cursor when the cursor is pressed.

// This will work with any item that has a scrollbar, such as
// ListBox, ItemsControl, and ScrollViewer
listBox.Visual.RollOverBubbling += (sender, args) =>
{
    var cursor = FormsUtilities.Cursor;

    // Only handle this if the crusor is pressed
    if (cursor.PrimaryDown)
    {
        // we can get the vertical scroll bar through visuals:
        var scrollBarVisual = (InteractiveGue) listBox.Visual.GetChildByNameRecursively(
            ListBox.VerticalScrollBarInstanceName);

        // InteractiveGues provide a FormsControlAsObject property to access
        // the forms object.
        var scrollBar = (ScrollBar)scrollBarVisual.FormsControlAsObject;

        // Change the ScrollBar's value which results in the ListBox scrolling.
        scrollBar.Value -= cursor.YChange /
            global::RenderingLibrary.SystemManagers.Default.Renderer.Camera.Zoom;

        // set the Handled property true so children do not get this
        args.Handled = true;
    }
};

Introduction

The NineSliceRuntime object is used to draw a visual object which references a Texture2D, but which does not stretch the corner pieces of a texture, and which only stretches the edges between the corners along their axis. In other words, the NineSlice (sometimes also referred to as a sprite frame) is used to draw frames in UI which can stretch without introducing visual artifacts.

For more information about the NineSlice type, see the NineSlice page.

Code Example

The following code can be used to instantiate a NineSliceRuntime which uses a Texture (png file) named Frame.png.

var nineSlice = new NineSliceRuntime();
nineSlice.SourceFileName = "Frame.png";
nineSlice.Width = 256;
nineSlice.Height = 48;
container.Children.Add(nineSlice);

Assigning NineSlice Texture

NineSlice textures can be assigned using a string property or Texture2D instance. When assigning using a string, the ToolsUtilities.FileManager.RelativeDirectory is used to determine the file's directory.

For example, consider a file called Frame.png which is located in the Content directory:

This file can be used as a texture by assigning the RelativeDirectory and then loading Frame.png. Note that RelativeDirectory is usually set to Content, or to the location of the .gumx file.

ToolsUtilities.FileManager.RelativeDirectory = "Content";
nineSlice.SourceFileName = "Frame.png";

Alternatively, a Texture2D can be assigned directly

// assuming MyTexture is a valid Texture2D
nineSlice.SourceFile = MyTexture;

Once a SourceFileName is assigned, the SourceFile property references a valid Texture2D which can be reused.

// assigning SourceFileName results in SourceFile also being set
firstNineSlice.SourceFileName = "Frame.png";
secondNineSlice.SourceFile = firstNineSlice.SourceFile;

TextureAddressMode and Texture Coordinates

By default a NineSlice uses it entire texture. This can be customized using texture coordinate and TextureAddress properies as shown in the following code:

nineSlice.TextureLeft = 0;
nineSlice.TextureTop = 16;
nineSlice.TextureWidth = 32;
nineSlice.TextureHeight = 32;
nineSlice.TextureAddress = Gum.Managers.TextureAddress.Custom;

Note that if TextureAddress isn't set to Custom, then the four coordinate values are ignored and the entire texture is used.

The RectangleRuntime object can be used to draw a single-pixel-wide rectangle. It can either have a solid outline or dotted, and can display any color. RectangleRuntimes only draw outlines. For filled rectangles see the ColoredRectangleRuntime type.

Code Example

The following code creates a RectangleRuntime:

var lineRectangle = new RectangleRuntime();
lineRectangle.Width = 120;
lineRectangle.Height = 24;
lineRectangle.Color = Color.Pink;  // This is a Microsoft.Xna.Framework.Color
container.Children.Add(lineRectangle);

Introduction

The SpriteRuntime object can be used to draw a Texture2D to screen. It supports drawing the entire texture or a portion. It also provides the ability to scale according to the source texture size and aspect ratio.

Code Example

The following code can be used to instantiate a Sprite which uses a Texture (png file) named BearTexture.png.

SpriteRuntime Texture

A SpriteRuntime's texture can be assigned using the name of the file or a direct Texture2D reference.

Assigning SourceFileName

The SourceFileName property is used to assign the SpriteRuntime's texture using a file name. The name of the file should (by default) be relative to the Content folder. For example, consider the following line:

This code assumes that the file is relative to the project's Content folder, as shown in the following screenshot:

Assigning Texture

If your game manages its own textures, you can assign a Texture on the SpriteRuntime through its Texture property as shown in the following code.

Note that assigning the SourceFileName property results in the Texture property referencing a texture if a valid texture is found.

Introduction

The TextRuntime object is used to draw strings to the screen. It supports a variety of options for rendering text including alignment, fonts, coloring, and line wrapping.

Example - Creating a TextRuntime

To create a TextRuntime, instantiate it and add it to the managers as shown in the following code:

Example - Obtaining a TextRuntime Reference From a Gum Project

To get a TextRuntime instance from a loaded Gum (gumx) project, add the following code. This code assumes you have an object named CurrentScreen, and that it contains a Text instance named TextInstance:

Fonts

By default all TextRuntime instances use an Arial 18 pt font. This can be changed by specifying ta custom font.

Fonts on TextRuntime objects can be modified in one of the following ways:

1. By setting the UseCustomFont property to true, then changing the CustomFontFile property to a desired .fnt file.

2. By directly assigning the BitmapFont property on the TextRuntime object, bypassing all other properties.

3. By setting UseCustomFont property to false, then changing the individual Font values. This approach requires following a specific .fnt naming convention.

For most projects, the first approach is recommended since it doesn't require specific naming conventions. The second approach also works well if you are directly loading the BitmapFont object yourself. The third approach is convenient if your project is using the Gum tool, and if the Gum tool has already generated fonts for the specific combinations of values you are assigning.

Assigning CustomFontFile

The following code shows how to load a custom font (the first approach):

Note that .fnt files reference one or more image files, so the image file must also be added to the correct folder. In this case, the WhitePeaberryOutline.fnt file references a WhitePeaberryOutline.png file, so both files are in the same folder.

Also, note that files are loaded from-file rather than using the content pipeline. This means that extensions (such as .fnt) are included in the file path, and that both the .fnt and .png files must have their Copy to Output Directory value set to Copy if newer.

Assigning BitmapFont

The following code shows how to assign the BitmapFont property on a TextRuntime:

Font Component Values

A TextRuntime's font can be controlled by its individual font component values. Setting these values in code will not produce a .fnt file for you - the .fnt file must already be in your project in the FontCache folder. The following values are used to determine the font (.fnt) to load:

• FontSize

• Font

• OutlineThickness

• UseFontSmoothing

• IsItalic

• IsBold

By default, all fonts will be of the format Font{Font}{FontSize}.fnt. Consider the following code:

This results in the TextRuntime object searching for a font named FontArial24.fnt.

The following additional suffixes (in order listed below) are added to the font name.

• OutlineThicknes - if greater than 0, then the suffix _o followed by the outline thickness is added. For example, if OutlineThickness is 3, a font might be named FontArial24_3.fnt

• UseFontSmoothing - if false, then _noSmooth is appended. For example Font24_noSmooth.fnt

• IsItalic - if true, then _Italic is appended. For example Font24_Italic.fnt

• IsBold - if true, then _Bold is appended. For example Font24_Bold.fnt

The BmfcSave.GetFontCacheFileNameFor method can be called with any combination to obtain the desired font value. For example, the following code coudl be used to determine the desired .fnt file:

Note that this method does not take into consideration the content folder.

Creating Fonts

To create a .fnt file, you have a few options:

1. Open Gum, create a temporary Text instance with the desired properties, then look at the font cache folder

3. Manually create a .fnt file in a text editor and a corresponding .png. This option requires understanding how the .fnt file format is structured. The best way to learn this is to open an existing font file.

Using Gum to create the font cache is fairly simple, but you must know which fonts you intend to use ahead of time. A font is created automatically by the Gum tool whenever a Text property is changed.

To view the existing font cache, you can click the View Font Cache menu item in Gum.

As you make changes to the Text object, new files are created and added to the font cache folder, as shown in the following animation:

Missing Font Exceptions

By default TextRuntime instances do not throw exceptions for missing font files even if GraphicalUiElement.ThrowExceptionsForMissingFiles is set to CustomSetPropertyOnRenderable.ThrowExceptionsForMissingFiles. The reason for this is because a TextRuntime's font is decided by a combination multiple properties.

If UseCustomFont is set to false, then the font is determined by the combination of font values (as discussed above). If useCustomFont is set to true, then the font is determined by the CustomFontFile (also as discussed above).

Ultimately the variables which are used for fonts can be assigned in any order, and can be assigned from multiple spots (such as direct assignments, states, or creation from Gum projects).

In other words, the TextRuntime doesn't know when variable assignment is finished. We can address this in a few different ways.

The first is to explicitly load the desired BitmapFont as discussed above. By calling the BitmapFont constructor, missing files will immediately throw an exception.

Another option is to use the GraphicalUiElement.ThrowExceptionsForMissingFiles method to verify if a font is valid.

The following code example shows how to check for invalid fonts using this method: