Introduction

MoveToFrbLayer can be used to move a GraphicalUiElement to a FlatRedBall layer. For information on moving objects to a layer in Glue, see the Adding Gum Components to Layers page. At the time of this writing, Gum objects can only exist on one FlatRedBall/Gum layer.

Gum Layers vs FlatRedBall Layers

Gum and FlatRedBall use two completely separate rendering systems. Visual objects in Gum cannot be directly added to FlatRedBall layers. To address this, the Gum plugin provides some methods to allow Gum objects to exist on FlatRedBall layers using the MoveToFrbLayer method. Internally, this is supported by Glue generating a Gum layer for every Glue layer. This association is stored in the current Gum screen (of type GumIdb ).

Code Example

The following code shows how to move an object named ButtonInstance to a FlatRedBall Layer named UiLayer. This code assumes that GumScreen is a valid Gum screen (which is of type GumIdb ).

ButtonInstance.MoveToFrbLayer(UiLayer, GumScreen);

Introduction

InterpolateBetween combines two states and applies the result to the calling object. The GraphicalUiElement class provides an implementation of InterpolateBetween which takes StateSave instances (allowing for interpolating between states created at runtime), while the specific implementation (such as the runtime class for a component) provides an InterpolateBetween overload which takes the specific state enumerations.

Example Using Enumerations

The following code shows how to call InterpolateBetween using state enumerations. It assumes:

• Button is a component, and ButtonRuntime is the class generated by the Gum plugin for the Button component

• ButtonInstance is an instance of ButtonRuntime

• The Button component has two uncategorized states: State1 and State2

ButtonInstance.InterpolateBetween(ButtonRuntime.VariableState.State1, ButtonRuntime.VariableState.State2, .75f);

The third parameter (which is the interpolationValue ) is a value usually between 0 and 1 which indicates the weight of the 2nd state. In this case, .75 means that 75% weight is given to State2 , while the remaining 25% is given to State1 .

Introduction

The ShowLineRectangles value controls whether dotted-line rectangles will be drawn around components. This value can help you debug where components are when they do not have visual elements, or to help you identify the clickable region when testing UI.

FlatRedBall Editor Example

ShowLineRectangles can be set through the FlatRedBall Editor UI. To change this value in the editor:

1. Select the gum project file (usually GumProject.gumx in Global Content Files)

2. Click the Gum Properties tab

3. Check or uncheck Show Dotted Outlines

Code Example Setting ShowLineRectangles

