Reference for the Mosaic class WidgetSet::PushButtonConfig

WidgetSet::PushButtonConfig
FaceActive
FaceDefault
FaceDisabled
FaceFocused
FaceFrameActive
FaceFrameDefault
FaceFrameDisabled
FaceFrameFocused
FaceLayout
FaceTintActive
FaceTintDefault
FaceTintDisabled
FaceTintFocused
IconAlignment
IconMarginBottom
IconMarginLeft
IconMarginRight
IconMarginTop
IconTintActive
IconTintDefault
IconTintDisabled
IconTintFocused
KeyCode
LabelAlignment
LabelColorActive
LabelColorDefault
LabelColorDisabled
LabelColorFocused
LabelFont
LabelMarginBottom
LabelMarginLeft
LabelMarginRight
LabelMarginTop
PressedFeedbackDuration
WidgetMaxSize
WidgetMinSize
WidgetSet::WidgetConfig

SEE ALSO

Using and customizing the Push Button widget.

This class implements the functionality permitting you to simply customize the look and feel of a monostable 'push button' widget (WidgetSet::PushButton). In the practice, you will create an instance of this class, configure its properties with bitmaps, colors and other relevant attributes according to your design expectations and assign such prepared configuration object to the property 'Appearance' of every affected push button widget. Thereupon the widgets will use the configuration information provided in the object.

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). With the configuration object you can specify the appearance of the button for every state individually. For this purpose you should know from which views the button is composed of:

If the button is actually focused, it can also be activated by pressing the keyboard key specified in the property KeyCode. To prevent the button from being able to be focused, initialize this property with the value Core::KeyCode.NoKey. The property PressedFeedbackDuration configures the duration how long the button should appear active (pressed) even if it has been taped for a very short time.

With the properties WidgetMinSize and WidgetMaxSize you can configure size constraints for the widget itself. You can, for example, limit the button to not shrink below a specified width or height.

property Resources::Bitmap FaceActive = null;

The property 'FaceActive' determines the bitmap to fill the background of the push button 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).

If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property FaceFrameActive. If the selected bitmap is intended to be animated, ensure that the property FaceFrameActive is -1.

If the specified bitmap contains opacity information only (Alpha8 bitmap), you can tint the bitmap by specifying the desired color in the property FaceTintActive. With the property FaceTintActive you can also modulate the opacity of a regular bitmap.

Per default, the actually visible face bitmap fills the entire background area of the button. With the property FaceLayout you can modify this behavior and configure the bitmap to retain its original width and/or height. You can also determine how the bitmap should be aligned vertically and horizontally within the button area.

property Resources::Bitmap FaceDefault = null;

The property 'FaceDefault' determines the bitmap to fill the background of the push button when the button is in the 'default' state.

If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property FaceFrameDefault. If the selected bitmap is intended to be animated, ensure that the property FaceFrameDefault is -1.

If the specified bitmap contains opacity information only (Alpha8 bitmap), you can tint the bitmap by specifying the desired color in the property FaceTintDefault. With the property FaceTintDefault you can also modulate the opacity of a regular bitmap.

Per default, the actually visible face bitmap fills the entire background area of the button. With the property FaceLayout you can modify this behavior and configure the bitmap to retain its original width and/or height. You can also determine how the bitmap should be aligned vertically and horizontally within the button area.

property Resources::Bitmap FaceDisabled = null;

The property 'FaceDisabled' determines the bitmap to fill the background of the push button when the button is in the 'disabled' state (property 'Enabled' of the button is 'false').

If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property FaceFrameDisabled. If the selected bitmap is intended to be animated, ensure that the property FaceFrameDisabled is -1.

If the specified bitmap contains opacity information only (Alpha8 bitmap), you can tint the bitmap by specifying the desired color in the property FaceTintDisabled. With the property FaceTintDisabled you can also modulate the opacity of a regular bitmap.

Per default, the actually visible face bitmap fills the entire background area of the button. With the property FaceLayout you can modify this behavior and configure the bitmap to retain its original width and/or height. You can also determine how the bitmap should be aligned vertically and horizontally within the button area.

property Resources::Bitmap FaceFocused = null;

The property 'FaceFocused' determines the bitmap to fill the background of the push button when the button is in the 'focused' state (the button can react to keyboard events).

If the specified bitmap contains more than one frame (multi-frame bitmap), the desired frame number can be selected in the property FaceFrameFocused. If the selected bitmap is intended to be animated, ensure that the property FaceFrameFocused is -1.

If the specified bitmap contains opacity information only (Alpha8 bitmap), you can tint the bitmap by specifying the desired color in the property FaceTintFocused. With the property FaceTintFocused you can also modulate the opacity of a regular bitmap.

Per default, the actually visible face bitmap fills the entire background area of the button. With the property FaceLayout you can modify this behavior and configure the bitmap to retain its original width and/or height. You can also determine how the bitmap should be aligned vertically and horizontally within the button area.

property int32 FaceFrameActive = -1;

The property 'FaceFrameActive' determines the frame number within the bitmap FaceActive. This property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no bitmap is shown.

If the property is initialized with the value -1 and the FaceActive 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 FaceFrameDefault = -1;

The property 'FaceFrameDefault' determines the frame number within the bitmap FaceDefault. This property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no bitmap is shown.

If the property is initialized with the value -1 and the FaceDefault 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 FaceFrameDisabled = -1;

The property 'FaceFrameDisabled' determines the frame number within the bitmap FaceDisabled. This property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no bitmap is shown.

If the property is initialized with the value -1 and the FaceDisabled 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 FaceFrameFocused = -1;

The property 'FaceFrameFocused' determines the frame number within the bitmap FaceFocused. This property is applicable for multi-frame bitmaps only (see also Resources::Bitmap). If the desired frame is not available in the bitmap, no bitmap is shown.

If the property is initialized with the value -1 and the FaceFocused 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 Core::Layout FaceLayout = Core::Layout[AlignToBottom, AlignToLeft, AlignToRight, AlignToTop, ResizeHorz, ResizeVert];

The property 'FaceLayout' determines the constraints how the actually displayed face bitmap (FaceActive, FaceDefault, FaceDisabled or FaceFocused) should be aligned within the button area. Per default the bitmap fills the button widget entirely.

The constraints 'ResizeVert' and 'ResizeHorz' determine whether the bitmap should be resized to fill the button vertically and/or horizontally. Deactivating the constraint causes the button to display the bitmap with its original height and/or width. In such case you can configure with the constraints 'AlignToTop', 'AlignToBottom', 'AlignToLeft' and 'AlignToRight' how the bitmap should be aligned within the button area.

property color FaceTintActive = #FFFFFFFF;

The property 'FaceTintActive' determines the color value to tint or modulate the bitmap specified in the property FaceActive. The effect of this color value depends on the type of the bitmap:

property color FaceTintDefault = #FFFFFFFF;

The property 'FaceTintDefault' determines the color value to tint or modulate the bitmap specified in the property FaceDefault. The effect of this color value depends on the type of the bitmap:

property color FaceTintDisabled = #FFFFFFFF;

The property 'FaceTintDisabled' determines the color value to tint or modulate the bitmap specified in the property FaceDisabled. The effect of this color value depends on the type of the bitmap:

property color FaceTintFocused = #FFFFFFFF;

The property 'FaceTintFocused' determines the color value to tint or modulate the bitmap specified in the property FaceFocused. The effect of this color value depends on the type of the bitmap:

property Views::ImageAlignment IconAlignment = Views::ImageAlignment[AlignHorzCenter, AlignVertCenter];

The property 'IconAlignment' determines how the bitmap specified in the property 'Icon' of the button widget should be aligned.

Per default, the icon is aligned within the entire button area. By using the properties IconMarginLeft, IconMarginRight, IconMarginTop and IconMarginBottom you can limit the area as desired.

property int32 IconMarginBottom = 0;

The property 'IconMarginBottom' determines the gap below the area destined to display the icon bitmap relative to the bottom edge of the button itself.

property int32 IconMarginLeft = 0;

The property 'IconMarginLeft' determines the gap on the left of the area destined to display the icon bitmap relative to the left edge of the button itself.

property int32 IconMarginRight = 0;

The property 'IconMarginRight' determines the gap on the right of the area destined to display the icon bitmap relative to the right edge of the button itself.

