With this template you can add a new Radio Item component to your project. Radio Item is a simple widget the user can press in order to select an option within a list of available options. Each time the user interacts with the Radio Item, the component sends signals to associated slot methods where your particular implementation is executed. If the Radio Item is focused the component can also be controlled by pressing keys on the keyboard or by using hardware buttons. Generally menu items are used within menus only. Therefore when using a Radio Item you will also need to add at least one Menu component to your project.

Components created with this template are intended to be adapted to your particular design expectations. After adding the new Radio Item you should edit the component, change its appearance and if desired also its behavior. Once you have adapted the component, you can embed instances of this Radio Item wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Radio Items created by the template are working widgets. If desired, they can already be used as they are.

The following figure demonstrates the default appearance of the Radio Item created by using the here described component template. Please note, that Radio Items are used in sub menus containing the available options. The here described template includes also an additional Option Item which exists to refer the sub menu. When the user activates the Option Item, the corresponding sub menu is presented where the user can select the desired option:

The approach with component templates has two functions. Primarily the templates should simplify the development of new components. Instead of creating the Radio Item from scratch you can use the available template. The second function is more educative. The template implements fully working Radio Item component you can investigate and learn about the corresponding programming aspects. The template is well documented. It contains annotations and inline comments with instructions helping you to understand how the component works and how it can be adapted to your particular needs.

This chapter provides an overview how the Radio Item component template is used within your own application and how you adapt this component according to your particular needs. You will find here also further details concerning the internal implementation of the Radio Item component.

To create a new Radio Item component from a template you simply Drag & Drop it between the Templates window and the Composer with an opened unit. This is important in that by using the component templates you add in fact a new class to your project. Classes, in turn, can exist within units only. The following are the typical steps to create a new Radio Item component from a template:

The Radio Item template is composed of two components: RadioItem and OptionItem. The RadioItem is intended to create sub menus containing all possible options the user can select from (like radio buttons). The OptionItem, in turn, is used in superior menus to refer to this sub menu and display which radio item is currently selected in the associated sub menu. When the user activates the option item, the associated sub menu is presented automatically. For more details concerning the relations between the option and the radio items, see the description at the beginning of this chapter.

The new created Radio Item and Option Item components appear accompanied by annotation providing helpful tips how to proceed. If undesired, you can select and delete the annotation.

Once you have created the Radio Item component, you can use it to assemble menu components. Technically seen, you embed an instance of the Radio Item class in-place within a superior Menu GUI component. At the runtime, the superior Menu GUI component takes care of the correct initialization, arrangement and the displaying of all embedded item components.

The following are the typical steps to create a new instance of an already existing Radio Item component:

As long as the Radio Item is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below. This is in so far worth mentioning as diverse features of the Radio Item are controlled by the corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

The Radio Item component descends from the Mosaic class Core::Group. Consequently, most of the properties listed in the above screenshot are inherited from this base class. Particular to the Radio Item are only few following properties:

Property	Description
Caption	The property Caption stores the text to display within the item.
OnSelect	The property OnSelect can refer to a slot method, which will receive a signal as soon as the user has selected the radio item. Thereupon the method's logic will be executed.
Outlet	The property Outlet can refer to any other int32 property the item should remain synchronized with. When the user selects the radio item, the affected property is automatically updated to the value found in the property OutletSelector. On the other hand, when the referred property is modified by another component, the radio item is automatically notified to remain in sync with the property. The item appears selected, when the referred property has the value equal to OutletSelector. This approach follows the Model-View-Controller (MVC) programming paradigm. Here the radio item represents the view and controller. The property referred via Outlet can be seen as a part of the model. See also Outlet properties.
OutletSelector	The property OutletSelector contains a value identifying the radio item within a group of radio items. At the runtime, the item compares this value with the value of the property referred by Outlet and if both are equal, the radio item assumes the selected state (its property Selected is true). If the values are different, the radio item appears not selected. This selector is useful to build a group of radio item that refers to the same outlet. Different selectors for each radio item manages automatically the group of radio items.
Selected	The property Selected stores the current state of the radio item. As long as the property is false, the item should appear in the not-selected state. As long as the property is true, the item should appear in selected state.

The position of the Radio Item doesn't matter. The Menu component will automatically arrange the items within its area and if necessary enlarge or reduce their size. Moreover, the size of the menu itself is adapted to the number and to the size of the enclosed items. This layout algorithm is part of the Menu component template. Consequently, when you move an item within the menu, it does not have any effect on its final position.

However, the order in which the items will be displayed at the runtime does correspond to the order in which the item objects are stored within the menu component. This is the order in which the items have been originally added. Consequently, the first added item appears at the top of the menu while the last added item is arranged at the end of the menu. See also the column Order in the members area of the Inspector window:

Radio Items work together as a group to provide mutually exclusive selection. To create a functioning group of radio items, you need to configure their properties correctly:

The following example demonstrates how to configure three Radio Items for quality selection. The items are connected to a common property Application::Device.Quality. Consequently, the selection in all Radio Items remains in sync with the property value:

The Radio Item implements the Model-View-Controller (MVC) programming paradigm:

This architecture provides several advantages:

When the value of the property changes, the affected Radio Items are notified:

While the user interacts with the Radio Item, the component sends signals to the associated slot method specified in the OnSelect property. Within the slot method your particular implementation can react and process the selection event:

