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/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 * @copydoc Dali::Toolkit::Button::SetDisabled
74 void SetDisabled( bool disabled );
77 * @copydoc Dali::Toolkit::Button::IsDisabled
79 bool IsDisabled() const;
82 * @copydoc Dali::Toolkit::Button::SetAutoRepeating
84 void SetAutoRepeating( bool autoRepeating );
87 * @copydoc Dali::Toolkit::Button::IsAutoRepeating
89 bool IsAutoRepeating() const;
92 * @copydoc Dali::Toolkit::Button::SetInitialAutoRepeatingDelay
94 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
97 * @copydoc Dali::Toolkit::Button::GetInitialAutoRepeatingDelay
99 float GetInitialAutoRepeatingDelay() const;
102 * @copydoc Dali::Toolkit::Button::SetNextAutoRepeatingDelay
104 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
107 * @copydoc Dali::Toolkit::Button::GetNextAutoRepeatingDelay
109 float GetNextAutoRepeatingDelay() const;
112 * @copydoc Dali::Toolkit::Button::SetTogglableButton
114 void SetTogglableButton( bool togglable );
117 * @copydoc Dali::Toolkit::Button::IsTogglableButton
119 bool IsTogglableButton() const;
122 * @copydoc Dali::Toolkit::Button::SetSelected
124 void SetSelected( bool selected );
127 * @copydoc Dali::Toolkit::Button::IsSelected
129 bool IsSelected() const;
132 * @copydoc Dali::Toolkit::Button::SetAnimationTime
134 void SetAnimationTime( float animationTime );
137 * @copydoc Dali::Toolkit::Button::GetAnimationTime
139 float GetAnimationTime() const;
142 * @copydoc Dali::Toolkit::Button::SetLabelText
144 void SetLabelText( const std::string& label );
147 * @copydoc Dali::Toolkit::Button::GetLabelText
149 std::string GetLabelText() const;
152 * @brief Produces a Property::Map of Text properties to create a Text Visual, merging existing properties with supplied map
153 * If the label does not exist yet, it is created.
154 * The derived buttons are notified if any properties are changed.
155 * @param[in] properties A Property::Map of key-value pairs of properties to set.
156 * @param[out] properties A Property::Map of text visual properties to set after merging inMap with existing maps
158 void MergeWithExistingLabelProperties( const Property::Map& inMap, Property::Map& outMap );
161 * Performs actions as requested using the action name.
162 * @param[in] object The object on which to perform the action.
163 * @param[in] actionName The action to perform.
164 * @param[in] attributes The attributes with which to perfrom this action.
165 * @return true if action has been accepted by this control
167 static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
169 public: // Deprecated API
172 * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
174 void SetLabel( Actor label );
177 * @deprecated Sets the unselected image with an url.
178 * @param[in] image The Actor to use.
180 void SetUnselectedImage( const std::string& filename );
183 * @deprecated Sets the selected image with an url.
184 * @param[in] filename The url of the image to use to use.
186 void SetSelectedImage( const std::string& filename );
189 * @deprecated Sets the selected background image with an url.
190 * @param[in] filename The url of the image to use to use.
192 void SetSelectedBackgroundImage( const std::string& filename );
195 * @deprecated Sets the background image with an url.
196 * @param[in] filename The url of the image to use to use.
198 void SetBackgroundImage( const std::string& filename );
201 * @deprecated Sets the disabled unselected background image with an url.
202 * @param[in] filename The url of the image to use to use.
204 void SetDisabledBackgroundImage( const std::string& filename );
207 * @deprecated Sets the disabled unselected image with an url.
208 * @param[in] filename The url of the image to use to use.
210 void SetDisabledImage( const std::string& filename );
213 * @deprecated Sets the disabled selected image with an url.
214 * @param[in] filename The url of the image to use to use.
216 void SetDisabledSelectedImage( const std::string& filename );
219 * @deprecated Sets the unselected image with an Actor.
220 * @param[in] image The Image to use.
222 void SetButtonImage( Image image );
225 * @deprecated Sets the selected image with an Actor.
226 * @param[in] image The Image to use.
228 void SetSelectedImage( Image image );
231 * @Gets url of a image visual, used by GetProperty but for deprecated Properties
232 * @param[in] index Visual index of url required
233 * @return filename for the corresponding visual
235 std::string GetUrlForImageVisual( const Property::Index index ) const;
238 * @copydoc Dali::Toolkit::Button::GetButtonImage
240 Actor GetButtonImage() const;
243 * @copydoc Dali::Toolkit::Button::GetSelectedImage
245 Actor GetSelectedImage() const;
254 UNSELECTED_STATE, ///< The button is unselected.
255 SELECTED_STATE, ///< The button is selected.
256 DISABLED_UNSELECTED_STATE, ///< The button is disabled and unselected.
257 DISABLED_SELECTED_STATE, ///< The button is disabled and selected.
258 STATE_COUNT, ///< Number of States
262 * Enum to distinguish the different style-able components of the button
266 UNSELECTED_FOREGROUND = 0,
268 DISABLED_SELECTED_FOREGROUND,
269 DISABLED_UNSELECTED_FOREGROUND,
270 UNSELECTED_BACKGROUND,
272 DISABLED_UNSELECTED_BACKGROUND,
273 DISABLED_SELECTED_BACKGROUND,
278 * Enum to list types of visual a state can have.
290 * Button press state which is not the same as the actual button's state.
291 * For example An UNSELECTED button can be DEPRESSED, but until released, the actual button state doesn't change to SELECTED
295 DEPRESSED, ///< The button is up.
296 UNPRESSED, ///< The button is down.
297 TOGGLE_DEPRESSED, ///< The button has been pressed down and will stay depressed when released.
301 * Construct a new Button.
306 * A reference counted object may only be deleted by calling Unreference()
310 * @return A reference to the label actor.
312 Actor& GetLabelActor();
315 * @return A reference to the unselected button image.
317 Actor GetUnselectedImage();
320 * @return A reference to the selected image.
322 Actor GetSelectedImage();
327 * Perform the click action to click the button.
328 * @param[in] attributes The attributes to perfrom this action.
329 * @return true if this control can perform action.
331 bool DoClickAction( const Property::Map& attributes );
334 * This method is called when the button is a Toggle button and released
335 * Could be reimplemented in subclasses to provide specific behaviour.
336 * @return bool returns true if state changed.
338 virtual bool OnToggleReleased();
341 * This method is called when touch leaves the boundary of the button or several touch points are received.
342 * Could be reimplemented in subclasses to provide specific behaviour.
344 virtual void OnTouchPointLeave();
347 * This method is called when the touch is interrupted.
348 * Could be reimplemented in subclasses to provide specific behaviour.
350 virtual void OnTouchPointInterrupted();
353 * This method is called when the \e selected property is changed.
355 virtual void OnStateChange( State newState ){}
358 * This method is called when the \e disabled property is changed.
360 virtual void OnDisabled() {}
363 * This method is called when the button is pressed.
365 virtual void OnPressed() {}
368 * This method is called when the button is released.
370 virtual void OnReleased() {}
375 * @copydoc Dali::Toolkit::PushButton::PressedSignal()
377 Toolkit::Button::ButtonSignalType& PressedSignal();
380 * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
382 Toolkit::Button::ButtonSignalType& ReleasedSignal();
385 * @copydoc Dali::Toolkit::Button::ClickedSignal()
387 Toolkit::Button::ButtonSignalType& ClickedSignal();
390 * @copydoc Dali::Toolkit::Button::StateChangedSignal()
392 Toolkit::Button::ButtonSignalType& StateChangedSignal();
395 * Connects a callback function with the object's signals.
396 * @param[in] object The object providing the signal.
397 * @param[in] tracker Used to disconnect the signal.
398 * @param[in] signalName The signal to connect to.
399 * @param[in] functor A newly allocated FunctorDelegate.
400 * @return True if the signal was connected.
401 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
403 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
408 * Called when a property of an object of this type is set.
409 * @param[in] object The object whose property is set.
410 * @param[in] index The property index.
411 * @param[in] value The new property value.
413 static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
416 * Called to retrieve a property of an object of this type.
417 * @param[in] object The object whose property is to be retrieved.
418 * @param[in] index The property index.
419 * @return The current value of the property.
421 static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
423 protected: // From Control
426 * @copydoc Toolkit::Control::OnInitialize()
427 * @note If overridden by deriving button classes, then an up-call to Button::OnInitialize MUST be made at the start.
429 virtual void OnInitialize();
432 * @copydoc Toolkit::Control::OnAccessibilityActivated()
434 virtual bool OnAccessibilityActivated();
437 * @copydoc Toolkit::Control::OnKeyboardEnter()
439 virtual bool OnKeyboardEnter();
442 * @copydoc Toolkit::Control::OnStageDisconnection()
443 * @note If overridden by deriving button classes, then an up-call to Button::OnStageDisconnection MUST be made at the end.
445 virtual void OnStageDisconnection();
448 * @copydoc Toolkit::Control::OnStageConnnection()
450 virtual void OnStageConnection( int depth );
453 * @copydoc Toolkit::Control::GetNaturalSize
455 virtual Vector3 GetNaturalSize();
458 * @copydoc Toolkit::Control::OnSetResizePolicy
460 virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension );
463 * @copydoc Toolkit::Control::OnRelayout
465 virtual void OnRelayout( const Vector2& size, RelayoutContainer& container );
470 * @brief Handler for touch data
471 * @param[in] actor The touched actor.
472 * @param[in] touch The touch info.
473 * @return true, if consumed, false otherwise.
475 bool OnTouch( Actor actor, const TouchData& touch );
478 * Handler for tap events.
479 * We do not actually do anything when we receive a tap as the button handles tap event through
480 * the touch event system itself as it requires more than just tap handling (e.g. leave events).
481 * This stops any of our parents receiving a tap gesture when it occurs within our area.
482 * @param[in] actor The tapped actor.
483 * @param[in] tap The tap gesture.
485 void OnTap(Actor actor, const TapGesture& tap);
488 * Sets up the autorepeating timer.
489 * @param[in] delay The delay time in seconds.
491 void SetUpTimer( float delay );
494 * Button has been pressed
499 * This method is called the button is down.
504 * This method is called when the button is up.
509 * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
511 bool AutoRepeatingSlot();
514 * Check the requested state is an allowed transition.
515 * Some states can not be transitioned to from certain states.
516 * @param[in] requestedState check if can transition to this state
517 * @return bool true if state change valid
519 bool ValidateState( State requestedState );
522 * Perform the given function on the visuals in the given state. Can be used to add and remove visuals.
523 * @param[in] functionPtr pointer to the function to perform an action on a visual
524 * @param[in] state Visuals in this state will be the target
526 void PerformFunctionOnVisualsInState( void(Button::*functionPtr)( Property::Index visualIndex), State state );
529 * Changes the button state when an action occurs on it
530 * @param[in] requestedState the state to change to
532 void ChangeState( State requestedState );
535 * @brief Get unselected button color
536 * @return color as vector4
538 const Vector4 GetUnselectedColor() const;
541 * @brief Get selected button color
542 * @return color as vector4
544 const Vector4 GetSelectedColor() const;
547 * Sets the color of button in selected or unselected state, if image also supplied this color will be appplied to it.
548 * If no visual exists, it is created.
549 * @param[in] color The color to use.
550 * @param[in] visualIndex The Visual to apply the color
552 void SetColor( const Vector4& color, Property::Index visualIndex );
555 * This method is called when the button is released.
562 * Set Text Label Padding
563 * @param[in] padding BEGIN END BOTTOM TOP
565 void SetLabelPadding( const Padding& padding );
568 * Get Text Label padding
571 Padding GetLabelPadding();
574 * Set Foreground/icon Padding
575 * @param[in] padding BEGIN END BOTTOM TOP
577 void SetForegroundPadding( const Padding& padding);
580 * Get Foreground padding
583 Padding GetForegroundPadding();
586 * @brief Setup the button components for example foregrounds and background
587 * @param[in] index the index of the visual to set
588 * @param[in] value the value to set on the component
589 * @param[in] visualDepth the depth of the visual if overlapping another
591 void CreateVisualsForComponent( Property::Index index ,const Property::Value& value, const float visualDepth );
594 * @brief Get the Property map for the given Visual
595 * @param[in] visualIndex visual index of the required visual
596 * @param[out] retreivedMap the property map used to construct the required visual
597 * @return bool success flag, true if visual found
599 bool GetPropertyMapForVisual( Property::Index visualIndex, Property::Map& retreivedMap ) const;
601 * Returns the animation to be used for transition, creating the animation if needed.
602 * @return The initialised transition animation.
604 Dali::Animation GetTransitionAnimation();
607 * @brief Set the position of the label relative to foreground/icon, if both present
608 * @param[in] labelAlignment given alignment setting
610 void SetLabelAlignment( Align labelAlignment);
613 * @brief Get set alignment of label in relation to foreground/icon
614 * @return Set alignment value
616 Align GetLabelAlignment();
619 * Removes the visual from the button (un-staged)
620 * If the derived button does not want the visual removed then use this virtual function to
621 * define the required behaviour.
622 * Can decide to only remove specified visuals via index
624 virtual void OnButtonVisualRemoval( Property::Index visualIndex );
630 * Removes the visual from the button and prepares it to be transitioned out
631 * @param[in] visualIndex the visual to remove
633 void RemoveVisual( Property::Index visualIndex );
636 * Adds the required visual to the button.
637 * @param[in] visualIndex The Property index of the visual required
639 void SelectRequiredVisual( Property::Index visualIndex );
642 Button( const Button& );
645 Button& operator = ( const Button& );
650 Toolkit::Button::ButtonSignalType mPressedSignal; ///< Signal emitted when the button is pressed.
651 Toolkit::Button::ButtonSignalType mReleasedSignal; ///< Signal emitted when the button is released.
652 Toolkit::Button::ButtonSignalType mClickedSignal; ///< Signal emitted when the button is clicked.
653 Toolkit::Button::ButtonSignalType mStateChangedSignal; ///< Signal emitted when the button's state is changed.
655 Timer mAutoRepeatingTimer;
657 Actor mLabel; ///< Stores the button text label.
658 Padding mLabelPadding; ///< The padding around the label (if present).
659 Padding mForegroundPadding; ///< The padding around the foreground/icon visual (if present).
661 Align mTextLabelAlignment; ///< Position of text label in relation to foreground/icon when both are present.
663 TapGestureDetector mTapDetector;
665 Vector4 mUnselectedColor;
666 Vector4 mSelectedColor;
668 bool mAutoRepeating; ///< Stores the autorepeating property.
669 bool mTogglableButton; ///< Stores the togglable property as a flag.
670 bool mTextStringSetFlag; ///< Stores if text has been set. Required in relayout but don't want to calculate there.
672 float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
673 float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
675 float mAnimationTime;
677 PressState mButtonPressedState; ///< In relation to the button being pressed/released
679 State mPreviousButtonState; ///< During a transition between two states, this stores the previous state so Visuals can be removed.
682 bool mClickActionPerforming; ///< Used to manage signal emissions during action
685 } // namespace Internal
687 // Helpers for public-api forwarding methods
689 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
691 DALI_ASSERT_ALWAYS( button );
693 Dali::RefObject& handle = button.GetImplementation();
695 return static_cast<Toolkit::Internal::Button&>( handle );
698 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
700 DALI_ASSERT_ALWAYS( button );
702 const Dali::RefObject& handle = button.GetImplementation();
704 return static_cast<const Toolkit::Internal::Button&>( handle );
707 } // namespace Toolkit
711 #endif // DALI_TOOLKIT_INTERNAL_BUTTON_H