dali-toolkit/devel-api/controls/buttons/toggle-button.h

   1 #ifndef DALI_TOOLKIT_TOGGLE_BUTTON_H
   2 #define DALI_TOOLKIT_TOGGLE_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 <dali-toolkit/public-api/controls/buttons/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 ToggleButton;
  35 } // namespace DALI_INTERNAL
  36 /**
  37  * @addtogroup dali_toolkit_controls_buttons
  38  * @{
  39  */
  40
  41 /**
  42  * @brief A ToggleButton allows the user to change a setting between two or more states.
  43  *
  44  * By default a ToggleButton emits a Button::StateChangedSignal() signal when it's clicked.
  45  *
  46  * Usage example: -
  47  *
  48  * @code
  49  *
  50  * void ToggleButtonExample::Create( Application& application )
  51  * {
  52  *   ToggleButton button = ToggleButton::New();
  53  *   button.SetProperty( Toolkit::ToggleButton::Property::STATE_VISUALS, Property::Array()
  54  *                       .Add( "A.png" )
  55  *                       .Add( "B.png" )
  56  *                       .Add( "C.png" ));
  57  *  or
  58  *
  59  *  Property::Map propertyMap1;
  60  *  Vector4 testColor1( 1.f, 0.5f, 0.3f, 0.2f );
  61  *  propertyMap1.Insert(Visual::Property::TYPE,  Visual::COLOR);
  62  *  propertyMap1.Insert(ColorVisual::Property::MIX_COLOR,  testColor1);
  63  *
  64  *  Property::Map propertyMap2;
  65  *  Vector4 testColor2( 0.5f, 1.f, 0.3f, 0.2f );
  66  *  propertyMap2.Insert(Visual::Property::TYPE,  Visual::COLOR);
  67  *  propertyMap2.Insert(ColorVisual::Property::MIX_COLOR,  testColor2);
  68  *
  69  *  Property::Map propertyMap3;
  70  *  Vector4 testColor3( 1.f, 0.5f, 1.f, 0.2f );
  71  *  propertyMap3.Insert(Visual::Property::TYPE,  Visual::COLOR);
  72  *  propertyMap3.Insert(ColorVisual::Property::MIX_COLOR,  testColor3);
  73  *
  74  *  button.SetProperty( Toolkit::ToggleButton::Property::STATE_VISUALS, Property::Array()
  75  *                       .Add( propertyMap1 )
  76  *                       .Add( propertyMap2 )
  77  *                       .Add( propertyMap3 ));
  78  *
  79  * button.SetProperty( Toolkit::ToggleButton::Property::TOOLTIPS, Property::Array()
  80  *                       .Add( "STATE A" )
  81  *                       .Add( "STATE B" )
  82  *                       .Add( "STATE C" ));
  83  *
  84  *   Stage::GetCurrent().Add( button );
  85  *
  86  *   // Connect to button signals emitted by the button
  87  *   button.ClickedSignal().Connect( this, &ToggleButtonExample::OnButtonClicked );
  88  * }
  89  *
  90  * bool ToggleButtonExample::OnButtonClicked( Button button )
  91  * {
  92  *   // Do something when the button is clicked
  93  *   return true;
  94  * }
  95  * @endcode
  96  *
  97  * See Button for more detail on signals and modifying states via properties.
  98  */
  99 class DALI_TOOLKIT_API ToggleButton : public Button
 100 {
 101 public:
 102   /**
 103    * @brief The start and end property ranges for this control.
 104    */
 105   enum PropertyRange
 106   {
 107     PROPERTY_START_INDEX = Button::PROPERTY_END_INDEX + 1, ///< Toggle button start index
 108     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000     ///< Reserving 1000 property indices
 109   };
 110
 111   /**
 112    * @brief An enumeration of properties belonging to the ToggleButton class.
 113    */
 114   struct Property
 115   {
 116     enum
 117     {
 118       /**
 119        * @brief The state visual array of toggle button.
 120        * @details Name "stateVisuals",  type Property::Array.
 121        * It's a property array of property-maps or a property array of strings,
 122        * property map expects a description of visual and
 123        * string represents an image url.
 124        * @note Mandatory
 125        */
 126       STATE_VISUALS = PROPERTY_START_INDEX,
 127
 128       /**
 129        * @brief The tooltips of toggle button.
 130        * @details Name "tooltips",  type Property::Array.
 131        * It's an array of toggle state tooltip strings.
 132        * Each tooltip string should match a toggle state strictly.
 133        * @note Mandatory
 134        */
 135       TOOLTIPS,
 136
 137       /**
 138        * @brief The current state index of toggle button.
 139        * @details Name "currentStateIndex",  type integer.
 140        * It just provides a property to get current state index.
 141        * @note Optional
 142        * @note The index is automatically changed when toggle button is clicked.
 143        */
 144       CURRENT_STATE_INDEX
 145     };
 146   };
 147
 148 public:
 149   /**
 150    * @brief Create an uninitialized ToggleButton; this can be initialized with ToggleButton::New().
 151    *
 152    * Calling member functions with an uninitialized Dali::Object is not allowed.
 153    */
 154   ToggleButton();
 155
 156   /**
 157    * @brief Copy constructor.
 158    * @param[in] toggleButton Handle to an object
 159    */
 160   ToggleButton(const ToggleButton& toggleButton);
 161
 162   /**
 163    * @brief Assignment operator.
 164    * @param[in] toggleButton Handle to an object
 165    * @return A reference to this
 166    */
 167   ToggleButton& operator=(const ToggleButton& toggleButton);
 168
 169   /**
 170    * @brief Destructor
 171    *
 172    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 173    */
 174   ~ToggleButton();
 175
 176   /**
 177    * @brief Create an initialized ToggleButton.
 178    *
 179    * @return A handle to a newly allocated Dali resource.
 180    */
 181   static ToggleButton New();
 182
 183   /**
 184    * @brief Downcast a handle to ToggleButton handle.
 185    *
 186    * If handle points to a ToggleButton the downcast produces valid
 187    * handle. If not the returned handle is left uninitialized.
 188    *
 189    * @param[in] handle Handle to an object
 190    * @return handle to a ToggleButton or an uninitialized handle
 191    */
 192   static ToggleButton DownCast(BaseHandle handle);
 193
 194 public: // Not intended for application developers
 195   /// @cond internal
 196   /**
 197    * @brief Creates a handle using the Toolkit::Internal implementation.
 198    *
 199    * @param[in]  implementation  The Control implementation.
 200    */
 201   DALI_INTERNAL ToggleButton(Internal::ToggleButton& implementation);
 202
 203   /**
 204    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 205    *
 206    * @param[in]  internal  A pointer to the internal CustomActor.
 207    */
 208   DALI_INTERNAL ToggleButton(Dali::Internal::CustomActor* internal);
 209   /// @endcond
 210 };
 211
 212 /**
 213  * @}
 214  */
 215 } // namespace Toolkit
 216
 217 } // namespace Dali
 218
 219 #endif // DALI_TOOLKIT_TOGGLE_BUTTON_H