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.
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.
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 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
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.
First we'll define the component:
Open Gum
Open or create a new Gum project
Right-click on the Components folder
Name the component HealthBar
Resize the HealthBar component so it is wider than it is tall. For example, assign a Width of 200 and Height 32.
Next we'll add a background to our HealthBar Component
Drag+drop a ColoredRectangle into the HealthBar
Select the newly-created ColoredRectangleInstance
Select the Alignment tab
Click the Fill Dock button
Change the ColoredRectangleInstance color to black
Now we have a black background to our HealthBar
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:
Drag+drop a Container onto the HealthBar
Select the Alignment tab
Click the Fill Dock button
Change Width and Height to -8 to provide a 4 pixel margin on each side.
Finally we'll add the foreground rectangle which displays the health:
Drag+drop another ColoredRectangle onto the ContainerInstance
Click the Alignment tab
Click the Fill Dock button
Change the following values:
X Units to Pixels from Left
X Origin to Left
Width to Percentage of Container
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.
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.
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.
As implied by the name, the NineSlice object is composed of nine Sprites. First we'll create the component:
Open Gum
Open or create a new Gum project
Right-click on the Components folder
Select Add Component
Name the Component CustomNineSlice
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.
Next we'll add the four sprites which will sit on the edge of our component:
Drag+drop a Sprite element onto the CustomNineSlice component
Click on the alignment tab
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.
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.
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.
The last Sprite we'll add is the center Sprite:
Drag+drop a Sprite element onto the CustomNineSlice component
Click on the alignment tab
Dock the newly-created Sprite to the center of its container.
Set both the newly created Sprite's Width and Height to -128
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.
Anchor the newly-created Sprite to the top-left of its container
Now the Sprites will stretch and adjust whenever the CustomNineSlice is resized.
