Introduction

The GuiManager keeps track of the order of IWindows that it is storing. For default-drawn Windows, this ordering is reflected in the draw order. However, for Glue Entities, the ordering of the Entities in the GuiManager may not match the ordering that the Entities are drawn. The order of IWindow Entities only matters if Entities overlap. In this case, you will need to manually control the order of Entities by using BringToFront. The GuiManager will also automatically bring clicked windows to the front. This is desirable when using default-drawn Windows, but usually not desirable when working with Entities. Therefore, if you are using IWindow Entities in Glue you will want to set the GuiManager's BringsClickedWindowsToFront property to false in your game's initialization.

Glue Entity example

If you have IWindow Entities which are overlapping, you will want to control the order of your Entities using the BringToFront method. For example, consider an Entity called ButtonFrame which contains three Buttons. To bring the three Buttons to the front so that they are clickable, you might want to add the following code:

private void CustomInitialize()
{
   BringButtonsToFront();
}
private void BringButtonsToFront()
{
   GuiManager.BringToFront(ButtonInstance1);
   GuiManager.BringToFront(ButtonInstance2);
   GuiManager.BringToFront(ButtonInstance3);
}

The MakeRegularWindow function can be used to convert an IWindow which has been made a dominant window through AddDominantWindow no longer act dominant and make it instead a regular window.

The GamePadsForUiControl list specifies which game pads can be used to control FlatRedBall.Forms controls. By default this list is empty, but it can be populated with gamepads to enable navigation and selection of UI with the DPad, AnalogSticks, and Buttons. For more information see the Forms and Xbox360Gamepad page.

Introduction

The GuiManager is a static object responsible for common UI element management as well as some UI creation. There are two categories of UI elements:

1. Default FlatRedBall GUI objects which are usually used for debugging and tools (these are used in all FRB graphical tools like the SpriteEditor, PolygonEditor, etc)

2. Glue Entities inheriting from IWindow

For a Default FlatRedBall UI element to be visible and functional it must either belong to the GuiManager or another UI element. Glue Entities are drawn by the engine like normal Entities - the GuiManager simply handles the cursor-based activity (like clicks).

Window Categories

When a Window is created and added to the GuiManager, it can be added to one of three internal lists. These lists define the three categories. These categories are:

• Regular

• Dominant

• Perishable

The following sections define the characteristics of each category.

Regular

Adding a Window by calling its constructor then passing it to the GuiManager's AddWindow method will add the Window as a regular Window. Regular Windows remain in memory until they are removed using the GuiManager's RemoveWindow method. Making a regular Window invisible will not remove it from the GuiManager.

Dominant

Dominant Windows are Windows which consume Cursor interaction while they are visible. In other words, if a dominant Window is present, no other Windows will receive input. Any Window can be made dominant through the AddDominantWindow method. Dominant Windows are often used when the users attention is required on a particular Window. Examples include a OkCancelWindow asking if the program should really exit after clicking the close button or a FileWindow for selecting a file to load in an application. Dominant Windows can be removed by either calling the GuiManager's RemoveWindow method or by setting the dominant Window's Visible property to false. Setting the Visible property to false will result in the GuiManager automatically removing the Window if RemoveInvisibleDominantWindows is set to true.

Perishable

Perishable Windows are Windows which will automatically be removed by the GuiManager when the user clicks and the Cursor is not over the perishable Window. Perishable Windows are most commonly used for Windows which have a short life span. Examples include the drop-down ListBoxes that appear when clicking the Button on ComboBoxes or menus appearing when right-clicking on an object. If the user clicks on a perishable Window, the Window will not automatically remove itself. The removal is usually handled in one of the Window's events in this case.

GuiManager Members

• FlatRedBall.Gui.GuiManager.AddDominantWindow

• FlatRedBall.Gui.GuiManager.BringsClickedWindowsToFront

• FlatRedBall.Gui.GuiManager.BringToFront

• FlatRedBall.Gui.GuiManager.MakeRegularWindow

• FlatRedBall.Gui.GuiManager.RemoveWindow

• FlatRedBall.Gui.GuiManager.ShowTextInputWindow

• FlatRedBall.Gui.GuiManager.SortZAndLayerBased

