Touchable
Contents List
Control Development
______________________________________________________
Button CoverFlow Dial Drawer IconButton InputField Keyboard Menu Item Menu Screen PageIndicator Roll SpinBox Sub-List TextButton CheckBox ToggleButton RadioButton CircularSlider Slider ScrollView List MultiStateButton TouchIndication TouchIndication3D TouchIndication3DMarkerControlDevelopment
KeyboardKey
Keyboard key is building block of Keyboard Control.
Properties
This Control does not have any configurable properties.
Scrollbar
The Scrollbar is used internally in List and ScrollView and shows up when the layout-size of those controls is smaller than its actual content. It can be used by custom scrollable controls.
Properties
| Property Name |
Type |
Description |
| Scroll Direction |
Enum (Vertical, Horizontal) | The direction in which the Scrollbar scrolls. |
| Handle Minimum Size |
Integer |
The minimum height (for vertical scrollbar) or minimum width (for horizontal scrollbar) of the handle in pixels. |
| Scrollbar Visibility |
Enum (Automatic, Collapsed, Visible) | Configure the visibility of the scrollbar. By default it is set to Automatic which will determine the visibility based on the actual content. |
| Min Movement To Scrolling |
Integer |
Minimum distance a touch gesture needs to move to start scrolling. |
| Blend Type |
CgiStudioControl::BlendType::Enum |
Sets the blend option. |
Functionality
The Scrollbar emits a ScrollableEvent which can be forwarded to a Behavior (f.e. List Behavior, Scroll View Behavior) via the Event Bridge Behavior.
| Behavior Name |
Type |
predefined/userdefined |
Description |
| Event Bridge |
Control Behavior |
predefined in List and ScrollView Control |
Forwards the ScrollableEvent from the Scrollbar to a Behavior |
| List |
Control ConstructionKit Behavior |
predefined in List Control |
Internaly receives the ScrollableEvent from the Scrollbar. |
| Scroll View |
Control ConstructionKit Behavior | predefined in ScrollView Control |
Internaly receives the ScrollableEvent from the Scrollbar. |
PageIndicatorElement
A PageIndicatorElement is a Control that is part of the Page Indicator Control. The Page Indicator Control indicates the currently displayed page. PageIndicatorElement is intended to be used as component of Page Indicator and therefore is not focusable as individual element.
The Control offers the possibility to customize it’s appearance through 9 patch image and color properties.
Properties
| Property Name |
Type |
Description |
| Selected Indicator Image | Candera::Image2D | Image displayed when the control is in selected state. |
| Indicator Image | Candera::Image2D | Image displayed when the control is in base deselected state. |
| Selected Indicator Pressed Image | Candera::Image2D | Image displayed when the control is in selected state and pressed. |
| Indicator Pressed Image | Candera::Image2D | Image displayed when the control is in deselected state and pressed. |
| Hovered Color | Candera::Color | The color to blend with the current control image when the control is hovered. |
| Disabled Color | Candera::Color | The color to blend with the current control image when the control is disabled. |
Button
The visual appearance can be configured with three images depending on the button's state and a hovered color that can be defined including an alpha value.
Additionally the Button offers an Anchor to attach content. Therefore you can also set the padding of the Button and its content.
Properties
| Property Name |
Type |
Description |
| Enabled |
bool |
If true, the control is enabled. Otherwise the visual representation of the control will be changed to the disabled colors. Also disable the focus to avoid receiving input. |
| Focusable | bool | If true, the control is focusable. Otherwise the control can not be focused. |
| Normal Image | 9 Patch Image | The image which is used as Button Image for the color multiplication of other states like Hovered. |
| Pressed Image | 9 Patch Image | The image which is used as Button Image if the pressed state applies. |
| Focused Image | 9 Patch Image | Transparent image contained in the center (border) of the control which is activated if the control has the current focus. The control must be set as focusable. Note that the focused image will always be contained in the top layer of the control. |
| Hovered Color Property Reference | Enum (Self, Other) | Choose how the property gets set. Via own property or from another Behavior. |
| Hovered Color | Candera::Color |
The color which is used as hovered color for blending with the Button Image. This property is only available if Hovered Color Property Reference is configured for "Self". |
| Hovered Color Property Provider |
Candera::Behavior |
Property Behavior which contains the color which has to be set on the effect. This property is only available if Hovered Color Property Reference is configured for "Other". |
| Disabled Color Property Reference |
Enum (Self, Other) | Choose how the property gets set.Via own property or from another Behavior. |
| Disabled Color | Candera::Color |
The color to set on the disabled Button. This property is only available if Disabled Color Property Reference is configured for "Self". |
| Disabled Color Property Provider |
Candera::Behavior |
Property Behavior which contains the color which has to be set on the effect. This property is only available if Disabled Color Property Reference is configured for "Other". |
| Padding | Candera::Margin | Padding of the Button. Used when a content is attached. |
| Blend Type | CgiStudioControl::BlendType::Enum | Sets the blend option. |
Functionality
The functionality of the button can be edited in the Behaviors panel or in the EventHandler Tab (see chapter EventHandler Tab). An EventHandler that checks for Clicks will perform the user defined action.
| Behavior Name |
Type |
predefined/userdefined |
Description |
| EventHandler | Control Behavior | predefined |
Checks a defined condition and invokes a defined action behavior if that condition is true. |
| CheckClick | Input Condition Behavior | predefined | Condition checks if the button has been clicked |
| Action | Action Behavior | userdefined | Userdefined action that will be performed when the button is clicked. |
CoverFlow
A CoverFlow is a proof-of-concept control that allows for horizontal swiping of child items. The items are scaled according to their location.
Child items are placed in provided anchor. It is possible to add padding by placing blank items at the beginning and at the end of the anchor content.
By default, the CoverFlow works horizontally.
Properties
| Property Name |
Type |
Description |
| Value | Float/Variant | Current value (position) of the CoverFlow. |
| Minimum | Float/Variant | The minimum value of CoverFlow. |
| Maximum | Float/Variant | The maximum value of CoverFlow. |
| Zoom Minimum |
Float/Variant |
Zoom effect minimum value. |
| Zoom Maximum |
Float/Variant | Zoom effect maximum value. |
| Increase Swipe Direction |
Enum (Left, Right, Up, Down) |
The direction of the swipe to increase value |
| Decrease Swipe Direction |
Enum (Left, Right, Up, Down) |
The direction of the swipe to decrease value |
| Orientation | StackLayouter::Arrangement | Selects arrangement for cover flow. See Set Layout for more information. |
| Blend Type | CgiStudioControl::BlendType::Enum | Sets the blend option. |
Dial
A dial is used to set a value within a specified range or to select between different options which are represented by the value of the dial. The control knob changes the value when the user touches and turns it. The degree of rotation corresponds to the desired value change. The dial snaps into its predefined positions defined by its step size.
The below figure shows an example using a 3-step rotation, with a Minimum Rotation of -45 degrees, Maximum Rotation of +45 degrees, and Step Size of 45 degrees. In this example, BackgroudImages 0 is displayed corresponding to Current Value = 0. Similarly, Current Value = 1 displays BackgroudImages 1 and Current Value = 2 displays BackgroudImages 2.
For a 5-step rotation with a Minimum Rotation of -90 degrees, Maximum Rotation of +90 degrees, and Step Size of 45 degrees, you will need to set 5 BackgroudImages.
The rotary knob supports events. If it receives an event of value change (ValueChangeEvent), the knob will be set accordingly. When the control is focused it is possible to control it using the keyboard (up/down arrow).
Properties
| Property Name |
Type |
Description |
| 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. |
| Current Value |
FeatStd::Int32 | Current value for the dial. |
| Step Size |
FeatStd::Float | Step size in degrees. |
| Minimum Rotation |
FeatStd::Float | Minimum rotation of the dial. |
| Maximum Rotation |
FeatStd::Float | Maximum rotation of the dial. |
| Knob Image |
Candera::Image2D | The image to set on the effect. |
| BackgroundImages |
Candera::Image2D | A list of images which should be available for selection. |
| Focus Image |
Candera::Image2D | The image to set on the effect. |
| Disabled Color |
Candera::Color | The color which can be used from other Behaviors. |
| Hovered Color |
Candera::Color | The color which can be used from other Behaviors. |
| Increment Key Code |
Candera::KeyboardKeyCode::Enum | Check the KeyCode of the pressed key (can also be modifier). |
| Decrement Key Code |
Candera::KeyboardKeyCode::Enum | Check the KeyCode of the pressed key (can also be modifier). |
| Blend Type |
CgiStudioControl::BlendType::Enum | The blend type that will be set on the affected node. |
Drawer
The Drawer Control provides a retractable area controlled via events. It offers an Anchor, where any kind of nodes can be attached to.
If the Drawer receives a Drawer Event, the Control will open or close itself. The "Change Drawer State" action allows to send these events and also provide the functionality to toggle the state of the Drawer Control.
When the "Drag Enabled" Property is set to true, then the Drawer can also be opened/closed by dragging the Knob.
All nodes that are attached to the Anchor will be displayed in the same way as they would be displayed when attached to an Overlay Layouter.
The image below shows a Drawer Control with "Appear Direction" left in initial state and in closed state. When the drawer gets closed, it slides to the left and gets hidden like closing a desk drawer.
Nine-Patch-Images are not supported by Drawer Image properties (Knob Pressed Image, Knob Normal Image).
Properties
| Property Name |
Type |
Description |
| Open | bool | If true, the control is shown in it's opened state. Otherwise the visual representation of the control will be it's closed state. |
| Appear Direction | Enum (Left, Right, Top, Bottom) |
Specifies the direction from which the content will appear. |
| Knob Pressed Image | Candera::Image2D | Specifies the look of the draggable Knob when it is pressed. Note: Should have the same or a bigger size than the Normal Image. |
| Knob Normal Image | Candera::Image2D | Specifies the look of the draggable Knob when it is not pressed. Note: Should have the same or a smaller size than the Pressed Image. |
| Drag Enabled | bool | If true, then the draggable Knob is active and visible. |
| Blend Type | CgiStudioControl::BlendType::Enum | Sets the blend option. |
IconButton
Properties
| Property Name |
Type |
Description |
| Identifier |
String |
Identifier which is used when emitting an Event (e.g. Click Event). |
| 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. |
| Normal Image | 9 patch image | The Image which is used if the normal state applies. |
| Pressed Image | 9 patch image | The Image which is used if the pressed state applies. |
| Focused Image | 9 patch image | Image which is transparent in the center (border). It gets activated if the control has the current focus. Therefore be sure that the Button is focusable. |
| Hovered Color | Candera::Color | The color which is used as hovered color for blending with the Button Image. |
| Disabled Color | Candera::Color | The color which is used for blending with the disabled Button Image. |
| Padding |
Candera::Margin | Padding of the button. Used when a content is attached. |
| Icon Horizontal Alignment | Enum (Left, Center, Right) | The horizontal alignment of the icon. |
| Icon Vertical Alignment | Enum (Top, Center, Bottom) | The vertical alignment of the icon. |
| Icon Normal Image | Candera::Image2D | The image which is used as Icon on the button if not pressed or hovered. |
| Icon Pressed Image | Candera::Image2D | The image which is used as Icon on the button if the pressed state applies. |
| Icon Focused Image |
Candera::Image2D | The image to set on the effect. |
| Icon Hovered Color |
Candera::Color | The color which is used as hovered color for blending with the button Icon image. |
| Icon Disabled Color |
Candera::Color | The color which is used for blending with the disabled button Icon Image. |
| Blend Type | CgiStudioControl::BlendType::Enum | Sets the blend option. |
InputField
The InputField contains an editable text. If the Control has the keyboard focus it can be modified by receiving “Key Events”. This events can e.g. be sent from a “Virtual Key Behavior”. Additionally the InputField contains a caret which can be shifted by “Key Events” (KeyCode: Key_LeftArrow or Key_RightArrow). Furthermore the Inputfield sends “Enter Exit" Events in case of losing the focus. This events can be checked by an Event Handler with the “Check Enter Or Exit Behavior” e.g. to activate a virtual keyboard. As other Controls it contains a value (string) which can be forwarded. Therefore just use the “Forward Value” Behavior and set another Control as Target Node.
The default text and the placeholder text have got additional properties for customizing them visually.
Properties
| Property Name |
Type |
Description |
| Enabled | bool | If true, the control is enabled. Otherwise the visual representation of the control will be changed to the disabled colors. Also disable the focus to avoid receiving input. |
| Focusable | bool | If true, the control is focusable. Otherwise the control can not be focused and will not receive any inputs. |
| DefaultText | String | Text which will be set as default text. |
| Text Color |
Candera::Color | The color set on the text. |
| Text Style |
Text Style |
The Style that will be set to the Text Node. |
| Text Disabled Color |
Candera::Color |
The color to set on the text if the control is disabled. |
| Placeholder Text | String | The Text that will be set to the Text Node. |
| Placeholder Text Color |
Candera::Color | The color of the placeholder text. |
| Placeholder Text Style |
Text Style |
The Style that will be used. |
| Placeholder Disabled Color |
Candera::Color |
The color to set on the effect of the Text. |
| Caret Image | Candera::Image2D | The image to set as caret. |
| Off Time Ms | Integer | Milliseconds before switching the blinking caret to On state. |
| On Time Ms | Integer | Milliseconds before switching the blinking caret to Off state. |
| Background Image | Candera::Image2D | The image to set as Background. |
| BG Disabled Color | Candera::Color | The color to set on the BG if the control is disabled. |
| Focused Image | Candera::Image2D | The image to set as focusborder. |
| Set Value On Enter |
bool |
If true, the value will be set when the Enter key is pressed. |
| Set Value On Each Change | bool | If true, the value will be set on each input. |
| Max Text Length | Integer | Maximum count of characters. |
| Just Digits | bool | If true, the Inputfield will receive just digits. |
| Blend Type | CgiStudioControl::BlendType::Enum | The blend type that will be set on the affected nodes. |
| Keyboard Node |
Node |
Keyboard node. |
| Keyboard Layout Name |
String |
Layout name. |
Keyboard
The Keyboard Control emulates physical computer keyboard that enables a user to enter characters into an InputField Control. The Keyboard Control is highly customizable via Configuration Script described below.
To use the Control one needs to connect an InputField with a keyboard via KeyboardAction with Action Open. When the InputField send the event, the Keyboard appears and sends pressed characters to the InputField that activates it.
Properties
| Property Name |
Type |
Description |
| Configuration Script | String |
Keyboard layout configuration script - key definitions (strings, KeyboardCodes or KeyboardActions) separated by spaces and newlines; may have parameters in parentheses and width specifiers in square brackets. See documentation and examples for reference. See Keyboard Behavior for more information. |
| State Machine Node |
Node |
Node containing State Machine Behavior, that will be sent a ValueChanged event with layout name, when layout switching occurs. In turn, State Machine may send SetConfiguration KeyboardAction to the Keyboard, to set new Keyboard layout configuration string. If left empty, layout changes will trigger ValueChanged on Keyboard node itself - in this case layout configuration string may be updated using Value change conditions attached to Keyboard node. |
| Navigate Up Key Code |
Candera::KeyboardKeyCode::Enum | Key used for navigating up |
| Navigate Down Key Code |
Candera::KeyboardKeyCode::Enum | Key used for navigating down |
| Navigate Next Key Code |
Candera::KeyboardKeyCode::Enum | Key used for navigating right |
| Navigate Previous Key Code |
Candera::KeyboardKeyCode::Enum | Key used for navigating left |
| Navigate Start On Down Key |
bool |
Enter navigation mode when pressing down key for the first time |
| Navigate End On Up Key |
bool |
Exit navigation mode when pressing up key on the first row |
| Navigate Start Key Code |
Candera::KeyboardKeyCode::Enum | Key used for entering navigation mode |
| Navigate End Key Code |
Candera::KeyboardKeyCode::Enum | Key used for exiting navigation mode |
| Navigate Close Key Code |
Candera::KeyboardKeyCode::Enum | Key used for closing keyboard |
| Navigate Invoke Key Code |
Candera::KeyboardKeyCode::Enum | Key used for invoking key action |
| Blend Type |
CgiStudioControl::BlendType::Enum | The blend type that will be set. |
MenuItem
A proper usage is to place or create it inside a MenuScreen control because of internal events that communicate with it. Those events handle runtime repositioning an instance of MenuItem or deleting it from a MenuScreen.
Properties
| Property Name |
Type |
Description |
| Enabled | bool | If true, then item is visible |
| Focus Image On Selection | 9-patch image | The border image is set while the MenuItem is selected |
| Focus Image On Dragging | 9-patch image | The border image is set while the MenuItem is in edit mode |
| Delete Button Normal Image | 9-patch image | The image will be shown in top-right of the Control in edit mode to enable deletion of the instance of MenuItem |
| Delete Button Pressed Image | 9-patch image | The image will be set while Delete Button is pressed |
| Delete Button Hovered Color | Candera::Color | The color will be blend with Delete Button images while a user has his cursor over the Delete Button |
| Focusable |
bool |
If true then focus node will be visible |
| Image | 9-patch image | A bitmap that is the icon of the Control |
| Label | String | A text that will be set to the Text Node. |
| Label Color | Candera::Color |
A color of the Icon Label. |
| Label Style | Text Style | A font style of the Text. |
| Label Trimming | Enum (None, Ellipsis, Custom Text) |
Trimming defines the behavior to employ when content overflows the content area |
| Blend Type | CgiStudioControl::BlendType::Enum | The blend type that will be set. |
Menu Screen
The Menu Screen 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 neighboring screens. The Control handles user input and forwards proper information to children MenuItem nodes. The children nodes may be removed and reordered at run time.
Properties
| Property Name |
Type |
Description |
| ActiveScreenIndex | FeatStd::UInt32 | Index (starting at 0) of the current visible screen. |
| NumberOfScreens | FeatStd::UInt32 | Default number of screens (can be changed in runtime) |
| Rows | FeatStd::UInt32 | Number of rows of a grid in a single screen |
| Columns | FeatStd::UInt32 | Number of columns of a grid in a single screen |
| Items | Binding Source | Binding to a list containing icons and labels that should be accessible in the MenuScreen |
| Swap Item Animation Easing Function | CgiStudioControl::EasingFunctions::Enum | Interpolation method for animations of swapping items |
| Swap Item Animation Length | FeatStd::Float | Length of the swapping animation |
| Change Screen Animation Easing Function | CgiStudioControl::EasingFunctions::Enum | Interpolation method for animations of changing screens |
| Change Screen Animation Length | FeatStd::Float | Length of the changing animation |
| Key Code To Move Selection Left | Candera::KeyboardKeyCode::Enum | Key that changes focus from an item to its left neighbor |
| Key Code To Move Selection Right | Candera::KeyboardKeyCode::Enum | Key that changes focus from an item to its right neighbor |
| Key Code To Move Selection Up | Candera::KeyboardKeyCode::Enum | Key that changes focus from an item to its top neighbor |
| Key Code To Move Selection Down | Candera::KeyboardKeyCode::Enum | Key that changes focus from an item to its bottom neighbor |
| Focusable | bool | Enables grabbing focus by the Control |
| Screen Change Timeout | FeatStd::Float | Time of dragging a Menu Item outside the Control to fire Change Screen |
| Background Image | Candera::Image2D | Background image of screens |
| Focus Border Image | Candera::Image2D | Image of the border rendered when the Control grabs focus |
| Limit Of Screens | FeatStd::UInt32 | Maximum number of screens that may be handled by the Control in runtime |
| Page Indicator Node | Node | Page indicator that helps in navigation between screens of the Control |
| Blend Type | CgiStudioControl::BlendType::Enum | The blend type that will be set. |
PageIndicator
A Page Indicator is a control that indicates currently visible page of set and provides method to switch to another page directly by click or if focused in a stepping manner using rotary action input.
The control interacts with MenuScreens through exchange of ValueChange and ChangeValue events. The cooperating control is set in Target Node property.
The action keys will move the focus in/out of the control and when in then will switch pages until first or last page is reached. Continued action will pass the focus out of the control.
By default the control supports up to 8 pages, support for more pages requires manual addition of additional PageIndicatorElements in the control.
Properties
| Property Name |
Type |
Description |
| Target Node | Node | A node to exchanging events. |
| Active Page Index | FeatStd::UInt32 | Index of currently visible page. Must be in range from 0 to Number Of Pages - 1 . |
| Number Of Pages | FeatStd::UInt32 | Number of available pages. |
| Decrement Key Code | Candera::KeyboardKeyCode::Enum | The Key Code triggering decrement of the value. |
| Increment Key Code | Candera::KeyboardKeyCode::Enum | The Key Code triggering increment of the value. |
| Blend Type | CgiStudioControl::BlendType::Enum | Sets the blend option. |
Roll
The Control represents a vertical list of numeric values from a specified range with a specified step. Current value of the Control is visible in the middle of the control and can be zoomed like using lens. Changing the current value can be animated and can be done using touch/pointer or configurable keys of a keyboard. One can edit the current value of the Control by entering it with a keyboard.
To use the Control simply put it in a scene and configure all desirable properties. A roll can forward value as well as receive a send value as event.
The range is implemented in a way that it starts at Minimum Value, increases by (positive) StepSize but no further than Maximum Value. This conforms to the way range stepping is usually implemented, and gives configuration flexibility.
Properties
| Property Name |
Type |
Description |
| Focusable |
bool |
If true, the control is focusable. Otherwise the control cannot be focused. |
| Value | Float | The value which will be changed using the roll |
| Min | Float | The minimum value which can be reached. This value is always smaller or equal to the MaxValue. |
| Max | Float | The maximum value which can be reached. This value is always bigger or equal to MinValue |
| Step | Float | The increment/decrement of the value. |
| LensVisible | bool | Is lens group visible? Enables highlighting of the current value, default zooming and bordering it. |
| Use Cyclic Roll | bool | Is roll cyclic? If true the MinValue of the Control can be reached after the MaxValue of the Control and vice versa |
| Allow Dragging Past Limit | bool |
Allow temporary over-dragging (dragging to blank values before first and after last entry). If true there is visible animation of the Control being „out of range“ while moving below minimum and above maximum value. |
| Value Style | Candera::TextRendering::Style | Sets the text style for the values outside the Lens. |
| Value Color | Candera::Color | Specifies color of values in the vertical list outside the Lens |
| Lens Style | Candera::TextRendering::Style | Sets the text style for the values inside the Lens. |
| Unit Text | String | Text used in lens (it means: when the lens is used at all) to present a unit of the value |
| Unit Style | Candera::TextRendering::Styler | Sets the text style for the Unit Text. |
| Unit Margin | Candera::Margin | Specifies margin of the UnitText |
| Unit Color | Candera::Color | Specifies color of the UnitText |
| Decoration Image | Candera::Image2D | Specifies a border image of the Lens |
| Text Input Color | Candera::Color | Speficies color of the text entered in the InputField while editing the current value of the Control |
| Text Edit Background | Candera::Image2D | The background image used for the Input Field when entering Text Edit mode. |
| Max Text Length | Unsigned Int 16 | Specifies maximum count of characters that may be entered while editing the current value of the Control |
| Decrement Key Code | Candera::KeyboardKeyCode::Enum | Key used to decrement the current value of the Control |
| Increment Key Code | Candera::KeyboardKeyCode::Enum | Key used to increment the current value of the Control |
| Edit Key Code | Candera::KeyboardKeyCode::Enum | Key used to enter edit mode (show InputField) of the current value of the Control |
| Blend Type | CgiStudioControl::BlendType::Enum | Sets the blend option. |
| Keyboard Node | Node | Specifies which Keyboard control should be used when entering edit mode. |
| Keyboard Layout Name | String | Layout name. |