Introduction

The tutorials contained within this section provide an introduction to working with the Gum UI tool. This tutorial is a great place to start whether you are an artist who will be creating screens and components in Gum, or if you are a programmer who will be integrating Gum into your game or application.

If you are using Gum in a game project, you may want to continue reading other sections after you finish these tutorials.

Animation keyframes are defined by creating states in categories. If an animation uses two states in the same category then the animation will tween between them

Introduction

General properties are shared by all Standard Elements and Components.

Introduction

The Has Events variable controls whether the selected instance supports UI-related events at runtime such as responding to a cursor click. If this value is false then events are not raised for this instance. If true, then cursor events are raised for this instance.

Usually instances of components should have this value set to true if the component can be interacted with at runtime, such as a button or text box.

This value has no effect in the Gum tool and is only used at runtime.

Has Events and Cursor.WindowOver

If an instance has its Has Events value unchecked then it will not be eligible to be assigned to the Cursor's WindowOver property. For more information, see the Cursor page.

• 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 of a NineSlice depends on its Blend, Alpha, Source File, and Color values.

For more information and examples, see the Sprite Blend page.

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.

Gum is the best Game UI Layout tool available. It provides a flexible, efficient layout engine capable of producing virtually any layout. Gum can be used in a variety of contexts including in the FlatRedBall game engine, MonoGame, raylib, Silk.NET, and more. Gum can also be rendered on Skia so it can be used in any environment that supports Skia such as WPF and Avalonia.

The Gum layout engine can also be included in any .NET project without requiring the use of a particular graphical API.

To download the Gum UI tool and start building your UI, see the Setup page.

Powerful WYSIWYG Editor

Gum UI includes advanced layout functionality to create and preview your UI

Object Oriented Design Focused on Reusable Controls

Gum allows the creation of components which can be instanced and customized in screens and other components

Gum Objects Support Multiple Size and Position Units

Adjust an object’s origin, position units, size units, and stacking to create fluid UI

Simple Integration - Gum Supports Many Runtimes

Grab the NuGet, add a few lines of code, see your Gum project in game! You can use Gum with MonoGame, KNI, FNA, raylib, Silk.NET, SkiaSharp, and many more platforms. For more information on our runtimes, see the Getting Started page.

Interact with Gum in Code

Gum objects can be created and modified in code. Create fully-featured UI by subscribing to common UI events.

void CustomInitialize()
{
    MyButton.Click += HandleOkButtonClick;
}

private void HandleOkButtonClick(object sender, EventArgs args)
{
    // do your logic here
}

Time-Tested and Reliable

Gum has been used in commercial projects of all sizes - check them out in our Showcase page.

Need Help?

Gum is actively maintained and provides lots of ways to get answers:

• Check the rest of the documentation

• Join the Discord chat (shared discord with FlatRedBall)

• Create an issue on Github

Introduction

Shape properties are shared by the standard elements that draw vector shapes. Unlike General Properties, which every Standard Element and Component shares, shape properties only appear on shape elements such as Circle and Rectangle.

These properties control how a shape is filled, whether it draws a gradient, and whether it casts a dropshadow:

• Has Dropshadow

• Is Filled

• Use Gradient

The following element types expose these properties:

• Circle and Rectangle - the core (non-Skia) shape standard elements.

• ColoredCircle, RoundedRectangle, and Arc - Skia standard elements.

• Line supports Has Dropshadow and Use Gradient, but not Is Filled (a line draws as a stroke and has no fill).

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, including the Arc shape and 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

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

Circles can be drawn as an outline, filled in, or both, and supports additional effects such as gradients, drop shadows, and dashed strokes. Circles are sized using their Width and Height values.

Circles support all shape properties. For more information see the Shape Properties page and subpages.

Introduction

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

Example

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

Introduction

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.

Corner Radius is restricted to half of the smallest absolute dimension. In other words, if the RoundedRectangle is too small to fit its set CornerRadius, then the effective CornerRadius shrinks.

The following shows a RoundedRectangle with a Corner Radius of 60. If it is resized to have an effective width or height of less than 120, then the effective radius shrinks.

Similarly, setting a Corner Radius that is larger than half the Width or Height does not affect the RoundedRectangle.

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

ColoredCircle are round shapes which can be filled in or drawn as an outline, with options for customizing their appearance.

ColoredCircles support shape properties such as Has Dropshadow, Is Filled, and Use Gradient. For more information and examples, see the Shape Properties pages.

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

The Is Tiling Middle Sections property controls whether the non-corner sections of a NineSlice are tiled (repeated) instead of stretched. By default this value is false, meaning the middle sections stretch to fill the available space. When set to true, the middle sections repeat their texture at its natural size instead of stretching.

This property appears in the Source category in the Variables tab.

This is useful for textures with repeating patterns like brick walls, chains, or borders where stretching would distort the pattern.

Default Behavior (Stretching)

By default, when a NineSlice is resized, the five non-corner sections (Top, Bottom, Left, Right, and Center) are stretched to fill the space between the corners. This works well for smooth or gradient textures, but can create visible distortion with patterned textures.

Tiling Behavior

When Is Tiling Middle Sections is set to true, the five non-corner sections repeat their texture instead of stretching:

• Top and Bottom edges tile horizontally

• Left and Right edges tile vertically

• Center section tiles in both directions

The four corner sections (Top Left, Top Right, Bottom Left, Bottom Right) are never tiled — they always render at their natural size regardless of this setting.

Introduction

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

The following image shows two Rectangles. 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 Dropshadow Offset Y

Dropshadow Offset X and Dropshadow Offset Y control the position of the dropshadow relative to the main body of the instance.

This value can be changed to move the dropshadow, which gives the element a sense of height.

Dropshadow Blur

Dropshadow Blur controls the dropshadow edge softness. A value of 0 creates a sharp shadow, while a larger value increases blur.

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 Color

Dropshadow Color adjusts the dropshadow color independent of the shape's body color. Usually dropshadows are pure black with their transparency adjusted by Dropshadow Alpha, but they can also include other colors if needed.

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

Rectangles can be drawn as an outline, filled in, or both, and supports additional effects such as gradients, drop shadows, and dashed strokes.

Rectangles support all shape properties. For more information see the Shape Properties page and subpages.

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

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

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.

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

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 Min Height variable sets the minimum height in pixels. This value is applied after all other layout so it can be used to overwrite automatically-assigned height.

By default this value is <NULL> which means there is no Min Height.

If Min Height is assigned (not <NULL>), then the effective height cannot be less than the Min Height value. The following animation shows that height is limited to a Min Height of 100.

Notice that the Height variable can still be set to a value smaller than Min Height, but it does not apply visually.

Min Height can also be used if Height Units is set to values other than Absolute. For example, Min Height can be used to limit the height of a ColoredRectangle when Height Units is Relative to Parent.

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 Min Width variable sets the minimum width in pixels. The value is applied after all other layout so it can be used to overwrite automatically-assigned width.

By default this value is <NULL> which means there is no Min Width.

