Introduction

Alpha controls an instance's transparency. A fully opaque instance has an Alpha of 255. A fully transparent instance has an Alpha of 0.

An object's transparency is a combination of its Alpha, Blend, and its Source File. Skia elements may also have transparent portions due to their shape (such as ColoredCircle and RoundedRectangle) as well as dropshadows.

Alpha and Children

By default the Alpha property affects the selected instance only - it does not cascade down to its children. For example, the following shows a parent white ColoredRectangle with a child blue ColoredRectangle. If the white ColoredRectangle's Alpha property changes, the BlueRectangle's opacity does not change.

A parent can affect its children's transparency if the parent is a container with Is Render Target set to true. For example, if the white rectangle is added to a Container, the Container can make its entire contents transparent.

Note that by setting Is Render Target to true, the entire container's Alpha can be adjusted rather rather than the alpha value cascading to each individual child. This Alpha value is used to control transparency after all children have been drawn. We can see the difference between a partially-transparent Container and each child individually being made partially transparent by overlapping two children ColoredRectangles.

The rectangles on the left each have an Alpha value of 255. These rectangles are in a Container Is Render Target set to true and an Alpha set to 128.

The rectangles on the right each have an Alpha of 128, so the red rectangle is visible behind the blue rectangle.

Introduction

General properties are shared by all types of components.

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 are not clipped (can fully-render) regardless of whether they are within the bounds of their parent or not. Setting this value to true prevents children from rendering outside of the bounds of their parent.

Introduction

The Base Type variable can be used to specify both inheritance but also the type of an instance.

Base Type on an instance indicates its type. This is usually automatically set when an instance is first created - usually by drag+dropping a component or standard element onto its target component or screen.

Gum Screens and Components support changing Base Type to specify inheritance. By setting Base Type, a screen or component automatically inherits the following:

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

Instance Base Type

All instances must have a Base Type set. For example, the following instance is of type Container.

Base Type is automatically assigned when a new instance is created. For example, the following animation shows a new ColoredRectangle instance created. Note that its Base Type is automatically assigned to ColoredRectangle.

Base Type can be changed after an instance is created. Keep in mind that doing so does not change its name or any other properties, so you may need to manually adjust properties when converting between different Base Types. Also, note that default values may change when switching from one Base Type to another.

The following shows a ColoredRectangle changed to a Container. Since Container and ColoredRectangle have different default Width and Height values, changing Base Type results in changes to default size too.

Component Inheritance

All components use inheritance even if their 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 Container 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 from its base component.

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

• 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. Children can be made invisible.

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.

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

Introduction

The Blend variable controls how the selected instance combines its colors with whatever is drawn before. The final appearance depends on its Blend, Alpha, Source File, and Color values.

Blend is available on the following types:

• ColoredRectangle

• Container (if Is Render Target is set to true)

• NineSlice

• Sprite

Blend is also available on all Skia elements:

• Arc

• ColoredCircle

• LottieAnimation

• RoundedRectangle

• Svg

Most examples on this page overlay a Sprite over ColoredRectangles, but the same Blend behavior applies to all items which support the Blend variable.

Normal Blend

Normal Blend is the default value. When an instance uses Normal Blend, it interpolates its color with whatever it draws on top of using its Alpha value as a weight.

If a Normal Blend Sprite has an Alpha of 255, then the Sprite completely replaces whatever is below.

If a Sprite has an Alpha of 128 (roughly half of 255), then it averages its color with whatever is below.

A Sprite with an Alpha of 25 (roughly 10%) blends with whatever is below, but its color is given a weight of roughly 10%.

Additive Blend

Additive Blend results in the color of a element being added to whatever is below. This typically results in brighter colors. Additive Blend can be used to simulate a light.

Since Additive Blend results in a modification of what is under instead of a replacement, an Additive Blend Sprite typically appear transparent even when Alpha is 255.

As Alpha is reduced, the brightening effect is reduced. A Sprite with an Alpha of 128 only applies roughly half as much of a brightening effect.

A Sprite with an Alpha of 25 applies a slight brightening effect.

Stacking multiple Sprites with Additive Blend results in the brightening effect stacking as well.

Replace Blend

Replace Blend results in the instance completely replacing whatever it is drawn on top of regardless of its Alpha or transparency in the source file.

A Sprite with no transparency in its source file drawn with Alpha of 255 looks the same whether it uses Replace or Normal Blend.

Changing the Alpha on a Sprite with Replace Blend does not affect how it is drawn - it is always drawn at full opacity.

Replace Blend results in a Sprite being fully opaque even if its source file has transparency. The following image shows two Sprites displaying the same image.

Alpha-Only Blends

Gum supports Blend modes which modify the alpha (opacity) of whatever is under the instance using the alpha-only Blend . Alpha-only Blend modes ignore the color of the instance using the Blend - only the alpha matters. Therefore, the following three circles would behave the same despite having different colors:

Since alpha-only blends operate directly on the alpha of whatever is below, they are only intended to be used on Containers with Is Render Target set to true. Usually objects with these blend modes are drawn on top of all other items in the container. For example, the following image shows a RenderTargetContainer which holds a number of items including the AlphaOnlyCircle. AlphaOnlyCircle is an instance which can be used to apply Alpha-only Blends to whatever is below.

Using an alpha-only Blend outside of a container with Is Render Target set to true typically results in the instance either being drawn as pure black or being invisible.

Subtract Alpha Blend

Subtract Alpha Blend subtracts, or "cuts out", the alpha of whatever is below.

As Alpha is reduced, the amount of opacity removed effect is also reduced. A Sprite with an Alpha of 128 only removes roughly half as much opacity from what is below.

Replace Alpha Blend

Replace Alpha forcefully sets the opacity of whatever is below. Rather than subtracting alpha, replace can forcefully set the alpha.

Replace Alpha with an Alpha value of 255 results in no changes if what is under is already opaque, but it can add alpha if what is under is transparent.

If Alpha is reduced, then the resulting pixels display the explicitly set alpha. The following shows setting alpha explicitly to 128 (about 50%).

Setting Alpha to 0 forcefully sets whatever is under to fully transparent. This is similar to performing Subtract Alpha with an Alpha of 255.

Keep in mind that Replace Alpha can apply different alpha values if the instance itself has variable alpha, such as a Sprite with some parts transparent and some parts opaque.

Min Alpha

Min Alpha modifies the underlying object so that the result is the minimum alpha between the instance and what is below. This can be used to create an alpha mask.

If the instance alpha is reduced, then the resulting transparency is reduced as well. The following shows setting Alpha to 128 (about 50%).

Keep in mind that multiple objects can be combined to create larger masks. For example, additional ColoredRectangles can be added to the circle above to create a larger mask. Each rectangle also has its Blend set to Min Alpha.

Introduction

The Locked property controls whether an instance can be clicked in the preview window. If this value is true, then the instance cannot be clicked on directly, but must instead be selected through the Project tab.