You can assign one and the same slot method to multiple Radio Item instances. At the runtime, when the slot method is signaled, evaluate the sender value to query which Radio Item has caused this event:

Once you have created the Radio Item component, you can use its Option Item to assemble menu components. Technically seen, you embed an instance of the Option Item class in-place within a superior Menu GUI component. At the runtime, the superior Menu GUI component takes care of the correct initialization, arrangement and the displaying of all embedded item components.

The following are the typical steps to create a new instance of an already existing Option Item component:

As long as the Option Item is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below. This is in so far worth mentioning as diverse features of the Option Item are controlled by the corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

The Option Item component descends from the Mosaic class Core::Group. Consequently, most of the properties listed in the above screenshot are inherited from this base class. Particular to the Option Item are only few following properties:

Property	Description
Caption	The property Caption stores the text to display within the item.
Outlet	The property Outlet can refer to any other int32 property the item should remain synchronized with. When the user selects a Radio Item, the affected property is automatically updated to the value found in the item's property OutletSelector. On the other hand, when the referred property is modified by another component, the Option Item is automatically notified to remain in sync with the property. This approach follows the Model-View-Controller (MVC) programming paradigm. Here the item represents the view and controller and the property referred via Outlet can be seen as a part of the model. See also Outlet properties.
Selection	The property Selection stores a value representing the current selection. This corresponds to the value OutletSelector of the actually selected item.
SubMenuClass	The property SubMenuClass determines the class of the menu GUI component to create and present when the user activates the menu item. This menu should consist of Radio Menu items.

The position of the Option Item doesn't matter. The Menu component will automatically arrange the items within its area and if necessary enlarge or reduce their size. Moreover, the size of the menu itself is adapted to the number and to the size of the enclosed items. This layout algorithm is part of the Menu component template. Consequently, when you move an item within the menu, it does not have any effect on its final position.

However, the order in which the items will be displayed at the runtime does correspond to the order in which the item objects are stored within the menu component. This is the order in which the items have been originally added. Consequently, the first added item appears at the top of the menu while the last added item is arranged at the end of the menu. See also the column Order in the members area of the Inspector window:

Option Items serve as entry points to sub menus containing Radio Items. To create a functioning Option Item, you need to configure its properties:

Component templates are intended to create widgets which can be adapted and enhanced to your particular design expectations. For this purpose, once you have added a new Radio Item component to your project, you can open the component class for editing. Thereupon the implementation of the component appears in a new Composer page:

Originally, if not yet modified, the Radio Item appears as a white rectangle with a caption text and a check mark image on the right side. The check mark is only visible when the item is selected. When the user interacts with the item, it changes color to provide visual feedback. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. The Radio Item can react to touch, mouse and keyboard inputs. The color reflects the actual state of the item.

This default functionality is implemented by following members belonging to the Radio Item. These members are explicitly intended to be modified. Understanding this internal structure is thus the first step before you start to adapt the Radio Item to your particular needs:

