Gum projects can be loaded in a game project. Gum projects are made up of multiple filesincluding:

• .gumx - the main Gum project

• .gusx - Gum screen files

• .gucx - Gum component files

• .gutx - Gum standard element files

• .png - image files

• .fnt - font files

Creating a Gum Project

Before creating a Gum project, it is recommended that you already have a functional MonoGame project with a Content folder.

If you haven't already downloaded it, you should down the Gum tool. See the Introduction page for information on downloading Gum.

To create a Gum project:

1. Open the gum tool

2. Select File->Save Project

3. Navigate to the Content folder of your game. If desired, create a sub-folder under the Content folder

4. Save the project - this will save multiple files under the Content folder

Adding the Gum Project Files to Your .csproj

To add the files to your .csproj:

1. Open your .csproj file in a text editor

2. Add a line to copy all files in the Gum project folder including the .gumx file itself. For an example, see the .csproj file for the MonoGameGumFromFile project: https://github.com/vchelaru/Gum/blob/0e266942560e585359f019ac090a6c1010621c0b/Samples/MonoGameGumFromFile/MonoGameGumFromFile/MonoGameGumFromFile.csproj#L37 Your .csproj may look like this:
3. Verify that all gum files (see the extension list above) are marked as Copy if newer in Visual Studio

The example above copies the entirety of the content folder to the output folder by using wildcards. If you do not want every file copied over, you can be more selective in what you copy by including only certain file types. For more information about wildcard support in .csproj files, see this page on how to include wildcards in your .csproj:

https://learn.microsoft.com/en-us/visualstudio/msbuild/how-to-select-the-files-to-build?view=vs-2022#specify-inputs-with-wildcards

Loading a Gum Project

To load a Gum Project:

1. Open Game1.cs

2. Modify the Initialize method so that it has the following lines after initializing SystemManagers:

var gumProject = GumProjectSave.Load("GumProject.gumx");
ObjectFinder.Self.GumProjectSave = gumProject;
gumProject.Initialize();

// This assumes that your project has at least 1 screen
gumProject.Screens.First().ToGraphicalUiElement(
    SystemManagers.Default, addToManagers:true);

Note that the ToGraphicalUiElement method has an addToManage parameter which determines whether the GraphicalUiElement is added to managers. If a GraphicalUiElement is not added to managers, it will not appear on screen.

Alternatively, the AddToManagers method can be explicitly called as shown in the following code:

var gumScreen = gumProject.Screens.First().ToGraphicalUiElement(
    SystemManagers.Default, addToManagers:true);

// AddToManagers provides more control, such as delaying addition, or adding 
// a GraphicalUiElement to a Layer
gumScreen.AddToManagers(SystemManagers.Default, layer:null);

For an example of a Game1.cs file which loads a project file, see the MonoGameGumFromFile: https://github.com/vchelaru/Gum/blob/0e266942560e585359f019ac090a6c1010621c0b/Samples/MonoGameGumFromFile/MonoGameGumFromFile/Game1.cs#L76-L82

Note that calling ToGraphicalUiElement creates a GraphicalUiElement (Gum object) from the first screen. You can inspect the gumProject.Screens file and select which screen you would like to create if your project has mutliple Screens.

You can access elements within the screen by accessing the GraphicalUiElement that is created, as shown in the following code:

// Load the gum project (see code above)
var screen = gumProject.Screens.First().ToGraphicalUiElement(
  SystemManagers.Default, 
  addToManagers:true);

// Items in the screen can be accessed using the GetGraphicalUiElementByName method:
var child = screen.GetGraphicalUiElementByName("TitleInstance");

// All GraphicalUiElements have common properties, like X:
child.X += 30;

// you can also set properties which may not be common to all GraphicalUiElements,
// like Text:
child.SetProperty("Text", "Hello world");

A full Game1 class which loads a project might look like this:

public class Game1 : Game
{
    private GraphicsDeviceManager _graphics;

    // Gum renders and updates using a hierarchy. At least
    // one object must have its AddToManagers method called.
    // If not loading from-file, then the easiest way to do this
    // is to create a ContainerRuntime and add it to the managers.
    GraphicalUiElement Root;

    public Game1()
    {
        _graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";
        IsMouseVisible = true;
    }

    protected override void Initialize()
    {
        SystemManagers.Default = new SystemManagers();
        SystemManagers.Default.Initialize(_graphics.GraphicsDevice, fullInstantiation: true);
        FormsUtilities.InitializeDefaults();

        var gumProject = GumProjectSave.Load("GumProject/GumProject.gumx");
        ObjectFinder.Self.GumProjectSave = gumProject;
        gumProject.Initialize();
        FormsUtilities.RegisterFromFileFormRuntimeDefaults();

        FileManager.RelativeDirectory = "Content/GumProject/";

        // This assumes that your project has at least 1 screen
        Root = gumProject.Screens.First().ToGraphicalUiElement(
            SystemManagers.Default, addToManagers: true);

        base.Initialize();
    }

    protected override void Update(GameTime gameTime)
    {
        if (IsActive)
        {
            FormsUtilities.Update(this, gameTime, Root);
        }

        SystemManagers.Default.Activity(gameTime.TotalGameTime.TotalSeconds);
        FormsUtilities.Update(this, gameTime, Root);
        base.Update(gameTime);
    }

    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.Clear(Color.CornflowerBlue);
        SystemManagers.Default.Draw();
        base.Draw(gameTime);
    }
}

Gum Projects in Different Folders

The code above and most samples in the Gum repository assume a Gum project located in the Content folder. If you are placing your Gum project in a subfolder, you need to set the FileManager.RelativeDirectory to the sbufolder prior to calling ToGraphicalUiElement. For example:

FileManager.RelativeDirectory = "Content/MySubFolder/";

var screen = gumProject.Screens.First().ToGraphicalUiElement(
  SystemManagers.Default, 
  addToManagers:true);

For a more detailed discussion on file loading and file locations, see the File Loading page.

Troubleshooting Gum Project Loading

If your Gum project load results in an exception, you can inspect the exception message for information about the failure. The most common type of failure is a missing file reference.

If you are missing files, you may have not set up the file to copy to the output folder. The following screenshot shows an incorrect setup - the CardInstance.gucx file is not copied, but it probably should be:

This can be changed to copy in Visual Studio, or the .csproj can be modified to include wildcards for copying files over, which can make maintenance easier as the project grows. See the section above for information and examples on setting up your project loading.

Introduction

Custom runtimes allow the creation of custom classes which are created when loading your Gum project. The use of custom runtimes is especially important if you are developing UI which should respond to user interactions such as clicks or if you are using Gum Forms.

