dali-toolkit/public-api/controls/buttons/button.h

   1 #ifndef __DALI_TOOLKIT_BUTTON_H__
   2 #define __DALI_TOOLKIT_BUTTON_H__
   3
   4 /*
   5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 class Button;
  33 }
  34 /**
  35  * @addtogroup dali_toolkit_controls_buttons
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Button is a base class for different kinds of buttons.
  41  *
  42  * This class provides the disabled property and the clicked signal.
  43  *
  44  * A ClickedSignal() is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
  45  *
  46  * When the \e disabled property is set to \e true, no signal is emitted.
  47  *
  48  * Button provides the following properties which modify the signals emitted:
  49  * <ul>
  50  *   <li>\e autorepeating
  51  *       When \e autorepeating is set to \e true, a Button::PressedSignal(), Button::ReleasedSignal() and Button::ClickedSignal() signals are emitted at regular
  52  *       intervals while the button is touched.
  53  *       The intervals could be modified with the Button::SetInitialAutoRepeatingDelay and Button::SetNextAutoRepeatingDelay methods.
  54  *
  55  *       A \e togglable button can't be \e autorepeating. If the \e autorepeating property is set to \e true, then the \e togglable property is set to
  56  *       false but no signal is emitted.
  57  *
  58  *   <li>\e togglable
  59  *       When \e togglable is set to \e true, a Button::StateChangedSignal() signal is emitted, with the selected state.
  60  * </ul>
  61  *
  62  * '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.
  63  *
  64  * The button's appearance can be modified by setting properties for the various images.
  65  *
  66  * 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.
  67  *
  68  * The \e button visual is shown over the \e background visual..
  69  * When pressed the unselected visuals are replaced by the \e selected visual. The text label is always placed on the top of all images.
  70  *
  71  * When the button is disabled, \e background, \e button and \e selected visuals are replaced by their \e disabled visuals.
  72  *
  73
  74  *
  75   * @brief A control which renders a short text string.
  76  *
  77  * Text labels are lightweight, non-editable and do not respond to user input.
  78  *
  79  *
  80  * @section ButtonProperties Properties
  81  * |%Property enum                                         |String name                             |Type          |Writable|Animatable|
  82  * |-------------------------------------------------------|----------------------------------------|--------------|--------|----------|
  83  * | Property::DISABLED                                    | disabled                               |  BOOLEAN     | Y      | N        |
  84  * | Property::AUTO_REPEATING                              | autoRepeating                          |  BOOLEAN     | Y      | N        |
  85  * | Property::INITIAL_AUTO_REPEATING_DELAY                | initialAutoRepeatingDelay              |  FLOAT       | Y      | N        |
  86  * | Property::NEXT_AUTO_REPEATING_DELAY                   | nextAutoRepeatingDelay                 |  FLOAT       | Y      | N        |
  87  * | Property::TOGGLABLE                                   | togglable                              |  BOOLEAN     | Y      | N        |
  88  * | Property::SELECTED                                    | selected                               |  BOOLEAN     | Y      | N        |
  89  * | Property::LABEL                                       | label                                  |  MAP         | Y      | N        |
  90  * | Property::UNSELECTED_STATE_VISUAL                     | unselectedVisual                       |  MAP         | Y      | N        |
  91  * | Property::SELECTED_VISUAL                             | selectedVisual                         |  MAP         | Y      | N        |
  92  * | Property::DISABLED_SELECTED_VISUAL                    | disabledSelectedVisual                 |  MAP         | Y      | N        |
  93  * | Property::DISABLED_UNSELECTED_VISUAL                  | disabledUnselectedVisual               |  MAP         | Y      | N        |
  94  * | Property::UNSELECTED_BACKGROUND_VISUAL                | unselectedBackgroundVisual             |  MAP         | Y      | N        |
  95  * | Property::SELECTED_BACKGROUND_VISUAL                  | selectedBackgroundVisual               |  MAP         | Y      | N        |
  96  * | Property::DISABLED_UNSELECTED_BACKGROUND_VISUAL       | disabledUnselectedBackgroundVisual     |  MAP         | Y      | N        |
  97  * | Property::DISABLED_SELECTED_BACKGROUND_VISUAL         | disabledSelectedBackgroundVisual       |  MAP         | Y      | N        |
  98  * | Property::LABEL_STRUT_LENGTH                          | labelStrutLength                       |  INTEGER     | Y      | N        |
  99  * | Property::LABEL_RELATIVE_ALIGNMENT                    | labelRelativeAlignment                 |  STRING      | Y      | N        |
 100  * -------------------------------------------------------------------------------------------------------------------------------------
 101  *
 102  * Note, *_VISUAL properties of type MAP can also be passed a uri of type STRING
 103  *
 104  * Signals
 105  * | %Signal Name     | Method                      |
 106  * |------------------|-----------------------------|
 107  * | pressed          | @ref PressedSignal()        |
 108  * | released         | @ref ReleasedSignal()       |
 109  * | clicked          | @ref ClickedSignal()        |
 110  * | stateChanged     | @ref StateChangedSignal()   |
 111  *
 112  * Actions
 113  * | %Action Name     | Attributes              | Description                                   |
 114  * |------------------|-------------------------|-----------------------------------------------|
 115  * | buttonClick      | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
 116  * @SINCE_1_0.0
 117  */
 118 class DALI_IMPORT_API Button : public Control
 119 {
 120 public:
 121
 122   /**
 123    * @brief The start and end property ranges for this control.
 124    * @SINCE_1_0.0
 125    */
 126   enum PropertyRange
 127   {
 128     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
 129     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
 130   };
 131
 132   /**
 133    * @brief An enumeration of properties belonging to the Button class.
 134    * @SINCE_1_0.0
 135    */
 136   struct Property
 137   {
 138     /**
 139      * @brief An enumeration of properties belonging to the Button class.
 140      * @SINCE_1_0.0
 141      */
 142     enum
 143     {
 144       /**
 145        * @brief name "disabled", type bool
 146        * @details Sets the button as \e disabled.
 147        * @SINCE_1_0.0
 148        */
 149       DISABLED = PROPERTY_START_INDEX,
 150
 151       /**
 152        * @brief name "autoRepeating", type bool
 153        * @details If the \e autorepeating property is set to \e true then the \e togglable property is set to false
 154        * @SINCE_1_0.0
 155        */
 156       AUTO_REPEATING,
 157
 158       /**
 159        * @brief name "initialAutoRepeatingDelay", type float
 160        * @details By default this value is set to 0.15 seconds.
 161        * @SINCE_1_0.0
 162        */
 163       INITIAL_AUTO_REPEATING_DELAY,
 164
 165       /**
 166        * @brief name "nextAutoRepeatingDelay", type float
 167        * @details default this value is set to 0.05 seconds
 168        * @SINCE_1_0.0
 169        */
 170       NEXT_AUTO_REPEATING_DELAY,
 171
 172       /**
 173        * @brief name "togglable", type bool
 174        * @details If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 175        * @SINCE_1_0.0
 176        */
 177       TOGGLABLE,
 178
 179       /**
 180        * @brief name "selected", type bool
 181        * @details Sets the togglable button as either selected or unselected, \e togglable property must be set to \e true.
 182        * @SINCE_1_0.0
 183        */
 184       SELECTED,
 185
 186       /**
 187        * @DEPRECATED_1_1.XX Use UNSELECTED_VISUAL
 188        * @brief name "unselectedStateImage", type string if it is a url, map otherwise
 189        * @details Sets the unselected button foreground image
 190        * @SINCE_1_0.0
 191        */
 192       UNSELECTED_STATE_IMAGE,
 193
 194       /**
 195        * @DEPRECATED_1_1.XX Use SELECTED_VISUAL
 196        * @brief name "selectedStateImage", type string if it is a url, map otherwise
 197        * @details Sets the selected button foreground image
 198        * @SINCE_1_0.0
 199        */
 200       SELECTED_STATE_IMAGE,
 201
 202       /**
 203        * @DEPRECATED_1_1.XX Use DISABLED_UNSELECTED_VISUAL
 204        * @brief name "disabledStateImage", type string if it is a url, map otherwise
 205        * @details Sets the disabled whilst unselected foreground button visual
 206        * @SINCE_1_0.0
 207        */
 208       DISABLED_STATE_IMAGE,
 209
 210       /**
 211        * @DEPRECATED_1_1.XX Use UNSELECTED_BACKGROUND_VISUAL
 212        * @brief name "unselectedColor", type Vector4
 213        * @SINCE_1_0.0
 214        */
 215       UNSELECTED_COLOR,
 216
 217       /**
 218        * @DEPRECATED_1_1.XX Use SELECTED_BACKGROUND_VISUAL
 219        * @brief name "selectedColor", type Vector4
 220        * @SINCE_1_0.0
 221        */
 222       SELECTED_COLOR,
 223
 224       /**
 225        * @brief name "label", type Property::Map
 226        * @SINCE_1_0.0
 227        */
 228       LABEL,
 229
 230       /**
 231        * @DEPRECATED_1_1.32 Use LABEL
 232        * @brief name "labelText", type std::string
 233        * @SINCE_1_0.0
 234        */
 235       LABEL_TEXT,
 236
 237       /**
 238        * @brief name "unselectedVisual", type string if it is a url, map otherwise
 239        * @details Sets the unselected button foreground/icon visual
 240        * @SINCE_1_2.XX
 241        */
 242       UNSELECTED_VISUAL,
 243
 244       /**
 245        * @brief name "selectedImage", type string if it is a url, map otherwise
 246        * @details Sets the selected button foreground/icon visual
 247        * @SINCE_1_2.XX
 248        */
 249       SELECTED_VISUAL,
 250
 251       /**
 252        * @brief name "disabledSelectedVisual", type string if it is a url, map otherwise
 253        * @details Sets the disabled selected state foreground/icon button visual
 254        * @SINCE_1_2.XX
 255        */
 256       DISABLED_SELECTED_VISUAL,
 257
 258       /**
 259        * @brief name "disabledUnSelectedVisual", type string if it is a url, map otherwise
 260        * @details Sets the disabled unselected state foreground/icon visual
 261        * @SINCE_1_2.XX
 262        */
 263       DISABLED_UNSELECTED_VISUAL,
 264
 265       /**
 266        * @brief name "unselectedBackgroundVisual", type string if it is a url, map otherwise
 267        * @details Sets the disabled in the unselected state background, button visual
 268        * @SINCE_1_2.XX
 269        */
 270       UNSELECTED_BACKGROUND_VISUAL,
 271
 272       /**
 273        * @brief name "selectedBackgroundVisual", type string if it is a url, map otherwise
 274        * @details Sets the selected background button visual
 275        * @SINCE_1_2.XX
 276        */
 277       SELECTED_BACKGROUND_VISUAL,
 278
 279       /**
 280        * @brief name "disabledUnselectedBackgroundVisual", type string if it is a url, map otherwise
 281        * @details Sets the disabled while unselected background button visual
 282        * @SINCE_1_2.XX
 283        */
 284       DISABLED_UNSELECTED_BACKGROUND_VISUAL,
 285
 286       /**
 287        * @brief name "disabledSelectedBackgroundVisual", type string if it is a url, map otherwise
 288        * @details Sets the disabled while selected background button visual
 289        * @SINCE_1_2.XX
 290        */
 291       DISABLED_SELECTED_BACKGROUND_VISUAL,
 292
 293       /**
 294        * @brief name "labelStrutLength", type INTEGER
 295        * @details Sets the distance between the label and foreground/icon visual if both present
 296        * @SINCE_1_2.XX
 297        */
 298       LABEL_STRUT_LENGTH,  // todo ????? remove
 299
 300       /**
 301        * @brief name "labelRelativeAlignment", type STRING
 302        * @details Sets the position of the the label in relation to the foreground/icon if both present
 303        * @SINCE_1_2.XX
 304        */
 305       LABEL_RELATIVE_ALIGNMENT,
 306     };
 307   };
 308
 309 public:
 310
 311   /**
 312    * @brief Create an uninitialized Button.
 313    *
 314    * Only derived versions can be instantiated.  Calling member
 315    * functions with an uninitialized Dali::Object is not allowed.
 316    * @SINCE_1_0.0
 317    */
 318   Button();
 319
 320   /**
 321    * @brief Copy constructor.
 322    * @SINCE_1_0.0
 323    * @param[in] button Handle to an object
 324    */
 325   Button( const Button& button );
 326
 327   /**
 328    * @brief Assignment operator.
 329    * @SINCE_1_0.0
 330    * @param[in] button Handle to an object
 331    * @return A reference to this
 332    */
 333   Button& operator=( const Button& button );
 334
 335   /**
 336    * @brief Downcast a handle to Button handle.
 337    *
 338    * If handle points to a Button the downcast produces valid
 339    * handle. If not the returned handle is left uninitialized.
 340    *
 341    * @SINCE_1_0.0
 342    * @param[in] handle Handle to an object
 343    * @return A handle to a Button or an uninitialized handle
 344    */
 345   static Button DownCast( BaseHandle handle );
 346
 347   /**
 348    * @brief Destructor
 349    *
 350    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 351    * @SINCE_1_0.0
 352    */
 353   ~Button();
 354
 355   // Deprecated API
 356
 357   /**
 358    * @DEPRECATED_1_1.32 Use SetProperty DISABLED or Styling file
 359    *
 360    * @brief Sets the button as \e disabled.
 361    *
 362    * No signals are emitted when the \e disabled property is set.
 363    *
 364    * @SINCE_1_0.0
 365    * @param[in] disabled property.
 366    */
 367   void SetDisabled( bool disabled ) DALI_DEPRECATED_API;
 368
 369   /**
 370    * @DEPRECATED_1_1.32 Use GetProperty DISABLED
 371    *
 372    * @brief Returns if the button is disabled.
 373    * @SINCE_1_0.0
 374    * @return \e true if the button is \e disabled.
 375    */
 376   bool IsDisabled() const DALI_DEPRECATED_API;
 377
 378   /**
 379    * @DEPRECATED_1_1.32 SetProperty AUTO_REPEATING or Styling file
 380    *
 381    * @brief Sets the \e autorepeating property.
 382    *
 383    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
 384    * but no signal is emitted.
 385    *
 386    * @SINCE_1_0.0
 387    * @param[in] autoRepeating \e autorepeating property.
 388    */
 389   void SetAutoRepeating( bool autoRepeating ) DALI_DEPRECATED_API;
 390
 391   /**
 392    * @DEPRECATED_1_1.32 GetProperty AUTO_REPEATING
 393    *
 394    * @brief Returns if the autorepeating property is set.
 395    * @SINCE_1_0.0
 396    * @return \e true if the \e autorepeating property is set.
 397    */
 398   bool IsAutoRepeating() const DALI_DEPRECATED_API;
 399
 400   /**
 401    * @DEPRECATED_1_1.32 SetProperty INITIAL_AUTO_REPEATING_DELAY or Styling file
 402    *
 403    * @brief Sets the initial autorepeating delay.
 404    *
 405    * By default this value is set to 0.15 seconds.
 406    *
 407    * @SINCE_1_0.0
 408    * @param[in] initialAutoRepeatingDelay in seconds.
 409    * @pre initialAutoRepeatingDelay must be greater than zero.
 410    */
 411   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay ) DALI_DEPRECATED_API;
 412
 413   /**
 414    * @DEPRECATED_1_1.32 GetProperty INITIAL_AUTO_REPEATING_DELAY
 415    *
 416    * @brief Gets the initial autorepeating delay in seconds.
 417    * @SINCE_1_0.0
 418    * @return the initial autorepeating delay in seconds.
 419    */
 420   float GetInitialAutoRepeatingDelay() const DALI_DEPRECATED_API;
 421
 422   /**
 423    * @DEPRECATED_1_1.32 SetProperty NEXT_AUTO_REPEATING_DELAY or Styling file
 424    *
 425    * @brief Sets the next autorepeating delay.
 426    *
 427    * By default this value is set to 0.05 seconds.
 428    *
 429    * @SINCE_1_0.0
 430    * @param[in] nextAutoRepeatingDelay in seconds.
 431    * @pre nextAutoRepeatingDelay must be greater than zero.
 432    */
 433   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay ) DALI_DEPRECATED_API;
 434
 435   /**
 436    * @DEPRECATED_1_1.32 GetProperty NEXT_AUTO_REPEATING_DELAY
 437    *
 438    * @brief Gets the next autorepeating delay in seconds.
 439    * @SINCE_1_0.0
 440    * @return the next autorepeating delay in seconds.
 441    */
 442   float GetNextAutoRepeatingDelay() const DALI_DEPRECATED_API;
 443
 444   /**
 445    * @DEPRECATED_1_1.32 SetProperty TOGGLABLE or Styling file
 446    *
 447    * @brief Sets the \e togglable property.
 448    *
 449    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 450    *
 451    * @SINCE_1_0.0
 452    * @param[in] togglable property.
 453    */
 454   void SetTogglableButton( bool togglable ) DALI_DEPRECATED_API;
 455
 456   /**
 457    * @DEPRECATED_1_1.32 GetProperty TOGGLABLE
 458    *
 459    * @brief Returns if the togglable property is set.
 460    * @SINCE_1_0.0
 461    * @return \e true if the \e togglable property is set.
 462    */
 463   bool IsTogglableButton() const DALI_DEPRECATED_API;
 464
 465   /**
 466    * @DEPRECATED_1_1.32 SetProperty SELECTED
 467    *
 468    * @brief Sets the button as selected or unselected.
 469    *
 470    * \e togglable property must be set to \e true.
 471    *
 472    * Emits a Button::StateChangedSignal() signal.
 473    *
 474    * @SINCE_1_0.0
 475    * @param[in] selected property.
 476    */
 477   void SetSelected( bool selected ) DALI_DEPRECATED_API;
 478
 479   /**
 480    * DEPRECATED_1_1.32  GetProperty SELECTED
 481    *
 482    * @brief Returns if the selected property is set and the button is togglable.
 483    * @SINCE_1_0.0
 484    * @return \e true if the button is \e selected.
 485    */
 486   bool IsSelected() const DALI_DEPRECATED_API;
 487
 488   /**
 489    * @DEPRECATED_1_1.32 Use Styling file to set animation
 490    *
 491    * @brief Sets the animation time.
 492    *
 493    * @SINCE_1_0.0
 494    * @param[in] animationTime The animation time in seconds.
 495    */
 496   void SetAnimationTime( float animationTime ) DALI_DEPRECATED_API;
 497
 498   /**
 499    * DEPRECATED_1_1.32 Use Styling file to set animation
 500    *
 501    * @brief Retrieves button's animation time.
 502    *
 503    * @SINCE_1_0.0
 504    * @return The animation time in seconds.
 505    */
 506   float GetAnimationTime() const DALI_DEPRECATED_API;
 507
 508   /**
 509    * @DEPRECATED_1_1.32 SetProperty Property::LABEL or Styling file
 510    *
 511    * @brief Sets the button's label.
 512    *
 513    * @SINCE_1_0.0
 514    * @param[in] label The label text.
 515    */
 516   void SetLabelText( const std::string& label ) DALI_DEPRECATED_API;
 517
 518   /**
 519    * DEPRECATED_1_1.32 GetProperty LABEL
 520    *
 521    * @brief Gets the label.
 522    *
 523    * @SINCE_1_0.0
 524    * @return The label text.
 525    */
 526   std::string GetLabelText() const DALI_DEPRECATED_API;
 527
 528   /**
 529    * @DEPRECATED_1_1.32 Use Styling file Property::UNSELECTED_STATE_IMAGE
 530    *
 531    * @brief Sets the unselected button image.
 532    *
 533    * @SINCE_1_0.0
 534    * @param[in] filename The button image.
 535    */
 536   void SetUnselectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 537
 538   /**
 539    * @DEPRECATED_1_1.32 Use styling
 540    * Use Property::UNSELECTED_BACKGROUND_VISUAL
 541    *
 542    * @brief Sets the unselected background image.
 543    *
 544    * @SINCE_1_0.0
 545    * @param[in] filename The background image.
 546    */
 547   void SetBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 548
 549   /**
 550    * @DEPRECATED_1_1.32 Use styling file, Property::SELECTED_STATE_IMAGE
 551    *
 552    * @brief Sets the selected image.
 553    *
 554    * @SINCE_1_0.0
 555    * @param[in] filename The selected image.
 556    */
 557   void SetSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 558
 559   /**
 560    * @DEPRECATED_1_2.32 Use styling file
 561    * Use Property::SELECTED_BACKGROUND_VISUAL
 562    *
 563    * @brief Sets the selected background image.
 564    *
 565    * @SINCE_1_0.0
 566    * @param[in] filename The selected background image.
 567    */
 568   void SetSelectedBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 569
 570   /**
 571    * @DEPRECATED_1_1.32 Use styling file
 572    * Use Property::DISABLED_SELECTED_BACKGROUND_VISUAL
 573    *
 574    * @brief Sets the disabled background image.
 575    *
 576    * @SINCE_1_0.0
 577    * @param[in] filename The disabled background image.
 578    */
 579   void SetDisabledBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 580
 581   /**
 582    * @DEPRECATED_1_1.32 Use styling file Property::DISABLED_STATE_IMAGE
 583    *
 584    * @brief Sets the disabled button image.
 585    *
 586    * @SINCE_1_0.0
 587    * @param[in] filename The disabled button image.
 588    */
 589   void SetDisabledImage( const std::string& filename ) DALI_DEPRECATED_API;
 590
 591   /**
 592    * @DEPRECATED_1_1.32 Use styling file
 593    * Use Property::DISABLED_SELECTED_VISUAL
 594    *
 595    * @brief Sets the disabled selected button image.
 596    *
 597    * @SINCE_1_0.0
 598    * @param[in] filename The disabled selected button image.
 599    */
 600   void SetDisabledSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 601
 602   /**
 603    * @DEPRECATED_1_0.50. Instead, use SetLabelText.
 604    *
 605    * @brief Sets the label with an actor.
 606    *
 607    * @SINCE_1_0.0
 608    * @param[in]  label The actor to use as a label
 609    */
 610   void SetLabel( Actor label ) DALI_DEPRECATED_API;
 611
 612   /**
 613    * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
 614    *
 615    * @brief Sets the button image.
 616    *
 617    * @SINCE_1_0.0
 618    * @param[in]  image The button image.
 619    */
 620   void SetButtonImage( Image image ) DALI_DEPRECATED_API;
 621
 622   /**
 623    * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
 624    *
 625    * @brief Sets the selected image.
 626    *
 627    * @SINCE_1_0.0
 628    * @param[in]  image The selected image.
 629    */
 630   void SetSelectedImage( Image image ) DALI_DEPRECATED_API;
 631
 632   /**
 633    * @DEPRECATED_1_0.50
 634    *
 635    * @brief Gets the button image.
 636    *
 637    * @SINCE_1_0.0
 638    * @remarks Avoid using this method as it's a legacy code.
 639    * @return     An actor with the button image.
 640    */
 641   Actor GetButtonImage() const DALI_DEPRECATED_API;
 642
 643   /**
 644    * @DEPRECATED_1_0.50
 645    *
 646    * @brief Gets the selected image.
 647    *
 648    * @SINCE_1_0.0
 649    * @remarks Avoid using this method as it's a legacy code.
 650    * @return     An actor with the selected image.
 651    */
 652   Actor GetSelectedImage() const DALI_DEPRECATED_API;
 653
 654 public: //Signals
 655
 656   /**
 657    * @brief Button signal type
 658    * @SINCE_1_0.0
 659    */
 660   typedef Signal< bool ( Button ) > ButtonSignalType;
 661
 662   /**
 663    * @brief This signal is emitted when the button is touched.
 664    *
 665    * A callback of the following type may be connected:
 666    * @code
 667    *   bool YourCallbackName( Button button );
 668    * @endcode
 669    * @SINCE_1_0.0
 670    * @return The signal to connect to.
 671    */
 672   ButtonSignalType& PressedSignal();
 673
 674   /**
 675    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
 676    *
 677    * A callback of the following type may be connected:
 678    * @code
 679    *   bool YourCallbackName( Button button );
 680    * @endcode
 681    * @SINCE_1_0.0
 682    * @return The signal to connect to.
 683    */
 684   ButtonSignalType& ReleasedSignal();
 685
 686   /**
 687    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
 688    *
 689    * A callback of the following type may be connected:
 690    * @code
 691    *   bool YourCallbackName( Button button );
 692    * @endcode
 693    * @SINCE_1_0.0
 694    * @return The signal to connect to.
 695    */
 696   ButtonSignalType& ClickedSignal();
 697
 698   /**
 699    * @brief This signal is emitted when the button's state is changed.
 700    *
 701    * The application can get the state by calling IsSelected().
 702    *
 703    * A callback of the following type may be connected:
 704    * @code
 705    *   bool YourCallbackName( Button button );
 706    * @endcode
 707    * @SINCE_1_0.0
 708    * @return The signal to connect to.
 709    */
 710   ButtonSignalType& StateChangedSignal();
 711
 712 public: // Not intended for application developers
 713
 714   /// @cond internal
 715   /**
 716    * @brief Creates a handle using the Toolkit::Internal implementation.
 717    *
 718    * @SINCE_1_0.0
 719    * @param[in]  implementation  The Control implementation.
 720    */
 721   DALI_INTERNAL Button( Internal::Button& implementation );
 722
 723   /**
 724    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 725    *
 726    * @SINCE_1_0.0
 727    * @param[in]  internal  A pointer to the internal CustomActor.
 728    */
 729   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
 730   /// @endcond
 731 };
 732
 733 /**
 734  * @}
 735  */
 736 } // namespace Toolkit
 737
 738 } // namespace Dali
 739
 740 #endif // __DALI_TOOLKIT_BUTTON_H__