property int32 IconMarginTop = 0;

The property 'IconMarginTop' determines the gap above the area destined to display the icon bitmap relative to the top edge of the button itself.

property color IconTintActive = #FFFFFFFF;

The property 'IconTintActive' determines the color value to tint or modulate the bitmap specified in the property 'Icon' of the button widget if 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). The effect of this color value depends on the type of the bitmap:

property color IconTintDefault = #FFFFFFFF;

The property 'IconTintDefault' determines the color value to tint or modulate the bitmap specified in the property 'Icon' of the button widget if the button is in the 'default' state. The effect of this color value depends on the type of the bitmap:

property color IconTintDisabled = #FFFFFFFF;

The property 'IconTintDisabled' determines the color value to tint or modulate the bitmap specified in the property 'Icon' of the button widget if the button is in the 'disabled' state (property 'Enabled' of the button is 'false'). The effect of this color value depends on the type of the bitmap:

property color IconTintFocused = #FFFFFFFF;

The property 'IconTintFocused' determines the color value to tint or modulate the bitmap specified in the property 'Icon' of the button widget if the button is in the 'focused' state (the button can react to keyboard events). The effect of this color value depends on the type of the bitmap:

property Core::KeyCode KeyCode = Core::KeyCode.Enter;

The property 'KeyCode' determines the key, the button should react on when it is focused. In this manner the user can control the widget by using keyboard or hardware buttons.

If this property is initialized with the value Core::KeyCode.NoKey, the button will not be able to become focused and it will not receive any keyboard events.

property Views::TextAlignment LabelAlignment = Views::TextAlignment[AlignHorzCenter, AlignVertCenter];

The property 'LabelAlignment' determines how the text specified in the property 'Label' of the button widget should be aligned.

Per default, the label is aligned within the entire button area. By using the properties LabelMarginLeft, LabelMarginRight, LabelMarginTop and LabelMarginBottom you can limit the area as desired.

property color LabelColorActive = #000000FF;

The property 'LabelColorActive' determines the color value to use when the text specified in the property 'Label' of the button widget is displayed and 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).

property color LabelColorDefault = #000000FF;

The property 'LabelColorDefault' determines the color value to use when the text specified in the property 'Label' of the button widget is displayed and the button is in the 'default' state.

property color LabelColorDisabled = #000000FF;

The property 'LabelColorDisabled' determines the color value to use when the text specified in the property 'Label' of the button widget is displayed and the button is in the 'disabled' state (property 'Enabled' of the button is 'false').

property color LabelColorFocused = #000000FF;

The property 'LabelColorFocused' determines the color value to use when the text specified in the property 'Label' of the button widget is displayed and the button is in the 'focused' state (the button can react to keyboard events).

property Resources::Font LabelFont = null;

The property 'LabelFont' determines the font object used to print the text specified in the property 'Label' of the button widget. If no font is specified (the property is 'null'), no text is displayed.

property int32 LabelMarginBottom = 0;

The property 'LabelMarginBottom' determines the gap below the area destined to display the label text relative to the bottom edge of the button itself.

property int32 LabelMarginLeft = 0;

The property 'LabelMarginLeft' determines the gap on the left of the area destined to display the label text relative to the left edge of the button itself.

property int32 LabelMarginRight = 0;

The property 'LabelMarginRight' determines the gap on the right of the area destined to display the label text relative to the right edge of the button itself.

property int32 LabelMarginTop = 0;

The property 'LabelMarginTop' determines the gap above the area destined to display the label text relative to the top edge of the button itself.

property int32 PressedFeedbackDuration = 50;

The property 'PressedFeedbackDuration' determines the minimum time in milliseconds how long the push button should appear pressed after the user has tapped it. This ensures, that the user can notice, that the button has been activated even if the user has touched it for a very short period.

property point WidgetMaxSize = <0,0>;

The property 'WidgetMaxSize' determines the maximum allowed size of the widget. Accordingly, the button can't become bigger than the value specified in this property. By using this property you can configure the size constraints for the button.

property point WidgetMinSize = <0,0>;

The property 'WidgetMinSize' determines the minimal allowed size of the widget. Accordingly, the button can't become smaller than the value specified in this property. By using this property you can configure the size constraints for the button.