In the context of Gum, a runtime is a class which handles interaction with a Gum component or screen while your game is running. The term runtime is used to distinguish between an object used at runtime (such as a ), or the Gum element (such as ).

Custom runtimes can encapsulate functionality and can be used to build any time of UI including simple UI such as Buttons and Checkboxes, or more complex UI such as ListBoxes or ComboBoxes.

Custom Runtimes GraphicalUiElement-Inheriting Classes

Custom runtimes are classes which you define which inherit from GraphicalUiElement or InteractiveGue. If your runtime needs custom logic but does not respond to user actions then you should use GraphicalUiElement as your base. If your runtime responds to user actions such as clicks, then you should use InteractiveGue as your base. If you are defining a custom runtime to be used as the Visual for Gum Forms, you should also inherit from InteractiveGue.

This tutorial uses InteractiveGue as a base since responding to clicks is the most common reason for creating a custom runtime, and such an object would be suitable for Gum Forms.

The InteractiveGue class inherits from GraphicalUiElement, but adds additional logic for raising events on common mouse actions. These actions are exposed as public events which can be subscribed internally in your InteractiveGue-inheriting class or externally per-instance. This tutorial shows how to handle events both internally and externally.

Defining a Custom Runtime

Custom runtimes fall into one of two categories:

1. Runtimes defined fully in-code

2. Runtimes defined in a Gum project

If a custom runtime is defined fully in code, then it must instantiate its own children. Typically these instances are added in a constructor.

Alternatively if a custom runtime is loaded from a Gum project, then it should not define its children since those will come from the loaded Gum project. However, it may need to access those children. It can do so in the AfterFullCreation method.

Example - Custom Runtime Defined in Gum

The following code shows how to create a custom runtime from Gum. Often times custom runtimes are used for Gum object, so using the standard 2-argument constructor and creating Gum objects is recommended as shown in the following code:

Note that this type of control is assumed to be used as a Forms Button, so it includes the instantiation of a Forms button.

Custom Runtimes for Screens

Custom runtime classes can be created for screens using the same approach as components. Typically custom runtimes for screens inherit from GraphicalUiElement rather than InteractiveGue since the screen itself does not need click events.

The following code is an example of a custom runtime for a screen which contains a text instance named TextInstance:

This type is registered using ElementSaveExtensions:

Calling ToGraphicalUiElement on the StartScreen results in an instance of the StartScreenRuntime being created.

Associating a Gum Component to a Runtime

Once a custom runtime is defined, it needs to be associated with a Gum component. For example, consider a component named StandardButton inside a Buttons folder.

Notice that the name StandardButton does not match the name ClickableButton, and this is often not desirable.

To associate StandardButton with ClickableButton, add the following code before calling ToGraphicalUiElement:

Now whenever ToGraphicalUiElement is called, all instances of StandardButton will be instantiated as a ClickableButton rather than the default GraphicalUiElement.

Using Cursor to Enable Events

If using InteractiveGue, the built-in events are only called if DoUiActivityRecursively is called either directly on the component, or on a parent of the component. Usually DoUiActivityRecursively is called in the context of using Forms, so it is recommended to do so using the FormsUtilities object. By using FormsUtilities you can reduce the amount of code needed for interactivity.

We can add FormsUtilities to our code as shown in the following snippet:

After adding the FormsUtilities calls, all events on any InteractiveGue will automatically be raised so long as the InteractiveGue is part of the hierarchy owned by the CurrentScreen.

Adding Events Per Instance

Events often need to be customized per instance. For example, a game's MainMenu screen may have buttons for starting the game, going to the options screen, or exiting the game.

The following code shows how to add events to runtime instances. This code assumes that each runtime instance is using a Runtime that inherits from InteractiveGue.

This page assumes you have an existing MonoGame project. This can be an empty project or an existing game.

At the time of this writing Gum + MonoGame has been tested on a variety of platforms including DesktopGL, DirectX, and mobile. It has also been used with Nez and Kni. If your particular platform is not supported please contact us on Discord and we will do our best to add support.

Adding Gum NuGet Packages

1. Open your MonoGame project in your preferred IDE.

2. Add the Gum.MonoGame NuGet package

Initializing Gum

1. Open your Game class (usually Game1.cs)

2. Add the following code to your Initialize method: SystemManagers.Default = new SystemManagers(); SystemManagers.Default.Initialize(_graphics.GraphicsDevice, fullInstantiation: true);

3. Add the following to your Update method: SystemManagers.Default.Activity(gameTime.TotalGameTime.TotalSeconds);

4. Add the following to your Draw method after you clear the graphics device: SystemManagers.Default.Draw();

Testing Gum

To test that you have successfully added Gum to the project, add the following code to your Initialize method after SystemManagers.Default.Initialize:

If everything is initialized correctly, you should see a white rectangle at the top-left of the screen.

Loading Gum Projects

Downloading the Gum Tool

Introduction

Gum provides a GumBatch object which works similar to SpriteBatch. It can be used for immediate mode rendering, which allows for calling Begin, Draw, and End just like SpriteBatch. This is useful if your project requires mixing Gum and MonoGame rendering, or if you are more comfortable using a SpriteBatch-like interface.

This page assumes you have an existing MonoGame project. This can be an empty project or an existing game.

Usage of GumBatch is completely optional, and it is only needed if you want to draw Gum objects at a partciular point in your drawing code. If you are using Gum to load .gumx projects, or if you would like Gum to handle all UI or HUD rendering, then you do not need to use GumBatch.

Adding Gum NuGet Packages

1. Open your MonoGame project in your preferred IDE.

2. Add the Gum.MonoGame NuGet package

GumBatch Quick Start

To initialize a GumBatch, you must:

• Declare a GumBatch at class scope

• Initialize the Gum SystemManagers - this is needed whether you use GumBatch or the full Gum retained mode rendering system

• Initialize the GumBatch

• (optional) load a .fnt file

• Draw with gumBatch in your Draw

The following shows a simple Game1.cs file which renders Gum Text:

This code produces the following image:

Note that this code assumes a font .fnt file (and matching .png) are in the Content/Fonts/ folder. All content is loaded relative to the Content folder, just like normal content in MonoGame. Also note that this content does not use the content pipeline, but must be set to Copy to Output.

Introduction

GumBatch is an object which supports immediate mode rendering, similar to MonoGame's SpriteBatch. GumBatch can support rendering text with DrawString as well as any IRenderableIpso.

For information on getting your project set up to use GumBatch, see the page.

Rendering Strings

GumBatch can be used to render strings directly. This requires a BitmapFont.

The following code renders a string at X = 100, Y=200:

Multiple strings can be rendered between Begin and End calls:

DrawString can accept newlines and color the text:

Rendering TextRuntimes

If your text rendering requires more advanced positioning, wrapping, rotation, sizing, and so on, you can use TextRuntime instances.

TextRuntimes can be used in both GumBatch as well as they can be added to the SystemManagers if you use SystemManagers.Draw (retained mode).

The following code shows how to create a TextRuntime instance and render it using GumBatch:

Rendering Parent/Child Hierarchy

GumBatch.Draw renders any argument renderable object. If the object has children, then the Draw call performs a hierarchical draw, respecting the parent/child relationship to control draw order.

For example, the following code creates a parent ColoredRectangleRuntime and a child TextRuntime:

Since the Draw call is only called on the Parent, then only the Parent reference is kept at class scope:

RenderTargets

GumBatch can be used to render Gum objects on RenderTarget2Ds, just like regular SpriteBatch calls.

The following code shows how to render on a RenderTarget:

Note that if you are rendering multiple objects on a render target, the BlendState must be set as to add the transparency. Using the default BlendState may result in alpha being "removed" from the render target when new instances are drawn.

The following shows how to create a BlendState for objects which have partial transpraency and are to be drawn on RenderTargets:

Introduction

UI events may require interacting with systems that are async by default (return Tasks). MonoGame projects do not have a default synchronization context for keeping async code on the primary thread, but this can be added fairly easily.

This tutorial shows how to add and work with a synchronization context to allow async calls without leaving the primary thread. The MonoGameGumFromFile project shows how to add a synchronization context. You can view this project .

Why is a Synchronization Context Needed?

When a method makes an async call, its continuation is not guaranteed to be on the same thread as the code preceding the async call. For example, consider the following code:

Unfortunatey, the code above may end up crashing or having other unexpected behaviors since the Button's IsEnabled is potentially being assigned on a non-primary thread. This is problematic because the UI may get updated mid-update, causing unexpected results.

Instead, we would like to keep all methods on the primary thread so that we can confidently interact with the UI without worrying about making changes mid-render.

Adding the SingleThreadSynchronizationContext

The MonoGameGumFromFile sample includes a class called SingleThreadSynchronizationContext which provides a simple synchronization context for keeping all async call continuation on the primary thread. You can download the file and add it to your project from here:

Once you have added it to your project, you need to add an instance to your Game class, initialize it in your Initialize method, and call its Update method in the Game's Update, as shown in the following code snippet:

After adding the SingleThreadSynchronizationContext class and after modifying your Game class as shown above, you can make async calls safely.

Keep in mind that the SingleThreadSynchronizationContext class can be modified for your own needs if you are comfortable making these changes.

MonoGame projects can take full advantage of the Gum tool and runtimes to create flexible layouts which are useful for HUDs, Menus, and UI of any complexity.

The Gum UI Tool is a WYSIWYG editor for creating layouts. Projects that are created in the Gum UI tool can be loaded into your MonoGame project with just a few lines of code.

The Gum runtime (called MonoGameGum) is a NuGet package which adds the classes necessary to load and interact with Gum projects.

Do I Need to Use the Gum Tool?

Absolutely not! The Gum tool can be useful for doing complex layouts, previewing how things may be positioned, and helping you learn how to code with Gum - but it is not required! You can use Gum purely in code to do your own layouts or use only parts of Gum (such as font rendering).

This section uses screenshots of the Gum tool so you can see what is possible with Gum, but everything you see here can also be done purely in code.

Sample Projects

If you prefer to dive in and see things working, the Gum repository includes sample projects that show how to work with Gum purely in code, and also how to load a Gum project into a MonoGame project.

You can clone the repository and open the projects in your favorite IDE (like Visual Studio) and try them out.

The direct link to the samples is here:

For more information about the Sample projects, see the .

What is the Gum UI Tool?

The Gum UI Tool (usually called "Gum") is a visual editor for creating layouts using the Gum layout engine. Gum has been used on many commercial games to create all types of UI ranging from standard game HUDs to complex forms-based UIs. Gum can be used for any type of game.

The Gum tool is simple to use - you can create your screens by drag+dropping, moving, and resizing objects with the mouse.

