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 namespace Toolkit
  27 {
  28 // Forward declarations
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 // Forward declarations
  33
  34 class PushButton;
  35 } // namespace DALI_INTERNAL
  36 /**
  37  * @addtogroup dali_toolkit_controls_buttons
  38  * @{
  39  */
  40
  41 /**
  42  * @brief A PushButton changes its appearance when is pressed and returns to its original when is released.
  43  *
  44  * By default, a PushButton emits a Button::PressedSignal() signal when the button is pressed, a Button::ClickedSignal() signal when it's clicked.
  45  * and a Button::ReleasedSignal() signal when it's released or having pressed it, the touch point leaves the boundary of the button.
  46  *
  47  * Usage example: -
  48  *
  49  * @code
  50  * // in Creating a DALi Application
  51  * void HelloWorldExample::Create( Application& application )
  52  * {
  53  *   PushButton button = PushButton::New();
  54  *   button.SetProperty( Actor::Property::PARENT_ORIGIN, ParentOrigin::CENTER );
  55  *   button.SetProperty( Button::Property::LABEL, "Press" );
  56  *   Stage::GetCurrent().Add( button );
  57  *
  58  *   // Connect to button signals emitted by the button
  59  *   button.ClickedSignal().Connect( this, &HelloWorldExample::OnButtonClicked );
  60  *   button.PressedSignal().Connect( this, &HelloWorldExample::OnButtonPressed );
  61  *   button.ReleasedSignal().Connect( this, &HelloWorldExample::OnButtonReleased );
  62  * }
  63  *
  64  * bool HelloWorldExample::OnButtonClicked( Button button )
  65  * {
  66  *   // Do something when the button is clicked
  67  *   return true;
  68  * }
  69  *
  70  * bool HelloWorldExample::OnButtonPressed( Button button )
  71  * {
  72  *   // Do something when the button is pressed
  73  *   return true;
  74  * }
  75  *
  76  * bool HelloWorldExample::OnButtonReleased( Button button )
  77  * {
  78  *   // Do something when the button is released
  79  *   return true;
  80  * }
  81  * @endcode
  82  *
  83  * See Button for more details on signals and modifying appearance via properties.
  84  * @SINCE_1_0.0
  85  */
  86 class DALI_TOOLKIT_API PushButton : public Button
  87 {
  88 public:
  89   /**
  90    * @brief Enumeration for the start and end property ranges for this control.
  91    * @SINCE_1_0.0
  92    */
  93   enum PropertyRange
  94   {
  95     PROPERTY_START_INDEX = Button::PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  96     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000     ///< Reserving 1000 property indices @SINCE_1_0.0
  97   };
  98
  99   /**
 100    * @brief Enumeration for the instance of properties belonging to the PushButton class.
 101    * @SINCE_1_0.0
 102    */
 103   struct Property
 104   {
 105     /**
 106      * @brief Enumeration for the instance of properties belonging to the PushButton class.
 107      * @SINCE_1_0.0
 108      */
 109     enum
 110     {
 111       LABEL_PADDING = PROPERTY_START_INDEX, ///< Property, name "labelPadding",    type Vector4 @SINCE_1_0.0
 112       ICON_PADDING,                         ///< Property, name "iconPadding",     type Vector4 @SINCE_1_0.0
 113     };
 114   };
 115
 116 public:
 117   /**
 118    * @brief Creates an uninitialized PushButton; this can be initialized with PushButton::New().
 119    *
 120    * Calling member functions with an uninitialized Dali::Object is not allowed.
 121    * @SINCE_1_0.0
 122    */
 123   PushButton();
 124
 125   /**
 126    * @brief Copy constructor.
 127    * @SINCE_1_0.0
 128    * @param[in] pushButton Handle to an object
 129    */
 130   PushButton(const PushButton& pushButton);
 131
 132   /**
 133    * @brief Move constructor
 134    * @SINCE_1_9.23
 135    *
 136    * @param[in] rhs A reference to the moved handle
 137    */
 138   PushButton(PushButton&& rhs);
 139
 140   /**
 141    * @brief Assignment operator.
 142    * @SINCE_1_0.0
 143    * @param[in] pushButton Handle to an object
 144    * @return A reference to this
 145    */
 146   PushButton& operator=(const PushButton& pushButton);
 147
 148   /**
 149    * @brief Move assignment
 150    * @SINCE_1_9.23
 151    *
 152    * @param[in] rhs A reference to the moved handle
 153    * @return A reference to this
 154    */
 155   PushButton& operator=(PushButton&& rhs);
 156
 157   /**
 158    * @brief Destructor.
 159    *
 160    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 161    * @SINCE_1_0.0
 162    */
 163   ~PushButton();
 164
 165   /**
 166    * @brief Creates an initialized PushButton.
 167    *
 168    * @SINCE_1_0.0
 169    * @return A handle to a newly allocated Dali resource
 170    */
 171   static PushButton New();
 172
 173   /**
 174    * @brief Downcasts a handle to PushButton handle.
 175    *
 176    * If handle points to a PushButton, the downcast produces valid handle.
 177    * If not, the returned handle is left uninitialized.
 178    *
 179    * @SINCE_1_0.0
 180    * @param[in] handle Handle to an object
 181    * @return handle to a PushButton or an uninitialized handle
 182    */
 183   static PushButton DownCast(BaseHandle handle);
 184
 185 public: // Not intended for application developers
 186   /// @cond internal
 187   /**
 188    * @brief Creates a handle using the Toolkit::Internal implementation.
 189    *
 190    * @SINCE_1_0.0
 191    * @param[in] implementation The Control implementation
 192    */
 193   DALI_INTERNAL PushButton(Internal::PushButton& implementation);
 194
 195   /**
 196    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 197    *
 198    * @SINCE_1_0.0
 199    * @param[in] internal A pointer to the internal CustomActor
 200    */
 201   DALI_INTERNAL PushButton(Dali::Internal::CustomActor* internal);
 202   /// @endcond
 203 };
 204
 205 /**
 206  * @}
 207  */
 208 } // namespace Toolkit
 209
 210 } // namespace Dali
 211
 212 #endif // DALI_TOOLKIT_PUSH_BUTTON_H