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

This is the root page for the usage guide. The usage guide will present how to use Gum to create UI. Note that this section does not discuss how to load this XML in custom engines, nor does it discuss how to create plugins for Gum.

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

The Variables tab in Gum displays all available variables when editing an instance. While the visual editor is very 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

ction

Components are objects which are created in Gum which can contain instances of other components and of standard objects. Examples of components include:

• Check boxes

• Buttons

• Popup Menus

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. 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 will automatically match 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. First let's center the Text:

1. Select the 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

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 will display 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

Note that through plugins the Standard list can be expanded. For example, Gum supports additional standard types through a Skia plugin.

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

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.

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 will select the Text item, so you need to re-select the destination (MainMenu).

3. Drag the Text item onto the preview window

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

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.

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:

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

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 where multiple options can be selected

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 will now have a new state called Highlighted:

Setting variables in states

Once a state is defined and selected, setting a variable will associate that variable with a given state. In other words, any variable that is set when the "Highlighted" state is selected will associate the variable with the Highlighted state.

For this example, we will 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 values that 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 will switch 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.