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.
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.
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:
Keep in mind this association can be overridden. For example, you may add the following to your custom code:
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
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.
If a button has focus, it can pass focus to the next button. The following code shows how to do this using the keyboard:
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:
The Visual property is the underlying Gum object used to render the Framework Element. The Visual object is of type GraphicalUiElement.
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 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:
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.
The following code can be used to add a Button to a Screen in code:
Note that controls which are added in code through Show should be removed manually in the Screen's CustomDestroy.
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