• FlatRedBall.Gui.GuiManager.TextHeight

• FlatRedBall.Gui.GuiManager.Windows

Did this article leave any questions unanswered? Post any question in our forums for a rapid response.

Introduction

The Windows IEnumerable contains all regular (non-dominant) windows in the GuiManager. By default IWindow-implementing Entities created in Glue will add themselves to the GuiManager and appear in this list. The order of IWindows in this list determines the order in which the Cursor performs UI checks.

FlatRedBall Forms

By default, FlatRedBall.Forms objects created through Gum screens add themselves to the GuiManager and appear in this list. Note that the GuiManager does not hold a direct reference to the FlatRedBall.Forms objects, but rather the Visual for each of the forms. Furthermore, only the top-level objects are added to the GuiManager. Therefore, if a StackLayout instance contains multiple buttons, only the StackLayout's Visual will appear in the Window list. For example, the following image shows a Gum screen with four buttons. Since all of the buttons are not contained by any other Forms objects, all four will appear in the Windows list.

Introduction

The RemoveWindow method can be used to remove a Window from the GuiManager. The pattern for addition and removal for the GuiManager matches the other managers. In other words, you call AddWindow to add a Window to the GuiManager, and RemoveWindow to remove it.

Code Example

Windows are added to the GuiManager through the AddWindow method:

Windows can be removed from the GuiManager through the RemoveWindow method:

Introduction

The BringsClickedWindowsToFront property controls whether the GuiManager brings any clicked Window to the front of its internal list. The internal GuiManager list does not control rendering, just the order that clicks are tested. Windows at the front of the list are prioritized regarding Cursor input. This is desired behavior if the GuiManager controls the rendering order of these windows (as is the case with the default FRB GUI found in the FRB tools) but it is not desirable behavior if the GuiManager does not control the rendering order (as is the case for Glue Entities implementing IWindow.

In summary:

1. If using default FlatRedBall Gui for a tool or debugging, leave BringsClickedWindowsToFront to its default BringsClickedWindowsToFront value.

2. If using Glue IWindow Entities, you should set BringsClickedWindowsToFront to false and control ordering through the BringToFront method)

Usage

// If using Glue and IWindow:
FlatRedBall.Gui.GuiManager.BringsClickedWindowsToFront = false;

Introduction

The SortZAndLayerBased function is a function which can be called to sort the GuiManager's Windows by their Z value and Layer membership. Layers take first priority, then IWindows which are on the same Layer will be sorted by their Z. The higher the Z value of an IWindow, or the further in-front a Layer is, the later in the list the IWindow will appear.

Code Example

The following can be called to update the order:

GuiManager.SortZAndLayerBased();

Introduction

Dominant Windows are IWindows which have higher priority over regular IWindows. If the GuiManager contains any dominant IWindows then any non-dominant IWindows will not receive any input from the Cursor. Dominant IWindows are a good way to prevent the user from interacting with regular (non-dominant) IWindows when UI such as a pause screen or exit confirmation screen is visible. Multiple IWindows can be marked as dominant windows using AddDominantWindow. AddDominantWindow can be called on a regular IWindow to convert it to a dominant window. Dominant windows can be converted back to non-dominant windows using the MakeRegularWindow method.

Example - AddDominantWindow, FlatRedBall Forms, and Gum

This example shows how to use AddDominantWindow to change whether a popup is the dominant window in response to UI events. This example uses a Gum screen with two objects - UserControlInstance and PopupInstance as shown in the following treeview:

Visually, the layout is shown in the following image:

The hiding and showing of the popup is controlled as shown in the following code:

void CustomInitialize()
{
    GumScreen.PopupInstance.Visible = false;

    Forms.ClosePopupButton.Click += (not, used) =>
    {
        GumScreen.PopupInstance.Visible = false;
        FlatRedBall.Gui.GuiManager.MakeRegularWindow(GumScreen.PopupInstance);
    };

    Forms.ShowPopupButton.Click += (not, used) =>
    {
        GumScreen.PopupInstance.Visible = true;
        FlatRedBall.Gui.GuiManager.AddDominantWindow(GumScreen.PopupInstance);
    };
    
}