Reference for the Mosaic class WidgetSet::PushButton

WidgetSet::PushButton
Appearance
Icon
IconFrame
IconFrameActive
IconFrameDefault
IconFrameDisabled
IconFrameFocused
Label
OnActivate
OnEnter
OnLeave
OnPress
OnRelease
ResignAfterHorizontalWipe
ResignAfterVerticalWipe
Core::Group
AlphaBlended
Buffered
Embedded
Enabled
Focus
Opacity
Visible
Add()
AddBehind()
BroadcastEvent()
BroadcastEventAtPosition()
CountDialogs()
CountViews()
DismissDialog()
DispatchEvent()
FadeGroup()
FindActiveDialogByClass()
FindCurrentDialog()
FindDialogByClass()
FindNextView()
FindPrevView()
FindSiblingView()
FindViewAtPosition()
FindViewInDirection()
FindViewWithinArea()
GetContentArea()
GetDialogAtIndex()
GetIndexOfDialog()
GetIndexOfView()
GetViewAtIndex()
GlobalPosition()
HasViewState()
Init()
InvalidateArea()
InvalidateViewState()
IsActiveDialog()
IsCurrentDialog()
IsDialog()
LocalPosition()
ObtainFocus()
PresentDialog()
Remove()
Restack()
RestackBack()
RestackBehind()
RestackTop()
SwitchToDialog()
UpdateLayout()
UpdateViewState()
Core::RectView
Bounds
Core::View
Layout
Owner
StackingPriority
ArrangeView()
ChangeViewState()
CursorHitTest()
Draw()
GetExtent()
GetRoot()
HandleEvent()
MoveView()

SEE ALSO

Using and customizing the Push Button widget.

This class implements the monostable 'push button' widget. When the user taps on the button, the button sends a signal to the slot method stored in its OnActivate property. 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.

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 push button is determined by the 'Push 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 push button. Usually, you will manage in your project your own configuration objects and customize the push buttons according to your design expectations. Depending on the information provided in the associated configuration object, the push button will be composed of following views:

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.

For more details regarding the customization of the button see the description of WidgetSet::PushButtonConfig class.

property WidgetSet::PushButtonConfig Appearance = null;

The property 'Appearance' refers to a 'Push Button Config' object containing bitmaps, colors, fonts and further configuration attributes to customize this push button widget. By assigning a configuration object to the property 'Appearance', the push 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 push button (the property 'Appearance' is 'null') the push button limits to display the bitmap specified in the property Icon.

Please note, configuration objects can be shared among multiple push button widgets. When the properties of the configuration object change, all push buttons (connected actually to it) are notified and updated to assume the new appearance.

property Resources::Bitmap Icon = null;

The property 'Icon' refers to the bitmap object to display as icon in this push button widget. If the bitmap consists of more than one frame, the desired frame number can be determined by using the the property IconFrame or individually for every button state by using the properties IconFrameDefault, IconFrameFocused, IconFrameActive and IconFrameDisabled.

If the bitmap is animated and the property IconFrameDefault, IconFrameFocused, IconFrameActive or IconFrameDisabled 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 push 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) by specifying them 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 IconFrameActive, IconFrameDefault, IconFrameDisabled and IconFrameFocused you can specify different frame number for every button state.

property int32 IconFrameActive = -1;

The property 'IconFrameActive' 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 push button should react on). 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' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.

property int32 IconFrameDefault = -1;

The property 'IconFrameDefault' determines the frame number within the bitmap Icon to be displayed when the button is in the 'default' state. 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' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.

property int32 IconFrameDisabled = -1;

The property 'IconFrameDisabled' determines the frame number within the bitmap Icon to be displayed when the button is in the 'disabled' state (its property Enabled 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' state. If the bitmap is not animated and the property is -1, the frame with number 0 is displayed.

property int32 IconFrameFocused = -1;

The property 'IconFrameFocused' 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). 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' 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 push 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 push button widget (the property Appearance is 'null'), no label is displayed.

Per default, the label is displayed centered within the push button area. You can modify the alignment of the label as well as its margins by specifying them in the configuration object.

property slot OnActivate = null;

The property 'OnActivate' can refer to a slot method, which will receive a signal as soon as the user has activated the button. Thereupon the method's logic will be executed.

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 push button is controlled by keyboard events, the button is activated when the user (after pressing the corresponding key) releases it again.

property slot OnEnter = null;

The property 'OnEnter' can refer to a slot method, which will receive signals when while pressing the push 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 push 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 push button or, if the button is focused, presses the key on the keyboard to activate the push 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 push 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 bool ResignAfterHorizontalWipe = false;

The property 'ResignAfterHorizontalWipe' determines whether while interacting with the push 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 push 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 push 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 push button is NOT interested to process the vertical wipe gestures and thus other handler should take over.