This value is applied only when new GraphicalUiElements are created, so changing it will not have an immediate impact on existing GraphicalUiElements. If you would like to turn off line rectangles, set this value to false before GlobalContent.Initialize is called in your Game1.cs file. For example, your code might look like this:

        protected override void Initialize()
        {
            FlatRedBallServices.InitializeFlatRedBall(this, graphics);
            CameraSetup.SetupCamera(SpriteManager.Camera, graphics);

            // Set ShowLineRectangles to false...
            GraphicalUiElement.ShowLineRectangles = false;

            // ...before GlobalContent.Initialize
        GlobalContent.Initialize();

            ...

Introduction

The GraphicalUiElement is the base class for all Gum runtime objects. In other words, all Gum components, screens, and standard elements inherit from this class when running in a FlatRedBall project. The GraphicalUiElement class provides functionality for positioning, parenting, sizing, and layout logic. Every Screen and Component in a Gum project will create a class in your Visual Studio project that inherits from GraphicalUiElement.

GraphicalUiElement as IWindow

All GraphicalUiElement instances implement the IWindow interface, which means that they can be used just like other FlatRedBall UI elements. For example, all GraphicalUiElements have a Click event which can be subscribed to. For more information on the IWindow interface, see the IWindow page.

Introduction

GetGraphicalUiElementByName returns the instance of a contained element by name, or null if a matching element isn't found.

Code Example

The following code can be used to find the "Score" component and disable it from being a clickable UI element:

// Assuming the current code has a EntireGumScreen object:
EntireGumScreen.GetGraphicalUiElementByName("Score").Enabled = false;

For more information on the Enabled property, see the IWindow.Enabled page.

Introduction

InterpolateTo creates a tweener which will interpolate to the argument state using the standard interpolation types (such as bounce).

Code Example

gumInstance.InterpolateTo(GumRuntimes.ComponentType.CategoryName.TargetState, 
    secondsToTake: 3, 
    interpolationType: FlatRedBall.Glue.StateInterpolation.InterpolationType.Bounce,
    easing:FlatRedBall.Glue.StateInterpolation.Easing.Out);

Introduction

GetAbsoluteLeft returns the left edge of the calling object in world coordinates. This is in absolute pixels - it is not relative to its parent. Note that this method does not consider rotation, so rotated elements may not return correct values.

Code Example - Detecting Collision Between GraphicalUiElements

The GetAbsolute functions provide information useful for performing collision between GraphicalUielements.

// requires the following using statement for extension method access:
using RenderingLibrary;

// Assuming firstObject and secondObject are valid GraphicalUiElement instances
var collide = firstObject.GetAbsoluteRight() > secondObject.GetAbsoluteLeft() &&
    firstObject.GetAbsoluteLeft() < secondObject.GetAbsoluteRight() &&
    firstObject.GetAbsoluteBottom() > secondObject.GetAbsoluteTop() &&
    firstObject.GetAbsoluteTop() < secondObject.GetAbsoluteBottom();

Introduction

HasCursorOver is used to return if the argument world X and world Y coordinates are inside the calling GraphicalUiElements. This is an extension method requiring the RenderingLibrary namespace. Despite its name, this can be used to detect if a pair of world coordinates are inside the caller regardless of whether this is for UI/cursor checks or otherwise.

Code Example - Detecting GuiManager.Cursor Over Gum Object

The following code can be used to determine if the cursor is over a GraphicalUiElement. Note, this does a bounds check on the Gum object even if the Gum object is not raising events.

void CustomActivity(bool firstTimeCalled)
{
    var cursor = GuiManager.Cursor;

    var isCursorOver = GumScreen.ColoredRectangleInstance.HasCursorOver(cursor);

    FlatRedBall.Debugging.Debugger.Write($"Cursor over: {isCursorOver}");
}

Code Example - Detecting Screen Coordinates on GraphicalUiElement

The following code shows how to detect if a ScreenX and ScreenY pair are inside a particular GraphicalUiElement:

// Since this is an extension method, the following is required:
using RenderingLibrary;

// assuming screenX and screenY are valid screen coordinates

float worldX;
float worldY;

// Assuming the game uses the default system managers
var managers = global::RenderingLibrary.SystemManagers.Default;

screenX -= managers.Renderer.GraphicsDevice.Viewport.X;
screenY -= managers.Renderer.GraphicsDevice.Viewport.Y;

managers.Renderer.Camera.ScreenToWorld(
    screenX, screenY,
    out worldX, out worldY);

var isOver = graphicalUiElement.HasCursorOver(worldX, worldY);

Introduction

The RaiseChildrenEventsOutsideOfBounds property determines whether to check for children events outside of a control's bounds. By default this is false, which means that children will only be checked if the cursor is inside of the parent's bounds.

If this value is true on a parent, then its children are checked even if they are outside of its bounds. This is important if children are positioned outside of the bounds, but it can have a negative impact on performance.

Note that if this value is true, then out-of-bounds checks are only performed for the direct children of the parent - it does not result in recursive checking of bounds.

Example - Checking Button Clicks

The following Gum layout shows a UI control UserControlInstance which has a button ButtonCloseInstance outside of its bounds.

By default this button will not be clickable because it is not contained in the boudns of its UserControlInstance.

To enable clicking the button, the following code could be added to the FlatRedBall Screen's CustomInitialize:

void CustomInitialize()
{
    GumScreen.UserControlInstance.RaiseChildrenEventsOutsideOfBounds = true;
}

Introduction

The SetProperty method can be used to assign any property on a GraphicalUiElement by the name of the property. This method is used internally to apply states, but it can also be used to perform scripting or assign state values without access to code generated types.

Code Example - Assigning Position

The following code assigns the Y value of a ColoredRectangle according to keyboard input.

Code Example - Assigning States

SetProperty allows the assignment of states by state name. This is useful when writing code which should apply to any type of Gum object as long as it contains the required category and states. This example assumes a component with a Size category containing two states: Big and Small.

This will automatically generate an enumeration and property in the component:

If you are writing code where you do not have access to the specific types, the state category can still be assigned using SetProperty as shown in the following code. Notice that the variable name does not use the prefix "Current", so the variable assigned is simply "SizeState":

Introduction

TestCollision is a method which is automatically called by the FlatRedBall engine on all IWindow instances which are part of the GuiManager . The Gum plugin automatically writes code for every Gum runtime to implement the IWindow interface, and Gum objects are directly or indirectly added to the GuiManager automatically. In other words, the TestCollision method is usually not called in game code, but can be used to diagnose problems with UI events not being raised.

Debugging TestCollision

TestCollision is part of the GumRuntime.IWindow.cs file, which is added to all projects which use Gum. Therefore, this can be easily debugged by calling the method and stepping in to see the logic flow. IWindow instances are either directly added to the GuiManager (if it's the root) or indirectly added as a child of a root object. The FlatRedBall code does not directly call TestCollision on all living UI elements. Rather, it calls it on the top-level, which is then responsible for calling it on its children. Therefore, when testing TestCollision, it's best to begin the test at the top level UI element (ignoring the Screen itself). For example, consider the following image:

In this case the top-level object is ChildStandardContainerInstance. If testing collision against ButtonInstance, then TestCollision should be called on ChildStandardContainerInstance to simulate the engine's behavior. To access the ChildStandardContainerInstance at runtime:

1. Drag+drop the Gum screen file (.gusx) onto the Glue Screen's Objects

2. Use the Source Name dropdown to select the desired object (ChildStandardContainerInstance in this case)

3. Click OK

To follow the logic:

1. Open Visual Studio

2. Open the Glue screen file which contains the newly-added object (GameScreen.cs in this case)

3. Find the CustomActivity method

4. Add the following code:

void CustomActivity(bool firstTimeCalled)
{
    var cursor = GuiManager.Cursor;

    if(cursor.PrimaryClick)
    {
        ChildStandardContainerInstance.TestCollision(cursor);
    }
}

Now we can add a breakpoint to the TestCollision call. Notice that the call is wrapped in an if statement. This gives you the chance to position the cursor where you want it before hitting the breakpoint. Without the if statement, the breakpoint would hit immediately, making debugging more difficult.