If Min Width is assigned (not <NULL>), then the effective width cannot be smaller than the Min Width value. The following animation shows that the width is limited to a Min Width of 100.

Notice that the Width variable can still be set to a value smaller than Min Width, but it does not apply visually.

Min Width can also be used if Width Units is set to values other than Absolute. For example, Min Width can be used to limit the width of a ColoredRectangle when Width Units is Relative to Parent.

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.

Children outside of the bounds of a container with Clips Children set to true can also be clipped by setting a container's Is Render Target value to true.

The clip region is always axis-aligned, so rotating a container that clips its children leaves the clip region unrotated. To rotate a container and keep its contents clipped, see Rotating and Scaling Clipped Contents.

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

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

Introduction

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

RoundedRectangles also support shape properties such as Has Dropshadow, Is Filled, and Use Gradient. For more information and examples, see the Shape Properties pages.

Introduction

Shapes (Skia) support varies per platform. See below to see information about your platform.

Gum is not notarized by Apple, so macOS blocks it the first time you open it. You approve it once, and after that Gum opens normally. A new release is a new download, so you approve each new copy once too.

Download and Extract

1. Download the file for your Mac from the latest release:

   • Gum-osx-arm64.tar.xz for Apple Silicon (M1 and later).

   • Gum-osx-x64.tar.xz for Intel.

   To check which one you have, open the Apple menu and select About This Mac. A Chip line starting with Apple means Apple Silicon. A Processor line mentioning Intel means Intel.

2. Double-click the .tar.xz file in Finder. macOS extracts Gum.app into the same folder.

3. Drag Gum.app into your Applications folder.

Allow Gum to Open

Use either the System Settings steps or the Terminal command. Both do the same job.

Option 1: System Settings

1. Double-click Gum.app. macOS shows a message saying it could not verify Gum. Click Done, not Move to Trash.

2. Open the Apple menu and select System Settings, then Privacy & Security.

3. Scroll down to the Security section. It shows a message that Gum was blocked. Click Open Anyway.

4. Enter your password or use Touch ID, then click Open Anyway in the dialog that appears.

The Open Anyway button only appears for about an hour after macOS blocks Gum. If you don't see it, double-click Gum.app again and then go back to Privacy & Security.

On macOS 14 (Sonoma) and earlier there is a shortcut: Control-click Gum.app in Finder, select Open, then click Open in the dialog. macOS 15 (Sequoia) removed this shortcut, so use the steps above there.

Option 2: Terminal

Open Terminal (in Applications > Utilities) and run:

macOS marks every downloaded file as coming from the internet, and that mark is what makes it check the app. This command removes the mark from Gum.app and everything inside it. If you put Gum.app somewhere other than Applications, change the path to match.

Folder Access Prompts

macOS asks before any app reads files in your Desktop, Documents, or Downloads folders, or on an external drive. The first time Gum opens a project in one of those places, you may see a message like "Gum would like to access files in your Documents folder." Click Allow.

If you clicked Don't Allow, Gum cannot read the project. To fix it:

1. Open System Settings > Privacy & Security > Files and Folders.

2. Find Gum in the list and turn on the folder your project is in.

3. Quit and reopen Gum.

Troubleshooting

• macOS says Gum "is damaged and can't be opened." Run the Terminal command in Option 2, then open Gum again.

• Gum is blocked again after updating. Each new download carries a new internet mark. Approve the new copy with either option above.

• Gum opens but can't find your project. Check the folder access steps in Folder Access Prompts.

For other setup details, including how to open a project from the command line, see Setup.

Introduction

The ability to expose variables in Gum makes components flexible. For this example we will continue using the HealthBar component from the previous tutorial.

Recap

The last tutorial created a HealthBar component with two rectangles - Background and Fill. The instances were set up to be positioned correctly according to the size of the HealthBar.

We also created a GameScreen and added a few HealthBar instances. Although we can position and size each HealthBar instance, they all display the same health percent. This tutorial discusses how to use exposed variables to allow each instance to display a different value.

Exposing the Text variable

By default components only exposes top level variables. Variables on instances inside the component are not available when editing an instance. In programming terms these variables are considered protected.

However, we can expose variables inside of our component so that they can be modified in our screen.

To do this:

1. Select Fill inside the HealthBar component

2. Find the Width variable in the Variables tab

3. Right-click on the Width variable Expose Variable

4. Enter the name HealthPercent for the variable name - note that typically variables are exposed without spaces in them, but Gum will display them with spaces in the variables tab

Notice the variable now displays its exposed variable name.

Although this variable belongs to the Fill instance, it is now exposed as a variable on HealthBar. You can now see this variable by selecting the HealthBar component.

Similarly, now each instance can be modified since each now exposes a Health Percent variable.

Conclusion

This tutorial shows how to use exposed variables to customize component instances. You can expose other instance variables in your components to customize instances. Other examples of variables which may be exposed include:

• Visibility of icons on a Button component

• Font sizes on a Label component

• Sprite visibility showing the number of connected gamepads on a JoinGame component

It's best to experiment with exposed variables to get a feel for how you can use them in your own components.

Introduction

Gum supports creating and previewing animations in the editor through the use of states. The general workflow for creating an animation is as follows:

1. Create states representing the keyframes in the animation (usually one category per animation)

2. Add an animation to the component or screen

3. Add states to the animation and adjust their time

4. Set interpolation values for each keyframe to control "easing"

Examples of animations

Gum's animation system is very powerful and can be used in a variety of situations:

• Animations which play when a screen or component is shown or hidden

• Animations used to transition between behavior states such as changing a button from regular to highlighted state

• Lengthy animations which can last multiple seconds for complex transitions

Storage of animations

Animations are stored separate from the screen or component on the file system. If a screen or component contains at least one animation then Gum will save a Gum Animation file (.ganj or .ganx extension) with the word "Animations" appended on the screen or component's name. In other words GameScreen would have a file called GameScreenAnimations.ganj/ganx in the same folder containing information about its animations.

Playing animations

Once an animation has been made it can be played back in editor. The following shows how an animation is played back, both in real time and also by dragging the slider.

Bottom-up stacks can be used to display stacks of elements which should move up as more are added. This concept is similar to messages received in a chat window. Gum layout can be used to produce this type of stack.

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

This container to stack needs the following variables set:

• Children Layout set to Top to Bottom Stack so all children stack vertically
• Height Units set to Relative to Children so the container resizes itself as more children are added
• Height set to 0 so the effective height of the container is based purely on its children
• Stack Spacing set to 2 (optional) to add spacing between each child

Now children of the Container stack vertically. This concept works for any type of child, but we'll use ColoredRectangles for this example. Add a few instances to the Container and they stack vertically.

Finally we can have the stack grow up instead of down. To do this, change the following variables on the parent container:

• Y Origin set to Bottom
• Y Units set to Pixels from Bottom

Now as new children are added, the parent stack grows and all items shift up.

Introduction

Masking can be achieved to create "cut-out" effects such as rounded corners or images drawn over a circle shape. Masking is performed using render target containers and blend modes. Masking requires at least three objects:

