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) 2020 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.SetProperty( Actor::Property::PARENT_ORIGIN, ParentOrigin::CENTER );
  57  *   button.SetProperty( Button::Property::LABEL, "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 details on signals and modifying appearance via properties.
  86  * @SINCE_1_0.0
  87  */
  88 class DALI_TOOLKIT_API PushButton : public Button
  89 {
  90 public:
  91
  92   /**
  93    * @brief Enumeration for 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 Enumeration for the instance of properties belonging to the PushButton class.
 104    * @SINCE_1_0.0
 105    */
 106   struct Property
 107   {
 108     /**
 109      * @brief Enumeration for the instance of properties belonging to the PushButton class.
 110      * @SINCE_1_0.0
 111      */
 112     enum
 113     {
 114       LABEL_PADDING = PROPERTY_START_INDEX,   ///< Property, name "labelPadding",    type Vector4 @SINCE_1_0.0
 115       ICON_PADDING,                           ///< Property, name "iconPadding",     type Vector4 @SINCE_1_0.0
 116     };
 117   };
 118
 119 public:
 120
 121   /**
 122    * @brief Creates an uninitialized PushButton; this can be initialized with PushButton::New().
 123    *
 124    * Calling member functions with an uninitialized Dali::Object is not allowed.
 125    * @SINCE_1_0.0
 126    */
 127   PushButton();
 128
 129   /**
 130    * @brief Copy constructor.
 131    * @SINCE_1_0.0
 132    * @param[in] pushButton Handle to an object
 133    */
 134   PushButton( const PushButton& pushButton );
 135
 136   /**
 137    * @brief Move constructor
 138    * @SINCE_1_9.23
 139    *
 140    * @param[in] rhs A reference to the moved handle
 141    */
 142   PushButton( PushButton&& rhs );
 143
 144   /**
 145    * @brief Assignment operator.
 146    * @SINCE_1_0.0
 147    * @param[in] pushButton Handle to an object
 148    * @return A reference to this
 149    */
 150   PushButton& operator=( const PushButton& pushButton );
 151
 152   /**
 153    * @brief Move assignment
 154    * @SINCE_1_9.23
 155    *
 156    * @param[in] rhs A reference to the moved handle
 157    * @return A reference to this
 158    */
 159   PushButton& operator=( PushButton&& rhs );
 160
 161   /**
 162    * @brief Destructor.
 163    *
 164    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 165    * @SINCE_1_0.0
 166    */
 167   ~PushButton();
 168
 169   /**
 170    * @brief Creates an initialized PushButton.
 171    *
 172    * @SINCE_1_0.0
 173    * @return A handle to a newly allocated Dali resource
 174    */
 175   static PushButton New();
 176
 177   /**
 178    * @brief Downcasts a handle to PushButton handle.
 179    *
 180    * If handle points to a PushButton, the downcast produces valid handle.
 181    * If not, the returned handle is left uninitialized.
 182    *
 183    * @SINCE_1_0.0
 184    * @param[in] handle Handle to an object
 185    * @return handle to a PushButton or an uninitialized handle
 186    */
 187   static PushButton DownCast( BaseHandle handle );
 188
 189 public: // Not intended for application developers
 190
 191   /// @cond internal
 192   /**
 193    * @brief Creates a handle using the Toolkit::Internal implementation.
 194    *
 195    * @SINCE_1_0.0
 196    * @param[in] implementation The Control implementation
 197    */
 198   DALI_INTERNAL PushButton( Internal::PushButton& implementation );
 199
 200   /**
 201    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 202    *
 203    * @SINCE_1_0.0
 204    * @param[in] internal A pointer to the internal CustomActor
 205    */
 206   DALI_INTERNAL PushButton( Dali::Internal::CustomActor* internal );
 207   /// @endcond
 208 };
 209
 210 /**
 211  * @}
 212  */
 213 } // namespace Toolkit
 214
 215 } // namespace Dali
 216
 217 #endif // DALI_TOOLKIT_PUSH_BUTTON_H