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 ColoredRectangleInstance and TextInstance are both white you may not be able to see the Text. Let's change the ColoredRectangleInstance's color:

1. Select ColoredRectangleInstance

2. Change Red to 0

3. Change Green to 0

4. Keep Blue as 255

Notice that as you change the values, the background on the text box changes from green to white to indicate that the value has an explicit value. The Blue text box keeps a green value since it has not been changed from its default value.

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

Sizing the colored rectangle

At this point we have made some progress towards creating our first button, but it still needs some work.

First, we're going to adjust the size of the instances inside of our Button component. At this point you can see that the ColoredRectangle (the blue background) is not the same size as the button. Not only do we want to make the blue ColoredRectangle 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. Keep in mind that using the Alignment tab is the fastest way to get your instances setup. The next section shows all of the changes that the Alignment tab performs for you:

1. Select the ColoredRectangleInstance

2. Change Height Units to Relative To Parent

3. Change Width Units to Relative to Parent

4. Change Height to 0. This means that the actual height of the ColoredRectangleInstance matches the actual height of its container (the Button Component). Since Height Units is set to Relative To Parent.

5. Change Width to 0. This means that the actual width of the ColoredRectangleInstance matches the actual width of its parent.

Now the ColoredRectangleInstance automatically matches the Button's actual with and height:

Next we'll position the TextInstance. 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 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 Horizontal Alignment to Center

3. Change its Vertical Alignment 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 Parent

3. Change Width to -40. This means the actual width of the Text is 40 pixels less than the actual 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 Variables

Buttons are typically wider than they are tall. To match this common layout, let's set some variables 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.

Creating Component 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

We can now resize and position the Button instance. We can reuse our Button component to create multiple instances. Each instance can be adjusted by changing its X, Y, Width, and Height values.

We can change top level variables on the Button such as X, Y, Width, and Height, but we cannot change variables on instances within the Button - all of our buttons currently display "Hello" text.

The next tutorial shows how to use exposed variables to further customize each button instance.

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.

Introduction

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

Recap

The last tutorial created a Button component with Text and ColoredRectangle instances. The instances 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 a Button only exposes its top level variables. Variables on instances inside the button are not available outside of the button. In programming terms these variables are considered protected.

However, we can expose variables on instances 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 variable is exposed by clicking on the 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 changed on each Button 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.

Conclusion

This tutorial shows how to expose Text values per-instance. You can expose other instance variables in your components to customize instances. Other examples of variables which may be exposed include:

• Visibility of icons on a Button component

• Font sizes on a Label component

• Sprite visibility showing the number of connected gamepads on a JoinGame component

• Width (percentage) on a HealthBar component

It's best to experiment with exposed variables to get a feel for how you can use them in your own components.

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.

For example you can think of screens in a video game which might 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. Click OK. 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

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. If you haven't yet, you should read through the earlier tutorials to create a Button component.

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 with 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 when the changes were made - 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 variables. This topic is covered in more detail in the next tutorial.

Introduction

Gum supports loading image files for Sprites and NineSlices. This tutorial discusses how to load files, and how they are referenced in Gum.

Setting up a workspace

First we'll set up a workspace:

1. Create a Screen called SpriteScreen.

2. Drag+drop a Sprite into the newly-created Screen

Setting the Sprite Source File

The Source File property is the image that the Sprite displays. Usually Source Files are of the .png file format. To set the source file:

1. Select SpriteInstance

2. Find Source File in the Variables tab

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

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

5. Click "Open" in the file window

6. Once Source File is set, the Sprite displays the image in the Editor tab

If you select a file which is not located in the same folder or a sub folder of your gum project, Gum asks if you would like to reference the file in its original location or create a copy.

Usually it's best to copy the file to the Gum project folder so that the Gum project can be moved to different computers without breaking file references.

Texture Coordinates

Sprites can display portions of their Source File. Files which combine multiple images are often called sprite sheets or tile sheets, and are commonly used in game development to keep art organized and to improve performance.

For example, the following file contains images for an animated character, ground tiles, and other entities for a platformer game.

