Component Runtimes

Introduction

Components in a Gum project can be instantiated in custom code. Custom components can be created in code for a number of reasons:

1. To create a variable number of items, such as items in an inventory component

2. To create popups which may appear at any point in the app

Code Example - Instantiating a Component

Before instantiating a component from a Gum project, you must first have your Gum project loaded. For more information see the Loading a Gum Project page.

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
ObjectFinder.Self.GumProjectSave.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.

ColoredRectangleComponent in Gum

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

StandardButton component in the Buttons folder in Gum

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

For more information about how to add a newly-created component runtime to managers or to a container, see the next section.

Adding a Component Runtime to a Parent

A newly-created component must be added directly or indirectly to managers. The following are the possible ways to add to managers:

Adding to a Container

The newly instantiated component can be added to a container in the screen. This container can be an actual ContainerRuntime instance, or to a control such as a ListBox.

// do not add to managers, since it will be added to a container
var newComponentRuntime = componentSave.ToGraphicalUiElement(
    SystemManagers.Default, addToManagers:false);
// assuming ScreenRoot is a valid root
var container = ScreenRoot.GetGraphicalUiElementByName("DesiredContainer");
container.Children.Add(newComponentRuntime);

To destroy the component, remove it from its parent, or set its parent to null:

newComponentRuntime.Parent = null;

Adding to PopupRoot/ModalRoot

The newly instantiated component can be added either the PopupRoot or ModalRoot. PopupRoot is used for popups which should appear on top of other controls, but which should not steal input. ModalRoot is used for popups which should steal focus from all other controls.

The following code shows how to create a Toast instance to display a message to a user. The code assumes your code has a valid Toast component.

// assumes toastComponent is a valid component
var newToastRuntime = toastComponent.ToGraphicalUiElement(
    SystemManagers.Default, addToManagers:false);
FrameworkElement.PopupRoot.Children.Add(newToastRuntime);
// the newToastRuntime needs to be removed from PopupRoot later

The following code shows how to create a MessageBox instance and add it to the ModalRoot so it receives exclusive input.

// assumes toastComponent is a valid component
var newMessageBoxRuntime = messageBoxComponent.ToGraphicalUiElement(
    SystemManagers.Default, addToManagers:false);
FrameworkElement.ModalRoot.Children.Add(newMessageBoxRuntime);
// the newMessageBoxRuntime needs to be removed from ModalRoot later

To destroy the component, remove it from its parent, or set its parent to null:

newMessageBoxRuntime.Parent = null;

Adding to Managers

Components can be added directly to managers. Usually items are only added directly to managers in the following situations:

• If they are the root runtime. Usually this is a Screen, but it can be a component if your project is not using screens.

• For testing/debugging.

• If your game has multiple roots, you can add instances to a list of GraphicalUiElements which are passed to Update. This is considered an advanced scenario.

var newComponentRuntime = componentSave.ToGraphicalUiElement(
    SystemManagers.Default, addToManagers:true);

To destroy the component, call RemoveFromManagers:

newComponentRuntime.RemoveFromManagers();

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:

Component exposing a 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);