Icon	Member	Description
	Caption	The property Caption stores the text to display within the item.
	OnSetCaption	The onset method belongs to the property Caption. Each time the value of the property is changed, the code implemented in the method is executed to update the caption text view and trigger layout recalculation in the owner menu.
	Selected	The property Selected stores the current state of the radio item. As long as the property is false, the item appears in the not-selected state. As long as the property is true, the item appears in selected state with visible check mark.
	OnSetSelected	The onset method belongs to the property Selected. Each time the value of the property is changed, the code implemented in the method triggers an update of the item's appearance to reflect the new selection state.
	Outlet	The property Outlet can refer to any other int32 property the item should remain synchronized with. This implements the Model-View-Controller pattern. When the user selects the radio item, the affected property is automatically updated. On the other hand, when the referred property is modified elsewhere, the radio item is automatically notified and updates its state.
	OnSetOutlet	The onset method belongs to the property Outlet. When the property value changes, this method detaches from the old outlet, attaches to the new outlet, and synchronizes the item's state with the new outlet's value.
	OutletSelector	The property OutletSelector contains a value identifying the radio item within a group of radio items. This value is stored in the outlet property when the item is selected, enabling mutually exclusive selection behavior.
	OnSetOutletSelector	The onset method belongs to the property OutletSelector. When the selector value changes, this method updates the item's selection state by comparing the new selector with the current outlet value.
	OnSelect	The property OnSelect can refer to a slot method, which will receive a signal as soon as the user has selected the radio item. Thereupon the method's logic will be executed.
	onOutlet	This internal slot method is connected to the outlet property as observer. It is called automatically when the outlet property value changes. The method reads the new value and updates the Selected state of the radio item accordingly.
	onPressTouch	This internal slot method is called when the user touches the item area (when the interaction begins). This slot method is connected to the member TouchHandler. The method focuses the item and handles the feedback flash effect.
	onReleaseTouch	This internal slot method is called when the user releases the touch screen after touching the item (when the interaction ends). This slot method is connected to the member TouchHandler. The method selects the radio item if the touch ended inside the item area.
	onEnterLeaveTouch	This internal slot method is called when the user drags the finger/mouse while pressing the item and enters or leaves the item's area. The method updates the item's appearance to show pressed or released state.
	KeyHandler	This key handler reacts to key press events. When the user presses the key specified in the property Filter of the key handler (per default Enter), the handler is activated and the method onPressKey is called.
	onPressKey	This internal slot method is called when the KeyHandler has been activated (when the user has pressed the Enter key). Thereupon, the method flashes the item briefly and selects it.
	FlashTimer	This Timer object is used to flash the item when the user has tapped it very quickly or the item has been selected with the keyboard. This is just a visual feedback effect. The timer's Begin property defines the flash duration (50 milliseconds per default).
	onFlashTimer	This internal slot method is called when the FlashTimer expires. The method ends the flash feedback effect and selects the radio item by updating the Selected property and the outlet property if configured.
	Background	This Filled Rectangle view displays in the template the background of the item. The background is white per default.
	Border	This Border view displays in the template the border of the item. The border appears only when the item is selected (focused) or pressed. Depending on the item's actual state variables enabled, selected and pressed the border's visibility and color changes.
	CaptionText	This Text view displays the caption text of the item. The text content is determined by the property Caption. Depending on the item's actual state, the text color changes between black and white/gray. The text view is configured with ellipsis mode to truncate long text with [...] sign.
	CheckImage	This Image view displays the check mark indicating that the radio item is selected. The image is only visible when the item's Selected property is true. The check mark uses frame 8 from the Resources::NavigationIconsMedium bitmap resource.
	TouchHandler	This Simple Touch Handler reacts to touch and mouse events and invokes the associated slot methods: onPressTouch, onReleaseTouch and onEnterLeaveTouch.
	UpdateViewState	This method is invoked automatically after the state of the component has been changed. In case of the Radio Item, the method updates the views Background, Border, CaptionText and CheckImage so they reflect the item's current state.
	GetMinimalSize	This method is invoked by the owner menu to determine the minimum width required by this item. The method calculates the width based on the caption text length, margins, and the check mark image width. This information is used by the menu for automatic size adjustment.
	enabled	This variable stores the current state of the item. It is true if the item is allowed to handle user inputs (the component is enabled). See also Control the Enabled state of nested components. If the item is actually disabled, the variable is consequently false.
	selected	This variable stores the current state of the item. It is true if the item is actually focused for keyboard inputs (more precisely, the item is selected within its owner menu component). The user can thereupon control the item via keyboard.
	pressed	This variable stores the current state of the item. It is true if the item should appear pressed. This is usually the case when the user touches the item actively or presses a key intended to select the item (the user is pressing the item or the flash effect is active).
	checked	This variable stores the current selection state of the radio item. It is true when the item is selected (corresponds to the Selected property value). This variable is used to track state changes and trigger animations if desired.

During its lifetime, the Radio Item will assume different states as direct effect of user interactions and as result of other superior state alternations within the GUI application. To track its current state the Radio Item manages the above mentioned state variables: enabled, selected, pressed and checked. The variables are evaluated and updated within the implementation of the method UpdateViewState. This method evaluates the common component states (Enabled and Selected), verifies whether the user is actually interacting with the item, and reads the selection state from the Selected property. At the end of the method the estimated states are stored in the state variables:

The variable isChecked directly reflects the value of the Selected property. This property, in turn, is synchronized with the outlet property when the Outlet is configured. The radio item automatically compares its OutletSelector value with the outlet property value to determine if it should be selected.

When common component states (Enabled or Selected) have changed, the method UpdateViewState is invoked automatically. You don't need to worry about it. Any other state alternations need to explicitly request an invocation of the UpdateViewState method. This is especially true for state alternations caused by touch handlers, keyboard handlers, timer objects, or outlet property changes. When you modify the Radio Item to handle other user inputs or perform other animations always ensure that each state alternation (each event) does request an invocation of UpdateViewState. In your implementation you use for this purpose the method InvalidateViewState.

The selection state management in Radio Item is more complex than in simple Menu Items because it must:

This complexity enables the mutually exclusive radio button behavior: when one Radio Item in a group is selected, all others automatically deselect because their OutletSelector no longer matches the outlet value.

Depending on your design expectations the default state management may require adaptations. Generally, you are free to modify the method UpdateViewState, add further state variables to your Radio Item or even remove the existing functionality if it is not needed in your case.

Originally, if not yet modified, the Radio Item appears as a white rectangle with a caption text and a check mark on the right side. The check mark is only visible when the item is selected. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. It's up to you to adapt the item to have the expected appearance. The available possibilities are explained in the following sections. Please note, that you can combine the different approaches according to your application case:

The Radio Item template contains per default the views Background, Border, CaptionText and CheckImage. If desired, you can modify the views. For example, you can display them with other colors depending on the actual state of the item. For this purpose you change the implementation of the above explained method UpdateViewState responsible for tracking the state alternations within the Radio Item.

When you open the method UpdateViewState you will see that it does not only update the state variables but also updates the views existing within the component. Accordingly, depending on the actual state of the item the views Background, Border, CaptionText and CheckImage are displayed with other colors, the border's visibility changes, and the check mark shows or hides. By simply modifying this implementation you change the appearance. For example, you change the pressed color from red to blue:

The Radio Item template uses a check mark image from the Resources::NavigationIconsMedium bitmap resource (frame 8). If you want to use a different icon or your own custom bitmap:

If you prefer the traditional radio button appearance with circles instead of check marks:

You can enhance Radio Items by adding icons that represent each option visually:

If not needed, you can delete the per default existing views Background, Border, CaptionText and CheckImage. Doing this, please don't forget to also remove all references to the deleted views from the implementation of the UpdateViewState and GetMinimalSize method. Otherwise you will get error messages next time the Composer contents is reloaded. To avoid this error message we recommend to perform the steps in following order:

Also possible, you can replace the existing views by other views. For example, in the original version, the Radio Item displays the caption as an ordinary text. To make the component more sophisticated, you could replace the here used Text view by e.g. Attributed Text view to support rich formatted text. For this purpose:

The initial size of the Radio Item is determined by the thick blue border surrounding the Canvas area. It corresponds to the default size that all instances of this Radio Item component will have. However, when menu items are embedded within a menu, the Menu component will automatically adjust the size of items according to:

If desired, you can adjust the Canvas area of the item component itself. This affects the default height and visual proportions of the item during editing. For this purpose you click and drag the edges of the surrounding border (see also Resize the Canvas area). Once the size is changed, you can then adapt (move, resize) the views existing within the component.

The views existing per default in the Radio Item template (Background, Border, CaptionText and TouchHandler) are configured to automatically adjust to fill the area of the item. The CheckImage is configured to stay aligned at the right edge of the item. All other views you have eventually added later to the Radio Item are not adjusted automatically.

To control the adjustment you have to explicitly configure for each view its Layout property. (see also Configure component layout). Let's assume, in order to display an icon you have added an Image view to the Radio Item. Then you have arranged the view within the Canvas area according to your design expectation. If you want now that the view is centered vertically and remains aligned at the left side when the item width changes, you enable in the property Layout of this view following settings:

When creating your own Radio Item component you should ensure that instances of the item can be configured to control all the features implemented in it. For example, if you have enhanced the item to display some icon, you should allow this icon to be specified individually for each item instance. In this way several item instances can exist at the same time, each displaying another icon and representing different selectable options.

To control the features in your item you use properties. A property can be understood as variable where the corresponding setting is stored, e.g. the icon bitmap to display in the item or the outlet selector value. When the value of the property changes, the item can react to it and update its appearance accordingly. The properties reflect thus the settings within your item. Together they form the interface of the component.

Usually, each particular setting within a component is represented by the corresponding property. Thus, a radio item where caption, selection state, outlet and outlet selector can be configured will require four properties. In its original version, the Radio Item contains already four properties Caption, Selected, Outlet and OutletSelector. The first stores the text to display, the second stores the current selection state, the third can refer to any other int32 property the item should remain synchronized with, and the fourth contains a value identifying the radio item within a group of radio items. In order to enhance this interface by your own properties, following steps are necessary:

That is all. Now when you deal with instances of the Radio Item component, you can evaluate and modify the properties similarly to how you access variables. Especially, when the item instance is selected, you see in Inspector window the property and can change it there. The modification is immediately visible in the Composer window.

If desired, the properties can also be modified at the runtime of your application. For example, the caption or the selection state can be adapted dynamically. For this purpose you access and modify the affected property directly within Chora code:

The Radio Item is an interactive component. It can be controlled via touch screen or by the mouse device. For this purpose the template contains the Simple Touch Handler object named TouchHandler. Per default, this handler covers the entire area of the item - this is thus the touch sensitive area. To this handler are associated three slot methods: onPressTouch, onReleaseTouch and onEnterLeaveTouch. As their names imply the methods are invoked at the beginning of the interaction (press), at its end (release) and when the user drags the finger and enters or leaves the item's area:

The methods take care of two tasks. As first they request an invocation of the UpdateViewState method if due to the performed touch (mouse) interaction the visual appearance of the item does need the update. The second task is the activation of the item when the user successfully touches and releases within the item's area, which selects the radio item and notifies the owner component.

The Radio Item uses a feedback flash effect to provide visual feedback when the user taps the item very quickly. If the user holds the finger pressed for a short moment (at least 50 milliseconds per default), the item is activated immediately when released. If the user taps very quickly (less than 50 milliseconds), a short flash effect is shown first before the item is activated. This ensures the user always gets visual feedback.

The slot method onPressTouch is invoked when the user touches the item area:

Later, when the user finalizes the touch (mouse) interaction, the item is activated depending on whether the finger/mouse is still inside the item's area and how long the user held the item pressed. This functionality is implemented in the slot method onReleaseTouch:

The slot method onEnterLeaveTouch is invoked when the user drags the finger while touching the item and enters or leaves the item's area. This method is also invoked at the begining and at the end of the touch interaction. The method simply requests a visual update to show the item as pressed or released:

Usually you will not need to edit the implementation of these methods. It corresponds already to whatever typical radio items do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your item. For example, you can modify the flash duration by changing the Begin property of the FlashTimer object. A shorter duration (e.g. 25 milliseconds) makes the flash faster, a longer duration (e.g. 100 milliseconds) makes it slower.

Per default the TouchHandler is configured to handle all touch events. If necessary you can change this behavior and restrict the item to react only when the user performs a particular touch interaction. The TouchHandler provides for this purpose diverse configuration properties like MinStrikeCount, MaxStrikeCount, NoOfFingers or LimitToFinger. For more details, see Configure the filter condition.

