1 #ifndef DALI_TOOLKIT_INTERNAL_BUTTON_H
2 #define DALI_TOOLKIT_INTERNAL_BUTTON_H
5 * Copyright (c) 2014 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/public-api/controls/buttons/button.h>
28 #include <dali-toolkit/public-api/controls/control-impl.h>
30 //#if defined(DEBUG_ENABLED)
31 // Debug::Filter* gLogButtonFilter = Debug::Filter::New(Debug::NoLogging, true, "LOG_BUTTON_CONTROL");
46 * @copydoc Toolkit::Button
48 * Button is the base class implementation for all buttons.
52 * All Foreground/Icon visuals expected to be the same size.
53 * Background visuals will take the size of the control.
54 * Padding and struts take size precedence over visuals when available space is limited.
55 * Icon/Foreground visuals take size precedence over Labels when available space is limited.
57 class Button : public Control
63 * Enum describing the position the text label can be in relation to the control (and foreground/icon)
67 BEGIN, // At the start of the control before the foreground/icon
68 END, // At the end of the control after the foreground/icon
69 TOP, // At the top of the control above the foreground/icon
70 BOTTOM // At the bottom of the control below the foreground/icon
76 * @copydoc Dali::Toolkit::Button::SetDisabled
78 void SetDisabled( bool disabled );
81 * @copydoc Dali::Toolkit::Button::IsDisabled
83 bool IsDisabled() const;
86 * @copydoc Dali::Toolkit::Button::SetAutoRepeating
88 void SetAutoRepeating( bool autoRepeating );
91 * @copydoc Dali::Toolkit::Button::IsAutoRepeating
93 bool IsAutoRepeating() const;
96 * @copydoc Dali::Toolkit::Button::SetInitialAutoRepeatingDelay
98 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
101 * @copydoc Dali::Toolkit::Button::GetInitialAutoRepeatingDelay
103 float GetInitialAutoRepeatingDelay() const;
106 * @copydoc Dali::Toolkit::Button::SetNextAutoRepeatingDelay
108 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
111 * @copydoc Dali::Toolkit::Button::GetNextAutoRepeatingDelay
113 float GetNextAutoRepeatingDelay() const;
116 * @copydoc Dali::Toolkit::Button::SetTogglableButton
118 void SetTogglableButton( bool togglable );
121 * @copydoc Dali::Toolkit::Button::IsTogglableButton
123 bool IsTogglableButton() const;
126 * @copydoc Dali::Toolkit::Button::SetSelected
128 void SetSelected( bool selected );
131 * @copydoc Dali::Toolkit::Button::IsSelected
133 bool IsSelected() const;
136 * @copydoc Dali::Toolkit::Button::SetAnimationTime
138 void SetAnimationTime( float animationTime );
141 * @copydoc Dali::Toolkit::Button::GetAnimationTime
143 float GetAnimationTime() const;
146 * @copydoc Dali::Toolkit::Button::SetLabelText
148 void SetLabelText( const std::string& label );
151 * @copydoc Dali::Toolkit::Button::GetLabelText
153 std::string GetLabelText() const;
156 * @brief Sets the specified properties on the button label.
157 * If the label does not exist yet, it is created.
158 * The derived buttons are notified if any properties are changed.
159 * @param[in] properties A Property::Map of key-value pairs of properties to set.
161 void SetupLabel( const Property::Map& properties );
164 * Performs actions as requested using the action name.
165 * @param[in] object The object on which to perform the action.
166 * @param[in] actionName The action to perform.
167 * @param[in] attributes The attributes with which to perfrom this action.
168 * @return true if action has been accepted by this control
170 static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
172 public: // Deprecated API
175 * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
177 void SetLabel( Actor label );
180 * @deprecated Sets the unselected image with an url.
181 * @param[in] image The Actor to use.
183 void SetUnselectedImage( const std::string& filename );
186 * @deprecated Sets the selected image with an url.
187 * @param[in] filename The url of the image to use to use.
189 void SetSelectedImage( const std::string& filename );
192 * @deprecated Sets the selected background image with an url.
193 * @param[in] filename The url of the image to use to use.
195 void SetSelectedBackgroundImage( const std::string& filename );
198 * @deprecated Sets the background image with an url.
199 * @param[in] filename The url of the image to use to use.
201 void SetBackgroundImage( const std::string& filename );
204 * @deprecated Sets the disabled unselected background image with an url.
205 * @param[in] filename The url of the image to use to use.
207 void SetDisabledBackgroundImage( const std::string& filename );
210 * @deprecated Sets the disabled unselected image with an url.
211 * @param[in] filename The url of the image to use to use.
213 void SetDisabledImage( const std::string& filename );
216 * @deprecated Sets the disabled selected image with an url.
217 * @param[in] filename The url of the image to use to use.
219 void SetDisabledSelectedImage( const std::string& filename );
222 * @deprecated Sets the unselected image with an Actor.
223 * @param[in] image The Actor to use.
225 void SetUnselectedImage( Actor image );
228 * @deprecated Sets the selected image with an Actor.
229 * @param[in] image The Actor to use.
231 void SetSelectedImage( Actor image );
234 * @deprecated Sets the selected background image with an Actor.
235 * @param[in] image The Actor to use.
237 void SetSelectedBackgroundImage( Actor image );
240 * @deprecated Sets the disabled image with an Actor.
241 * @param[in] image The Actor to use.
243 void SetDisabledImage( Actor image );
246 * @deprecated Sets the disabled selected image with an Actor.
247 * @param[in] image The Actor to use.
249 void SetDisabledSelectedImage( Actor image );
252 * @deprecated Sets the disabled background image with an Actor.
253 * @param[in] image The Actor to use.
255 void SetDisabledBackgroundImage( Actor image );
258 * @Gets url of a image visual, used by GetProperty but for deprecated Properties
259 * @param[in] index Visual index of url required
260 * @return filename for the corresponding visual
262 std::string GetUrlForImageVisual( Property::Index index );
266 * @copydoc Dali::Toolkit::Button::GetButtonImage
268 Actor GetButtonImage() const;
271 * @copydoc Dali::Toolkit::Button::GetSelectedImage
273 Actor GetSelectedImage() const;
282 UNSELECTED_STATE, ///< The button is unselected.
283 SELECTED_STATE, ///< The button is selected.
284 DISABLED_UNSELECTED_STATE, ///< The button is disabled and unselected.
285 DISABLED_SELECTED_STATE, ///< The button is disabled and selected.
286 STATE_COUNT, ///< Number of States
290 * Enum to distinguish the different style-able components of the button
294 UNSELECTED_FOREGROUND = 0,
296 DISABLED_SELECTED_FOREGROUND,
297 DISABLED_UNSELECTED_FOREGROUND,
298 UNSELECTED_BACKGROUND,
300 DISABLED_UNSELECTED_BACKGROUND,
301 DISABLED_SELECTED_BACKGROUND,
306 * Enum to list types of visual a state can have.
318 * Button press state which is not the same as the actual button's state.
319 * For example An UNSELECTED button can be DEPRESSED, but until released, the actual button state doesn't change to SELECTED
323 DEPRESSED, ///< The button is up.
324 UNPRESSED, ///< The button is down.
325 TOGGLE_DEPRESSED, ///< The button has been pressed down and will stay depressed when released.
329 * Construct a new Button.
334 * A reference counted object may only be deleted by calling Unreference()
338 * @return A reference to the label actor.
340 Actor& GetLabelActor();
343 * @return A reference to the unselected button image.
345 Actor GetUnselectedImage();
348 * @return A reference to the selected image.
350 Actor GetSelectedImage();
355 * Perform the click action to click the button.
356 * @param[in] attributes The attributes to perfrom this action.
357 * @return true if this control can perform action.
359 bool DoClickAction( const Property::Map& attributes );
362 * This method is called when the button is a Toggle button and released
363 * Could be reimplemented in subclasses to provide specific behaviour.
364 * @return bool returns true if state changed.
366 virtual bool OnToggleReleased();
369 * This method is called when touch leaves the boundary of the button or several touch points are received.
370 * Could be reimplemented in subclasses to provide specific behaviour.
372 virtual void OnTouchPointLeave();
375 * This method is called when the touch is interrupted.
376 * Could be reimplemented in subclasses to provide specific behaviour.
378 virtual void OnTouchPointInterrupted();
381 * This method is called when the \e selected property is changed.
383 virtual void OnStateChange( State newState ){}
386 * This method is called when the \e disabled property is changed.
388 virtual void OnDisabled() {}
391 * This method is called when the button is pressed.
393 virtual void OnPressed() {}
396 * This method is called when the button is released.
398 virtual void OnReleased() {}
403 * @copydoc Dali::Toolkit::PushButton::PressedSignal()
405 Toolkit::Button::ButtonSignalType& PressedSignal();
408 * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
410 Toolkit::Button::ButtonSignalType& ReleasedSignal();
413 * @copydoc Dali::Toolkit::Button::ClickedSignal()
415 Toolkit::Button::ButtonSignalType& ClickedSignal();
418 * @copydoc Dali::Toolkit::Button::StateChangedSignal()
420 Toolkit::Button::ButtonSignalType& StateChangedSignal();
423 * Connects a callback function with the object's signals.
424 * @param[in] object The object providing the signal.
425 * @param[in] tracker Used to disconnect the signal.
426 * @param[in] signalName The signal to connect to.
427 * @param[in] functor A newly allocated FunctorDelegate.
428 * @return True if the signal was connected.
429 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
431 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
436 * Called when a property of an object of this type is set.
437 * @param[in] object The object whose property is set.
438 * @param[in] index The property index.
439 * @param[in] value The new property value.
441 static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
444 * Called to retrieve a property of an object of this type.
445 * @param[in] object The object whose property is to be retrieved.
446 * @param[in] index The property index.
447 * @return The current value of the property.
449 static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
451 protected: // From Control
454 * @copydoc Toolkit::Control::OnInitialize()
455 * @note If overridden by deriving button classes, then an up-call to Button::OnInitialize MUST be made at the start.
457 virtual void OnInitialize();
460 * @copydoc Toolkit::Control::OnAccessibilityActivated()
462 virtual bool OnAccessibilityActivated();
465 * @copydoc Toolkit::Control::OnKeyboardEnter()
467 virtual bool OnKeyboardEnter();
470 * @copydoc Toolkit::Control::OnStageDisconnection()
471 * @note If overridden by deriving button classes, then an up-call to Button::OnStageDisconnection MUST be made at the end.
473 virtual void OnStageDisconnection();
476 * @copydoc Toolkit::Control::OnStageConnnection()
478 virtual void OnStageConnection( int depth );
481 * @copydoc Toolkit::Control::GetNaturalSize
483 virtual Vector3 GetNaturalSize();
486 * @copydoc Toolkit::Control::OnSetResizePolicy
488 virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension );
491 * @copydoc Toolkit::Control::OnRelayout
493 virtual void OnRelayout( const Vector2& size, RelayoutContainer& container );
498 * @brief Handler for touch data
499 * @param[in] actor The touched actor.
500 * @param[in] touch The touch info.
501 * @return true, if consumed, false otherwise.
503 bool OnTouch( Actor actor, const TouchData& touch );
506 * Handler for tap events.
507 * We do not actually do anything when we receive a tap as the button handles tap event through
508 * the touch event system itself as it requires more than just tap handling (e.g. leave events).
509 * This stops any of our parents receiving a tap gesture when it occurs within our area.
510 * @param[in] actor The tapped actor.
511 * @param[in] tap The tap gesture.
513 void OnTap(Actor actor, const TapGesture& tap);
516 * Sets up the autorepeating timer.
517 * @param[in] delay The delay time in seconds.
519 void SetUpTimer( float delay );
522 * Button has been pressed
527 * This method is called the button is down.
532 * This method is called when the button is up.
537 * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
539 bool AutoRepeatingSlot();
542 * Check the requested state is an allowed transition.
543 * Some states can not be transitioned to from certain states.
544 * @param[in] requestedState check if can transition to this state
545 * @return bool true if state change valid
547 bool ValidateState( State requestedState );
550 * Perform the given function on the visuals in the given state. Can be used to add and remove visuals.
551 * @param[in] functionPtr pointer to the function to perform an action on a visual
552 * @param[in] state Visuals in this state will be the target
554 void PerformFunctionOnVisualsInState( void(Button::*functionPtr)( Property::Index visualIndex), State state );
557 * Changes the button state when an action occurs on it
558 * @param[in] requestedState the state to change to
560 void ChangeState( State requestedState );
563 * @brief Get unselected button color
564 * @return color as vector4
566 const Vector4 GetUnselectedColor() const;
569 * @brief Get selected button color
570 * @return color as vector4
572 const Vector4 GetSelectedColor() const;
575 * Sets the color of button in selected or unselected state, if image also supplied this color will be appplied to it.
576 * If no visual exists, it is created.
577 * @param[in] color The color to use.
578 * @param[in] visualIndex The Visual to apply the color
580 void SetColor( const Vector4& color, Property::Index visualIndex );
583 * This method is called when the button is released.
590 * Set Text Label Padding
591 * @param[in] padding BEGIN END BOTTOM TOP
593 void SetLabelPadding( const Padding& padding );
596 * Get Text Label padding
599 Padding GetLabelPadding();
602 * Set Foreground/icon Padding
603 * @param[in] padding BEGIN END BOTTOM TOP
605 void SetForegroundPadding( const Padding& padding);
608 * Get Foreground padding
611 Padding GetForegroundPadding();
614 * @brief Setup the button components for example foregrounds and background
615 * @param[in] index the index of the visual to set
616 * @param[in] value the value to set on the component
617 * @param[in] visualDepth the depth of the visual if overlapping another
619 void CreateVisualsForComponent( Property::Index index ,const Property::Value& value, const float visualDepth );
622 * Returns the animation to be used for transition, creating the animation if needed.
623 * @return The initialised transition animation.
625 Dali::Animation GetTransitionAnimation();
628 * @brief Set the position of the label relative to foreground/icon, if both present
629 * @param[in] labelAlignment given alignment setting
631 void SetLabelAlignment( Align labelAlignment);
634 * @brief Get set alignment of label in relation to foreground/icon
635 * @return Set alignment value
637 Align GetLabelAlignment();
640 * Removes the visual from the button (un-staged)
641 * If the derived button does not want the visual removed then use this virtual function to
642 * define the required behaviour.
643 * Can decide to only remove specified visuals via index
645 virtual void OnButtonVisualRemoval( Property::Index visualIndex );
651 * Removes the visual from the button and prepares it to be transitioned out
652 * @param[in] visualIndex the visual to remove
654 void RemoveVisual( Property::Index visualIndex );
657 * Adds the required visual to the button.
658 * @param[in] visualIndex The Property index of the visual required
660 void SelectRequiredVisual( Property::Index visualIndex );
663 Button( const Button& );
666 Button& operator = ( const Button& );
671 Toolkit::Button::ButtonSignalType mPressedSignal; ///< Signal emitted when the button is pressed.
672 Toolkit::Button::ButtonSignalType mReleasedSignal; ///< Signal emitted when the button is released.
673 Toolkit::Button::ButtonSignalType mClickedSignal; ///< Signal emitted when the button is clicked.
674 Toolkit::Button::ButtonSignalType mStateChangedSignal; ///< Signal emitted when the button's state is changed.
676 Timer mAutoRepeatingTimer;
678 Actor mLabel; ///< Stores the button text label.
679 Padding mLabelPadding; ///< The padding around the label (if present).
680 Padding mForegroundPadding; ///< The padding around the foreground/icon visual (if present).
682 Align mTextLabelAlignment; ///< Position of text label in relation to foreground/icon when both are present.
684 TapGestureDetector mTapDetector;
686 Vector4 mUnselectedColor;
687 Vector4 mSelectedColor;
689 bool mAutoRepeating; ///< Stores the autorepeating property.
690 bool mTogglableButton; ///< Stores the togglable property as a flag.
691 float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
692 float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
694 float mAnimationTime;
696 PressState mButtonPressedState; ///< In relation to the button being pressed/released
698 State mPreviousButtonState; ///< During a transition between two states, this stores the previous state so Visuals can be removed.
701 bool mClickActionPerforming; ///< Used to manage signal emissions during action
704 } // namespace Internal
706 // Helpers for public-api forwarding methods
708 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
710 DALI_ASSERT_ALWAYS( button );
712 Dali::RefObject& handle = button.GetImplementation();
714 return static_cast<Toolkit::Internal::Button&>( handle );
717 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
719 DALI_ASSERT_ALWAYS( button );
721 const Dali::RefObject& handle = button.GetImplementation();
723 return static_cast<const Toolkit::Internal::Button&>( handle );
726 } // namespace Toolkit
730 #endif // DALI_TOOLKIT_INTERNAL_BUTTON_H