inc/FUiCtrlProgress.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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. For full construction, the Construct() method must be called right after calling this constructor.
 145          *
 146          * @since       2.0
 147          */
 148         Progress(void);
 149
 150
 151         /**
 152          * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called when the destructor of this interface is called.
 153          *
 154          * @since       2.0
 155          */
 156         virtual ~Progress(void);
 157
 158
 159         /**
 160          * Initializes this instance of %Progress with the specified parameters.
 161          *
 162          * @since               2.0
 163          *
 164          * @return              An error code
 165          * @param[in]   rect                            An instance of the Rectangle class @n
 166          *                                                          This instance represents the x and y coordinates of the top-left corner of the created window along with
 167          *                                  its width and height.
 168          * @param[in]   minValue                        The minimum value of the current instance of %Progress
 169          * @param[in]   maxValue                        The maximum value of the current instance of %Progress
 170          * @exception   E_SUCCESS                       The method is successful.
 171          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 172          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 173          *                                                                      The specified values should be positive and @c minValue should be less than @c maxValue.
 174          * @exception   E_SYSTEM                        A system error has occurred.
 175          * @remarks     A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier. @n
 176          * @remarks     The size of the control must be within the range defined by the minimum size and the maximum size.
 177          */
 178         result Construct(const Tizen::Graphics::Rectangle& rect, int minValue, int maxValue);
 179
 180         /**
 181          * Initializes this instance of %Progress with the specified parameters.
 182          *
 183          * @since               2.1
 184          *
 185          * @return              An error code
 186          * @param[in]   rect                            An instance of the FloatRectangle class @n
 187          *                                                          This instance represents the x and y coordinates of the top-left corner of the created window along with
 188          *                                  its width and height.
 189          * @param[in]   minValue                        The minimum value of the current instance of %Progress
 190          * @param[in]   maxValue                        The maximum value of the current instance of %Progress
 191          * @exception   E_SUCCESS                       The method is successful.
 192          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 193          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 194          *                                                                      The specified values should be positive and @c minValue should be less than @c maxValue.
 195          * @exception   E_SYSTEM                        A system error has occurred.
 196          * @remarks     A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier. @n
 197          * @remarks     The size of the control must be within the range defined by the minimum size and the maximum size.
 198          */
 199         result Construct(const Tizen::Graphics::FloatRectangle& rect, int minValue, int maxValue);
 200
 201 public:
 202         /**
 203          * Sets the current value of the %Progress control. @n
 204          * 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.
 205          *
 206          * @since               2.0
 207          *
 208          * @param[in]   value   The current progress value
 209          */
 210         void SetValue(int value);
 211
 212
 213         /**
 214          * Sets the minimum and maximum value of the %Progress control.
 215          *
 216          * @since               2.0
 217          *
 218          * @return              An error code
 219          * @param[in]   minValue                        The minimum value of the current instance of %Progress
 220          * @param[in]   maxValue                        The maximum value of the current instance of %Progress
 221          * @exception   E_SUCCESS                       The method is successful.
 222          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 223          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 224          *                                                                      The specified values should be positive.
 225          * @exception   E_SYSTEM                        A system error has occurred.
 226          */
 227         result SetRange(int minValue, int maxValue);
 228
 229
 230         /**
 231          * Gets the current value of the %Progress control.
 232          *
 233          * @since       2.0
 234          *
 235          * @return      An integer value representing the current value of progress, @n
 236          *                      else @c -1 if an error occurs
 237          */
 238         int GetValue(void) const;
 239
 240
 241         /**
 242          * Gets the minimum value and the maximum value of the %Progress control.
 243          *
 244          * @since               2.0
 245          *
 246          * @param[out]  minValue        The minimum value
 247          * @param[out]  maxValue        The maximum value
 248         */
 249         void GetRange(int& minValue, int& maxValue) const;
 250
 251
 252         /**
 253          * Gets the percent value of the %Progress control.
 254          *
 255          * @since       2.0
 256          *
 257          * @return      The progress as a percentage, @n
 258          *                      else @c -1 if an error occurs
 259          */
 260         int GetPercentComplete(void) const;
 261
 262
 263         /**
 264          * Sets the color of the bar.
 265          *
 266          * @since     2.0
 267          *
 268          * @return    An error code
 269          * @param[in] color             The color to set
 270          * @exception E_SUCCESS         The method is successful.
 271          * @exception E_SYSTEM          A system error has occurred.
 272          * @remarks   The method ignores the alpha value of the @c color parameter and sets the alpha value to @c 255.
 273          */
 274         result SetBarColor(const Tizen::Graphics::Color& color);
 275
 276
 277         /**
 278          * Gets the color of the bar.
 279          *
 280          * @since     2.0
 281          *
 282          * @return    The color of the bar, @n
 283          *                        else RGBA(0, 0, 0, 0) if an error occurs
 284          * @exception E_SUCCESS         The method is successful.
 285          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 286          */
 287         Tizen::Graphics::Color GetBarColor(void) const;
 288
 289
 290         /**
 291          * Sets the background color of the bar.
 292          *
 293          * @since     2.1
 294          *
 295          * @param[in] color             The color to be set
 296          * @remarks   The method ignores the alpha value of the @c color parameter and sets the alpha value to @c 255.
 297          * @see GetBarBackgroundColor()
 298          */
 299         void SetBarBackgroundColor(const Tizen::Graphics::Color& barBackgroundColor);
 300
 301         /**
 302          * Gets the background color of the bar.
 303          *
 304          * @since     2.1
 305          *
 306          * @return    The background color of the bar, @n
 307          *                        else RGBA(0, 0, 0, 0) if an error occurs
 308          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 309          * @see SetBarBackgroundColor()
 310          */
 311         Tizen::Graphics::Color GetBarBackgroundColor(void) const;
 312
 313
 314 private:
 315         //
 316         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 317         //
 318         Progress(const Progress& rhs);
 319
 320         //
 321         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 322         //
 323         Progress& operator =(const Progress& rhs);
 324
 325         friend class _ProgressImpl;
 326
 327 };  // Progress
 328
 329 }}} // Tizen::Ui::Controls
 330
 331 #endif // _FUI_CTRL_PROGRESS_H_