1 #ifndef DALI_TOOLKIT_INTERNAL_BUTTON_H
2 #define DALI_TOOLKIT_INTERNAL_BUTTON_H
5 * Copyright (c) 2019 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>
42 * @copydoc Toolkit::Button
44 * Button is the base class implementation for all buttons.
48 * All Foreground/Icon visuals expected to be the same size.
49 * Background visuals will take the size of the control.
50 * Padding and struts take size precedence over visuals when available space is limited.
51 * Icon/Foreground visuals take size precedence over Labels when available space is limited.
53 class Button : public Control
59 * Enum describing the position the text label can be in relation to the control (and foreground/icon)
63 BEGIN, // At the start of the control before the foreground/icon
64 END, // At the end of the control after the foreground/icon
65 TOP, // At the top of the control above the foreground/icon
66 BOTTOM // At the bottom of the control below the foreground/icon
72 * @brief Sets the button as \e disabled.
73 * @param[in] disabled Disabled property
75 void SetDisabled( bool disabled );
78 * @brief Returns if the button is disabled.
79 * @return \e true if the button is \e disabled
81 bool IsDisabled() const;
84 * @brief Sets the \e autorepeating property.
85 * @param[in] autoRepeating \e autorepeating property
87 void SetAutoRepeating( bool autoRepeating );
90 * @brief Sets the initial autorepeating delay.
91 * @param[in] initialAutoRepeatingDelay in seconds
93 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
96 * @brief Sets the next autorepeating delay.
97 * @param[in] nextAutoRepeatingDelay in seconds
99 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
102 * @brief Sets the \e togglable property.
103 * @param[in] togglable Togglable property
105 void SetTogglableButton( bool togglable );
108 * @brief Sets the button as selected or unselected.
109 * @param[in] selected Selected property
111 void SetSelected( bool selected );
114 * @brief Returns if the selected property is set and the button is togglable.
115 * @return \e true if the button is \e selected
117 bool IsSelected() const;
120 * @brief Produces a Property::Map of Text properties to create a Text Visual, merging existing properties with supplied map
121 * If the label does not exist yet, it is created.
122 * The derived buttons are notified if any properties are changed.
123 * @param[in] properties A Property::Map of key-value pairs of properties to set.
124 * @param[out] properties A Property::Map of text visual properties to set after merging inMap with existing maps
126 void MergeWithExistingLabelProperties( const Property::Map& inMap, Property::Map& outMap );
129 * Performs actions as requested using the action name.
130 * @param[in] object The object on which to perform the action.
131 * @param[in] actionName The action to perform.
132 * @param[in] attributes The attributes with which to perfrom this action.
133 * @return true if action has been accepted by this control
135 static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
144 UNSELECTED_STATE, ///< The button is unselected.
145 SELECTED_STATE, ///< The button is selected.
146 DISABLED_UNSELECTED_STATE, ///< The button is disabled and unselected.
147 DISABLED_SELECTED_STATE, ///< The button is disabled and selected.
148 STATE_COUNT, ///< Number of States
152 * Enum to distinguish the different style-able components of the button
156 UNSELECTED_FOREGROUND = 0,
158 DISABLED_SELECTED_FOREGROUND,
159 DISABLED_UNSELECTED_FOREGROUND,
160 UNSELECTED_BACKGROUND,
162 DISABLED_UNSELECTED_BACKGROUND,
163 DISABLED_SELECTED_BACKGROUND,
168 * Enum to list types of visual a state can have.
180 * Button press state which is not the same as the actual button's state.
181 * For example An UNSELECTED button can be DEPRESSED, but until released, the actual button state doesn't change to SELECTED
185 DEPRESSED, ///< The button is up.
186 UNPRESSED, ///< The button is down.
187 TOGGLE_DEPRESSED, ///< The button has been pressed down and will stay depressed when released.
191 * Construct a new Button.
196 * A reference counted object may only be deleted by calling Unreference()
200 * @return A reference to the label actor.
202 Actor& GetLabelActor();
205 * @return A reference to the unselected button image.
207 Actor GetUnselectedImage();
210 * @return A reference to the selected image.
212 Actor GetSelectedImage();
217 * Perform the click action to click the button.
218 * @param[in] attributes The attributes to perfrom this action.
219 * @return true if this control can perform action.
221 bool DoClickAction( const Property::Map& attributes );
224 * This method is called when the button is a Toggle button and released
225 * Could be reimplemented in subclasses to provide specific behaviour.
226 * @return bool returns true if state changed.
228 virtual bool OnToggleReleased();
231 * This method is called when touch leaves the boundary of the button or several touch points are received.
232 * Could be reimplemented in subclasses to provide specific behaviour.
234 virtual void OnTouchPointLeave();
237 * This method is called when the touch is interrupted.
238 * Could be reimplemented in subclasses to provide specific behaviour.
240 virtual void OnTouchPointInterrupted();
243 * This method is called when the \e selected property is changed.
245 virtual void OnStateChange( State newState ){}
248 * This method is called when the \e disabled property is changed.
250 virtual void OnDisabled() {}
253 * This method is called when the button is pressed.
255 virtual void OnPressed() {}
258 * This method is called when the button is released.
260 virtual void OnReleased() {}
265 * @copydoc Dali::Toolkit::PushButton::PressedSignal()
267 Toolkit::Button::ButtonSignalType& PressedSignal();
270 * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
272 Toolkit::Button::ButtonSignalType& ReleasedSignal();
275 * @copydoc Dali::Toolkit::Button::ClickedSignal()
277 Toolkit::Button::ButtonSignalType& ClickedSignal();
280 * @copydoc Dali::Toolkit::Button::StateChangedSignal()
282 Toolkit::Button::ButtonSignalType& StateChangedSignal();
285 * Connects a callback function with the object's signals.
286 * @param[in] object The object providing the signal.
287 * @param[in] tracker Used to disconnect the signal.
288 * @param[in] signalName The signal to connect to.
289 * @param[in] functor A newly allocated FunctorDelegate.
290 * @return True if the signal was connected.
291 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
293 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
298 * Called when a property of an object of this type is set.
299 * @param[in] object The object whose property is set.
300 * @param[in] index The property index.
301 * @param[in] value The new property value.
303 static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
306 * Called to retrieve a property of an object of this type.
307 * @param[in] object The object whose property is to be retrieved.
308 * @param[in] index The property index.
309 * @return The current value of the property.
311 static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
313 protected: // From Control
316 * @copydoc Toolkit::Control::OnInitialize()
317 * @note If overridden by deriving button classes, then an up-call to Button::OnInitialize MUST be made at the start.
319 virtual void OnInitialize();
322 * @copydoc Toolkit::Control::OnAccessibilityActivated()
324 virtual bool OnAccessibilityActivated();
327 * @copydoc Toolkit::Control::OnKeyboardEnter()
329 virtual bool OnKeyboardEnter();
332 * @copydoc Toolkit::Control::OnStageDisconnection()
333 * @note If overridden by deriving button classes, then an up-call to Button::OnStageDisconnection MUST be made at the end.
335 virtual void OnStageDisconnection();
338 * @copydoc Toolkit::Control::OnStageConnnection()
340 virtual void OnStageConnection( int depth );
343 * @copydoc Toolkit::Control::GetNaturalSize
345 virtual Vector3 GetNaturalSize();
348 * @copydoc Toolkit::Control::OnSetResizePolicy
350 virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension );
353 * @copydoc Toolkit::Control::OnRelayout
355 virtual void OnRelayout( const Vector2& size, RelayoutContainer& container );
360 * @brief Handler for touch data
361 * @param[in] actor The touched actor.
362 * @param[in] touch The touch info.
363 * @return true, if consumed, false otherwise.
365 bool OnTouch( Actor actor, const TouchData& touch );
368 * Handler for tap events.
369 * We do not actually do anything when we receive a tap as the button handles tap event through
370 * the touch event system itself as it requires more than just tap handling (e.g. leave events).
371 * This stops any of our parents receiving a tap gesture when it occurs within our area.
372 * @param[in] actor The tapped actor.
373 * @param[in] tap The tap gesture.
375 void OnTap(Actor actor, const TapGesture& tap);
378 * Sets up the autorepeating timer.
379 * @param[in] delay The delay time in seconds.
381 void SetUpTimer( float delay );
384 * Button has been pressed
389 * This method is called the button is down.
394 * This method is called when the button is up.
399 * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
401 bool AutoRepeatingSlot();
404 * Check the requested state is an allowed transition.
405 * Some states can not be transitioned to from certain states.
406 * @param[in] requestedState check if can transition to this state
407 * @return bool true if state change valid
409 bool ValidateState( State requestedState );
412 * Changes the button state when an action occurs on it
413 * @param[in] requestedState the state to change to
415 void ChangeState( State requestedState );
418 * This method is called when the button is released.
425 * Set Text Label Padding
426 * @param[in] padding BEGIN END BOTTOM TOP
428 void SetLabelPadding( const Padding& padding );
431 * Get Text Label padding
434 Padding GetLabelPadding();
437 * Set Foreground/icon Padding
438 * @param[in] padding BEGIN END BOTTOM TOP
440 void SetForegroundPadding( const Padding& padding);
443 * Get Foreground padding
446 Padding GetForegroundPadding();
449 * @brief Setup the button components for example foregrounds and background
450 * @param[in] index the index of the visual to set
451 * @param[in] value the value to set on the component
452 * @param[in] visualDepth the depth of the visual if overlapping another
454 void CreateVisualsForComponent( Property::Index index, const Property::Value& value, const int visualDepth );
457 * @brief Get the Property map for the given Visual
458 * @param[in] visualIndex visual index of the required visual
459 * @param[out] retreivedMap the property map used to construct the required visual
460 * @return bool success flag, true if visual found
462 bool GetPropertyMapForVisual( Property::Index visualIndex, Property::Map& retreivedMap ) const;
464 * Returns the animation to be used for transition, creating the animation if needed.
465 * @return The initialised transition animation.
467 Dali::Animation GetTransitionAnimation();
470 * @brief Set the position of the label relative to foreground/icon, if both present
471 * @param[in] labelAlignment given alignment setting
473 void SetLabelAlignment( Align labelAlignment);
476 * @brief Get set alignment of label in relation to foreground/icon
477 * @return Set alignment value
479 Align GetLabelAlignment();
482 * Removes the visual from the button (un-staged)
483 * If the derived button does not want the visual removed then use this virtual function to
484 * define the required behaviour.
485 * Can decide to only remove specified visuals via index
487 virtual void OnButtonVisualRemoval( Property::Index visualIndex );
493 * Removes the visual from the button and prepares it to be transitioned out
494 * @param[in] visualIndex the visual to remove
496 void RemoveVisual( Property::Index visualIndex );
499 * Adds the required visual to the button.
500 * @param[in] visualIndex The Property index of the visual required
502 void SelectRequiredVisual( Property::Index visualIndex );
505 Button( const Button& );
508 Button& operator = ( const Button& );
513 Toolkit::Button::ButtonSignalType mPressedSignal; ///< Signal emitted when the button is pressed.
514 Toolkit::Button::ButtonSignalType mReleasedSignal; ///< Signal emitted when the button is released.
515 Toolkit::Button::ButtonSignalType mClickedSignal; ///< Signal emitted when the button is clicked.
516 Toolkit::Button::ButtonSignalType mStateChangedSignal; ///< Signal emitted when the button's state is changed.
518 Timer mAutoRepeatingTimer;
520 Actor mLabel; ///< Stores the button text label.
521 Padding mLabelPadding; ///< The padding around the label (if present).
522 Padding mForegroundPadding; ///< The padding around the foreground/icon visual (if present).
524 Align mTextLabelAlignment; ///< Position of text label in relation to foreground/icon when both are present.
526 TapGestureDetector mTapDetector;
528 bool mAutoRepeating; ///< Stores the autorepeating property.
529 bool mTogglableButton; ///< Stores the togglable property as a flag.
530 bool mTextStringSetFlag; ///< Stores if text has been set. Required in relayout but don't want to calculate there.
532 float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
533 float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
535 float mAnimationTime;
537 PressState mButtonPressedState; ///< In relation to the button being pressed/released
539 State mPreviousButtonState; ///< During a transition between two states, this stores the previous state so Visuals can be removed.
542 bool mClickActionPerforming; ///< Used to manage signal emissions during action
545 } // namespace Internal
547 // Helpers for public-api forwarding methods
549 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
551 DALI_ASSERT_ALWAYS( button );
553 Dali::RefObject& handle = button.GetImplementation();
555 return static_cast<Toolkit::Internal::Button&>( handle );
558 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
560 DALI_ASSERT_ALWAYS( button );
562 const Dali::RefObject& handle = button.GetImplementation();
564 return static_cast<const Toolkit::Internal::Button&>( handle );
567 } // namespace Toolkit
571 #endif // DALI_TOOLKIT_INTERNAL_BUTTON_H