-#ifndef __DALI_TOOLKIT_INTERNAL_BUTTON_H__
-#define __DALI_TOOLKIT_INTERNAL_BUTTON_H__
+#ifndef DALI_TOOLKIT_INTERNAL_BUTTON_H
+#define DALI_TOOLKIT_INTERNAL_BUTTON_H
/*
* Copyright (c) 2014 Samsung Electronics Co., Ltd.
#include <dali/public-api/animation/animation.h>
// INTERNAL INCLUDES
+#include <dali-toolkit/devel-api/visual-factory/visual-base.h>
#include <dali-toolkit/public-api/controls/buttons/button.h>
#include <dali-toolkit/public-api/controls/control-impl.h>
+//#if defined(DEBUG_ENABLED)
+// Debug::Filter* gLogButtonFilter = Debug::Filter::New(Debug::NoLogging, true, "LOG_BUTTON_CONTROL");
+//#endif
+
namespace Dali
{
{
/**
+ * @copydoc Toolkit::Button
+ *
* Button is the base class implementation for all buttons.
+ *
+ * @note
+ *
+ * All Foreground/Icon visuals expected to be the same size.
+ * Background visuals will take the size of the control.
+ * Padding and struts take size precedence over visuals when available space is limited.
+ * Icon/Foreground visuals take size precedence over Labels when available space is limited.
*/
class Button : public Control
{
public:
/**
+ * Enum describing the position the text label can be in relation to the control (and foreground/icon)
+ */
+ enum Align
+ {
+ BEGIN, // At the start of the control before the foreground/icon
+ END, // At the end of the control after the foreground/icon
+ TOP, // At the top of the control above the foreground/icon
+ BOTTOM // At the bottom of the control below the foreground/icon
+ };
+
+public:
+
+ /**
* @copydoc Dali::Toolkit::Button::SetDisabled
*/
void SetDisabled( bool disabled );
std::string GetLabelText() const;
/**
- * @copydoc Dali::Toolkit::PushButton::SetUnselectedImage
- */
- void SetUnselectedImage( const std::string& filename );
-
- /**
- * @copydoc Dali::Toolkit::PushButton::SetSelectedImage
- */
- void SetSelectedImage( const std::string& filename );
-
- /**
- * @copydoc Dali::Toolkit::PushButton::SetBackgroundImage
- */
- void SetBackgroundImage( const std::string& filename );
-
- /**
- * @copydoc Dali::Toolkit::PushButton::SetSelectedBackgroundImage
- */
- void SetSelectedBackgroundImage( const std::string& filename );
-
- /**
- * @copydoc Dali::Toolkit::PushButton::SetDisabledImage
- */
- void SetDisabledImage( const std::string& filename );
-
- /**
- * @copydoc Dali::Toolkit::CheckBoxButton::SetDisabledSelectedImage
- */
- void SetDisabledSelectedImage( const std::string& filename );
-
- /**
- * @copydoc Dali::Toolkit::PushButton::SetDisabledBackgroundImage
+ * @brief Sets the specified properties on the button label.
+ * If the label does not exist yet, it is created.
+ * The derived buttons are notified if any properties are changed.
+ * @param[in] properties A Property::Map of key-value pairs of properties to set.
*/
- void SetDisabledBackgroundImage( const std::string& filename );
+ void SetupLabel( const Property::Map& properties );
/**
- * @return The filename used for the button image.
+ * Performs actions as requested using the action name.
+ * @param[in] object The object on which to perform the action.
+ * @param[in] actionName The action to perform.
+ * @param[in] attributes The attributes with which to perfrom this action.
+ * @return true if action has been accepted by this control
*/
- std::string GetUnselectedImageFilename() const;
+ static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
- /**
- * @return The filename used for the selected image.
- */
- std::string GetSelectedImageFilename() const;
+public: // Deprecated API
/**
- * @return The filename used for the background image.
+ * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
*/
- std::string GetBackgroundImageFilename() const;
+ void SetLabel( Actor label );
/**
- * @return The filename used for the selected background image.
+ * @deprecated Sets the unselected image with an url.
+ * @param[in] image The Actor to use.
*/
- std::string GetSelectedBackgroundImageFilename() const;
+ void SetUnselectedImage( const std::string& filename );
/**
- * @return The filename used for the disabled button image.
+ * @deprecated Sets the selected image with an url.
+ * @param[in] filename The url of the image to use to use.
*/
- std::string GetDisabledImageFilename() const;
+ void SetSelectedImage( const std::string& filename );
/**
- * @return The filename used for the disabled selected image.
+ * @deprecated Sets the selected background image with an url.
+ * @param[in] filename The url of the image to use to use.
*/
- std::string GetDisabledSelectedImageFilename() const;
+ void SetSelectedBackgroundImage( const std::string& filename );
/**
- * @return The filename used for the disabled background image.
+ * @deprecated Sets the background image with an url.
+ * @param[in] filename The url of the image to use to use.
*/
- std::string GetDisabledBackgroundImageFilename() const;
+ void SetBackgroundImage( const std::string& filename );
/**
- * @brief Sets the specified properties on the button label.
- * If the label does not exist yet, it is created.
- * The derived buttons are notified if any properties are changed.
- * @param[in] properties A Property::Map of key-value pairs of properties to set.
+ * @deprecated Sets the disabled unselected background image with an url.
+ * @param[in] filename The url of the image to use to use.
*/
- void ModifyLabel( const Property::Map& properties );
+ void SetDisabledBackgroundImage( const std::string& filename );
/**
- * Performs actions as requested using the action name.
- * @param[in] object The object on which to perform the action.
- * @param[in] actionName The action to perform.
- * @param[in] attributes The attributes with which to perfrom this action.
- * @return true if action has been accepted by this control
+ * @deprecated Sets the disabled unselected image with an url.
+ * @param[in] filename The url of the image to use to use.
*/
- static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
-
-public: // Deprecated API
+ void SetDisabledImage( const std::string& filename );
/**
- * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
+ * @deprecated Sets the disabled selected image with an url.
+ * @param[in] filename The url of the image to use to use.
*/
- void SetLabel( Actor label );
+ void SetDisabledSelectedImage( const std::string& filename );
/**
* @deprecated Sets the unselected image with an Actor.
* @param[in] image The Actor to use.
*/
- void SetButtonImage( Actor image );
+ void SetUnselectedImage( Actor image );
/**
* @deprecated Sets the selected image with an Actor.
void SetSelectedImage( Actor image );
/**
- * @deprecated Sets the background image with an Actor.
- * @param[in] image The Actor to use.
- */
- void SetBackgroundImage( Actor image );
-
- /**
* @deprecated Sets the selected background image with an Actor.
* @param[in] image The Actor to use.
*/
void SetDisabledBackgroundImage( Actor image );
/**
+ * @Gets url of a image visual, used by GetProperty but for deprecated Properties
+ * @param[in] index Visual index of url required
+ * @return filename for the corresponding visual
+ */
+ std::string GetUrlForImageVisual( Property::Index index );
+
+
+ /**
* @copydoc Dali::Toolkit::Button::GetButtonImage
*/
Actor GetButtonImage() const;
*/
Actor GetSelectedImage() const;
-protected:
+public:
- enum ButtonState
+ /**
+ * Button's state
+ */
+ enum State
{
- ButtonUp, ///< The button is up.
- ButtonDown, ///< The button is down.
+ UNSELECTED_STATE, ///< The button is unselected.
+ SELECTED_STATE, ///< The button is selected.
+ DISABLED_UNSELECTED_STATE, ///< The button is disabled and unselected.
+ DISABLED_SELECTED_STATE, ///< The button is disabled and selected.
+ STATE_COUNT, ///< Number of States
};
/**
- * Button paint states.
+ * Enum to distinguish the different style-able components of the button
*/
- enum PaintState
+ enum Visuals
{
- UnselectedState, ///< The button is unselected.
- SelectedState, ///< The button is selected.
- DisabledUnselectedState, ///< The button is disabled and unselected.
- DisabledSelectedState, ///< The button is disabled and selected.
+ UNSELECTED_FOREGROUND = 0,
+ SELECTED_FOREGROUND,
+ DISABLED_SELECTED_FOREGROUND,
+ DISABLED_UNSELECTED_FOREGROUND,
+ UNSELECTED_BACKGROUND,
+ SELECTED_BACKGROUND,
+ DISABLED_UNSELECTED_BACKGROUND,
+ DISABLED_SELECTED_BACKGROUND,
+ VISUALS_COUNT
};
/**
- * Enum to specify which decoration when getting and setting decorations.
+ * Enum to list types of visual a state can have.
+ */
+ enum VisualState
+ {
+ BACKGROUND = 0,
+ FOREGROUND,
+ VISUAL_STATE_COUNT
+ };
+
+protected:
+
+ /**
+ * Button press state which is not the same as the actual button's state.
+ * A button can be DEPRESSED but the until released the button state may have not changed,
+ * For example DEPRESSING a toggle button that is already in the SELECTED state will not change the button state untill released.
*/
- enum DecorationState
+ enum PressState
{
- UNSELECTED_DECORATION = 0,
- SELECTED_DECORATION,
- DECORATION_STATES
+ DEPRESSED, ///< The button is up.
+ UNPRESSED, ///< The button is down.
+ TOGGLE_DEPRESSED, ///< The button has been pressed down and will stay depressed when released.
};
/**
/**
* @return A reference to the unselected button image.
*/
- Actor& GetUnselectedImage();
+ Actor GetUnselectedImage();
/**
* @return A reference to the selected image.
*/
- Actor& GetSelectedImage();
-
- /**
- * @return A reference to the background image.
- */
- Actor& GetBackgroundImage();
-
- /**
- * @return A reference to the selected background image.
- */
- Actor& GetSelectedBackgroundImage();
-
- /**
- * @return A reference to the disabled button image.
- */
- Actor& GetDisabledImage();
-
- /**
- * @return A reference to the disabled selected image.
- */
- Actor& GetDisabledSelectedImage();
-
- /**
- * @return A reference to the disabled background image.
- */
- Actor& GetDisabledBackgroundImage();
+ Actor GetSelectedImage();
private:
/**
* This method is called when the \e selected property is changed.
*/
- virtual void OnSelected() {}
+ virtual void OnStateChange( State newState ){}
/**
* This method is called when the \e disabled property is changed.
* @copydoc Toolkit::Control::OnStageDisconnection()
* @note If overridden by deriving button classes, then an up-call to Button::OnStageDisconnection MUST be made at the end.
*/
- void OnStageDisconnection();
+ virtual void OnStageDisconnection();
+
+ /**
+ * @copydoc Toolkit::Control::OnStageConnnection()
+ */
+ virtual void OnStageConnection( int depth );
+
+ /**
+ * @copydoc Toolkit::Control::GetNaturalSize
+ */
+ virtual Vector3 GetNaturalSize();
+
+ /**
+ * @copydoc Toolkit::Control::OnSetResizePolicy
+ */
+ virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension );
+ /**
+ * @copydoc Toolkit::Control::OnRelayout
+ */
+ virtual void OnRelayout( const Vector2& size, RelayoutContainer& container );
private:
void SetUpTimer( float delay );
/**
+ * Button has been pressed
+ */
+ void Pressed();
+
+ /**
* Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
*/
bool AutoRepeatingSlot();
/**
- * Sets the button as selected or unselected.
- * @param[in] selected \e selected property value.
- * @param[in] emitSignal Emit a signal if this value is \e true.
+ * Check the requested state is an allowed transition.
+ * Some states can not be transitioned to from certain states.
+ * @param[in] requestedState check if can transition to this state
+ * @return bool true if state change valid
*/
- void SetSelected( bool selected, bool emitSignal );
+ bool ValidateState( State requestedState );
/**
- * This method is called when the button is pressed.
+ * Perform the given function on the visuals in the given state. Can be used to add and remove visuals.
+ * @param[in] functionPtr pointer to the function to perform an action on a visual
+ * @param[in] state Visuals in this state will be the target
*/
- void Pressed();
+ void PerformFunctionOnVisualsInState( void(Button::*functionPtr)( Property::Index visualIndex), State state );
/**
- * This method is called when the button is released.
+ * Transition the visual in or out using the set animation
+ * @param[in] state State to transition in or out
*/
- void Released();
+ void SetVisualsForTransition( State state );
/**
- * Used to perform common setup applied to images within button.
- * This will replace the current image with the specifed one.
- * @param[in] actorToModify The image to replace.
- * @param[out] newActor The new image to use.
+ * Changes the button state when an action occurs on it
+ * @param[in] requestedState the state to change to
*/
- void SetupContent( Actor& actorToModify, Actor newActor );
+ void ChangeState( State requestedState );
/**
- * Gets the unselected content color.
- * @return The currently used unselected color.
+ * @brief Get unselected button color
+ * @return color as vector4
*/
const Vector4 GetUnselectedColor() const;
/**
+ * @brief Get selected button color
+ * @return color as vector4
+ */
+ const Vector4 GetSelectedColor() const;
+
+ /**
* Sets the color of button in selected or unselected state, if image also supplied this color will be appplied to it.
* If no visual exists, it is created.
* @param[in] color The color to use.
- * @param[in] selectedState The state to apply the color to, SelectedState or DisabledUnselectedState.
+ * @param[in] visualIndex The Visual to apply the color
*/
- void SetColor( const Vector4& color, PaintState selectedState );
+ void SetColor( const Vector4& color, Property::Index visualIndex );
/**
- * Gets the selected content color.
- * @return The currently used selected color.
+ * This method is called when the button is released.
*/
- const Vector4 GetSelectedColor() const;
+ void Released();
protected:
- ButtonState GetState();
- PaintState GetPaintState();
- void SetDecoration( DecorationState state, Actor actor );
- Actor& GetDecoration( DecorationState state );
+ /**
+ * Set Text Label Padding
+ * @param[in] padding BEGIN END BOTTOM TOP
+ */
+ void SetLabelPadding( const Padding& padding );
+ /**
+ * Get Text Label padding
+ * @return Padding
+ */
+ Padding GetLabelPadding();
/**
- * Returns the animation to be used for transitioning creating the animation if needed.
+ * Set Foreground/icon Padding
+ * @param[in] padding BEGIN END BOTTOM TOP
+ */
+ void SetForegroundPadding( const Padding& padding);
+
+ /**
+ * Get Foreground padding
+ * @ return Padding
+ */
+ Padding GetForegroundPadding();
+
+ /**
+ * @brief Get the pressed state of the button
+ * @return ButtonPressedState the state the button is in
+ */
+ PressState GetPressedState();
+
+ /**
+ * @brief Get the state of the button
+ * @return PaintState the state the button is in
+ */
+ State GetButtonState();
+
+ /**
+ * @brief Setup the button components for example foregrounds and background
+ * @param[in] index the index of the visual to set
+ * @param[in] value the value to set on the component
+ * @param[in] visualDepth the depth of the visual if overlapping another
+ */
+ void CreateVisualsForComponent( Property::Index index ,const Property::Value& value, const float visualDepth );
+
+ /**
+ * Returns the animation to be used for transition, creating the animation if needed.
* @return The initialised transition animation.
*/
Dali::Animation GetTransitionAnimation();
/**
+ * @brief Set distance between label and foreground/icon, if both present
+ * @param[in] length length of strut
+ */
+ void SetLabelStrutLength( unsigned int length );
+
+ /**
+ * @brief Set the position of the label relative to foreground/icon, if both present
+ * @param[in] labelAlignment given alignment setting
+ */
+ void SetLabelAlignment( Align labelAlignment);
+
+ /**
+ * @brief Get set distance between label and foreground/icon visual
+ * @return length of strut
+ */
+ float GetLabelStrutLength();
+
+ /**
+ * @brief Get set alignment of label in relation to foreground/icon
+ * @return Set alignment value
+ */
+ Align GetLabelAlignment();
+
+ /**
* Prepares the actor to be transitioned in.
* @param[in] actor The actor that will be transitioned in.
*/
- virtual void PrepareForTranstionIn( Actor actor ) {}
+ virtual void PrepareForTransitionIn( Actor actor ) {}
/**
* Prepares the actor to be transitioned in.
* @param[in] actor The actor that will be transitioned out.
*/
- virtual void PrepareForTranstionOut( Actor actor ) {}
+ virtual void PrepareForTransitionOut( Actor actor ) {}
/**
* Transitions the actor in, allowing derived classes to configure
* Button is in charge of calling Dali::Animation::Play and so derived classes
* only need to add the animation.
*/
- virtual void OnTransitionIn( Actor actor ) {}
+ virtual void OnTransitionIn( Actor actor );
/**
* Transitions the actor out, allowing derived classes to configure
*/
virtual void OnTransitionOut( Actor actor ) {}
+ /**
+ * Removes the visual from the button (un-staged)
+ * If the derived button does not want the visual removed then use this virtual function to
+ * define the required behaviour.
+ * Can decide to only remove specified visuals via index
+ */
+ virtual void OnButtonVisualRemoval( Property::Index visualIndex );
+
+
private:
/**
void StartTransitionAnimation();
/**
- * This method stops all transition animations
+ * This method stops and clears animations
*/
- void StopTransitionAnimation();
+ void ClearTransitionAnimation();
/**
* Called when the transition animation finishes.
void TransitionAnimationFinished( Dali::Animation& source );
/**
- * Resets the Button to the base state for the current paint state.
- * Any additionally inserted images needed for transitions that are
- * no longer needed and the removed.
- */
- void ResetImageLayers();
-
- /**
- * Transitions out the actor
- */
- void TransitionOut( Actor actor );
-
- /**
- * Removes the actor from the button and prepares it to be transitioned out
- */
- void RemoveButtonImage( Actor& actor );
-
- /**
- * Finds the index of the actor.
- * If the actor doesn't exist, return the last index + 1.
+ * Transition button visual using an animation before removal from Stage
*/
- unsigned int FindChildIndex( Actor& actor );
+ void TransitionButtonVisualOut( Property::Index visualIndex );
/**
- * Adds an actor to the hierarchy and prepares it to be transitioned.
- * @param[in] actor The actor to add
+ * Transition button visual using an animation before adding to Stage
*/
- void PrepareAddButtonImage( Actor& actor );
+ void TransitionButtonVisualIn( Property::Index visualIndex );
/**
- * Adds an actor to the hierarchy and marks it to be transitioned.
- * @param[in] actor The actor to add
+ * Removes the visual from the button and prepares it to be transitioned out
+ * @param[in] visualIndex the visual to remove
*/
- void TransitionButtonImage( Actor& actor );
+ void RemoveVisual( Property::Index visualIndex );
/**
- * Adds an actor to the hierarchy.
- * @param[in] actor The actor to add
+ * Adds the required visual to the button.
+ * @param[in] visualIndex The Property index of the visual required
*/
- void AddButtonImage( Actor& actor );
-
- /**
- * (Re)Adds the label (if exists) to the hierarchy (so it is always on top).
- */
- void ReAddLabel();
+ void SelectRequiredVisual( Property::Index visualIndex );
// Undefined
Button( const Button& );
Toolkit::Button::ButtonSignalType mClickedSignal; ///< Signal emitted when the button is clicked.
Toolkit::Button::ButtonSignalType mStateChangedSignal; ///< Signal emitted when the button's state is changed.
- Timer mAutoRepeatingTimer; ///< Timer used to implement the autorepeating property.
-
- Actor mLabel; ///< Stores the button label.
+ Timer mAutoRepeatingTimer;
- Actor mDecoration[ DECORATION_STATES ]; ///< Stores the decorations for both selected and unselected states.
+ Actor mLabel; ///< Stores the button text label.
+ Padding mLabelPadding; ///< The padding around the label (if present).
+ Padding mForegroundPadding; ///< The padding around the foreground/icon visual (if present).
- Actor mUnselectedContent; ///< Stores the unselected content.
- Actor mSelectedContent; ///< Stores the selected content.
- Actor mBackgroundContent; ///< Stores the background content.
- Actor mSelectedBackgroundContent; ///< Stores the selected background content.
- Actor mDisabledContent; ///< Stores the disabled content.
- Actor mDisabledSelectedContent; ///< Stores the disabled selected content.
- Actor mDisabledBackgroundContent; ///< Stores the disabled background content.
+ unsigned int mForeGroundToLabelStrutLength; ///< Distance between foreground/icon and label.
+ Align mTextLabelAlignment; ///< Position of text label in relation to foreground/icon when both are present.
- Animation mTransitionAnimation; ///< Animation used in the state transitions.
+ Animation mTransitionAnimation; ///< Used in the state transitions.
TapGestureDetector mTapDetector;
- Vector4 mUnselectedColor; ///< Color to use for unselected content.
- Vector4 mSelectedColor; ///< Color to use for selected content.
+ Vector4 mUnselectedColor;
+ Vector4 mSelectedColor;
- bool mDisabled; ///< Stores the disabled property.
- bool mAutoRepeating; ///< Stores the autorepeating property.
- bool mTogglableButton; ///< Stores the togglable property.
- bool mSelected; ///< Stores the selected state.
- float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
- float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
+ bool mAutoRepeating; ///< Stores the autorepeating property.
+ bool mTogglableButton; ///< Stores the togglable property as a flag.
+ float mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
+ float mNextAutoRepeatingDelay; ///< Stores the next autorepeating delay in seconds.
- float mAnimationTime; ///< The animation time.
+ float mAnimationTime;
- // Actions
- bool mClickActionPerforming;
+ PressState mButtonPressedState; ///< In relation to the button being pressed/released
+ State mButtonState;
+ State mPreviousButtonState; ///< During a transition between two states, this stores the previous state so Visuals can be removed.
- ButtonState mState; ///< Stores the button state.
- PaintState mPaintState; ///< Stores the paint state.
+ // Actions
+ bool mClickActionPerforming; ///< Used to manage signal emissions during action
};
} // namespace Internal
} // namespace Dali
-#endif // __DALI_TOOLKIT_INTERNAL_BUTTON_H__
+#endif // DALI_TOOLKIT_INTERNAL_BUTTON_H