If your device does not contain any touch screen nor mouse, the per default existing TouchHandler and its associated slot methods are unnecessary ballast. You can remove them in such case. We recommend to do this in following order to avoid eventual error message because of broken references between still existing and the already removed members:

The Radio Item is an interactive component. It can be controlled via keyboard or hardware buttons. For this purpose the template contains the Key Press Handler object named KeyHandler. To this handler is associated the slot methodonPressKey. The method is thus invoked when the user presses the key matching the filter condition specified in the handler object. This is per default the Enter key:

The method takes care of activating the item and showing the feedback flash effect. Similar to the touch handling, the method ensures that the user always gets visual feedback by showing a flash effect before selecting the radio item:

Usually you will not need to edit the implementation of this method. It corresponds already to whatever typical radio items do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your item.

Per default the key handler is configured to accept the Enter key. If necessary you can change this behavior and adapt the item to react to other keys. The key handler provides for this purpose the configuration property Filter. For example, if you want the item to be activated with the Space key, set the property Filter of the object KeyHandler to the value Core::KeyCode.Space. For more details, see Configure the filter condition.

If your device does not contain any keyboard nor hardware buttons, the per default existing key handler and its associated slot method are unnecessary ballast. You can remove them in such case. We recommend to do this in following order to avoid eventual error messages because of broken references between still existing and the already removed members:

The Radio Item uses a feedback flash effect to provide visual feedback when the user interacts with the item very quickly. This ensures that the user always sees a visible response to their action, even for very brief taps or key presses.

The flash effect is implemented using the Timer object named FlashTimer. This timer is configured with a duration (50 milliseconds per default) that determines how long the item should appear in the pressed state:

The timer is started in two situations:

When the timer expires, the slot method onFlashTimer is called, which ends the flash effect and selects the radio item:

The flash duration can be adjusted by modifying the Begin property of the FlashTimer object:

If you don't want the flash effect at all, you can simplify the touch and keyboard handling by removing the timer and directly setting the Selected property in the touch/keyboard handlers. However, this is not recommended as users expect visual feedback for their interactions.

The GetMinimalSize method plays a crucial role in the automatic layout system of menus. This method is called by the owner menu to determine how much horizontal space the item requires at minimum. The menu uses this information to:

The default implementation calculates the minimum width based on the caption text length plus the check image width plus margins:

Please note that the calculation temporarily disables the ellipsis mode of the text view to get the full text width without truncation. This ensures that the menu knows how much space is really needed to display the complete caption.

If you have modified the item appearance by adding icons, badges, or other decorations, you must adapt this method to include the additional space needed. For example, if you added an icon on the left side, take its width as well as an additional margin in account:

In the section Adapt the appearance of the component you learned how state alternations within the Radio Item are processed and how views existing in the component are updated in order to reflect the actual state. Accordingly, when the user touches the item (starts pressing it), the item does appear pressed. When the user releases the item again (ends pressing it), the item restores its released appearance. The default implementation performs such appearance updates instantly, just in the moment when the respective interaction took place.

If desired, you can modify the Radio Item to update its appearance with animations. For example, instead of instantly switching between the pressed and released appearance, such item can fade-in/out the background color, scale or fade the check image, or show other animated transitions. For this purpose you use the Animation Effects. With an Animation Effect you can animate a property of a view existing in the item. Following are the steps how to do this:

Component templates are intended to create widgets which can be adapted and enhanced to your particular design expectations. For this purpose, once you have added a new Option Item component to your project, you can open the component class for editing. Thereupon the implementation of the component appears in a new Composer page:

Originally, if not yet modified, the Option Item appears as a white rectangle with a caption text on the left side, a preview text on the right side showing the currently selected option, and an arrow icon indicating that a sub menu will open. When the user interacts with the item, it changes color to provide visual feedback. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. The Option Item can react to touch, mouse and keyboard inputs.

This default functionality is implemented by following members belonging to the Option Item. These members are explicitly intended to be modified. Understanding this internal structure is thus the first step before you start to adapt the Option Item to your particular needs:

Icon	Member	Description
	Caption	The property Caption stores the text to display on the left side of the item (the setting name, e.g. "Quality", "Language").
	OnSetCaption	The onset method belongs to the property Caption. Each time the value of the property is changed, the code implemented in the method is executed to update the caption text view and trigger layout recalculation in the owner menu.
	SubMenuClass	The property SubMenuClass determines the class of the menu GUI component to create and present when the user activates the menu item. This menu should consist of Radio Menu Items. The property must reference a class descending from Core::Group.
	OnSetSubMenuClass	The onset method belongs to the property SubMenuClass. It validates that the assigned class descends from Core::Group and triggers an update of the preview text to reflect the options available in the new sub menu. If the validation fails, an exception is thrown.
	Selection	The property Selection stores a value representing the current selection. This corresponds to the value OutletSelector of the actually selected Radio Item in the sub menu.
	OnSetSelection	The onset method belongs to the property Selection. When the selection value changes, this method triggers an update of the preview text to show the caption of the newly selected Radio Item.
	Outlet	The property Outlet can refer to any other int32 property the item should remain synchronized with. This property should be the same property that the Radio Items in the sub menu reference. When the outlet value changes, the Option Item automatically updates its preview text.
	OnSetOutlet	The onset method belongs to the property Outlet. When the property value changes, this method detaches from the old outlet, attaches to the new outlet as observer, and synchronizes the item's state with the new outlet's value.
	onOutlet	This internal slot method is connected to the outlet property as observer. It is called automatically when the outlet property value changes (typically when a Radio Item in the sub menu is selected). The method reads the new value and updates the Selection property accordingly.
	onUpdatePreview	This internal slot method is called when the preview text needs to be updated. The method creates a temporary instance of the sub menu, finds the selected Radio Item, extracts its caption, and displays it in the PreviewText view.
	openSubMenu	This internal slot method is called when the user has activated the Option Item. The method creates an instance of the sub menu specified in SubMenuClass and presents it as a dialog using PresentDialog() method. This is the core functionality that distinguishes the Option Item from basic menu items.
	onPressTouch	This internal slot method is called when the user touches the item area (when the interaction begins). This slot method is connected to the member TouchHandler. The method focuses the item and handles the feedback flash effect.
	onReleaseTouch	This internal slot method is called when the user releases the touch screen after touching the item (when the interaction ends). This slot method is connected to the member TouchHandler. The method opens the sub menu if the touch ended inside the item area.
	onEnterLeaveTouch	This internal slot method is called when the user drags the finger/mouse while pressing the item and enters or leaves the item's area. The method updates the item's appearance to show pressed or released state.
	KeyHandler	This key handler reacts to key press events. When the user presses the key specified in the property Filter of the key handler (per default Enter), the handler is activated and the method onPressKey is called.
	onPressKey	This internal slot method is called when the KeyHandler has been activated (when the user has pressed the Enter key). Thereupon, the method flashes the item briefly and opens the sub menu.
	FlashTimer	This Timer object is used to flash the item when the user has tapped it very quickly or the item has been activated with the keyboard. This is just a visual feedback effect. The timer's Begin property defines the flash duration (50 milliseconds per default).
	onFlashTimer	This internal slot method is called when the FlashTimer expires. The method ends the flash feedback effect and opens the sub menu.
	Background	This Filled Rectangle view displays in the template the background of the item. The background is white per default.
	Border	This Border view displays in the template the border of the item. The border appears only when the item is selected (focused) or pressed. Depending on the item's actual state variables enabled, selected and pressed the border's visibility and color changes.
	CaptionText	This Text view displays the caption text on the left side of the item. The text content is determined by the property Caption. Depending on the item's actual state, the text color changes between black and white/gray. The text view is configured with ellipsis mode to truncate long text with [...] sign.
	PreviewText	This Text view displays the preview text on the right side of the item showing the caption of the currently selected Radio Item from the sub menu. The text is right-aligned and uses a smaller font than the caption. The text view is configured with ellipsis mode to truncate long text with [...] sign.
	ArrowImage	This Image view displays the arrow icon on the far right indicating that a sub menu will be opened. The arrow provides visual feedback that activating this item will enter a sub menu. Per default, it displays frame 3 (right arrow) from the Resources::NavigationIconsMedium bitmap resource.
	TouchHandler	This Simple Touch Handler reacts to touch and mouse events and invokes the associated slot methods: onPressTouch, onReleaseTouch and onEnterLeaveTouch.
	UpdateViewState	This method is invoked automatically after the state of the component has been changed. In case of the Option Item, the method updates the views Background, Border, CaptionText, PreviewText and ArrowImage so they reflect the item's current state.
	GetMinimalSize	This method is invoked by the owner menu to determine the minimum width required by this item. The method calculates the width based on twice the caption text width (to accommodate both caption and preview text) plus margins. This information is used by the menu for automatic size adjustment.
	enabled	This variable stores the current state of the item. It is true if the item is allowed to handle user inputs (the component is enabled). See also Control the Enabled state of nested components. If the item is actually disabled, the variable is consequently false.
	selected	This variable stores the current state of the item. It is true if the item is actually focused for keyboard inputs (more precisely, the item is selected within its owner menu component). The user can thereupon control the item via keyboard.
	pressed	This variable stores the current state of the item. It is true if the item should appear pressed. This is usually the case when the user touches the item actively or presses a key intended to activate the item (the user is pressing the item or the flash effect is active).

During its lifetime, the Option Item will assume different states as direct effect of user interactions and as result of other superior state alternations within the GUI application. To track its current state the Option Item manages the above mentioned state variables: enabled, selected and pressed. The variables are evaluated and updated within the implementation of the method UpdateViewState. This method evaluates the common component states (Enabled and Selected) and verifies whether the user is actually interacting with the item via touch screen or keyboard (the user is pressing the item). At the end of the method the estimated states are stored in the state variables:

For example, the local variable isPressed will become true if the user is actually touching within the area of the item AND the finger/mouse is still inside the item's boundaries (the variables Down and Inside of the TouchHandler are both true) or the feedback flash timer is active (the variable Enabled of the FlashTimer is true). Being in this state, the item should assume the appearance indicating that the user is actively pressing it.

When common component states (Enabled or Selected) have changed, the method UpdateViewState is invoked automatically. You don't need to worry about it. Any other state alternations need to explicitly request an invocation of the UpdateViewState method. This is especially true for state alternations caused by touch handlers, keyboard handlers or timer objects. When you modify the Option Item to handle other user inputs or perform other animations always ensure that each state alternation (each event) does request an invocation of UpdateViewState. In your implementation you use for this purpose the method InvalidateViewState.

Depending on your design expectations the default state management may require adaptations. Generally, you are free to modify the method UpdateViewState, add further state variables to your Option Item or even remove the existing functionality if it is not needed in your case.

For example, the default implementation of the Option Item template manages the state selected. This state indicates that the item is actually selected within the superior menu. The item could thus receive keyboard events. However, whether the item is really able to receive events does depend on the selection status of its owner menu and all other superior components. Only when the item lies on the focus path, the item will receive keyboard events. If your application case requires the item to distinguish this additional state, you can add a variable focused similar to the approach described in the Horizontal Slider template.

Originally, if not yet modified, the Option Item appears as a white rectangle with caption text on the left, preview text on the right, and an arrow icon. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. It's up to you to adapt the item to have the expected appearance.

The PreviewText view displays the currently selected option. You can customize its appearance by modifying its properties:

If you want to use a different arrow icon or your own custom bitmap:

By default, the caption and preview text share the horizontal space roughly equally. You can adjust this proportion:

If not needed, you can delete the per default existing views Background, Border, CaptionText, PreviewText and ArrowImage. Doing this, please don't forget to also remove all references to the deleted views from the implementation of the UpdateViewState and GetMinimalSize method. Otherwise you will get error messages next time the Composer contents is reloaded. To avoid this error message we recommend to perform the steps in following order:

Also possible, you can replace the existing views by other views. For example, in the original version, the Option Item displays the caption as an ordinary text. To make the component more sophisticated, you could replace the here used Text view by e.g. Attributed Text view to support rich formatted text. For this purpose:

The initial size of the Option Item is determined by the thick blue border surrounding the Canvas area. It corresponds to the default size that all instances of this Option Item component will have. However, when menu items are embedded within a menu, the Menu component will automatically adjust the size of items according to:

If desired, you can adjust the Canvas area of the item component itself. This affects the default height and visual proportions of the item during editing. For this purpose you click and drag the edges of the surrounding border (see also Resize the Canvas area). Once the size is changed, you can then adapt (move, resize) the views existing within the component.

The views existing per default in the Option Item template (Background, Border, CaptionText, PreviewText and TouchHandler) are configured to automatically adjust to fill the area of the item. The ArrowImage is configured to stay aligned at the right edge of the item. The CaptionText is aligned to the left while the PreviewText is aligned to the right. All other views you have eventually added later to the Option Item are not adjusted automatically.

To control the adjustment you have to explicitly configure for each view its Layout property. (see also Configure component layout). Let's assume, in order to display an icon you have added an Image view to the Option Item. Then you have arranged the view within the Canvas area according to your design expectation. If you want now that the view is centered vertically and remains aligned at the left side when the item width changes, you enable in the property Layout of this view following settings:

When creating your own Option Item component you should ensure that instances of the item can be configured to control all the features implemented in it. For example, if you have enhanced the item to display some icon, you should allow this icon to be specified individually for each item instance. In this way several item instances can exist at the same time, each displaying another icon and opening different sub menus with different options.

To control the features in your item you use properties. A property can be understood as variable where the corresponding setting is stored, e.g. the icon bitmap to display in the item or the class of the sub menu to open. When the value of the property changes, the item can react to it and update its appearance accordingly. The properties reflect thus the settings within your item. Together they form the interface of the component.

Usually, each particular setting within a component is represented by the corresponding property. Thus, an option item where icon, caption, sub menu class and current selection can be configured will require four properties. In its original version, the Option Item contains already four properties Caption, SubMenuClass, Selection and Outlet. The first stores the text to display, the second determines which menu component to create and present when the user activates the menu item, the third stores a value representing the current selection, and the fourth can refer to any other int32 property the item should remain synchronized with. In order to enhance this interface by your own properties, following steps are necessary:

That is all. Now when you deal with instances of the Option Item component, you can evaluate and modify the properties similarly to how you access variables. Especially, when the item instance is selected, you see in Inspector window the property and can change it there. The modification is immediately visible in the Composer window.

If desired, the properties can also be modified at the runtime of your application. For example, the caption, the sub menu class or the selection can be adapted dynamically. For this purpose you access and modify the affected property directly within Chora code:

The Option Item is an interactive component. It can be controlled via touch screen or by the mouse device. For this purpose the template contains the Simple Touch Handler object named TouchHandler. Per default, this handler covers the entire area of the item - this is thus the touch sensitive area. To this handler are associated three slot methods: onPressTouch, onReleaseTouch and onEnterLeaveTouch. As their names imply the methods are invoked at the beginning of the interaction (press), at its end (release) and when the user drags the finger and enters or leaves the item's area:

The methods take care of two tasks. As first they request an invocation of the UpdateViewState method if due to the performed touch (mouse) interaction the visual appearance of the item does need the update. The second task is the activation of the item when the user successfully touches and releases within the item's area, which triggers the opening of the sub menu containing the option radio items.

The Option Item uses a feedback flash effect to provide visual feedback when the user taps the item very quickly. If the user holds the finger pressed for a short moment (at least 50 milliseconds per default), the item is activated immediately when released. If the user taps very quickly (less than 50 milliseconds), a short flash effect is shown first before the item is activated. This ensures the user always gets visual feedback.

The slot method onPressTouch is invoked when the user touches the item area:

Later, when the user finalizes the touch (mouse) interaction, the item is activated depending on whether the finger/mouse is still inside the item's area and how long the user held the item pressed. This functionality is implemented in the slot method onReleaseTouch:

The slot method onEnterLeaveTouch is invoked when the user drags the finger while touching the item and enters or leaves the item's area. This method is also invoked at the begining and at the end of the touch interaction. The method simply requests a visual update to show the item as pressed or released:

Usually you will not need to edit the implementation of these methods. It corresponds already to whatever typical menu items do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your item. For example, you can modify the flash duration by changing the Begin property of the FlashTimer object. A shorter duration (e.g. 25 milliseconds) makes the flash faster, a longer duration (e.g. 100 milliseconds) makes it slower.

Per default the TouchHandler is configured to handle all touch events. If necessary you can change this behavior and restrict the item to react only when the user performs a particular touch interaction. The TouchHandler provides for this purpose diverse configuration properties like MinStrikeCount, MaxStrikeCount, NoOfFingers or LimitToFinger. For more details, see Configure the filter condition.

If your device does not contain any touch screen nor mouse, the per default existing TouchHandler and its associated slot methods are unnecessary ballast. You can remove them in such case. We recommend to do this in following order to avoid eventual error message because of broken references between still existing and the already removed members:

The Option Item is an interactive component. It can be controlled via keyboard or hardware buttons. For this purpose the template contains the Key Press Handler object named KeyHandler. To this handler is associated the slot methodonPressKey. The method is thus invoked when the user presses the key matching the filter condition specified in the handler object. This is per default the Enter key:

The method takes care of activating the item and showing the feedback flash effect. Similar to the touch handling, the method ensures that the user always gets visual feedback by showing a flash effect before opening the sub menu:

Usually you will not need to edit the implementation of this method. It corresponds already to whatever typical menu items do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your item.

Per default the key handler is configured to accept the Enter key. If necessary you can change this behavior and adapt the item to react to other keys. The key handler provides for this purpose the configuration property Filter. For example, if you want the item to be activated with the Space key, set the property Filter of the object KeyHandler to the value Core::KeyCode.Space. For more details, see Configure the filter condition.

If your device does not contain any keyboard nor hardware buttons, the per default existing key handler and its associated slot method are unnecessary ballast. You can remove them in such case. We recommend to do this in following order to avoid eventual error messages because of broken references between still existing and the already removed members:

The Option Item uses a feedback flash effect to provide visual feedback when the user interacts with the item very quickly. This ensures that the user always sees a visible response to their action, even for very brief taps or key presses.

The flash effect is implemented using the Timer object named FlashTimer. This timer is configured with a duration (50 milliseconds per default) that determines how long the item should appear in the pressed state:

The timer is started in two situations:

When the timer expires, the slot method onFlashTimer is called, which ends the flash effect and opens the sub menu:

The flash duration can be adjusted by modifying the Begin property of the FlashTimer object:

If you don't want the flash effect at all, you can simplify the touch and keyboard handling by removing the timer and directly calling the openSubMenu slot in the touch/keyboard handlers. However, this is not recommended as users expect visual feedback for their interactions.

The GetMinimalSize method plays a crucial role in the automatic layout system of menus. This method is called by the owner menu to determine how much horizontal space the item requires at minimum. The menu uses this information to:

The default implementation calculates the minimum width based on twice the caption text length plus margins. This accounts for both the caption text and the preview text (which could potentially be as long as the caption):

Please note that the calculation temporarily disables the ellipsis mode of the text view to get the full text width without truncation. This ensures that the menu knows how much space is really needed to display the complete caption.

If you have modified the item appearance by adding icons, badges, or other decorations, you must adapt this method to include the additional space needed. For example, if you added an icon on the left side, take its width as well as an additional margin in account:

When the user activates an Option Item, it opens the associated sub menu as a modal dialog. This is implemented in the openSubMenu slot method. This method is invoked when the user activates the item (either through touch, mouse or keyboard input) and is responsible for creating and presenting the sub menu. Usually, the sub menu will contain Radio Items associated to the Option Item.

The implementation performs following checks:

You can customize how the sub menu appears and disappears by modifying the PresentDialog() invocation. The method provides several parameters to control the presentation:

For more details about dialog transitions and positioning, see Customize provided Dialog transition animations.

One of the features of the Option Item is its ability to automatically display the currently selected option from the associated sub menu. This is implemented through the onUpdatePreview slot method, which performs the following steps:

Here is the complete implementation:

This mechanism is triggered automatically in three situations:

In the section Adapt the appearance of the component you learned how state alternations within the Option Item are processed and how views existing in the component are updated in order to reflect the actual state. Accordingly, when the user touches the item (starts pressing it), the item does appear pressed. When the user releases the item again (ends pressing it), the item restores its released appearance. The default implementation performs such appearance updates instantly, just in the moment when the respective interaction took place.

If desired, you can modify the Option Item to update its appearance with animations. For example, instead of instantly switching between the pressed and released appearance, such item can fade-in/out the background color, scale the arrow image, fade or slide the preview text, or show other animated transitions. For this purpose you use the Animation Effects. With an Animation Effect you can animate a property of a view existing in the item. Following are the steps how to do this: