Introduction

The tutorials contained within this section provide an introduction to working with the Gum UI tool. This tutorial is a great place to start whether you are an artist who will be creating screens and components in Gum, or if you are a programmer who will be integrating Gum into your game or application.

If you are using Gum in a game project, you may want to continue reading other sections after you finish these tutorials.

Animation keyframes are defined by creating states in categories. If an animation uses two states in the same category then the animation will tween between the

Introduction

States are a powerful way to create expressive groups of variables. Some UI elements may require a combination of states to be applied simultaneously.

For example, consider creating a CheckBox element. This CheckBox may have one set of states for whether it is checked:

• Checked

• Unchecked

But it may also need a second set of states for being enabled and disabled (which may modify the color of the Text and graphics for the check box:

• Enabled

• Disabled

In this case multiple states need to coexist and may be combined. Categories allow you to organize states so that multiple states can be set simultaneously.

Creating categorized states

For this tutorial we'll create a new component. This component will have state categories for size and for color. To do this:

1. Open Gum

2. Create a new Component called "CategoryDemo"

3. Right-click anywhere in the State box and select "Add Category"

4. Enter the name "Size" for the new category and click OK

5. Repeat the above steps to create a "Color" category

Now we can add states to the categories. To do this:

1. Right-click on the "Size" category and select "Add State"

2. Enter the name "Small" for the new state

3. Right-click on the "Size" category again and select "Add State"

4. Add a second state to "Big"

5. Right-click on the "Color" category and select "Add State

6. Add a state called "Red"

7. Right-click on the "Color" category again and select "Add State

8. Add a state called "Blue"

Adding visuals

Now that we have states set up we need to add a visual element to the component so that we can see our changes.

To do this, drag+drop a ColoredRectangle into your component

Setting variables in states

To modify a state, you can select it and edit in the preview window or change properties in the Variables tab to modify what the state sets. Notice that normally for a component like this the ColoredRectangleInstance would have its width and height be relative to its container, but we're not doing this for the sake of keeping the tutorial shorter.

First we'll set the Size states. To do this:

1. Select the "Big" state

2. Resize the colored rectangle so it is larger than the default

3. Select the "Small" state

4. Resize the colored rectangle so it is smaller than the default

Next we'll set the Color states. To do this:

1. Select the "Red" state

2. Set the Red, Green, Blue values to: 255, 0, 0

3. Select the "Blue" state

4. Set the Red, Green, Blue values to: 0, 0, 255

Viewing multiple states on an instance

Now that we have our CategoryDemo component set up with multiple categories, we can view these states on any CategoryDemo instance. To do this:

1. Create a Screen called CategoryDemoScreen

2. Drop an instance of the CategoryDemo component into the CategoryDemoScreen

3. Select the newly-created CategoryDemoInstance

4. Scroll down in the Variables list and notice that the instance has drop-downs for each category.

5. You can set each state independently and the states will combine

Categories and Variables

If a variable is modified in one of the states in a category, then all of the states in that category are automatically assigned the default value, and this value is explicitly set. This concept makes working with states far more predictable.

For example, we can consider a component which has:

• A single ColoredRectangle

• A category called RectangleSizeCategory

• States called Big, Medium, and Small

Initially, all states in a category do not explicitly assign any variables. We can see this by selecting the category and observing the Variables tab.

If a variable is changed in one of the states in the category, then that variable propagates to all other states, and the Category lists this as one of the variables that it modifies.

For example, we can select the Big category and change the ColoredRectangle.Width property to 150.

Once this value is changed, the RectangleSizeCategory lists this as a variable that it modifies in the Variables tab.

If we select any of the other states in the category, they show that they explicitly set the Width value as well (the value has a white background instead of light green). The value is inherited from the default state.

Once a variable is set in a category, all states are required to set this value. A variable cannot be removed from a single state in a category. Rather, to remove a variable, all states in the category must remove the variable. This can be done by selecting the category and pressing the X button next to the variable name.

Introduction

Gum supports creating and previewing animations in the editor through the use of states. The general workflow for creating an animation is as follows:

1. Create states representing the keyframes in the animation (usually one category per animation)

2. Add an animation to the component or screen

3. Add states to the animation and adjust their time

4. Set interpolation values for each keyframe to control "easing"

Examples of animations

Gum's animation system is very powerful and can be used in a variety of situations:

• Animations which play when a screen or component is shown or hidden

• Animations used to transition between behavior states such as changing a button from regular to highlighted state

• Lengthy animations which can last multiple seconds for complex transitions

Storage of animations

Animations are stored separate from the screen or component on the file system. If a screen or component contains at least one animation then Gum will save a Gum Animation XML file (.ganx extension) with the word "Animations" appended on the screen or component's name. In other words GameScreen would have a file called GameScreenAnimations.ganx in the same folder containing information about its animations.

Playing animations

Once an animation has been made it can be played back in editor. The following shows how an animation is played back, both in real time and also by dragging the slider.

Introduction

The component tutorial shows how objects can be sized and positioned according to the container that they are a part of. Although this is the default behavior, the parent of an instance can be explicitly set to another instance.

This functionality is useful for

• Stacking objects on top of each other or side by side

• Placing objects next to other objects which are dynamically sized

• Creating tables and other complicated layout objects

Creating a Component

For this example we'll create a Text object which includes a value and a unit of measurement. Specifically we'll create two text objects - one will display a numerical value, the other will say "feet". We will use two text objects so that we can independently color them.

To do this:

1. Create a new component called MeasurementDisplay

2. Drop two Text objects in the newly-created component

3. Name the first "ValueText"

4. Name the second "UnitsDisplay"

Positioning according to a parent

Next we'll make the UnitsDisplay use the ValueText as its parent:

1. Select the UnitsDisplay Text object

2. Change its Parent to ValueText

3. Change its X Units to "PixelsFromRight". This will make the text object be positioned according to its parent's right edge

4. Change its X to 10 - this means the UnitsDisplay text will be 10 units offset from the right edge of its parent ValueText

5. Change its Y to 0

Next we'll want the parent text (ValueText) to automatically size according to its contents. To do this, set its Width to 0. Setting Width to 0 on a text instance means that the text's width will be equal to the size needed to display the text.

Adjusting Colors

Now that we have the texts set up, let's modify the color of the UnitsDisplay:

1. Select the UnitsDisplay

2. Change Red to 200

3. Change Green to 150

4. Change Blue to 0

Changing ValueText

Now the Text variable in ValueText can be changed, and when doing so the UnitsDisplay will automatically change positions:

Gum is the best Game UI Layout tool available. It provides a flexible, efficient layout engine capable of producing virtually any layout. Gum can be used in a variety of contexts including in the FlatRedBall game engine, MonoGame, and Meadow. The Gum layout engine can also be included in any .NET project without requiring the use of a particular graphical API.

Powerful WYSIWYG Editor

Gum UI includes advanced layout functionality to create and preview your UI

Object Oriented Design Focused on Reusable Controls

Gum allows the creation of components which can be instanced and customized in screens and other components

Gum Objects Support Multiple Size and Position Units

Adjust an object’s origin, position units, size units, and stacking to create fluid UI

Simple Integration with any FlatRedBall or MonoGame Project

Grab the NuGet, add a few lines of code, see your Gum project in game!

Interact with Gum in Code

Gum objects can be created and modified in code. Create fully-featured UI by subscribing to common UI events.

Need Help?

Gum is actively maintained and provides lots of ways to get answers:

• Check the rest of the documentation here

• Join the Discord chat (shared discord with FlatRedBall)

• Create an issue on Github

Gum Application (binaries): files.flatredball.com/content/Tools/Gum/Gum.zip

Gum Source Code: https://www.github.com/vchelaru/Gum

Windows

Currently the Gum tool requires XNA runtimes. Download and install the runtime prior to running Gum:

Since Gum is a prebuilt file in a .zip, Windows blocks the file which results in the "Windows protected your PC" popup:

You can click More info, then Run anyway. Alternatively, you can right-click on the .zip file and select the option to unblock:

Mac

Prerequisites

Before proceeding, ensure that you have the following prerequisites installed on your macOS:

1. Homebrew

2. WINE

3. Winetricks

Install Homebrew

Homebrew is a package manager for macOS. If you haven't installed Homebrew yet, you can install it by following the instructions on the official Homebrew website.

Install WINE and Winetricks

You can install WINE and Winetricks using Homebrew. Open a terminal and run the following commands:

brew install --cask --no-quarantine wine-stable
brew install winetricks

Automated Setup

The following goes through the steps do download and run the setup_gum_mac.sh automation script. This script goes through the steps for you with minimal interaction to setup your environment on macOS to run the GUM tool using WINE. If you would prefer to do this setup manually, please see the Manual Setup Steps section below.

1. Download the setup_gum.mac.sh script https://raw.githubusercontent.com/vchelaru/Gum/master/setup_gum_mac.sh

2. Open a terminal and cd to the directory that the script was downloaded to

3. Make the script executable

chmod +x ./setup_gum_mac.sh

1. Execute the script

./setup_gum.mac.sh

Manual Setup Steps

The following goes through the steps setup your environment on macOS to run the GUM tool using WINE.

1. Open a new terminal

2. Install .NET Framework 4.8 using winetricks with the following command:

winetricks dotnet48

This command initiates the installation of .NET Framework 4.8. A total of two installer dialogs appear one after another. Follow the steps for both to complete the installation. This process may take a several minutes, so please be patient.

1. Download the XNA 4.0 Redistributable MSI file from Microsoft. You can download it using the following command:

curl -O https://download.microsoft.com/download/A/C/2/AC2C903B-E6E8-42C2-9FD7-BEBAC362A930/xnafx40_redist.msi

1. After downloading the MSI file, install it using the following command:

wine msiexec /i xnafx40_redist.msi

Follow the installation prompts. At the end of the installation, it may display an error related to launching DirectX. This is normal; just click "Close" on the error dialog.

1. Download the Gum Tool ZIP file from the FlatRedBall website and save it to your preferred location. You can download it using the following command:

curl -o Gum.zip https://files.flatredball.com/content/Tools/Gum/Gum.zip

1. Unzip the downloaded Gum Tool ZIP file into the Program Files directory of the WINE folder. Run the following command in the terminal:

unzip Gum.zip -d ~/.wine/drive_c/Program\ Files/Gum

1. After unzipping the Gum Tool, remove the downloaded ZIP file using the following command:

rm -f Gum.zip

1. Create a script to run the Gum Tool. Run the following command in the terminal:

echo '#!/bin/bash
wine ~/.wine/drive_c/Program\\ Files/Gum/Data/Gum.exe' > ~/bin/Gum

1. Make the script executable by running:

chmod +x ~/bin/Gum

1. To ensure you can run the Gum Tool from any directory, add the script directory to your PATH.

For Bash SHELL

if ! grep -q 'export PATH="\$HOME/bin:\$PATH"' ~/.bash_profile 2>/dev/null; then
    echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bash_profile
fi

For ZSH Shell

if ! grep -q 'export PATH="\$HOME/bin:\$PATH"' ~/.zshrc 2>/dev/null; then
    echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
fi

1. Reload the shell configuration to apply the changes. Run the following command:

For BASH Shell

source ~/.bash_profile

For ZSH Shell

source ~/.zshrc

Running the Gum Tool

Congratulations! You have now successfully set up the Gum Tool on macOS using WINE. You can open the Gum Tool by simply typing the following command in the terminal:

Gum

If the command doesn't work immediately, try closing and reopening the terminal.

Introduction

This page walks you through the basics of using the Gum UI tool, which we'll refer to simply as Gum for this and all other documentation.

Gum Elements

Gum separates its elements into three categories: Screens, Components, and Standard. Behaviors are an advanced topic that we'll skip for these tutorials.

Standard elements represent the building-blocks for screens and components, and all projects use the same set of standard elements. To see the list of elements, expand the Standard tree item. Clicking on any element displays it in the preview window.

Sprite element is selected in the image above. Notice that since a SourceFile is not set, the Sprite renders as a red X.

Standard Types

Components

Components are objects which can contain standard elements and instances of other components. Components can be very simple, such as a Label, or very complex, such as an options menu with dozens of instances. Items added to components or screens are called instances.

Screens

Screens are objects which can contain standard elements and instances of other components. Unlike Components, Screens cannot be added to other Screens. Screens exist mainly for organization. Screens can be simple, such as a loading screen, or complex such as a HUD in an RTS game.

Components vs. Screens

Components and screens are similar - both can contain instances of standard elements, and both can contain other components. The only difference between screens and components is that screens cannot contain other screens.

You can think of screens like a screen in a video game. Examples include a main menu, credits screen, options screen, and level selection screen. You can think of components as elements which are composed of multiple standard elements. Examples include a Button component which is made up of a Sprite instance and a Text instance, or a Logo component which may be made up of multiple Sprites and Text objects.

Creating a Screen

To create a screen:

1. Right-click on the Screens tree item and select Add Screen
2. Enter the name of the new screen - such as MainMenu

3. The newly-created screen is created and selected

Adding instances

Instances of standard and component elements can be added to screens and components. To add an instance:

1. Select the destination screen or component. For example, select the MainMenu screen

2. Push the left mouse button (but don't release it) on the Text item. If you happen to release the mouse button, this selects the Text item, so you need to re-select the destination (MainMenu).

3. Drag the Text item onto the Editor tab

4. Release the mouse button. A new text instance appears in your screen.

Alternatively, you can also drag+drop a standard element into a screen in the tree view.

Editing in the preview window

Once an instance is a part of a screen or component it can be edited visually in the preview window. The selected instance has eight (8) handles surrounding it. These are called the resize handles and can be used to change the selected instance's width and height.

In the case of the Text object, the resize handles are used to control how the text object performs line wrapping.

You can use the resize handles to resize the instance, or you can simply push the mouse button and drag inside the instance to change its position. Notice that an object's outline is displayed when the cursor is hovering over the instance.

Conclusion

This tutorial introduces the basics of working with standard elements and adding them to Screens. The next tutorial covers the Variables tab which can be used to access all element variables.

Introduction

Gum supports loading image files for Sprites and NineSlices. We'll discuss how to load files, and how they are referenced in Gum.

Setting up a workspace

First we'll set up a workspace. To do this 1. Create a Screen. I'll call my Screen "SpriteScreen" 1. Drag+drop a Sprite into the newly-created Screen

1. Setting the Sprite SourceFile

   The "SourceFile" property controls the image that the Sprite displays. Common examples of source file types are .png and .tga. To add a source file

2. Select a Sprite

3. Click on the "SourceFile" box

4. Click the "..." button to bring up a file window

5. Navigate to the location of the file you would like to load

6. Click "Open" in the file window

7. Once the source file is set the image will appear in Gum

Source file locations

Files referenced by Gum projects will be relative to the root gum project itself. Therefore, you may notice that the source file begins with a "../", indicating that the relative location of the file is not a subfolder of the Gum project. For portability you may want to keep all source files in a folder located under your gum project (which has the extension .gumx).

Introduction

States allow you to set multiple variables at one time. Examples of states might include:

• A button with Regular, Highlighted, Pressed, and Disabled states

• A game logo in Large and Small modes

• A game hud which can appear on and off screen

Prerequisites

This tutorial builds upon the previous tutorial where a Button component was created. To follow along you will need to have a Button component created as defined in the earlier tutorials.

Defining states

First we'll define two new states. All components and screens have a Default state automatically. This Default state is uncategorized, but all other states must be in a category. Therefore, we'll first add a new category:

1. Right-click in the States tab

2. Select Add Category
3. Enter the name ButtonStateCategory

To add a new state:

1. Right-click on ButtonStateCategory

2. Select Add State
3. Enter the name "Highlighted"

4. Click OK

The Button component now has a new state called Highlighted:

Setting variables in states

Once a state is defined and selected, setting a variable associates that variable the selected state. In other words, any variable that is set when the Highlighted state is selected results in that variable being added to that state.

For this example, we can make the button become a lighter blue when highlighted. To do this:

1. Verify the Highlighted state is selected

2. Select the ColoredRectangleInstance

3. Set the Green and Red values to 100

Notice that the Green and Red values are rendered with a white background rather than green - indicating that they are explicitly set in the Highlight state.

Switching between states

The values that have just been set apply only to the state that was selected - the Highlight state. This means that clicking on the Default state switches the button back to the default colors. By clicking on the states in Gum you can preview and edit states easily.

Category Variables

Whenever a state in a category sets a variable, that variable is set across all states in that category. So far this tutorial only created a single state called Highlighted, but if additional states are set, all will explicitly set the Red and Green state. This topic is covered in more detail in the next tutorial.

Introduction

The ability to expose variables in Gum makes components very powerful and flexible. For this example we will continue the Button example from the last tutorial.

Recap

The last tutorial set up a Button component with Text and ColoredRectangle instances. The two were set up to be positioned correctly according to the size of the button.

We then created a MainMenu screen and added a few instances of the Button component to the MainMenu screen.

While the size and positioning functionality in our button works well, the Text itself always says "Hello".

Exposing the Text variable

By default each instance of our Button cannot access values that are contained inside the ColoredRectangleInstance or TextInstance. However, we can "expose" these variables so that they can be modified in our MainMenu screen.

To do this:

1. Select TextInstance under Button

2. Find the "Text" variable in the Variables tab (Second column, under the "States" panel)

3. Right-click on the text box and select "Expose Variable"

4. Enter the name "Text" for the variable name

You can verify that the Text value is exposed by clicking the "Button" component and seeing the "Text" variable under the "Exposed" category:

Setting instance variables

Now that the Text variable is an exposed variable, it can be set per-instance. To do this:

1. Select one of the Buttons in MainMenu

2. Change its Text to "Button 1"

Feel free to set different Text values on all of the buttons. Notice that the Text may word-wrap.

Introduction

Components can contain instances of other components and of standard objects. Examples of components include:

• Check boxes

• Buttons

• Popup Menus

Components can also be simple (such as a button) or more complex UI elements such as a full Options screen with dozens of instances.

Simple Button Example - Creating the Entity

To understand how components work, we'll create a simple Button component. To do this:

1. Right-click on the Components folder in Gum and select "Add Component"

2. Name the Component "Button"

3. Drag+drop a "ColoredRectangle" standard element into the Button component

4. Drag+drop a "Text" standard element into the Button component

Since both the ColoredRectangleInstance and TextInstance are using white text you may not be able to see the Text. Let's change the ColoredRectangleInstance's color:

1. Select the ColoredRectangleInstance

2. Change Red to 0

3. Change Green to 0

4. Set Blue to 255 - this should change the background from being green (default) to white (custom value). To do this, simply delete and re-type 255 in the Blue box, or click in the box and press enter.

Now you should be able to see the Text on top of the rectangle:

Sizing the colored rectangle

At this point we have what will eventually become a button, but it still needs some work. First, we're going to adjust the size of the objects contained in the button. At this point you can see that the colored rectangle (the blue background for the button) is not the same size as the button. Not only do we want to make the blue colored rectangle larger, but we also want it to automatically match the Button's size (the dotted outline).

To do this:

1. Select the ColoredRectangleInstance

2. Select the Alignment tab

3. Click the Fill Dock button

Alternatively you can adjust the individual values:

1. Select the ColoredRectangleInstance

2. Change Height Units to "Relative to Container"

3. Change the Width Units to "Relative to Container"

4. Change the Height to 0. This means that the Height of the ColoredRectangleInstance will match the Height of its container (the Button Component) since it's using "Relative to Container" Height Units.

5. Change the Width to 0. Just like with Height, this means that the Width of the ColoredRectangleInstance will match the Width of its container.

Now the ColoredRectangleInstance automatically matches the Button's Width and Height:

Positioning the Text

Next we'll position the Text. We'll want to adjust the Text so that it is always centered, and line-wraps with the size of the button.

To do this:

1. Select TextInstance

2. Click the Alignment tab

3. Set the Margin to 20

4. Click the Fill Dock button

Alternatively you can set each individual value on the Text by following these steps:

1. Select TextInstance

2. Change its HorizontalAlignment to Center

3. Change its VerticalAlignment to Center

At this point the Text is vertically and horizontally centered within its boundaries, but we want to have the boundaries centered within the Button. To do this:

1. Keep TextInstance selected

2. Change the X Units to "Pixels From Center"

3. Change the X Origin to "Center"

4. Change X to 0

Now let's make it centered on the Y as well:

1. Keep the TextInstance selected

2. Change the Y Units to "Pixels From Center"

3. Change the Y Origin to "Center"

4. Change Y to 0

Finally, let's make the width of the text match the width of the button. For the Text we'll actually leave a border around the edge so the Text doesn't line wrap right against the edge of the button. To do this:

1. Keep the TextInstance selected

2. Change the Width Units to "Relative to Container"

3. Change Width to -40. This means that the width of the Text will be 40 pixels less than the width of its container. Since the button is centered this means a 20 pixel border on the left and 20 on the right (20+20=40).

Setting the Button default values

Buttons are typically wider than they are tall. To match this common layout, let's set the default values on the Button:

1. Select the Button component

2. Change Width to 120

3. Change Height to 36

Notice that whenever you change these values, the contained objects (text and colored rectangle) adjust automatically.

Using components as instances

Now that we have a component created, we can add instances of this component the same way we have added standard elements. To do this:

1. Create a new Screen. I'll call mine MainMenu

2. Drag+drop the Button component into the Screen

You can now resize and position the Button instance. You can also add multiple buttons and adjust the individually.

See the section (Exposing Variables) to learn how to change the text independently for each button!

Introduction

The Variables tab in Gum displays all available variables when editing an instance or element. While the visual editor is handy for quick edits such as positioning and resizing instances, the Variables tab exposes all variables. It is also useful for making fine changes to instances, such as by moving an instance by a single pixel.

The Variables tab shows variables for the selected instance or element.

Editing Variables

Variables can be edited simply by changing values on the selected variable. For example, to move the text to the right, change its X value to a positive number:

Positioning Instances

Gum provides a flexible positioning system. The position of an element is a result of a number of variables. We'll go over a few here.

By default all instances are positioned by their top-left corner. For example, setting the Text instance's X and Y to 0 aligned its top-left position to the top-left of the screen (which is identified by a dotted line.

We can change the origin of the Text object by setting its "X Origin" and "Y Origin" values. Notice that if X Origin is set to "Center" then the Text object is positioned by its center:

Notice that I had to pan the view to be able to see the Text object. Gum provides multiple ways to pan the view:

• Press and hold the middle mouse button while the cursor is over the preview window. While the middle mouse button is down, move the mouse cursor.

• Use the scroll bars on the bottom and side of the view

• Hold down CTRL and press the arrow keys

Changing the X Origin value changes the origin of the selected instance; however, it is still positioned relative to the top-left corner of the Text instance's container - which in this case is the entire screen designated by the dotted outline rectangle.

We can change the origin that the Text is relative to by changing the X Units. By default the X Units variable is set to Pixels from Left for X and Pixels from Top for Y.

Changing the X Units to Pixels from Right will cause the Text to be positioned on the right-side of the screen.

Text Alignment

The X,Y values, Origin values, and Units values are all available for every type of element in Gum; however, these values only change the bounds. In the case of a Text object we may be interested in how the text is aligned within the bounds. The Text object offers two variables for aligning its text: Horizontal Alignment and Vertical Alignment. Changing the Horizontal Alignment to Center centers the Text within its bounds:

Default and overriding values

You may have noticed that some variables in the Variables tab have a green background while others have a white background. For example, in the image above the TextInstance's Vertical Alignment is green. The reason for this is because instances are not required to define values for every variable. Whenever an instance does not set a variable value, it uses the value that is defined in the Standard Element definition.

To see how this works, select the Text item under the Standard folder. Notice that all values have a white background. Notice the default values for Horizontal Alignment and Vertical Alignment:

If the default Horizontal Alignment and Vertical Alignment values are changed, the changes will immediately be reflected in the preview window for the default Text configuration:

Now if we select the TextIntance we will see that the VerticalAlignment is visibly using the Bottom value; however the Horizontal Alignment is still using center - this is because a value that is explicitly set on an instance will always override the default value set in the Standard element. Notice that Horizontal Alignment has a white background (indicating a custom value) and Vertical Alignment has a green background (indicating a default value).

Values can be reverted back to their default simply by right-clicking on the variable name in the Variables tab and selecting Make Default

Introduction

Gum supports creating animations which can play other animations. This is especially useful when creating animations in Screens that contain components which themselves have animations. This tutorial will build upon the previous tutorial where we created an animated component called TextComponent.

Creating a Screen

First we'll create a Screen called AnimatedScreen. To do this:

1. Right-click on Screens

2. Select "Add Screen"

3. Enter the name "AnimatedScreen" and click the OK button

4. Drag+drop a few TextComponents into the Screen and spread them out visually

Defining the initial state

The animation we will be creating in our Screen will start with all TextComponents being invisible, then each one appearing by playing their Show animation. The animations will be slightly staggered. First we'll add the initial state where all of the TextComponents are invisible. To do this:

1. Verify that the AnimatedScreen is selected

2. Right-click in the states area and select "Add State"

3. Name the state "AllInvisible" and click OK

4. Select one of the TextComponents

5. Set its State to Hidden

6. Repeat setting the State to Hidden for the other TextComponents

Creating the Animation

Now we have all of the states and animations that we'll use as keyframes in our animation. To create the animation:

1. Select AnimatedScreen

2. Select "State Animation" -> "View Animations"

3. Click "Add Animation"

4. Name the animation "ShowAll"

5. Select the ShowAll animation

6. Click "Add State"

7. Select "AllInvisible" and click OK

The animation now sets all TextComponents to their Hidden state initially.

Adding Sub-Animations

Next we'll be adding animations to animate the TextComponent instances to visible. To do this:

1. Bring up the animation window for AnimatedScren if it is not already showing

2. Select "ShowAll"

3. Click "Add Sub-animation"

4. Select the first TextComponentInstance

5. Select the Show animation and click OK

6. Select the newly-created animation and set its Time to 0.5

7. Repeat the above steps to add animations for the other two TextComponents, but set their times to 1.0 and 1.5

Now the animation can be played or previewed with the slider bar:

Introduction

Gum provides simple controls for centering objects inside of their parents. This page shows how to center objects in a variety of situations. For brevity this document uses vertical centering, but the same concepts apply to horizontal centering.

Centering with Anchors (Alignment Tab)

The easiest way to center an object is to use the center Anchor. This sets all of the values necessary to center an object both vertically and horizontally.

Centering Using Units

Objects can be centered by setting their unit and numerical values. The Alignment tab is a shortcut for these values. For example, to set an object so that it is centered vertically, the following values can be set:

• Y = 0

• Y Units = Pixels from Center

• YOrigin = Center

Centering with Margins

Centering can be performed with margins by adding an additional container which will create the necessary margins. For example, consider a situation where we want to center the green rectangle inside the blue rectangle, but leave a 32 pixel margin at the top.

We may want something similar to the following image:

To do this, an additional container can be added as shown in the following image:

In this case, the container has the following relevant properties:

• Y = 0 (so it is pressed against the bottom)

• Y Units = Pixels From Bottom (so it is bottom justified

• Height = -32 (leaving a 32 pixel margin)

• Height Units = Relative to Container (so that it always has a 32 pixel margin regardless of parent size)

The green rectangle can be added as a child to the container, and then centered within the container. This results in the green rectangle always being centered within the area that leaves a 32 pixel margin at the top even if the main rectangle is resized, as shown in the following animation:

Additonal margin can also be added to the bottom by changing the container's Y value. For example, a 20 margin border can be added at the bottom, leaving a 32 pixel margin at the top by setting the following values on the container:

• Y = -20 (move the bottom of the container up by 20 pixels)

• Height = -52 (leaving a 32 pixel margin at the top, and accounting for the container being moved up an extra 20 pixels)

Introduction

This article shows how to create an animated component. It will contain an animation which can be used when the component first appears.

Creating the Component

First we'll create a component which will be animated. To do this:

1. Right-click on Components

2. Select Add Component

3. Enter the name TextComponent and click OK

4. Drag+drop the Text Standard into the TextComponent to create a Text instance

5. Select the Alignment tab and click the middle button to have the TextInstance fill the TextComponent

Creating the States

Now that we have a component we'll add the states needed for animation. We'll add all states in a category called HideShow. Animation states should always be categorized. To create the states:

1. Right click in the States list box

2. Select Add Category

3. Enter the name HideShow

4. Right-click on the HideShow folder

5. Select Add State

6. Enter the name Hidden and click OK

7. Right-click on the HideShow folder

8. Select Add State

9. Select Shown

Setting values in the states

Now that we have the states defined we can set values for the states. In this case the only thing we'll be modifying is the TextInstance's Font Scale value. To do this:

1. Select TextInstance

2. Select the Hidden state

3. Set the Font Scale to 0. This makes the Text so small that it's invisible

4. Select the Shown state

5. Verify the Font Scale is 1, or set it to 1 if not. This makes the Text regular size

Creating the Show animation

The two states we created above will be used as the keyframes for our animation. The animation will begin in the Hidden state then interpolate to the Shown state. To add this animation:

1. Verify that TextComponent or any objects under it are selected

2. Select State Animation ->View Animations

3. Click the Add Animation button

4. Name the animation Show and click OK

5. Select the Show animation and click Add State

6. Select the Hidden state and click OK - this is the first keyframe in our animation

7. Click Add State again

8. Select Shown and click OK

The animation can now be played or previewed:

Adjusting Interpolation Type

The Interpolation Type value sets how one keyframe blends to another. By default keyframes use Linear interpolation, which is a constant change from one state to another. When interpolating from one keyframe to another, the first keframe defines the interpolation type. In our case the Hidden frame defines the interpolation type. We can change the Interpolation Type and preview the animation:

1. Select the Hidden keyframe

2. Change Interpolation Type to Elastic

Playing the animation will reflect these changes.

Introduction

Although Gum naturally provides a NineSlice object, the Gum layout system can be used to create a custom NineSlice component. Such a component could be used if additional flexibility beyond what is provided by the standard NineSlice is needed.

Creating the Component

As implied by the name, the NineSlice object is composed of nine Sprites. First we'll create the component:

1. Open Gum

2. Open or create a new Gum project

3. Right-click on the Components folder

4. Select Add Component

5. Name the Component CustomNineSlice

Adding Corner Sprites

Next, we'll add corner Sprite instances to our CustomNineSlice. We'll be using the alignment tab to position Sprites. The alignment tab provides a quick way to place objects, but the same can be achieved using the following variables individually:

• Drag+drop a Sprite element onto the CustomNineSlice component

• Click the Alignment tab

• Repeat the steps above three more times, creating one Sprite for each of the four corners

Notice that if we resize our CustomNineSlice component, each of the four sprites remains in the corner.

Adding Edge Sprites

Next we'll add the four sprites which will sit on the edge of our component:

1. Drag+drop a Sprite element onto the CustomNineSlice component

2. Click on the alignment tab

3. Dock the newly-created Sprite to the top of its container. Docking sets the width of the sprite to match the width of the component. We'll address this in the next step.

4. To accommodate for the corner Sprites, we need to adjust the width of the top Sprite. Set the newly-created Sprite's Width to -128. Since the Sprite uses a Width Units of RelativeToContainer, Setting the value to -128 will make the sprite be 128 units smaller than the container. We picked 128 because each of the corner sprites is 64.

5. Repeat the above steps, but instead setting the dock to create sprites on the left, right, and bottom. adjust width and height values as necessary.

Adding the Center Sprite

The last Sprite we'll add is the center Sprite:

1. Drag+drop a Sprite element onto the CustomNineSlice component

2. Click on the alignment tab

3. Dock the newly-created Sprite to the center of its container.

4. Set both the newly created Sprite's Width and Height to -128

Assigning values on CustomNineSlice

Unlike the regular NineSlice, changing the texture values requires a considerable amount of variable modification. To change the CustomNineSlice to use 9 separate textures, the following values must be set:

• Each of the Sprite instances must have its SourceFile value set

• The edge Sprites will have to have their Width and Height values modified to account for the possible resizing of the corner sprites

• The center Sprite will have to have both its Width and Height values modified

If using a sprite sheet, then all of the work above will need to be done plus the texture coordinate values will need to be modified.

Bottom-up stacks can be used to display stacks of elements which should move up as more are added. This concept is similar to messages received in a chat window. Gum layout can be used to produce this type of stack.

A bottom-up stack will be a container, which could be an instance of a container or a component since components ultimately are containers. For this example we'll use a container.

For this container to stack we'll set the following variables:

• Children Layout set to Top to Bottom Stack so all children stack vertically
• Height Units set to Relative to Children so the container resizes itself as more children are added
• Height set to 0 so the height of the container is based purely on its children
• Stack Spacing set to 2 (optional) to add spacing between each child

Now the container can have children added. Any type of child will stack. For this tutorial we'll use ColoredRectangle instances. Add a few instances to the Container and they stack vertically.

Finally we can have the stack grow up instead of down. To do this, change the following variables on the parent container:

• Y Origin set to Bottom
• Y Units set to Pixels from Bottom

Now as new children are added, the parent stack grows and all items shift up.

• Button

• HealthBar

• Slider

• Menu

Components can be small and reusable, such as a Label, or they can be large complex objects such as a settings menu with dozens of options.

Component instances can be added to other Components or to Screens.

Introduction

When a parent uses RelativeToChildren for its for its Width Units or Height Units, it must only consider children which are not positioned relative to the parents' Width or Height, respectively.

For the sake of brevity, this document will discuss Width, Width Units, X, and X Units values. All concepts also apply to Height, Height Units, Y, and Y Units.

Gum Prevents Recursive

Conceptually, parent Width Units and children X Units can create recursive relationships. For example, consider the following situation:

• Parent.WidthUnits = RelativeToChildren

• Child.XUnits = Percentage

• Child.Width = 100

• Child.X = 50

In this case the Parent width depends on the Child X and Width values. But the Child X depends on the Parent Width. This creates a recursive relationship which cannot be resolved (or which can be resolved with unexpected results).

Therefore, when determining the Width of a parent using RelativeToChildren WidthUnits, all children which have position or size values relative to their parent are ignored.

Specifically, the following values are considered absolute, and any values besides these will result in a child being ignored when calculating a relative parent Width:

• WidthUnits = Absolute, PercentageOfSourceFile, RelativeToChildren

• XUnits = PixelsFromLeft, PixelsFromMiddle, PixelsFromRight

Only the following values are considered absolute, and any values besides these will result in a child being ignored when calculating a relative parent Height:

• HeightUnits = Absolute, PercentageOfSourceFile, RelativeToChildren

• YUnits = PixelsFromTop, PixelsFromMiddle, PixelsFromBottom

Width and Height are calculated independently. This means that a child may be ignored when calculating RelativeToChildren Width, but may be considered when calculating RelativeToChildren Height.

Examples

To help explain the way units work, this section two ColoredRectangles. Other types such as Container could be used, but colored rectangle is easier to see in pictures and animations so we'll use this type. Also, like the section above this section uses X and Width values, but the same concepts apply to Y and Height values.

Initially the Parent has a Width of 0 and a Width Units of Relative to Children.

This results in the Parent's width being controlled by the right side of the Child (the red ColoredRectangle). In other words, if the Child is moved or if its Width changes, the Parent's Width also changes.

In this case, the Parent's Width depends on its Child - specifically the right side. The Child's right side is absolute - it does not depend on the parent, so this relationship is not circular. However, if we were to adjust the Child so that its X Units depended on the parent's width, such as by changing X Units to Pixels from Right, the child would now depend on the Parent's width, creating a circular relationship. We can see that once this circular relationship is established, the parent's actual width changes to 0.

To reiterate, after this change, the child's right side depends on the parent's right side, and the parent's right side depends on the child's right side. This circular dependency is resolved by Gum with the parent ignoring the child - in this case the Parent behaves as if the child does not exist when it determines its actual width. This results in the Parent's width depending on no children, so it is set to 0 (the value set on the Parent's width).

These types of circular dependencies can cause confusion but they are okay to use in actual projects. Typically these types of situations exist when a Parent has a mix of children - some of which use absolute positioning, some of which depend on their parent.

For example, we can add a second child - a yellow ColoredRectangle maned Child2. If Child2's right side is absolute, then the Parent will use it to determine its size. Notice that when this happens, the red Child ColoredRectangle adjusts appropriately.

The properties are applied in the following order:

1. Child2's right side is determined using its absolute X and Width values

2. Parent's Width value is set according to Child2's right side. Parent ignores Child (the red box) because Child's right side depends on Parent's right side.

3. Child sets its X according to Parent's right side

A practical example of how this type of relationship might be used is a situation where Parent contains objects that should control its size, but also has elements which react to the size such as a top bar.

Introduction

The Locked property controls whether an instance can be clicked in the preview window. If this value is true, then the instance cannot be clicked on directly, but must instead be selected through the Project tab.

Once a locked object is selected it can still be edited normally, both in the Variables tab and in the Editor tab. Locking an instance prevents accidental selection in the Editor tab.

The Clips Children property controls whether children of a component or container can render outside of the bounds of their parent. By default this is false, which means that all children can fully-render, regardless of whether they are within the bounds of their parent or not. Setting this value to true will prevent children from rendering outside of the bounds of their parent.

Introduction

The Height Units variable controls how a unit is vertically sized, which may be relative to its parent. By default most types uses Absolute height, where each unit represents 1 pixel of height in pixels. When using Absolute, an object ignores its parent's Height.

Absolute

The following shows a child ColoredRectangle with 50 Absolute Height:

Relative to Container

The following shows a child ColoredRectangle with -10 Relative to Container Height, which means is sized 10 pixels less tall than its parent.

Percentage of Container

The following shows a child ColoredRectangle with 100 Percentage Height, which means it has 100% of the height of its parent. Note that 100 Percentage is the same as 0 Relative to Container:

Ratio of Container

Ratio of Container can be used to fill available space or to share available space with other objects using a ratio.

The simplest case is a single child in a container with its Height Units set to Ratio of Container.

In this case the blue ColoredRectangle has no siblings (its container has no other children), so it occupies the entire parent height. If a second child is added (by copy/pasting the existing child), then each child is given 1 ratio value, which means each is 1/2 of the size of the entire parent.

To better visualize the effect of ratio, it's common to set the parent's Children Layout to Top to Bottom Stack, and to give each child a different color as shown in the following image.

As more children are added, each child's height is adjusted to make room for the new children.

Ratio values are distributed among all siblings using Ratio of Container proportionally. The image above shows four siblings, each given 1/4 of the ratio. If one of the the ratios changes (such as by increasing the second sibling's Height value to 3), then all siblings adjust in response to this change.

In this case, the total ratio is 6 (1 + 3 + 1 + 1), so the red is given 3/6 (1/2) of the container's height, while each of the others is given 1/6 of the container's height.

Values of 0 are supported, resulting in the object drawing with an absolute height of 0.

Ratio of Container is calculated after accounting for the height of children which are using absolute height. For example, if the height of the first child is 80 with a Height Units of Absolute, then the other three shrink to give the first the necessary room.

This effect can also be seen by adjusting the height using the handles.

Gum ignores invisible objects when calculating available space for Ratio Width units. Therefore, if a sibling is invisible, Gum treats it as if it has 0 height which allows all other Ratio siblings to expand.

Ratio of Container also respects Stack Spacing. A Stack Spacing value greater than 0 removes the available space for all children with a Height Units of Relative to Container.

Relative to Children

The following image shows a child ColoredRectangle with 50 RelativeToChildren Height, which means that it is 50 pixels taller than is necessary to contain its children. Since the rectangle has no children, this is the same as having 50 Absolute Height:

RelativeToChildren can be used to size an object based on the position and sizes of a container's children. The following image shows a container with 0 RelativeToChildren Height, which mans that its height is set just large enough to contain its children. Notice that if the children are moved, the rectangle's height adjusts. Both children are considered so the container adjusts its height according to the bottom-most side of either child:

A non-zero Height when using RelativeToChildren can be used to add additional padding to a parent container. The following shows how changing the height can adjust the absolute height relative to children:

Relative to Children and Auto Grid Vertical

If a parent sets its Height Units to Relative to Children, then it must resize itself to contain its children. Normally, the height of the entire parent is determined by the child which needs the most space vertically. If the parent uses an Auto Grid Vertical layout, then the children control the size of the cells rather than the entire parent. Since all cells must be the same size, the child which needs the most amount of space vertically determines the height of all cells.

For example, the following image shows a four by four grid, each containing one white rectangle. The first rectangle has an absolute width and height of 100, so each cell is sized to be 100x100. Note that the other rectangles are 50x50.

The largest child determines the cell size for all other children. Therefore, if a child is moved or resized so it outgrows its cell, then the parent height adjusts in response.

Relative to Children and Text

The term "children" can refer to:

• Instances added to a parent, such as ColoredRectangles added to a Container

• Individual letters in a Text instance - each letter and line of text can expand the height of its parent

The following animation shows a Text instance which has its Height Units set to RelativeToChildren. As more lines of text are added, the Text automatically expands in size.

The height of a Text instance using Relative to Children depends on the number of lines displayed by the Text instance and the maximum line height given the current font properties. Therefore, the height of a Text stance remains the same regardless of the contents of a single line.

For example, the following image contains multiple Text instances. Each has a single line of text, but the line of text differs in the height of each character. Notice that the texts are all the same height even though the contents of their lines differ.

Percentage of Other Dimension

Percentage of Other Dimension adjusts the object's effective height so it remains proportional to the Width value multiplied by the Height value (as a percentage). For example, if a Height value of 200 is entered, then the effective height is 200% (2x) of the width.

The following image shows a child ColoredRectangle with a Height of 200 Percentage of Other Dimension. In this image, the Width value is 50 units, so the effective height is 100 units:

Percentage of Source File

The Sprite type has an extra Height Unit called Percentage of Source File, which sets the height of the Sprite according to the file that it is displaying. This is the default Height Unit for Sprites.

The following image shows a child Sprite with 200 Percentage of Source File Height, which means it draws two times as tall as its source image:

Introduction

Gum Screens and Components support defining a base type. By setting a base type, a screen or component automatically inherits the following from the base type:

• Variable values

• Exposed variables

• Instances

• Available variables, such as stacking if inheriting from a container

Inheritance is useful if your project needs multiple screens or components which share common variables or instances.

Component Inheritance

All components use inheritance even if the Base Type variable is not set explicitly. By default components inherit from the Container type.

By inheriting from the Container type, components have access to all component variables such as Children Layout.

Inheriting from Standard Types

Components can inherit from standard types. For example, instead of inheriting from Container a component may inherit from ColoredRectangle. By doing so, it has access to all properties on the ColoredRectangle type.

Inheriting from Components

Components can inherit from other components. By doing so the component inherits all children and exposed variables.

A component which inherits from another component is often called a derived component. The component which is being inherited from is often called a base component.

A base component can be used to define instances which the derived component can modify. For example a component named ButtonBase may define that all components have a ColoredRectangle named Background and a Text named TextInstance.

If another component uses ButtonBase as its Base Type, then this component automatically gets Background and TextInstance children which match the base instances.

The CancelButton can modify variables on the added children. For example the CancelButton can modify the Text on the TextInstance and the color values on the Background.

The derived component has the following restrictions when working with children

• Name cannot be changed. For example Background must always be named Background.

• Base Type cannot be changed. For example, the base type for Background must be ColoredRectangle

• Children defined in the base cannot be removed. For example, the Background child cannot be deleted from CancelButton

If the base type adds new instances, then the derived types automatically get the same instances added as well. Similarly, if the base type deletes a child, then the child is also removed from the derived type.

Derived types get access to all of the exposed variables in the base type. For example, if ButtonBase exposes the TextInstance's Text property, this is also available on the derived component.

Base Type vs States

Base types allow for the customization of a component, including the creation of many variants. Similarly, States also allow for the customization of a component in similar ways. When deciding between whether to use states or inheritance, keep the following in mind:

• States are often used to set variables temporarily, while inheritance is permanent. For example, a button may set its background color values in response to being highlighted. By contrast, a Cancel button may always say "Cancel".

• States do not allow for the creation of new instances. Although derived components cannot delete children which are defined by their Base Type, derived components can add additional instances.

• Components can use multiple categories. Therefore, it may not be clear which category defines the type of component. A component can only have one Base Type, so its type is defined clearly.

Introduction

Health bars are common UI elements in games. A similar element to health bars are progress bars. Even though the two are used in different situations, the layout for these two is the same.

Creating the Component

First we'll define the component:

1. Open Gum

2. Open or create a new Gum project

3. Right-click on the Components folder

4. Name the component HealthBar

5. Resize the HealthBar component so it is wider than it is tall. For example, assign a Width of 200 and Height 32.

Adding a Background

Next we'll add a background to our HealthBar Component

1. Drag+drop a ColoredRectangle into the HealthBar

2. Select the newly-created ColoredRectangleInstance

3. Select the Alignment tab

4. Click the Fill Dock button
5. Change the ColoredRectangleInstance color to black

Now we have a black background to our HealthBar

Creating an Inner Container

The HealthBar displays its current health with another rectangle. This second rectangle will be contained inside a container, which will provide a boundary. To add an inner container:

1. Drag+drop a Container onto the HealthBar

2. Select the Alignment tab

3. Click the Fill Dock button

4. Change Width and Height to -8 to provide a 4 pixel margin on each side.

Adding the Foreground Rectangle

Finally we'll add the foreground rectangle which displays the health:

1. Drag+drop another ColoredRectangle onto the ContainerInstance

2. Click the Alignment tab

3. Click the Fill Dock button

4. Change the following values:

   1. X Units to Pixels from Left

   2. X Origin to Left

   3. Width to Percentage of Container

   4. Width to 100

Now, the Width value can change between 0 and 100 to indicate the health percentage.

Exposing the Width of the inner rectangle may be needed to change instances of each HealthBar.

Introduction

The Rotation property can be used to rotate Gum components. It is measured in degrees, where positive values rotate an object counterclockwise about its origin ( and ).

Example

An object is rotated by its origin, which by default is its top-left corner:

Objects can also be rotated visually by grabbing the rotation handle:

X Origin and Y Origin

Introduction

The Width Units variable controls how a unit is horizontally sized, which may be relative to its parent. By default an object uses Absolute width, where each unit represents 1 pixel of width in absolute terms. When using Absolute, an object ignores its parents' Width.

Absolute

The following shows a child with 50 Absolute Width:

Relative to Container

The following image shows a child ColoredRectangle with -10 RelativeToContainer Width, so it sizes itself 10 pixels less wide than its parent.

Percentage of Container

The following shows a child ColoredRectangle with 100 Percentage of Container Width, which means it has 100% of the width of its parent. Note that 100 Percentage is the same as 0 Relative to Container:

Ratio of Container

Relative to Children

The following image shows a child ColoredRectangle with 50 Relative to Children Width, which means that it is sized 50 pixels wider than is necessary to contain its children. Since the rectangle has no children, this is the same as having 50 Absolute Width:

Relative to Children can be used to size an object based on the position and sizes of a container's children. The following image shows a container with 0 Relative to Children Width, which means that its width is set just large enough to contain its children.

A non-zero Width when using Relative to Children can be used to add additional padding to a parent container. The following image shows a container with 20 pixels of padding width:

Relative to Children dynamically adjusts to changes in properties on the children. In the following animation the container has a Children Layout of Left to Right Stack. Adding additional children expands the container automatically:

Relative to Children and Auto Grid Horizontal

If a parent sets its Width Units to Relative to Children, then it must resize itself to contain its children. Normally the width of the entire parent is determined by the child which needs the most space horizontally. If the parent uses an Auto Grid Horizontal layout, then the children control the size of the cells rather than the entire parent. Since all cells must be the same size, the child which needs the most amount of space horizontally determines the width of all cells.

For example, the following image shows a four by four grid, each containing one white rectangle. The first rectangle has an absolute width and height of 100, so each cell is sized to be 100x100. Note that the other rectangles are 50x50.

The largest child determines the cell size for all other children. Therefore, if a child is moved or resized so it outgrows its cell, then the parent width adjusts in response.

Relative to Children and Text

Setting a Text instance's Width Units to Relative to Children results in the Text object adjusting according to its text contents. For example, setting the Width Units to Relative to Children and setting the Width to 0 results in the Text object automatically adjusting its actual width according to the text it contains.

Percentage of Other Dimension

Percentage of Other Dimension adjusts the object's effective width so it remains proportional to the Height value multiplied by the Width value (as a percentage). For example, if a Width value of 200 is entered, then the effective width is 200% (2x) of the height.

The following image shows a child ColoredRectangle with a Width of 200 Percentage of Other Dimension. In this image, the Height value is 50 units, so the effective width is 100 units:

Percentage of Source File

The following image shows a child Sprite with 200 Percentage of Source File Width, which means it draws two times as wide as its source image:

Absolute Multiplied by Font Scale

Absolute Multiplied by Font Scale is a property which multiplies the Font Scale property at runtime with the width value. This can be used to create widths which are responsive to font scales for devices which may have variable text sizes.

At the time of this writing, the Gum tool always uses a Font Scale of 1, so this cannot be previewed in the tool. However, when a Gum project is loaded at runtime, the runtime may apply a Font Scale value such as using the Text size from Windows.

Introduction

The X property controls the horizontal position for an object. The X value represents the position of an object's , using its .

Example

By default, an object's top-left corner is positioned relative to its parent's top-left corner.

The X Units variable controls how a unit is horizontally positioned relative to its parent. By default an object is positioned relative to the left of its parent, where each unit represents 1 pixel.

PixelsFromLeft

The following shows a child positioned 50 PixelsFromLeft relative to its parent:

PixelsFromCenterX

The following shows a child ColoredRectangle positioned 50 PixelsFromCenterX relative to its parent:

PixelsFromRight

The following shows a child ColoredRectangle positioned 50 PixelsFromRight relative to its Parent:

PercentageWidth

The following shows a child ColoredRectangle positioned 50 PercentageWidth relative to its Parent. In other words, it will be positioned halfway between the left and right edges of the Parent:

Introduction

The Visible property controls whether an object and its children appear.

Example

Toggling the Visible property changes whether an object is drawn.

Parent/Child Visibility

Toggling the visibility of a parent will make all children invisible, even if a child's Visible property is true.

Introduction

Parenting allows UI elements to be positioned and sized according to other UI elements. Parenting hierarchies can go many levels deep and the parent/child relationship can be visualized by the white line connecting the parent to the child when the child is selected.

Example - Drag+Drop in the Tree View

To change the parent/child relationship in the tree view:

1. Select a child

2. Drag+drop the child onto the desired parent

The child can be detached from its parent by drag+dropping it onto the Component.

Example - Using the Dropdown

To set a parent/child relationship:

1. Select the child

2. Change the Parent property to the desired parent:

Introduction

Variable References allows any variable on an instance to reference a variable on another instance. The most common use of Variable References is to create a centralized style component which can be referenced throughout a Gum project.

Variables which are assigned through Variable References cannot be directly set on the instance - the value obtained through the reference overwrites any custom value.

Example - Creating Color Styles

The following example creates a Styles component which contains a color value which is referenced by objects in a MainMenu Screen.

Any component can serve as a centralized location for styling, but we use the name Styles by convention.

The Styles component can contain as many objects as are needed to style your project. Additional objects can be added to help indicate how things are used visually. For example, we include a Text object to indicate the red color is the Primary Color.

The color value can be referenced by any other object including objects in different screens or components.

To add a variable reference:

1. Select the object which should have a variable reference

2. Click inside the Variable References text box

3. Type the variable reference. The format of the variable reference is {VariableName} = {Components or Screens}/{ComponentOrScreenName}.{InstanceName}.{InstanceVariable} For example, to reference the Red variable in the Styles component, the syntax is Red = Components/Styles.PrimaryColor.Red

Since color values have three components (Red, Green, and Blue), then all three components must be referenced. In this example, the background can reference the three colors with the following assignment text:

The types of the objects that contain the Variable References or which are being referenced do not matter. For example, a Text object could have its color values depend on the color values defined by a ColoredRectangle in the Styles component.

Once Variable References are set, the referenced instances (instances in Styles) can be changed and the changes will immediately propagate throughout the entire project.

Variable References in the Property Grid

As shown above, Variable References can be used to assign one variable to another. If a variable is referenced, then the variable cannot be manually assigned. The Variable Reference takes priority. For example, if an object references the Red, Green, and Blue variables, then those values cannot be manually set on the object. The values appear disabled and text indicates why they are read-only.

Implied Variable References

When entering a variable reference, Gum understands implied variable references by filling in the left-side of the equals sign to match the variable name on the right-side. For example, the following can be entered in the Variable References text box:

Gum automatically adds Red = before the entry, as this is the most likely variable assignment. This addition happens when the text box loses focus, such as when Tab is pressed or when a different text box gains focus.

Assigning color values is a common part of styling, so to help with this situation, Gum also expands the "Color" variable into all three components when the Variable References text box loses focus. For example, the following text can be used to assign all three values at once:

When the Variable References box loses focus, this is expanded to the following assignments:

Same-Screen/Component References

The examples given above are useful for a centralized styling scenario. Variable references do not require referencing variables from other Screens or Components. If a reference is between two instances in the same Screen or Component, then the variable reference does not need to include the name of the component.

For example, we can assign the X value of one ColoredRectangle (RedRectangle) to the X value of another ColoredRectangle (BlueRectangle) using the following assignment:

This assignment forces the RedRectangle's X value to match the BlueRectangle's X value.

Changing the BlueRectangle's X value automatically updates the RedRectangle's X, even though the two rectangles have no other relationship to each other (such as a parent-child relationship).

Obtaining a Qualified Variable Name

Typing a variable name can be tedious, especially when referencing a variable in a different Screen or Component. Qualified variable names can be obtained by right-clicking on the variable name in Gum and selecting the Copy Qualified Variable Name option. This can then be pasted in the Variable References box of any other object.

Referencing Different Variables

Usually a variable references the same-named variable from the source, such as Red being assigned to Red. This is not a requirement, and variables can reference other variable values. For example, the Green value could reference the Red value on a source.

Although this is not common, referencing different variables can help create complex UI elements.

Introduction

The X Origin variable controls the point which an object is positioned by. By default the X Origin is Left. The X Origin is shown visually as a white "X" in the editor.

Left

The following image shows a with its X Origin set to Left:

Center

The following image shows a ColoredRectangle with its X Origin set to Center:

Right

The following image shows a ColoredRectangle with its X Origin set to Right:

The Y Units variable controls how a unit is vertically positioned relative to its parent. By default an object is positioned relative to the top of its parent, where each unit represents 1 pixel downward.

PixelsFromTop

The followingshows a child positioned 50 PixelsFromTop relative to its parent:

PixelsFromCenterY

The followingshows a child ColoredRectangle positioned 50 PixelsFromCenterY relative to its parent:

PixelsFromCenterYInverted

The followingshows a child ColoredRectangle positioned 50 PixelsFromCenterYInverted relative to its parent. Note that coordinates are "inverted", which means that increasing the Y value moves the object up rather than down. This value exists to simplify integration with engines which may use positive Y as up:

PixelsFromBottom

The followingshows a child ColoredRectangle positioned 50 PixelsFromBottom relative to its parent:

PercentageHeight

The followingshows a child ColoredRectangle positioned 50 PercentageHeight relative to its parent:

Introduction

Behaviors can define requirements which are resuable across multiple components to standardize instance names and behaviors. If a component uses a behavior, then it is forced to include categories and instances according to the behavior definition.

Behaviors are used to define requirements for components, to simplify the creation of new components, and to reduce the chances of spelling and implementation mistakes.

Common Behavior Usage

Behaviors are used to standardize state, category, and instance names. The most common usage of behaviors is with Gum Forms. Of course, behaviors can also be used to standardize names in your project for components which are not intended to be with Gum Forms.

Creating a Behavior

To add a behavior:

1. Right-click on the Behaviors folder

2. Select Add Behavior
3. Enter the new behavior name. Often time the word Behavior is added at the end of the name, such as ButtonBehavior

New behaviors appear in the Project tab.

Once a behavior has been created, it can be given categories, states, and instances. Any component which uses this behavior is required to have the same categories and states.

For example, the ButtonBehavior may have the following:

• ButtonCategory (Category)

  • Enabled (State)

  • Disabled (State)

  • Focused (State)

  • Pushed (State)

A behavior can have as many categories and states as needed.

Once a behavior is added, it can be used in a component. To add a behavior to a component, drag+drop the behavior onto the component in the tree view.

Behaviors can also be added and removed on the component's Behaviors tab:

1. Select a component which should use the behavior

2. Click the Behaviors tab

3. Click the Edit button

4. Check the desired behaviors - a component may use multiple behaviors

5. Click OK

Notice that once a behavior is added to a component, the component automatically creates the matching categories and states.

These categories cannot be removed as long as the component uses the behavior.

Category and State Requirements

As mentioned above, if a component uses a behavior, then the component is required to include all of the states and categories defined by the behavior. If a behavior is added to a component, then all states and categories in the behavior are automatically added to the component. Keep in mind that newly-added states do not automatically assign any values. The behavior only requires that the states exist but it does not decide which variables are assigned by the states. These required states can even be left to their default so they have no affect on the component.

Required states and categories cannot be removed or renamed. Required states cannot be moved to different categories.

If a new category or state is added to a behavior, all components which use the behavior also have the new category or state added.

If a state or category is removed from a behavior, Gum does not remove the state or category from components which implement the behavior. Behaviors only define what is required, but they do not prevent components from defining additional states and categories. Also, the states on components may still be needed even if the behavior is removed. Therefore, if you remove any states or categories from a behavior, you may need to manually remove the same states and categories from components which use the behavior if these are no longer needed.

Instance Requirements

Behaviors can include instances, resulting in required instances existing in components which use the behavior. Instances in behaviors only include two properties:

• Name

• Base Type

Instances in behaviors only require that instances in components have these two matching properties. All other properties can be set to any value.

To add an instance to a behavior, drag+drop a standard element or component onto the behavior in the Project tab.

An instance can have its Name changed, Base Type changed, or removed.

If a component is missing a behavior then the Error window provides information about the missing requirement.

Introduction

ColoredRectangles are used to display solid color rectangles. It can be used to provide a solid colored background or placeholders for content such as Sprites. ColoredRectangles are also useful for quickly blocking out a UI or learning about Gum's layout with a visual object.

As the name suggests, ColoredRectangles have a Color property which can be modified.

Introduction

The Y Origin variable controls the point which an object is positioned by. By default the Y Origin is Top. The Y Origin is shown visually as a white "X" in the editor.

Top

The following image shows a with its Y Origin set to Top:

Center

The following image shows a ColoredRectangle with its Y Origin set to Center:

Bottom

The following image shows a ColoredRectangle with its Y Origin set to Bottom:

Baseline

The following shows a Text with its Y Origin set to Baseline:

Baseline is often used to align fonts of different sizes. The following image shows two Text instances with different font sizes. Both are positioned by their baseline so their bottoms align properly (ignoring descenders, such as on the letter p and the comma).

By contrast, the following image shows the same Text instances using bottom alignment.

Introduction

The Default Implementation property can be used to indicate which component is the default implementation for a behavior. This property does is not used by the Gum tool, but instead exists for runtime implementations (such as FlatRedBall) to decide which type of component to create when an instance of a behavior is requested.

This property may not be used by a particular runtime. For example, at the time of this writing the MonoGame runtime does not use this property.

Common Usage

Behaviors are often used to help with the creation of components which need to have a certain set of states and instances. For example, the Button type in Gum Forms uses a category named ButtonCategory containing multiple states such as Enabled and Disabled.

At runtime, a game may need to create an instance of the Button type without specifying the component associated with the Button forms type. The Default Implementation property can help runtime libraries (such as FlatRedBall) determine which component to create for the Button's visual.

The Button type is a good example of why this property might be needed because the default Forms components include multiple components which implement ButtonBehavior.

To resolve this ambiguity, the ButtonBehavior's Default Implementation is automatically set to Controls/ButtonStandard.

For more information about whether you should set the Default Implementation, refere to the documentation for your particular runtime.

Introduction

The Blend variable controls how the selected instance combines its colors with whatever is drawn before. The final appearance of a NineSlice depends on its Blend, Alpha, Source File, and Color values.

For more information and examples, see the Sprite Blend page.

Introduction

NineSlice is a standard component which can be used to create visual objects which can stretch to any size without creating distortion on the source image. For example, consider the following image:

This image could be used to create nine slices of various sizes without any distortion:

The NineSlice achieves this effect by splitting the texture into nine pieces, and scales each one differently to prevent distortion. Highlighting a nine slice shows how it is split:

This is achieved by splitting the texture into 1/3 sections wide and tall. The following image shows how the original image will be split:

NineSlice Texture

The simplest way to assign a texture to a NineSlice is to use a single file. Setting the SourceFile to a single PNG will result in the NineSlice using that one texture, where each section of the NineSlice displays 1/3 of the width of the file and 1/3 of the height of the file.

A NineSlice's Texture Address property can be used to change the portion of the source texture that it uses. More info can be found in the Texture Address subpage.

Alternatively, nine files can be used to specify each section of the NineSlice independently. To use nine individual files, each file must be given a specific suffix.

The following suffixes can be added to create nine slice graphics. For example, assuming your NineSlice image is called "Image" and you are using the .png file format:

• Image_BottomCenter.png

• Image_BottomLeft.png

• Image_BottomRight.png

• Image_Center.png

• Image_Left.png

• Image_Right.png

• Image_TopCenter.png

• Image_TopLeft.png

• Image_TopRight.png

The Wraps Children property controls whether children wrap or stack beyond their container's boundaries when the container's Children Layout is set to Top to Bottom Stack or Left to Right Stack.

If a parent has Wraps children set to true, the wrapping adjusts in response to resizing the parent.

Similarly, resizing a child may result in the stacking changing.

The row height in a Left to Right Stack is determined by the largest child in the row.

Similarly, column width in a Top to bottom Stack is determined by the largest child in the column.

Containers are used to group objects to simply movement, alignment, positioning, and size. Containers are usually invisible, although they can draw their outlines in Gum to help visualize their position and size.

Introduction

The Texture Left variable controls the left pixel of the source rectangle used to draw the NineSlice. Texture Left is only available if the NineSlice uses a Texture Address of Custom or Dimension Based.

The following image shows a NineSlice with a Texture Left value of 96.

Texture Left controls the left side of the region that the NineSlice displays on its source file. In this case, the left-edge of the source rectangle is 96 pixels from the left edge of the entire file.

Introduction

The Children Layout property determines how a container positions its children. The default value is "Regular" which means that children are positioned according to their X Units and Y Units.

Top to Bottom Stack results in the children stacking one on top of another, from top to bottom.

Left to Right Stack results in the children stacking one beside another, from left to right.

Auto Grid Horizontal results in the children being placed in a grid, filling in horizontally first before wrapping to the next row.

Auto Grid Vertical results in the children being placed in a grid, filling in vertically first before wrapping to a new column.

Example

The following shows how to use the ChildrenLayout property to change the default position of a Container's children. The following animation shows the different Children Layouts being set:

Regular

Regular layout positions each child independent of every other child. The position of one child does not affect the position other children. This is the default layout for containers.

Top to Bottom Stack

Top to Bottom Stack results in each child being positioned after its previous sibling vertically. This can be used to create horizontal stacks.

Left to Right Stack

Left to Right Stack results in each child being positioned after its previous sibling horizontally. This can be used to create vertical stacks.

Stacking and X/Y Values

When children stack, each child's X or Y depends on the boundary of its previous sibling. When stacking vertically, the child's Y value begins at the bottom side of the previous item. Similarly, when stacking horizontally, the child's X value begins at the right side of the previous item.

For example, the following image shows a Text object with a Y value of 20. Notice that it is positioned 20 units below the item above it.

This effect is easy to notice when dragging an object inside a stack, as shown in the following animation:

Stacking and Units

If instances are stacked in a container, the stacking controls the instance values based on the direction of the stack. Containers with a Top to Bottom Stack control the Y value of their children. Similarly, Containers with a Left to Right Stack control the X value of their children. The position value which is not controlled by the stack can be changed freely without any impact on the stacking.

For example, if a container stacks its children using a Top to Bottom Stack, the children in the stack are free to change their X values. The following animation shows how children can be left, center, or right anchored (which changes their X Units and X Origin) without affecting the other children in the stack.

An object will stack only if its position unit values are top or left for vertical or horizontal stacks. For example, if a child is part of a Top to Bottom Stack, it will only stack if its Y Units is set to Pixels from Top. Otherwise it ignores its parents stacking behavior.

In general this behavior can cause unexpected behavior, especially if additional siblings follow the child which is not using the default Pixels from Top or Pixels from Left, so changing this value on the primary stacking direction is not recommended.

Stack Spacing

Top to Bottom and Left to Right stacks separate their children using the Stack Spacing property. For more information, see the Stack Spacing page.

Stacking and Children Origin

In most cases children which are stacked should use a Left X Origin if the parent uses a LeftToRightStack and should use a Top Y Origin if the parent uses a Top To Bottom Stack.

For example, consider a parent which contains two children - a blue and a red rectangle.

In the image shown above, the red rectangle is positioned directly to the right of the blue rectangle. Notice that if the red rectangle's X Origin is changed to Center, the red rectangle overlaps the blue rectangle.

If the red rectangle's X Origin is changed to Right, then its right side will align with the right side of the blue rectangle, resulting in the red overlapping the blue completely. In this case the stacking is essentially cancelled out by the X Origin.

This overlapping may not be desirable, so keep this in mind when changing a stacked child's origin.

Wraps Children

The Wraps Children property controls how stacking behaves beyond boundaries. For more information, see the Wraps Children page.

Reordering Children

Children of a container which uses the TopToBottomStack or LeftToWriteStack will be ordered according to their order in the tree view on the left. By default this is the order in which the children are added to a parent container.

Children can be reordered using the right-click menu on an instance.

Alternatively, children order can be changed by clicking on the item in the tree view, holding down the ALT key, then pressing the up or down arrows.

Auto Grid Horizontal and Auto Grid Vertical

Auto Grid Horizontal and Auto Grid Vertical layouts result in each child of the container being placed in its own cell. All position and size values are relative to the entire cell, so children can expand to fill their cell or be positioned according to any side or corner.

The following shows a container with an Auto Grid Horizontal and Vertical Cells of 2, resulting in a 2x2 grid. As children are added to the container through copy/paste, each child is placed in its own cell.

The number of cells is controlled by the Auto Grid Horizontal Cells and Auto Grid Vertical Cells. Increasing the number of cells results in the rows or columns adjusting automatically.

Each child occupies one cell, and the order of the children controls the order of the placement in grids. The first child occupies the top-left row. If using Auto Grid Horizontal, each child is placed to the right of its preceding sibling, wrapping to the next line when reaching the end of a row. If using Auto Grid Vertical, each child is placed below its preceding sibling, wrapping to the next column when reaching the end of a column.

Children can be reordered by using the alt+arrow key in the tree view, resulting in reordering just like when using a stacking Children Layout.

Children treat their particular cell in the grid as their parent, so any sizes or positions will be based on their parent cell. In other words, if a child's WidthUnits is set to RelativeToContainer, the container in this case is the cell, not the entire Container instance.

If additional children are added beyond the number of cells in a grid, additional children will spill over the bounds of the grid. The following animation shows a 3x3 grid using Auto Grid Horizontal. As more children are added, additional rows are added below the bounds of the grid.

When using Auto Grid Horizontal, the number of columns is fixed, but additional rows can be added beyond the bounds of the container.

When using Auto Grid Vertical, the number of rows is fixed, but additional columns can be added beyond the bounds of the container.

Introduction

The Texture Address variable can be used to define the area that the NineSlice displays. By default the Texture Address is set to Entire Texture which means the NineSlice will display the entire source file (split up among the nine pieces).

Entire Texture

The following screenshot shows an entire texture being used for a NineSlice.

The entire texture is split up into 3 sections horizontally and 3 sections vertically, matching up the texture coordinates used to display the NineSlice's 9 sections.

Custom

The Custom value allows specifying a custom set of coordinates for the Nine Slice. Custom is most often used to when an image is part of a sprite sheet. The following example uses this image:

The NineSlice uses the following variables:

• Texture Address = Custom

• Texture Top = 0

• Texture Left = 0

• Texture Height = 40

• Texture Width = 40

These values result in the the following NineSlice:

Default Child Container specifies which instance should contain children which are added to instances of the current component.

By default this value is blank, which means that children will treat the entire component as their parent. If this value is set, children which are dropped on instances of this component type will use the instance as their parent.

Default Child Container is typically set on containers which are designed to hold children, but which have margins or decoration around the dedicated container instance. Examples include list boxes, tree views, and frames.

Example

Consider a Component named Frame which has two instances: OuterRectangle and InnerRectangle.

This Component is designed to keep all of is children inside the InnerRectangle, so that any child automatically respects the margin specified by InnerRectangle.

To make this kind of relationship the default, the Frame can set its Default Child Container property to InnerRectangle.

Once this value is set, instances which are drag+dropped onto Frame instances will use the InnerRectangle as their parent, as shown in the following animation.

Parent Details

When one instance is drag+dropped onto another instance, the Parent property is set according to the parent's Default Child Container.

Using the example above, the RectangleInstance is dropped on the ContainerTestInstance. Since the ContainerTestInstance is of type Frame, then the Default Child Container is applied on the drop, which results in the RectangleInstance's Parent being set to ContainerTestInstance.InnerRectangle.

Introduction

Polygons are shapes defined by an ordered set of points. Polygons can be used to draw lines, shapes, and define collision in games.

Introduction

The Texture Top variable controls the top pixel of the source rectangle used to draw the NineSlice. Texture Top is only available if the NineSlice uses a Texture Address of Custom or Dimension Based.

The following image shows a NineSlice with a Texture Top value of 48.

Texture Top controls the top side of the region that the NineSlice displays on its source file. In this case, the top-edge of the source rectangle is 48 pixels from the top edge of the entire file.

Introduction

Arcs are curved lines with variable thickness. Arcs can also be used to draw wedges if the line thickness is large enough.

Arc dimensions

Arcs draw inside their bounds, with the edge of the arc touching the bounding rectangle. The thickness of the arc remains consisntent regardless of the bound width and height.

The following shows an arc with a Sweep Angle of 270 degrees, being resized in the Editor tab.

Introduction

Thickness controls the width of the arc line in pixels. This value can be increased to make the line arc thicker.

Thickness can be increased to create a wedge.

Note that Thickness can be increased to any value including values larger than the radius of the arc. Large values can result in the arc rendering past its center point creating a bowtie shape.

Other undesirable rendering effects can happen with large thicknesses when working with arcs which have one size (width or height) larger than the other, as shown in the following image:

Introduction

Start Angle defines the angle of the starting point of the arc. This value is measured in degrees, with a value of 0 pointing to the right. The value increases counterclockwise. the Start Angle and Sweep Angle values combine to determine the range of angles covered by the Arc.

The following image shows the an Arc with a Start Angle of 0. The red lines and text are not part of the arc and are added to the screen shot to show the location of the Start Angle.

Changing the Start Angle moves one side of the arc. The arc appears to rotate if the Start Angle is changed gradually.

Start Angle defines the starting point of the arc. A value of 270 degrees and a value of -90 place the starting point of the arc in the same location. Values larger than 360 result in the value looping. These values, although normally not needed, can be used to create spinning animatoins.

Introduction

Sprites are objects which can draw an image (such as a .png) or a portion of a .png.

Introduction

Skia standard elements are a collection of elements which use SkiaSharp for rendering. Skia standard elements provide additional types of visuals supported by Gum, but not all runtimes support Skia standard elements.

Skia adds advanced vector graphics support for shapes such as Arc, ColoredCircle, and RoundedRectangle. Skia also adds support for vector file formats such as SVG and Lottie.

Enabling Skia Standard Elements

Skia standard elements must be explicitly added to gum projects. To add Skia standard elements Select Plugins -> Add Skia Standard Elements.

After clicking this option, Gum adds new standard elements.

Once these Skia standard elements are added, they can be added to Screens and Components just like any other standard element.

Introduction

The Custom Frame Texture Coordinate Width property allows a NineSlice to customize the number of pixels used on the source texture when defining its outer frame. This allows for fine control over which parts of a NineSlice stretch and which parts are used as the corners and edges.

By default this value is null, which means the NineSlice automatically dedicates 1/3 of the texture for the edges.

Changing Custom Frame Texture Coordinate Width

If the Custom Frame Texture Coordinate Width value is changed, then the source texture applies a fixed pixel size to the borders. For example, using the image above, the frame can be changed to 3 so that only the black and white pixels are part of the border.

Introduction

Categories can be used to organize similar states into one group (such as a button's Pressed and Unpressed states).

A category can contain one or more states. States within a category have special behavior:

1. If one state in a category explicitly sets a variable (such as X), then all other states in that category will also explicitly set the variable.

2. Each category can be set individually on an instance of a component or standard element. In other words, if a component has two categories, each category can be assigned to a state within that category independently.

Explicit Values Across States in a Category

Normally, when a new state is created, all variables are explicitly unset. The value displayed in the properties window will be the value inherited from the default state.

For example, the following image shows a component with a state called State1 with no variables explicitly assigned. Notice all values are green:

We can see the same behavior on a categorized state. The following image shows the categorized LeftSide state with all inherited values:

As mentioned in the introduction, if a variable is explicitly set on one state in a category, then all other states in that category will that same variable set to its default.

For example, if we set the X variable in the LeftSide state, the X variable in the RightSide state will become explicitly set (black instead of green).

Once the X variable is set on one state in a category, all other states in the same category will automatically have this value set - even new states:

Removing Variables from Categories

Variables can be removed from states, but this removal must be done at the category level rather than at the individual state. Doing so will remove all variables from all states within a category. To remove a variable in all states in a category:

1. Select the category itself (not the state)

2. Click the "X" button next to the variable

3. Confirm that you would like to remove the variable. Warning: this will remove the variable from all contained states.

This will remove the assignment of the variable from all states in the category.

Introduction

The texture address property controls the texture address behavior of a sprite. Specifically it can control whether texture addresses variables are available, and how texture coordinates and sprite size relate.

Entire Texture

If the texture address property is set to EntireTexture then the sprite draws its full image. The sprite does not repeat or render only part of the texture.

When using Entire Texture, individual texture values cannot be set so wrapping is not possible.

Custom

If the texture address property is set to Custom then the top, bottom, left, and right properties can be independently set. This allows a sprite to only render a portion of its source texture.

Typically a Texture Address of Custom is used in combination with a Width Units of Percent of File Width and and a Height Units of Percent of File Height. In this case, the size of the sprite depends on the texture coordinates.

DimensionsBased

If the Texture Address property is set to DimensionsBased then the texture coordinates adjusts internally according to the width and the height of the Sprite. In other words, making the sprite larger or smaller dies not stretch the image that it is rendering. Instead the image is be clipped, or clamped/wrapped according to the Wrap property.

When the Texture Address is set to DimensionBased, then the Texture Width and Texture Height values are replaced by Texture Width Scale and Texture Height Scale. In this mode, the Texture Width and Texture Height values are calculated by multiplying the absolute size of the Sprite by its respective scale values.

Texture Width Scale and Texture Height Scale

The Texture Width Scale and Texture Height Scale values determine the size of the texture on the Sprite when using DimensionsBased Texture Address. By default this value is 1, which means that the source image displays at its native size.

Increasing this value results in the image displaying larger. For example setting a value of 2 results in the displayed image being twice as large. Scale values for width and height can be set independently.

Introduction

The text object can be used to display written information. The text object supports:

• Horizontal and Vertical alignment

• Fonts from the installed font library on your machine

• Custom fonts using Bitmap Font Generator:

• Scaling independent of source font

Introduction

The Wrap value controls whether the sprite wraps its image when rendering portions beyond the right and bottom image bounds. If this value is true then wrapping occurs. Otherwise, areas beyond the texture extend the last pixel - also known as "clamping" the value.

The Wrap variable applies when dealing with a Texture Address of Custom or DimensionsBased. Wrapping is not available when using a Texture Address value of Entire Texture.

Wrap and Custom Texture Address

If Texture Address is set to Custom then wrapping is available. All examples in the Custom Texture Address section use the following values:

• Width = 100

• Width Units = Percentage of File Width

• Height = 100

• Height Units = Percentage of File Height

For more information, see the and pages.

Toggling wrapping adjusts whether the Sprite wraps or clamps the area defined by the Texture Left, Texture Top, Texture Width, and Texture Height values.

A texture is wrapped if its Texture Right or Texture Bottom values are set to be larger than the source texture. For example, the following image shows a Sprite which is using an image that is 200x200. Its Texture Width is set to 500 and Texture Height is set to 300 so the sprite displays wrapping.

If the Texture Width or Texture Height values are adjusted, then the Sprite's wrapping also adjusts.

If Wrap is set to true, then wrapping happens for any area to the right or bottom of the bounds of the source. The following shows the bounds of a sprite moved in the Texture Coordinate tab resulting in the area that is being displayed wrapping and repeating.

Wrap and DimensionsBased

If a Sprite sets DimensionsBased for its Texture Address, then its source file can wrap if its dimensions are large enough to result in the texture width or texture height set to a value larger than the source dimensions.

All examples in the DimensionsBased Texture Address section use the following values:

• Width Units = Absolute

• Height Units = Absolute

Toggling wrapping adjusts whether the Sprite wraps or clamps the area defined by the Texture Left, Texture Top, and its size.

If a Sprite's width or height are adjusted, this results in its texture coordinate values also being modified. If Wrap is true then areas outside of the source file wrap.

Wrapping can also be affected by changing the Texture Width Scale or Texture Height Scale. Smaller values result in image being drawn smaller, making it wrap more.

Introduction

The Color value is used to perform a multiply color operation on the sprite. Color values can be used to darken or tint a grayscale texture. By default Sprites us a white color, which means the original texture will display unmodified.

Examples

The following images show the color values as applied to a multi-color sprite.

Red: 255 Green: 255 Blue: 255

Red: 255 Green: 0 Blue: 0

Red: 0 Green: 255 Blue: 0

Red: 0 Green: 0 Blue: 255

Red: 128 Green: 128 Blue: 128

Red: 0 Green: 0 Blue: 0

Introduction

The Blend variable controls how the selected instance combines its colors with whatever is drawn before. The final appearance of a Sprite or NineSlice depends on its Blend, Alpha, Source File, and Color values.

Normal Blend

Normal Blend is the default value. When an instance uses Normal Blend, it interpolates its color with whatever it draws on top of using its Alpha value as a weight.

If a Normal Blend Sprite has an Alpha of 255, then the Sprite completely replaces whatever it is drawn on top of.

If a Sprite has an alpha of 128 (roughly half of 255), then it averages its color with whatever it is drawn on top of.

A Sprite with 25 alpha (roughly 10%) will blend with whatever it is drawn on top of, but its color is given a weight of roughly 10%.

Additive Blend

Additive Blend results in the color of a Sprite being added to whatever it is drawn on top of. This typically results in the Sprite or NineSlice making things brighter. Additive Blend can be used to simulate a light.

Since Additive Blend results in a modification of what is under instead of a replacement, an Additive Blend Sprite or NineSlice typically appear transparent even when Alpha 255.

As alpha is reduced, the brightening effect is reduced. A Sprite or NineSlice with an alpha of 128 only applies roughly half as much of a brightening effect.

A Sprite or NineSlice with an alpha of 25 applies a slight brightening effect.

Stacking multiple Sprites or NineSlices with an Additive Blend results in the brightening effect stacking as well.

Replace Blend

Replace blend results in the Sprite or NineSlice completely replacing whatever it is drawn on top of regardless of Alpha or transparency in the source file.

A Sprite with no transparency in its source file drawn at 255 looks the same whether it uses Replace Blend or Normal Blend.

Changing the Alpha on a Sprite or NineSlice with Replace Blend does not affect how it is drawn - it is always drawn at full opacity.

Replace Blend results in a Sprite or NineSlice being fully opaque even if its source file has transparency. The following image shows two Sprites displaying the same image.

The Blue value controls the color of the Text object. The Blue value has a range of 0 - 255. The Blue value combines with the Red and Green values to create the final color.

For more information on working with color, see the Color page.

The Green value controls the color of the Text object. The Green value has a range of 0 - 255. The Green value combines with the Blue and Red values to create the final color.

For more information on working with color, see the Color page.

Introduction

The Font variable sets the font family used by the text.

This dropdown appears only if Use Custom Font is set to false.

The Font dropdown has access to any font which is installed locally.

To use a font in Gum, download the font and install it by double-clicking or right-clicking on the font.

Font Generation and Font Cache

Gum performs rendering using rasterized fonts. In other words, it renders using pre-made .png files which contain all of the characters in a font.

You can view the Font Cache in your project by selecting Content -> View Font Cache.

This folder contains all font files used by your project.

Note that each font has three files:

• bmfc - Bitmap Font Generator configuration file. This can be opened in Bitmap Font Generator to see the settings that have been used to export the other files

• fnt - Bitmap Font Generator font file. This is a text file indicating the location of each character in the matching png files. It also includes kerning pairs.

• png - This is the image file containing the letters for the font. The font may contain multiple image files if the character set or font size are large enough.

Each PNG can be opened in an image editor to view the packed characters. For example, the following shows the Arial 24 font. The blue background has been added manually to make the white characters visible:

Font Cache Generation

Fonts are generated as needed by Gum. This happens whenever a property changes on a Text object requiring a new font. Gum only re-generates fonts if a matching font doesn't already exist. The following animation shows new fonts being generated as a Text's Font Size is changed.

Fonts are generated in response to any of the following properties changing:

• Font

• Font Size

• Outline Thickness

• Is Italic

• Is Bold

• Use Font Smoothing

Introduction

Font Size controls how large a font appears on screen. Each font size and Font combination creates its own rasterized font, so using a lot of different font sizes will increase the amount of texture memory your game needs.

Example

The Font Size property can be set in Gum to make a text object's font larger or smaller. For example, the following shows a Text object with a font size of 18:

Changing the font size will increase the size of the Text object. For example, here is the same Text object with a Font Size of 36:

Font Cache

The first time a Font and Font Size combination are referenced, Gum creates a file in the FontCache folder. You may notice a small pause in Gum when setting Font and Font Size combinations for the first time as the file is created, but subsequent changes will be fast.

The FontCache folder is located in the following location:

/FontCache/

Introduction

This value controls the number of letters that the Text object will show. This value is used when displaying the text, but is not used when calculating the Text size or line wrapping.

If the value is <NULL>, then there is no maximum - all letters are displayed.

Example

Max Letters To Show limits the number of characters (including spaces). By default this value is <NULL>, which means a Text object will display its full string. Setting this value will adjust the display of the text, but it will not impact any layout values.

For example, by default a Text object displays all of its letters. Note that the Width is fixed, and the Height depends on the contained text - the Height is automatically set on the Text object according to the contents of the text.

Setting Max Letters To Show value to 30 restricts the Text object to displaying its first 30 characters, but the size and line wrapping do not change.

Max Letters To Show applies after all layout and text positioning has been applied. Therefore, centered text may appear off-center. The following text would appear centered if Max Letters To Show allowed the entire text to be displayed, but since it is cut-off, it appears off-center.

Introduction

The font scale property allows you to zoom a font in or out, effectively making the text larger or smaller. Unlike using the font size property, font scale will not re-create the font (when using standard fonts). Font scale is also necessary for resizing custom fonts.

Details

By default Text objects Font Scale value of 1.

Font scale can be increased, but doing so can make fonts pixellated. For example, setting the Font Scale value to 5 makes each pixel on the font 5x as large, resulting in a pixellated text object.

Similarly, FontScale can be set to a value smaller than 1, resulting in a shrunk font.

Introduction

The Color value controls a Text object's color. The Color value is created by combining the Red, Green, and Blue values.

The Color value can be changed through the color picker, or by changing the individual Red, Green, and Blue color values.

Color Multiplication

For default Text objects, the Color value modifies the displayed Text color. Gum creates .fnt and .png files where the color is white. If the .png includes any colors that are not white, then the resulting color is produced by multiplying the color value with each pixel. Therefore, if a Font is outlined, then the black pixels remain black.

Introduction

OutlineThickness can be used to create an outline around a font. The outline is saved in the .png of the font itself, so each value for OutlineThickness results in a new .fnt file and associated .png files created in the FontCache folder.

Setting OutlineThickness

The OutlineThickness can be set on a Text object like any other variable.

OutlineThickness changes appear in the Gum window.

The Red value controls the color of the Text object. The Red value has a range of 0 - 255. The Red value combines with the Blue and Green values to create the final color.

For more information on working with color, see the .

Introduction

The Source File property determines the file that is used by the Sprite. Sprite Source Files support the following formats:

• .png files

• .achx files (AnimationChains)

• Images from URLs

If a Sprite has an empty Source File or if it references a missing file, then the missing file texture is displayed.

Setting a PNG Source File

Source File can be set by typing a value or using the ... button to browser for a file.

All files are added as paths relative to the .gumx project.

If a file is referenced outside of the .gumx folder, then Gum asks if you would like to copy the file or reference it outside of the current directory. Usually files should be copied to the project folder to keep the entire Gum proejct portable.

ACHX Files

Once you have created an .achx file, you can reference it the same as a .png by entering its name or selecting it with the ... button.

When referencing an .achx file, be sure to also check the Animate checkbox and to select the Current Chain Name.

Referencing URLs

Gum Sprites can also reference URLs. Gum can display images from URLs with standard file extensions such as .png and .jpg

Introduction

The Is Italic value controls whether the Text instance uses an auto-generated font which is italicized.

Introduction

Text Overflow Vertical Mode controls whether lines of text can draw outside of the bounds of the Text object vertically.

Spill

Spill enables the drawing of text lines outside of the vertical bounds of a Text instance. The following image shows a Text instance with wrapped text using Spill.

Truncate Line

Truncate Line removes lines which fall outside of the bounds of the Text instance. The following animation shows lines of text truncating in response to changing the Text instance's height.

Note that if the Text instance's height becomes too small then all text disappears.

Introduction

Text Overflow Horizontal Mode controls how truncated words are treated. Horizontal truncation is only performed if the Text instance is using a Text Overflow Vertical Mode of Truncate Line. For information more see the page.

Truncate Word

Truncate Word results in words which do not fit in the Text instance's bounds being completely removed.

The following animation shows words (and lines) truncated in response to changing a Text instance's size.

Ellipsis Letter

Ellipsis Letter results in letters which do not fit in the Text instance's bounds being replaced by an ellipsis (...) which fits in the bounds of the Text instance.

The following animation shows words (and lines) replaced by ellipsis in response to changing a Text instance's size.

Note that additional letters must be removed from the Text instance so the added ellipsis fits in the Text instance's bounds.

Introduction

The Is Bold value controls whether the Text instance uses an auto-generated font which is bold.

Introduction

Text objects have a Text property which controls the displayed text. By default this value is set to "Hello".

Changing Text

The Text property can be changed in the multi-line edit window.

Text will wrap according to the Text object's Width.

The enter key can be used to add new lines to text.

Using BBCode for Inline Styling

Gum text supports inline styling using BBCode-like syntax. To add inline styling, surround text with variable assignment tags as shown in the following screenshot:

The following table shows the available variables that can be used for inline styling:

Note that changing Font and FontSize results in new Fonts created in the Font Cache.

BBCode can span multiple lines, whether the newlines happen due to line wrapping or through the addition of newlines in the text.

Multiple tags can overlap each other allowing you to combine tags for a single piece of text. For example, the following sets text to both bold and orange:

Styles can contain other styles as many levels deep as necessary.

Introduction

The Is CodeGen Plugin Enabled checkbox controls whether Gum generates code automatically to the destination location specified by the Code Project Root. Gum automatically generates code if:

• The Is CodeGen Plugin Enabled is checked

• A Code Project Root is specified

• An object has its Generation Behavior set to GenerateAutomaticallyOnPropertyChange

If this option is unchecked, then code will not automatically be saved to disk even if the other options are set.

For more information on automatic code generation, see the section on automatically saving generated code.

Introduction

This option controls whether generated code is displayed in the Code tab. If checked, generated code is displayed and is updated whenever a change is made in Gum.

Usually this option can remain checked even if you are not using generated code; however, very large components and screens may generate a large amount of code, which can slightly affect Gum's performance when selecting objects or making changes. If you are experiencing slowdowns and you do not need code to be generated, you can uncheck this option.

Introduction

The Use Custom Font variable controls whether a Text object uses a premade .fnt file (if true) or if it Gum automatically creates font files according to the Text's Font, Font Size, and Outline Thickness variables.

Use Custom Font is false by default.

Example

If Use Custom Font is set to true, then Gum displays the Custom Font File variable, which can point to a .fnt file created by Bitmap Font Generator.

If Use Custom Font is set to true, then the Font, Font Size, and Outline Thickness variables can no longer be set - as they are part of the font file itself.

The Font Scale variable is still available when using custom fonts.

To set a custom font

1. Click the ... button

2. Navigate to the location of the desired .fnt file

3. Select the file and click Open

Custom font files are .fnt files created by BitmapFontGenerator. Gum automatically creates .fnt files whenever a font value changes when UseCustomFonts is unchecked.

Creating Fonts with BitmapFontGenerator

To create your own font file:

1. Download Bitmap Font Generator from https://angelcode.com/products/bmfont/

2. Select Options -> Font Settings

3. Use the dropdown to select the font you would like to use. All .ttf files installed on the current machine should appear in the dropdown. If you would like to install a new .ttf, restart Bitmap Font Generator after installing the font.
4. After changing the settings, click OK

5. Select which characters you would like included in your font. Adding characters can increase the font size, but may be required depending on which characters you intend to use.
6. Select Options->Export Options

7. Select a Bit depth of 32 (or else transparencies won’t come through).

8. Select the texture width and height. For best performance, select a size which will contain all of the characters you have selected. Also, many game engines prefer textures which are power of two such as 256, 512, 1024, or 2048. Sizes larger than 2048 may not render properly on some hardware.

9. Change the Textures option to png – Portable Network Graphics

10. Be sure to keep the Font descriptor as Text.

11. Press OK to apply the changes

Also, note that if you are using outline, you will want to have the following values:

• A: outline

• R: glyph

• G: glyph

• B: glyph

You can verify that the settings will produce a proper PNG by selecting Options -> Visualize. If you see “No Output!” then you need to select characters to export. See the above step for more information.

To save the font, select Options->Save bitmap font as… to save your .fnt and .png files.

Once you have saved your files, you can select the .fnt to use in your project.

Creating Fonts with Hiero

The Hiero tool can also be used to generate .fnt files:

To generate a font:

1. Download and open the Hiero tool

2. Set the values needed for your font, such as font type, size, and effects
3. Select File -> Save BMFont Files (text)...

4. Select the location to save the files, such as in your project's Contents folder, or the subfolder which contains your Gum project

This .fnt file can now be loaded in the Gum tool or in code just like any other .fnt file.

Introduction

The Project Tab displays all Screens, Components, Standard Elements, and Behaviors in a project. Each element type is organized in its own subfolder.

Searching

The search bar can be used to find elements in your project by searching for their name. By default the following are searched:

• Screen Names

• Component Names

• Standard Element Names

• Behavior Names

Additionally, variable values can be searched by checking the Search variables checkbox. When checked, variable values are searched for the entered text.

Introduction

The Generation Scope options control whether the entire selected object is shown in the generated code window or if only the current state is selected.

If Selected Object is selected, then the entire object's generated code is displayed.

The Selected State option is useful if you would like to see only the changes made by the selected state.

Introduction

The Code tab provides generated code for your current Gum objects.

This tab provides the following functionality:

• Immediate display of generated code for the selected object

• Ability to see generated code for individual instances in an object or for an entire component/screen

• Ability to generate code automatically for a variety of target platforms

If you are working with Gum in a C# environment then the Code tab can help you write Gum code.

Enabling CodeGen Preview

To enable code generation:

1. Select a Screen, Component, or instance

2. Check the Is CodeGen Plugin Enabled checkbox

3. Check the Show CodeGen Preview checkbox to display the current selection in the preview window

Previewing Instances

If you have a single instance selected, the preview window displays the code for creating the instance and assigning its variables. This is especially useful if you are unsure how to reproduce a particular layout in code. For example, the following image shows the generated code for a Text named TextInstance.

The generated code shows all of the assignments necessary to reproduce the current instance's layout. Keep in mind that only explicitly-set variables are displayed. Any default (green background) variables are not assigned in generated code.

Previewing Entire Screens and Components

If a Screen or Component is selected, then an entire class for the component is displayed in the preview window. This generated code includes:

• using statements

• A partial class with the suggested name. The name appends the word "Runtime" to the Screen or Component name

• enum declaration for all categories

• Properties for each category including switch statements assigning all properties for each state

• A property for each instance in the Screen or Component

• Initialization of all variables including variables on the instances

Automatic Saving of Generated Code

The Code tab supports the automatic copying of files to disk. By using this feature, C# projects can automatically stay in sync with Gum projects, eliminating the need to write custom Runtime objects.

To set up automatic code generation, first enable the code generation plugin as shown above. The Show CodeGen Preview checkbox does not need to be checked.

Next, modify the values in the Project-Wide Code Generation section and the Element Code Generation section as discussed in the following sections:

Output Library

Select the desired Output Library, such as MonoGame.

Object Instantiation Type

If you are planning on loading the .gumx project, select the FindByName option.

If you would like the entire project generated, select the FullyInCode option. This option enables working in Gum to create layouts which will work fully in code without loading a .gumx file. This is especially improtant if you are working on a platform with limited IO access. Generated code can run faster than loading a .gumx file since it does not require file IO, XML parsing, and reflection.

Project-wide Using Statements

Add the following using statement at the end of the Project-wide Using Statement box so that references to standard runtime types are found.

If you plan on creating Screens, you should also add using statements for your component runtimes

Code Project Root

Enter the location of the folder containing the .csproj file in the Code Project Root text box. If an absolute path is entered, it will be saved to a relative path so that generation works for all users working on a project regardless of where a project is cloned even though it appears absolute in Gum. For example: C:\Users\Owner\Documents\GitHub\Gum\Samples\MonoGameGumCodeGeneration\

Root Namespace

Enter the project's Root Namespace, such as MyGame.

Default Screen Base

Enter the type that you would like all Screen runtimes to inherit from. If you're not sure what to enter, then use GraphicalUiElement. If your game uses a custom class that you have written for all Screens, then use the name of that class. You can switch to custom classes later as your project grows.

Generation Behavior

Select NeverGenerate for components which should not generate to disk

Select GenerateManually if you would like to generate code only when the Generate Code button is clicked.

Select GenerateAutomaticallyOnPropertyChange to generate code whenever a property changed. This option is useful once you are comfortable with code generation. It results in code being generated automatically as you make edits in Gum.

Introduction

The Is Italic value controls whether the Text instance uses an auto-generated font which applies font smooth (anti-aliasing). This effect of this value can be easily observed if zoomed in.

This value is true by default because it usually produces more visually appealing fonts. If your project is using an intentionally pixelated font then you may want to disable this property to preserve the pixelated aesthetic.

Introduction

The project properties window allows you to modify properties that apply across the entire project (as opposed to a single screen or component).

To open the Project Properties tab, select Edit -> Properties.

Canvas Width/Height

Gum allows you to change the canvas width and height of a project. This canvas width/height can both give you a sense of size when creating UIs, as well as provide a container for objects with no parents. In other words, objects that sit directly in a screen (as opposed to in another container) will be positioned and sized according to the canvas width/height.

The canvas width and height can be changed through the project properties page.

Localization

Gum supports localization using a localization CSV. Adding a localization file to your Gum project is useful since it allows previewing your layout with different languages. Some languages have text which is longer than other languages. By checking your localization in Gum you can adjust your layout so that it properly handles longer text.

Localization can be added using a CSV file. The first column in a localization file is the string ID, which is the key that is used to perform localization look-ups. These keys should suggest the text which is displayed, but should also have some kind of prefix or suffix to differentiate string IDs from untranslated text.

Each additional column can contain translations for a single language. The top row of the CSV is ignored by Gum, so you can add titles for the language to make your CSV more readable.

The following shows what a sample CSV might look like:

Notice the string IDs in the table above have the "T_" prefix. This is not a requirement - you are free to use any string ID convention you choose.

Notice that comments using two forward slashes (similar to languages like C#) can be used to add comments which are ignored by Gum.

Once you have created a CSV with the desired entries, you can reference this by clicking the ... button to browse for the file in Gum.

After selecting the localization file, you can choose which language index is being displayed. Note that this is a 0-based index, with the left-most column being 0. For example, using the table above a Language Index of 1 would result in the English column being displayed.

Once you have added a localization file, Gum recognizes this and displays Text properties as an editable drop-down. You can type in a string ID, or you can use the drop-down to select from available options.

Localized text appears in Gum based on the selected ID. You can change the Language Index at any time to see localization applied immediately in your screens and components.

Font Ranges

The Font Ranges setting controls which characters are included in default fonts. The Font Ranges value is ignored when using custom font (.fnt) files.

The default Font Ranges value is 32-126,160-255 which maps to the first page of the Bitmap font generator character set, labeled as Latin + Latin Supplement.

Additional characters can be added by modifying the Font Ranges character set. Individual characters can be added or entire ranges. For example, to add the Latin Extended A set, the Font Ranges value can be changed to 32-126,160-255,256-383. Note that the last range of 256-383 could be merged with the previous to produce the following range: 32-126:160-383. Note that the ranges are inclusive on both ends, so a range of 160-383 will include the characters 160 and 383 along with all values in between.

Changing the font ranges immediately refreshes the page. Note that all fonts are re-created so this operation can take some time.

The following animation shows the Ā character being included and excluded from the Font Range, causing it to appear and disappear in the displayed text.

Note that expanding the character set results in larger font PNG files which can impact the size and performance of games using the Gum files.

Introduction

The Inheritance Location options allow you to control where inheritance is specified in generated code (custom or generated code).

Custom and Generated Code

When an element is selected, its generated code is displayed in the Gum tool. If automatic or manual saving of generated code is enabled, then this generated code is saved to disk at the desired location. When generated code is saved, it is saved with the Runtime.Generated.cs suffix. An accompanying custom code file is also saved in the same folder. This custom code is generated initially, but after that it is not re-generated by Gum. This pair of files allows Gum to continue to update the .Generated.cs file without overwriting custom code.

The Inheritance Location option controls whether inheritance is added to custom or generated code. In most cases it's desirable to keep inheritance in generated code; however, some environments (such as .NET Maui) may benefit from writing inheritance in custom code.

Clear Font Cache

Clear Font Cache deletes all of the font cache files (.png and .fnt) from the font cache for the particular project.

Introduction

The Stack Spacing variable controls the additional padding between children when a container uses a Children Layout of either Top to Bottom Stack or Left to Right Stack. Stack Spacing serves as an alternative to adjusting the position of each item in a stack.

Setting Stack Spacing

A larger Stack Spacing value increases the spacing between each child. By default Stack Spacing is set to 0 which means that no spacing is added between items in a stack.

Changing the stack spacing adds gaps between each child as shown in the following animation.

Stack Spacing can also be a negative value resulting in overlapping children. The items in the following animation are partially transparent to show the overlap.

Stack Spacing and Stacking Direction