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

Behaviors can define requirements which can be reused 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.

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 and states. Any component which uses this behavior is required to have the same categories and states. States can be added and removed the same as when working with states in other elements. For more information, see the States page.

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

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 continues to use the behavior.

Introduction

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

Absolute

The following shows a child with 50 Absolute Height:

Relative to Container

Percentage of 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.

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.

Relative to Children

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.

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.

Percentage of Source File

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

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

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

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.

Drag+dropping onto a parent may set the Parent property to an instance inside of the parent's Component type sets its Default Child Container value. For more information see the Default Child Container page.

Example - Using the Dropdown

To set a parent/child relationship:

1. Select the child

2. Change the Parent property to the desired 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

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

Example

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

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:

Red = Components/Styles.PrimaryColor.Red
Green = Components/Styles.PrimaryColor.Green
Blue = Components/Styles.PrimaryColor.Blue

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:

Components/Styles.PrimaryColor.Red

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:

Components/Styles.PrimaryColor.Color

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

Red = Components/Styles.PrimaryColor.Red
Green = Components/Styles.PrimaryColor.Green
Blue = Components/Styles.PrimaryColor.Blue

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:

X = BlueRectangle.X

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.

Green = Components/Styles.PrimaryColor.Red

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

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 ColoredRectangle 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

Ratio of Container can be used to fill available space or to share available space with other objects using a ratio. It behaves similar to a Height Units of Ratio of Container, but operates horizontally rather than vertically.

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 Sprite type has an extra With Unit called Percentage of Source File, which sets the width of the Sprite according to the file that it is displaying. This is the default Width Unit for Sprites.

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 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 ColoredRectangle 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:

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 (X Origin and Y Origin).

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

The X Origin and Y Origin properties define the point of rotation for an object. For example, the following shows a rectangle rotated about its center:

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.

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

PixelsFromCenterYInverted

PixelsFromBottom

PercentageHeight

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

PixelsFromRight

PercentageWidth

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

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

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 Y property controls the vertical position for an object. The Y 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.

Introduction

The Wrap value controls whether the sprite will wrap its image when rendering portions beyond the image location. If this value is true then wrapping will occur. Otherwise, areas beyond the texture will extend the last pixel - also known as "clamping" the value.

The Wrap variable applies when dealing with a Texture Address of Custom or DimensionsBased.

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: http://www.angelcode.com/products/bmfont/

• Scaling independent of source font

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.

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

Stack Spacing can be used for either Top to Bottom or Left to Right Stacking.

Stack Spacing and Wrapping

Stack Spacing can be used on container instances which stack and wrap their children. As stack spacing increases, the amount of space allocated to each object also increases, resulting in wrapping occurring earlier.

If wrapping occurs, then stack spacing applies spacing between rows and columns as shown the following animation:

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.

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

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

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

NineSlice Properties

• NineSlice.Texture Address

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 will draw its full image. The sprite will not repeat this texture or render only part of the texture.

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 will adjust internally according to the width and the height of the Sprite. In other words, making the sprite larger or smaller will not stretch the image that it is rendering. Instead the image will be clipped, or clamped/wrapped according to the Wrap property.

Wrap

Combining the DimensionsBased texture address with the wrap property will let you easily create tiling sprites.

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

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:

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/

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 .

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 Font variable sets the font family used by the text.

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

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.

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 Color page.

Introduction

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

For a tutorial on working with categories, see the State Categories Tutorial

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 Accross 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 varible 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

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.

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

Gum natively supports referencing Animation Chain XML files (.achx) which are created by the FlatRedBall AnimationEditor. For more information on creating .achx files, see the FlatRedBall AnimationEditor page.

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

Sprites can also reference images without extensions, such as urls from https://picsum.photos/

Introduction

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

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

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 Text Overflow Vertical Mode 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

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:

This is [Color=Orange][IsBold=true]bold and orange[/Color][/IsBold] text.

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

This [Color=Orange]is orange, [IsBold=true]bold[/IsBold], and [IsItalic=true]italic[/IsItalic][/Color] text.    

Introduction

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

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

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

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.