Buttons
PUBLISHED
A button is a small object on the UI that you press in order to operate it. DALi provides button controls, such as PushButton
, CheckBoxButton
, and RadioButton
.
In this tutorial, the following subjects are covered:
Overview
Dali::Toolkit::Button
is the base class for the button UI components.
Buttons can be disabled. Buttons can be made togglable, and then selected or unselected.
Button Events
The following table lists the basic signals provided by the Dali::Toolkit::Button
class.
Table: Dali::Toolkit::Button input signals
Input signal | Description |
---|---|
PressedSignal() |
Emitted when the button is touched. |
ReleasedSignal() |
Emitted when the button is touched, and the touch point leaves the boundary of the button. |
ClickedSignal() |
Emitted when the button is touched, and the touch point doesn't leave the boundary of the button. |
StateChangedSignal() |
Emitted when the button state is changed. |
Here is an example of adding an event handler to a push button Clicked event:
button.ClickedSignal().Connect( this, &ButtonClicked ); bool ChangeImageClicked( Button button ) { ... // button pressed return true; }
Events are not fired when the disabled property is set to true.
The Dali::Toolkit::Button
class provides the following properties which modify the fired events:
- When autorepeating is set to true, the Pressed, Released and Clicked events are fired at regular intervals while the button is touched.
The interval times can be modified with the InitialAutoRepeatingDelay and NextAutoRepeatingDelay properties.
A togglable button can't be autorepeating. If the autorepeating property is set to true, then the togglable property is set to false but no event is fired.
- When togglable is set to true, a StateChanged event is fired, with the selected state.
For a checkbox all 4 events are available, usually only the StateChanged event is used to notify when the button changes its state to selected or unselected.
For a radio button use the StateChanged event to check when the radio button is selected.
PushButton
The Dali::Toolkit::PushButton
class provides a button that can be pressed to operate it. A push button changes its appearance when is pressed and returns to its original appearance when is released.
Figure: PushButton
A push button emits a Button::PressedSignal()
signal when the button is pressed, a Button::ClickedSignal()
signal when clicked, and a Button::ReleasedSignal()
signal when released or the touch point leaves the boundary of the button.
The following code shows an example of a basic push button:
void HelloWorldExample::Create( Application& application ) { PushButton button = PushButton::New(); button.SetParentOrigin( ParentOrigin::CENTER ); button.SetProperty( Button::Property::LABEL, "Press"); Stage::GetCurrent().Add( button ); // Connect to button signals emitted by the button button.ClickedSignal().Connect( this, &HelloWorldExample::OnButtonClicked ); button.PressedSignal().Connect( this, &HelloWorldExample::OnButtonPressed ); button.ReleasedSignal().Connect( this, &HelloWorldExample::OnButtonReleased ); } bool HelloWorldExample::OnButtonClicked( Button button ) { // Do something when the button is clicked return true; } bool HelloWorldExample::OnButtonPressed( Button button ) { // Do something when the button is pressed return true; } bool HelloWorldExample::OnButtonReleased( Button button ) { // Do something when the button is released return true; }
CheckBoxButton
The Dali::Toolkit::CheckBoxButton
class provides a check box button, which can be checked or unchecked.
Figure: CheckBoxButton
A checkbox button emits all 4 button input signals, but often you can simply use the Button::StateChangedSignal()
signal to be notified when the button changes its state to selected or unselected.
The following code shows an example of a basic checkbox button:
void HelloWorldExample::Create( Application& application ) { CheckBoxButton button = CheckBoxButton::New(); button.SetParentOrigin( ParentOrigin::CENTER ); button.SetProperty( Button::Property::LABEL, "Check" ); button.SetSize( 200, 40 ); button.SetProperty( Control::Property::BACKGROUND, Color::WHITE ); Stage::GetCurrent().Add( button ); // Connect to a button signal emitted by the button button.StateChangedSignal().Connect( this, &HelloWorldExample::OnButtonStateChanged ); } bool HelloWorldExample::OnButtonStateChanged( Button button ) { // Do something when the button state is changed // You can get the state using the property Button::Property::SELECTED return true; }
RadioButton
The Dali::Toolkit::RadioButton
class provides a radio button with 2 states: selected and unselected.
Figure: RadioButton
Usually, radio buttons are grouped. When they have the same parent, 2 or more radio buttons are located in the same group. In each group, only 1 radio button can be selected at a given time. You can use the Button::StateChangedSignal()
signal to check which radio button is selected.
The following code shows an example of a basic radio button:
void HelloWorldExample::Create( Application& application ) { Actor radioGroup = Actor::New(); radioGroup.SetParentOrigin( ParentOrigin::CENTER ); Stage::GetCurrent().Add( radioGroup ); RadioButton button1 = RadioButton::New(); button1.SetProperty( Button::Property::LABEL, "button1" ); button1.SetBackgroundColor( Color::WHITE ); button1.SetPosition( 0, -40 ); radioGroup.Add( button1 ); RadioButton button2 = RadioButton::New(); button2.SetProperty( Button::Property::LABEL, "button2" ); button2.SetBackgroundColor( Color::WHITE ); button2.SetPosition( 0, 40 ); radioGroup.Add( button2 ); // Connect a single callback to button signals emitted by both button1 and button2 button1.StateChangedSignal().Connect( this, &HelloWorldExample::OnButtonStateChanged ); button2.StateChangedSignal().Connect( this, &HelloWorldExample::OnButtonStateChanged ); } bool HelloWorldExample::OnButtonStateChanged( Toolkit::Button button ) { // Do something when the 2 buttons' states are changed // button parameter can be both button1 and button2 // You can use properties Button::Property::LABEL and Button::Property::SELECTED // to know which button is selected return true; }
Button creation with Visuals
Using Visuals
Buttons can contain various Visuals, not just ImageVisual.
Below is an example using ImageVisual, TextVisual and ColorVisual
Setting ImageVisual to a Button using a Property Map
Right button (Red) is when the button is selected.
Selected and unselected images are provided to the button as two property maps containing the required URL.
... PushButton button = PushButton::New(); button.SetProperty( Button::Property::SELECTED_VISUAL, Property::Map().Add( Visual::Property::TYPE, Visual::IMAGE ) .Add( ImageVisual::Property::URL, DEMO_IMAGE_DIR "red-button.png" ) ); button.SetProperty( Button::Property::UNSELECTED_VISUAL, Property::Map().Add( Visual::Property::TYPE, Visual::IMAGE ) .Add( ImageVisual::Property::URL, DEMO_IMAGE_DIR "green-button.png" ) ); button.SetParentOrigin( ParentOrigin::CENTER ); mView.Add( button ); // Adding button to stage via mView which is a staged control.
Setting Text to a PushButton using a Property Map (Full Control)
Toolkit::PushButton button = Toolkit::PushButton::New(); Property::Map textSettingsMap; textSettingsMap.Add( Visual::Property::TYPE, Toolkit::Visual::TEXT ) .Add( TextVisual::Property::TEXT, "Press Me" ) .Add( TextVisual::Property::MULTI_LINE, true ) .Add( TextVisual::Property::POINT_SIZE, 12.0f ); button.SetProperty( Toolkit::Button::Property::LABEL, textSettingsMap );
Setting a ColorVisual to a PushButton using a Property Map
Toolkit::PushButton button = Toolkit::PushButton::New(); Property::Map visualSettingMap; visualSettingMap.Add( Visual::Property::TYPE, Toolkit::Visual::COLOR ) .Add( ColorVisual::Property::MIX_COLOR, Vector4( R, G, B, 1.0f ) ); button.SetProperty( DevelButton::Property::UNSELECTED_BACKGROUND_VISUAL, visualSettingMap ); OR button.SetProperty( Toolkit::Button::Property::UNSELECTED_VISUAL, visualSettingMap );
Setting a ColorVisual for the background and a TextVisual for the Label.
Using the above ColorVisual and TextVisual to have a color background with text in the foreground.
Toolkit::PushButton button = Toolkit::PushButton::New(); Property::Map visualSettingMap; visualSettingMap.Add( Visual::Property::TYPE, Toolkit::Visual::COLOR ) .Add( ColorVisual::Property::MIX_COLOR, Vector4( R, G, B, 1.0f ) ); button.SetProperty( Toolkit::Button::Property::UNSELECTED_VISUAL, visualSettingMap ); Property::Map textSettingsMap; textSettingsMap.Add( Visual::Property::TYPE, Toolkit::Visual::TEXT ) .Add( TextVisual::Property::TEXT, "Press Me" ) .Add( TextVisual::Property::MULTI_LINE, true ) .Add( TextVisual::Property::POINT_SIZE, 12.0f ); button.SetProperty( Toolkit::Button::Property::LABEL, textSettingsMap );
Setting Text to a Button using a string (Basic)
Toolkit::PushButton button = Toolkit::PushButton::New(); button.SetProperty( Toolkit::Button::Property::LABEL, "Select" );
Check box button set up
Two checkboxes with default selected and unselected images.
Toolkit::CheckBoxButton checkboxButton1 = Toolkit::CheckBoxButton::New(); checkboxButton1.SetProperty( Toolkit::Button::Property::LABEL, "CheckBox is selectable" ); checkboxButton1.StateChangedSignal().Connect( this, &ButtonCode::CheckBoxSelected ); checkboxButton1.SetParentOrigin( ParentOrigin::CENTER ); checkboxButton1.SetAnchorPoint( AnchorPoint::BOTTOM_CENTER ); checkboxButton1.SetName("one"); Toolkit::CheckBoxButton checkboxButton2 = Toolkit::CheckBoxButton::New(); checkboxButton2.SetProperty( Toolkit::Button::Property::LABEL, "CheckBox is selectable" ); checkboxButton2.StateChangedSignal().Connect( this, &ButtonCode::CheckBoxSelected ); checkboxButton2.SetParentOrigin( ParentOrigin::CENTER ); checkboxButton2.SetAnchorPoint( AnchorPoint::TOP_CENTER ); checkboxButton2.SetName("two"); mView.Add( checkboxButton1 ); mView.Add( checkboxButton2 );
Radio buttons set up in a Group
Radio buttons parented to the same control only allow one to be selected at any time.
Control mView = Control::New(); Toolkit::RadioButton radioButton1 = Toolkit::RadioButton::New(); radioButton1.SetProperty( Toolkit::Button::Property::LABEL, "High" ); radioButton1.SetParentOrigin( ParentOrigin::CENTER ); radioButton1.SetAnchorPoint( AnchorPoint::BOTTOM_CENTER ); radioButton1.SetName("one"); Toolkit::RadioButton radioButton2 = Toolkit::RadioButton::New(); radioButton2.SetProperty( Toolkit::Button::Property::LABEL, "Low" ); radioButton2.SetParentOrigin( ParentOrigin::CENTER ); radioButton2.SetAnchorPoint( AnchorPoint::TOP_CENTER ); radioButton2.SetName("two"); mView.Add( radioButton1 ); mView.Add( radioButton2 );