Basic Controls
Controls visualize data and react to user input.
<Window/> is also a control.
Use SafeDeleteControl and SafeDeleteComposition
to delete a control or a composition containing controls.
Otherwise memory leaks may happen.
A control has three main composition properties:
- BoundsComposition:
This is a composition of the control's border.
To make a control appear inside another composition,
just simply adds BoundsComposition as a child composition to that composition.
- ContainerComposition:
This is a composition of the control's inner border.
To make another composition inside a control,
just simply adds that composition as a child composition to ContainerComposition.
- FocusComposition:
If a control is focusable,
this property returns a non-null value.
FocusComposition receives most of composition events.
Ideally,
events provided by the control itself is sufficient enough,
FocusComposition is designed for the implementation of the control and the control template.
BoundsComposition and
ContainerComposition will not change during a control's life time.
FocusComposition changes when the control template changes.
Many properties are shared across control classes.
States
The following properties and events control states for a control.
VisuallyEnabled (VisuallyEnabledChanged)
When a control's Enabled is set to false,
VisuallyEnalbed of the control itself and all direct or indirect child controls is also set to false.
A visually disabled control doesn't react to user input.
VisuallyEnabled of the control template automatically updates when this property is changed.
Enabled (EnabledChanged)
The default value for this property is true.
When a control's Enabled is set to false,
VisuallyEnalbed of the control itself and all direct or indirect child controls is also set to false.
A visually disabled control doesn't react to user input.
Sample
Visible (VisibleChanged)
The default value for this property is true.
When a control's Visible is set to false,
the control disappears,
but it still affect the minimum size of all parent compositions.
Text (TextChanged)
The default value for this property is "".
This property controls the text displayed on the control.
Text of the control template automatically updates when this property is changed.
DisplayFont (DisplayFontChanged)
DisplayFont reflects the expected font for this control.
The expected font for this control is,
either the Font of this control if it is not empty,
or the nearest parent control's non-empty Font.
If no font is found all the way to the top level control,
it becomes GetCurrentController()->ResourceService()->GetDefaultFont()
DisplayFont of the control template automatically updates when this property is changed.
Font (FontChanged)
The default value for this property is null.
When a control's Font is changed,
DisplayFont of the control itself and all direct or indirect child controls with an empty Font is also changed,
Sample
Context (ContextChanged)
The default value for this property is null.
This property offers a way to communicate between a control and its control template or item templates.
When the value is changed,
the Context property of its control template or item templates will be changed to that value.
Please check out
this tutorial project
as an example.
In this project,
it creates a new control TriplePhaseButton which has different images for different states.
This new control passes itself to the Context of a button inside this control,
and than the control template of this button communicates directly to this new control,
to make the button behaves like a triple-phases button (unlike double-phases buttons like check boxes).
Focused (FocusedChanged)
The default value for this property is false.
Calling SetFocus to try to move focus to this control.
A focused control accepts keyboard and character input to the window.
Tag
The default value for this property is null.
This property accepts any value.
It does nothing but associates a value to a control.
Control Template
The following properties and events control the control template for a control.
ControlThemeName (ControlThemeNameChanged)
A ThemeTemplates contains control template implementations for controls.
Each control template factory fields are optional.
Multiple ThemeTemplates could be registered and unregistered using RegisterTheme and UnregisteredTheme.
The later registered ThemeTemplates has a higher pririty.
When calling GetCurrentTheme->CreateStyle(themeName),
it goes through all registered theme and find if any ThemeTemplates has an implementation for the specified themeName.
ControlThemeName property specifies which control template should be used for this template.
Different control classes have different default values for this property.
In most of the cases this property is not expected to be changed during the runtime.
When ControlThemeName is changed and ControlTemplate is empty,
the control template for this control will be changed immediately.
SetControlThemeNameAndTemplate is for changing both ControlThemeName and ControlTemplate at the same time to improve the performance.
ControlTemplate (ControlTemplateChanged)
This property is used when you doesn't want the registered control template for this control.
The default value for this property is empty.
The value for this property must be a vl::Func for the function type templates::GuiControlTemplate*(const reflection::description::Value&).
Please check out
this page
for details about using this property in GacUI XML Resource.
When ControlTemplate is assigned with an empty value,
ControlThemeName kicks in and update the control template for this control.
When ControlTemplate is assigned with a non-empty value,
this property is evaluated to create a control template for this control.
SetControlThemeNameAndTemplate is for changing both ControlThemeName and ControlTemplate at the same time to improve the performance.
ControlTemplateObject
This property returns the currently used control template instance.
A control template is also a composition,
and it has BoundsComposition and ContainerComposition too.
But they are not same values as the same property of the control.
FocusComposition is the same to control and control templates.
Context
The following properties and events provide access of the control's context.
Parent (ControlSignalTrigerred with ParentLineChanged)
A control appears inside its Parent,
otherwise this property returns null (usually for windows and menus).
To add a control directly inside another control,
just simply call AddChild, which adds the child control's BoundsComposition to the parent control's ContainerComposition.
It is also OK when the child control's BoundsComposition is not the direct child composition of the parent control's ContainerComposition.
GetChildrenCount, GetChild and HasChild
provide access for child controls.
RelatedControlHost (ControlSignalTrigerred with ParentLineChanged)
RelatedControlHost is the root parent control for a control,
which is usually a window or a menu.
otherwise this property returns null (usually for windows and menus).
Behaviors
The following properties and events control the behavior of a control.
AcceptTabInput
The default value for this property true.
When this property is set to true,
pressing TAB key when this control is focused type a TAB character into this control.
TabPriority
The default value for this property is -1.
Pressing TAB in a window cause the focus to move between all controls that have a non-negative value TabProperty from low to high.
Alt (AltChanged)
The default value for this property is "".
Pressing ALT causes a window prints all acceptable keys to move focus to all controls that have a non-empty Alt.
Alt could contain multiple upper-cased letters and digits,
which is a sequence that moves the focus to this control after pressing ALT.
For controls that are not focusable but manage focus of direct child controls (like Tab control),
or for controls that manage focus of child controls in another window (like menus),
SetActivatingAltHost is an important function to activate this feature for this control.
This function is only for control authors to use.
Pressing ESC or BACKSPACE goes back to the upper level window or control during a ALT sequence.
TooltipControl
The default value for this property is null.
A legal value for this property must be a control that is not contained in any composition.
When the mouse stops on a control for a while,
its TooltipControl will appear at the mouse cursor.
When a control is deleted,
it also deletes its TooltipControl.
DisplayTooltip and CloseTooltip
could be call to manually control a tooltip proactively.
TooltipWidth
The default value for this property is 0.
This property controls the width of TooltipControl.
Sample
Service Objects
AddService (ControlSignalTrigerred with ServiceAdded) associates a nullable service object to this control with an identifier that could be any string.
QueryService or QueryTypedService<T> searches for a service object using an identifier all the way up to the top-level control.
If multiple service objects are found,
the one in the nearest parent control wins.
Some service identifiers are hard-coded in controls,
even if you try to associate a service objects using thses identifiers,
it takes no effect on some controls:
- vl::presentation::compositions::IGuiAltAction
- vl::presentation::compositions::IGuiAltActionContainer
- vl::presentation::compositions::IGuiAltActionHost
- vl::presentation::controls::IGuiMenuService
- vl::presentation::controls::IGuiMenuDropdownProvider
- vl::presentation::controls::IToolstripUpdateLayoutInvoker
- vl::presentation::compositions::IGuiTabAction
Predefined services are full name of GacUI classes,
it is easy to avoid conflict with your own service objects.
