Removed OnButton virtual functions and simplified RadioButton logic
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / controls / buttons / button.h
index cce1c66..68b2567 100644 (file)
@@ -37,7 +37,7 @@ class Button;
  */
 
 /**
- * @brief Button is a base class for different kind of buttons.
+ * @brief Button is a base class for different kinds of buttons.
  *
  * This class provides the disabled property and the clicked signal.
  *
@@ -59,14 +59,46 @@ class Button;
  *       When \e togglable is set to \e true, a Button::StateChangedSignal() signal is emitted, with the selected state.
  * </ul>
  *
- * The button's appearance can be modified by setting properties for the various image filenames.
+ * 'Visual' describes not just traditional images like png, bmp but refers to whatever is used to show the button, it could be a color, gradient or some other kind of renderer.
  *
- * The \e background is always shown and doesn't change if the button is pressed or released. The \e button image is shown over the \e background image when the
- * button is not pressed and is replaced by the \e selected image when the button is pressed. The text label is placed always on the top of all images.
+ * The button's appearance can be modified by setting properties for the various images.
  *
- * When the button is disabled, \e background, \e button and \e selected images are replaced by their \e disabled images.
+ * It is not mandatory to set all visuals. A button could be defined only by setting its \e background visual or by setting its \e background and \e selected visuals.
  *
- * Is not mandatory set all images. A button could be defined only by setting its \e background image or by setting its \e background and \e selected images.
+ * The \e button visual is shown over the \e background visual..
+ * When pressed the unselected visuals are replaced by the \e selected visual. The text label is always placed on the top of all images.
+ *
+ * When the button is disabled, \e background, \e button and \e selected visuals are replaced by their \e disabled visuals.
+ *
+
+ *
+  * @brief A control which renders a short text string.
+ *
+ * Text labels are lightweight, non-editable and do not respond to user input.
+ *
+ *
+ * @section ButtonProperties Properties
+ * |%Property enum                                         |String name                             |Type          |Writable|Animatable|
+ * |-------------------------------------------------------|----------------------------------------|--------------|--------|----------|
+ * | Property::DISABLED                                    | disabled                               |  BOOLEAN     | Y      | N        |
+ * | Property::AUTO_REPEATING                              | autoRepeating                          |  BOOLEAN     | Y      | N        |
+ * | Property::INITIAL_AUTO_REPEATING_DELAY                | initialAutoRepeatingDelay              |  FLOAT       | Y      | N        |
+ * | Property::NEXT_AUTO_REPEATING_DELAY                   | nextAutoRepeatingDelay                 |  FLOAT       | Y      | N        |
+ * | Property::TOGGLABLE                                   | togglable                              |  BOOLEAN     | Y      | N        |
+ * | Property::SELECTED                                    | selected                               |  BOOLEAN     | Y      | N        |
+ * | Property::LABEL                                       | label                                  |  MAP         | Y      | N        |
+ * | Property::UNSELECTED_STATE_VISUAL                     | unselectedVisual                       |  MAP         | Y      | N        |
+ * | Property::SELECTED_VISUAL                             | selectedVisual                         |  MAP         | Y      | N        |
+ * | Property::DISABLED_SELECTED_VISUAL                    | disabledSelectedVisual                 |  MAP         | Y      | N        |
+ * | Property::DISABLED_UNSELECTED_VISUAL                  | disabledUnselectedVisual               |  MAP         | Y      | N        |
+ * | Property::UNSELECTED_BACKGROUND_VISUAL                | unselectedBackgroundVisual             |  MAP         | Y      | N        |
+ * | Property::SELECTED_BACKGROUND_VISUAL                  | selectedBackgroundVisual               |  MAP         | Y      | N        |
+ * | Property::DISABLED_UNSELECTED_BACKGROUND_VISUAL       | disabledUnselectedBackgroundVisual     |  MAP         | Y      | N        |
+ * | Property::DISABLED_SELECTED_BACKGROUND_VISUAL         | disabledSelectedBackgroundVisual       |  MAP         | Y      | N        |
+ * | Property::LABEL_RELATIVE_ALIGNMENT                    | labelRelativeAlignment                 |  STRING      | Y      | N        |
+ * -------------------------------------------------------------------------------------------------------------------------------------
+ *
+ * Note, *_VISUAL properties of type MAP can also be passed a uri of type STRING
  *
  * Signals
  * | %Signal Name     | Method                      |
@@ -77,9 +109,10 @@ class Button;
  * | stateChanged     | @ref StateChangedSignal()   |
  *
  * Actions
- * | %Action Name     | %Button method called       |
- * |------------------|-----------------------------|
- * | buttonClick      | %DoClickAction()            |
+ * | %Action Name     | Attributes              | Description                                   |
+ * |------------------|-------------------------|-----------------------------------------------|
+ * | buttonClick      | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
+ * @SINCE_1_0.0
  */
 class DALI_IMPORT_API Button : public Control
 {
@@ -87,35 +120,181 @@ public:
 
   /**
    * @brief The start and end property ranges for this control.
+   * @SINCE_1_0.0
    */
   enum PropertyRange
   {
-    PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
-    PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices
+    PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
+    PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
   };
 
   /**
    * @brief An enumeration of properties belonging to the Button class.
+   * @SINCE_1_0.0
    */
   struct Property
   {
+    /**
+     * @brief An enumeration of properties belonging to the Button class.
+     * @SINCE_1_0.0
+     */
     enum
     {
-      DISABLED = PROPERTY_START_INDEX, ///< name "disabled",                     @see SetDisabled(),                  type bool
-      AUTO_REPEATING,                  ///< name "autoRepeating",                @see SetAutoRepeating(),             type bool
-      INITIAL_AUTO_REPEATING_DELAY,    ///< name "initialAutoRepeatingDelay",    @see SetInitialAutoRepeatingDelay(), type float
-      NEXT_AUTO_REPEATING_DELAY,       ///< name "nextAutoRepeatingDelay",       @see SetNextAutoRepeatingDelay(),    type float
-      TOGGLABLE,                       ///< name "togglable",                    @see SetTogglableButton(),           type bool
-      SELECTED,                        ///< name "selected",                     @see SetSelected(),                  type bool
-      UNSELECTED_STATE_IMAGE,          ///< name "unselectedStateImage",         @see SetUnselectedImage(),           type std::string
-      SELECTED_STATE_IMAGE,            ///< name "selectedStateImage",           @see SetSelectedImage(),             type std::string
-      DISABLED_STATE_IMAGE,            ///< name "disabledStateImage",           @see SetDisabledImage(),             type std::string
-      UNSELECTED_COLOR,                ///< name "unselectedColor",                                                   type Vector4
-      SELECTED_COLOR,                  ///< name "selectedColor",                                                     type Vector4
-      LABEL,                           ///< name "label",                                                             type Property::Map
-
-      // Deprecated properties:
-      LABEL_TEXT,                      ///< name "labelText",                    @see SetLabelText(),                 type std::string
+      /**
+       * @brief name "disabled", type bool
+       * @details Sets the button as \e disabled.
+       * @SINCE_1_0.0
+       */
+      DISABLED = PROPERTY_START_INDEX,
+
+      /**
+       * @brief name "autoRepeating", type bool
+       * @details If the \e autorepeating property is set to \e true then the \e togglable property is set to false
+       * @SINCE_1_0.0
+       */
+      AUTO_REPEATING,
+
+      /**
+       * @brief name "initialAutoRepeatingDelay", type float
+       * @details By default this value is set to 0.15 seconds.
+       * @SINCE_1_0.0
+       */
+      INITIAL_AUTO_REPEATING_DELAY,
+
+      /**
+       * @brief name "nextAutoRepeatingDelay", type float
+       * @details default this value is set to 0.05 seconds
+       * @SINCE_1_0.0
+       */
+      NEXT_AUTO_REPEATING_DELAY,
+
+      /**
+       * @brief name "togglable", type bool
+       * @details If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
+       * @SINCE_1_0.0
+       */
+      TOGGLABLE,
+
+      /**
+       * @brief name "selected", type bool
+       * @details Sets the togglable button as either selected or unselected, \e togglable property must be set to \e true.
+       * @SINCE_1_0.0
+       */
+      SELECTED,
+
+      /**
+       * @DEPRECATED_1_1.XX Use UNSELECTED_VISUAL
+       * @brief name "unselectedStateImage", type string if it is a url, map otherwise
+       * @details Sets the unselected button foreground image
+       * @SINCE_1_0.0
+       */
+      UNSELECTED_STATE_IMAGE,
+
+      /**
+       * @DEPRECATED_1_1.XX Use SELECTED_VISUAL
+       * @brief name "selectedStateImage", type string if it is a url, map otherwise
+       * @details Sets the selected button foreground image
+       * @SINCE_1_0.0
+       */
+      SELECTED_STATE_IMAGE,
+
+      /**
+       * @DEPRECATED_1_1.XX Use DISABLED_UNSELECTED_VISUAL
+       * @brief name "disabledStateImage", type string if it is a url, map otherwise
+       * @details Sets the disabled whilst unselected foreground button visual
+       * @SINCE_1_0.0
+       */
+      DISABLED_STATE_IMAGE,
+
+      /**
+       * @DEPRECATED_1_1.XX Use UNSELECTED_BACKGROUND_VISUAL
+       * @brief name "unselectedColor", type Vector4
+       * @SINCE_1_0.0
+       */
+      UNSELECTED_COLOR,
+
+      /**
+       * @DEPRECATED_1_1.XX Use SELECTED_BACKGROUND_VISUAL
+       * @brief name "selectedColor", type Vector4
+       * @SINCE_1_0.0
+       */
+      SELECTED_COLOR,
+
+      /**
+       * @brief name "label", type Property::Map
+       * @SINCE_1_0.0
+       */
+      LABEL,
+
+      /**
+       * @DEPRECATED_1_1.32 Use LABEL
+       * @brief name "labelText", type std::string
+       * @SINCE_1_0.0
+       */
+      LABEL_TEXT,
+
+      /**
+       * @brief name "unselectedVisual", type string if it is a url, map otherwise
+       * @details Sets the unselected button foreground/icon visual
+       * @SINCE_1_2.XX
+       */
+      UNSELECTED_VISUAL,
+
+      /**
+       * @brief name "selectedImage", type string if it is a url, map otherwise
+       * @details Sets the selected button foreground/icon visual
+       * @SINCE_1_2.XX
+       */
+      SELECTED_VISUAL,
+
+      /**
+       * @brief name "disabledSelectedVisual", type string if it is a url, map otherwise
+       * @details Sets the disabled selected state foreground/icon button visual
+       * @SINCE_1_2.XX
+       */
+      DISABLED_SELECTED_VISUAL,
+
+      /**
+       * @brief name "disabledUnSelectedVisual", type string if it is a url, map otherwise
+       * @details Sets the disabled unselected state foreground/icon visual
+       * @SINCE_1_2.XX
+       */
+      DISABLED_UNSELECTED_VISUAL,
+
+      /**
+       * @brief name "unselectedBackgroundVisual", type string if it is a url, map otherwise
+       * @details Sets the disabled in the unselected state background, button visual
+       * @SINCE_1_2.XX
+       */
+      UNSELECTED_BACKGROUND_VISUAL,
+
+      /**
+       * @brief name "selectedBackgroundVisual", type string if it is a url, map otherwise
+       * @details Sets the selected background button visual
+       * @SINCE_1_2.XX
+       */
+      SELECTED_BACKGROUND_VISUAL,
+
+      /**
+       * @brief name "disabledUnselectedBackgroundVisual", type string if it is a url, map otherwise
+       * @details Sets the disabled while unselected background button visual
+       * @SINCE_1_2.XX
+       */
+      DISABLED_UNSELECTED_BACKGROUND_VISUAL,
+
+      /**
+       * @brief name "disabledSelectedBackgroundVisual", type string if it is a url, map otherwise
+       * @details Sets the disabled while selected background button visual
+       * @SINCE_1_2.XX
+       */
+      DISABLED_SELECTED_BACKGROUND_VISUAL,
+
+      /**
+       * @brief name "labelRelativeAlignment", type STRING
+       * @details Sets the position of the the label in relation to the foreground/icon if both present
+       * @SINCE_1_2.XX
+       */
+      LABEL_RELATIVE_ALIGNMENT,
     };
   };
 
@@ -126,27 +305,34 @@ public:
    *
    * Only derived versions can be instantiated.  Calling member
    * functions with an uninitialized Dali::Object is not allowed.
+   * @SINCE_1_0.0
    */
   Button();
 
   /**
    * @brief Copy constructor.
+   * @SINCE_1_0.0
+   * @param[in] button Handle to an object
    */
   Button( const Button& button );
 
   /**
    * @brief Assignment operator.
+   * @SINCE_1_0.0
+   * @param[in] button Handle to an object
+   * @return A reference to this
    */
   Button& operator=( const Button& button );
 
   /**
-   * @brief Downcast an Object handle to Button.
+   * @brief Downcast a handle to Button handle.
    *
    * If handle points to a Button the downcast produces valid
    * handle. If not the returned handle is left uninitialized.
    *
+   * @SINCE_1_0.0
    * @param[in] handle Handle to an object
-   * @return handle to a Button or an uninitialized handle
+   * @return handle to a Button or an uninitialized handle
    */
   static Button DownCast( BaseHandle handle );
 
@@ -154,226 +340,314 @@ public:
    * @brief Destructor
    *
    * This is non-virtual since derived Handle types must not contain data or virtual methods.
+   * @SINCE_1_0.0
    */
   ~Button();
 
+  // Deprecated API
+
   /**
+   * @DEPRECATED_1_1.32 Use SetProperty DISABLED or Styling file
+   *
    * @brief Sets the button as \e disabled.
    *
    * No signals are emitted when the \e disabled property is set.
    *
+   * @SINCE_1_0.0
    * @param[in] disabled property.
    */
-  void SetDisabled( bool disabled );
+  void SetDisabled( bool disabled ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 Use GetProperty DISABLED
+   *
+   * @brief Returns if the button is disabled.
+   * @SINCE_1_0.0
    * @return \e true if the button is \e disabled.
    */
-  bool IsDisabled() const;
+  bool IsDisabled() const DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 SetProperty AUTO_REPEATING or Styling file
+   *
    * @brief Sets the \e autorepeating property.
    *
    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
    * but no signal is emitted.
    *
+   * @SINCE_1_0.0
    * @param[in] autoRepeating \e autorepeating property.
    */
-  void SetAutoRepeating( bool autoRepeating );
+  void SetAutoRepeating( bool autoRepeating ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 GetProperty AUTO_REPEATING
+   *
+   * @brief Returns if the autorepeating property is set.
+   * @SINCE_1_0.0
    * @return \e true if the \e autorepeating property is set.
    */
-  bool IsAutoRepeating() const;
+  bool IsAutoRepeating() const DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 SetProperty INITIAL_AUTO_REPEATING_DELAY or Styling file
+   *
    * @brief Sets the initial autorepeating delay.
    *
    * By default this value is set to 0.15 seconds.
    *
-   * @pre initialAutoRepeatingDelay must be greater than zero.
+   * @SINCE_1_0.0
    * @param[in] initialAutoRepeatingDelay in seconds.
+   * @pre initialAutoRepeatingDelay must be greater than zero.
    */
-  void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
+  void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 GetProperty INITIAL_AUTO_REPEATING_DELAY
+   *
+   * @brief Gets the initial autorepeating delay in seconds.
+   * @SINCE_1_0.0
    * @return the initial autorepeating delay in seconds.
    */
-  float GetInitialAutoRepeatingDelay() const;
+  float GetInitialAutoRepeatingDelay() const DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 SetProperty NEXT_AUTO_REPEATING_DELAY or Styling file
+   *
    * @brief Sets the next autorepeating delay.
    *
    * By default this value is set to 0.05 seconds.
    *
-   * @pre nextAutoRepeatingDelay must be greater than zero.
+   * @SINCE_1_0.0
    * @param[in] nextAutoRepeatingDelay in seconds.
+   * @pre nextAutoRepeatingDelay must be greater than zero.
    */
-  void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
+  void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 GetProperty NEXT_AUTO_REPEATING_DELAY
+   *
+   * @brief Gets the next autorepeating delay in seconds.
+   * @SINCE_1_0.0
    * @return the next autorepeating delay in seconds.
    */
-  float GetNextAutoRepeatingDelay() const;
+  float GetNextAutoRepeatingDelay() const DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 SetProperty TOGGLABLE or Styling file
+   *
    * @brief Sets the \e togglable property.
    *
    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
    *
+   * @SINCE_1_0.0
    * @param[in] togglable property.
    */
-  void SetTogglableButton( bool togglable );
+  void SetTogglableButton( bool togglable ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 GetProperty TOGGLABLE
+   *
+   * @brief Returns if the togglable property is set.
+   * @SINCE_1_0.0
    * @return \e true if the \e togglable property is set.
    */
-  bool IsTogglableButton() const;
+  bool IsTogglableButton() const DALI_DEPRECATED_API;
 
   /**
-   * Sets the button as selected or unselected.
+   * @DEPRECATED_1_1.32 SetProperty SELECTED
+   *
+   * @brief Sets the button as selected or unselected.
    *
    * \e togglable property must be set to \e true.
    *
    * Emits a Button::StateChangedSignal() signal.
    *
+   * @SINCE_1_0.0
    * @param[in] selected property.
    */
-  void SetSelected( bool selected );
+  void SetSelected( bool selected ) DALI_DEPRECATED_API;
 
   /**
-   * @return \e true if the \e selected property is set and the button is togglable.
+   * DEPRECATED_1_1.32  GetProperty SELECTED
+   *
+   * @brief Returns if the selected property is set and the button is togglable.
+   * @SINCE_1_0.0
+   * @return \e true if the button is \e selected.
    */
-  bool IsSelected() const;
+  bool IsSelected() const DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 Use Styling file to set animation
+   *
    * @brief Sets the animation time.
    *
+   * @SINCE_1_0.0
    * @param[in] animationTime The animation time in seconds.
    */
-  void SetAnimationTime( float animationTime );
+  void SetAnimationTime( float animationTime ) DALI_DEPRECATED_API;
 
   /**
+   * DEPRECATED_1_1.32 Use Styling file to set animation
+   *
    * @brief Retrieves button's animation time.
    *
+   * @SINCE_1_0.0
    * @return The animation time in seconds.
    */
-  float GetAnimationTime() const;
+  float GetAnimationTime() const DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 SetProperty Property::LABEL or Styling file
+   *
    * @brief Sets the button's label.
    *
+   * @SINCE_1_0.0
    * @param[in] label The label text.
    */
-  void SetLabelText( const std::string& label );
+  void SetLabelText( const std::string& label ) DALI_DEPRECATED_API;
 
   /**
+   * DEPRECATED_1_1.32 GetProperty LABEL
+   *
    * @brief Gets the label.
    *
+   * @SINCE_1_0.0
    * @return The label text.
    */
-  std::string GetLabelText() const;
+  std::string GetLabelText() const DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 Use Styling file Property::UNSELECTED_STATE_IMAGE
+   *
    * @brief Sets the unselected button image.
    *
+   * @SINCE_1_0.0
    * @param[in] filename The button image.
    */
-  void SetUnselectedImage( const std::string& filename );
+  void SetUnselectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 
   /**
-   * @brief Sets the background image.
+   * @DEPRECATED_1_1.32 Use styling
+   * Use Property::UNSELECTED_BACKGROUND_VISUAL
+   *
+   * @brief Sets the unselected background image.
    *
+   * @SINCE_1_0.0
    * @param[in] filename The background image.
    */
-  void SetBackgroundImage( const std::string& filename );
+  void SetBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 Use styling file, Property::SELECTED_STATE_IMAGE
+   *
    * @brief Sets the selected image.
    *
+   * @SINCE_1_0.0
    * @param[in] filename The selected image.
    */
-  void SetSelectedImage( const std::string& filename );
+  void SetSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_2.32 Use styling file
+   * Use Property::SELECTED_BACKGROUND_VISUAL
+   *
    * @brief Sets the selected background image.
    *
+   * @SINCE_1_0.0
    * @param[in] filename The selected background image.
    */
-  void SetSelectedBackgroundImage( const std::string& filename );
+  void SetSelectedBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 Use styling file
+   * Use Property::DISABLED_SELECTED_BACKGROUND_VISUAL
+   *
    * @brief Sets the disabled background image.
    *
+   * @SINCE_1_0.0
    * @param[in] filename The disabled background image.
    */
-  void SetDisabledBackgroundImage( const std::string& filename );
+  void SetDisabledBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 Use styling file Property::DISABLED_STATE_IMAGE
+   *
    * @brief Sets the disabled button image.
    *
+   * @SINCE_1_0.0
    * @param[in] filename The disabled button image.
    */
-  void SetDisabledImage( const std::string& filename );
+  void SetDisabledImage( const std::string& filename ) DALI_DEPRECATED_API;
 
   /**
+   * @DEPRECATED_1_1.32 Use styling file
+   * Use Property::DISABLED_SELECTED_VISUAL
+   *
    * @brief Sets the disabled selected button image.
    *
+   * @SINCE_1_0.0
    * @param[in] filename The disabled selected button image.
    */
-  void SetDisabledSelectedImage( const std::string& filename );
-
-  // Deprecated API
+  void SetDisabledSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 
   /**
-   * @deprecated DALi 1.0.50
+   * @DEPRECATED_1_0.50. Instead, use SetLabelText.
    *
    * @brief Sets the label with an actor.
    *
+   * @SINCE_1_0.0
    * @param[in]  label The actor to use as a label
    */
-  void SetLabel( Actor label );
+  void SetLabel( Actor label ) DALI_DEPRECATED_API;
 
   /**
-   * @deprecated DALi 1.0.50
+   * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
    *
    * @brief Sets the button image.
    *
+   * @SINCE_1_0.0
    * @param[in]  image The button image.
    */
-  void SetButtonImage( Image image );
+  void SetButtonImage( Image image ) DALI_DEPRECATED_API;
 
   /**
-   * @deprecated DALi 1.0.50
+   * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
    *
    * @brief Sets the selected image.
    *
+   * @SINCE_1_0.0
    * @param[in]  image The selected image.
    */
-  void SetSelectedImage( Image image );
+  void SetSelectedImage( Image image ) DALI_DEPRECATED_API;
 
   /**
-   * @deprecated DALi 1.0.50
+   * @DEPRECATED_1_0.50
    *
    * @brief Gets the button image.
    *
+   * @SINCE_1_0.0
+   * @remarks Avoid using this method as it's a legacy code.
    * @return     An actor with the button image.
    */
-  Actor GetButtonImage() const;
+  Actor GetButtonImage() const DALI_DEPRECATED_API;
 
   /**
-   * @deprecated DALi 1.0.50
+   * @DEPRECATED_1_0.50
    *
    * @brief Gets the selected image.
    *
+   * @SINCE_1_0.0
+   * @remarks Avoid using this method as it's a legacy code.
    * @return     An actor with the selected image.
    */
-  Actor GetSelectedImage() const;
+  Actor GetSelectedImage() const DALI_DEPRECATED_API;
 
 public: //Signals
 
   /**
    * @brief Button signal type
+   * @SINCE_1_0.0
    */
   typedef Signal< bool ( Button ) > ButtonSignalType;
 
@@ -384,6 +658,7 @@ public: //Signals
    * @code
    *   bool YourCallbackName( Button button );
    * @endcode
+   * @SINCE_1_0.0
    * @return The signal to connect to.
    */
   ButtonSignalType& PressedSignal();
@@ -395,6 +670,7 @@ public: //Signals
    * @code
    *   bool YourCallbackName( Button button );
    * @endcode
+   * @SINCE_1_0.0
    * @return The signal to connect to.
    */
   ButtonSignalType& ReleasedSignal();
@@ -406,27 +682,32 @@ public: //Signals
    * @code
    *   bool YourCallbackName( Button button );
    * @endcode
+   * @SINCE_1_0.0
    * @return The signal to connect to.
    */
   ButtonSignalType& ClickedSignal();
 
   /**
    * @brief This signal is emitted when the button's state is changed.
+   *
    * The application can get the state by calling IsSelected().
    *
    * A callback of the following type may be connected:
    * @code
    *   bool YourCallbackName( Button button );
    * @endcode
+   * @SINCE_1_0.0
    * @return The signal to connect to.
    */
   ButtonSignalType& StateChangedSignal();
 
 public: // Not intended for application developers
 
+  /// @cond internal
   /**
    * @brief Creates a handle using the Toolkit::Internal implementation.
    *
+   * @SINCE_1_0.0
    * @param[in]  implementation  The Control implementation.
    */
   DALI_INTERNAL Button( Internal::Button& implementation );
@@ -434,9 +715,11 @@ public: // Not intended for application developers
   /**
    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
    *
+   * @SINCE_1_0.0
    * @param[in]  internal  A pointer to the internal CustomActor.
    */
   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
+  /// @endcond
 };
 
 /**