dali-toolkit/public-api/controls/progress-bar/progress-bar.h

   1 #ifndef DALI_TOOLKIT_PROGRESS_BAR_H
   2 #define DALI_TOOLKIT_PROGRESS_BAR_H
   3
   4 /*
   5  * Copyright (c) 2017 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/control.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 class ProgressBar;
  33 }
  34 /**
  35  * @addtogroup dali_toolkit_controls_progress_bar
  36  * @{
  37  */
  38
  39 /**
  40  * @brief ProgressBar is a control to give the user an indication of the progress of an operation.
  41  * *
  42  *     Determinate Progress State
  43  *
  44  *      #  : Progress visual
  45  *      *  : Secondary Progress visual
  46  *      =  : Track visual
  47  *     40% : Label visual
  48  *
  49  *     =============================================
  50  *     = ###############**** 40%                   =
  51  *     =============================================
  52  *
  53  *     Indeterminate Progress State
  54  *
  55  *      /  : Indeterminate visual
  56  *
  57  *     =============================================
  58  *     = ///////////////////////////////////////// =
  59  *     =============================================
  60  *
  61  * Also progress value percentage is shown as text inside the progress bar.
  62  * Signals
  63  * | %Signal Name      | Method                        |
  64  * |-------------------|-------------------------------|
  65  * | valueChanged      | @ref ValueChangedSignal()     |
  66  *
  67  * @SINCE_1_2.60
  68  */
  69
  70 class DALI_IMPORT_API ProgressBar : public Control
  71 {
  72 public:
  73
  74   // Properties
  75
  76   /**
  77    * @brief The start and end property ranges for this control.
  78    * @SINCE_1_2.60
  79    */
  80   enum PropertyRange
  81   {
  82     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< Start Index. @SINCE_1_2.60
  83     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices. @SINCE_1_2.60
  84   };
  85
  86   /**
  87    * @brief An enumeration of properties belonging to the ProgressBar class.
  88    * @SINCE_1_2.60
  89    */
  90   struct Property
  91   {
  92     enum
  93     {
  94       /**
  95        * @brief The progress value of progress bar, progress runs form 0 to 1.
  96        * @details Name "progressValue", type Property::FLOAT.
  97        * @SINCE_1_2.60
  98        * @note Optional. If not supplied, the default is 0.
  99        * @note Value should be between 0 to 1.
 100        * @note If Value is set to 0, progress bar will be set to beginning.
 101        * @note If Value is set to 1, progress bar will be set to end.
 102        * @note Any Value outside of the range is ignored.
 103        */
 104       PROGRESS_VALUE = PROPERTY_START_INDEX,
 105
 106       /**
 107        * @brief The secondary progress value of progress bar, secondary progress runs form 0 to 1.
 108        * @details Name "secondaryProgressValue", type Property::FLOAT.
 109        * @SINCE_1_2.60
 110        * @note Optional. If not supplied, the default is 0.
 111        * @note Value should be between 0 to 1.
 112        * @note If Value is set to 0, progress bar will be set secondary progress to beginning.
 113        * @note If Value is set to 1, progress bar will be set secondary progress to end.
 114        * @note Any Value outside of the range is ignored.
 115        */
 116       SECONDARY_PROGRESS_VALUE,
 117
 118       /**
 119        * @brief Sets the progress-bar as \e indeterminate state.
 120        * @details name "indeterminate", type Property::BOOLEAN.
 121        * @SINCE_1_2.60
 122        */
 123       INDETERMINATE,
 124
 125       /**
 126        * @brief The track Visual value of progress bar, it's a full progress area and it's shown behind PROGRESS_VISUAL.
 127        * @details Name "trackVisual", type Property::MAP or Property::STRING (url to image).
 128        * @SINCE_1_2.60
 129        * @note Optional. If not supplied, the default track visual will be shown.
 130        */
 131       TRACK_VISUAL,
 132
 133       /**
 134        * @brief The progress Visual value of progress bar, size of the progress visual is changed based on PROGRESS_VALUE.
 135        * @details Name "progressVisual", type Property::MAP or Property::STRING (url to image).
 136        * @SINCE_1_2.60
 137        * @note Optional. If not supplied, the default progress visual will be shown.
 138        */
 139       PROGRESS_VISUAL,
 140
 141       /**
 142        * @brief The secondary progress visual of progress bar, size of the secondary progress visual is changed based on SECONDARY_PROGRESS_VALUE.
 143        * @details Name "secondaryProgressVisual", type Property::MAP or Property::STRING (url to image).
 144        * @SINCE_1_2.60
 145        * @note Optional. If not supplied, the secondary progress visual will not be shown.
 146        */
 147       SECONDARY_PROGRESS_VISUAL,
 148
 149       /**
 150        * @brief The indeterminate visual of progress bar.
 151        * @details Name "inditerminateVisual", type Property::MAP or Property::STRING (url to image).
 152        * @SINCE_1_2.60
 153        * @note Optional. If not supplied, the default indeterminate visual will be shown.
 154        */
 155       INDETERMINATE_VISUAL,
 156
 157       /**
 158        * @brief The transition data for indeterminate visual animation.
 159        * @details Name "indeterminateVisualAnimation", type Property::MAP or Property::ARRAY.
 160        * @SINCE_1_2.60
 161        * @note Optional. If not supplied, default animation will be played.
 162        */
 163       INDETERMINATE_VISUAL_ANIMATION,
 164
 165       /**
 166        * @brief The Label visual of progress bar.
 167        * @details Name "labelVisual", type Property::MAP.
 168        * @SINCE_1_2.60
 169        */
 170       LABEL_VISUAL,
 171     };
 172   };
 173
 174 public:
 175
 176   /**
 177    * @brief Creates the ProgressBar control.
 178    * @SINCE_1_2.60
 179    * @return A handle to the ProgressBar control
 180    */
 181   static ProgressBar New();
 182
 183   /**
 184    * @brief Creates an empty ProgressBar handle.
 185    * @SINCE_1_2.60
 186    */
 187   ProgressBar();
 188
 189   /**
 190    * @brief Copy constructor.
 191    *
 192    * Creates another handle that points to the same real object.
 193    * @SINCE_1_2.60
 194    */
 195   ProgressBar( const ProgressBar& handle );
 196
 197   /**
 198    * @brief Assignment operator.
 199    *
 200    * Changes this handle to point to another real object.
 201    * @SINCE_1_2.60
 202    */
 203   ProgressBar& operator=( const ProgressBar& handle );
 204
 205   /**
 206    * @brief Destructor.
 207    *
 208    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 209    * @SINCE_1_2.60
 210    */
 211   ~ProgressBar();
 212
 213   /**
 214    * @brief Downcast an Object handle to ProgressBar.
 215    *
 216    * If handle points to a ProgressBar the
 217    * downcast produces valid handle. If not the returned handle is left uninitialized.
 218    * @SINCE_1_2.60
 219    * @param[in] handle Handle to an object
 220    * @return handle to a ProgressBar or an uninitialized handle
 221    */
 222   static ProgressBar DownCast( BaseHandle handle );
 223
 224 public:  // Signals
 225
 226   /**
 227    * @brief Value changed signal type.
 228    * @SINCE_1_2.60
 229    */
 230   typedef Signal< void ( ProgressBar, float, float ) > ValueChangedSignalType;
 231
 232   /**
 233    * @brief Signal emitted when the ProgressBar value changes.
 234    *
 235    * A callback of the following type may be connected:
 236    * @code
 237    *   void YourCallbackName( ProgressBar progressBar, float progressValue, float secondaryProgressValue );
 238    * @endcode
 239    * @SINCE_1_2.60
 240    * @return The signal to connect to
 241    */
 242   ValueChangedSignalType& ValueChangedSignal();
 243
 244 public: // Not intended for application developers
 245
 246   /// @cond internal
 247   /**
 248    * @brief Creates a handle using the Toolkit::Internal implementation.
 249    * @param[in]  implementation  The Control implementation
 250    */
 251   DALI_INTERNAL ProgressBar(Internal::ProgressBar& implementation);
 252
 253   /**
 254    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 255    * @param[in]  internal  A pointer to the internal CustomActor
 256    */
 257   explicit DALI_INTERNAL ProgressBar( Dali::Internal::CustomActor* internal );
 258   /// @endcond
 259 };
 260
 261 /**
 262  * @}
 263  */
 264 } // namespace Toolkit
 265
 266 } // namespace Dali
 267
 268 #endif // DALI_TOOLKIT_PROGRESS_BAR_H