Common Component Types

Introduction

This tutorial looks at some of the more common component types in Gum and how to work with them in code. This tutorial provides an introduction to common controls. For a deeper dive into each type of Forms control, see the Gum Forms Controls page.

If you've been following the previous tutorials, keep in mind that this tutorial begins with an empty TitleScreen. Since the previously-added buttons are being deleted, any code written must also be removed to no longer reference the buttons or you will get compile errors.

StackPanel

StackPanels are used to contain other controls in Forms. StackPanels are similar to Containers, but they default to stacking their children top-to-bottom. StackPanels also provide access to their children as Forms, whereas Containers provide access to the visuals of their children rather than the forms object. Therefore, you should usually use a StackPanel to contain children, or a Panel if you do not want stacking.

By default StackPanels display a dotted outline in the Gum tool, but are invisible at runtime. We can add a stack pane to our screen by drag+dropping the StackPanel component into our Screen.

StackPanel in TitleScreen

Label

Label provides a way to display read-only strings to the user. A Label's Text property can be used to change the displayed string.

We can add a label to StackPanelInstance by drag+dropping the Label component in the Project tab.

LabelInstance in a StackPanelInstance

We can change its Text, Color, and Style in the Exposed section in the Variables tab.

Common Label properties in Gum

We can override these properties in code through the generated instance. For example, we can modify our TitleScreen's CustomInitialize method to change the label text.

Full Code

partial class TitleScreen
{
    partial void CustomInitialize()
    {
        LabelInstance.Text = "I am set in code";
    }
}

Diff

partial class TitleScreen
{
    partial void CustomInitialize()
    {
+       LabelInstance.Text = "I am set in code";
    }
}

Label at runtime with its Text property changed

All properties available in the Gum tool are also available in code. To keep the tutorial shorter we will not cover all properties both in Gum and in code unless there are important differences. Feel free to experiment and try setting properties in code as you are reading through the remainder of this tutorial.

Button

By default Gum provides a variety of Buttons. We'll use ButtonStandard, but feel free to experiment with other button components.

Button components in Gum

We can add a ButtonStandard to our stack panel by drag+dropping the ButtonStandard component onto the TitleScreen's StackPanelInstance.

ButtonStandard in StackPanelInstance

Notice that the button automatically stacks below the LabelInstance because the StackPanelInstance stacks top-to-bottom by default.

The most common way to interact with a Button is to assign its Click event. The following code can be used to increment the button's text whenever it is clicked.

Full Code

partial class TitleScreen
{
    int clickCount = 0;
    partial void CustomInitialize()
    {
        LabelInstance.Text = "I am set in code";

        ButtonStandardInstance.Click += (_, _) =>
            ButtonStandardInstance.Text = $"Clicked {++clickCount} Time(s)";
    }
}

Diff

partial class TitleScreen
{
+   int clickCount = 0;
    partial void CustomInitialize()
    {
        LabelInstance.Text = "I am set in code";

+       ButtonStandardInstance.Click += (_, _) =>
+           ButtonStandardInstance.Text = $"Clicked {++clickCount} Time(s)";
    }
}

Button responding to clicks

CheckBox

CheckBox provides a way to display and edit bool values. We can add a CheckBox instance by drag+dropping the CheckBox component onto our StackPanelInstance.

CheckBox in StackPanelInstance

CheckBox provides a number of events for responding to changes:

• Click - whenever the CheckBox is clicked
• Checked - whenever the CheckBox's IsChecked is set to true
• Unchecked - whenever the CheckBox's IsChecked is set to false
• Indeterminate - whenever the CheckBox's IsChecked is set to null

We can display the checked state by handling the Click event as shown in the following code:

First Tab

partial void CustomInitialize()
{
    CheckBoxInstance.Click += (_, _) =>
    {
        CheckBoxInstance.Text = CheckBoxInstance.IsChecked == true
            ? "Checked"
            : CheckBoxInstance.IsChecked == false
                ? "Unchecked"
                : "Indeterminate";
    };
}

Diff

