The Visual Tree: Controls are managed in a visual tree. Each control has a VisualParent and VisualChildren. VisualChildren are managed by the control classes themselves; this collection should not be directly changed by the user. The controls will automatically put a "logical child" into the VisualChildren collection if necessary. The root of the visual tree is the UIScreen which starts all update, layout and render traversals. The VisualParent of the UIScreen is . Only objects in the visual tree handle input, take part in the layout process and are rendered.

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

A Logical/Visual Tree 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. 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 also visual children.

IsLoaded: The UIControl is loaded (IsLoaded) when the control is added to the VisualChildren of a loaded control, or when the control is in the VisualChildren of an unloaded parent control and the parent control is loaded. Update(TimeSpan) is automatically called if the control is loaded.

PropertyChanged Events: PropertyChanged events are only raised for game object properties, like Background, IsEnabled, etc. The event is not raised for "normal" properties, like ActualIsEnabled, Screen, VisualState, etc.

Render Transforms: Controls have a RenderTransform that is defined using the game object properties RenderTransformOrigin, RenderTranslation, RenderRotation and RenderScale. The render transform can be used to scale, rotate and translate the control. The render transform is correctly applied when input is handled (e.g. mouse clicks). But the render transform is ignored in the layout process.

UIControl Properties: A UIControl is derived from GameObject and therefore has game object properties (see GamePropertyT) and game object events (see GameEventT). One big advantage of the game object property system is that they can be initialized in the XML file of the UI Theme. The UI control properties are extended game object properties: They must be created using CreatePropertyT(Type, String, String, String, T, UIPropertyOptions) and CreateEventT(Type, String, String, String, T). UIPropertyOptions can be assigned to UI control properties (see GetPropertyOptions(Int32) and SetPropertyOptions(Int32, UIPropertyOptions)). Depending on the UIPropertyOptions property changes automatically invoke InvalidateMeasure, InvalidateArrange, or InvalidateVisual when required. Game object properties have only one global default value. If a control class, e.g. a Button, should have class-specific default values, the method OverrideDefaultValueT(Type, Int32, T) can be used.

Styles and Templates: Each control has a Style. When the control is loaded. The control retrieves style information (e.g. default values) from the IUIRenderer and creates a template game object with property values determined by the used Style. This game object is set as the Template. To apply a new style to an already loaded control, the control must first be removed from the visual tree and afterwards added back again to the visual tree.

The Layout Process: The layout process is a simplified version of the WPF/Silverlight layout process. The layout process starts at the root of the visual tree (the UIScreen) or when UpdateLayout is called. First, Measure(Vector2F) is called for all controls in the visual tree. Measure(Vector2F) computes the DesiredWidth and DesiredHeight of a control. These values are determined either by the theme or the user (see Width, Height, MinWidth and MinHeight) or automatically computed by the control. It is also possible to call Measure(Vector2F) manually.

After that, Arrange(Vector2F, Vector2F) is called for all controls in the visual tree. Arrange(Vector2F, Vector2F) computes the ActualX, ActualY, ActualWidth and ActualHeight of a control in screen coordinates. The actual bounds are determined by the properties X, Y, Margin, HorizontalAlignment and VerticalAlignment. (X and Y are usually only used for controls in a Canvas or directly under the UIScreen.) The measure and arrange results are cached, and the layout process is only repeated when necessary. A new layout process can be issued using InvalidateMeasure or InvalidateArrange. When game object properties are changed, they automatically invalidate the layout if necessary. Derived classes can override OnMeasure(Vector2F) and OnArrange(Vector2F, Vector2F) to customize the layout results.

The Rendering Process: The rendering process starts at the root of the visual tree (the screen) when Draw(TimeSpan) is called by the user. Render(UIRenderContext) will be called for each control in the visual tree. Derived classes can override OnRender(UIRenderContext) to do custom drawing. Per default, OnRender(UIRenderContext) lets the renderer draw the control (see Render(UIControl, UIRenderContext)).

Custom Rendering: There are several ways to customize the appearance and rendering of controls:

• If the UIRenderer is used: Change the styles in the UI theme (see the themes in the example projects).
• If the UIRenderer is used: Add a new render method to the RenderCallbacks of the UIRenderer if custom drawing code is necessary.
• Use your own IUIRenderer instead of the UIRenderer.
• Override OnRender(UIRenderContext) of a specific UIControl.

Visual States: The VisualStates of this control are: "Disabled", "Default"

Reference