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/public-api/controls/buttons/button.h>
27 #include <dali-toolkit/public-api/controls/control-impl.h>
41 * Button is the base class implementation for all buttons.
43 class Button : public Control
49 * Construct a new Button.
54 * A reference counted object may only be deleted by calling Unreference()
61 * @copydoc Dali::Toolkit::Button::SetDisabled
63 void SetDisabled( bool disabled );
66 * @copydoc Dali::Toolkit::Button::IsDisabled
68 bool IsDisabled() const;
71 * @copydoc Dali::Toolkit::Button::SetAutoRepeating
73 void SetAutoRepeating( bool autoRepeating );
76 * @copydoc Dali::Toolkit::Button::IsAutoRepeating
78 bool IsAutoRepeating() const;
81 * @copydoc Dali::Toolkit::Button::SetInitialAutoRepeatingDelay
83 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
86 * @copydoc Dali::Toolkit::Button::GetInitialAutoRepeatingDelay
88 float GetInitialAutoRepeatingDelay() const;
91 * @copydoc Dali::Toolkit::Button::SetNextAutoRepeatingDelay
93 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
96 * @copydoc Dali::Toolkit::Button::GetNextAutoRepeatingDelay
98 float GetNextAutoRepeatingDelay() const;
101 * @copydoc Dali::Toolkit::Button::SetTogglableButton
103 void SetTogglableButton( bool togglable );
106 * @copydoc Dali::Toolkit::Button::IsTogglableButton
108 bool IsTogglableButton() const;
111 * @copydoc Dali::Toolkit::Button::SetSelected
113 void SetSelected( bool selected );
116 * @copydoc Dali::Toolkit::Button::IsSelected
118 bool IsSelected() const;
121 * @copydoc Dali::Toolkit::Button::SetAnimationTime
123 void SetAnimationTime( float animationTime );
126 * @copydoc Dali::Toolkit::Button::GetAnimationTime
128 float GetAnimationTime() const;
131 * @copydoc Dali::Toolkit::Button::SetLabelText
133 void SetLabelText( const std::string& label );
136 * @copydoc Dali::Toolkit::Button::GetLabelText
138 std::string GetLabelText() const;
141 * @copydoc Dali::Toolkit::PushButton::SetUnselectedImage
143 void SetUnselectedImage( const std::string& filename );
146 * @copydoc Dali::Toolkit::PushButton::SetSelectedImage
148 void SetSelectedImage( const std::string& filename );
151 * @copydoc Dali::Toolkit::PushButton::SetBackgroundImage
153 void SetBackgroundImage( const std::string& filename );
156 * @copydoc Dali::Toolkit::PushButton::SetSelectedBackgroundImage
158 void SetSelectedBackgroundImage( const std::string& filename );
161 * @copydoc Dali::Toolkit::PushButton::SetDisabledImage
163 void SetDisabledImage( const std::string& filename );
166 * @copydoc Dali::Toolkit::CheckBoxButton::SetDisabledSelectedImage
168 void SetDisabledSelectedImage( const std::string& filename );
171 * @copydoc Dali::Toolkit::PushButton::SetDisabledBackgroundImage
173 void SetDisabledBackgroundImage( const std::string& filename );
176 * @return The filename used for the button image.
178 std::string GetUnselectedImageFilename() const;
181 * @return The filename used for the selected image.
183 std::string GetSelectedImageFilename() const;
186 * @return The filename used for the background image.
188 std::string GetBackgroundImageFilename() const;
191 * @return The filename used for the selected background image.
193 std::string GetSelectedBackgroundImageFilename() const;
196 * @return The filename used for the disabled button image.
198 std::string GetDisabledImageFilename() const;
201 * @return The filename used for the disabled selected image.
203 std::string GetDisabledSelectedImageFilename() const;
206 * @return The filename used for the disabled background image.
208 std::string GetDisabledBackgroundImageFilename() const;
211 * @brief Sets the specified properties on the button label.
212 * If the label does not exist yet, it is created.
213 * The derived buttons are notified if any properties are changed.
214 * @param[in] properties A Property::Map of key-value pairs of properties to set.
216 void ModifyLabel( const Property::Map& properties );
219 * Performs actions as requested using the action name.
220 * @param[in] object The object on which to perform the action.
221 * @param[in] actionName The action to perform.
222 * @param[in] attributes The attributes with which to perfrom this action.
223 * @return true if action has been accepted by this control
225 static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
227 public: // Deprecated API
230 * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
232 void SetLabel( Actor label );
235 * @deprecated Sets the unselected image with an Actor.
236 * @param[in] image The Actor to use.
238 void SetButtonImage( Actor image );
241 * @deprecated Sets the selected image with an Actor.
242 * @param[in] image The Actor to use.
244 void SetSelectedImage( Actor image );
247 * @deprecated Sets the background image with an Actor.
248 * @param[in] image The Actor to use.
250 void SetBackgroundImage( Actor image );
253 * @deprecated Sets the selected background image with an Actor.
254 * @param[in] image The Actor to use.
256 void SetSelectedBackgroundImage( Actor image );
259 * @deprecated Sets the disabled image with an Actor.
260 * @param[in] image The Actor to use.
262 void SetDisabledImage( Actor image );
265 * @deprecated Sets the disabled selected image with an Actor.
266 * @param[in] image The Actor to use.
268 void SetDisabledSelectedImage( Actor image );
271 * @deprecated Sets the disabled background image with an Actor.
272 * @param[in] image The Actor to use.
274 void SetDisabledBackgroundImage( Actor image );
277 * @copydoc Dali::Toolkit::Button::GetButtonImage
279 Actor GetButtonImage() const;
282 * @copydoc Dali::Toolkit::Button::GetSelectedImage
284 Actor GetSelectedImage() const;
289 * @return A reference to the label actor.
291 Actor& GetLabelActor();
294 * @return A reference to the unselected button image.
296 Actor& GetUnselectedImage();
299 * @return A reference to the selected image.
301 Actor& GetSelectedImage();
304 * @return A reference to the background image.
306 Actor& GetBackgroundImage();
309 * @return A reference to the selected background image.
311 Actor& GetSelectedBackgroundImage();
314 * @return A reference to the disabled button image.
316 Actor& GetDisabledImage();
319 * @return A reference to the disabled selected image.
321 Actor& GetDisabledSelectedImage();
324 * @return A reference to the disabled background image.
326 Actor& GetDisabledBackgroundImage();
331 * Perform the click action to click the button.
332 * @param[in] attributes The attributes to perfrom this action.
333 * @return true if this control can perform action.
335 bool DoClickAction( const Property::Map& attributes );
338 * This method is called after the button initialization.
339 * Could be reimplemented in subclasses to provide specific behaviour.
341 virtual void OnButtonInitialize() { }
344 * This method is called when the label is set.
345 * @param[in] noPadding Used to bypass padding if the label is to be treated generically.
347 virtual void OnLabelSet( bool noPadding ) {}
350 * This method is called when the unselected button image is set
352 virtual void OnUnselectedImageSet() {}
355 * This method is called when the selected image is set
357 virtual void OnSelectedImageSet() {}
360 * This method is called when the background image is set
362 virtual void OnBackgroundImageSet() {}
365 * This method is called when the selected background image is set
367 virtual void OnSelectedBackgroundImageSet() {}
370 * This method is called when the disabled button image is set
372 virtual void OnDisabledImageSet() {}
375 * This method is called when the disabled selected image is set
377 virtual void OnDisabledSelectedImageSet() {}
380 * This method is called when the disabled background image is set
382 virtual void OnDisabledBackgroundImageSet() {}
385 * This method is called from the OnTouchEvent method when the button is down.
386 * Could be reimplemented in subclasses to provide specific behaviour.
388 virtual void OnButtonDown();
391 * This method is called from the OnTouchEvent method when the button is up.
392 * Could be reimplemented in subclasses to provide specific behaviour.
394 virtual void OnButtonUp();
397 * This method is called from the OnTouchEvent method when the touch point leaves the boundary of the button or
398 * more than one touch points are received.
399 * Could be reimplemented in subclasses to provide specific behaviour.
401 virtual void OnTouchPointLeave();
404 * This method is called from the OnTouchEvent method when the touch point is interrupted.
405 * Could be reimplemented in subclasses to provide specific behaviour.
407 virtual void OnTouchPointInterrupted();
410 * This method is called when the button is removed from the stage.
411 * Could be reimplemented in subclasses to provide specific behaviour.
413 virtual void OnButtonStageDisconnection();
416 * This method is called when the \e selected property is changed.
418 virtual void OnSelected() {}
421 * This method is called when the \e disabled property is changed.
423 virtual void OnDisabled() {}
426 * This method is called when the button is pressed.
428 virtual void OnPressed() {}
431 * This method is called when the button is released.
433 virtual void OnReleased() {}
438 * @copydoc Dali::Toolkit::PushButton::PressedSignal()
440 Toolkit::Button::ButtonSignalType& PressedSignal();
443 * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
445 Toolkit::Button::ButtonSignalType& ReleasedSignal();
448 * @copydoc Dali::Toolkit::Button::ClickedSignal()
450 Toolkit::Button::ButtonSignalType& ClickedSignal();
453 * @copydoc Dali::Toolkit::Button::StateChangedSignal()
455 Toolkit::Button::ButtonSignalType& StateChangedSignal();
458 * Connects a callback function with the object's signals.
459 * @param[in] object The object providing the signal.
460 * @param[in] tracker Used to disconnect the signal.
461 * @param[in] signalName The signal to connect to.
462 * @param[in] functor A newly allocated FunctorDelegate.
463 * @return True if the signal was connected.
464 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
466 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
471 * Called when a property of an object of this type is set.
472 * @param[in] object The object whose property is set.
473 * @param[in] index The property index.
474 * @param[in] value The new property value.
476 static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
479 * Called to retrieve a property of an object of this type.
480 * @param[in] object The object whose property is to be retrieved.
481 * @param[in] index The property index.
482 * @return The current value of the property.
484 static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
486 protected: // From CustomActorImpl
489 * @copydoc Dali::CustomActorImpl::OnTouchEvent( const TouchEvent& event )
491 virtual bool OnTouchEvent( const TouchEvent& event );
493 private: // From Control
496 * @copydoc Toolkit::Control::OnInitialize()
498 virtual void OnInitialize();
501 * @copydoc Toolkit::Control::OnAccessibilityActivated()
503 virtual bool OnAccessibilityActivated();
506 * @copydoc Toolkit::Control::OnKeyboardEnter()
508 virtual bool OnKeyboardEnter();
511 * Callback received when the button is disconnected from the stage.
512 * It resets the button status.
514 void OnControlStageDisconnection();
519 * Handler for tap events.
520 * We do not actually do anything when we receive a tap as the button handles tap event through
521 * the touch event system itself as it requires more than just tap handling (e.g. leave events).
522 * This stops any of our parents receiving a tap gesture when it occurs within our area.
523 * @param[in] actor The tapped actor.
524 * @param[in] tap The tap gesture.
526 void OnTap(Actor actor, const TapGesture& tap);
529 * Sets up the autorepeating timer.
530 * @param[in] delay The delay time in seconds.
532 void SetUpTimer( float delay );
535 * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
537 bool AutoRepeatingSlot();
540 * Sets the button as selected or unselected.
541 * @param[in] selected \e selected property value.
542 * @param[in] emitSignal Emit a signal if this value is \e true.
544 void SetSelected( bool selected, bool emitSignal );
547 * This method is called when the button is pressed.
552 * This method is called when the button is released.
557 * Used to perform common setup applied to images within button.
558 * This will replace the current image with the specifed one.
559 * @param[in] actorToModify The image to replace.
560 * @param[out] newActor The new image to use.
562 void SetupContent( Actor& actorToModify, Actor newActor );
565 * Sets the color of the unselected image.
566 * If no image exists, it is created.
567 * @param[in] color The color to use.
569 void SetUnselectedColor( const Vector4& color );
572 * Gets the unselected content color.
573 * @return The currently used unselected color.
575 const Vector4 GetUnselectedColor() const;
578 * Sets the color of the selected image.
579 * If no image exists, it is created.
580 * @param[in] color The color to use.
582 void SetSelectedColor( const Vector4& color );
585 * Gets the selected content color.
586 * @return The currently used selected color.
588 const Vector4 GetSelectedColor() const;
594 ButtonUp, ///< The button is up.
595 ButtonDown, ///< The button is down.
599 * Button paint states.
603 UnselectedState, ///< The button is unselected.
604 SelectedState, ///< The button is selected.
605 DisabledUnselectedState, ///< The button is disabled and unselected.
606 DisabledSelectedState, ///< The button is disabled and selected.
610 * Enum to specify which decoration when getting and setting decorations.
614 UNSELECTED_DECORATION = 0,
619 ButtonState GetState();
620 PaintState GetPaintState();
621 void SetDecoration( DecorationState state, Actor actor );
622 Actor& GetDecoration( DecorationState state );
626 * Returns the animation to be used for transitioning creating the animation if needed.
627 * @return The initialised transition animation.
629 Dali::Animation GetTransitionAnimation();
632 * Prepares the actor to be transitioned in.
633 * @param[in] actor The actor that will be transitioned in.
635 virtual void PrepareForTranstionIn( Actor actor ) {}
638 * Prepares the actor to be transitioned in.
639 * @param[in] actor The actor that will be transitioned out.
641 virtual void PrepareForTranstionOut( Actor actor ) {}
644 * Transitions the actor in, allowing derived classes to configure
645 * the GetTransitionAnimation() animation ready.
646 * Button is in charge of calling Dali::Animation::Play and so derived classes
647 * only need to add the animation.
649 virtual void OnTransitionIn( Actor actor ) {}
652 * Transitions the actor out, allowing derived classes to configure
653 * the GetTransitionAnimation() animation ready.
654 * Button is in charge of calling Dali::Animation::Play and so derived classes
655 * only need to add the animation.
657 virtual void OnTransitionOut( Actor actor ) {}
662 * Starts the transition animation.
663 * Button::TransitionFinished is called when the animation finishes.
665 void StartTransitionAnimation();
668 * This method stops all transition animations
670 void StopTransitionAnimation();
673 * Called when the transition animation finishes.
675 void TransitionAnimationFinished( Dali::Animation& source );
678 * Resets the Button to the base state for the current paint state.
679 * Any additionally inserted images needed for transitions that are
680 * no longer needed and the removed.
682 void ResetImageLayers();
685 * Transitions out the actor
687 void TransitionOut( Actor actor );
690 * Removes the actor from the button and prepares it to be transitioned out
692 void RemoveButtonImage( Actor& actor );
695 * Finds the index of the actor.
696 * If the actor doesn't exist, return the last index + 1.
698 unsigned int FindChildIndex( Actor& actor );
701 * Adds an actor to the hierarchy and prepares it to be transitioned.
702 * @param[in] actor The actor to add
704 void PrepareAddButtonImage( Actor& actor );
707 * Adds an actor to the hierarchy and marks it to be transitioned.
708 * @param[in] actor The actor to add
710 void TransitionButtonImage( Actor& actor );
713 * Adds an actor to the hierarchy.
714 * @param[in] actor The actor to add
716 void AddButtonImage( Actor& actor );
719 * (Re)Adds the label (if exists) to the hierarchy (so it is always on top).
724 Button( const Button& );
727 Button& operator = ( const Button& );
732 Toolkit::Button::ButtonSignalType mPressedSignal; ///< Signal emitted when the button is pressed.
733 Toolkit::Button::ButtonSignalType mReleasedSignal; ///< Signal emitted when the button is released.
734 Toolkit::Button::ButtonSignalType mClickedSignal; ///< Signal emitted when the button is clicked.
735 Toolkit::Button::ButtonSignalType mStateChangedSignal; ///< Signal emitted when the button's state is changed.
737 Timer mAutoRepeatingTimer; ///< Timer used to implement the autorepeating property.
739 Actor mLabel; ///< Stores the button label.
741 Actor mDecoration[ DECORATION_STATES ]; ///< Stores the decorations for both selected and unselected states.
743 Actor mUnselectedContent; ///< Stores the unselected content.
744 Actor mSelectedContent; ///< Stores the selected content.
745 Actor mBackgroundContent; ///< Stores the background content.
746 Actor mSelectedBackgroundContent; ///< Stores the selected background content.
747 Actor mDisabledContent; ///< Stores the disabled content.
748 Actor mDisabledSelectedContent; ///< Stores the disabled selected content.
749 Actor mDisabledBackgroundContent; ///< Stores the disabled background content.
751 Animation mTransitionAnimation; ///< Animation used in the state transitions.
753 TapGestureDetector mTapDetector;
755 Vector4 mUnselectedColor; ///< Color to use for unselected content.
756 Vector4 mSelectedColor; ///< Color to use for selected content.
758 bool mDisabled; ///< Stores the disabled property.
759 bool mAutoRepeating; ///< Stores the autorepeating property.
760 bool mTogglableButton; ///< Stores the togglable property.
761 bool mSelected; ///< Stores the selected state.
762 float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
763 float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
765 float mAnimationTime; ///< The animation time.
768 bool mClickActionPerforming;
770 ButtonState mState; ///< Stores the button state.
771 PaintState mPaintState; ///< Stores the paint state.
774 } // namespace Internal
776 // Helpers for public-api forwarding methods
778 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
780 DALI_ASSERT_ALWAYS( button );
782 Dali::RefObject& handle = button.GetImplementation();
784 return static_cast<Toolkit::Internal::Button&>( handle );
787 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
789 DALI_ASSERT_ALWAYS( button );
791 const Dali::RefObject& handle = button.GetImplementation();
793 return static_cast<const Toolkit::Internal::Button&>( handle );
796 } // namespace Toolkit
800 #endif // __DALI_TOOLKIT_INTERNAL_BUTTON_H__