1. A container to hold the masked objects. This container must be a render target container

2. The content to mask, such as a Sprite displaying an image

3. The mask shape, which can be a shape (such as a Circle) or another sprite with alpha that defines the mask

Creating a Container

The first step is to create a container that will be the render target. A render target is required so that the mask can modify the alpha of its sibling in the container.

To contain a render target container, add a new Container object to your Screen or Component. If you want your entire Component to be the container, then you can check the Is Render Target variable on the container itself.

Adding a Sprite

Next, add the content that you would like to have the mask applied to. For example, this could be an image. In this case, we will use a Sprite that is displaying a sample image. Add a sprite to your container and set its Source File to an image such as https://picsum.photos/id/74/100/100.

Adding the Mask Shape

Next, add the shape that you would like to act as the mask. The mask can be an actual shape such as a circle, or it can be another image with custom alpha. For this example we'll use a circle.

Add a circle to your container and dock fill it so it takes the entire size of the container.

Next we'll modify the shape so it its alpha can be used. Set these variables:

• Stroke Width = 0

• Is Filled = true (checked)

• Blend = MinAlpha

The MinAlpha value indicates that each pixel should use the minimum alpha, between the alpha that is on the image or the circle. In this case, the image is fully opaque, so the alpha is effectively the alpha of the circle. The outside of the circle shape is fully transparent so it removes the alpha from the image.

This same concept can be applied with other shapes, such as rectangles to produce rounded corners on images.

Introduction

The concept of padding is often used to add spacing between the edge of a container and its children. Padding can be achieved by adding sub-containers.

Creating a Container

First we'll create a top-level container. This container controls the size of all objects internally, including the background. We will also include a background object which is sized according to the container. To keep things simple, this example uses a dark blue ColoredRectangle.

The ColoredRectangle is set so its size matches its parent.

Next we can add another container to the top-level container. By default this container sits at the top-left of the parent when it is added with a drag+drop.

To have the container fill its parent, but also include padding:

1. Select the inner container

2. Click the Alignment tab

3. Enter the desired padding in the Margin text box

4. Click the Dock Fill button

This inner container can now be used to hold all children. Note that if you are creating a Component and you want to make this be the default container for children, you may want to set the Default Child Container to this inner container. For more information see the Default Child Container page.

Introduction

Render targets and blend modes can be combined to create a silhouette of any shape. This example uses a Sprite with transparency. It uses the Bear.png file:

Creating a Silhouette Component

To create a Component that can display a Silhouette, first create a new component named SilhouetteSprite.

Add a ColoredRectangle instance and a Sprite instance. The order matters - the Sprite should be drawn on top of the ColoredRectangle (it should show up 2nd in the Project tree view).

For this example, we will use the Alignment tab to adjust each item:

• SilhouetteSprite (main component) - Dock Size to Children

• ColoredRectangleInstance - Dock Fill

The Sprite should already be sized according to its source file, although you can change this size if desired.

The ColoredRectangleInstance defines the color of the silhouette so change it to a desired color.

Your component should look similar to the following image:

Next we'll adjust the transparency values. To do this:

1. Set SilhouetteSprite Is Render Target to true

2. Set SpriteInstance Blend to MinAlpha

Your sprite's silhouette should now appear, using the underlying color as its own color.

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. Shapes may also have transparent portions due to their form (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

By default, when one instance (such as a NineSlice) is attached to another instance (such as a Container), the child attaches to the root of the parent. However, complex components often have internal structures. For example, a Window may have an InnerPanel which acts as the "landing zone" for children.

Slots allow you to designate specific internal parts of a component as an "attachment point". Any instance in a component can be designated as a slot by checking the Is Slot variable.

Note that instances can be marked as Default Slots for automatic parenting. For more information see the Default Slot page.

Example - Using Is Slot

Setting an instance's Is Slot to true is a way to tell Gum that it should be available as a parent. Any number of instances can be slots.

For example, consider a Component with three children: Header, Body, and Footer. In this case all three instances should be considered slots.

To set the value, select each instance and check Is Slot.

If we have an instance of this HeaderBodyFooterComponent in a screen, then other instances can use any of the slots as their parent value. For example, the following screenshot shows a Text instance's available parents. Notice that all three slots are available.

We can select any of these as the Text's parent.

Introduction

The Locked property controls whether an instance can be clicked in the Editor tab, and whether any variables can be modified on the locked item.

Locked items appear with a lock icon.

If this value is true, then the following is true:

• Instance cannot be selected in the Editor tab

• Instance variables are all disabled and cannot be edited in the Variables tab (except un-locking the instance)

• Selected instances cannot be moved, resized, or rotated in the Editor tab

• Polygons cannot have points modified, added, or deleted in the Editor tab

• The Alignment tab buttons leave the instance where it is. If other instances are selected too, the buttons change only the unlocked ones, and the Output tab lists the locked instances they skipped.

Introduction

The Max Height variable sets the maximum height in pixels. This value is applied after all other layout so it can be used to overwrite automatically-assigned height.

By default this value is <NULL> which means there is no Max Height.

If Max Height is assigned (not <NULL>), then the effective height cannot be larger than the Max Height value. The following animation shows that height is limited to a Max Height of 100.

Notice that the Height variable can still be set to a value larger than the Max Height, but it does not apply visually.

Max Height can also be used if Height Units is set to values other than Absolute. For example, Max Height can be used to limit the height of a ColoredRectangle when Height Units is Relative to Parent.

Max Height and Relative to Children

Note that Max Height can prevent a container from growing according to its children. For more information, see the Relative to Children Height Units page.

A container with a Top to Bottom Stack grows to its Max Height when its children need more space. The child that crosses the max extends past the container's bottom edge. If the container also has Wraps Children checked, it stops at the bottom edge of the last child that fits, since the next child moves to a new column. For more information see the Children Layout page.

Introduction

The Max Width variable sets the maximum width in pixels. The value is applied after all other layout so it can be used to overwrite automatically-assigned width.

By default this value is <NULL> which means there is no Max Width.

If Max Width is assigned (not <NULL>), then the effective width cannot be larger than the Max Width value. The following animation shows that width is limited to a Max Width of 100.

Notice that the Width variable can still be set to a value larger than Max Width, but it does not apply visually.

Max Width can also be used if Width Units is set to values other than Absolute. For example, Max Width can be used to limit the width of a ColoredRectangle when Width Units is Relative to Parent.

Max Width and Relative to Children

Note that Max Width can prevent a container from growing according to its children. For more information, see the Relative to Children Width Units page.

A container with a Left to Right Stack grows to its Max Width when its children need more space. The child that crosses the max extends past the container's right edge. If the container also has Wraps Children checked, it stops at the right edge of the last child that fits, since the next child moves to a new row. For more information see the Children Layout page.

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.

Rotation in Stacks and Grids

Stacks and grids space a rotated child as if it were not rotated. With the default top-left origin, a rotated child can overlap its neighbors or leave gaps. With another origin, such as Center, the rotation also shifts where the next sibling starts in a stack. Auto Grid cells do not move. For more information see Stacking and Rotation.

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.

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:

X Origin in a Left to Right Stack

A child in a Left to Right Stack which is not the first child ignores its X Origin, and the stack positions it as if its X Origin were Left. This keeps it from overlapping its previous sibling. The first child in the stack uses its X Origin normally, and X Origin works normally for every child in a Top to Bottom Stack.

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

Is Filled sets whether a shape is filled in or if it is drawn using stroke - another word for outline.

Stroke Width

Stroke Width sets the thickness of the stroke (outline). Increasing the value makes the stroke thicker. Note that increasing the stroke brings the stroke inward, so the shape is still bound by its effective width and height.

Stroke, Gradient, and Dropshadow

If a shape 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

The Default Implementation property can be used to indicate which component is the default implementation for a behavior. This property 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.

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 is associated with the ButtonBehavior.

At runtime, a game may need to create an instance of the Button type without specifying a component. For example, the following code can be used to create a button:

var button = new Button();
button.Text = "Hello";
StackLayoutInstance.AddChild(button);

The Default Implementation property can help runtime libraries 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 use 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.

If you have created a custom runtime, such as a new ListBoxItem, you may need to change the Default Implementation for the ListBoxItem behavior.

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 Alpha (transparency)

• Container Blend

• Alpha-only Blend modes on instances contained in the Container

Is Render Target Clips Children

Containers with Is Render Target set to true automatically clip their children. This behavior is the same as setting Clips Children to true. This happens because render targets internally create a texture which matches their size. Therefore, any items which are placed outside of the bounds of a render target container are not rendered.

Using Is Render Target for Special Effects

Once a container is rendered to a render target, additional special effects can be applied at runtime. These include:

• Scaling

• Rotating

• Rendering portions using texture coordinates

For a step-by-step tool walkthrough of rotating and scaling a clipped container, see Rotating and Scaling Clipped Contents. For the same pattern in code, see the SpriteRuntime RenderTargetTextureSource documentation.

If you are managing a render target yourself in code instead of using Is Render Target, see Render Targets for the blend-mode setup needed to composite translucent content correctly on MonoGame and raylib.

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

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.

Custom Frame Texture Coordinate Width Set to 0

If Custom Frame Texture Coordinate Width is set to a value of 0, then the NineSlice does not draw a border. In other words, setting this value to 0 results in the NineSlice behaving like a Sprite.

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 can be any shape, so their width and height values cannot be explicitly set. Instead, a Polygon's width and height values are determined by their points.

Width and Height from Points

A Polygon's effective width and height is determined by its points. The furthest-right point determines the polygon's width and the furthest down point determines the polygon's height.

For example, a square Polygon with the furthest points at 128,128 has a width of 128 and a height of 128.

A Polygon's height can be used to affect parents, siblings, and children depending on the other instances' Width Units, Height Units, and stacking values.

For example, we can add a rectangle as a child of a ColoredRectangle to see how its points affect the size of the polygon.

We can see similar behavior if we place the Polygon in a stacking parent.

A Polygon's height and width are measured from a Polygon's top left corner to the furthest down right point. Points which have a negative value do not affect a Polygon's effective height, so moving points above or to the left of the origin will not affect the layout of any object which depends on the Polygon's size.

For example, if we move Polygon points in a stack up or to the left, this does not shift any of the Polygon's siblings.

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.

Default Slot specifies where children are added to instances of the selected component.

By default this value is blank, which means that newly added children treat the entire component as their parent. If Default Slot value is set, children which are dropped on instances of this component type use the Default Slot as their parent.

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

Multiple instances can act as slots. For information on using multiple slots, see the Is Slot page.

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 Slot property to InnerRectangle.

Once this value is set, instances which are drag+dropped onto Frame instances use the InnerRectangle as their parent, as shown in the following animation.

When one instance is drag+dropped onto another instance, the Parent property is set according to the parent's Default Slot.

Using the example above, the RectangleInstance is dropped on the ContainerTestInstance. Since the ContainerTestInstance is of type Frame, then the Default Slot is applied on the drop, which results in the RectangleInstance's Parent being set to ContainerTestInstance.InnerRectangle.

As mentioned above, if an instance is added to a parent component, the instance automatically attaches itself to the parent's Default Slot. This can be undone by manually changing the Parent property.

For example, the Parent can be manually changed to ContainerTestInstance.

Introduction

This guide walks through Gum's layout system using Figma as a reference point. The quick reference table below covers the most common mappings. The sections that follow explain the concepts that feel meaningfully different coming from Figma.

Quick Reference: Figma → Gum

In Figma, you organize your work into Pages, each containing Frames that typically represent individual screens or views. Components live alongside your frames and can be used across pages.

Gum splits this into three explicit categories visible in the Project panel:

• Screens — represent individual UI states in your game, like a main menu, HUD, or pause screen. You can think of each Screen as a top-level Frame in Figma. Unlike Figma frames though, Screens can't be nested inside other Screens — they're always top-level.

• Components — reusable elements like buttons, list items, or windows. These work like Figma components: define once, place instances anywhere.

• Standard Elements — the built-in primitives (Sprite, Text, ColoredRectangle, etc.) that you drag into Screens and Components to build your UI.

There's no equivalent to Figma's Pages — Screens serve as the organizational unit directly.

Gum's coordinate system works the same as Figma's: X increases to the right, Y increases downward, with (0, 0) at the top-left of the canvas or parent.

In Figma, a Frame can hold children and have its own fill and stroke. In Gum, layout containers are called Containers, and they are always invisible — there's no fill or stroke to set. You may notice containers showing up with a dotted outline in the editor, but that's just the container outline display (on by default in Gum) and isn't part of the rendered output.

To give a container a visible background, add a ColoredRectangle or NineSlice as a child. For example, a button component might have a Container at the root, a NineSlice child for the background, and a Text child for the label.

In Figma, you set X and Y and use the nine-point reference selector to control which corner of the object those numbers measure from. In Gum, the same idea is split into three properties:

X Units options:

Y Units mirrors this vertically, with positive Y always pointing downward. Pixels From Right and Pixels From Bottom work the same way — X=0 / Y=0 is at the edge, and positive goes outward past it. To position something inside those edges, use negative values.

X Origin / Y Origin options are Left/Top (default), Center, and Right/Bottom — the same as Figma's nine-point reference selector, just set separately per axis.

Center an element horizontally inside its parent (like Figma's "center" horizontal constraint):

Pin an element's right edge 10px inside the parent's right edge (like Figma's right constraint with 10px offset):

Note that Gum doesn't pin both sides of an element at once to stretch it. Stretching is handled by Width/Height Units instead.

Like Figma's Fixed / Fill / Hug, Gum controls sizing through Width Units and Height Units:

Relative to Children works like Hug. The numeric value adds padding — for example, Width = 16 with Relative to Children adds 8px on each side. Note that children whose size depends on the parent's size are excluded from this calculation to avoid a circular dependency.

Ratio of Parent works like CSS flex-grow. Three siblings with ratios of 1, 2, 1 get 25%, 50%, and 25% of the parent's width respectively.

The Alignment tab has shortcut buttons that set X, Y, Width, and Height variables for common layouts. They don't toggle any state — they just write variables, so you undo them with Ctrl+Z.

Anchor sets position variables only (X, Y, and their Units and Origins), similar to Figma's constraint presets. It won't change the element's size.

Dock sets both position and size, for "fill a side" patterns — think of it as Figma's "Fill container" combined with a constraint. Options include Top, Bottom, Left, Right, Fill, Fill Horizontally, Fill Vertically, and Size to Children.

Figma's Auto Layout is called Children Layout in Gum, set on the container itself:

Stack Spacing is the same as Figma's Gap between items. Negative values cause children to overlap.

In Auto Grid modes, the parent's size is divided equally among cells. The number of columns (or rows) is fixed; additional rows (or columns) are added as needed.

A couple of differences from Figma's Auto Layout worth knowing:

• No padding. To approximate padding, size a child with Relative to Parent and a negative value, or offset children manually.

• Cross-axis alignment is per-child. In a Top to Bottom Stack, Gum controls each child's Y automatically, but each child sets its own X. In Figma, alignment (left/center/right) is a single setting on the parent.

Wraps Children works like Figma Auto Layout's Wrap mode. Row height is set by the tallest child; column width by the widest.

One constraint: the container's size on the stacking axis can't be Relative to Children at the same time — that would be circular. You can still use Relative to Children on the cross axis (e.g. height on a horizontal stack). Alternatively, set a Max Width on the container — it will grow with its content until hitting the max, then start wrapping.

Figma's Clip content is called Clips Children in Gum. Off by default, meaning children can render freely outside their parent's bounds.

Gum's Components work like Figma's components — define once, place multiple instances, override individual properties per instance.

Gum also has Is Slot, which doesn't have a direct Figma equivalent. You can mark child instances inside a component as slots — named attachment points that elements can parent themselves to when the component is placed in a screen. For example, a Window component with Header, Body, and Footer slots lets you drop children directly into any of those sections.

Same as Figma: items earlier in the tree render behind items later in the tree. Right-click to Bring to Front, Send to Back, Move Forward, or Move Backward. Reordering a parent moves all its children with it.

Rotation is in degrees. One difference from Figma: positive values rotate counterclockwise (Figma rotates clockwise). The pivot point is set by X Origin and Y Origin — by default that's the top-left corner, so set both to Center if you want to rotate around the middle.

Min Width, Max Width, Min Height, and Max Height work the same as in Figma — they clamp the effective size after all other calculations. They work with any Width/Height unit type, so you can combine them with Relative to Parent or Relative to Children layouts.

Introduction

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

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

Gradient start color and Color2

A gradient creates a smooth interpolation from a start color to Color2.

For Circle, Rectangle, and Arc, the gradient starts from the shape's own color — for Circle and Rectangle that is the Fill color when the shape is filled or the Stroke color when it is outline-only, and for Arc it is the shape's Color. To adjust where the gradient begins, change that color; to adjust where it ends, change Color2. Because the start is the color the shape already shows, turning Use Gradient on and off does not produce a sudden color change.

The older ColoredCircle and RoundedRectangle shapes instead expose a dedicated Color1 for the gradient start.

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

The Color value can be used to set or modify the effective color of an object. The color value is combined with the Color Operation and an object's Source File or Font settings to produce a final color.

Example: Setting Color

Most objects in Gum have a Color (or similar) property which can be set directly in the editor. For example, Text instances have a Color which directly controls their effective color.

Color and Shapes

Shapes support multiple color values. Which value applies depends on a number of settings.

Stroke Color

By default shapes render their outline. The Stroke Color variable controls their outline color.

Stroke Color also applies to Rectangles.

Circles and Rectangles can set an independent Fill Color along Stroke Color. First, Is Filled must be checked. Once a shape is filled, its Fill Color can be set.

Sprites and NineSlices can change the way their Color value is applied by changing Color Operation.

The Modulate Color Operation is also often referred to as multiply. This is the default value, and it multiplies color the sprite that is being drawn by the color value.

Modulate is the default Color Operation value. When paired with the default value of (255, 255, 255) - pure white - Modulate does not modify the color of a sprite.

Any color other than white darkens the Sprite. A value of pure black results in all colors (red, green, blue) being multiplied by 0, which creates a black silhouette.

The math for multiply is that each of the three color components is normalized, which means a value of 0 to 255 is adjusted to a 0 to 1 range. Therefore, values of 128 become a value of (nearly) 0.5. These normalized values are multiplied against each channel in the source image to produce a final result.

Multiplying by a color which has uneven red, green, and blue values can darken and tint.

The Add Color Operation can be used to add color values to the source image. Add can be used to brighten color values.

An Add value of 0, 0, 0 does not modify the original sprite.

Any other color besides black brightens the Sprite. A value of white creates a white silhouette, resulting in all color values displaying their max 255.

Other values can be used to tint and brighten the argument sprite.

The Silhouette Color Operation uses the Sprite's Color value while keeping the Source File's opacity. This Color Operation is used to create colored silhouettes.

When using Silhouette, color values overwrite the source texture.

Introduction

Gum supports loading image files for Sprites and NineSlices. This tutorial discusses how to load files, and how they are referenced in Gum.

Setting up a workspace

First we'll set up a workspace:

1. Create a Screen called SpriteScreen.

2. Drag+drop a Sprite into the newly-created Screen

Setting the Sprite Source File

Source File is the image that the Sprite displays. Usually Source Files are of the .png file format. To set the source file:

1. Select SpriteInstance

2. Find Source File in the Variables tab

3. Click the "..." button to bring up a file window

If you select a file which is not located in the same folder or a sub folder of your gum project, Gum asks if you would like to reference the file in its original location or create a copy.

Usually it's best to copy the file to the Gum project folder so that the Gum project can be moved to different computers without breaking file references.

Sprites can display portions of their Source File. Files which combine multiple images are often called sprite sheets or tile sheets, and are commonly used in game development to keep art organized and to improve performance.

For example, the following file contains images for an animated character, ground tiles, and other entities for a platformer game.

If we download this file and set it as our , then the sprite displays the entire file.

We can display a portion of the Sprite rather than the entire file:

1. Click on the Texture Coordinates tab

2. Check the Snap to grid option to make it easier to select a region

3. Double-click anywhere on the image to select a region around the cursor

4. Move the selected region to the desired location to adjust the sprite's texture coordinate values

Introduction

Gum is an open source project so you can run it from source instead of running the pre-compiled project. Running from source is not a requirement, and is only needed if you intend to contribute to Gum or if you'd like to diagnose problems in a debugger.

Obtaining the source code

1. Download the source file from GitHub

   1. If you downloaded the .zip file from the GitHub main page, unzip the file

   2. If you downloaded the file through a Git client, be sure to be on the main branch

Building Gum requires the . Gum builds and runs from source on Windows, macOS, and Linux.

1. Locate the Gum.slnx file at the root of the repository (Gum.Wpf.sln is the older Windows-only WPF tool, which no longer ships)

2. Open it in Visual Studio, Rider, or VS Code

3. Build the whole solution rather than only the startup project. This guarantees that all plugins are built and copied correctly. For more information see below.

Run the following from the root of the repository:

To open a project on startup, add its path after --:

Some of Gum's features live in plugin projects, which copy themselves into the tool's Plugins folder when they build. Building only the Gum.Avalonia project (for example, by pressing F5 in Visual Studio after changing a plugin) does not rebuild them. Build the whole solution, or run dotnet build Gum.slnx, after changing a plugin.

If a menu item or tab that comes from a plugin is missing, build the whole solution. To see which plugins loaded, select Plugins > Manage Plugins. The dialog also lists any plugin that was found but could not be loaded, along with the reason.

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:

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

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

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 .

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.

A child in a which is not the first child ignores its Y Origin, and the stack positions it as if its Y Origin were Top. This keeps it from overlapping its previous sibling. The first child in the stack uses its Y Origin normally, and Y Origin works normally for every child in a Left to Right Stack.

Introduction

The Clips Children and Is Render Target properties clip their children to an axis-aligned rectangle. Because the clip region stays aligned to the screen, rotating a container that clips its children leaves the clip region unrotated, so the result looks broken.

To rotate (or scale) a container and keep its contents clipped, you render the container to a render target and display that render target through a Sprite. The Sprite can then be rotated, scaled, positioned, and stacked like any other Gum object, and the clipping rotates along with it.

The Two-Object Pattern

This effect uses two objects:

1. A Container with Is Render Target set to true. This container holds the content you want to clip, and it clips its children automatically.

2. A Sprite with its Render Target Texture Source set to the container above. The Sprite displays the container's render target and can be freely rotated and scaled.

The source container (which has Use Render Terget set to true) can even be made invisible:

1. Create a Container and add the children you want to clip and rotate.

2. Select the Container and set its Is Render Target value to true. Its children are now clipped to the container's bounds.

3. Create a Sprite.

• A container with Is Render Target set to true performs its layout and rendering even when its Visible value is false. Set the source container's Visible to false to hide the original while still displaying it through the Sprite.

• Children inside the render target container are not interactive while displayed through the Sprite

• — the same pattern in code

Gum supports creating animations which can play other animations. This is especially useful when creating animations in Screens that contain components which themselves have animations. This tutorial will build upon the where we created an animated component called TextComponent.

First we'll create a Screen called AnimatedScreen. To do this:

1. Right-click on Screens

2. Select "Add Screen"

Austerity X

Deadvivors

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

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.

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

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

Introduction

The Components tutorial shows how Rectangle instances can be sized and positioned according to the component that they are a part of. Instances can use other instances as their parents too. Gum does not place a limit to the depth of the parent/child hierarchy, enabling flexible and responsive layouts through.

Parent/child relationships are useful for

• Automatically adjusting margins and backgrounds

• Word-wrapping text relative to a parent

• Stacking objects on top of each other or side by side

• Placing objects next to other objects which are dynamically sized

• Creating tables and other complicated layout objects

For this example we'll create a Component for displaying distance. This component has two Text instances:

• ValueText - the Text instance responsible for displaying the value for the distance. For example "100".

• UnitsDisplay - the Text instance responsible for displaying the units for the distance. For example "km" for kilometers.

The two Text instances will have different colors so that ValueText stands out.

To create our component:

1. Create a new component named MeasurementDisplay

2. Drop two Text objects in the newly-created component

3. Name the first ValueText

4. Name the second UnitsDisplay

Next we'll make the UnitsDisplay use the ValueText as its parent:

1. Drag+drop UnitsDisplay onto ValueText to create a parent/child relationship

2. Change UnitsDisplay's X Units to Pixels From Right. This makes the text object positioned according to its parent's right edge

3. Change its X

The ValueText actual width should be based on its contents, so we'll do the following:

1. Select ValueText

2. Change Width Units to Relative to Children

3. Change Width to 0

By setting these values, ValueText is now sized according to its children, which in this case are its letters.

You may have noticed that UnitsDisplay is also a child of the ValueText. However, since UnitsDisplay is explicitly positioned outside of the bounds of its parent ValueText, then ValueText ignores this child when calculating its own Width. For a detailed discussion of Width Units and whether children are ignored, see the page.

Now that we have adjusted the position, size, and parent values on our Text instances, let's modify the color of the UnitsDisplay:

1. Select the UnitsDisplay

2. Change Red to 200

3. Change Green to 150

Now that we have set up a parent/child relationship between ValueText and UnitsDisplay, UnitsDisplay automatically adjusts its position in response to changes in ValueText. Any change on ValueText resulting in the right-side of the parent changing automatically adjusts the position of UnitsDisplay.

For example, if we change the Text property on ValueText, it grows or shrinks in response.

As mentioned above, changing the Text property causes ValueText to grow or shrink. However, regardless of its size, the Width property is still set to 0.

The Width variable is used in combination with its Width Units to calculate an effective width. In this case, the effective width is determined by the Text property on ValueText. It's important to note that all Gum objects have effective values for x, y, width, and height, all of which are determined by their respective units values.

Children always depend on their parents' effective values rather than their explicitly set values. Gum helps us visualize the effective values when we mouse over one of the resize handles on the selected object. For example, the following image shows the Width, Width Units, and effective width values of our ValueText.

Introduction

States allow you to set multiple variables at one time. Examples of states might include:

• A button with Regular, Highlighted, Pressed, and Disabled states

• A game logo in Large and Small modes

• A game HUD which can appear on and off screen

This tutorial shows how to add states which can be used to display if a player is low, medium, or high health by adjusting the color of the fill bar.

This tutorial builds upon the previous tutorials where a HealthBar component was created. If you haven't yet, you should read through the earlier tutorials to create a HealthBar component.

First we'll define a category and our three states. All components and screens have a Default state automatically. This Default state is uncategorized, but all other states must be in a category. Therefore, we'll first add a new category:

1. Right-click in the States tab

2. Select Add Category
3. Enter the name HealthCategory

Although it's not necessary, categories often have the name "Category" at the end.

To add a new state:

1. Right-click on HealthCategory

2. Select Add State
3. Enter the name "High"

4. Click OK

The HealthBar component should now have three states.

Once a state is defined and selected, you can make changes to the component and any of those changes are applied to the selected state. In other words, any variable that is set when the High state is selected results in that variable being added to that state.

For this component, we want to change the Fill color depending on whether the health is High, Medium, or Low.

Our High state should display a green color, and if you've set your Fill to be green, then this is already set how we want. This means we don't have to make any changes to the High state.

Instead, we'll make the fill yellow in the Medium state:

1. Select the Medium state

2. Select the Fill Rectangle instance under HealthBar

3. Change the Fill Color variable to a yellow color. Note that the fact that our rectangle is called "Fill" and that we are changing "Fill Color" is a coincidence. We named our Rectangle Fill because it fills the health bar. The Fill Color exists on every Rectangle, and controls the inner color of a rectangle, as opposed to Stroke Color which controls the outline color.

Although this might seem like a simple change, a lot has happened in response to this change, so we should take a moment to break it down.

First, by changing the Fill Color value on the Medium state, we have set every state to explicitly set its color. We can see this by noticing that every state now has an edited icon.

This tells us that the Fill instance is modified by every state in the HealthCategory. Even the High and Low states, which haven't been modified, are now explicitly setting the color to the default green.

We can modify the Low state to be a red color:

1. Select the Low state

2. Make sure Fill is still selected

3. Change the Fill Color variable to a red color

Now we can select any state and see what our state looks like immediately.

Now that we have added a new category to our HealthBar component, we can assign per-instance.

Notice that the Health Category State variable is independent of Health Percent. Although the two are conceptually connected, Gum considers these to be two unrelated variables which can be adjusted individually. These variables would typically be connected in code in a game.

This tutorial covers how to set up a state, but the next tutorial dives deeper into categories, including using multiple categories to mix variable assignments.

Introduction

This article shows how to create an animated component. It will contain an animation which can be used when the component first appears.

Creating the Component

First we'll create a component which will be animated. To do this:

1. Right-click on Components

2. Select Add Component

3. Enter the name TextComponent and click OK

4. Drag+drop the Text Standard into the TextComponent to create a Text instance

5. Select the Alignment tab and click the middle button to have the TextInstance fill the TextComponent

Now that we have a component we'll add the states needed for animation. We'll add all states in a category called HideShow. Animation states should always be categorized. To create the states:

1. Right click in the States list box

2. Select Add Category

3. Enter the name HideShow

4. Right-click on the HideShow folder

Now that we have the states defined we can set values for the states. In this case the only thing we'll be modifying is the TextInstance's Font Scale value. To do this:

1. Select TextInstance

2. Select the Hidden state

3. Set the Font Scale to 0. This makes the Text so small that it's invisible

4. Select the

The two states we created above will be used as the keyframes for our animation. The animation will begin in the Hidden state then interpolate to the Shown state. To add this animation:

1. Verify that TextComponent or any objects under it are selected

2. Select View -> View Animations

3. The Animations tab appears in the bottom right

The animation can now be played or previewed:

The Interpolation Type value sets how one keyframe blends to another. By default keyframes use Linear interpolation, which is a constant change from one state to another. When interpolating from one keyframe to another, the first keframe defines the interpolation type. In our case the Hidden frame defines the interpolation type. We can change the Interpolation Type and preview the animation:

1. Select the Hidden keyframe

2. Change Interpolation Type to Elastic

Playing the animation will reflect these changes.

Introduction

Gum provides simple controls for centering objects inside of their parents. This page shows how to center objects in a variety of situations. For brevity this document uses vertical centering, but the same concepts apply to horizontal centering.

Centering with Anchors (Alignment Tab)

The easiest way to center an object is to use the center Anchor. This sets all of the values necessary to center an object both vertically and horizontally.

Centering Using Units

Objects can be centered by setting their unit and numerical values. The Alignment tab is a shortcut for these values, but we can assign each value individually so an object is centered vertically:

• Set Y to 0

• Set Y Units to Pixels from Center

• Set Y Origin to Center

Centering can be performed with margins by adding an additional container to create the necessary margins. For example, consider a situation where we want to center the green rectangle inside the blue rectangle, but leave a 32 pixel margin at the top.

We may want something similar to the following image:

To do this, an additional container can be added as shown in the following image:

In this case, the container has the following relevant properties:

• Y = 0 (so it is pressed against the bottom)

• Y Units = Pixels From Bottom (so it is bottom justified)

• Height

The green rectangle can be added as a child to the container, and then centered within the container. This results in the green rectangle always being centered within the area that leaves a 32 pixel margin at the top even if the main rectangle is resized, as shown in the following animation:

Additional margin can also be added to the bottom by changing the container's Y value. For example, a 20 margin border can be added at the bottom, leaving a 32 pixel margin at the top by setting the following values on the container:

• Y = -20 (move the bottom of the container up by 20 pixels)

• Height = -52 (leaving a 32 pixel margin at the top, and accounting for the container being moved up an extra 20 pixels)

Stacks can be centered horizontally or vertically. To center a stack of objects, an internal container is needed.

A centered stack might look like this:

For this example, we'll begin with a Container and a background ColoredRectangle. The background is not necessary, but it helps visualize the main Container's size.

Next we'll add another container which will hold our stacking instances.

1. Drag+drop a container onto the MainContainer

2. Click the Alignment tab

3. Click Anchor Center

We can add children to the container:

1. Set the inner container's Children Layout to Top to Bottom Stack

2. Drag+drop children onto the inner container to have them stack

3. Optionally adjust the Stack Spacing variable to add gaps between the children

For this example I modified each child rectangle to have

• Width = 128

• Height = 32

• Color = Green

Finally, we mark the inner container to be sized according to its children. Since it remains centered, whenever its size adjusts (by adding or removing children), the inner container adjusts to remain centered.

Now if children are added or removed, the container remains centered.

Introduction

Components are reusable objects which can contain instances of other components and of standard objects. Examples of components include:

• Health Bars

• Buttons

• Popup Menus

Components can also be simple such as a button or more complex UI elements such as a full Options menu with dozens of instances.

Components can be made from-scratch or can be imported. Gum provides a full set of components for common controls including Button, TextBox, and ListBoxes, but for this tutorial we will be exploring how to build a component from scratch.

The first step in creating a component is to add an empty component and name it:

1. Right-click on the Components folder in Gum and select Add Component

2. Name the Component "HealthBar" (no spaces)

Next we'll add two Rectangle instances. One will be used as the background for the health bar, and one will be used as the fill for the health bar.

1. Drag+drop a Rectangle from the Standard folder into your Health Bar

2. Repeat this again to create a 2nd rectangle

If you dragged the instances on the tree view, the two Rectangle instances will overlap. We will adjust their positions later in this tutorial.

Next we'll rename the instances so their names match their purpose. Rename the first rectangle Background and the second Fill. You can press F2 or change an instance name in its Name text box in the Variables tab.

In this case, since Fill comes after Background, then it will draw on top. This ordering will become important when we make changes to these two instances later in the tutorial.

If you renamed them in the wrong order, you can also adjust their order in the component by selecting one of the instances, holding down the Alt key, and then pressing the up or down arrows to reorder the selected instance. You can also drag+drop to reorder, but be careful to not create an accidental parent/child relationship between the instances.

Next we'll adjust the Background Rectangle:

1. Select Background

2. Check the Is Filled variable

3. Set Fill Color to black - click on the colored box to open the color editor, or you can type the hex value 000000

Now the Background should be a solid black background to the entire component

Before moving on, you might want to spend some time adjusting values on your background. Although we removed the stroke and changed the background to black, you may want your HealthBar to have a different appearance. Try changing other values to get a feel for the different options provided by Rectangles.

Also, note that we clicked the Fill Dock button. This button is a shortcut which changes a number of variables on the component. Specifically this changed:

• X, X Units, X Origin - the background will always be positioned horizontally according to its parent's center

• Y, Y Units, Y Origin - the background will always be positioned vertically according to its parent's center

• Width, Width Units - the background will always grow or shrink horizontally to fill its parent

• Height, Height Units - the background will always grow or shrink vertically to fill its parent

For more information on docking, see the .

Next we'll adjust our Fill Rectangle, starting with its color:

1. Select Fill

2. Check the Is Filled variable

3. Set Fill Color to a green color - the exact value doesn't matter too much so pick a color you like

Unlike Background, the Fill rectangle needs to adjust in response to display how much health a player has. Specifically, the Fill rectangle needs to always fill its parent vertically, but its width depends on a health value.

First, we can adjust the height to fill its parent. To do this, set these values:

• Set Height to 0

• Set Height Units to Relative to Parent

Height Units and Width Units can be used to adjust the size of your object relative to its parent or children. In this case the parent is the entire health bar itself. Note that we've set up our Height and Height Units to be relative to parent manually, which is exactly what was done earlier when clicked the Fill Dock button. As mentioned earlier, the Fill Dock button is just a shortcut for setting these types of values.

Next we'll adjust our fill bar so that the width is a percentage of its parent rather than an absolute value.

• Set Width to any value between 0 and 100. It should be 50 by default which is a good default

• Set Width Units to Percent of Parent

Now if we adjust the Width value, the health bar width adjusts relative to its parent.

Now that we have set up both Background and Fill to be relative to their parent's size, we can adjust the size of the HealthBar component and all of the instances should also adjust automatically.

Select the HealthBar component and set the following values:

• Set Width to 200

• Set Height to 24

Now that we have a component created, we can add instances of this component the same way we have added standard elements. To do this:

1. Create a new Screen. I'll call mine GameScreen

2. Drag+drop the HealthBar component into the Screen

You can move and resize the newly-created HealthBarInstance in your screen. Notice that Background and Fill adjust in response to size changes on health bar.

You can also create copies by pressing CTRL+C, CTRL+V. Note that newly-created instances overlap the copied instance, so you need to move pasted instances.

Although we can can change the size and position of our health bars, we are missing some very important functionality - the ability to change how much health is displayed. The next tutorial discusses how to expose variables so that each instance can be modified.

Introduction

The Gum Variables tab displays all available variables when editing an instance or element. The Variables tab exposes all variables, and is useful for making fine changes to instances, such as by moving an instance by a single pixel.

The Variables tab shows variables for the selected instance or element.

Editing Variables

Variables can be edited by changing values on the selected variable. For example, to move the text to the right, change its X value to a positive number. Press Enter or Tab to apply the changes:

Positioning Instances

Gum provides a flexible positioning system. The position of an element is a result of a number of variables. We'll go over a few here.

By default all instances are positioned by their top-left corner. For example, setting the Text instance's X and Y to 0 aligned its top-left position to the top-left of the screen (which is identified by a dotted line.

We can change the origin of the Text object by setting its X Origin and Y Origin values. Notice that if X Origin is set to Center then the Text object is positioned by its center:

You may need to pan the view in the Editor tab to be able to see the Text object. Gum provides multiple ways to pan the view:

• Press and hold the middle mouse button while the cursor is over the preview window. While the middle mouse button is down, move the mouse cursor.

• Use the scroll bars on the bottom and side of the view

• Hold down CTRL and press the arrow keys

Changing the X Origin value changes the origin of the selected instance; however, it is still positioned relative to the top-left corner of the Text instance's container - which in this case is the entire screen designated by the dotted outline rectangle.

We can change the origin that the Text is relative to by changing the X Units. By default the X Units variable is set to Pixels From Left and Y Units is set to Pixels From Top.

Changing the X Units to Pixels From Right causes the Text to be positioned on the right-side of the screen.

The X,Y, Origin, and Units values are all available for every type of element in Gum; however, these values only change the bounds. In the case of a Text object we may be interested in how the text is aligned within the bounds. The Text object offers two variables for aligning its text: Horizontal Alignment and Vertical Alignment. Changing the Horizontal Alignment to Center centers the Text within its bounds:

You may have noticed that some variables in the Variables tab have an icon next to the variable label, while others are missing this icon.

Whenever an instance does not explicitly set a variable value, it uses a default value.

Gum lets us view and edit tese values.

To edit default values:

1. Right-click on the chip for a standard type, such as the Text chip
2. Select Edit Defaults...

3. Change the values that you would like to edit

Notice the default alignment values for Text

We can make changes to the default values now that the text is selected. For example, we can change the alignment values to be right and bottom. When we are editing any standard, the default values are displayed in the Editor tab so we can see these changes in real time.

Now if we select the TextIntance we will see that the Vertical Alignment is using the Bottom value; however the Horizontal Alignment is still using Center - this is because a value that is explicitly set on an instance will always override the default value set in the Standard element. Notice that Horizontal Alignment has an icon (indicating a custom value) and Vertical Alignment has no icon (indicating a default value).

Values can be reverted back to their default simply by right-clicking on the variable name in the Variables tab and selecting Make Default

You can undo the changes that you made to Standard Text by editing the defaults again and making the changes back to being top-left, or first editing defaults then pressing CTRL+Z to undo the changes.

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.

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.

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.

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.

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

This document walks through creating a behavior from scratch, using a ButtonBehavior-style definition as a familiar illustration. You would not actually recreate ButtonBehavior in a real project — it already exists - but the same steps apply to any custom behavior you define for your own components.

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

For example, the ButtonBehavior may have the following:

• ButtonCategory (Category)

  • Enabled (State)

  • Disabled (State)

  • Focused (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

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.

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.

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.

The standard Forms behaviors ship with Behavior Properties (see ) that surface a Behavior category in the Variables tab and drive design-time preview. A custom behavior can declare these too, but there is currently no tool UI for it - they are added by hand-editing the behavior's .behx file. This is an advanced, rarely-needed scenario; the standard Forms behaviors already cover the common cases.

Introduction

By default, a new Gum project has no behaviors. The most common way behaviors enter a project is automatically: adding Forms controls (Button, TextBox, Slider, and so on) adds their matching behaviors for you - see Default Behaviors below.

Creating or editing behaviors yourself is an advanced, rarely-needed scenario. The vast majority of projects only ever use the behaviors that Forms controls bring in automatically.

A behavior defines requirements that are reusable across multiple components: required categories and states, required instances, and optionally Behavior Properties - design-time properties that surface in a Behavior category in the Variables tab and connect to properties on the runtime Forms control (such as TextBox's TextWrapping or Slider's Minimum/Maximum). Behavior Properties are covered in Behavior Properties below. If a component uses a behavior, then the component is forced to include categories and instances according to the behavior definition.