Control Behaviors
Content List
- Construction Kit Control Behaviors
- Map
- Construction Kit Scroll Control Behaviors
- Circular Slider Behavior
- Drawer Behavior
- Map
- Internal Control Behaviors
- Caret
- Handle Control State
- DataContext
- Edit Text
- Selection Group
- Caret
- Public Property Control Behaviors
- Provide Alignment
- Copy Size
- Provide Color
- Provide Margin
- Property Provider
- Render Node
- Provide Appearance
- Provide Image
- Set Layout
- Provide Text
- Provide Alignment
- Align Pivot
- Android Event Bridge
- Arc Align
- Blend Mode
- Breadcrumb Behavior
- Disable Control
- Enable Control
- Event Bridge
- Focus
- Focus Leave
- Hover
- HoverLeave
- IntervalSwitch
- Keyboard Behavior
- Menu Item
- MenuScreen
- Navigation Instruction View
- OnClick
- OnPressed
- OnTimer
- Orbit Camera Transform
- Page Indicator
- Rectangle Clipping Behavior
- Roll
- Touch Indication Behavior
- Transform Mesh2D
- Event Handler
- Virtual Key
Construction Kit Control Behaviors > Map
Map
Description
Provides the map rendering and navigation functionality.
| Property Name | Type | Description |
|---|---|---|
| Bearing | BearingType | Clockwise angle relative to North that the users currently faces. |
| Longitude | LongitudeType | Longitude of current users location. |
| Latitude | LatitudeType | Latitude of current users location. |
| SimulateDriving | SimulateDrivingType | Simulate driving along computed route when in navigation mode. |
| NaviMessageNode | NaviMessagesNodeType | Node to which navigation instructions will be sent. |
| LocationMesh | LocationMeshType | Node containing mesh(es) used to render the location indicator. |
| RouteOverlayColor | RouteOverlayColorType | Color used by the route overlay. |
| AvoidTolls | AvoidTollsType | Avoid tolls during route computation. |
| AvoidMotorways | AvoidMotorwaysType | Avoid motorways during route computation. |
| AvoidFerry | AvoidFerryType | Avoid ferrys during route computation. |
Map Bridge
Description
Builds a bridge to MapBehavior forwarding touch events.
| Property Name | Type | Description |
|---|---|---|
| TargetNode | TargetNodeType | Node containing the target MapBehavior to which events will be forwarded. |
Construction Kit Control Behaviors > Construction Kit Scroll Control Behaviors
List Behavior
Description
ListBehavior is a list supporting scrolling itemwise and pagewise combined with either relative or absolute scrolling.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| ScrollDirection | ScrollDirection::Enum | The direction in which the ListBehavior scrolls. |
| Position | FeatStd::Float | The pixel position of the visible content within the list content. |
| AnimationDuration | FeatStd::UInt32 | Duration of the scrolling animation. |
| DecelerationFactor | FeatStd::Float | Loss of flick animation speed over time. |
| MaxSpeedPerFlick | FeatStd::Float | Maximum amount of speed each flick motion adds to the flick animation. |
| MinSpeedPerFlick | FeatStd::Float | Minimum speed required to count a touch gesture as a flick and start or continue the flick animation. |
| MinMovementToScrolling | FeatStd::UInt32 | Minimum distance a touch gesture needs to move to start a scrolling animation. |
| MaxTouchSampleAge | FeatStd::UInt32 | Maximum age in miliseconds of touch movement speed counted towards generating flick animation speed. |
| Items | The items property is used for binding of dynamic items. It can only be set via databinding. Only one visible list control should be bound to a fragment list in the model. Otherwise the list fragments in the model are not able to provide data for both list controls. Use a separate list model that is filled with the same data if such a use case is required. | |
| ListFragmentTriggerOffset | FeatStd::SizeType | A dynamic list is requested in fragments to reduce memory consumption and overall performance overhead. This trigger offset value defines an area at the begin and end of the list fragment. Whenever the list shows a part of these areas a new fragment is requested from the model. |
| ListFragmentSize | FeatStd::SizeType | A dynamic list is requested in fragments to reduce memory consumption and overall performance overhead. This buffer size defines how large this fragment should be. By default it is set to 0 which results in an automatic calculation. The automatic calculation assumes the number of item nodes is configured to match the maximum number of visible nodes for one page. By multiplying this number by three and adding the trigger offset one time for the begin and one additional time for the end to calculate for the automatic buffer size the list has a spare page on each side before a new fragment has to be requested |
Scrollbar Behavior
Description
Reflects the position of the scrollable behavior. E.g. ListBehavior2D.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| TouchListenerNode | Candera::AbstractNodePointer | This node defines the area on which the ScrollbarBehavior will listen for the touch events. |
| ScrollDirection | FeatStd::Optional< ScrollDirection::Enum > | The direction in which the ListBehavior scrolls. By default it is configured as a vertical scrollbar. |
| ScrollbarVisibility | ScrollbarVisibility::Enum | Configure the visibility of the scrollbar. By default it is set to Automatic which will determine the visibility based on the actual content. |
| HandleMinimumSize | FeatStd::UInt32 | The minimum height (for vertical scrollbar) or minimum width (for horizontal scrollbar) of the handle in pixels. |
| MinMovementToScrolling | FeatStd::UInt32 | Minimum distance a touch gesture needs to move to start scrolling. |
Scroll View
Description
Scroll View is a Touchable Control that has a ContentAnchor which can be filled with various content. Depending on the size of the content and the configured Scroll View's Layout Size, a horizontal and/or vertical scrollbar appears.
Because of the fact that Scroll View supports horizontal and vertical scrolling, it receives the ScrollableEvent from Send Scrollable Event Behavior (can also be forwarded from a Scrollbar Behavior Scrollbar via Event Bridge Behavior).
Example Usage
Common Properties
This behavior does not have any configurable properties.
SubList Behavior
Description
SubListBehavior extends the ListBehavior by special handling when being used in a child node of a ListBehavior.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| ScrollDirection | ScrollDirection::Enum | The direction in which the SubListBehavior scrolls. |
| Position | FeatStd::Float | The pixel position of the visible content within the list content. |
| AnimationDuration | FeatStd::UInt32 | Duration of the scrolling animation. |
| DecelerationFactor | FeatStd::Float | Loss of flick animation speed over time. |
| MaxSpeedPerFlick | FeatStd::Float | Maximum amount of speed each flick motion adds to the flick animation. |
| MinSpeedPerFlick | FeatStd::Float | Minimum speed required to count a touch gesture as a flick and start or continue the flick animation. |
| MinMovementToScrolling | FeatStd::UInt32 | Minimum distance a touch gesture needs to move to start a scrolling animation. |
| MaxTouchSampleAge | FeatStd::UInt32 | Maximum age in miliseconds of touch movement speed counted towards generating flick animation speed. |
| Items | The items property is used for binding of dynamic items. It can only be set via databinding. Only one visible list control should be bound to a fragment list in the model. Otherwise the list fragments in the model are not able to provide data for both list controls. Use a separate list model that is filled with the same data if such a use case is required. | |
| ListFragmentTriggerOffset | FeatStd::SizeType | A dynamic list is requested in fragments to reduce memory consumption and overall performance overhead. This trigger offset value defines an area at the begin and end of the list fragment. Whenever the list shows a part of these areas a new fragment is requested from the model. |
| ListFragmentSize | FeatStd::SizeType | A dynamic list is requested in fragments to reduce memory consumption and overall performance overhead. This buffer size defines how large this fragment should be. By default it is set to 0 which results in an automatic calculation. The automatic calculation assumes the number of item nodes is configured to match the maximum number of visible nodes for one page. By multiplying this number by three and adding the trigger offset one time for the begin and one additional time for the end to calculate for the automatic buffer size the list has a spare page on each side before a new fragment has to be requested |
Construction Kit Control Behaviors
Circular Slider Behavior
Description
This behavior provides the functionality of CircularSlider control by creating a radial mask and setting a rotation of knob node.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Value | FeatStd::Variant | Value of the slider |
| MinimumValue | FeatStd::Variant | Minimum value of the slider |
| MaximumValue | FeatStd::Variant | Maximum value of the slider |
| StepSize | FeatStd::Variant | Step size for Value |
| MinimumAngle | FeatStd::Float | Angle of the slider, corresponding to minimum value. |
| MaximumAngle | FeatStd::Float | Angle of the slider, corresponding to maximum value. |
| ThumbNode | Candera::AbstractNodePointer | Thumb node which will be rotated. |
| ImageNode | Candera::AbstractNodePointer | Image node which will be masked. |
Drawer Behavior
Description
Drawer Behavior to switch node on/off.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Open | bool | Shows the Drawer in its opened appearance. |
| AppearDirection | AppearDirection::Enum | The direction from which the Drawer will open. |
| DragEnabled | bool | Set to true to allow the Drawer to be controlled by Touch Inputs. |
Internal Control Behaviors
Caret
Description
Behavior which receives the CaretPositionChanged Event from the EditTextBehavior. It forwards the value to other behaviors (e.g. SetSize) and switches the blinking state.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| CaretNode | Candera::AbstractNodePointer | Node which will be set as caret." type=" |
| IntervalSwitchBehavior | Candera::Behavior* | The Caret Behavior will change the state of the given IntervalSwitch Behavior. |
Handle Control State
Description
Basic Behavior which handles the states of a control. Sends a StateEvent to StateConditions.
Example Usage
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Highlighted | bool | If true, the controls state Highlighted is set to true. |
| Enabled | bool | If set to false it will not react on focus events and does not have to support different visualizations for the different states. |
| Focusable | bool | If true, the control is focusable. Otherwise the control can not be focused. |
| Identifier | Candera::AbstractNodePointer | Identifier which is used when emitting an Event (e.g. Click Event). |
DataContext
Description
This behavior provides a local data context on the associated node that can act as a set of binding sources (if a binding source is set at that data context). It is internally used by other behaviors like the list behavior to set individual binding sources for items.
Common Properties
This behavior does not have any configurable properties.
Edit Text
Description
Control Behavior to make a TextNode editable. Receives KeyEvents and emits CaretPositionChanged Events. These can be received by the CaretBehavior to set the position of the caret node.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| InputText | FeatStd::String | Text which will be set as default text. |
| TextNode | Candera::AbstractNodePointer | Text Node which will be edited. |
| Placeholder | Candera::AbstractNodePointer | Text which will be shown as placeholder. |
| SetValueOnEachChange | bool | If true, the value will be set on each input. |
| MaxTextLength | FeatStd::UInt16 | Maximum count of characters. |
| JustDigits | bool | If true, the Inputfield will receive just digits. |
Selection Group
Description
Provides an ArrayProperty for Selection Objects. If one of them gets selected the others get deselected (Objects need a ChangeSelectionActionBehavior). Needs to be attached to a value Behavior.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| DefaultSelectedObject | Candera::AbstractNodePointer | Selection Object (e.g. RadioButton) which shall be selected by default. |
Public Property Control Behaviors
Provide Alignment
Description
Provides properties to set the horizontal and vertical alignment. Especially for Controls.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| HorizontalAlignment | Candera::HorizontalAlignment | Provides property to set the Horizontal Alignment (especially for Controls). |
| VerticalAlignment | Candera::VerticalAlignment | Provides property to set the Vertical Alignment (especially for Controls). |
Copy Size
Description
Copies the layout size to a target node. Especially for Controls to transfer the size from the control node to an inner node.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| TargetNode | Candera::AbstractNodePointer | The target node to which the events are routed from the source node. If the property is not set, the event will be routed to the node of the behavior |
Provide Color
Description
Sets the color of a node with a Color effect attached (e.g. BitmapBrushColorBlend).
Common Properties
| Property Name | Type | Description |
|---|---|---|
| PropertyReference | CgiStudioControl::PropertyReference::Enum | Choose how the property gets set. Via own property or from another Behavior. |
| Color | Candera::Color | The color to set. |
Advanced Properties
| Property Name | Type | Description |
|---|---|---|
| PropertyProvider | Behavior* | Property Behavior which contains the color which has to be set on the effect. |
Provide Margin
Description
Provides property to set the margin. Especially for Controls.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Margin | Candera::Margin | Provides property to set the Margin (especially for Controls). |
Property Provider
Description
Offers to set a property of a selectable type. This property can then be used for other Behaviors (e.g. an image for Set Image or Provide Image).
Common Properties
| Property Name | Type | Description |
|---|---|---|
| PropertyDataType | CgiStudioControl::PropertyDataTypes::Enum | Choose the type which sould be offered by this behavior. |
Advanced Properties
| Property Name | Type | Description |
|---|---|---|
| Color | Candera::Color | The color which can be used from other Behaviors. |
| Text | FeatStd::String | The Text that will be set to the Text Node. |
| Image | <Candera::MemoryManagement::SharedPointer<Candera::Image2D>/td> | description="The image to set on the effect. |
| Texture | Candera::MemoryManagement::SharedPointer<Candera::TextureImage> | The texture to set on the effect. |
| Appearance | Candera::MemoryManagement::SharedPointer<Candera::Appearance> | The appearance to set on the node. |
| Value | FeatStd::Variant | The value that will be set to the Send Value as Event action. |
| Layout | CgiStudioControl::LayoutType::Enum | The layouter type for node. See Set Layout for more information. |
Render Node
Description
Sets rendering of a node to enabled or disabled and provides the setting as a property for Controls.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| EnableRendering | bool | If true, rendering is enabled. |
Provide Appearance
Description
ProvideAppearance, 3D only
Common Properties
| Property Name | Type | Description |
|---|---|---|
| PropertyReference | CgiStudioControl::PropertyReference::Enum | Choose how the property gets set. Via own property or from another Behavior. |
| Appearance | Candera::MemoryManagement::SharedPointer<Candera::Appearance> | The appearance to set on the node. |
Advanced Properties
| Property Name | Type | Description |
|---|---|---|
| PropertyProvider | Behavior* | Property Behavior which contains the color which has to be set on the effect. |
Provide Image
Description
Sets the image of a node and provides the Image as a property for Controls.
Example Usage
Common Properties
| Property Name | Type | Description |
|---|---|---|
| PropertyReference | CgiStudioControl::PropertyReference::Enum | Choose how the property gets set. Via own property or from another Behavior. |
| Image | Candera::MemoryManagement::SharedPointer<Candera::Image2D> | The image to set on the effect. |
| Texture | Candera::MemoryManagement::SharedPointer<Candera::TextureImage> | The image to set on the appearance. |
| PropertyProvider | Behavior* | Property Behavior which contains the color which has to be set on the effect. |
Set Layout
Description
Provides a published property to set the layout for Controls.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Layout | CgiStudioControl::LayoutType::Enum | Selects layouter type for node: None, Overlay, Stack, Baseline. |
| StackArrangement | Candera::StackLayouter::Arrangement | Selects arrangement for stack layouter. |
| PropertyReference | CgiStudioControl::PropertyReference::Enum | Choose how the property gets set. Via own property or from another Behavior. |
| PropertyProvider | Behavior* | Property Behavior which contains the layout which has to be set on the effect. See Property Provider for more information. |
Limitations
- Only certain built-in layouters are supported
- Scene Composer does not support displaying layout-related properties when layouter is assigned using SetLayout behavior.
Provide Text
Description
Modifies the text of a TextNode or CanvasText and provides the text as property for Controls.
Example Usage
Common Properties
| Property Name | Type | Description |
|---|---|---|
| PropertyReference | CgiStudioControl::PropertyReference::Enum | Choose how the property gets set. Via own property or from another Behavior. |
| Text | FeatStd::String | The Text that will be set to the Text Node. |
| PropertyProvider | Behavior* | Property Behavior which contains the color which has to be set on the effect. |
| Style | Candera::MemoryManagement::SharedPointer<Candera::TextRendering::SharedStyle> | The Style that will be set to the Text Node. |
| Alignment | Candera::TextNode2DLayouter::TextAlignment | The horizontal text alignment, using the culture text direction, is used to define how text will be horizontally aligned within its layout area. |
| Multiline | bool | If multi line is disabled then the new line control characters will be ignored and text will always be rendered in one line. |
| LineSpacing | Candera::TextRendering::PixelSize | Defines the distance between the baselines of successive lines of text. |
| WordWrap | bool | If word wrapping is enabled then the lines that exceed the client area will be split during arrangement into multiple lines. |
| Trimming | Candera::TextNode2DLayouter::Trimming | Trimming defines the behavior to employ when content overflows the content area. |
| TrimmingText | FeatStd::String | Trimming text defines the text which replaces content overflowing the content area. |
Align Pivot
Description
Aligns all child nodes according to their pivot point.
Example Usage
Common Properties
This behavior does not have any configurable properties.
Android Event Bridge
Description
Receives JsonEvents from an Android Control and transforms them to an equivalent CGI Studio event.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| TargetNode | Candera::AbstractNodePointer | The target node to which the events are sent. If the property is not set, the event will be routed to the node of the behavior. |
Arc Align
Description
Aligns child nodes in a circular layout. Provides properties for the radius, orientation offset and the min and max angle.
Example Usage
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Radius | Float | Radius of the digital needle indicators. |
| Orientation Offset | Float | Offset in the orientation of the needle indicators. |
| Angle Min Max | Vector2 | Min/Max angle values (e.g. indicators displayed from -25 to 210 degrees). |
Blend Mode
Description
Sets a blend mode from a given list of options. Depending on that option the behavior choses the appropriate blend factors and operations. In 2D it sets the values on the effect and in 3D on the render-mode if one is attached on the same node.
The following blend modes are available:
 |
|
The default blend mode comes in different variations, e.g. pre-multiplied, which should be applied if the alpha channel is pre-multiplied. The other blend modes are implemented according to the Porter-Duff composition modes.
In 3D there are two additional blend modes available:
- Lighten
- Darken.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Blend Mode | BlendType::Enum | Sets a blend mode from a given list of options. |
| PropertyReference | CgiStudioControl::PropertyReference::Enum | Choose how the property gets set. Via own property or from another Behavior. |
| PropertyProvider | Behavior* | Property Behavior which contains the color which has to be set on the effect. |
Breadcrumb Behavior
Description
Common Properties
| Property Name | Type | Description |
|---|---|---|
| StateMachineNode | Candera::AbstractNodePointer | The node of the State Machine |
| EllipsisText | FeatStd::String | When more elements are added than the breadcrumb can show, one element will be replaced with the text from this field (collapse effect). |
| PathDelimiter | FeatStd::String | Tag that separates the elements that a path contains. |
Disable Control
Description
This behavior is a Behavior Block
Enable Control
Description
This behavior is a Behavior Block.
Event Bridge
Description
Builds a bridge for events between two nodes for direct event dispatching. The events are routed from the source node to the target node (only in one direction).
Common Properties
| Property Name | Type | Description |
|---|---|---|
| TargetNode | Candera::AbstractNodePointer | The target node to which the events are routed from the source node. If the property is not set, the event will be routed to the node of the behavior. |
Focus
Description
This behavior is a Behavior Block.
Focus Leave
Description
This behavior is a Behavior Block.
Hover
See also
Description
This behavior is a Behavior Block.
Example Usage
HoverLeave
Description
This behavior is a Behavior Block.
Example Usage
IntervalSwitch
Description
Sends Off or On value to Trigger Behaviors that belong to same node.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| State | IntervalSwitchState::Enum | If set to On, sends only On value to Trigger Behaviors in the same node. If set to Off, sends only Off value to Trigger Behaviors in the same node. If set to Blinking, alternates between sending On or Off values. Use On Time Ms and Off Time Ms to specify the speed of blinking. |
| OnTimeMs | FeatStd::UInt32 | If State is set to Blinking, IntervalSwitchBehavior will be sending On value for On Time Ms miliseconds before switching to sending Off value. |
| OffTimeMs | FeatStd::UInt32 | If State is set to Blinking, IntervalSwitchBehavior will be sending Off value for Off Time Ms miliseconds before switching to sending On value. |
Keyboard Behavior
Description
This behavior provides the functionality of Keyboard control by managing the Keyboard Keys and setting their properties according to the Configuration Script.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| ConfigurationScript | FeatStd::String | String that specifies symbols and layout of the Control |
| StateMachineNode | AbstractNodePointer | State machine that reacts on events sent by a special key to change keyboard layout |
| KeyBackContentType | CgiStudioControl::KeyContent::Enum | Switch for Content of KEY_BACK special key |
| KeyBackText | FeatStd::String | KEY_BACK is labeled with the text (enabled with appropriate content type set to text) |
| KeyBackImage | SharedPointer<Candera::Image2D> | KEY_BACK is labeled with the image (enabled with appropriate content type set to image) |
| KeyEnterContentType | CgiStudioControl::KeyContent::Enum | Switch for Content of KEY_ENTER special key |
| KeyEnterText | FeatStd::String | KEY_ENTER is labeled with the text (enabled with appropriate content type set to text) |
| KeyEnterImage | SharedPointer<Candera::Image2D> | KEY_ENTER is labeled with the image (enabled with appropriate content type set to image) |
| KeySpaceContentType | CgiStudioControl::KeyContent::Enum | Switch for Content of KEY_SPACE special key |
| KeySpaceText | FeatStd::String | KEY_SPACE is labeled with the text (enabled with appropriate content type set to text) |
| KeySpaceImage | SharedPointer<Candera::Image2D> | KEY_SPACE is labeled with the image (enabled with appropriate content type set to image) |
| KeySwitchContentType | CgiStudioControl::KeyContent::Enum | Switch for Content of SWITCH special key |
| KeySwitchText | FeatStd::String | SWITCH is labeled with the text (enabled with appropriate content type set to text) |
| KeySwitchImage | SharedPointer<Candera::Image2D> | SWITCH is labeled with the image (enabled with appropriate content type set to image) |
| KeyShiftContentType | CgiStudioControl::KeyContent::Enum | Switch for Content of SHIFT special key |
| KeyShiftText | FeatStd::String | SHIFT is labeled with the text (enabled with appropriate content type set to text) |
| KeyShiftImage | SharedPointer<Candera::Image2D> | SHIFT is labeled with the image (enabled with appropriate content type set to image) |
| KeyCloseContentType | CgiStudioControl::KeyContent::Enum | Switch for Content of CLOSE special key |
| KeyCloseText | FeatStd::String | CLOSE is labeled with the text (enabled with appropriate content type set to text) |
| KeyCloseImage | SharedPointer<Candera::Image2D> | CLOSE is labeled with the image (enabled with appropriate content type set to image) |
| NavigateUpKeyCode | Candera::KeyboardKeyCode::Enum | Key from a physical keyboard that moves focus to a key above the current focused |
| NavigateDownKeyCode | Candera::KeyboardKeyCode::Enum | Key from a physical keyboard that moves focus to a key below the current focused |
| NavigateNextKeyCode | Candera::KeyboardKeyCode::Enum | Key from a physical keyboard that moves focus to a key on the right from the current focused |
| NavigatePreviousKeyCode | Candera::KeyboardKeyCode::Enum | Key from a physical keyboard that moves focus to a key on the left from the current focused |
| NavigateStartKeyCode | Candera::KeyboardKeyCode::Enum | Key from a physical keyboard that starts navigation within the Control |
| NavigateStartOnDown | bool | Enables starting navigation with the same key as NavigateDownKeyCode |
| NavigateEndKeyCode | Candera::KeyboardKeyCode::Enum | Key from a physical keyboard that finishes navigation within the Control |
| NavigateEndOnUp | bool | Enables finishing navigation with the same key as NavigateUpKeyCode |
| NavigateCloseKeyCode | Candera::KeyboardKeyCode::Enum | Key from a physical keyboard that hides the Control |
| NavigateInvokeKeyCode | Candera::KeyboardKeyCode::Enum | Key from a physical keyboard that emulates clicking the current focused Key from the Control |
Configuration String
The most important feature of the Keyboard Control is Configuration Script. It is parsed during layouting a scene which a keyboard is embedded on and keys (their appearance and their special functionalities) are arranged according to it.
The configuration script is simply a string. Each line of the string specifies a row of keys in the instance of keyboard and consists of space-separated list of key strings. A key string specifies a value that will be sent to a connected InputField. The most typical key string is simply a character or figure but it is not limited to it.
Following key strings have a special meaning:
| Key String | Meaning |
|---|---|
| enum from Candera::KeyboardKeyCode::Enum: KEY_BACK, KEY_SPACE, KEY_ENTER |
For most keys KEY_* has the same meaning as * (e.g. „KEY_A“ is the same as simply „A“); it enables keys with non-printable characters like backspace etc. |
| CLOSE() | Represents a key that sends Close KeyboardAction to a state machine; it is designed to enable hiding (setting EnableRendering to false) an instance of the Control |
| SWITCH(layoutName) | Represents a key that sends ¬¬to a state machine an event with its argument; it is designed to enable permanent changing layout e.g. to uppercase letters, symbols or digits |
| SHIFT(layoutName) | Mostly the same as SWITCH() but is separated to enable changing layout only for a single input, it means after entering a single letter (e.g. first capital letter in a sentence) the layout will be reset to the previous one |
| NULL() | Represents a key that will NOT be rendered; it is designed for a layouting/padding purpose |
Keyboard Control has public properties that customize labels of keys with the special meaning described above. One can set them custom text or image label.
Each key string (both regular and special) can be extended by a scaling factor in square brackets, e.g. SHIFT(Uppercase/en/US)[2] defines a key that sends to a state machine event with “Uppercase/en/US” string and the key itself is counted “2” times (like two different keys) when counting default width of a key in its row.
It is not obligatory to connect the Control to a state machine. There is a default set of layouts with lower- and uppercase english letters as well as digits and symbols with full switching support without a state machine.
Menu Item
Description
Sends Off or On value to Trigger Behaviors that belong to same node.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| DeleteButtonNode | Candera::AbstractNodePointer | Delete button node needed to control visibility (render on/off). |
| Focusable | bool | If true then focus node will be visible. |
| FocusNode | Candera::AbstractNodePointer | Focus node needed to control visibility (render on/off) and change focus image. |
| Enabled | bool | If true then item is visible. |
| FocusImageOnSelection | Candera::MemoryManagement::SharedPointer<Candera::Image2D> | The image to set on the effect. |
| FocusImageOnDragging | Candera::MemoryManagement::SharedPointer<Candera::Image2D> | The image to set on the effect. |
| Blend Type | CgiStudioControl::BlendType::Enum | Sets the blend option. |
MenuScreen
Description
The Control represents a menu in the form of a grid of icons (instances of the Menu Item Control). It has configurable number of rows and columns as well as default and maximum number of screens. A user can swipe between neighbouring screens. The Control handles user input and forwards proper information to children MenuItem nodes. The children nodes may be removed and reordered in runtime.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Action | MenuScreenAction::Enum | Action that will be called on the menu screen. |
| MenuItemNode | Candera::AbstractNodePointer | Needed to identify which node should be deleted. |
| MenuScreenNode | Candera::AbstractNodePointer | MenuScreen node to which event will be sent. |
| Blend Type | CgiStudioControl::BlendType::Enum | Sets the blend option. |
Navigation Instruction View
Description
Behavior for displaying the instructions during navigation.
| Property Name | Type | Description |
|---|---|---|
| SignDisplayNode | SignDisplayNodeType | Node used to display the graphical sign. |
| PrimaryTextNode | PrimaryTextNodeType | Node used to display the primary message. |
| SecondaryTextNode | SecondaryTextNodeType | Node used to display the secondary message. |
| ManeuverTypeTextNode | ManeuverTypeTextNodeType | Node used to display the maneuver type (as text). |
OnClick
Description
This behavior is a Behavior Block.
OnClick behavior allows to check for single, double or tripple (or any) Click events.
- Note:
- Click is a synthetic event composed by combining two basic events: Press and Release.
Example Usage
OnPressed
Description
This behavior is a Behavior Block.
OnPressed behavior allows to check for Pressed and Released (and LongPressed) events.
Example Usage
OnTimer
See also
Description
This behavior is a Behavior Block.
Example Usage
Orbit Camera Transform
Description
When attached to a Node, the specified camera will orbit around that Node. PLAYER USE ONLY
| Property Name | Type | Description |
|---|---|---|
| Camera | CameraType | The camera that looks at the associated node. |
Page Indicator
Description
Manages PageIndicator Control and its PageIndicatorElements.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| ActivePageIndex | FeatStd::Int32 | Index of active page (range from 0 to NumberOfPages - 1) |
| NumberOfPages | FeatStd::Int32 | Total number of pages (you have to ensure that PageIndicator has at least this number of child elements) |
| DecrementKeyCode | Candera::KeyboardKeyCode::Enum | Key used for decrementing value (if value is actually decremented, focus handling is suspended) |
| IncrementKeyCode | Candera::KeyboardKeyCode::Enum | Key used for incrementing value (if value is actually incremented, focus handling is suspended) |
| TargetNode | Candera::AbstractNodePointer | Target node that will receive a ChangeValueEvent when ActivePageIndex changes |
Rectangle Clipping Behavior
Description
Clips the control to given rectangle.
| Property Name | Type | Description |
|---|---|---|
| Width | WidthType | Width of the clipping rectangle. |
| Height | HeightType | Height of the clipping rectangle. |
| ClipPositionEnabled | ClipPositionEnabledType | Enable Clipping Position. |
Roll
Description
Roll is used for displaying and selecting entries representing Float values from range min..max with step size.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Step | FeatStd::Float | Value step (positive float value). |
Advanced Properties
| Property Name | Type | Description |
|---|---|---|
| ValueGroup | Candera::AbstractNodePointer | Node containing a range of displayed values |
| LensGroup | Candera::AbstractNodePointer | Node containing current value |
| DecorationGroup | Candera::AbstractNodePointer | Node containing lens decoration |
| Value | FeatStd::Float | Current value |
| Format | FeatStd::String | Value display format (use f for value) |
| Min | FeatStd::Float | Minimum value |
| Max | FeatStd::Float | Maximum value |
| Step | FeatStd::Float | Value step (positive float) |
| LensVisible | bool | Is lens group visible? |
| UseCyclicRoll | bool | Is roll cyclic? |
| AllowDraggingPastLimit | bool | Allow temporary over-dragging (dragging to blank values before first and after last entry) |
| DecrementKeyCode | Candera::KeyboardKeyCode::Enum | Key used for decrementing value (if value is actually decremented, focus handling is suspended) |
| IncrementKeyCode | Candera::KeyboardKeyCode::Enum | Key used for incrementing value (if value is actually incremented, focus handling is suspended) |
| EditKeyCode | Candera::KeyboardKeyCode::Key_Enter | Key used for entering text edit mode |
| TextEditNode | Candera::AbstractNodePointer | Node containing text edit field |
Touch Indication Behavior
Description
Used to display a touch indicator at the position where the screen is touched. Control must be positioned at position (0;0) if no offset to the touch location is desired.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| IndicationNode | Candera::AbstractNodePointer | The node moved by the Touch Indication Behavior. It is moved to the touch location to point it out. |
| TouchAreaNode | Candera::AbstractNodePointer | The node whose area the Touch Indication Behavior should indicate touch events on. |
| Camera | The camera used to render the touch indicator. Will be used to correctly match touch position with object position in case the camera has a position offset. | |
| DistanceFromCamera | FeatStd::Float | How far from the camera should the touch indication node be rendered. |
| OnAnimation | Candera::MemoryManagement::SharedPointer<Candera::Animation::AnimationPlayer> | Optional animation played when the indicator is shown. |
| OffAnimation | Candera::MemoryManagement::SharedPointer<Candera::Animation::AnimationPlayer> | Optional animation played when the indicator is hidden. |
| HideIndicatorOnMove | bool | Hide the touch indicator when a move is detected, otherwise the indicator will stay visible during movement until the finger is lifted from the screen. |
Transform Mesh2D
Description
Performs a perspective projection of a 3D rotated effect (e.g. Bitmap or SolidColor effects) based on the configured origin, rotation and field of view.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Rotation | FeatStd::Float | Defines the rotation angle in degree around configured rotation axis at the configured origin |
| CameraDistance | FeatStd::Float | Defines a normalized camera distance (the projection is based on a normalized geometry of widht and height 1) with a default value of 1. |
| FitToMaximumSizeRotation | FeatStd::Float | Defines the rotation angle in degree that will be uses as maximum for the FitToMaximumSize fit strategy. Default is an angle of 90 degree. |
| RotationAxis | Candera::Vector3 | Defines the axis (default is the y axis) for the rotation as a 3D direction vector (the vector will be internally normalized). |
| FieldOfView | FeatStd::Float | The area on the Y axis view field in degrees. It influences the perspective distortion of the projection. Higher angles will result in more distorted projection. Lower angles will result in less perspective distorted projections. The angle has to be higher than 0 and less than 180. |
| FitStrategy | TransformMesh2DFitStrategy::Enum | Defines how the perspective projected mesh should fit into the original boundaries. |
| HorizontalOrigin | CgiStudioControl::HorizontalOrigin::Enum | The origin influences where the rotation is performed and how the perspective projection looks. It is defined as a normalized (bitmap resolution independent) origin on the y axis as Left (0), Center (0.5), Right (1.0) or Custom (see CustomHorizontalOrigin). |
| VerticalOrigin | CgiStudioControl::VerticalOrigin::Enum | The origin influences where the rotation is performed and how the perspective projection looks. It is defined as a normalized (bitmap resolution independent) origin on the y axis as Top (0), Center (0.5), Bottom (1.0) or Custom (see CustomVerticalOrigin). |
| CustomHorizontalOrigin | FeatStd::Float | Defines a normalized (bitmap resolution independent) custom origin that can not be defined with Left, Center or Right. |
| CustomVerticalOrigin | FeatStd::Float | Defines a normalized (bitmap resolution independent) custom origin that can not be defined with Top, Center or Bottom. |
| OriginOffset | Candera::Vector2 | In addition to the configured normalized origin this pixel based origin offset is added. |
Event Handler
Description
Passes a value to a Condition Behavior and if the response is positive, invokes an Action behavior.
Example Usage
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Condition | Candera::ConditionBehavior* | The ConditionBehavior that TriggerBehavior passes a value to and expect a response from to see if Action needs to be invoked. |
| Actions | ActionBehaviorArrayProperty | The set of ActionBehaviors that TriggerBehavior invokes in the even that it receives a positive response from Condition. |
Virtual Key
Description
Receives a Change Value Event with a boolean. True will start emitting Key Events, false will stop emitting Key Events.
Common Properties
| Property Name | Type | Description |
|---|---|---|
| Modifier | Candera::KeyModifierEnum::Enum | Modifier Key (e.g. Shift) |
| KeyCode | Candera::KeyboardKeyCode::Enum | With KeyCode you can select any key. |