If we download this file and set it as our , then the sprite displays the entire file.

We can display a portion of the Sprite rather than the entire file:

1. Click on the Texture Coordinates tab

2. Check the Snap to grid option to make it easier to select a region

3. Double-click anywhere on the image to select a region around the cursor

4. Move the selected region to the desired location to adjust the sprite's texture coordinate values

Introduction

The Gum Variables tab displays all available variables when editing an instance or element. While the Editor tab 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 by changing values on the selected variable. For example, to move the text to the right, change its X value to a positive number. Press Enter or Tab to apply the changes:

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:

You may need to pan the view in the Editor tab 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 and Y Units is set to Pixels From Top.

Changing the X Units to Pixels From Right causes the Text to be positioned on the right-side of the screen.

Text Alignment

The X,Y, Origin, 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. 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 in action, select the Text item under the Standard folder. Notice that all values have a white background. Keep in mind the 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 Vertical Alignment is 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

The Components tutorial shows how Text and ColoredRectangle instances can be sized and positioned according to the Button that they are a part of. Instances can use other instances as their parents. Gum does not place a limit to the depth of the parent/child hierarchy, enabling flexible and responsive layouts through.

Parent/child relationships are useful for

• Automatically adjusting margins and backgrounds

• Word-wrapping text relative to a parent

• 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 Component for displaying distance. This component has two Text instances:

• ValueText - the Text instance responsible for displaying the value for the distance. For example "100".

• UnitsDisplay - the Text instance responsible for displaying the units for the distance. For example "km" for kilometers.

The two Text instances will have different colors so that ValueText stands out.

To create our component:

1. Create a new component named 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 instance

2. Change its Parent to ValueText

3. Change its X Units to Pixels From Right. This makes the text object positioned according to its parent's right edge

4. Change its X to 10 . This means the UnitsDisplay text is 10 units offset from the right edge of its parent ValueText

5. Verify its Y is 0

The ValueText actual width should be based on its contents, so we'll do the following:

1. Select ValueText

2. Change Width Units to Relative to Children

3. Change Width to 0

By setting these values, ValueText is now sized according to its children, which in this case are its letters.

You may have noticed that UnitsDisplay is also a child of the ValueText. However, since UnitsDisplay is explicitly positioned outside of the bounds of its parent ValueText, then ValueText ignores this child when calculating its own Width. For a detailed discussion of Width Units and whether children are ignored, see the Width Units page.

Adjusting Colors

Now that we have adjusted the position, size, and parent values on our Text instances, 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 that we have set up a parent/child relationship between ValueText and UnitsDisplay, UnitsDisplay automatically adjusts its position in response to changes in ValueText. Any change on ValueText resulting in the right-side of the parent changing automatically adjusts the position of UnitsDisplay.

For example, if we change the Text property on ValueText, it grows or shrinks in response.

Width and Effective Width

As mentioned above, changing the Text property causes ValueText to grow or shrink. However, regardless of its size, the Width property is still set to 0.

The Width variable is used in combination with its Width Units to calculate an effective width. In this case, the effective width is determined by the Text property on ValueText. It's important to note that all Gum objects have effective values for x, y, width, and height, all of which are determined by their respective units values.

Children always depend on their parents' effective values rather than their explicitly set values. Gum helps us visualize the effective values when we mouse over one of the resize handles on the selected object. For example, the following image shows the Width, Width Units, and effective width values of our ValueText.

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 a Button component which displays a button callout.

This button might be a standard Button with the following states:

• Enabled

• Disabled

• Highlighted

• Pushed

But it may also have states for which button icon to display:

• A

• B

• X

• Y

• LeftStick

• RightStick

These two sets of states could be set independently and combined at runtime. Categories let you create groups of states so that multiple states can be set simultaneously.

Creating Categorized States

For this tutorial we'll create a new component. This component has 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, select the Default state and drag+drop a ColoredRectangle into your component

Setting Variables in States

To modify a state, you can select it and edit in the Editor tab 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, and 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 combine

We can revert the states back to their unset values by right-clicking on the state variable and selecting the Make Default item.

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, 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.