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 * @copydoc Dali::Toolkit::Button::SetDisabled
51 void SetDisabled( bool disabled );
54 * @copydoc Dali::Toolkit::Button::IsDisabled
56 bool IsDisabled() const;
59 * @copydoc Dali::Toolkit::Button::SetAutoRepeating
61 void SetAutoRepeating( bool autoRepeating );
64 * @copydoc Dali::Toolkit::Button::IsAutoRepeating
66 bool IsAutoRepeating() const;
69 * @copydoc Dali::Toolkit::Button::SetInitialAutoRepeatingDelay
71 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
74 * @copydoc Dali::Toolkit::Button::GetInitialAutoRepeatingDelay
76 float GetInitialAutoRepeatingDelay() const;
79 * @copydoc Dali::Toolkit::Button::SetNextAutoRepeatingDelay
81 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
84 * @copydoc Dali::Toolkit::Button::GetNextAutoRepeatingDelay
86 float GetNextAutoRepeatingDelay() const;
89 * @copydoc Dali::Toolkit::Button::SetTogglableButton
91 void SetTogglableButton( bool togglable );
94 * @copydoc Dali::Toolkit::Button::IsTogglableButton
96 bool IsTogglableButton() const;
99 * @copydoc Dali::Toolkit::Button::SetSelected
101 void SetSelected( bool selected );
104 * @copydoc Dali::Toolkit::Button::IsSelected
106 bool IsSelected() const;
109 * @copydoc Dali::Toolkit::Button::SetAnimationTime
111 void SetAnimationTime( float animationTime );
114 * @copydoc Dali::Toolkit::Button::GetAnimationTime
116 float GetAnimationTime() const;
119 * @copydoc Dali::Toolkit::Button::SetLabelText
121 void SetLabelText( const std::string& label );
124 * @copydoc Dali::Toolkit::Button::GetLabelText
126 std::string GetLabelText() const;
129 * @copydoc Dali::Toolkit::PushButton::SetUnselectedImage
131 void SetUnselectedImage( const std::string& filename );
134 * @copydoc Dali::Toolkit::PushButton::SetSelectedImage
136 void SetSelectedImage( const std::string& filename );
139 * @copydoc Dali::Toolkit::PushButton::SetBackgroundImage
141 void SetBackgroundImage( const std::string& filename );
144 * @copydoc Dali::Toolkit::PushButton::SetSelectedBackgroundImage
146 void SetSelectedBackgroundImage( const std::string& filename );
149 * @copydoc Dali::Toolkit::PushButton::SetDisabledImage
151 void SetDisabledImage( const std::string& filename );
154 * @copydoc Dali::Toolkit::CheckBoxButton::SetDisabledSelectedImage
156 void SetDisabledSelectedImage( const std::string& filename );
159 * @copydoc Dali::Toolkit::PushButton::SetDisabledBackgroundImage
161 void SetDisabledBackgroundImage( const std::string& filename );
164 * @return The filename used for the button image.
166 std::string GetUnselectedImageFilename() const;
169 * @return The filename used for the selected image.
171 std::string GetSelectedImageFilename() const;
174 * @return The filename used for the background image.
176 std::string GetBackgroundImageFilename() const;
179 * @return The filename used for the selected background image.
181 std::string GetSelectedBackgroundImageFilename() const;
184 * @return The filename used for the disabled button image.
186 std::string GetDisabledImageFilename() const;
189 * @return The filename used for the disabled selected image.
191 std::string GetDisabledSelectedImageFilename() const;
194 * @return The filename used for the disabled background image.
196 std::string GetDisabledBackgroundImageFilename() const;
199 * @brief Sets the specified properties on the button label.
200 * If the label does not exist yet, it is created.
201 * The derived buttons are notified if any properties are changed.
202 * @param[in] properties A Property::Map of key-value pairs of properties to set.
204 void ModifyLabel( const Property::Map& properties );
207 * Performs actions as requested using the action name.
208 * @param[in] object The object on which to perform the action.
209 * @param[in] actionName The action to perform.
210 * @param[in] attributes The attributes with which to perfrom this action.
211 * @return true if action has been accepted by this control
213 static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
215 public: // Deprecated API
218 * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
220 void SetLabel( Actor label );
223 * @deprecated Sets the unselected image with an Actor.
224 * @param[in] image The Actor to use.
226 void SetButtonImage( Actor image );
229 * @deprecated Sets the selected image with an Actor.
230 * @param[in] image The Actor to use.
232 void SetSelectedImage( Actor image );
235 * @deprecated Sets the background image with an Actor.
236 * @param[in] image The Actor to use.
238 void SetBackgroundImage( Actor image );
241 * @deprecated Sets the selected background image with an Actor.
242 * @param[in] image The Actor to use.
244 void SetSelectedBackgroundImage( Actor image );
247 * @deprecated Sets the disabled image with an Actor.
248 * @param[in] image The Actor to use.
250 void SetDisabledImage( Actor image );
253 * @deprecated Sets the disabled selected image with an Actor.
254 * @param[in] image The Actor to use.
256 void SetDisabledSelectedImage( Actor image );
259 * @deprecated Sets the disabled background image with an Actor.
260 * @param[in] image The Actor to use.
262 void SetDisabledBackgroundImage( Actor image );
265 * @copydoc Dali::Toolkit::Button::GetButtonImage
267 Actor GetButtonImage() const;
270 * @copydoc Dali::Toolkit::Button::GetSelectedImage
272 Actor GetSelectedImage() const;
278 ButtonUp, ///< The button is up.
279 ButtonDown, ///< The button is down.
283 * Button paint states.
287 UnselectedState, ///< The button is unselected.
288 SelectedState, ///< The button is selected.
289 DisabledUnselectedState, ///< The button is disabled and unselected.
290 DisabledSelectedState, ///< The button is disabled and selected.
294 * Enum to specify which decoration when getting and setting decorations.
298 UNSELECTED_DECORATION = 0,
304 * Construct a new Button.
309 * A reference counted object may only be deleted by calling Unreference()
313 * @return A reference to the label actor.
315 Actor& GetLabelActor();
318 * @return A reference to the unselected button image.
320 Actor& GetUnselectedImage();
323 * @return A reference to the selected image.
325 Actor& GetSelectedImage();
328 * @return A reference to the background image.
330 Actor& GetBackgroundImage();
333 * @return A reference to the selected background image.
335 Actor& GetSelectedBackgroundImage();
338 * @return A reference to the disabled button image.
340 Actor& GetDisabledImage();
343 * @return A reference to the disabled selected image.
345 Actor& GetDisabledSelectedImage();
348 * @return A reference to the disabled background image.
350 Actor& GetDisabledBackgroundImage();
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 label is set.
363 * @param[in] noPadding Used to bypass padding if the label is to be treated generically.
365 virtual void OnLabelSet( bool noPadding ) {}
368 * This method is called when the unselected button image is set
370 virtual void OnUnselectedImageSet() {}
373 * This method is called when the selected image is set
375 virtual void OnSelectedImageSet() {}
378 * This method is called when the background image is set
380 virtual void OnBackgroundImageSet() {}
383 * This method is called when the selected background image is set
385 virtual void OnSelectedBackgroundImageSet() {}
388 * This method is called when the disabled button image is set
390 virtual void OnDisabledImageSet() {}
393 * This method is called when the disabled selected image is set
395 virtual void OnDisabledSelectedImageSet() {}
398 * This method is called when the disabled background image is set
400 virtual void OnDisabledBackgroundImageSet() {}
403 * This method is called the button is down.
404 * Could be reimplemented in subclasses to provide specific behaviour.
406 virtual void OnButtonDown();
409 * This method is called when the button is up.
410 * Could be reimplemented in subclasses to provide specific behaviour.
412 virtual void OnButtonUp();
415 * This method is called when touch leaves the boundary of the button or several touch points are received.
416 * Could be reimplemented in subclasses to provide specific behaviour.
418 virtual void OnTouchPointLeave();
421 * This method is called when the touch is interrupted.
422 * Could be reimplemented in subclasses to provide specific behaviour.
424 virtual void OnTouchPointInterrupted();
427 * This method is called when the \e selected property is changed.
429 virtual void OnSelected() {}
432 * This method is called when the \e disabled property is changed.
434 virtual void OnDisabled() {}
437 * This method is called when the button is pressed.
439 virtual void OnPressed() {}
442 * This method is called when the button is released.
444 virtual void OnReleased() {}
449 * @copydoc Dali::Toolkit::PushButton::PressedSignal()
451 Toolkit::Button::ButtonSignalType& PressedSignal();
454 * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
456 Toolkit::Button::ButtonSignalType& ReleasedSignal();
459 * @copydoc Dali::Toolkit::Button::ClickedSignal()
461 Toolkit::Button::ButtonSignalType& ClickedSignal();
464 * @copydoc Dali::Toolkit::Button::StateChangedSignal()
466 Toolkit::Button::ButtonSignalType& StateChangedSignal();
469 * Connects a callback function with the object's signals.
470 * @param[in] object The object providing the signal.
471 * @param[in] tracker Used to disconnect the signal.
472 * @param[in] signalName The signal to connect to.
473 * @param[in] functor A newly allocated FunctorDelegate.
474 * @return True if the signal was connected.
475 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
477 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
482 * Called when a property of an object of this type is set.
483 * @param[in] object The object whose property is set.
484 * @param[in] index The property index.
485 * @param[in] value The new property value.
487 static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
490 * Called to retrieve a property of an object of this type.
491 * @param[in] object The object whose property is to be retrieved.
492 * @param[in] index The property index.
493 * @return The current value of the property.
495 static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
497 protected: // From Control
500 * @copydoc Toolkit::Control::OnInitialize()
501 * @note If overridden by deriving button classes, then an up-call to Button::OnInitialize MUST be made at the start.
503 virtual void OnInitialize();
506 * @copydoc Toolkit::Control::OnAccessibilityActivated()
508 virtual bool OnAccessibilityActivated();
511 * @copydoc Toolkit::Control::OnKeyboardEnter()
513 virtual bool OnKeyboardEnter();
516 * @copydoc Toolkit::Control::OnStageDisconnection()
517 * @note If overridden by deriving button classes, then an up-call to Button::OnStageDisconnection MUST be made at the end.
519 void OnStageDisconnection();
525 * @brief Handler for touch data
526 * @param[in] actor The touched actor.
527 * @param[in] touch The touch info.
528 * @return true, if consumed, false otherwise.
530 bool OnTouch( Actor actor, const TouchData& touch );
533 * Handler for tap events.
534 * We do not actually do anything when we receive a tap as the button handles tap event through
535 * the touch event system itself as it requires more than just tap handling (e.g. leave events).
536 * This stops any of our parents receiving a tap gesture when it occurs within our area.
537 * @param[in] actor The tapped actor.
538 * @param[in] tap The tap gesture.
540 void OnTap(Actor actor, const TapGesture& tap);
543 * Sets up the autorepeating timer.
544 * @param[in] delay The delay time in seconds.
546 void SetUpTimer( float delay );
549 * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
551 bool AutoRepeatingSlot();
554 * Sets the button as selected or unselected.
555 * @param[in] selected \e selected property value.
556 * @param[in] emitSignal Emit a signal if this value is \e true.
558 void SetSelected( bool selected, bool emitSignal );
561 * This method is called when the button is pressed.
566 * This method is called when the button is released.
571 * Used to perform common setup applied to images within button.
572 * This will replace the current image with the specifed one.
573 * @param[in] actorToModify The image to replace.
574 * @param[out] newActor The new image to use.
576 void SetupContent( Actor& actorToModify, Actor newActor );
579 * Gets the unselected content color.
580 * @return The currently used unselected color.
582 const Vector4 GetUnselectedColor() const;
585 * Sets the color of button in selected or unselected state, if image also supplied this color will be appplied to it.
586 * If no visual exists, it is created.
587 * @param[in] color The color to use.
588 * @param[in] selectedState The state to apply the color to, SelectedState or DisabledUnselectedState.
590 void SetColor( const Vector4& color, PaintState selectedState );
593 * Gets the selected content color.
594 * @return The currently used selected color.
596 const Vector4 GetSelectedColor() const;
600 ButtonState GetState();
601 PaintState GetPaintState();
602 void SetDecoration( DecorationState state, Actor actor );
603 Actor& GetDecoration( DecorationState state );
607 * Returns the animation to be used for transitioning creating the animation if needed.
608 * @return The initialised transition animation.
610 Dali::Animation GetTransitionAnimation();
613 * Prepares the actor to be transitioned in.
614 * @param[in] actor The actor that will be transitioned in.
616 virtual void PrepareForTranstionIn( Actor actor ) {}
619 * Prepares the actor to be transitioned in.
620 * @param[in] actor The actor that will be transitioned out.
622 virtual void PrepareForTranstionOut( Actor actor ) {}
625 * Transitions the actor in, allowing derived classes to configure
626 * the GetTransitionAnimation() animation ready.
627 * Button is in charge of calling Dali::Animation::Play and so derived classes
628 * only need to add the animation.
630 virtual void OnTransitionIn( Actor actor ) {}
633 * Transitions the actor out, allowing derived classes to configure
634 * the GetTransitionAnimation() animation ready.
635 * Button is in charge of calling Dali::Animation::Play and so derived classes
636 * only need to add the animation.
638 virtual void OnTransitionOut( Actor actor ) {}
643 * Starts the transition animation.
644 * Button::TransitionFinished is called when the animation finishes.
646 void StartTransitionAnimation();
649 * This method stops all transition animations
651 void StopTransitionAnimation();
654 * Called when the transition animation finishes.
656 void TransitionAnimationFinished( Dali::Animation& source );
659 * Resets the Button to the base state for the current paint state.
660 * Any additionally inserted images needed for transitions that are
661 * no longer needed and the removed.
663 void ResetImageLayers();
666 * Transitions out the actor
668 void TransitionOut( Actor actor );
671 * Removes the actor from the button and prepares it to be transitioned out
673 void RemoveButtonImage( Actor& actor );
676 * Finds the index of the actor.
677 * If the actor doesn't exist, return the last index + 1.
679 unsigned int FindChildIndex( Actor& actor );
682 * Adds an actor to the hierarchy and prepares it to be transitioned.
683 * @param[in] actor The actor to add
685 void PrepareAddButtonImage( Actor& actor );
688 * Adds an actor to the hierarchy and marks it to be transitioned.
689 * @param[in] actor The actor to add
691 void TransitionButtonImage( Actor& actor );
694 * Adds an actor to the hierarchy.
695 * @param[in] actor The actor to add
697 void AddButtonImage( Actor& actor );
700 * (Re)Adds the label (if exists) to the hierarchy (so it is always on top).
705 Button( const Button& );
708 Button& operator = ( const Button& );
713 Toolkit::Button::ButtonSignalType mPressedSignal; ///< Signal emitted when the button is pressed.
714 Toolkit::Button::ButtonSignalType mReleasedSignal; ///< Signal emitted when the button is released.
715 Toolkit::Button::ButtonSignalType mClickedSignal; ///< Signal emitted when the button is clicked.
716 Toolkit::Button::ButtonSignalType mStateChangedSignal; ///< Signal emitted when the button's state is changed.
718 Timer mAutoRepeatingTimer; ///< Timer used to implement the autorepeating property.
720 Actor mLabel; ///< Stores the button label.
722 Actor mDecoration[ DECORATION_STATES ]; ///< Stores the decorations for both selected and unselected states.
724 Actor mUnselectedContent; ///< Stores the unselected content.
725 Actor mSelectedContent; ///< Stores the selected content.
726 Actor mBackgroundContent; ///< Stores the background content.
727 Actor mSelectedBackgroundContent; ///< Stores the selected background content.
728 Actor mDisabledContent; ///< Stores the disabled content.
729 Actor mDisabledSelectedContent; ///< Stores the disabled selected content.
730 Actor mDisabledBackgroundContent; ///< Stores the disabled background content.
732 Animation mTransitionAnimation; ///< Animation used in the state transitions.
734 TapGestureDetector mTapDetector;
736 Vector4 mUnselectedColor; ///< Color to use for unselected content.
737 Vector4 mSelectedColor; ///< Color to use for selected content.
739 bool mDisabled; ///< Stores the disabled property.
740 bool mAutoRepeating; ///< Stores the autorepeating property.
741 bool mTogglableButton; ///< Stores the togglable property.
742 bool mSelected; ///< Stores the selected state.
743 float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
744 float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
746 float mAnimationTime; ///< The animation time.
749 bool mClickActionPerforming;
751 ButtonState mState; ///< Stores the button state.
752 PaintState mPaintState; ///< Stores the paint state.
755 } // namespace Internal
757 // Helpers for public-api forwarding methods
759 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
761 DALI_ASSERT_ALWAYS( button );
763 Dali::RefObject& handle = button.GetImplementation();
765 return static_cast<Toolkit::Internal::Button&>( handle );
768 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
770 DALI_ASSERT_ALWAYS( button );
772 const Dali::RefObject& handle = button.GetImplementation();
774 return static_cast<const Toolkit::Internal::Button&>( handle );
777 } // namespace Toolkit
781 #endif // __DALI_TOOLKIT_INTERNAL_BUTTON_H__