Once a locked object is selected it can still be edited normally, both in the Variables tab and in the Editor tab. Locking an instance prevents accidental selection in the Editor tab.

Introduction

The Parent variable 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.

Parents and Units

Parents control control the position of their children. Parents can also control the size of their objects depending on the child's Width Units and Height Units.

For example, if a parent is moved, its children move along with it. For more information on positioning children, see the X Units and Y Units pages.

Children can also be sized according to their parents. For more information on sizing children according to their parent, see the Width Units and Height Units pages.

Children Outside of Parent Bounds

Children can be placed outside of their parent's bounds. In the simplest case, a child can be dragged outside of its parent's bounds in the editor.

Children outside of their parent's bounds still follow all of the same rules for sizing and positioning, but there are some important things to keep in mind.

Children placed outside of a parent do not affect the parent's effective width or height. Any unit value that depends on children or parents only considers the immediate child or parent and does not look at sizes beyond the immediate relationship.

For example if a parent has 100 effective width, and its child is given an X of 200, the parent's effective width remains 100 (assuming the parent does not size itself according to its children). This is important when other children are sized or positioned according to the parent's width.

The following animation shows three instances:

1. A parent container

2. A blue rectangle which is sized according to the parent rectangle

3. A yellow rectangle which is moved outside of the bounds of its parent

Notice that when the parent resizes the blue rectangle is also resized, but when the yellow rectangle is moved outside of the parent bounds, the parent and blue rectangle are not resized.

Children outside of bounds may not respond to click events unless the parent is explicitly checking for click events outside of its bounds. This is a property which is set at runtime. For more information see the RaiseChildrenEventsOutsideOfBounds page.

Example - Drag+Drop in the Tree View

To change Parent in the Project tab:

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 Parent by name:

1. Select the desired child

2. Change the Parent property to the desired parent:

Introduction

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

Absolute

The following shows a child ColoredRectangle with 50 Absolute Height:

Relative to Parent

The following shows a child ColoredRectangle with -10 Relative to Parent Height, which means is sized 10 pixels less tall than its parent.

Percentage of Parent

The following shows a child ColoredRectangle with 100 Percentage of Parent, which means it has 100% of the height of its parent. Note that 100 Percentage is the same as 0 Relative to Parent:

Ratio of Parent

Ratio of Parent 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 Parent.

In this case the blue ColoredRectangle has no siblings (its parent has no other children), so it occupies the entire parent height. If a second child is added (by copy/pasting the existing child), then each child is given 1 ratio value, which means each is 1/2 of the size of the entire parent.

To better visualize the effect of ratio, it's common to set the parent's Children Layout to Top to Bottom Stack, and to give each child a different color as shown in the following image.

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 Parent 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 parent's height, while each of the others is given 1/6 of the parent's height.

Values of 0 are supported, resulting in the object drawing with an absolute height of 0.

Ratio of Parent 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 of Parent units. Therefore, if a sibling is invisible, Gum treats it as if it has 0 height which allows all other ratio siblings to expand.

Ratio of Parent also respects Stack Spacing. A Stack Spacing value greater than 0 removes the available space for all children with a Height Units of Relative to Parent.

Relative to Children

The following image shows a child ColoredRectangle with 50 Relative to Children Height, which means that it is 50 pixels taller than is necessary to contain its children. Since the rectangle has no children, this is the same as having 50 Absolute Height:

Relative to Children can be used to size an object based on the position and sizes of a parent's children. The following image shows a container with 0 Relative to Children Height, which means that its height is set just large enough to contain its children. Notice that if the children are moved, the parent'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 Relative to Children can be used to add additional padding to a parent container. The following animation shows how changing the height can adjust the absolute height relative to children:

Ignored Height Values

A parent container can ignore its children when it determines its own height when using a Height Units of Relative to Children if any of the following are true:

1. The child's Ignored By Parent Size is true.

2. The child's height depends on its parent's height. This circular dependency is resolved by the parent ignoring this child.

3. The child is explicitly positioned outside of parent's bounds

4. The child's Y Units is Percentage of Parent Height

Child's Ignored By Parent Size is True (1)

If a child has its Ignored By Parent Size set to true, then the parent ignores this child when calculating its own size. For more information, see the Ignored By Parent Size page.

Child Depends on Parent Height (2)

If a child's height depends on the parent, then the child is ignored by the parent. Once the parent has determined its own height, then the child is sized according to the parent. This type of circular dependency is common when adding background visuals to a container.

For example consider a container with two children - BlueRectangle and YellowRectangle - with the following variables:

• BlueRectangle Y = Pixels from Top

• BlueRectangle Height Units = Absolute

• YellowRectangle Height Units = Relative to Parent

Only YellowRectangle depends on its parent.

Since BlueRectangle's absolute height value does not depend on the parent, the parent can use BlueRectangle's absolute height when calculating its own absolute height. Since YellowRectangle depends on the parent, the parent ignores the YellowRectangle. Instead, YellowRectangle depends on the parent container's absolute height for calculating its own absolute height. This in effect creates a situation where BlueRectangle affects the height of both its parent and also its YellowRectangle sibling.

Child Explicitly Positioned Outside of Parent's Bounds (3)

A parent does not consider a child if the child is explicitly positioned outside of the parent's bounds. This can happen if the child's Y Units and Y values result in the child being drawn outside of the parent's bounds.

If a child has Y Units of Pixels from Top and its Y value pushes the child out of the top of its parent, then the portion that is outside of the top of the parent is ignored. The BlueRectangle in the following image has an absolute height of 50. Its Y value is -20, so only 30 pixels are used to determine the parent's height.

Similarly, if a child uses a Y Units of Pixels from Bottom then the parent does not consider the height of any portion which is outside of its bounds. The following animation shows RedRectangle placed outside of the bottom of its bounds with a Y Units of Pixels from Bottom.

Notice that if RedRectangle is moved so that it is inside the bounds, it can affect the absolute height of the parent. As RedRectangle is moved into the bounds, the parent grows to accommodate the desired RedRectangle Y value.

If a child is a Text instance using a Y Origin of Baseline and a Y Units of Pixels from Bottom, then portions of the text which fall below the baseline are ignored by the parent's height.

Child Y Units is Percentage of Parent Height (4)

A parent ignores its child if the child uses a Y Units of Percentage of Parent Height because this also creates a circular dependency (parent height depends on child position, child position depends on parent height).

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 Relative To Children. As more lines of text are added, the Text automatically expands in size.

The height of a Text instance using Relative to Children depends on the number of lines displayed by the Text instance and the maximum line height given the current font properties. Therefore, the height of a Text stance remains the same regardless of the contents of a single line.

For example, the following image contains multiple Text instances. Each has a single line of text, but the line of text differs in the height of each character. Notice that the texts are all the same height even though the contents of their lines differ.

We can observe the absolute height of a Text instance by mousing over one of the handles for resizing vertically.

In this case, the height is 41 pixels tall. This is based on the lineHeight as defined on the .fnt file. The image above is using an Arial 36 font which has a lineHeight value of 41 pixels.

Percentage of Width

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

The following image shows a child ColoredRectangle with a Height of 200 Percentage of Other Dimension. In this image, the Width value is 50 units, so the effective height is 100 units:

Percentage of File Height

Sprites can select a Height Units called Percentage of File Height, which sets the height of the Sprite according to the file that it is displaying. This is the default Height Units for Sprites.

The following image shows a child Sprite with 200 Percentage of Source File Height, which means it draws two times as tall as its source image:

This value depends on the Sprite's Texture Height property, so changing Texture Height also changes the Sprite's absolute height.

Maintain File Aspect Ratio Height

Sprites can select a Height Unit called Maintain File Aspect Ratio Height which sets the height of the sprite so its aspect ratio matches its source file multiplied by the Height value. Usually Maintain File Aspect Ratio Height is used with a Height value of 100 so that the Sprite shows is source file at the correct aspect ratio.

When this value is used, a Sprite's Width can be changed resulting in its absolute height also changing.

When using Maintain File Aspect Ratio Height, the Sprite's absolute height depends on the Sprite's Texture Height property.

Introduction

Ignored By Parent Size determines whether the parent of an instance considers the instance when performing its sizing. This value is only used if the parent has a Height Units or Width Units of Relative To Children. If a parent has a Height Units or Width Units of any other value, then this value has no impact on the parent's size.

Introduction

Children in a Screen, Component, or parent instance are drawn top-to-bottom, so that children further down are drawn on top.

Changing Order

Gum provides a number of ways to reorder instances.

Items can be right-clicked in the editor to change their order.

• Bring to Front - reorders the instance so that it is in front of all of its siblings.

• Move Forward - moves the instance in front of the sibling that is in front of it. In other words, moves the item forward by one index.

• Move In Front Of - moves the instance in front of the selected sibling.

• Move Backward - moves the instance behind the sibling that is currently behind it. In other words, moves the item backwards by one index.

• Send to Back - reorders the instance so that it is behind all of its siblings.

Items can be re-ordered in the Project tree view by holding the alt key and pressing up or down.

Parent and Children Ordering

Gum uses a hierarchical ordering which means that a parent and all of its children draw before any of the siblings of the parent. For example, a container and all of its children draw before any other siblings of the container.

The following animation shows a container named ContainerInstance2 which draws on top of ContainerInstance1. All children of ContainerInstance2 also draw on top of children of ContainerInstance1.

If a parent is reordered, then all of its children also respect the new order. For example, if ContainerInstance2 is sent to the back, then all of its children draw below ContainerInstance1 and its children.

Order and Stacking / Grid

If a parent uses a stack or grid layout for its Children Layout variable, then the order of the children in the Project tab determines their order in the stack or grid.

For more information, see the Children Layout page.

Introduction

Rotation can be used to rotate Gum components. Rotation is measured in degrees, where positive values rotate an object counterclockwise about its origin (X Origin and Y Origin).

Example

An object is rotated about its origin, which by default is its top-left corner:

Objects can also be rotated visually by grabbing the rotation handle:

Holding the SHIFT key snaps angles to 15 degree increments.

X Origin and Y Origin

The X Origin and Y Origin properties define the point of rotation for an object. The following animation shows how changing origin values can affect rotation.

Introduction

Variable References allows any variable on an instance or component to reference other variables. These other variables can be on the same instance or component, a different instance, or even variables from a different component.

One 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. For example, the reference Height = Width results in Height being read-only and depending on Width. Note that this is using a shorthand variable assignment which is discussed in later sections.

Variable Reference Syntax

Variable References can contain multiple lines. Each line is a separate variable reference. Each variable reference uses the following syntax:

{Variable} = {Components or Screens}/{ComponentOrScreenName}.{Instance}.{Variable}

For example, to assign a Component's X value to a different component's X value, the following syntax could be used:

X = Components/OtherComponent.X

Variable Assignment Reference

X references the X value in OtherComponent. Note that X could be the X value on any component or any instance inside of a component:

X = Components/OtherComponent.X

Spaces are optional around the equals sign, but spaces are not allowed in variable names. The following lines are okay:

Y=Components/OtherComponent.Y
Width = Components/OtherComponent.Width

However, the following is not allowed:

// Spaces are not allowed, so Gum would comment this reference:
X Units = Components/OtherComponent.X Units

Lines can be commented out to disable the reference. If Gum encounters a scripting error, it will automatically comment out lines as well so that you can make corrections:

// This is considered a comment so it will not run
// Neither will this:
// X = Components/OtherComponent.Y

An Instance can reference its own Component's X value by using the qualified name:

X = Components/ComponentContainingThisInstance.X

An instance or component can reference the variable of another instance in the same component by using the name of the instance. The name of the containing component or screen is not required if the instances are both in the same component or screen:

Width = OtherInstanceInSameComponent.Width

Components and instances can reference variables that are contained within instances of other components. In this case the name of the referenced instance is appended to the qualified name of the Screen or Component:

Red = Components/StyleComponent.PrimaryColorRectangle.Red

Elements and Screens inside subfolders can be referenced. The subfolder path is included with forward slashes:

XUnits = Components/ComponentFolder/ComponentInFolder.XUnits

The right side can be a variable in a Screen, although this isn't too common in practice:

Green = Screens/MainMenuGum.ColoredRectangleInstance.Green

Similarly, variables on Standards can also be referenced. This is also quite rare, since this modifying the Standard element also has side effects on every other instance that is of the same type:

YUnits = Standards/Text.YUnits

Although it's common for variables to reference the same variable on a different object (such as X being set to another object's X value), this is not a requirement. For example, the following lines are valid:

Y = OtherInstance.X
Width = Components/OtherComponent.Height

Instances can reference their own variables, but these must be qualified. For example, ColoredRectangleInstance can assign its Width to equal its own Height. Note that Gum will extend shorthand code as shown in a later section:

Width = ColoredRectangleInstance.Height

Variables can be assigned to constant values, essentially locking the value:

X = 100
Text = "Hello"
Visible = true

Math operations can be used in variable assignments. This includes add, subtract, multiply, divide, and parenthesis to control order of operations:

// This evaluates to 17
Y = (1 + 2) * 7 - 4

Math operations can reference both constant values (1, 2, 3) or other variables:

Width = (OtherInstance.Height * 3) + 10

// This is a direct assignment:
X = Components/OtherComponent.X
// This is a division operation:
X = CustomVariable/OtherComponent/X

Numeric variable types can be mixed. For example, Red is typically an int value (whole number), while X is a float (supports decimals). Gum automatically casts the variable appropriately:

X = ColoredRectangleInstance.Red
Green = ColoredRectangleInstance.Y

Gum automatically casts any value to a string (text). For example, a Text's Text variable could be assigned to its own Y value:

Text=TextInstance.Y

Strings can be concatenated (combined) using the + operator:

Text="My Position is " + TextInstance.X + ", " + TextInstance.Y

Gum cannot convert unrelated types, including different Units. For example, the following would be commented out by Gum:

//WidthUnits = TextInstance.HeightUnits

Referencing Custom Variables

Variable references can include custom variables, both on the left and right side. Custom variables can be combined with variable references to create flexible layouts. For more information on using custom variables, see the Add Variables page.

Unqualified and Shorthand Assignments

As mentioned above, fully qualified assignments are allowed in any context. For example, a component can reference its own qualified variables:

X = Components/SameComponent.Y

Components do not need to qualify their own variables. They can reference them without any qualification. Therefore, the following variable reference is equivalent to the fully-qualified reference above:

X = Y

Similarly, the following two variable references are equivalent assuming ContainedInstance is part of the component with the reference:

Y = Components/SameComponent.InstanceInComponent.Y
// is equivalent to:
Y = InstanceInComponent.Y

Instances must qualify their own variables as shown in the following code:

X = SameInstance.Y

Gum will automatically qualify assignments when an instance is selected. In other words, X = Y gets qualified to X = SameInstance.Y if SameInstance is the owner of the variable. This automatic qualification makes it easy for an instance to reference its own values. The following animation shows how the Y and Height values become qualified to the instance after tabbing out of the Variable Reference text box.

Complex assignments are automatically qualified as well.

The left side of an assignment can be omitted if referencing the same variable on another instance or component. For example, by typing OtherInstance.YUnits , Gum automatically expands the reference to YUnits = OtherInstance.YUnits .

Note that this only works when assigning one variable directly to another variable. Complex assignments will not be prefixed.

Color Expansion

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

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.

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.

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.

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.

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.

Pixels From Left

The following shows a child ColoredRectangle positioned 50 Pixels From Left relative to its parent:

Pixels From Center

The following shows a child ColoredRectangle positioned 50 Pixels From Center relative to its parent:

Pixels From Right

The following shows a child ColoredRectangle positioned 50 Pixels From Right relative to its Parent:

Percentage Parent Width

The following shows a child ColoredRectangle positioned 50 Percentage Parent Width relative to its Parent. In other words, it will be positioned halfway between the left and right edges of the Parent:

Introduction

The X Origin variable controls the point which an object is positioned by. By default the X Origin is Left. 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 Width Units variable controls how a unit is horizontally sized, which may be relative to its parent. By default elements uses Absolute width, where each unit represents 1 pixel of width in absolute terms. When using Absolute, an object ignores its parents' effective width.

Absolute

The following shows a child ColoredRectangle with 50 Absolute Width:

Relative to Parent

The following image shows a child ColoredRectangle with -10 Relative to Parent Width, so it sizes itself 10 pixels less wide than its parent.

If an instance does not have a parent, then it uses the canvas size when using a Width Units of Relative to Parent.

Percentage of Parent

The following shows a child ColoredRectangle with 100 Percentage of Parent Width, which means it has 100% of the effective width of its parent. Note that 100 Percentage of Parent is the same as 0 Relative to Parent:

If an object does not have a parent, then the width of the canvas is used.

Ratio of Parent

Ratio of Parent 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 Parent, but operates horizontally rather than vertically.

Ratio of Parent is usually used with a parent that has its Children Layout set to Left to Right Stack or Top to Bottom Stack. For more information, see the Children Layout page.

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 parent's children. The following animation shows a container with 0 Relative to Children Width, which means that its effective width is set just large enough to contain its children. Notice that if the children are moved, the parent's effective width adjusts. Both children are considered so the container adjusts its width according to the right-most side of either child:

A non-zero Width when using Relative to Children can be used to add additional padding to a parent container. The following animation shows how changing the Width variable can adjust the absolute width relative to children:

Relative to Children results in effective width dynamically adjusting in response to changes on a container's children. The following animation shows a container with Children Layout of Left to Right Stack. Adding additional children expands the container automatically:

Ignored Width Values

A parent container can ignore its children when it determines its absolute width when using a Width Units of Relative to Children if any of the following are true:

1. The child's Ignored By Parent Size is true.

2. The child's width depends on its parent's width. This circular dependency is resolved by the parent ignoring this child.

3. The child is explicitly positioned outside of the parent's bounds

4. The child's X Units is Percentage of Parent Width

Child's Ignored By Parent Size is True (1)

If a child has its Ignored By Parent Size set to true, then the parent ignores this child when calculating its own size. For more information, see the Ignored By Parent Size page.

Child Width Depends on its Parent's Width (2)

If a child's width depends on the parent, then the child is ignored by the parent. Once the parent has determined its own width, then the child is sized according to the parent. This type of circular dependency is common when adding background visuals to a container.

For example consider a container with two children - BlueRectangle and YellowRectangle - with the following variables:

• BlueRectangle X = Pixels from Left

• BlueRectangle Width Units = Absolute

• YellowRectangle Width Units = Relative to Parent

Only YellowRectangle depends on its parent.

Since BlueRectangle's absolute width value does not depend on the parent, the parent can use BlueRectangle's absolute width when calculating its own absolute width. Since YellowRectangle depends on the parent, the parent ignores the YellowRectangle. Instead, YellowRectangle depends on the parent container's absolute width for calculating its own absolute width. This in effect creates a situation where BlueRectangle affects the width of both its parent and also its YellowRectangle sibling.

Child is Explicitly Positioned Outside of Parent's Bounds (3)

A parent does not consider a child if the child is explicitly positioned outside of the parent's bounds. This can happen if the child's X Units and X values result in the child being drawn outside of the parent's bounds

If a child has X Units of Pixels from Left and its X value pushes the child out of the left of the parent, then the portion that is outside of the left of the parent is ignored. The BlueRectangle in the following image has an absolute width of 50. Its X value is -20, so only 30 pixels are used to determine the parent's effective height.

Similarly, if a child uses an X Units of Pixels from Right then the parent does not consider the width of any portion which is outside of its bounds. The following animation shows RedRectangle placed outside of the right of the container's bounds with a X Units of Pixels from Right.

Notice that if RedRectangle is moved so that it is inside the bounds, it can affect the absolute width of the parent. As RedRectangle is moved into the bounds, the parent grows to accommodate the desired RedRectangle X value.

Child's X Units is Percentage of Parent Width (4)

A parent ignores its child if the child uses an X Units of Percentage of Parent Width because this also creates a circular dependency (parent width depends on child position, child position depends on parent width).

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. In other words if a Text's Width Units is set to Relative To Children, then the words in the Text do not wrap.

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 Height

Percentage of Height adjusts the object's effective width so it remains proportional to the effective 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 Height. In this image, the Height value is 50 units, so the effective width is 100 units:

Percentage of File Width

Sprites can select a Width Unit called Percentage of File Width, 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:

When using Percentage of Source File Width, the Sprite's absolute width depends on the Sprite's Texture Width property.

For more information, see the Sprite Texture Address page.

Maintain File Aspect Ratio Width

Sprites can select a Width Unit called Maintain File Aspect Ratio Width, which sets the effective width of the Sprite so that its aspect ratio matches its source file multiplied by the Width value. Usually Maintain File Aspect Ratio Width is used with a Width value of 100 so that the Sprite shows is source file at the correct aspect ratio.

When this value is used, a Sprite's Height can be changed resulting in its absolute width also changing.

When using Maintain File Aspect Ratio Width, the Sprite's effective width depends on the Sprite's Texture Width property.

Absolute Multiplied by Font Scale

Absolute Multiplied by Font Scale is a value 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 Visible variable controls whether an object and its children appear.

Example

Setting Visible to false hides the selected instance.

Parent/Child Visibility

Setting a parent's Visible variable to false also hides all children. Note that this does not explicitly set the Visible property to false for all children, but a child's effective visibility depends on its parent.

Visibility and Stacking

If an instance is part of a parent which stacks its children (has a Children Layout of Left to Right Stack or Top to Bottom Stack), then it will no longer be considered when stacking siblings if it is invisible. In other words, making an item invisible removes it from the stack.

If the stack contains children which use a Width Units of Ratio, then hiding any of the siblings results in the children with ratio width adjusting to occupy the extra space.

Selecting Invisible Objects

An invisible object can be selected by clicking on it in the Project tab or in the Editor tab.

Visible items are given preferential selection even if they are ordered behind invisible items.

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.

Pixels From Top

The following image shows a child ColoredRectangle positioned 50 Pixels From Top relative to its parent:

Pixels From Center

The following image shows a child ColoredRectangle positioned 50 Pixels From Center relative to its parent:

Pixels From Bottom

The following image shows a child ColoredRectangle positioned 50 Pixels From Bottom relative to its parent:

Percentage Parent Height

The following image shows a child ColoredRectangle positioned 50 Percentage Parent Height relative to its parent:

Pixels From Baseline

Pixels From Baseline positions a child relative to the parent's baseline. If the parent is a Text instance, the baseline is the Y position of the bottom of letters which do not have descenders. For more information on the concept of text baseline, see the baseline Wikipedia page https://en.wikipedia.org/wiki/Baseline_(typography)

The following image shows a child ColoredRectangle positioned 0 pixels relative to a Text instance's baseline.

When using Pixels From Baseline, the position depends on the font size, baseline definition in the .fnt, and whether the text wraps. For example, changing the Width of the Text causes line wrapping which shifts the baseline.

A text instance's baseline is defined by its Font and Font Scale values. These values ultimately create a .fnt file with a base value indicating the distance from the top of the text instance to the baseline. For example, an Arial font with Font Size 40 has a base value of 36 and a lineHeight of 45.

This means that 36 pixels fall above the baseline, and 9 pixels (45 - 36) below.

Note that if the parent is not a Text instance, then the bottom of the parent is used as the baseline. The following image shows a Colored Rectangle using a Y Units of Pixels From Baseline with a Container parent.

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 ColoredRectangle with its Y Origin set to Top:

Center

The following image shows a ColoredRectangle with its Y Origin set to Center:

Bottom

The following image shows a ColoredRectangle with its Y Origin set to Bottom:

Baseline

The following shows a Text with its Y Origin set to Baseline:

Baseline refers to the bottom of the text for letters without descenders. For more information see the Wikipedia Baseline page.

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 Default Implementation property can be used to indicate which component is the default implementation for a behavior. This property does is not used by the Gum tool, but instead exists for runtime implementations (such as FlatRedBall) to decide which type of component to create when an instance of a behavior is requested.

This property may not be used by a particular runtime. For example, at the time of this writing the MonoGame runtime does not use this property.

Common Usage

Behaviors are often used to help with the creation of components which need to have a certain set of states and instances. For example, the Button type in Gum Forms uses a category named ButtonCategory containing multiple states such as Enabled and Disabled.

At runtime, a game may need to create an instance of the Button type without specifying the component associated with the Button forms type. The Default Implementation property can help runtime libraries (such as FlatRedBall) determine which component to create for the Button's visual.

The Button type is a good example of why this property might be needed because the default Forms components include multiple components which implement ButtonBehavior.

To resolve this ambiguity, the ButtonBehavior's Default Implementation is automatically set to Controls/ButtonStandard.

For more information about whether you should set the Default Implementation, refer to the documentation for your particular runtime.

Introduction

Behaviors can define requirements which are reusable across multiple components to standardize instance names and behaviors. If a component uses a behavior, then the component is forced to include categories and instances according to the behavior definition.

The most common usage of behaviors is the automatic creation and inclusion of Gum Forms behaviors.

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.

Common Behavior Usage

Behaviors are used to standardize state, category, and instance names. The most common usage of behaviors is with Gum Forms. Of course, behaviors can also be used to standardize names in your project for components which are not intended to be with Gum Forms.

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 is created, it can be given categories, states, and instances. Components which use this behavior are required to have matching categories and states.

The process of adding and removing states to behaviors is the same as adding and removing 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, drag+drop the behavior onto the component in the tree view.

Behaviors can also be added and removed on the component's Behaviors tab:

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.

If the behavior is selected in the Behaviors tab, the required states and categories are highlighted in the States tab.

These categories cannot be removed as long as the component uses the behavior.

Category and State Requirements

As mentioned above, if a component uses a behavior, then the component is required to include all of the states and categories defined by the behavior. If a behavior is added to a component, then all states and categories in the behavior are automatically added to the component. Keep in mind that newly-added states do not automatically assign any values. The behavior only requires that the states exist but it does not decide which variables are assigned by the states. These required states can even be left to their default so they have no affect on the component.

Required states and categories cannot be removed or renamed. Required states cannot be moved to different categories.

If a new category or state is added to a behavior, all components which use the behavior also have the new category or state added.

If a state or category is removed from a behavior, Gum does not remove the state or category from components which implement the behavior. Behaviors only define what is required, but they do not prevent components from defining additional states and categories. Also, the states on components may still be needed even if the behavior is removed. Therefore, if you remove any states or categories from a behavior, you may need to manually remove the same states and categories from components which use the behavior if these are no longer needed.

Instance Requirements

Behaviors can include instances, resulting in required instances existing in components which use the behavior. Instances in behaviors only include two properties:

• Name

• Base Type

Instances in behaviors only require that instances in components have these two matching properties. All other properties can be set to any value.

To add an instance to a behavior, drag+drop a standard element or component onto the behavior in the Project tab.

An instance can have its Name changed, Base Type changed, or removed.

If a component is missing a behavior then the Error window provides information about the missing requirement.

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.

Introduction

Circles are an outlined shape which can be used for visualizations or collision in games. Circles provide a color for their outline but they cannot be filled in.

Default Child Container specifies the default parent for children of the selected component.

By default this value is blank, which means that newly added children treat the entire component as their parent. If this value is set, children which are dropped on instances of this component type 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.

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

• Top to Bottom Stack containers control the Y value of their children.

• Left to Right Stack containers 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 stacks 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

The position of a child in a stack is determined by the size of the previous item in the stack and the origin of the child. In most cases children which are stacked should use a Left X Origin if the parent uses a Left To Right Stack and should use a Top Y Origin if the parent uses a Top To Bottom Stack.

Consider a container with a blue rectangle which stacks horizontally. The blue occupies some space according to its absolute width. The next instance after the blue rectangle is placed relative to the right-side of the blue rectangle.

For example, if a red rectangle (partially transparent to make it easier to see when overlapping) is added to the container, the stack may create a layout similar to the following image:

Keep in mind that the stack simply states the position of the next item. Each item can freely adjust its X Origin (or Y Origin in a Top to Bottom Stack). 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 aligns with the right side of the blue rectangle, resulting in the red overlapping the blue completely. In this case the red rectangle's 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.

For more information on ordering, see the Order page.

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

Contained Type enables code generation and Gum runtimes (such as FlatRedBall) to create strongly-typed containers.

Common Usage

Some Gum components or Containers may exist to hold a list of a particular type of item. For example, consider a game which includes a row of hearts to show the player's current health.

In this particular case, the hearts can be filled or empty to show the current and max health, but the max health can also be increased. If the max health increases, then a new heart instance is added to the container at runtime.

Since this container should only ever contain instances of a Heart component, then the container's Contained Type can be set to Heart.

In this example, FlatRedBall respects the Contained Type variable and generates a generic list.

As mentioned above, the implementation of this variable depends on the runtime you are using. If you are using a runtime which does not implement this feature and you would like to have it added, please create a GitHub issue or make a request in Discord.

Introduction

Is Render Target controls whether all instances contained in this container render directly to the screen (if false), or if they first render to their own dedicated target before rendering to the screen (if true).

Is Render Target defaults to false (unchecked).

Is Render Target enables a number of graphical effects including:

• Container (transparency)

• Container

• Alpha-only modes on instances contained in the Container

The Wraps Children property controls whether children wrap or stack beyond their container's boundaries when the container's 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 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:

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

Introduction

The Blend variable controls how the selected instance combines its colors with whatever is drawn before. The final appearance of a NineSlice depends on its Blend, Alpha, Source File, and Color values.

For more information and examples, see the .

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 Left variable controls the left pixel of the source rectangle used to draw the NineSlice. Texture Left is only available if the NineSlice uses a Texture Address of Custom or Dimension Based.

The following image shows a NineSlice with a Texture Left value of 96.

Texture Left controls the left side of the region that the NineSlice displays on its source file. In this case, the left-edge of the source rectangle is 96 pixels from the left edge of the entire file.

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

Polygons are shapes defined by an ordered set of points. Polygons can be used to draw lines, shapes, and define collision in games.

Introduction

Points are an ordered set of X,Y values defining the shape of the polygon. All points are relative to the Polygon's position. Typically the last point is the same as the first point creating a closed polygon.

By default polygons have four sides. Since the first and last point is repeated, a four-sided polygon has five points.

Each point is relative to the polygon's X and Y (position). Points use pixel coordinates. The following image shows a polygon with the following points:

• -32, -32

• 32, -32

• 32, 32

• 32, -32

• -32, -32 (repeat of first point)

Notice that the image above has points which appear above and to the left of the polygon's origin.

Adding Points in the Editor

The easiest way to add points is by selecting a Polygon, then clicking on the + icon that appears in the center of the line where you would like to add a point. The following animation shows how to add points to a square to create an octagon:

Moving Points

Points can be moved by clicking on them and dragging them in the editor. Note that points can be positioned anywhere, even if lines cross or if a polygon is concave.

Removing Points

A point can be removed by clicking on it and pressing the delete key.

Advanced Point Editing

Points can also be edited manually in the Screen or Component which contains the Polygon instance. You can open the file in a text editor to see a list of points.

For example, consider the following polygon:

The points for this polygon defined in the MainMenu XML file might look like this:

<VariableList xsi:type="VariableListSaveOfVector2">
  <Type>Vector2</Type>
  <Name>PolygonInstance.Points</Name>
  <IsFile>false</IsFile>
  <IsHiddenInPropertyGrid>false</IsHiddenInPropertyGrid>
  <Value>
    <Vector2>
      <X>0</X>
      <Y>46</Y>
    </Vector2>
    <Vector2>
      <X>32</X>
      <Y>32</Y>
    </Vector2>
    <Vector2>
      <X>10</X>
      <Y>0</Y>
    </Vector2>
    <Vector2>
      <X>0</X>
      <Y>46</Y>
    </Vector2>
  </Value>
</VariableList>

These points can be changed in the XML file. If the file is changed then Gum automatically reloads this file.

Remember that the first and last points should have the same values if you want your polygon to be closed. You can make edits in the XML file to separate the start and end if you would like to draw a segmented line rather than a closed polygon.

Introduction

Skia standard elements are a collection of elements which use SkiaSharp for rendering. Skia standard elements provide additional types of visuals supported by Gum, but not all runtimes support Skia standard elements.

Skia adds advanced vector graphics support for shapes such as Arc, ColoredCircle, and RoundedRectangle. Skia also adds support for vector file formats such as SVG and Lottie.

Enabling Skia Standard Elements

Skia standard elements must be explicitly added to gum projects. To add Skia standard elements Select Plugins -> Add Skia Standard Elements.

After clicking this option, Gum adds new standard elements.

Once these Skia standard elements are added, they can be added to Screens and Components just like any other standard element.

Introduction

The Texture Top variable controls the top pixel of the source rectangle used to draw the NineSlice. Texture Top is only available if the NineSlice uses a Texture Address of Custom or Dimension Based.

The following image shows a NineSlice with a Texture Top value of 48.

Texture Top controls the top side of the region that the NineSlice displays on its source file. In this case, the top-edge of the source rectangle is 48 pixels from the top edge of the entire file.

Introduction

Arcs are curved lines with variable thickness. Arcs can also be used to draw wedges if the line thickness is large enough.

Arc dimensions

Arcs draw inside their bounds, with the edge of the arc touching the bounding rectangle. The thickness of the arc remains consisntent regardless of the bound width and height.

The following shows an arc with a Sweep Angle of 270 degrees, being resized in the Editor tab.

Introduction

Has Dropshadow controls whether a dropshadow is drawn below an element. By default this value is false.

The following image shows two RoundedRectangles. The left with Has Dropshadow unchecked, the right with Has Dropshadow checked.

Note that if an instance has a dropshadow, the dropshadow renders outside of the bounds of the instance.

Dropshadows draw as part of the object, so if multiple objects stack, their dropshadows also stack.

Dropshadow Offset X and Y

Dropshadow Offset X and Y control the position of the dropshadow relative to the main body of the instance. By default this value is 3 pixels below (Dropshadow Offset Y of positive 3).

This value can be changed to offset the dropshadow in any direction increasing a sense of height for the element.

Dropshadow Blur X and Y

Dropshadow Blur X and Y control how much to blur the dropshadow on the X and Y axes, respectively. A value of 0 creates a sharp shadow, while a larger value increases blur. Note that the X and Y values can be adjusted independently.

Dropshadow Alpha

Dropshadow Alpha controls the transparency of a dropshadow. A fully-opaque dropshadow has an alpha of 255. This value can be modified to decrease or increase the dropshadow's opacity.

Dropshadow Red, Green, and Blue

Dropshadow Red, Green, and Blue can be used to adjust the dropshadow color. Usually dropshadows are pure black with their transparency adjusted by Dropshadow Alpha, but they can also include other colors if needed.

Introduction

The Use Gradient property controls whether a Skia Standard Element uses gradient values if true or a solid color if false.

By default this value is false.

If this value is set to true, then additional properties appear for controlling the gradient.

Red1 and 2, Green1 and 2, Blue1 and 2

Gradients create a smooth interpolation of color from the first set of values (Red1, Green1, Blue1) to the second set of values (Red2, Green2, Blue2).

Changing these values adjusts the gradient start and end colors.

Gradient X1 and 2, Gradient Y1 and 2

The gradient values appear at their respective values at the points specified by Gradient X1, Gradient Y1, Gradient X2, and Gradient Y2. For example the gradient points could be visualized as shown in the following image:

Changing the Gradient X or Y values changes the start and end points for the gradient.

Gradient X1 and X2 Units, Gradient Y1 and Y2 Units

Gradient values use Units similar to X Units and Y Units. By default, gradient values are relative to the top-left of the element. Since the gradient values are not affected by size, changing the size of the element does not affect the gradient.

The gradient X and Y units can be changed. Each value can be set independently. For example, the X2 and Y2 units can be adjusted to be relative to the bottom-right corner of the instance. The following shows a RoundedRectangle with the Gradient X2 and Y2 values 100 pixels up and to the left of the bottom-right corner. If the RoundedRectangle is resized, then the gradient adjusts in response.

Gradient X and Y values can exist outside of the visual space of the instance, and even outside of its bounds. The following image shows an Arc with a gradient which is defined below the visual part of the arc. Notice that the Gradient Y values are both 0 PixelsFromBottom.

Gradient Type

Gradient Type controls whether the gradient is linear or radial. Radial gradients place the center of the radial gradient at X1,Y1 and the edge of the radial gradient at X2, Y2.

Introduction

Is Filled controls whether a shape is filled in or if it is drawn using stroke - another word for outline. By default this is true, but it can be unchecked to make a shape draw its outline.

Stroke Width

Stroke Width controls the thickness of the stroke (outline). Increasing the value makes the stroke thicker.

Stroke, Gradient, and Dropshadow

If a Skia standard element has its Is Filled unchecked, this affects the rendering of gradients and dropshadows.

Gradients only fill the solid parts of a shape, so if a shape has Is Filled set to false, the hollow center of the shape does not show gradient color.

Dropshadows respect the opaque part of the shape, so changing Is Filled also affects the dropshadow.

Introduction

Start Angle defines the angle of the starting point of the arc. This value is measured in degrees, with a value of 0 pointing to the right. The value increases counterclockwise. the Start Angle and Sweep Angle values combine to determine the range of angles covered by the Arc.

The following image shows the an Arc with a Start Angle of 0. The red lines and text are not part of the arc and are added to the screen shot to show the location of the Start Angle.

Changing the Start Angle moves one side of the arc. The arc appears to rotate if the Start Angle is changed gradually.

Start Angle defines the starting point of the arc. A value of 270 degrees and a value of -90 place the starting point of the arc in the same location. Values larger than 360 result in the value looping. These values, although normally not needed, can be used to create spinning animatoins.

Introduction

Sweep Angle defines the angle that the arc covers. This is a signed value, with positive values going counterclockwise.

The following shows an arc with a positive Sweep Angle of 135 degrees.

Changing the Sweep Angle changes the length of the arc. If the value is negative, then the Sweep Angle increases the size clockwise.

A sweep angle of 360 creates an arc that extends to a full circle. Values greater than 360 appear the same as if Sweep Angle is set to 360.

Introduction

RoundedRectangle is similar to a ColoredRectangle with the added functionality of supporting rounded corners.

RoundedRectangles also support Skia properties such as Has Dropshadow, Is Filled, and Use Gradient. For more information and examples, see the Skia Standard Element General Properties pages.

Introduction

Thickness controls the width of the arc line in pixels. This value can be increased to make the line arc thicker.

Thickness can be increased to create a wedge.

Note that Thickness can be increased to any value including values larger than the radius of the arc. Large values can result in the arc rendering past its center point creating a bowtie shape.

Other undesirable rendering effects can happen with large thicknesses when working with arcs which have one size (width or height) larger than the other, as shown in the following image:

Introduction

The Canvas element creates an instance of a SKCanvas which can be accessed in code to perform custom rendering. The contents of the Canvas cannot be modified in Gum. Since it is a Gum object, it does provide all of the variables for positioning, sizing but the rendering must be performed in custom code.

Since the Canvas cannot perform any rendering in Gum, it appears as an empty container.

Introduction

The Corner Radius variable controls the radius of each of the four corners on a rounded rectangle. A value of 0 results in a sharp corner. Increasing this value makes the corners more rounded.

Introduction

LottieAnimation instances can render animations in the Lottie format. Lottie files are animated files, usually with vector art, which serve as an alternative to gifs. Since they are often vector art, Lottie files can be resized without pixelation.

Lottie files can be downloaded from various sites or created in application such as Adobe After Effects. If you are interested in testing out Lottie animations, you may want to check lottiefiles.com for sample Lottie files.

The following shows a Lottie animation playing in Gum. Source file: https://lottiefiles.com/free-animation/city-skyline-HFnJYQZLPP

Source File

The Source File variable controls the lottie animation displayed. This value can be set and changed just like source files on other elements such as a .png on a Sprite.

Lottie Width and Height

Width and Height values can be set on a Lottie file just like any other Gum element. Unlike rasterized objects such as Sprites, LottieAnimations use Vector art so they can be resized and still retain crisp edges and details.

LottieAnimations are still rasterized in Gum, so they display pixels when the view is zoomed in, especially if the LottieAnimation has a small Width or Height.

Introduction

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

Introduction

Svgs can display .svg files. Since these files are vector art, they can be resized without pixelation.

The following is an Svg instance displaying the FlatRedBall logo. Source SVG: https://github.com/flatredball/FlatRedBallMedia/blob/master/FlatRedBall%20Logos/frb-logo-main.svg

Source File

The Source File variable controls the lottie animation displayed. This value can be set and changed just like source files on other elements such as a .png on a Sprite.

Svg Width and Height

Width and Height values can be set on an Svg file just any other Gum element. Unlike rasterized objects such as Sprites, Svgs use Vector art so they can be resized and still retain crisp edges and details.

Svgs are still rasterized in Gum, so they display pixels when the view is zoomed in, especially if the Svg has a small Width or Height.

Maintain File Aspect Ratio Width and Height

Svgs support the Maintain File Aspect Ratio Width and Maintain File Aspect Ratio Height units. For more information, see the Width Units and Height Units page.

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 project portable.

ACHX Files

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

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 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 are related.

Entire Texture

If the texture address property is set to EntireTexture then the sprite draws its full image. The sprite does not repeat or render only part of the texture. This renders the entire image.

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

When the Texture Address is set to DimensionsBased, then the Texture Width and Texture Height values are replaced by Texture Width Scale and Texture Height Scale. In this mode, the Texture Width and Texture Height values are calculated by multiplying the absolute size of the Sprite by its respective scale values.

DimensionsBased Texture Address and Percentage of File Width/Height

If a Sprite uses a Width Units of Percentage of File Width or a Height Units of Percentage of File Height, then the Width and Height values represent the size of the sprite relative to the entire source file.

For example, if a Sprite is displaying a source PNG file with a width of 130 pixels and its Width is 300, then the absolute width of the Sprite is 390 (130 * 300%). If Wrap is checked, then this indicates the number of times that the image repeats on the Sprite.

Texture Width Scale and Texture Height Scale

The Texture Width Scale and Texture Height Scale values determine the size of the texture on the Sprite when using DimensionsBased Texture Address. By default this value is 1, which means that the source image displays at its native size.

Increasing this value results in the image displaying larger. For example setting a value of 2 results in the displayed image being twice as large. Scale values for width and height can be set independently.

Introduction

The Wrap value controls whether the sprite wraps its image when rendering portions beyond the right and bottom image bounds. If this value is true then wrapping occurs. Otherwise, areas beyond the texture extend the last pixel - also known as "clamping" the value.

The Wrap variable applies when dealing with a Texture Address of Custom or DimensionsBased. Wrapping is not available when using a Texture Address value of Entire Texture.

Wrap and Custom Texture Address

If Texture Address is set to Custom then wrapping is available. All examples in the Custom Texture Address section use the following values:

• Width = 100

• Width Units = Percentage of File Width

• Height = 100

• Height Units = Percentage of File Height

For more information, see the and pages.

Toggling wrapping adjusts whether the Sprite wraps or clamps the area defined by the Texture Left, Texture Top, Texture Width, and Texture Height values.

A texture is wrapped if its Texture Right or Texture Bottom values are set to be larger than the source texture. For example, the following image shows a Sprite which is using an image that is 200x200. Its Texture Width is set to 500 and Texture Height is set to 300 so the sprite displays wrapping.

If the Texture Width or Texture Height values are adjusted, then the Sprite's wrapping also adjusts.

If Wrap is set to true, then wrapping happens for any area to the right or bottom of the bounds of the source. The following shows the bounds of a sprite moved in the Texture Coordinate tab resulting in the area that is being displayed wrapping and repeating.

Wrap and DimensionsBased

If a Sprite sets DimensionsBased for its Texture Address, then its source file can wrap if its dimensions are large enough to result in the texture width or texture height set to a value larger than the source dimensions.

All examples in the DimensionsBased Texture Address section use the following values:

• Width Units = Absolute

• Height Units = Absolute

Toggling wrapping adjusts whether the Sprite wraps or clamps the area defined by the Texture Left, Texture Top, and its size.

If a Sprite's width or height are adjusted, this results in its texture coordinate values also being modified. If Wrap is true then areas outside of the source file wrap.

Wrapping can also be affected by changing the Texture Width Scale or Texture Height Scale. Smaller values result in image being drawn smaller, making it wrap more.

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

ColoredCircle are round shapes which can be filled in or drawn as an outline. Unlike the non-Skia Circle element, ColoredCircles can be filled in and provide more options for customizing their appearance.

ColoredCircles support Skia properties such as Has Dropshadow, Is Filled, and Use Gradient. For more information and examples, see the Skia Standard Element General Properties pages.

Introduction

The text object can be used to display written information. The text object supports:

• Horizontal and Vertical alignment

• Text wrapping

• 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

• BBCode-style inline formatting

Text Wrapping

Texts wrap their contained words based on their dimensions. Whether a text wraps ultimately depends on whether the Text's Width Units is Relative To Children.

The following animation shows text wrapping on a text which is using an Absolute Width Units.

Introduction

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

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

States are collection of variables which can be used to represent a component or screen configuration. States can be used for a variety of situations including:

• Defining the appearance of a UI element such as Enabled, Disabled, Highlighted, and Pushed

• Defining positions for interpolation and animation such as OffScreen and OnScreen

• Defining start/end or empty/full states for interpolation such as AmmoFull and AmmoEmpty

• Defining appearance in response to game-specific status such as NotJoined and PlayerJoined.

Every element automatically includes a Default state which cannot be removed. This state is automatically selected and any changes made to a component happen on the Default state unless a different state is selected.

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.

Introduction

The Font variable sets the font family used by the text.

This dropdown appears only if Use Custom Font is set to false.

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

• Font Size

• Outline Thickness

• Is Italic

• Is Bold

• Use Font Smoothing

Installing Fonts

Windows Machines typically have dozens of fonts installed automatically. You may be working on a project which needs custom fonts. These fonts can be obtained on many websites including https://www.dafont.com/ and https://fonts.google.com/.

Once a font has been installed, you must restart Gum for the font to be available in the Font dropdown.

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.

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

Introduction

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

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 Is Italic value controls whether the Text instance uses an auto-generated font which is italicized.

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/

Font Size and Pixel Fonts

Games which are using fonts that are intentionally pixelated should avoid setting Font Size in-between the intended font size multiples for the given font. These sizes depend on the specific font used, and may require some trial and error.

For example, consider the font Press Start 2P which can be installed from https://fonts.google.com/specimen/Press+Start+2P

Font Size can be set to any value, but this font only looks good if Font Size is set to 8.

The rendering artifacts are more obvious when zooming in, as shown in the following image:

Of course, we could also set the Font Size to 16, but this is unnecessary. Since text instances using pixelated fonts usually have Use Font Smoothing set to false, then the Text can use its Font Scale to adjust its size.

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.

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 .

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

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

The Use Custom Font variable controls whether a Text object uses a premade .fnt file (if true) or if 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:

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

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.