Click or drag to resize
DigitalRuneUI Controls

The DigitalRune Game UI library provides GUI controls, like windows, buttons, text boxes, ..., for any XNA application (Windows, Windows Phone 7 or Xbox 360). This section gives an overview over the UI service and controls.

The UI service and the UI manager

Each application that wants to render UI controls must create an instance of the UIManager. InputManagerUpdate(TimeSpan) must be called once per frame.

The UI manager implements the interface IUIService, which can be used by game components to add UI screens and UI controls.

UI controls and UI screens

UIControl is the base class for all UI controls. UI controls are managed in a visual tree (e.g. a Window control contains a StackPanel control which contains several Button controls, ...).

The root of the visual tree is the UIScreen. Screens must be added to the UI service. The UI service automatically updates the screens in each frame. Screens are not drawn automatically. You must call UIScreenDraw(GameTime) manually to draw a screen. Screens can be rendered into the backbuffer or into a render target. For example, it is also possible to render a screen into a render target and use it as an interactive texture in the 3D game.

Games can use any number of screens. Many games will only use a single screen. Some games will use several screens, e.g. a "Debug" screen with debug statistics above the normal "Game" screen with the UI controls of the game.

Visual tree and logical tree

Controls are managed in a visual tree: Each control has a VisualParent and VisualChildren. Visual children are managed by the controls themselves; the VisualChildren collection should not be directly changed by the user. The controls will automatically add a "logical child" to the visual children if it needs to be rendered.

The root of the visual tree is the UIScreen, which starts all update, layout and render traversals. The screen does not have a visual parent. Only objects in the visual tree handle input, take part in the layout process and are rendered.

ContentControls have a Content property. Panel and the UIScreen have a Children collection. Other controls may have an Items collection. Using these properties the user can create parent-child relationships which define the logical tree.

Here is an example: A Window is a ContentControl, therefore it has a Content property. The user adds a logical child to the window by setting the Content property (e.g. a StackPanel that contains other controls). The window will automatically put the content into the VisualChildren collection because the content should be updated and rendered with the window. The window has a few more visual children: An Image control that draws the window icon, a TextBlock that draws the window title and a Button that represents the Close button of a window. These "internal" controls are automatically created by the window and added to its visual children.

Subtopics