Gum is an object oriented design tool, so projects can contain reusable components which contain other components and standard elements (text, sprite, container, etc). Gum also provides inheritance, and behaviors (a concept similar to interfaces in C#). For example, the following PauseMenu component inherits from UserControl - a base type defining the standard visuals for a framed UI element.

What is the Gum Layout Engine

The Gum Layout Engine is the core technology behind the Gum UI Tool and the Gum MonoGame runtimes. Gum layouts use a few rules to determine the position and size relationships between parents and children. These rules allow for the creation of virtually any type of layout.

Projects which perform their layouts purely in code can still take advantage of the Gum UI Tool to preview their layouts and to learn about the capiblities of the GraphicalUiElement (the C# object type providing access to all Gum properties).

By default, Gum elements are positioned relative to the top-left of their parent. Similarly, the origin of a Gum element is also its own top-left corner. Therefore, a rectangle that has an X of 100 and a Y of 50 appears as shown in the following image:

The Gum tool helps you visualize the relationship between a child and its parent when the child is selected. Notice that the child draws a line from its origin (its top-left corner) to the top left of its parent. In this case the parent is the entire screen, which has a dotted outline.

A child's position is relative to its parent's position, so changing the position of the parent ultimately changes the absolute position of its child as well. The following animation shows a parent container which has a white rectangle as its child. Notice the child can be moved relative to the parent. If the parent is moved, then the child's absolute position changes as well.

This basic type of layout is similar to layouts provided by most visual APIs including SpriteBatch in MonoGame.

The Gum layout engine is built around the concept of "units". As mentioned above, by default the X and Y values of an element is measured in units from the top-left corner. In other words, the default X Units is absolute pixels from left for X and absolute pixels from top for Y. The Gum tool exposes this as a set of buttons.

At runtime, these properties exist as enums which can be changed. For example, to set an element's XUnits to be relative to the horizontal center of its parent, the following code can be used:

As mentioned above, the Gum tool is very useful for testing out how different properties behave quickly. For example, the following animation shows how X and X Units can be used to change the position of an object relative to its parent:

The position, units, and origin values can be used to create common layouts. The following code could be used to center a child in its parent:

This same layout could be achieved in the Gum UI tool by setting the following values:

• X = 0

• X Units = Pixels from Center

• X Origin = Center

An element's size can also be controlled through units. For example, a child rectangle could set to provide an 8 pixel border inside of its parent container using the following code.

Similarly, the following could be done in the Gum UI tool::

• X = 0

• X Units = Pixels from Center

• X Origin = Center

• Y = 0

• Y Units = Pixels from Center

• Y Origin = Center

• Width = -16

• Width Units = Relative to Container

• Height = -16

• Height Units = Relative to Container

Note that the Width and Height are set to -16, which is twice the desired border. This is because the border of 8 pixels must appear on both the left and right sides for Width and both the top and bottom sides for Height.

Notice that each of these properties combines to produce a center layout. While this may seem verbose, this type of fine control provides ultimate flexibility. You aren't limited to simple alignments such as left, right, and center. Rather, you can create layouts where any part of the object is positioned relative to any other part of its parent.

This type of center layout is responsive to changes in the parent, so if the parent changes position or size, the child moves along with it as expected.

Hierarchies can go many levels deep, and each parent child relationship follows the same rules. For example, the following animation shows a relationship where the blue and red children occupy the left and right half of the white rectangle, including a border of 8 pixels around and inbetween the rectangles. Notice that changing the parent size automatically cascades size and position changes to the children.

Children are in control of their own layouts using "unit" values, but parent elements can also apply rules to control layout by setting the Children Layout property. For example, a parent can stack its children from top-to-bottom by setting Children Layout to Top to Bottom Stack. Notice that changing the stacking from top-to-bottom changes the Y positioning of the children. The X position is intentionally staggered to be able to see the position of each rectangle when stacking is turned off.

Children can still control their position values relative to the stacking, so a child can change its X and Y value. If a child changes its Y or Height value in a Top to Bottom Stack, then subsequent children are adjusted react to this change immediately.

Stacking can be combined with wrapping and stack spacing to create list boxes and inventory grids quickly.

Layout dependencies can go from parent-> child and child-> parent to create powerful layouts. We recommend that new users spend some time in the Gum UI Tool to see what can be created and to browse the documentation to see more example images and animations.

What's Next?

If you're ready to use Gum, then head on over to the Setup page. The MonoGame section provides information specific to MonoGame, but the rest of the Gum documentation site provides information which applies both to the Gum UI Tool and coding of Gum in MonoGame projects.

Introduction

The easiest way to use Gum is to add the NuGet packages to your game project. Alternatively you can link your game to Gum source for additional debugging, to stay up to date with the latest improvements, or if you are interested in contributing.

This document assumes you already have a game project with the Gum NuGet packages linked.

Linking Soruce

If you have followed the Setup steps, then you should have a game which references the Gum NuGet package.

To replace this package with source references:

1. Clone the Gum repository

2. Remove the NuGet package by selecting Gum.MonoGame and pressing the Delete key.

3. Right-click on your Solution in the Solution Explorer and select Add -> Existing Project...

4. Select <Gum Root>/MonoGameGum/MonoGameGum.csproj

5. Repeat the previous step but select the following csproj files:

   1. <Gum Root>/GumCommon/GumCommon.csproj

   2. <Gum Root>/GumDataTypes/GumDataTypesNet6.csproj

   3. <Gum Root>/ToolsUtilities/ToolsUtilitiesStandard.csproj
6. Right-click on your game project's Dependencies folder and select Add Project Reference...

7. Check the Gum projects you added to the solution earlier and click OK

You are now fully linked to source. You can build and run your game.

Introduction

Gum Forms is a set of classes which provide fully-functional forms controls which you can use in your game. Examples of forms controls include:

• Button

• Checkbox

• ListBox

• TextBox

• Slider

Gum Forms can be used purely in code (no .gumx project required), or you can fully style your forms objects in a Gum project.

Quick Setup - Forms in code

The easiest way to add Forms to your project is to use the FormsUtilities class. Keep in mind that Forms is not a replacement for Gum; rather, it adds objects on top of Gum which provide common UI interaction. In other words, if you are using Forms, you are still using Gum as well. Therefore, when using Forms you must also initialize Gum.

The following code snippet shows how to initialize Forms and Gum, and how to add a single Button to your project:

The code above produces a single button which can be clicked to increment the click count.

Quick Setup - Forms in the Gum Tool

Forms can be used with the Gum tool, allowing you to create fully functional UI layouts visually.

To use Forms in a project that loads a Gum project (.gumx) the following steps are needed:

1. Components must be added to the Gum project which have the necessary behaviors to be used as Forms visuals

2. The Gum project must be loaded in code, just like any other Gum project

Adding Forms Components to the Gum Project

To add components which are used for Forms visuals:

1. Open your project in Gum, or create a new project

   1. If creating a new project, save the project in a subfolder of your game's Content folder

2. Select Content -> Add Forms Components
3. Check the option to include DemoScreenGum, or alternatively add a new screen to your project and drag+drop the desired components into your screen

Once you have saved your project, modify your Gum file to include the project:

1. Open your .csproj in a text editor (or click on it in Visual Studio)

2. Add the wildcard addition code to copy all of your Gum projects

Your project is now referenced in your game. Modify the Game file to initialize the Gum systems and to load the .gumx project. Your code might look like this:

Introduction

The static ModalRoot and PopupRoot properties provide an InteractiveGue which serve as the root for any element which should appear on top of other elements. These properties have the following characteristics:

• Automatically created by FormsUtilities.InitializeDefaults

• Automatically resized to fit the entire screen, including if the GraphicalUiElement.CanvasHeight and GraphicalUiElement.CanvasWidth change.

• Both Remains on top of all other elements for its given layer. ModalRoot appears on top of PopupRoot.

These properties can be used in custom code to place elements (such as custom popup and toast elements) above all other elements.

Modal Popups

Popups which are placed on the ModalRoot element are considered modal - they block the input of all other controls. This is useful if you would like to create a popup which must be clicked before any other elements receive input. If multiple elements are added to ModalRoot, only the last item (and its children) receive input events. This allows one popup to show another popup.

By contrast, elements added to the PopupRoot are not modal - other elements can receive input.

Example - Adding a Popup

The following code can be used to display a popup to either ModalRoot or PopupRoot depending on the isModal value.

Introduction

FrameworkElement is the base class for all Gum Forms controls. It provides much of the common functionality across all controls.

Introduction

The IsFocused property gets or sets whether a component has focus. For example a TextBox will have its IsFocused set to true if the caret is visible and if it is taking input from the keyboard.

Code Example - Setting IsFocused

IsFocused can be directly assigned to give focus to an object. For example the following code gives a TextBoxInstance focus:

TextBoxInstance.IsFocused = true;

If you are setting focus on a TextBox in response to a click event, you may need to also clear the Cursor's input. For example, the following would set focus on TextBoxInstance when ButtonInstance is clicked:

ButtonInstance.Click += (_,_) =>
{
    TextBoxInstance.IsFocused = true;
    // Remove the clear so that the TextBoxInstance doesn't immediately lose focus
    // on the same frame it got focus due to the cursor having been clicked
    FormsUtilities.Cursor.ClearInputValues();
};

Introduction

IsEnabled controls whether the framework element responds to input from the user. Many controls reflect whether they are enabled visually, so a disabled element (such as a Button) appears differently than an enabled button.

Introduction

The ListBox control provides a scrollable list of ListBoxItems for displaying and selecting from a list.

Code Example: Adding a ListBox

The following code adds items to a ListBox when a button is clicked. When an item is added, ScrollIntoView is called so the item is shown.

var listBox = new ListBox();
this.Root.Children.Add(listBox.Visual);
listBox.X = 50;
listBox.Y = 50;
listBox.Width = 400;
listBox.Height = 200;

var button = new Button();
this.Root.Children.Add(button.Visual);
button.X = 50;
button.Y = 270;
button.Width = 200;
button.Height = 40;
button.Text = "Add to ListBox";
button.Click += (s, e) =>
{
    var newItem = $"Item @ {DateTime.Now}";
    listBox.Items.Add(newItem);
    listBox.ScrollIntoView(newItem);
};

Selection

ListBox items can be selected. The ListBox class provides a number of ways to work with the selection.

Selection can be set by index:

listBox.SelectedIndex = 0;

Item can also be selected by the reference itself, assuming the referenced item is part of the list box:

listBox.SelectedObject = "English";

Whenever the selection changes, the SelectionChanged event is raised:

listBox.SelectionChanged += (sender, args) =>
{
    System.Diagnostics.Debug.WriteLine($"Selected item: {listBox.SelectedObject}");
};

Customizing with VisualTemplate

The VisualTemplate lets you customize the type of ListBoxItem created for the ListBox. The following code shows how to assign a VisualTemplate to a runtime object named CustomListBoxItemRuntime:

// assign the template before adding new list items
listBox.VisualTemplate = 
    new MonoGameGum.Forms.VisualTemplate(() => 
        // do not create a forms object because this template will be
        // automatically added to a ListBoxItem by the ListBox:
        new CustomListBoxItemRuntime(tryCreateFormsObject:false));

The VisualTemplate class can optionally pass a parameter representing the item in the list box. This can be used to create different types of items based on the object added. For example the following code would compare the passed object as an integer to whether it is greater than 100 and returns a different item depending on this result:

// assign the template before adding new list items
listBox.VisualTemplate = 
    new MonoGameGum.Forms.VisualTemplate((item) => 
    {
        // Be sure you know the type before casting:
        var itemAsInt = (int)item;
        if(itemAsInt > 100)
        {
            return new CustomListBoxItemHighValue(tryCreateFormsObject:false);
        }
        else
        {
            return new CustomListBoxItemLowValue(tryCreateFormsObject:false);
        }
        
    }

Customizing Displayed Property with ListBoxItemFormsType

By default the ListBox calls ToString on each item. This is usually okay if you are dealing with primitive types. For example, the following code adds sequential integers to a ListBox:

for (int i = 0; i < 20; i++)
{
    listBox.Items.Add(i);
}

Often you may want to add a list of items which should not use their ToString method. For example you may have a list of IDs which represent weapons in a dictionary. The display can be customized by inheriting from ListBoxItem as shown in the following code:

listBox.ListBoxItemFormsType = typeof(WeaponDisplayingListBoxItem);

foreach(var weapon in weapons)
{
    listBox.Items.Add(weapon.Id);
}

// define WeaponDisplayingListBoxItem
class WeaponDisplayingListBoxItem : ListBoxItem
{
    public WeaponDisplayingListBoxItem(InteractiveGue gue) : base(gue) { }
    public override void UpdateToObject(object o)
    {
        var idAsInt = (int)o;
        // assuming this has access to Weapons:
        var weapon = Weapons[idAsInt];
        coreText.RawText = weapon.Name;
    }
}

Introduction

The ScrollViewer control provides a container which can hold Gum objects (including other Gum Forms objects). The user can scroll the ScrollViewer with the mouse or ScrollBar.

By default the ScrollViewer's InnerPanel expands automatically in response to its children and stacks its children top-to-bottom. Of course, this behavior can be changed since the InnterPanel is a standard GraphicalUiElement.

Code Example: Creating a ScrollViewer

The following code creates a ScrollViewer and adds ColoredRectangleRuntimes to the ScrollViewer.

var scrollViewer = new ScrollViewer();
this.Root.Children.Add(scrollViewer.Visual);
scrollViewer.X = 50;
scrollViewer.Y = 50;
scrollViewer.Width = 200;
scrollViewer.Height = 200;
scrollViewer.InnerPanel.StackSpacing = 2;

var random = new System.Random();
for (int i = 0; i < 30; i++)
{
    var innerRectangle = new ColoredRectangleRuntime();
    innerRectangle.X = random.NextSingle() * 150;
    // no need to set innerRectangle.Y since each rectangle stacks
    innerRectangle.Width = 30;
    innerRectangle.Height = 30;
    innerRectangle.Color = new Color(random.Next(255), random.Next(255), random.Next(255));
    scrollViewer.InnerPanel.Children.Add(innerRectangle);
}

VerticalScrollBarVisibility

VerticalScrollBarVisibility controls the visibility of the vertical scroll bar, specifically in regards to the number of items in the ScrollViewer. The available values are:

• Auto - the ScrollBar displays only if needed based on the size of the inner panel

• Hidden - the ScrollBar remains invisible even if the contents of the inner panel exceed the size of its container

• Visible - the ScrollBar always displays

The default is Auto which means that the scroll bar only displays if necessary.

Introduction

The PasswordBox control is a TextBox-like control which can be used for entering passwords. It uses a SecureString rather than regular string and hides the entered characters by using the * key for each character typed. For more information see the SecureString documentation: https://learn.microsoft.com/en-us/dotnet/api/system.security.securestring?view=net-8.0

Code Example: Adding a PasswordBox

The following code adds a password box.

var passwordBox = new PasswordBox();
this.Root.Children.Add(passwordBox.Visual);
passwordBox.X = 50;
passwordBox.Y = 50;
passwordBox.Width = 200;
passwordBox.Height = 34;
passwordBox.Placeholder = "Enter Password";

var button = new Button();
this.Root.Children.Add(button.Visual);
button.X = 50;
button.Y = 90;
button.Text = "Get Password";
button.Click += (_, _) => Debug.WriteLine(passwordBox.Password.ToString());

Introduction

The Button control providing an event for handling clicks.

Code Example: Adding a Button

The following code adds a button which increments every time it is clicked:

var button = new Button();
Root.Children.Add(button.Visual);
button.X = 0;
button.Y = 0;
button.Width = 100;
button.Height = 50;
button.Text = "Hello MonoGame!";
int clickCount = 0;
button.Click += (_, _) =>
{
    clickCount++;
    button.Text = $"Clicked {clickCount} times";
};

Introduction

The CheckBox control provides the ability to display a true/false state and allows the user to toggle the state through clicking.

Code Example: Adding a CheckBox

var checkBox = new CheckBox();
Root.Children.Add(checkBox.Visual);
checkBox.X = 50;
checkBox.Y = 50;
checkBox.Text = "Checkbox";
checkBox.Checked += (_,_) => Debug.WriteLine($"IsChecked:{checkBox.IsChecked}");
checkBox.Unchecked += (_, _) => Debug.WriteLine($"IsChecked:{checkBox.IsChecked}");

The TextBox control allows users to enter a string. It supports highlighting, copy/paste, selection with mouse and keyboard, and CTRL key for performing operations on entire words.

Code Example: Creating a TextBox

The following code creates a TextBox.

var textBox = new TextBox();
this.Root.Children.Add(textBox.Visual);
textBox.X = 50;
textBox.Y = 50;
textBox.Width = 200;
textBox.Height = 34;
textBox.Placeholder = "Placeholder Text...";

var textBox2 = new TextBox();
this.Root.Children.Add(textBox2.Visual);
textBox2.X = 50;
textBox2.Y = 90;
textBox2.Width = 200;
textBox2.Height = 34;
textBox2.Placeholder = "Placeholder Text...";

Selection

Selection can be performed programmatically or by the user using the cursor.

The SelectionLength property can be used to determine if any text is selected. The following code shows how to output the selected characters:

if(textBox.SelectionLength > 0)
{
    var selectedText = textBox.Text.Substring(
        textBox.SelectionStart, 
        textBox.SelectionLength);
    System.Diagnostics.Debug.WriteLine("Selected text: " + selectedText");
}

The SelectionStart and SelectionLength proerties can be modified to change the visual selection. For example, the following selects the first 5 letters:

textBox.SelectionStart = 0;
textBox.SelectionLength = 5;

The entire text can be selected as shown in the following code:

textBox.SelectionStart = 0;
textBox.SelectionLength = textBox.Text?.Length ?? 0; // in case text is null

Selection can also be performed by the user. Double-clicking the text box selects all text.

A push+drag with the mouse selects the text between the start and the current location of the drag.

Holding down the shift key and pressing the arrow keys adjusts the selection.

TextWrapping

The TextWrapping property can be used to set whether the TextBox wraps text. By default this value is set to TextWrapping.NoWrap which means the text does not wrap, but instead extends horizontally.

If TextWrapping is set to `TextWrapping.Wrap, then text wraps to multiple lines. Note that usually this is combined with a taller text box so that multiple lines display properly.

wrappedTextBox.TextWrapping = TextWrapping.Wrap;
// If you have set up your TextBox in code, you may need to make it taller:
wrappedTextBox.Height = 140;

Introduction

The Slider control provides a way for the user to change a value by dragging the slider thumb.

Code Example: Creating a Slider

The following code creates a Slider which allows the user to select a value between 0 and 30, inclusive. The IsSnapToTickEnabled property results in the value being snapped to the TickFrequency value. In this case, the value is used to force whole numbers.

var slider = new Slider();
this.Root.Children.Add(slider.Visual);
slider.X = 50;
slider.Y = 50;
slider.Minimum = 0;
slider.Maximum = 30;
slider.TicksFrequency = 1;
slider.IsSnapToTickEnabled = true;
slider.Width = 250;
slider.ValueChanged += (_, _) => 
    Debug.WriteLine($"Value: {slider.Value}");
slider.ValueChangeCompleted += (_, _) => 
    Debug.WriteLine($"Finished setting Value: {slider.Value}");

Introduction

Gum Forms provide fully functional controls with minimal setup. These controls can be restyled in code, either per-instance, or globally per control type. Customization can be performed in-code or in the Gum tool.

Customizing an Instance

Individual instances can be customized by modifying the built-in states which are added automatically by the default implementations.

The following code shows how to modify a Button instance. A default button can be constructed using the following code:

Notice that this button has subtle color changes when the cursor hovers over or pushes on it.

These cursor actions result in different states being applied to the button. These states are initialized by default when calling the following code:

We can customize the state by modifying the values. For example, we can change the color of the background by adding the following code:

Now the button highlights yellow instead of a lighter blue.

Any property on the button or its children can be modified through states. For example, we can also change the text color and size as shown in the following code. You may need to make the button bigger so it can contain the larger text.

The button text now becomes black and is twice as big when highlighted but notice that the text changes are not undone when the cursor moves off of the button (when the Highlighted state is unset).

The reason that the hover state is not unset is because all variables which are set through states persist until they are undone. Typically if you create states in the Gum tool, the Gum tool forces any state which is set in a category to also be propagated through all other states in the same category. However, when we're setting states in code, we must make sure to apply any states that we care to all other categories.

In this case we can fix the larger text by setting the TextInstance's color and FontScale back to its default:

Available Instances

Each default control type is made up of individual instances, most of which are standard types such as ColoredRectangle and TextInstance. The example above assigns properties on two instances:

• ButtonBackground

• TextInstance

Since each control (such as Button, CheckBox, or TextBox) has its own individual instances, we need to know the names and types of these instances to add VariableSaves to our states.

We can find the names of these instances by looking at the source code for the default forms implementations.

These can be found in the Gum repository here:

For example, we can look at the DefaultButtonRuntime.cs file and notice that it has a ButtonBackground and TextInstance:

By inspecting the code of other controls we can see which instances are available for styling. We can also look at the existing states which are provided by the default implementations. For example the DefaultButtonRuntime adds states for Enabled, Highlighted, Pushed, and Disabled. Note that this list may change in the future as Gum Forms continues to be developed.

Keep in mind that the Name property of the internal instances is important. For example using the code above, the background object is accessed through "ButtonBackground" rather than "background" when creating new states.

Replacing Styling Globally with Derived Classes

The example above shows how to replace styling on a single Button instance. Instead of changing each instance manually, we can create a derived class which defines its own custom styling.

The first step is to create a new class which inherits from the default Forms control. These can all be found in the DefaultVisuals page linked above.

For example, we can create a derived class which inherits from the base DefaultButtonRuntime as shown in the following code:

Notice that we must implement a constructor with the same parameters as the base class - this is important because Gum calls this constructor for us when we create a Button instance and the parameter list must match.

Now we can implement our own styling inside the if(fullInstantiation) block. The code to implement styling here is the same as above except this object is the visual, so the category exists on this. For example, we can make the background pink when highlighted and enabled as shown in the following code:

Next we need to tell Gum Forms to use our new button as the default Button type. We can do this by replacing the default type associated with Button as shown in the following code. This code should go in Game1 right after FormsUtilities.InitializeDefaults();, before instantiating any Buttons as shown in the following code:

You may want to also remove or comment out any code for customizing the button explicitly below otherwise your pink styling may get overwritten on the particular instance by the styling written earlier in this tutorial.

By instantiating a Button, Forms automatically uses your new StyledButtonRuntime resulting in the button appearing pink.

Defining a ButtonRuntime Without Inheritance

The section above shows how to customize a button using inheritance. This approach is beneificial if you would like to modify the styling colors on the existing children of the button. Since Gum visuals are regular Gum objects, you can achieve even more customization by creating a new Button class which inherits from InteractiveGue and adding your own controls. In other words, you can add your own instances to the button (such as additional Text instances) or replace existing instances with your own (such as replacing the background ColoredRectangleRuntime with a NineSlice or Sprite).

For example, we can create a NineSlice that uses the following image:

Now we can create a new Button which inherits from InteractiveGue rather than DefaultButtonRuntime to fully customize the appearance of our button. Note that the only requirement that Buttons have is that they contain a Text object named TextIntance, so we should copy this instance from the DefaultButtonRutime code into our own. Our new Button also has a NineSlice which references the button_square_gradient.png from above, and states for Enabled and Pressed.

In general when creating your own Forms control, it can be helpful to reference the existing Default implementation for the control you are creating.

Of course we also need to tell Forms to use our new class as the default button type:

Now we can run our game and see the button in action:

As mentioned above, you are free to add any controls to your custom button including icons, additional Text instances, and additional Sprites for other effects. You can customize your Forms objects to look however you want.

Available States

Most controls in Forms share the same common states. The exception is components which can be toggled on/off such as CheckBox. For all other controls the following states exist:

• Enabled

• Disabled

• Highlighted

• Pushed

• Focused

• HighlightedFocused

• DisabledFocused

CheckBoxes append the words On, Off, and Indeterminate to the states. For example, a CheckBox can support states including:

• EnabledOn

• EnabledOff

• EnabledIndeterminate

• DisabledOn

• DisabledOff

• DisabledIndetermate

• ... and so on.

Defining a Custom Runtime from Gum

Buttons can be defined fully in the Gum tool. This approach allows you to preview your visuals in the editor, and allows editing of the styles without writing any code.

Conceptually the steps are as follows:

1. Define a component for your forms type in the Gum tool

2. Add the states needed for the forms type that you are working with in the proper category

3. Define a custom runtime for the Forms control in your Visual Studio project

4. Associate the custom runtime to the forms type using the DefaultFormsComponents dictionary

This section walks you through how to create a custom Button component, and how to use this in your project. Once you understand how to create a Button component, other Forms controls can be created similarly.

Defining a Button Component in Gum

The first step is to define a Button component in Gum. This component can be named anything you want. For example, you may name it Button or StandardButton. You can also create components for specific purposes such as CloseButton which would be a button that closes menus.

Components defined in Gum can contain almost anything you want; however, Buttons should usually contain a TextInstance so that the Text property can assign the string on an internal Text object.

The following image shows the a component named StandardButton which contains a ColoredRectangle, a Rectangle, and a Text instance. For other controls, see the DefaultVisuals page linked above.

Adding Button States to the Component

All Gum Forms components react to various properties by assigning states. For a full list of states needed, see the DefaultVisuals page linked above.

Defining a Custom Runtime for the Forms Control

Once you have created a Component in your project, you need to create a custom runtime class. This custom runtime class associates the Component in your .gumx file to a strongly-typed class. This runtime type also enables the creation of Forms controls by instantiating the runtime object, including when an element from the Gum project is converted to a GraphicalUiElement.

The runtime class does not need much code since most of the work is done in the Gum project. The following shows an example custom runtime for the StandardButton component:

This runtime can be associated with the StandardButton component in Gum using the following code in your Game class:

Associate the Custom Runtime to the Forms Type

Finally, we can associate the Forms control with the runtime. For example, the following code can be used to create a StandardButtonRuntime whenever the code calls new Button. Note that this is not a requirement for working with Forms, but it can make testing more convenient.

Note that in this case, we can only associate one type of component runtime with each type of Forms control. In other words, if you write code that instantiates a new Button using the Button constructor, a StandardButtonRuntime will be created internally.

Of course, you are not required to create buttons this way - you can also create buttons by adding instances of your component in your Gum screen in the tool, or by instantiating the desired runtime.

Modifying ListBoxItems

ListBoxItems are typically created automatically when items are added to a ListBox instance. We can modify ListBoxItems by creating a runtime object for our ListBoxItem then assigning the ListBox's VisualTemplate.

You may want to rename the class when creating your own version. For example, you may want to name yours CustomListBoxItemRuntime.

Once you have created your custom ListBoxItem runtime implementation, you can use it on a list box by assigning the VisualTemplate. Be sure to assign it before adding items to your ListBox, as shown in the following code:

Introduction

Components in a Gum project can be instantiated in custom code. Note that this is not a requirement to use a component since you can also add an instance of the component in your screen.

Code Example - Instantiating a Component

Before instantiating a component, you must first load the project using the standard .gumx loading code as shown in the following code block:

Once you have instantiated your project, you can create a component as shown in the following code:

The Components property contains a list of all components, so you can also access components by name or other property. For example, the First method can be used to find a component by name as shown in the following code:

Note that the name passed to the First method should match the name given in Gum. For example, in this case the code searches for a component named ColoredRectangleComponent.

If a component is in a folder, then its name is the qualified name relative to the Components folder. For example, the following component's name at runtime is "Buttons/StandardButton"

The ToGraphicalUiElement method can automatically add the component to the root for rendering, or alternatively it can be added to an existing container. If adding to an existing container, then the ToGraphicalUiElement's addToManagers parameter should be false as shown in the following code:

Troubleshooting Component Creation

SetProperty

The SetProperty method can be used to set properties on components which are not natively part of GraphicalUiElement. This is useful in the following situations:

• Setting a property which may not exist on all GraphicalUiElements, such as the Text property on a GraphicalUiElement for a Text standard element

• Setting a property which has been exposed

If a GraphicalUiElement is a Text instance, the Text property can be assigned through SetProperty as shown in the following code:

If a component has an exposed variable, then this variable can be assigned through SetProperty. For example, consider the following component which exposes its Text variable:

This can be assigned through the SetProperty. Be sure to use the name exactly as it appears in Gum:

Apply State

States can be applied in code by string (unqualified name), or by accessing the state on the backing ComponentSave. Note, this can also be performed on screens and standards.

Introduction

MonoGameGum provides common runtime types which can be used to build your layouts. The runtime objects correspond to the standard objects in the Gum tool. These provide a type-safe, expressive way of creating and working with Gum. The following runtime objects exist:

• ColoredRectangleRuntime

• ContainerRuntime

• NineSliceRuntime

• SpriteRuntime

• TextRuntime

Notice that at the time of this writing, only a subset of Gum standard types are available. This is likely to expand over time.

All runtime objects inherit from GraphicalUiElement, which is the base class for all Gum objects. Therefore, all runtime objects share the same properties for position (such as X and XUnits), size (such as Width and WidthUnits), and rotation.

Introduction

A typical Gum project references many file types. Aside from the XML files created by the Gum tool (such as a .gumx file), a typical Gum project also references .png files and .fnt files.

Files which are referenced by your Gum project (as created in the Gum UI tool) automatically load their necessary dependencies assuming the files are part of the built file system. Typically this means that your project should copy all Gum XML, PNG, and FNT files to the output folder. Gum does not use the MonoGame content pipeline.

Files in Gum Projects

When a file is added to a Gum project, the Gum UI tool checks the location of the file. If the file is not relative to the Gum project file (.gumx), the Gum UI tool warns you about the file being located outside of the project's folder. The tool recommends that the file should be copied so that your project remains portable.

If all of your project files are located relative to the .gumx root project file, then your project should be portable, and all referenced files will be automatically resolved for you when instantiating Screens and Components from your Gum project.

The Gum runtime library performs all of its loading from-file, so all of your files must be present in the destination directory. As explained in the page, all of your files should be set to Copy if newer in Visual Studio.

Loading Files Through Runtime Objects

Gum runtime objects can reference files. For example both SpriteRuntime and NineSliceRuntime can reference a Texture2D. Similarly, the TextRuntime type can reference BitmapFonts which are loaded from .fnt and .png files.

All runtime types support the assignment of these files by direct assignment of their appropriate type, or by string name.

For example, a Sprite's texture could be assigned either through the SourceFileName property or the Texture property:

In the case of the SourceFile assignment, the SpriteRuntime loads the Texture2D from disk. By default the file is loaded relative to the Content folder.

Example - Loading a Font File

You can explicitly load font files if you would like to change fonts in custom code, or if you are using the GumBatch class to do your own Gum rendering.

To load a file, first make sure that your font is added to Visual Studio, usually in the Content folder. In the case of fonts, you should have at least 2 files:

1. A .png file

2. A .fnt file

Usually both files are added to the same directory. Be sure to mark both files as Copy if Newer.

The file can be loaded using the BitmapFont constructor:

Setting FileManager.RelativeDirectory

Whenever a file is assigned on a runtime object, Gum looks for the file in the ToolsUtilities.FileManager.RelativeDirectory directory. This directory defaults to your game's Content folder.

If your Gum project (.gumx) is located in the Content folder, then you should probably not change this value.

If your project is located in a subfolder of Content, then you must change the relative directory to be the location of your Gum project before you assign files. For example, consider a situation where the Gum project is located in a folder called gum.

To support this situation, you would want to set your relative directory as shown in the following code:

Note that the following operations can result in files being loaded, so if your project is not located in the Content folder then you must set the RelativeDirectory before doing any of the following:

• Calling ToGraphicalUiElement

• Assigning SourceFileName

• Setting custom or cached fonts on a Text object

• Setting states (which may assign variables)

It's recommended practice to set the RelativeDirectory to your Gum project's location and to leave it there so you never have to consider subfolders in any code that accesses files directly or indirectly.

File Caching

By default Gum caches loaded textures. In other words, the following code only results in a single file IO operation:

File caching can be disabled by setting the LoaderManager's CacheTextures property to false as shown in the following code:

Of course, doing so means that Gum will go to disk for every file which can increase load times and result in significantly more video memory usage.

Note that setting CacheTextures to false flushes the cache and disposes all cached content, so you can force the reload of all files by calling setting CacheTextures to false, then back to true as shown in the following code:

Be careful setting CacheTextures to false since all existing textures will be disposed. This means that if you have loaded textures which are still being referenced by runtime objects, you will get an exception if those are still being drawn after setting CacheTextures to false.

Introduction

If your game includes support for resizing the game window, you may need to write additional code to handle the new width and height. This page discusses the options you have for handling resizing. When a game is resized, the typical response is to adjust GraphicalUiElement.CanvasWidth and GraphicalUiElement.CanvasHeight, but you may also want to zoom your UI depending on the needs of your game.

Setting Initial Size

Desktop projects can set their initial size in the Game constructor as shown in the following code:

Default Behavior

By default resizing your Game does not adjust Gum. The following animation shows how Gum behaves by default. Note that the objects in the following animation are properly docked to the corners and center as indicated by the displayed text:

Handling Resizing with No Zoom

This section discusses how react to the window resizing by adjusting the GraphicalUiElement sizes and performing a layout. The Screen contains a Container which is sized to the entire screen with a small border around the edges. The Container has a ColoredRectangle which fills the entire Container. Each Text object is docked as indicated by its displayed string.

The following code shows how to handle a resize:

Handling Resizing with Zoom

You may want to zoom your game rather than provide more visible space to the user when resizing. In this case you need to decide whether to use width or height when deciding how much to zoom your game. For this example we will use height since some users may have monitors with differing aspect ratios.

To properly zoom we need to store the original size in a variable in the Game class so that we can use it to determine the zoom level. The following code is a modified version of the code above with additional logic and variables added to handle zooming:

FrameworkElement PopupRoot and ModalRoot

The FrameworkElement object has two InteractiveGues: PopupRoot and ModalRoot. These are typically created automatically by FormsUtilities but can be assigned manually. In either case, the size of these two containers is automatically managed by FormsUtilities in its Update call so you do not need to update these manually.

Introduction

This page discusses common troubleshooting techniques when your Gum Forms objects are not behaving as expected.

Cursor.WindowOver

You can check the WindowOver property to see what the Cursor believes it is over. This can tell you if the Cursor is over the object that you expect it to be over. The following code can be used to output the CursorOver to Visual Studio's output window:

Clicks are Offset

Clicks could be offset if the GraphicalUiElement's CanvasWidth and CanvasHeight are set incorrectly. For more information, see the .

You can also output the Cursor's X and Y values to the screen to compare them to the desired object's bounds, as shown in the following code: