inc/FUiCtrlProgress.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FUiCtrlProgress.h
  20  * @brief       This is the header file for the %Progress class.
  21  *
  22  * This header file contains the declarations of the %Progress class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_PROGRESS_H_
  26 #define _FUI_CTRL_PROGRESS_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FUiControl.h>
  31 #include <FUiContainer.h>
  32 #include <FUiCtrlControlsTypes.h>
  33
  34 namespace Tizen { namespace Ui { namespace Controls
  35 {
  36
  37 /**
  38  * @class       Progress
  39  * @brief       This class is an implementation of a %Progress control.
  40  *
  41  * @since       2.0
  42  *
  43  * The %Progress class displays the progress of a lengthy operation in a progress bar.
  44  *
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_progress.htm">Progress</a>.
  46  *
  47  * The following example demonstrates how to use the %Progress class.
  48  *
  49  * @code
  50 // Sample code for ProgressSample.h
  51 #include <FUi.h>
  52
  53 class ProgressSample
  54         : public Tizen::Ui::Controls::Form
  55         , public Tizen::Ui::IActionEventListener
  56 {
  57 public:
  58         ProgressSample(void)
  59         : __pProgress(null)
  60         , __pValue(0){}
  61
  62         bool Initialize(void);
  63         virtual result OnInitializing(void);
  64         virtual void OnActionPerformed(const Tizen::Ui::Control&, int);
  65
  66 private:
  67         static const int ID_BUTTON_CHECKED = 100;
  68
  69         Tizen::Ui::Controls::Progress* __pProgress;
  70         int __pValue;
  71 };
  72  *      @endcode
  73  *
  74  *      @code
  75 // Sample code for ProgressSample.cpp
  76 #include <FGraphics.h>
  77
  78 #include "ProgressSample.h"
  79
  80 using namespace Tizen::Graphics;
  81 using namespace Tizen::Ui::Controls;
  82
  83 bool
  84 ProgressSample::Initialize(void)
  85 {
  86         Construct(FORM_STYLE_NORMAL);
  87         return true;
  88 }
  89
  90 result
  91 ProgressSample::OnInitializing(void)
  92 {
  93         result r = E_SUCCESS;
  94
  95         // Creates an instance of Progress
  96         __pProgress = new Progress();
  97         __pProgress->Construct(Rectangle(50, 50, GetClientAreaBounds().width - 100, 100), 0, 100);
  98         __pProgress->SetValue(__pValue);
  99
 100         // Creates an instance of pButton to control progress value
 101         Button* pButton = new Button();
 102         pButton->Construct(Rectangle(50, 200, 150, 100), L"Here");
 103         pButton->SetActionId(ID_BUTTON_CHECKED);
 104         pButton->AddActionEventListener(*this);
 105
 106         // Adds the __pProgress and the pButton to the form
 107         AddControl(__pProgress);
 108         AddControl(pButton);
 109
 110         return r;
 111 }
 112
 113 void
 114 ProgressSample::OnActionPerformed(const Control& source, int actionId)
 115 {
 116         switch (actionId)
 117         {
 118         case ID_BUTTON_CHECKED :
 119                 {
 120                         if (__pValue >= 100)
 121                         {
 122                                 __pValue = 0;
 123                         }
 124                         else
 125                         {
 126                                 __pValue += 10;
 127                         }
 128                         __pProgress->SetValue(__pValue);
 129                         __pProgress->Invalidate(true);
 130                 }
 131                 break;
 132         default:
 133                 break;
 134         }
 135 }
 136  * @endcode
 137  *
 138  */
 139 class _OSP_EXPORT_ Progress
 140         : public Tizen::Ui::Control
 141 {
 142 public:
 143         /**
 144          * The object is not fully constructed after this constructor is called.  @n
 145          * For full construction, the %Construct() method must be called right after calling this constructor.
 146          *
 147          * @since       2.0
 148          */
 149         Progress(void);
 150
 151
 152         /**
 153          * This polymorphic destructor should be overridden if required.@n
 154          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 155          *
 156          * @since       2.0
 157          */
 158         virtual ~Progress(void);
 159
 160
 161         /**
 162          * Initializes this instance of %Progress with the specified parameters.
 163          *
 164          * @since               2.0
 165          *
 166          * @return              An error code
 167          * @param[in]   rect                            An instance of the Tizen::Graphics::Rectangle class @n
 168          *                                                          This instance represents the x and y coordinates of the top-left corner of the created window along with
 169          *                                  its width and height. @n
 170          *                                                                      The optimal size of the control is defined in
 171          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 172          * @param[in]   minValue                        The minimum value of the current instance of %Progress
 173          * @param[in]   maxValue                        The maximum value of the current instance of %Progress
 174          * @exception   E_SUCCESS                       The method is successful.
 175          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 176          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 177          *                                                                      The specified values should be positive and @c minValue should be less than @c maxValue.
 178          * @exception   E_SYSTEM                        A system error has occurred.
 179          * @remarks
 180          *                              - A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 181          *                              - The size of the control must be within the range defined by the minimum size and the maximum size.
 182          */
 183         result Construct(const Tizen::Graphics::Rectangle& rect, int minValue, int maxValue);
 184
 185         /**
 186          * Initializes this instance of %Progress with the specified parameters.
 187          *
 188          * @since               2.1
 189          *
 190          * @return              An error code
 191          * @param[in]   rect                            An instance of the Tizen::Graphics::FloatRectangle class @n
 192          *                                                          This instance represents the x and y coordinates of the top-left corner of the created window along with
 193          *                                  its width and height. @n
 194          *                                                                      The optimal size of the control is defined in
 195          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 196          * @param[in]   minValue                        The minimum value of the current instance of %Progress
 197          * @param[in]   maxValue                        The maximum value of the current instance of %Progress
 198          * @exception   E_SUCCESS                       The method is successful.
 199          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 200          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 201          *                                                                      The specified values should be positive and @c minValue should be less than @c maxValue.
 202          * @exception   E_SYSTEM                        A system error has occurred.
 203          * @remarks
 204          *                              - A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 205          *                              - The size of the control must be within the range defined by the minimum size and the maximum size.
 206          */
 207         result Construct(const Tizen::Graphics::FloatRectangle& rect, int minValue, int maxValue);
 208
 209 public:
 210         /**
 211          * Sets the current value of the %Progress control. @n
 212          * If the given value is greater than the @c maxValue with which %Progress is constructed, it will be set to %maxValue. The same applies for @c minValue.
 213          *
 214          * @since               2.0
 215          *
 216          * @param[in]   value   The current progress value
 217          */
 218         void SetValue(int value);
 219
 220
 221         /**
 222          * Sets the minimum and maximum value of the %Progress control.
 223          *
 224          * @since               2.0
 225          *
 226          * @return              An error code
 227          * @param[in]   minValue                        The minimum value of the current instance of %Progress
 228          * @param[in]   maxValue                        The maximum value of the current instance of %Progress
 229          * @exception   E_SUCCESS                       The method is successful.
 230          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 231          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 232          *                                                                      The specified values should be positive.
 233          * @exception   E_SYSTEM                        A system error has occurred.
 234          */
 235         result SetRange(int minValue, int maxValue);
 236
 237
 238         /**
 239          * Gets the current value of the %Progress control.
 240          *
 241          * @since       2.0
 242          *
 243          * @return      An integer value representing the current value of progress, @n
 244          *                      else @c -1 if an error occurs
 245          */
 246         int GetValue(void) const;
 247
 248
 249         /**
 250          * Gets the minimum value and the maximum value of the %Progress control.
 251          *
 252          * @since               2.0
 253          *
 254          * @param[out]  minValue        The minimum value
 255          * @param[out]  maxValue        The maximum value
 256         */
 257         void GetRange(int& minValue, int& maxValue) const;
 258
 259
 260         /**
 261          * Gets the percent value of the %Progress control.
 262          *
 263          * @since       2.0
 264          *
 265          * @return      The progress as a percentage, @n
 266          *                      else @c -1 if an error occurs
 267          */
 268         int GetPercentComplete(void) const;
 269
 270
 271         /**
 272          * Sets the color of the bar.
 273          *
 274          * @since     2.0
 275          *
 276          * @return    An error code
 277          * @param[in] color             The color to set
 278          * @exception E_SUCCESS         The method is successful.
 279          * @exception E_SYSTEM          A system error has occurred.
 280          * @remarks   The method ignores the alpha value of the @c color parameter and sets the alpha value to @c 255.
 281          */
 282         result SetBarColor(const Tizen::Graphics::Color& color);
 283
 284
 285         /**
 286          * Gets the color of the bar.
 287          *
 288          * @since     2.0
 289          *
 290          * @return    The color of the bar, @n
 291          *                        else RGBA(0, 0, 0, 0) if an error occurs
 292          * @exception E_SUCCESS         The method is successful.
 293          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 294          */
 295         Tizen::Graphics::Color GetBarColor(void) const;
 296
 297
 298         /**
 299          * Sets the background color of the bar.
 300          *
 301          * @since     2.1
 302          *
 303          * @param[in] barBackgroundColor             The color to set
 304          * @remarks   The method ignores the alpha value of the @c color parameter and sets the alpha value to @c 255.
 305          * @see GetBarBackgroundColor()
 306          */
 307         void SetBarBackgroundColor(const Tizen::Graphics::Color& barBackgroundColor);
 308
 309         /**
 310          * Gets the background color of the bar.
 311          *
 312          * @since     2.1
 313          *
 314          * @return    The background color of the bar, @n
 315          *                        else RGBA(0, 0, 0, 0) if an error occurs
 316          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 317          * @see SetBarBackgroundColor()
 318          */
 319         Tizen::Graphics::Color GetBarBackgroundColor(void) const;
 320
 321
 322 private:
 323         //
 324         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 325         //
 326         Progress(const Progress& rhs);
 327
 328         //
 329         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 330         //
 331         Progress& operator =(const Progress& rhs);
 332
 333         friend class _ProgressImpl;
 334
 335 };  // Progress
 336
 337 }}} // Tizen::Ui::Controls
 338
 339 #endif // _FUI_CTRL_PROGRESS_H_