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