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( bool disabled )
63 void SetDisabled( bool disabled );
66 * @copydoc Dali::Toolkit::Button::IsDisabled() const
68 bool IsDisabled() const;
71 * @copydoc Dali::Toolkit::Button::SetAutoRepeating( bool autoRepeating )
73 void SetAutoRepeating( bool autoRepeating );
76 * @copydoc Dali::Toolkit::Button::IsAutoRepeating() const
78 bool IsAutoRepeating() const;
81 * @copydoc Dali::Toolkit::Button::SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay )
83 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
86 * @copydoc Dali::Toolkit::Button::GetInitialAutoRepeatingDelay() const
88 float GetInitialAutoRepeatingDelay() const;
91 * @copydoc Dali::Toolkit::Button::SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay )
93 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
96 * @copydoc Dali::Toolkit::Button::GetNextAutoRepeatingDelay() const
98 float GetNextAutoRepeatingDelay() const;
101 * @copydoc Dali::Toolkit::Button::SetTogglableButton( bool togglable )
103 void SetTogglableButton( bool togglable );
106 * @copydoc Dali::Toolkit::Button::IsTogglableButton() const
108 bool IsTogglableButton() const;
111 * @copydoc Dali::Toolkit::Button::SetSelected( bool selected )
113 void SetSelected( bool selected );
116 * @copydoc Dali::Toolkit::Button::IsSelected() const
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::SetLabel( const std::string& label )
133 void SetLabel( const std::string& label );
136 * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
138 void SetLabel( Actor label );
141 * @copydoc Dali::Toolkit::Button::GetLabel()
143 Actor GetLabel() const;
146 * @copydoc Dali::Toolkit::PushButton::SetButtonImage( Actor image )
148 void SetButtonImage( Actor image );
151 * @copydoc Dali::Toolkit::PushButton::GetButtonImage()
153 Actor GetButtonImage() const;
157 * @return A reference to the button image.
159 Actor& GetButtonImage();
162 * @copydoc Dali::Toolkit::PushButton::SetSelectedImage( Actor image )
164 void SetSelectedImage( Actor image );
167 * @copydoc Dali::Toolkit::PushButton::GetSelectedImage()
169 Actor GetSelectedImage() const;
173 * @return A reference to the selected image.
175 Actor& GetSelectedImage();
178 * @copydoc Dali::Toolkit::PushButton::SetBackgroundImage( Actor image )
180 void SetBackgroundImage( Actor image );
183 * @copydoc Dali::Toolkit::PushButton::GetBackgroundImage()
185 Actor GetBackgroundImage() const;
189 * @return A reference to the background image.
191 Actor& GetBackgroundImage();
194 * @copydoc Dali::Toolkit::PushButton::SetSelectedBackgroundImage( Actor image )
196 void SetSelectedBackgroundImage( Actor image );
199 * @copydoc Dali::Toolkit::PushButton::GetSelectedBackgroundImage()
201 Actor GetSelectedBackgroundImage() const;
205 * @return A reference to the selected background image.
207 Actor& GetSelectedBackgroundImage();
210 * @copydoc Dali::Toolkit::PushButton::SetDisabledImage( Actor image )
212 void SetDisabledImage( Actor image );
215 * @copydoc Dali::Toolkit::PushButton::GetDisabledImage()
217 Actor GetDisabledImage() const;
221 * @return A reference to the disabled button image.
223 Actor& GetDisabledImage();
226 * @copydoc Dali::Toolkit::CheckBoxButton::SetDisabledSelectedImage( Actor image )
228 void SetDisabledSelectedImage( Actor image );
231 * @copydoc Dali::Toolkit::CheckBoxButton::GetDisabledSelectedImage()
233 Actor GetDisabledSelectedImage() const;
237 * @return A reference to the disabled selected image.
239 Actor& GetDisabledSelectedImage();
242 * @copydoc Dali::Toolkit::PushButton::SetDisabledBackgroundImage( Actor image )
244 void SetDisabledBackgroundImage( Actor image );
247 * @copydoc Dali::Toolkit::PushButton::GetDisabledBackgroundImage()
249 Actor GetDisabledBackgroundImage() const;
253 * @return A reference to the disabled background image.
255 Actor& GetDisabledBackgroundImage();
258 * Performs actions as requested using the action name.
259 * @param[in] object The object on which to perform the action.
260 * @param[in] actionName The action to perform.
261 * @param[in] attributes The attributes with which to perfrom this action.
262 * @return true if action has been accepted by this control
264 static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
269 * @return A reference to the label actor.
276 * Perform the click action to click the button.
277 * @param[in] attributes The attributes to perfrom this action.
278 * @return true if this control can perform action.
280 bool DoClickAction( const Property::Map& attributes );
283 * This method is called after the button initialization.
284 * Could be reimplemented in subclasses to provide specific behaviour.
286 virtual void OnButtonInitialize() { }
289 * This method is called when the label is set.
291 virtual void OnLabelSet() {}
294 * This method is called when the button image is set
296 virtual void OnButtonImageSet() {}
299 * This method is called when the selected image is set
301 virtual void OnSelectedImageSet() {}
304 * This method is called when the background image is set
306 virtual void OnBackgroundImageSet() {}
309 * This method is called when the selected background image is set
311 virtual void OnSelectedBackgroundImageSet() {}
314 * This method is called when the disabled button image is set
316 virtual void OnDisabledImageSet() {}
319 * This method is called when the disabled selected image is set
321 virtual void OnDisabledSelectedImageSet() {}
324 * This method is called when the disabled background image is set
326 virtual void OnDisabledBackgroundImageSet() {}
329 * This method is called from the OnTouchEvent method when the button is down.
330 * Could be reimplemented in subclasses to provide specific behaviour.
332 virtual void OnButtonDown();
335 * This method is called from the OnTouchEvent method when the button is up.
336 * Could be reimplemented in subclasses to provide specific behaviour.
338 virtual void OnButtonUp();
341 * This method is called from the OnTouchEvent method when the touch point leaves the boundary of the button or
342 * more than one touch points are received.
343 * Could be reimplemented in subclasses to provide specific behaviour.
345 virtual void OnTouchPointLeave();
348 * This method is called from the OnTouchEvent method when the touch point is interrupted.
349 * Could be reimplemented in subclasses to provide specific behaviour.
351 virtual void OnTouchPointInterrupted();
354 * This method is called when the button is removed from the stage.
355 * Could be reimplemented in subclasses to provide specific behaviour.
357 virtual void OnButtonStageDisconnection();
360 * This method is called when the \e selected property is changed.
362 virtual void OnSelected() {}
365 * This method is called when the \e disabled property is changed.
367 virtual void OnDisabled() {}
370 * This method is called when the button is pressed.
372 virtual void OnPressed() {}
375 * This method is called when the button is released.
377 virtual void OnReleased() {}
382 * @copydoc Dali::Toolkit::PushButton::PressedSignal()
384 Toolkit::Button::ButtonSignalType& PressedSignal();
387 * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
389 Toolkit::Button::ButtonSignalType& ReleasedSignal();
392 * @copydoc Dali::Toolkit::Button::ClickedSignal()
394 Toolkit::Button::ButtonSignalType& ClickedSignal();
397 * @copydoc Dali::Toolkit::Button::StateChangedSignal()
399 Toolkit::Button::ButtonSignalType& StateChangedSignal();
402 * Connects a callback function with the object's signals.
403 * @param[in] object The object providing the signal.
404 * @param[in] tracker Used to disconnect the signal.
405 * @param[in] signalName The signal to connect to.
406 * @param[in] functor A newly allocated FunctorDelegate.
407 * @return True if the signal was connected.
408 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
410 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
415 * Called when a property of an object of this type is set.
416 * @param[in] object The object whose property is set.
417 * @param[in] index The property index.
418 * @param[in] value The new property value.
420 static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
423 * Called to retrieve a property of an object of this type.
424 * @param[in] object The object whose property is to be retrieved.
425 * @param[in] index The property index.
426 * @return The current value of the property.
428 static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
430 protected: // From CustomActorImpl
433 * @copydoc Dali::CustomActorImpl::OnTouchEvent( const TouchEvent& event )
435 virtual bool OnTouchEvent( const TouchEvent& event );
437 private: // From Control
440 * @copydoc Toolkit::Control::OnInitialize()
442 virtual void OnInitialize();
445 * @copydoc Toolkit::Control::OnAccessibilityActivated()
447 virtual bool OnAccessibilityActivated();
450 * @copydoc Toolkit::Control::OnKeyboardEnter()
452 virtual bool OnKeyboardEnter();
455 * Callback received when the button is disconnected from the stage.
456 * It resets the button status.
458 void OnControlStageDisconnection();
463 * Handler for tap events.
464 * We do not actually do anything when we receive a tap as the button handles tap event through
465 * the touch event system itself as it requires more than just tap handling (e.g. leave events).
466 * This stops any of our parents receiving a tap gesture when it occurs within our area.
467 * @param[in] actor The tapped actor.
468 * @param[in] tap The tap gesture.
470 void OnTap(Actor actor, const TapGesture& tap);
473 * Sets up the autorepeating timer.
474 * @param[in] delay The delay time in seconds.
476 void SetUpTimer( float delay );
479 * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
481 bool AutoRepeatingSlot();
484 * Sets the button as selected or unselected.
485 * @param[in] selected \e selected property value.
486 * @param[in] emitSignal Emit a signal if this value is \e true.
488 void SetSelected( bool selected, bool emitSignal );
491 * This method is called when the button is pressed.
496 * This method is called when the button is released.
504 ButtonUp, ///< The button is up.
505 ButtonDown, ///< The button is down.
509 * Button paint states.
513 UnselectedState, ///< The button is unselected.
514 SelectedState, ///< The button is selected.
515 DisabledUnselectedState, ///< The button is disabled and unselected.
516 DisabledSelectedState, ///< The button is disabled and selected.
519 ButtonState GetState();
520 PaintState GetPaintState();
523 * Returns the animation to be used for transitioning creating the animation if needed.
524 * @return The initialised transition animation.
526 Dali::Animation GetTransitionAnimation();
529 * Prepares the actor to be transitioned in.
530 * @param[in] actor The actor that will be transitioned in.
532 virtual void PrepareForTranstionIn( Actor actor ) {}
535 * Prepares the actor to be transitioned in.
536 * @param[in] actor The actor that will be transitioned out.
538 virtual void PrepareForTranstionOut( Actor actor ) {}
541 * Transitions the actor in, allowing derived classes to configure
542 * the GetTransitionAnimation() animation ready.
543 * Button is in charge of calling Dali::Animation::Play and so derived classes
544 * only need to add the animation.
546 virtual void OnTransitionIn( Actor actor ) {}
549 * Transitions the actor out, allowing derived classes to configure
550 * the GetTransitionAnimation() animation ready.
551 * Button is in charge of calling Dali::Animation::Play and so derived classes
552 * only need to add the animation.
554 virtual void OnTransitionOut( Actor actor ) {}
558 * Starts the transition animation.
559 * Button::TransitionFinished is called when the animation finishes.
561 void StartTransitionAnimation();
564 * This method stops all transition animations
566 void StopTransitionAnimation();
569 * Called when the transition animation finishes.
571 void TransitionAnimationFinished( Dali::Animation& source );
574 * Resets the Button to the base state for the current paint state.
575 * Any additionally inserted images needed for transitions that are
576 * no longer needed and the removed.
578 void ResetImageLayers();
581 * Transitions out the actor
583 void TransitionOut( Actor actor );
586 * Removes the actor from the button and prepares it to be transitioned out
588 void RemoveButtonImage( Actor& actor );
591 * Finds the index of the actor.
592 * If the actor doesn't exist, return the last index + 1.
594 unsigned int FindChildIndex( Actor& actor );
597 * Adds an actor to the hierarchy and prepares it to be transitioned.
598 * @param[in] actor The actor to add
600 void PrepareAddButtonImage( Actor& actor );
603 * Adds an actor to the hierarchy and marks it to be transitioned.
604 * @param[in] actor The actor to add
606 void TransitionButtonImage( Actor& actor );
609 * Adds an actor to the hierarchy.
610 * @param[in] actor The actor to add
612 void AddButtonImage( Actor& actor );
615 * (Re)Adds the label (if exists) to the hierarchy (so it is always on top).
620 Button( const Button& );
623 Button& operator = ( const Button& );
628 Toolkit::Button::ButtonSignalType mPressedSignal; ///< Signal emitted when the button is pressed.
629 Toolkit::Button::ButtonSignalType mReleasedSignal; ///< Signal emitted when the button is released.
630 Toolkit::Button::ButtonSignalType mClickedSignal; ///< Signal emitted when the button is clicked.
631 Toolkit::Button::ButtonSignalType mStateChangedSignal; ///< Signal emitted when the button's state is changed.
633 Timer mAutoRepeatingTimer; ///< Timer used to implement the autorepeating property.
635 Actor mLabel; ///< Stores the button label.
637 Actor mUnselectedContent; ///< Stores the unselected content.
638 Actor mSelectedContent; ///< Stores the selected content.
639 Actor mBackgroundContent; ///< Stores the background content.
640 Actor mSelectedBackgroundContent; ///< Stores the selected background content.
641 Actor mDisabledContent; ///< Stores the disabled content.
642 Actor mDisabledSelectedContent; ///< Stores the disabled selected content.
643 Actor mDisabledBackgroundContent; ///< Stores the disabled background content.
645 Animation mTransitionAnimation; ///< Animation used in the state transitions.
647 TapGestureDetector mTapDetector;
649 bool mDisabled; ///< Stores the disabled property.
650 bool mAutoRepeating; ///< Stores the autorepeating property.
651 bool mTogglableButton; ///< Stores the togglable property.
652 bool mSelected; ///< Stores the selected state.
653 float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
654 float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
656 float mAnimationTime; ///< The animation time.
659 bool mClickActionPerforming;
661 ButtonState mState; ///< Stores the button state.
662 PaintState mPaintState; ///< Stores the paint state.
665 } // namespace Internal
667 // Helpers for public-api forwarding methods
669 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
671 DALI_ASSERT_ALWAYS( button );
673 Dali::RefObject& handle = button.GetImplementation();
675 return static_cast<Toolkit::Internal::Button&>( handle );
678 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
680 DALI_ASSERT_ALWAYS( button );
682 const Dali::RefObject& handle = button.GetImplementation();
684 return static_cast<const Toolkit::Internal::Button&>( handle );
687 } // namespace Toolkit
691 #endif // __DALI_TOOLKIT_INTERNAL_BUTTON_H__