Reference for the Mosaic class WidgetSet::RadioButton
This class implements a bistable 'radio button' widget. When the user taps the button, the current state of the button represented by the boolean property Selected is set and signal is sent to the slot method stored in the property OnSelect. Once selected, the radio button remains in this state until the property Selected is set to the value 'false' (e.g. in reaction to another radio button selection). By connecting further slot methods to the properties OnPress, OnRelease, OnEnter and OnLeave you can react to other events triggered while the user interacts with the button.
Alternatively the property Outlet can refer to any other 'int32' property the widget should remain synchronized with. When the user selects the radio button, the affected property is automatically set to the value OutletSelector. On the other hand, when the referred property is modified by another one, the radio button is automatically notified to remain in sync with the property.
This approach follows the Model-View-Controller (MVC) programming paradigm. Here the radio button represents the 'View' and 'Controller' and the property referred via 'Outlet' can be seen as a part of the 'Model'.
During its lifetime the button remains always in one of the four states: 'disabled', 'default', 'focused' and 'active'. The state 'disabled' is true for every not available button (the property Enabled of the button is 'false'). Such buttons will ignore all user inputs. The state 'default' determines a button, which is ready to be touched by the user or ready to become focused. As soon as the button becomes focused, it switches in the state 'focused'. In this state the user can activate the button by pressing a key on the keyboard. Finally, the state 'active' is true, if the user actually interacts with the button (the button is pressed).
The exact look and feel of the radio button is determined by the 'Radio Button Configuration' object assigned to the property Appearance. The configuration object provides bitmaps, colors, fonts and other configuration parameters needed to construct and display the radio button. Usually, you will manage in your project your own configuration objects and customize the radio buttons according to your design expectations.
In particular application cases you can instruct the button to automatically resign and retarget the actual touch interaction to another touch handler (e.g. another widget) after the user has performed a horizontal wipe gesture (ResignAfterHorizontalWipe) or vertical wipe gesture (ResignAfterVerticalWipe). Using these properties several widgets can cooperate during an active user interaction even if these handler overlap each other.
If the button is actually focused, it can also be activated by pressing the keyboard key Core::KeyCode.Enter. In the configuration object you can specify another key code, if desired. To prevent the button from being able to be focused, specify in the configuration object the Core::KeyCode.NoKey as the code to activate the button.
The radio button widget provides an additional set of methods useful to query the actual state of the widget (GetCurrentState(), GetTransitionStartState(), GetTransitionEndState(), GetTransitionProgress()). These methods can be invoked from a slot method assigned to the property OnUpdate. In this manner you can automatically arrange and updated additional decoration according to the actual state of the widget.
For more details regarding the customization of the button see the description of WidgetSet::RadioButtonConfig class.
property WidgetSet::RadioButtonConfig Appearance = null;
The property 'Appearance' refers to a 'Radio Button Config' object containing bitmaps, colors, fonts and further configuration attributes to customize this radio button widget. By assigning a configuration object to the property 'Appearance', the radio button automatically assumes the look and feel as determined in the properties of the configuration object.
If there is no configuration object associated to the radio button (the property 'Appearance' is 'null') the radio button limits to display the bitmap specified in the property Icon.
Please note, configuration objects can be shared among multiple radio button widgets. When the properties of the configuration object change, all radio buttons (connected actually to it) are notified and updated to assume the new appearance.
method WidgetSet::CommonState GetCurrentState();
The method GetCurrentState() returns the state of the widget (OffDefault, OffDisabled, OffFocused, OffActive, OnDefault, OnDisabled, OnFocused or OnActive) according to the latest user interaction by additionally taking in account the widgets current Selected state (On or Off).
The obtained state information is useful to update decorations associated to the widget if those should depend on the widget's current state. For more details concerning the decorations, see the property OnUpdate.
Please note, if the widget is configured to perform animations during state transitions, you can use the methods GetTransitionStartState(), GetTransitionEndState() and GetTransitionProgress() to obtain information concerning the animation.
method WidgetSet::CommonState GetTransitionEndState();
The method GetTransitionEndState() returns the state of the widget (OffDefault, OffDisabled, OffFocused, OffActive, OnDefault, OnDisabled, OnFocused or OnActive) valid after the actual state transition will finish and by additionally taking in account the Selected state (On or Off) the widget will assume finally.
This information, together with the values returned by the methods GetTransitionStartState() and GetTransitionProgress(), can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.
If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionEndState() returns the widget's latest state equal to the value returned by the method GetCurrentState().
method float GetTransitionProgress();
The method GetTransitionProgress() returns a value in range 0.0..1.0 according to the progress of the actually performed state transition. The start and the end states for the transition can be queried by the methods GetTransitionStartState() and GetTransitionEndState(). The obtained information can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.
If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionProgress() returns the value 0.0.
method WidgetSet::CommonState GetTransitionStartState();
The method GetTransitionStartState() returns the state of the widget (OffDefault, OffDisabled, OffFocused, OffActive, OnDefault, OnDisabled, OnFocused or OnActive) valid just before the actual state transition begun by additionally taking in account the Selected state (On or Off) the widget had at this time.
This information, together with the values returned by the methods GetTransitionEndState() and GetTransitionProgress(), can be useful to calculate the state of decoration views which depend on the progress of the animation. For more details concerning the decorations, see the property OnUpdate.
If the widget is not configured to perform any state transitions with animations or there is no transition in progress, GetTransitionStartState() returns the widget's latest state equal to the value returned by the method GetCurrentState().
property Resources::Bitmap Icon = null;
The property 'Icon' refers to the bitmap object to display as icon in this radio button widget. If the bitmap consists of more than one frame, the desired frame number can be determined by using the property IconFrame or individually for every button state by using the properties IconOffFrame, IconOnFrame, IconOffFrameDefault, IconOffFrameFocused, IconOffFrameActive, IconOffFrameDisabled, IconOnFrameDefault, IconOnFrameFocused, IconOnFrameActive and IconOnFrameDisabled.
If the bitmap is animated and the property IconOffFrameDefault, IconOffFrameFocused, IconOffFrameActive, IconOffFrameDisabled, IconOnFrameDefault, IconOnFrameFocused, IconOnFrameActive or IconOnFrameDisabled is initialized with the value -1, the animation will start automatically as soon as the button enters the corresponding state.
Per default, the icon is displayed centered within the radio button area. You can modify the alignment of the icon, its margins, its opacity as well as its colors (if the specified bitmap is Alpha8) in the configuration object assigned to the property Appearance.
property int32 IconFrame = -1;
The property 'IconFrame' determines the frame number within the bitmap Icon to be displayed. Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
This property determines the icon frame number to be used regardless of the actual state of the button. By using the properties IconOffFrame, IconOffFrameActive, IconOffFrameDefault, IconOffFrameDisabled, IconOffFrameFocused, IconOnFrame, IconOnFrameActive, IconOnFrameDefault, IconOnFrameDisabled and IconOnFrameFocused you can specify different frame number for every button state.
property int32 IconOffFrame = -1;
The property 'IconOffFrame' determines the frame number within the bitmap Icon to be displayed when the button is actually switched-off (property Selected is 'false'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
This property determines the icon frame number to be used when the button is actually switched-off (property Selected is 'false') regardless of other button states. By using the properties IconOffFrameActive, IconOffFrameDefault, IconOffFrameDisabled, IconOffFrameFocused, IconOnFrame, IconOnFrameActive, IconOnFrameDefault, IconOnFrameDisabled and IconOnFrameFocused you can specify different frame number for every button state.
property int32 IconOffFrameActive = -1;
The property 'IconOffFrameActive' determines the frame number within the bitmap Icon to be displayed when the button is in the 'active' state (the user is actually touching the button or pressing a key on the keyboard the radio button should react on) and it is actually switched-off (property Selected is 'false'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started as soon as the button enters the 'active/switched-off' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 IconOffFrameDefault = -1;
The property 'IconOffFrameDefault' determines the frame number within the bitmap Icon to be displayed when the button is in the 'default' state and it is actually switched-off (property Selected is 'false'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started as soon as the button enters the 'default/switched-off' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 IconOffFrameDisabled = -1;
The property 'IconOffFrameDisabled' determines the frame number within the bitmap Icon to be displayed when the button is in the 'disabled' state (its property Enabled is 'false') and it is actually switched-off (property Selected is 'false'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started as soon as the button enters the 'disabled/switched-off' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 IconOffFrameFocused = -1;
The property 'IconOffFrameFocused' determines the frame number within the bitmap Icon to be displayed when the button is in the 'focused' state (the button can react to keyboard events) and it is actually switched-off (property Selected is 'false'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started as soon as the button enters the 'focused/switched-off' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 IconOnFrame = -1;
The property 'IconOnFrame' determines the frame number within the bitmap Icon to be displayed when the button is actually switched-on (property Selected is 'true'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
This property determines the icon frame number to be used when the button is actually switched-on (property Selected is 'true') regardless of other button states. By using the properties IconOffFrame, IconOffFrameActive, IconOffFrameDefault, IconOffFrameDisabled, IconOffFrameFocused, IconOnFrameActive, IconOnFrameDefault, IconOnFrameDisabled and IconOnFrameFocused you can specify different frame number for every button state.
property int32 IconOnFrameActive = -1;
The property 'IconOnFrameActive' determines the frame number within the bitmap Icon to be displayed when the button is in the 'active' state (the user is actually touching the button or pressing a key on the keyboard the radio button should react on) and it is actually switched-on (property Selected is 'true'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started as soon as the button enters the 'active/switched-on' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 IconOnFrameDefault = -1;
The property 'IconOnFrameDefault' determines the frame number within the bitmap Icon to be displayed when the button is in the 'default' state and it is actually switched-on (property Selected is 'true'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started as soon as the button enters the 'default/switched-on' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 IconOnFrameDisabled = -1;
The property 'IconOnFrameDisabled' determines the frame number within the bitmap Icon to be displayed when the button is in the 'disabled' state (its property Enabled is 'false') and it is actually switched-on (property Selected is 'true'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started as soon as the button enters the 'disabled/switched-on' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property int32 IconOnFrameFocused = -1;
The property 'IconOnFrameFocused' determines the frame number within the bitmap Icon to be displayed when the button is in the 'focused' state (the button can react to keyboard events) and it is actually switched-on (property Selected is 'true'). Thus this property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no icon is shown.
If the property is initialized with the value -1 and the Icon bitmap is animated, the animation is automatically started as soon as the button enters the 'focused/switched-on' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.
property string Label = "";
The property 'Label' specifies the text to display as label in this radio button widget. The desired font as well as the colors for all individual button states have to be specified in the configuration object assigned to the property Appearance. If there is no configuration object associated to this radio button widget (the property Appearance is 'null'), no label is displayed.
Per default, the label is displayed centered within the radio button area. You can modify the alignment of the label as well as its margins by specifying them in the configuration object.
This property determines the label to be used regardless of the actual state of the button. By using the properties LabelOff and LabelOn you can specify different labels for every button state.
property string LabelOff = "";
The property 'LabelOff' specifies the text to display as label in this radio button widget when it is in the switched-off state (property Selected is 'false'). The desired font as well as the colors for all individual button states have to be specified in the configuration object assigned to the property Appearance. If there is no configuration object associated to this radio button widget (the property Appearance is 'null'), no label is displayed.
Per default, the label is displayed centered within the radio button area. You can modify the alignment of the label as well as its margins by specifying them in the configuration object.
property string LabelOn = "";
The property 'LabelOn' specifies the text to display as label in this radio button widget when it is in the switched-on state (property Selected is 'true'). The desired font as well as the colors for all individual button states have to be specified in the configuration object assigned to the property Appearance. If there is no configuration object associated to this radio button widget (the property Appearance is 'null'), no label is displayed.
Per default, the label is displayed centered within the radio button area. You can modify the alignment of the label as well as its margins by specifying them in the configuration object.
property slot OnEnter = null;
The property 'OnEnter' can refer to a slot method, which will receive signals when while pressing the radio button the user drags the finger so it leaves and enters the button area. Accordingly, the button assumes the 'active' state again (it is 'armed' now). In the associated slot method the implementation can handle the event.
This event is also triggered, if the button is focused and the user presses the key on the keyboard to activate the button.
property slot OnLeave = null;
The property 'OnLeave' can refer to a slot method, which will receive signals when while pressing the radio button the user drags the finger so it leaves the button area. Accordingly, the button assumes the 'default' or 'focused' state again (it is not 'armed' anymore). In the associated slot method the implementation can handle the event.
This event is also triggered, if the button is focused and the user (after pressing a key on the keyboard to activate the button) releases this key again terminating so the interaction.
property slot OnPress = null;
The property 'OnPress' can refer to a slot method, which will receive a signal as soon as the user touches the radio button or, if the button is focused, presses the key on the keyboard to activate the radio button. Thereupon the method's logic will be executed.
In other words, this event is triggered at the beginning of the interaction between user and the button.
property slot OnRelease = null;
The property 'OnRelease' can refer to a slot method, which will receive a signal as soon as the user lifts the finger from the radio button or, if the button was activated by preceding keyboard event, the user releases the key again. Thereupon the method's logic will be executed.
In other words, this event is triggered at the end of the interaction between user and the button.
property slot OnSelect = null;
The property 'OnSelect' can refer to a slot method, which will receive a signal as soon as the user has activated the button causing the button to change its state from switched-off to switched-on. Thereupon the method's logic will be executed. In the associated slot method you can evaluate the property Selected as reflecting the current switched-off/on state of the button.
The button is activated when the user (after touching the button) releases the button again while the finger was still within the button area. If the radio button is controlled by keyboard events, the button is activated when the user (after pressing the corresponding key) releases it again.
Please note, once in the switched-on state, the user can't toggle the radio button in the switched-off state. To change the state, you have to set the property Selected to the value 'false'. Alternatively, you can group several radio buttons by connecting them to the same Outlet property. In this case the actually selected button is automatically switched-off when the user selects another one.
property slot OnUpdate = null;
The property 'OnUpdate' can refer to a slot method, which should be invoked by the widget when its state changes (or more generally, when the user interacts with the widget). This method is intended to update decorations associated to this radio button widget.
From the implementation of the slot method you can invoke the methods GetCurrentState(), GetTransitionStartState(), GetTransitionEndState() and GetTransitionProgress() to query the current state of the widget.
property ^int32 Outlet = null;
The property 'Outlet' can refer to any other 'int32' property the widget should remain synchronized with. When the user selects the radio button, 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 one, the radio button is automatically notified to remain in sync with the property. The button appears selected (switched-on), when the referred property has the value equal to OutletSelector.
This approach follows the Model-View-Controller (MVC) programming paradigm. Here the radio button represents the 'View' and 'Controller' and the property referred via 'Outlet' can be seen as a part of the 'Model'.
property int32 OutletSelector = 0;
The property 'OutletSelector' contains a value identifying the radio button within a group of radio buttons. At the runtime, the button compares this value with the value of the property referred by Outlet and if both are equal, the radio button assumes the 'selected' (switched-on) state (its property Selected is 'true'). If the values are different, the radio button appears not selected (switched-off). This selector is useful to build a group of radio buttons that refers to the same outlet. Different selectors for each radio button manages automatically the group of radio buttons.
property bool ResignAfterHorizontalWipe = false;
The property 'ResignAfterHorizontalWipe' determines whether while interacting with the radio button, the button may automatically resign and deflect the current processing of touch events (the current grab cycle) to another touch handler.
If this property is 'true' and the user performs a horizontal wipe gesture within the button area, the button searches for another touch handler (e.g. another widget) willing to take over the further event processing of the actual interaction. In other words, you use this property to specify that the radio button is NOT interested to process the horizontal wipe gestures and thus other handler should take over.
property bool ResignAfterVerticalWipe = false;
The property 'ResignAfterVerticalWipe' determines whether while interacting with the radio button, the button may automatically resign and deflect the current processing of touch events (the current grab cycle) to another touch handler.
If this property is 'true' and the user performs a vertical wipe gesture within the button area, the button searches for another touch handler (e.g. another widget) willing to take over the further event processing of the actual interaction. In other words, you use this property to specify that the radio button is NOT interested to process the vertical wipe gestures and thus other handler should take over.
property bool Selected = false;
The property 'Selected' stores the current state of the radio button. As long as the property is 'false', the widget is in switched-off (not selected) state. In turn, initializing the property with the value 'true' causes the button to change in the switched-on (selected) state.
