Introduction

When a parent uses RelativeToChildren for its for its Width Units or Height Units, it must only consider children which are not positioned relative to the parents' Width or Height, respectively.

For the sake of brevity, this document will discuss Width, Width Units, X, and X Units values. All concepts also apply to Height, Height Units, Y, and Y Units.

Gum Prevents Recursive

Conceptually, parent Width Units and children X Units can create recursive relationships. For example, consider the following situation:

• Parent.WidthUnits = RelativeToChildren

• Child.XUnits = Percentage

• Child.Width = 100

• Child.X = 50

In this case the Parent width depends on the Child X and Width values. But the Child X depends on the Parent Width. This creates a recursive relationship which cannot be resolved (or which can be resolved with unexpected results).

Therefore, when determining the Width of a parent using RelativeToChildren WidthUnits, all children which have position or size values relative to their parent are ignored.

Specifically, the following values are considered absolute, and any values besides these will result in a child being ignored when calculating a relative parent Width:

• WidthUnits = Absolute, PercentageOfSourceFile, RelativeToChildren

• XUnits = PixelsFromLeft, PixelsFromMiddle, PixelsFromRight

Only the following values are considered absolute, and any values besides these will result in a child being ignored when calculating a relative parent Height:

• HeightUnits = Absolute, PercentageOfSourceFile, RelativeToChildren

• YUnits = PixelsFromTop, PixelsFromMiddle, PixelsFromBottom

Width and Height are calculated independently. This means that a child may be ignored when calculating RelativeToChildren Width, but may be considered when calculating RelativeToChildren Height.

Examples

To help explain the way units work, this section two ColoredRectangles. Other types such as Container could be used, but colored rectangle is easier to see in pictures and animations so we'll use this type. Also, like the section above this section uses X and Width values, but the same concepts apply to Y and Height values.

Initially the Parent has a Width of 0 and a Width Units of Relative to Children.

This results in the Parent's width being controlled by the right side of the Child (the red ColoredRectangle). In other words, if the Child is moved or if its Width changes, the Parent's Width also changes.

In this case, the Parent's Width depends on its Child - specifically the right side. The Child's right side is absolute - it does not depend on the parent, so this relationship is not circular. However, if we were to adjust the Child so that its X Units depended on the parent's width, such as by changing X Units to Pixels from Right, the child would now depend on the Parent's width, creating a circular relationship. We can see that once this circular relationship is established, the parent's actual width changes to 0.

To reiterate, after this change, the child's right side depends on the parent's right side, and the parent's right side depends on the child's right side. This circular dependency is resolved by Gum with the parent ignoring the child - in this case the Parent behaves as if the child does not exist when it determines its actual width. This results in the Parent's width depending on no children, so it is set to 0 (the value set on the Parent's width).

These types of circular dependencies can cause confusion but they are okay to use in actual projects. Typically these types of situations exist when a Parent has a mix of children - some of which use absolute positioning, some of which depend on their parent.

For example, we can add a second child - a yellow ColoredRectangle maned Child2. If Child2's right side is absolute, then the Parent will use it to determine its size. Notice that when this happens, the red Child ColoredRectangle adjusts appropriately.

The properties are applied in the following order:

1. Child2's right side is determined using its absolute X and Width values

2. Parent's Width value is set according to Child2's right side. Parent ignores Child (the red box) because Child's right side depends on Parent's right side.

3. Child sets its X according to Parent's right side

A practical example of how this type of relationship might be used is a situation where Parent contains objects that should control its size, but also has elements which react to the size such as a top bar.

Introduction

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

Absolute

The following shows a child ColoredRectangle with 50 Absolute Height:

Relative to Container

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

Percentage of Container

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

Ratio of Container

Ratio of Container can be used to fill available space or to share available space with other objects using a ratio.

The simplest case is a single child in a container with its Height Units set to Ratio of Container.

In this case the blue ColoredRectangle has no siblings (its container 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 Container proportionally. The image above shows four siblings, each given 1/4 of the ratio. If one of the the ratios changes (such as by increasing the second sibling's Height value to 3), then all siblings adjust in response to this change.

In this case, the total ratio is 6 (1 + 3 + 1 + 1), so the red is given 3/6 (1/2) of the container's height, while each of the others is given 1/6 of the container's height.

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

Ratio of Container is calculated after accounting for the height of children which are using absolute height. For example, if the height of the first child is 80 with a Height Units of Absolute, then the other three shrink to give the first the necessary room.

This effect can also be seen by adjusting the height using the handles.

Gum ignores invisible objects when calculating available space for Ratio Width units. Therefore, if a sibling is invisible, Gum treats it as if it has 0 height which allows all other Ratio siblings to expand.

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

Relative to Children

The following image shows a child ColoredRectangle with 50 RelativeToChildren 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:

RelativeToChildren can be used to size an object based on the position and sizes of a container's children. The following image shows a container with 0 RelativeToChildren Height, which mans that its height is set just large enough to contain its children. Notice that if the children are moved, the rectangle's height adjusts. Both children are considered so the container adjusts its height according to the bottom-most side of either child:

A non-zero Height when using RelativeToChildren can be used to add additional padding to a parent container. The following shows how changing the height can adjust the absolute height relative to children:

Relative to Children and Auto Grid Vertical

If a parent sets its Height Units to Relative to Children, then it must resize itself to contain its children. Normally, the height of the entire parent is determined by the child which needs the most space vertically. If the parent uses an Auto Grid Vertical layout, then the children control the size of the cells rather than the entire parent. Since all cells must be the same size, the child which needs the most amount of space vertically determines the height of all cells.

For example, the following image shows a four by four grid, each containing one white rectangle. The first rectangle has an absolute width and height of 100, so each cell is sized to be 100x100. Note that the other rectangles are 50x50.

The largest child determines the cell size for all other children. Therefore, if a child is moved or resized so it outgrows its cell, then the parent height adjusts in response.

Relative to Children and Text

The term "children" can refer to:

• Instances added to a parent, such as ColoredRectangles added to a Container

• Individual letters in a Text instance - each letter and line of text can expand the height of its parent

The following animation shows a Text instance which has its Height Units set to RelativeToChildren. As more lines of text are added, the Text automatically expands in size.

Percentage of Other Dimension

Percentage of Other Dimension adjusts the object's effective height so it remains proportional to the Width value multiplied by the Height value (as a percentage). For example, if a Height value of 200 is entered, then the effective height is 200% (2x) of the width.

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

The Sprite type has an extra Height Unit called Percentage of Source File, which sets the height of the Sprite according to the file that it is displaying. This is the default Height Unit 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:

Introduction

Parenting allows UI elements to be positioned and sized according to other UI elements. Parenting hierarchies can go many levels deep and the parent/child relationship can be visualized by the white line connecting the parent to the child when the child is selected.

Example - Drag+Drop in the Tree View

To change the parent/child relationship in the tree view:

1. Select a child

2. Drag+drop the child onto the desired parent

The child can be detached from its parent by drag+dropping it onto the Component.

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

Example - Using the Dropdown

To set a parent/child relationship:

1. Select the child

2. Change the Parent property to the desired parent:

Introduction

The Visible property controls whether an object and its children appear.

Example

Toggling the Visible property changes whether an object is drawn.

Parent/Child Visibility

Toggling the visibility of a parent will make all children invisible, even if a child's Visible property is true.

The Clips Children property controls whether children of a component or container can render outside of the bounds of their parent. By default this is false, which means that all children can fully-render, regardless of whether they are within the bounds of their parent or not. Setting this value to true will prevent children from rendering outside of the bounds of their parent.

Introduction

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

Absolute

The following shows a child with 50 Absolute Width:

Relative to Container

Percentage of Container

Ratio of Container

Relative to Children

Relative to Children can be used to size an object based on the position and sizes of a container's children. The following image shows a container with 0 Relative to Children Width, which means that its width is set just large enough to contain its children.

A non-zero Width when using Relative to Children can be used to add additional padding to a parent container. The following image shows a container with 20 pixels of padding width:

Relative to Children dynamically adjusts to changes in properties on the children. In the following animation the container has a Children Layout of Left to Right Stack. Adding additional children expands the container automatically:

Relative to Children and Auto Grid Horizontal

If a parent sets its Width Units to Relative to Children, then it must resize itself to contain its children. Normally the width of the entire parent is determined by the child which needs the most space horizontally. If the parent uses an Auto Grid Horizontal layout, then the children control the size of the cells rather than the entire parent. Since all cells must be the same size, the child which needs the most amount of space horizontally determines the width of all cells.

For example, the following image shows a four by four grid, each containing one white rectangle. The first rectangle has an absolute width and height of 100, so each cell is sized to be 100x100. Note that the other rectangles are 50x50.

The largest child determines the cell size for all other children. Therefore, if a child is moved or resized so it outgrows its cell, then the parent width adjusts in response.

Relative to Children and Text

Setting a Text instance's Width Units to Relative to Children results in the Text object adjusting according to its text contents. For example, setting the Width Units to Relative to Children and setting the Width to 0 results in the Text object automatically adjusting its actual width according to the text it contains.

Percentage of Other Dimension

Percentage of Other Dimension adjusts the object's effective width so it remains proportional to the Height value multiplied by the Width value (as a percentage). For example, if a Width value of 200 is entered, then the effective width is 200% (2x) of the height.

Percentage of Source File

Absolute Multiplied by Font Scale

Absolute Multiplied by Font Scale is a property which multiplies the Font Scale property at runtime with the width value. This can be used to create widths which are responsive to font scales for devices which may have variable text sizes.

At the time of this writing, the Gum tool always uses a Font Scale of 1, so this cannot be previewed in the tool. However, when a Gum project is loaded at runtime, the runtime may apply a Font Scale value such as using the Text size from Windows.

Introduction

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

Example

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

Introduction

The X Origin variable controls the point which an object is positioned by. By default the X Origin is Left. The X Origin is shown visually as a white "X" in the editor.

Left

The following image shows a ColoredRectangle with its X Origin set to Left:

Center

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

Right

The following image shows a ColoredRectangle with its X Origin set to Right:

Introduction

Gum Screens and Components support defining a base type. By setting a base type, a screen or component automatically inherits the following from the base type:

• Variable values

• Exposed variables

• Instances

• Available variables, such as stacking if inheriting from a container

Inheritance is useful if your project needs multiple screens or components which share common variables or instances.

Component Inheritance

All components use inheritance even if the Base Type variable is not set explicitly. By default components inherit from the Container type.

By inheriting from the Container type, components have access to all component variables such as Children Layout.

Inheriting from Standard Types

Components can inherit from standard types. For example, instead of inheriting from Container a component may inherit from ColoredRectangle. By doing so, it has access to all properties on the ColoredRectangle type.

Inheriting from Components

Components can inherit from other components. By doing so the component inherits all children and exposed variables.

A component which inherits from another component is often called a derived component. The component which is being inherited from is often called a base component.

A base component can be used to define instances which the derived component can modify. For example a component named ButtonBase may define that all components have a ColoredRectangle named Background and a Text named TextInstance.

If another component uses ButtonBase as its Base Type, then this component automatically gets Background and TextInstance children which match the base instances.

The CancelButton can modify variables on the added children. For example the CancelButton can modify the Text on the TextInstance and the color values on the Background.

The derived component has the following restrictions when working with children

• Name cannot be changed. For example Background must always be named Background.

• Base Type cannot be changed. For example, the base type for Background must be ColoredRectangle

• Children defined in the base cannot be removed. For example, the Background child cannot be deleted from CancelButton

If the base type adds new instances, then the derived types automatically get the same instances added as well. Similarly, if the base type deletes a child, then the child is also removed from the derived type.

Derived types get access to all of the exposed variables in the base type. For example, if ButtonBase exposes the TextInstance's Text property, this is also available on the derived component.

Base Type vs States

Base types allow for the customization of a component, including the creation of many variants. Similarly, States also allow for the customization of a component in similar ways. When deciding between whether to use states or inheritance, keep the following in mind:

• States are often used to set variables temporarily, while inheritance is permanent. For example, a button may set its background color values in response to being highlighted. By contrast, a Cancel button may always say "Cancel".

• States do not allow for the creation of new instances. Although derived components cannot delete children which are defined by their Base Type, derived components can add additional instances.

• Components can use multiple categories. Therefore, it may not be clear which category defines the type of component. A component can only have one Base Type, so its type is defined clearly.

Introduction

Variable References allows any variable on an instance to reference a variable on another instance. The most common use of Variable References is to create a centralized style component which can be referenced throughout a Gum project.

Variables which are assigned through Variable References cannot be directly set on the instance - the value obtained through the reference overwrites any custom value.

Example - Creating Color Styles

The following example creates a Styles component which contains a color value which is referenced by objects in a MainMenu Screen.

Any component can serve as a centralized location for styling, but we use the name Styles by convention.

The Styles component can contain as many objects as are needed to style your project. Additional objects can be added to help indicate how things are used visually. For example, we include a Text object to indicate the red color is the Primary Color.

The color value can be referenced by any other object including objects in different screens or components.

To add a variable reference:

1. Select the object which should have a variable reference

2. Click inside the Variable References text box

3. Type the variable reference. The format of the variable reference is {VariableName} = {Components or Screens}/{ComponentOrScreenName}.{InstanceName}.{InstanceVariable} For example, to reference the Red variable in the Styles component, the syntax is Red = Components/Styles.PrimaryColor.Red

Since color values have three components (Red, Green, and Blue), then all three components must be referenced. In this example, the background can reference the three colors with the following assignment text:

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

The types of the objects that contain the Variable References or which are being referenced do not matter. For example, a Text object could have its color values depend on the color values defined by a ColoredRectangle in the Styles component.

Once Variable References are set, the referenced instances (instances in Styles) can be changed and the changes will immediately propagate throughout the entire project.

Variable References in the Property Grid

As shown above, Variable References can be used to assign one variable to another. If a variable is referenced, then the variable cannot be manually assigned. The Variable Reference takes priority. For example, if an object references the Red, Green, and Blue variables, then those values cannot be manually set on the object. The values appear disabled and text indicates why they are read-only.

Implied Variable References

When entering a variable reference, Gum understands implied variable references by filling in the left-side of the equals sign to match the variable name on the right-side. For example, the following can be entered in the Variable References text box:

Components/Styles.PrimaryColor.Red

Gum automatically adds Red = before the entry, as this is the most likely variable assignment. This addition happens when the text box loses focus, such as when Tab is pressed or when a different text box gains focus.

Assigning color values is a common part of styling, so to help with this situation, Gum also expands the "Color" variable into all three components when the Variable References text box loses focus. For example, the following text can be used to assign all three values at once:

Components/Styles.PrimaryColor.Color

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

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

Same-Screen/Component References

The examples given above are useful for a centralized styling scenario. Variable references do not require referencing variables from other Screens or Components. If a reference is between two instances in the same Screen or Component, then the variable reference does not need to include the name of the component.

For example, we can assign the X value of one ColoredRectangle (RedRectangle) to the X value of another ColoredRectangle (BlueRectangle) using the following assignment:

X = BlueRectangle.X

This assignment forces the RedRectangle's X value to match the BlueRectangle's X value.

Changing the BlueRectangle's X value automatically updates the RedRectangle's X, even though the two rectangles have no other relationship to each other (such as a parent-child relationship).

Obtaining a Qualified Variable Name

Typing a variable name can be tedious, especially when referencing a variable in a different Screen or Component. Qualified variable names can be obtained by right-clicking on the variable name in Gum and selecting the Copy Qualified Variable Name option. This can then be pasted in the Variable References box of any other object.

Referencing Different Variables

Usually a variable references the same-named variable from the source, such as Red being assigned to Red. This is not a requirement, and variables can reference other variable values. For example, the Green value could reference the Red value on a source.

Green = Components/Styles.PrimaryColor.Red

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

Introduction

The Y property controls the vertical position for an object. The Y value represents the position of an object's Y Origin, using its Y 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.

PixelsFromLeft

The following shows a child ColoredRectangle positioned 50 PixelsFromLeft relative to its parent:

PixelsFromCenterX

The following shows a child ColoredRectangle positioned 50 PixelsFromCenterX relative to its parent:

PixelsFromRight

The following shows a child ColoredRectangle positioned 50 PixelsFromRight relative to its Parent:

PercentageWidth

The following shows a child ColoredRectangle positioned 50 PercentageWidth relative to its Parent. In other words, it will be positioned halfway between the left and right edges of the 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 Rotation property can be used to rotate Gum components. It is measured in degrees, where positive values rotate an object counterclockwise about its origin (X Origin and Y Origin).

Example

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

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

X Origin and Y Origin

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

The Y Units variable controls how a unit is vertically positioned relative to its parent. By default an object is positioned relative to the top of its parent, where each unit represents 1 pixel downward.

PixelsFromTop

The followingshows a child ColoredRectangle positioned 50 PixelsFromTop relative to its parent:

PixelsFromCenterY

The followingshows a child ColoredRectangle positioned 50 PixelsFromCenterY relative to its parent:

PixelsFromCenterYInverted

The followingshows a child ColoredRectangle positioned 50 PixelsFromCenterYInverted relative to its parent. Note that coordinates are "inverted", which means that increasing the Y value moves the object up rather than down. This value exists to simplify integration with engines which may use positive Y as up:

PixelsFromBottom

The followingshows a child ColoredRectangle positioned 50 PixelsFromBottom relative to its parent:

PercentageHeight

The followingshows a child ColoredRectangle positioned 50 PercentageHeight relative to its parent: