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, but we can assign each value individually so an object is centered vertically:

• Set Y to 0

• Set Y Units to Pixels from Center

• Set Y Origin to Center

Centering with Margins

Centering can be performed with margins by adding an additional container to 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 Parent (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:

Additional 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)

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.

Items in a bottom-up stack need a parent Container. This Container could be an instance of a Container or a component since components usually have their Base Type set to Container. For this example we'll use a container.

This container to stack needs the following variables set:

• 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 effective height of the container is based purely on its children
• Stack Spacing set to 2 (optional) to add spacing between each child

Now children of the Container stack vertically. This concept works for any type of child, but we'll use ColoredRectangles for this example. 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.

Introduction

Although Gum includes a standard NineSlice element, 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 element 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 could be achieved using the following variables individually:

• Width Units

• X Origin

• X Units

• Height Units

• Y Origin

• Y Units

To create the corner Sprites:

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

1. Click the Alignment tab

2. Anchor the newly-created Sprite to the top-left of its container
3. Repeat the steps above three more times, creating one Sprite for each of the four corners, anchoring each one to their respective corner

Notice if we resize our CustomNineSlice component, each of the four Sprites remains in its respective corner.

Adding Edge Sprites

Next we'll add the four Sprites which will sit on the edges 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 Relative to Parent, setting the value to -128 makes the Sprite 128 units smaller than its parent. 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

Finall we'll add 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 assignment. 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.

Introduction

Health bars are common UI elements in games. They are similar to progress bars, so this example could be used to create either. This example explains how to create a health bar component.

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 Width to 200 and Height to 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 in our HealthBar

Creating an Inner Container

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

1. Drag+drop a Container onto the HealthBar

2. Select the Alignment tab

3. Enter a Margin value of 4

4. Click the Fill Dock button

Now we have a ContainerInstance with the proper margin

Adding the Foreground Rectangle

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

1. Drag+drop another ColoredRectangle onto the ContainerInstance. Be sure to drop it on ContainerInstance so that the newly-added ColoredRectangle is a child of the container

2. Click the Alignment tab

3. Set Margin back to 0

4. Click the Fill Dock button

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

Expose Width

Next we'll expose the inner ColoredRectangle's Width property so it can be assigned per HealthBar instance:

1. Select the inner ColoredRectangle instance

2. Right-click on its Width variable and select Expose Variable
3. Enter an appropriate name such as "Percentage" and click OK

Now we can add instances of the HealthBar to a screen and control its fill percentage.