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

   1 #ifndef __DALI_TOOLKIT_PUSH_BUTTON_H__
   2 #define __DALI_TOOLKIT_PUSH_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 "button.h"
  23
  24 namespace Dali
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 // Forward declarations
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 // Forward declarations
  35
  36 class PushButton;
  37 }
  38 /**
  39  * @addtogroup dali_toolkit_controls_buttons
  40  * @{
  41  */
  42
  43 /**
  44  * @brief A PushButton changes its appearance when is pressed and returns to its original when is released.
  45  *
  46  * By default a PushButton emits a Button::PressedSignal() signal when the button is pressed, a Button::ClickedSignal() signal when it's clicked
  47  * and a Button::ReleasedSignal() signal when it's released or having pressed it, the touch point leaves the boundary of the button.
  48  *
  49  * Usage example: -
  50  *
  51  * @code
  52  * // in Creating a DALi Application
  53  * void HelloWorldExample::Create( Application& application )
  54  * {
  55  *   PushButton button = PushButton::New();
  56  *   button.SetParentOrigin( ParentOrigin::CENTER );
  57  *   button.SetLabelText( "Press" );
  58  *   Stage::GetCurrent().Add( button );
  59  *
  60  *   // Connect to button signals emitted by the button
  61  *   button.ClickedSignal().Connect( this, &HelloWorldExample::OnButtonClicked );
  62  *   button.PressedSignal().Connect( this, &HelloWorldExample::OnButtonPressed );
  63  *   button.ReleasedSignal().Connect( this, &HelloWorldExample::OnButtonReleased );
  64  * }
  65  *
  66  * bool HelloWorldExample::OnButtonClicked( Button button )
  67  * {
  68  *   // Do something when the button is clicked
  69  *   return true;
  70  * }
  71  *
  72  * bool HelloWorldExample::OnButtonPressed( Button button )
  73  * {
  74  *   // Do something when the button is pressed
  75  *   return true;
  76  * }
  77  *
  78  * bool HelloWorldExample::OnButtonReleased( Button button )
  79  * {
  80  *   // Do something when the button is released
  81  *   return true;
  82  * }
  83  * @endcode
  84  *
  85  * See Button for more detail on signals and modifying appearance via properties.
  86  * @SINCE_1_0.0
  87  */
  88 class DALI_IMPORT_API PushButton : public Button
  89 {
  90 public:
  91
  92   /**
  93    * @brief The start and end property ranges for this control.
  94    * @SINCE_1_0.0
  95    */
  96   enum PropertyRange
  97   {
  98     PROPERTY_START_INDEX = Button::PROPERTY_END_INDEX + 1,          ///< @SINCE_1_0.0
  99     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserving 1000 property indices @SINCE_1_0.0
 100   };
 101
 102   /**
 103    * @brief An enumeration of properties belonging to the PushButton class.
 104    * @SINCE_1_0.0
 105    */
 106   struct Property
 107   {
 108     enum
 109     {
 110       UNSELECTED_ICON = PROPERTY_START_INDEX, ///< Property, name "unselectedIcon",  type std::string @SINCE_1_0.0
 111       SELECTED_ICON,                          ///< Property, name "selectedIcon",    type std::string @SINCE_1_0.0
 112       ICON_ALIGNMENT,                         ///< Property, name "iconAlignment",   type std::string @SINCE_1_0.0
 113       LABEL_PADDING,                          ///< Property, name "labelPadding",    type Vector4 @SINCE_1_0.0
 114       ICON_PADDING,                           ///< Property, name "iconPadding",     type Vector4 @SINCE_1_0.0
 115     };
 116   };
 117
 118 public:
 119
 120   /**
 121    * @brief Create an uninitialized PushButton; this can be initialized with PushButton::New().
 122    *
 123    * Calling member functions with an uninitialized Dali::Object is not allowed.
 124    * @SINCE_1_0.0
 125    */
 126   PushButton();
 127
 128   /**
 129    * @brief Copy constructor.
 130    * @SINCE_1_0.0
 131    */
 132   PushButton( const PushButton& pushButton );
 133
 134   /**
 135    * @brief Assignment operator.
 136    * @SINCE_1_0.0
 137    */
 138   PushButton& operator=( const PushButton& pushButton );
 139
 140   /**
 141    * @brief Destructor
 142    *
 143    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 144    * @SINCE_1_0.0
 145    */
 146   ~PushButton();
 147
 148   /**
 149    * @brief Create an initialized PushButton.
 150    *
 151    * @SINCE_1_0.0
 152    * @return A handle to a newly allocated Dali resource.
 153    */
 154   static PushButton New();
 155
 156   /**
 157    * @brief Downcast a handle to PushButton handle.
 158    *
 159    * If handle points to a PushButton the downcast produces valid
 160    * handle. If not the returned handle is left uninitialized.
 161    *
 162    * @SINCE_1_0.0
 163    * @param[in] handle Handle to an object
 164    * @return handle to a PushButton or an uninitialized handle
 165    */
 166   static PushButton DownCast( BaseHandle handle );
 167
 168
 169   // Deprecated API
 170
 171   using Button::SetButtonImage;
 172
 173   /**
 174    * @DEPRECATED_1_0.50. Instead, use Button::SetUnselectedImage.
 175    *
 176    * @brief Sets the unselected image with an Actor.
 177    *
 178    * @SINCE_1_0.0
 179    * @param[in] image The Actor to use.
 180    */
 181   void SetButtonImage( Actor image );
 182
 183   using Button::SetBackgroundImage;
 184
 185   /**
 186    * @DEPRECATED_1_0.50. Instead, use Button::SetBackgroundImage.
 187    *
 188    * @brief Sets the background image with an Actor.
 189    *
 190    * @SINCE_1_0.0
 191    * @param[in] image The Actor to use.
 192    */
 193   void SetBackgroundImage( Actor image );
 194
 195   using Button::SetSelectedImage;
 196
 197   /**
 198    * @DEPRECATED_1_0.50. Instead, use Button::SetSelectedImage( const std::string& filename ).
 199    *
 200    * @brief Sets the selected image with an Actor.
 201    *
 202    * @SINCE_1_0.0
 203    * @param[in] image The Actor to use.
 204    */
 205   void SetSelectedImage( Actor image );
 206
 207   using Button::SetSelectedBackgroundImage;
 208
 209   /**
 210    * @DEPRECATED_1_0.50. Instead, use Button::SetSelectedBackgroundImage.
 211    *
 212    * @brief Sets the selected background image with an Actor.
 213    *
 214    * @SINCE_1_0.0
 215    * @param[in] image The Actor to use.
 216    */
 217   void SetSelectedBackgroundImage( Actor image );
 218
 219   using Button::SetDisabledBackgroundImage;
 220
 221   /**
 222    * @DEPRECATED_1_0.50. Instead, use Button::SetDisabledBackgroundImage.
 223    *
 224    * @brief Sets the disabled background image with an Actor.
 225    *
 226    * @SINCE_1_0.0
 227    * @param[in] image The Actor to use.
 228    */
 229   void SetDisabledBackgroundImage( Actor image );
 230
 231   using Button::SetDisabledImage;
 232
 233   /**
 234    * @DEPRECATED_1_0.50. Instead, use Button::SetDisabledImage.
 235    *
 236    * @brief Sets the disabled image with an Actor.
 237    *
 238    * @SINCE_1_0.0
 239    * @param[in] image The Actor to use.
 240    */
 241   void SetDisabledImage( Actor image );
 242
 243   using Button::SetDisabledSelectedImage;
 244
 245   /**
 246    * @DEPRECATED_1_0.50. Instead, use Button::SetDisabledSelectedImage.
 247    *
 248    * @brief Sets the disabled selected image with an Actor.
 249    *
 250    * @SINCE_1_0.0
 251    * @param[in] image The Actor to use.
 252    */
 253   void SetDisabledSelectedImage( Actor image );
 254
 255
 256 public: // Not intended for application developers
 257
 258   /// @cond internal
 259   /**
 260    * @brief Creates a handle using the Toolkit::Internal implementation.
 261    *
 262    * @SINCE_1_0.0
 263    * @param[in]  implementation  The Control implementation.
 264    */
 265   DALI_INTERNAL PushButton( Internal::PushButton& implementation );
 266
 267   /**
 268    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 269    *
 270    * @SINCE_1_0.0
 271    * @param[in]  internal  A pointer to the internal CustomActor.
 272    */
 273   DALI_INTERNAL PushButton( Dali::Internal::CustomActor* internal );
 274   /// @endcond
 275 };
 276
 277 /**
 278  * @}
 279  */
 280 } // namespace Toolkit
 281
 282 } // namespace Dali
 283
 284 #endif // __DALI_TOOLKIT_PUSH_BUTTON_H__