partial void CustomInitialize()
{
+   CheckBoxInstance.Click += (_, _) =>
+   {
+       CheckBoxInstance.Text = CheckBoxInstance.IsChecked == true
+           ? "Checked"
+           : CheckBoxInstance.IsChecked == false
+               ? "Unchecked"
+               : "Indeterminate";
+   };
}

The rest of this tutorial omits the full CustomInitialize function and only shows the newly-added code to keep the displayed code shorter.

CheckBox in StackPanelInstance

ComboBox

ComboBoxes provide a list of options for the user to select. ComboBoxes internally use a ListBox to display their options.

We can add a ComboBox instance by drag+dropping the ComboBox component onto StackPanelInstance.

ComboBox in StackPanelInstance

Now that we've seen how stacking works in our StackPanelInstance, the reminder of this tutorial only displays a single component at a time in the StackPanelInstance as to avoid the UI getting too cluttered. Of course, you should feel free to add and remove component instances to experiment on your own.

Notice that our ComboBoxInstance extends horizontally beyond the bounds of our StackPanelInstance. This can be problematic because the portion which is outside of the StackPanelInstance will not respond to clicks.

We can solve this by extending the horizontal size of our StackPanelInstance to include all of its children.

To do this, select the StackPanelInstance and set the following values:

Variable	Value
Width	0
Width Units	Relative to Children
Min Width	50

We can do the same for Height values:

Variable	Value
Height	0
Height Units	Relative to Children
Min Height	50

Now the StackPanel sizes itself according to its children.

StackPanelInstance adjusted to size itself according to its children

We can populate objects in a ComboBox by adding to its Items property. We can also react to object being selected by using the SelectionChanged event:

Full Code

partial void CustomInitialize()
{
    for(int i = 0; i < 10; i++)
    {
        ComboBoxInstance.Items.Add($"Item {i}");
    }

    ComboBoxInstance.SelectionChanged += (_, _) =>
    {
        var selectedObject = ComboBoxInstance.SelectedObject;
        System.Diagnostics.Debug.WriteLine($"Selected object: {selectedObject}");
    };
}

Diff

partial void CustomInitialize()
{
+   for(int i = 0; i < 10; i++)
+   {
+       ComboBoxInstance.Items.Add($"Item {i}");
+   }

+   ComboBoxInstance.SelectionChanged += (_, _) =>
+   {
+       var selectedObject = ComboBoxInstance.SelectedObject;
+       System.Diagnostics.Debug.WriteLine($"Selected object: {selectedObject}");
+   };
}

ComboBox reacting to SelectionChanged event

ListBox

ListBox provides a way to view and select from a list of items. It is similar to a ComboBox, but it does not collapse when an item is selected.

We can add a ListBox instance by drag+dropping a ListBox onto StackPanelInstance.

ListBox in StackPanelInstance

We can populate objects in a ListBox by adding to its Items property. We can also react to objects being selected by using the SelectionChanged event:

Full Code

partial void CustomInitialize()
{
    for(int i = 0; i < 10; i++)
    {
        ListBoxInstance.Items.Add($"Item {i}");
    }

    ListBoxInstance.SelectionChanged += (_, _) =>
    {
        var selectedObject = ListBoxInstance.SelectedObject;
        System.Diagnostics.Debug.WriteLine($"Selected object: {selectedObject}");
    };
}

Diff

partial void CustomInitialize()
{
+   for(int i = 0; i < 10; i++)
+   {
+       ListBoxInstance.Items.Add($"Item {i}");
+   }

+   ListBoxInstance.SelectionChanged += (_, _) =>
+   {
+       var selectedObject = ListBoxInstance.SelectedObject;
+       System.Diagnostics.Debug.WriteLine($"Selected object: {selectedObject}");
+   };
}

ListBox reacting to SelectionChanged event

Menu and MenuItem

Menu is a control which is usually placed at the top of the screen It contains MenUitem instances which can perform commands when clicked, or which can contain sub-items.

We can add a Menu by drag+dropping the Menu into our TitleScreen. Usually Menu instances are added directly to a screen rather than to a container such as a StackPanelInstance.

Menu in Gum tool

Notice that the Menu is collapsed. We can add MenuItem instances to the Menu by drag+dropping a MenuItem component onto the MenuInstance.

MenuItem in Menu

MenuItems expose a Header variable which can be edited. Additional MenuItem instances can be added to the Menu and they will stack.

Menu with assigned Header value

Sub-items can be added by dragging MenuItems onto existing MenuItem instances.

We can handle the Clicked event to react to clicks on MenuItem instances.

Full Code

partial void CustomInitialize()
{
    MenuItemInstance3.Clicked += (_, _) =>
        System.Diagnostics.Debug.WriteLine("Menu Item Clicked");
}

Diff

partial void CustomInitialize()
{
+    MenuItemInstance3.Clicked += (_, _) =>
+        System.Diagnostics.Debug.WriteLine("Menu Item Clicked");
}

RadioButton

RadioButton provides a way to select from a set of options. Unlike CheckBox, when one RadioButton is selected, other RadioButton instances in the group are deselected.

We can add multiple RadioButton instances by drag+dropping the RadioButton component onto StackPanelInstance multiple times.

RadioButtons in StackPanelInstance

We can modify the Text property of each instance to differentiate between them.

RadioButton instances displaying different text

We can handle the Checked event to respond to a RadioButton being checked.

Full Code

partial void CustomInitialize()
{
    RadioButtonInstance.Checked += (_, _) =>
        System.Diagnostics.Debug.WriteLine("Option 1 Checked");

    RadioButtonInstance1.Checked += (_, _) =>
        System.Diagnostics.Debug.WriteLine("Option 2 Checked");

    RadioButtonInstance2.Checked += (_, _) =>
        System.Diagnostics.Debug.WriteLine("Option 3 Checked");
}

Diff

partial void CustomInitialize()
{
+   RadioButtonInstance.Checked += (_, _) =>
+       System.Diagnostics.Debug.WriteLine("Option 1 Checked");

+   RadioButtonInstance1.Checked += (_, _) =>
+       System.Diagnostics.Debug.WriteLine("Option 2 Checked");

+   RadioButtonInstance2.Checked += (_, _) =>
+       System.Diagnostics.Debug.WriteLine("Option 3 Checked");
}

RadioButtons reacting to Checked event

RadioButtons group according to their common parent. For more information on grouping, see the RadioButton page.

Slider

Sliders provide a way to select a value within a range, as specified by Minimum and Maximum.

We can add a Slider by drag+dropping a Slider component on StackPanelInstance.

Slider in StackPanelInstance

We can set the slider minimum and maximum and react to value changes using the following code:

Full Code

partial void CustomInitialize()
{
    SliderInstance.Minimum = 0;
    SliderInstance.Maximum = 100;
    SliderInstance.ValueChanged += (_, _) =>
        System.Diagnostics.Debug.WriteLine($"Slider Value: {SliderInstance.Value}");
}

Diff

partial void CustomInitialize()
{
+   SliderInstance.Minimum = 0;
+   SliderInstance.Maximum = 100;
+   SliderInstance.ValueChanged += (_, _) =>
+       System.Diagnostics.Debug.WriteLine($"Slider Value: {SliderInstance.Value}");
}

Slider value changed by dragging the thumb or clicking on the track

TextBox

TextBoxes provide a way to view and edit string values.

We can add a TextBox by drag+dropping a TextBox component on StackPanelInstance.

TextBox in StackPanelInstance

We can respond to text being entered in the TextBox as shown in the following code:

Full Code

partial void CustomInitialize()
{
    TextBoxInstance.TextChanged += (_,_) =>
        System.Diagnostics.Debug.WriteLine($"TextBox text: '{TextBoxInstance.Text}'");
}

Diff

partial void CustomInitialize()
{
+   TextBoxInstance.TextChanged += (_,_) =>
+       System.Diagnostics.Debug.WriteLine($"TextBox text: '{TextBoxInstance.Text}'");
}

Handling the TextChanged event

Conclusion

This tutorial covers the basics of working with the most common types of forms components. As mentioned above, feel free to experiment with controls and explore the Controls documentation section for more information about each control.