# 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](/gum/code/controls.md) 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. {% tabs %} {% tab title="Full Code" %} ```csharp partial class TitleScreen { partial void CustomInitialize() { LabelInstance.Text = "I am set in code"; } } ``` {% endtab %} {% tab title="Diff" %} ```diff partial class TitleScreen { partial void CustomInitialize() { + LabelInstance.Text = "I am set in code"; } } ``` {% endtab %} {% endtabs %}

Label at runtime with its Text property changed

{% hint style="info" %} 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. {% endhint %} ## 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. {% tabs %} {% tab title="Full Code" %} ```csharp partial class TitleScreen { int clickCount = 0; partial void CustomInitialize() { LabelInstance.Text = "I am set in code"; ButtonStandardInstance.Click += (_, _) => ButtonStandardInstance.Text = $"Clicked {++clickCount} Time(s)"; } } ``` {% endtab %} {% tab title="Diff" %} ```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)"; } } ``` {% endtab %} {% endtabs %}

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: {% tabs %} {% tab title="First Tab" %} ```csharp partial void CustomInitialize() { CheckBoxInstance.Click += (_, _) => { CheckBoxInstance.Text = CheckBoxInstance.IsChecked == true ? "Checked" : CheckBoxInstance.IsChecked == false ? "Unchecked" : "Indeterminate"; }; } ``` {% endtab %} {% tab title="Diff" %} ```diff partial void CustomInitialize() { + CheckBoxInstance.Click += (_, _) => + { + CheckBoxInstance.Text = CheckBoxInstance.IsChecked == true + ? "Checked" + : CheckBoxInstance.IsChecked == false + ? "Unchecked" + : "Indeterminate"; + }; } ``` {% endtab %} {% endtabs %} {% hint style="info" %} The rest of this tutorial omits the full CustomInitialize function and only shows the newly-added code to keep the displayed code shorter. {% endhint %}

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

{% hint style="info" %} 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. {% endhint %} 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:
VariableValue
Width0
Width UnitsRelative to Children
Min Width50
We can do the same for Height values:
VariableValue
Height0
Height UnitsRelative to Children
Min Height50
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: {% tabs %} {% tab title="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}");
    };
}
{% endtab %} {% tab title="Diff" %} ```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}"); + }; } ``` {% endtab %} {% endtabs %}

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: {% tabs %} {% tab title="Full Code" %} ```csharp 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}"); }; } ``` {% endtab %} {% tab title="Diff" %} ```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}"); + }; } ``` {% endtab %} {% endtabs %}

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. {% tabs %} {% tab title="Full Code" %} ```csharp partial void CustomInitialize() { MenuItemInstance3.Clicked += (_, _) => System.Diagnostics.Debug.WriteLine("Menu Item Clicked"); } ``` {% endtab %} {% tab title="Diff" %} ```diff partial void CustomInitialize() { + MenuItemInstance3.Clicked += (_, _) => + System.Diagnostics.Debug.WriteLine("Menu Item Clicked"); } ``` {% endtab %} {% endtabs %}
## 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. {% tabs %} {% tab title="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");
}
{% endtab %} {% tab title="Diff" %} ```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"); } ``` {% endtab %} {% endtabs %}

RadioButtons reacting to Checked event

{% hint style="info" %} RadioButtons group according to their common parent. For more information on grouping, see the [RadioButton page](/gum/code/controls/radiobutton.md). {% endhint %} ## 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: {% tabs %} {% tab title="Full Code" %} ```csharp partial void CustomInitialize() { SliderInstance.Minimum = 0; SliderInstance.Maximum = 100; SliderInstance.ValueChanged += (_, _) => System.Diagnostics.Debug.WriteLine($"Slider Value: {SliderInstance.Value}"); } ``` {% endtab %} {% tab title="Diff" %} ```diff partial void CustomInitialize() { + SliderInstance.Minimum = 0; + SliderInstance.Maximum = 100; + SliderInstance.ValueChanged += (_, _) => + System.Diagnostics.Debug.WriteLine($"Slider Value: {SliderInstance.Value}"); } ``` {% endtab %} {% endtabs %}

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: {% tabs %} {% tab title="Full Code" %} ```csharp partial void CustomInitialize() { TextBoxInstance.TextChanged += (_,_) => System.Diagnostics.Debug.WriteLine($"TextBox text: '{TextBoxInstance.Text}'"); } ``` {% endtab %} {% tab title="Diff" %} ```diff partial void CustomInitialize() { + TextBoxInstance.TextChanged += (_,_) => + System.Diagnostics.Debug.WriteLine($"TextBox text: '{TextBoxInstance.Text}'"); } ``` {% endtab %} {% endtabs %}

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](/gum/code/controls.md) for more information about each control. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.flatredball.com/gum/code/getting-started/tutorials/gum-project-forms-tutorial/common-component-types.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.