1 #ifndef DALI_TOOLKIT_INTERNAL_BUTTON_H
2 #define DALI_TOOLKIT_INTERNAL_BUTTON_H
5 * Copyright (c) 2020 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #include <dali/public-api/adaptor-framework/timer.h>
23 #include <dali/public-api/animation/animation.h>
26 #include <dali-toolkit/devel-api/visual-factory/visual-base.h>
27 #include <dali-toolkit/devel-api/controls/buttons/button-devel.h>
28 #include <dali-toolkit/public-api/controls/control-impl.h>
29 #include <dali-toolkit/internal/controls/control/control-data-impl.h>
43 * @copydoc Toolkit::Button
45 * Button is the base class implementation for all buttons.
49 * All Foreground/Icon visuals expected to be the same size.
50 * Background visuals will take the size of the control.
51 * Padding and struts take size precedence over visuals when available space is limited.
52 * Icon/Foreground visuals take size precedence over Labels when available space is limited.
54 class Button : public Control
60 * Enum describing the position the text label can be in relation to the control (and foreground/icon)
64 BEGIN, // At the start of the control before the foreground/icon
65 END, // At the end of the control after the foreground/icon
66 TOP, // At the top of the control above the foreground/icon
67 BOTTOM // At the bottom of the control below the foreground/icon
73 * @brief Sets the button as \e disabled.
74 * @param[in] disabled Disabled property
76 void SetDisabled( bool disabled );
79 * @brief Returns if the button is disabled.
80 * @return \e true if the button is \e disabled
82 bool IsDisabled() const;
85 * @brief Sets the \e autorepeating property.
86 * @param[in] autoRepeating \e autorepeating property
88 void SetAutoRepeating( bool autoRepeating );
91 * @brief Sets the initial autorepeating delay.
92 * @param[in] initialAutoRepeatingDelay in seconds
94 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
97 * @brief Sets the next autorepeating delay.
98 * @param[in] nextAutoRepeatingDelay in seconds
100 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
103 * @brief Sets the \e togglable property.
104 * @param[in] togglable Togglable property
106 void SetTogglableButton( bool togglable );
109 * @brief Sets the button as selected or unselected.
110 * @param[in] selected Selected property
112 void SetSelected( bool selected );
115 * @brief Returns if the selected property is set and the button is togglable.
116 * @return \e true if the button is \e selected
118 bool IsSelected() const;
121 * @brief Produces a Property::Map of Text properties to create a Text Visual, merging existing properties with supplied map
122 * If the label does not exist yet, it is created.
123 * The derived buttons are notified if any properties are changed.
124 * @param[in] properties A Property::Map of key-value pairs of properties to set.
125 * @param[out] properties A Property::Map of text visual properties to set after merging inMap with existing maps
127 void MergeWithExistingLabelProperties( const Property::Map& inMap, Property::Map& outMap );
130 * Performs actions as requested using the action name.
131 * @param[in] object The object on which to perform the action.
132 * @param[in] actionName The action to perform.
133 * @param[in] attributes The attributes with which to perfrom this action.
134 * @return true if action has been accepted by this control
136 static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
145 UNSELECTED_STATE, ///< The button is unselected.
146 SELECTED_STATE, ///< The button is selected.
147 DISABLED_UNSELECTED_STATE, ///< The button is disabled and unselected.
148 DISABLED_SELECTED_STATE, ///< The button is disabled and selected.
149 STATE_COUNT, ///< Number of States
153 * Enum to distinguish the different style-able components of the button
157 UNSELECTED_FOREGROUND = 0,
159 DISABLED_SELECTED_FOREGROUND,
160 DISABLED_UNSELECTED_FOREGROUND,
161 UNSELECTED_BACKGROUND,
163 DISABLED_UNSELECTED_BACKGROUND,
164 DISABLED_SELECTED_BACKGROUND,
169 * Enum to list types of visual a state can have.
181 * Button press state which is not the same as the actual button's state.
182 * For example An UNSELECTED button can be DEPRESSED, but until released, the actual button state doesn't change to SELECTED
186 DEPRESSED, ///< The button is up.
187 UNPRESSED, ///< The button is down.
188 TOGGLE_DEPRESSED, ///< The button has been pressed down and will stay depressed when released.
192 * Construct a new Button.
197 * A reference counted object may only be deleted by calling Unreference()
201 * @return A reference to the label actor.
203 Actor& GetLabelActor();
206 * @return A reference to the unselected button image.
208 Actor GetUnselectedImage();
211 * @return A reference to the selected image.
213 Actor GetSelectedImage();
218 * Perform the click action to click the button.
219 * @param[in] attributes The attributes to perfrom this action.
220 * @return true if this control can perform action.
222 bool DoClickAction( const Property::Map& attributes );
225 * This method is called when the button is a Toggle button and released
226 * Could be reimplemented in subclasses to provide specific behaviour.
227 * @return bool returns true if state changed.
229 virtual bool OnToggleReleased();
232 * This method is called when touch leaves the boundary of the button or several touch points are received.
233 * Could be reimplemented in subclasses to provide specific behaviour.
235 virtual void OnTouchPointLeave();
238 * This method is called when the touch is interrupted.
239 * Could be reimplemented in subclasses to provide specific behaviour.
241 virtual void OnTouchPointInterrupted();
244 * This method is called when the \e selected property is changed.
246 virtual void OnStateChange( State newState ){}
249 * This method is called when the \e disabled property is changed.
251 virtual void OnDisabled() {}
254 * This method is called when the button is pressed.
256 virtual void OnPressed() {}
259 * This method is called when the button is released.
261 virtual void OnReleased() {}
266 * @copydoc Dali::Toolkit::PushButton::PressedSignal()
268 Toolkit::Button::ButtonSignalType& PressedSignal();
271 * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
273 Toolkit::Button::ButtonSignalType& ReleasedSignal();
276 * @copydoc Dali::Toolkit::Button::ClickedSignal()
278 Toolkit::Button::ButtonSignalType& ClickedSignal();
281 * @copydoc Dali::Toolkit::Button::StateChangedSignal()
283 Toolkit::Button::ButtonSignalType& StateChangedSignal();
286 * Connects a callback function with the object's signals.
287 * @param[in] object The object providing the signal.
288 * @param[in] tracker Used to disconnect the signal.
289 * @param[in] signalName The signal to connect to.
290 * @param[in] functor A newly allocated FunctorDelegate.
291 * @return True if the signal was connected.
292 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
294 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
299 * Called when a property of an object of this type is set.
300 * @param[in] object The object whose property is set.
301 * @param[in] index The property index.
302 * @param[in] value The new property value.
304 static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
307 * Called to retrieve a property of an object of this type.
308 * @param[in] object The object whose property is to be retrieved.
309 * @param[in] index The property index.
310 * @return The current value of the property.
312 static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
314 protected: // From Control
317 * @copydoc Toolkit::Control::OnInitialize()
318 * @note If overridden by deriving button classes, then an up-call to Button::OnInitialize MUST be made at the start.
320 void OnInitialize() override;
323 * @copydoc Toolkit::Control::OnAccessibilityActivated()
325 bool OnAccessibilityActivated() override;
328 * @copydoc Toolkit::Control::OnKeyboardEnter()
330 bool OnKeyboardEnter() override;
333 * @copydoc Toolkit::Control::OnSceneDisconnection()
334 * @note If overridden by deriving button classes, then an up-call to Button::OnSceneDisconnection MUST be made at the end.
336 void OnSceneDisconnection() override;
339 * @copydoc Toolkit::Control::OnSceneConnection()
341 void OnSceneConnection( int depth ) override;
344 * @copydoc Toolkit::Control::GetNaturalSize
346 Vector3 GetNaturalSize() override;
349 * @copydoc Toolkit::Control::OnSetResizePolicy
351 void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension ) override;
354 * @copydoc Toolkit::Control::OnRelayout
356 void OnRelayout( const Vector2& size, RelayoutContainer& container ) override;
361 * @brief Handler for touch data
362 * @param[in] actor The touched actor.
363 * @param[in] touch The touch info.
364 * @return true, if consumed, false otherwise.
366 bool OnTouch( Actor actor, const TouchEvent& touch );
369 * Handler for tap events.
370 * We do not actually do anything when we receive a tap as the button handles tap event through
371 * the touch event system itself as it requires more than just tap handling (e.g. leave events).
372 * This stops any of our parents receiving a tap gesture when it occurs within our area.
373 * @param[in] actor The tapped actor.
374 * @param[in] tap The tap gesture.
376 void OnTap(Actor actor, const TapGesture& tap);
379 * Sets up the autorepeating timer.
380 * @param[in] delay The delay time in seconds.
382 void SetUpTimer( float delay );
385 * Button has been pressed
390 * This method is called the button is down.
395 * This method is called when the button is up.
400 * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
402 bool AutoRepeatingSlot();
405 * Check the requested state is an allowed transition.
406 * Some states can not be transitioned to from certain states.
407 * @param[in] requestedState check if can transition to this state
408 * @return bool true if state change valid
410 bool ValidateState( State requestedState );
413 * Changes the button state when an action occurs on it
414 * @param[in] requestedState the state to change to
416 void ChangeState( State requestedState );
419 * This method is called when the button is released.
426 * Set Text Label Padding
427 * @param[in] padding BEGIN END BOTTOM TOP
429 void SetLabelPadding( const Padding& padding );
432 * Get Text Label padding
435 Padding GetLabelPadding();
438 * Set Foreground/icon Padding
439 * @param[in] padding BEGIN END BOTTOM TOP
441 void SetForegroundPadding( const Padding& padding);
444 * Get Foreground padding
447 Padding GetForegroundPadding();
450 * @brief Setup the button components for example foregrounds and background
451 * @param[in] index the index of the visual to set
452 * @param[in] value the value to set on the component
453 * @param[in] visualDepth the depth of the visual if overlapping another
455 void CreateVisualsForComponent( Property::Index index, const Property::Value& value, const int visualDepth );
458 * @brief Get the Property map for the given Visual
459 * @param[in] visualIndex visual index of the required visual
460 * @param[out] retreivedMap the property map used to construct the required visual
461 * @return bool success flag, true if visual found
463 bool GetPropertyMapForVisual( Property::Index visualIndex, Property::Map& retreivedMap ) const;
465 * Returns the animation to be used for transition, creating the animation if needed.
466 * @return The initialised transition animation.
468 Dali::Animation GetTransitionAnimation();
471 * @brief Set the position of the label relative to foreground/icon, if both present
472 * @param[in] labelAlignment given alignment setting
474 void SetLabelAlignment( Align labelAlignment);
477 * @brief Get set alignment of label in relation to foreground/icon
478 * @return Set alignment value
480 Align GetLabelAlignment();
483 * Removes the visual from the button (un-staged)
484 * If the derived button does not want the visual removed then use this virtual function to
485 * define the required behaviour.
486 * Can decide to only remove specified visuals via index
488 virtual void OnButtonVisualRemoval( Property::Index visualIndex );
494 * Removes the visual from the button and prepares it to be transitioned out
495 * @param[in] visualIndex the visual to remove
497 void RemoveVisual( Property::Index visualIndex );
500 * Adds the required visual to the button.
501 * @param[in] visualIndex The Property index of the visual required
503 void SelectRequiredVisual( Property::Index visualIndex );
506 Button( const Button& );
509 Button& operator = ( const Button& );
514 Toolkit::Button::ButtonSignalType mPressedSignal; ///< Signal emitted when the button is pressed.
515 Toolkit::Button::ButtonSignalType mReleasedSignal; ///< Signal emitted when the button is released.
516 Toolkit::Button::ButtonSignalType mClickedSignal; ///< Signal emitted when the button is clicked.
517 Toolkit::Button::ButtonSignalType mStateChangedSignal; ///< Signal emitted when the button's state is changed.
519 Timer mAutoRepeatingTimer;
521 Actor mLabel; ///< Stores the button text label.
522 Padding mLabelPadding; ///< The padding around the label (if present).
523 Padding mForegroundPadding; ///< The padding around the foreground/icon visual (if present).
525 Align mTextLabelAlignment; ///< Position of text label in relation to foreground/icon when both are present.
527 TapGestureDetector mTapDetector;
529 bool mAutoRepeating; ///< Stores the autorepeating property.
530 bool mTogglableButton; ///< Stores the togglable property as a flag.
531 bool mTextStringSetFlag; ///< Stores if text has been set. Required in relayout but don't want to calculate there.
533 float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
534 float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
536 float mAnimationTime;
538 PressState mButtonPressedState; ///< In relation to the button being pressed/released
540 State mPreviousButtonState; ///< During a transition between two states, this stores the previous state so Visuals can be removed.
543 bool mClickActionPerforming; ///< Used to manage signal emissions during action
546 struct AccessibleImpl : public Control::Impl::AccessibleImpl
548 using Control::Impl::AccessibleImpl::AccessibleImpl;
550 Dali::Accessibility::States CalculateStates() override;
551 std::string GetNameRaw() override;
552 Property::Index GetNamePropertyIndex() override;
556 } // namespace Internal
558 // Helpers for public-api forwarding methods
560 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
562 DALI_ASSERT_ALWAYS( button );
564 Dali::RefObject& handle = button.GetImplementation();
566 return static_cast<Toolkit::Internal::Button&>( handle );
569 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
571 DALI_ASSERT_ALWAYS( button );
573 const Dali::RefObject& handle = button.GetImplementation();
575 return static_cast<const Toolkit::Internal::Button&>( handle );
578 } // namespace Toolkit
582 #endif // DALI_TOOLKIT_INTERNAL_BUTTON_H