Introduction

HandleTab can be used to tab to the previous or next item which can receive focus. This is a manual way to force tabbing rather than relying on the built-in functionality. For information about how to execute automatic tabbing with gamepads, see the Forms and Xbox30GamePad tutorial.

Code Example - Tabbing to the Next Button

If a button has focus, it can pass focus to the next button. The following code shows how to do this using the keyboard:

// assume MyButton has focus:
var keyboard = InputManager.Keyboard;
if(keyboard.KeyPushed(Keys.Down) ||
    keyboard.KeyPushed(Keys.W) )
{
    MyButton.HandleTab(TabDirection.Down);
}
if(keyboard.KeyPushed(Keys.Up) ||
    keyboard.KeyPushed(Keys.S))
{
    MyButton.HandleTab(TabDirection.Down);
}

If your game has multiple elements which can be focused you can handle tabbing regardless of which element has focus as shown in the following code:

var keyboard = InputManager.Keyboard;
if (keyboard.KeyPushed(Keys.Up) ||
    keyboard.KeyPushed(Keys.W) )
{
    (InputManager.InputReceiver as FrameworkElement)?.HandleTab(TabDirection.Up);
}
if (keyboard.KeyPushed(Keys.Down) ||
    keyboard.KeyPushed(Keys.S))
{
    (InputManager.InputReceiver as FrameworkElement)?.HandleTab(TabDirection.Down);
}

Introduction

The Visual property is the underlying Gum object used to render the Framework Element. The Visual object is of type GraphicalUiElement.

Visual vs Forms Object

The Forms object can be thought of as a wrapper to the underlying Visual object. The Visual object provides some unique functionality that is not available directly to the Forms object. The following is a brief summary of what each offers: The Forms object:

• Provides a standardized interface for performing common operations such as setting a Button's Text, adding items to a ListBox, and highlighting text in a TextBox.

• Provides basic controls for positioning and sizing through X, Y, Width, and Height

• Provides standard access to state properties such as IsEnabled, IsMouseOver, and parent/children relationships

By contrast, the Visual object provides:

• Full control over positioning using all Gum properties such as X, Y, XUnits, YUnits, XOrigin, YOrigin, and ChildrenLayout

• Full control over sizing using all Gum properties such as Width, Height, WidthUnits, and HeightUnits

• Full access to all custom properties (such as custom states) if converted to its specific type

• Animation support

• State interpolation support

• Property assignment through strings

Most cases require interacting only with the main Forms object, but if additional flexibility is needed then the Visual object can be accessed and modified. Note that some properties (such as a Button's state) are controlled by the Forms object, so modifying these values may result in the Forms object overriding the changes in response to runtime logic (such as the mouse hovering over a Button).

Forms and Visual Two-Way Relationship

Forms and their Visuals have a two-way relationship. If you have access to one, you can get access to the other. For example, consider the following code:

var button = Forms.ButtonInstance;
var buttonVisual = button.Visual;
var buttonFromVisual = (FlatRedBall.Forms.Controls.Button)buttonVisual.FormsControlAsObject;
// will be true:
var areEqual = button == buttonFromVisual;

Introduction

DefaultFormsComponents is a static property in the FrameworkElement class which associates a FlatRedBall.Forms control to a default Gum component type. DefaultFormsComponent is used whenever code instantiates a FlatRedball.Forms object, allowing the internal engine to automatically create visuals for it. In other words, this association defines the default appearance of a FlatRedBall.Forms object by associating it with a Gum type. For example, the following code shows how a simple button can be created. Notice that this code does not require instantiating a Gum object - the Button automatically has a Visual object created internally.

// Notice that a visual is not specified for the button
// The button will automatically create its own visual
// according to the association in DefaultFormsComponents
var button = new Button();

// Now the button has a visual which can be used:
button.Visual.AddToManagers();
// Alternatively, the button can call Show, which internally adds the visuals
// to the correct managers:
button.Show();

// and of course the button is fully functional:
button.Click += HandleButtonClick;

Internally, the Button class looks at the DefaultFormsComponents dictionary. It searches for an entry for its type ( typeof(FlatRedBall.Forms.Controls.Button) ), and if it finds a match, it uses that as its visual.

DefaultFormsComponents in Generated Code

If your project has FlatRedBall.Forms added (default if you used the wizard), then FRB automatically populate the DefaultFormsComponents dictionary according to behaviors assigned to components in the Gum project. Unmodified projects which include Forms components will have a standard component for each Forms control. The code for this is added to the GumIdb.Generated.cs file. For example, the code may look like this:

FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.Button)] = typeof(ProjectName.GumRuntimes.DefaultForms.ButtonRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.CheckBox)] = typeof(ProjectName.GumRuntimes.DefaultForms.CheckBoxRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.ComboBox)] = typeof(ProjectName.GumRuntimes.DefaultForms.ComboBoxRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.ListBox)] = typeof(ProjectName.GumRuntimes.DefaultForms.ListBoxRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.ListBoxItem)] = typeof(ProjectName.GumRuntimes.DefaultForms.ListBoxItemRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.RadioButton)] = typeof(ProjectName.GumRuntimes.DefaultForms.RadioButtonRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.ScrollBar)] = typeof(ProjectName.GumRuntimes.DefaultForms.ScrollBarRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.ScrollViewer)] = typeof(ProjectName.GumRuntimes.DefaultForms.ScrollViewerRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.Slider)] = typeof(ProjectName.GumRuntimes.DefaultForms.SliderRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.TextBox)] = typeof(ProjectName.GumRuntimes.DefaultForms.TextBoxRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.ToggleButton)] = typeof(ProjectName.GumRuntimes.DefaultForms.ToggleButtonRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.TreeView)] = typeof(ProjectName.GumRuntimes.DefaultForms.TreeViewRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.TreeViewItem)] = typeof(ProjectName.GumRuntimes.DefaultForms.TreeViewItemRuntime);
FlatRedBall.Forms.Controls.FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.UserControl)] = typeof(ProjectName.GumRuntimes.DefaultForms.UserControlRuntime);

Keep in mind this association can be overridden. For example, you may add the following to your custom code:

FrameworkElement.DefaultFormsComponents[typeof(FlatRedBall.Forms.Controls.Button)] = 
    typeof(ProjectName.GumRuntimes.LargeMenuButtonRuntime);

The DefaultFormsComponents can be assigned and re-assigned any number of times, allowing a project to have per-screen or even per-function default behavior, rather than a global association.

Note that you can also add additional entries for any custom Forms type - you are not limited to Forms types which ship with the FlatRedBall.Forms library. Also, if you have custom .Forms controls that should have default implementations, you should consider doing so before any Screen runs, such as in Game1.cs. This guarantees that any loading code

Introduction

The Show method can be used to add a Forms to the necessary managers so that it is drawn and can respond to input events. This method should not be called on Forms instances which have been added through the Gum tool - it is only used on Forms which are added in code, and which do not have a parent.

Code Example

The following code can be used to add a Button to a Screen in code:

Button button;
void CustomInitialize()
{
    button = new Button();
    button.Text = "I am a button created in code";
    button.X = 100;
    button.Y = 100;
    button.Show();
}

Note that controls which are added in code through Show should be removed manually in the Screen's CustomDestroy.

void CustomDestroy()
{
    button.Visual.RemoveFromManagers();
}

The FrameworkElement class serves as the base class for all FlatRedBall.Forms Controls. A FrameworkElement has the following characteristics:

• A Visual object of type GraphicalUiElement (Gum runtime object)

• X and Y values, using the Visual's unit types

• ActualX and ActualY, returning the pixel coordinates of the left and top of the control, respectively