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  * @file        FUiCtrlProgress.h
  19  * @brief       This is the header file for the %Progress class.
  20  *
  21  * This header file contains the declarations of the %Progress class and its helper classes.
  22  */
  23
  24 #ifndef _FUI_CTRL_PROGRESS_H_
  25 #define _FUI_CTRL_PROGRESS_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseTypes.h>
  29 #include <FUiControl.h>
  30 #include <FUiContainer.h>
  31 #include <FUiCtrlControlsTypes.h>
  32
  33 namespace Tizen { namespace Ui { namespace Controls
  34 {
  35
  36 /**
  37  * @class       Progress
  38  * @brief       This class is an implementation of a %Progress control.
  39  *
  40  * @since       2.0
  41  *
  42  * The %Progress class displays the progress of a lengthy operation in a progress bar.
  43  *
  44  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_progress.htm">Progress</a>.
  45  *
  46  * The following example demonstrates how to use the %Progress class.
  47  *
  48  * @code
  49 // Sample code for ProgressSample.h
  50 #include <FUi.h>
  51
  52 class ProgressSample
  53         : public Tizen::Ui::Controls::Form
  54         , public Tizen::Ui::IActionEventListener
  55 {
  56 public:
  57         ProgressSample(void)
  58         : __pProgress(null)
  59         , __pValue(0){}
  60
  61         bool Initialize(void);
  62         virtual result OnInitializing(void);
  63         virtual void OnActionPerformed(const Tizen::Ui::Control&, int);
  64
  65 private:
  66         static const int ID_BUTTON_CHECKED = 100;
  67
  68         Tizen::Ui::Controls::Progress* __pProgress;
  69         int __pValue;
  70 };
  71  *      @endcode
  72  *
  73  *      @code
  74 // Sample code for ProgressSample.cpp
  75 #include <FGraphics.h>
  76
  77 #include "ProgressSample.h"
  78
  79 using namespace Tizen::Graphics;
  80 using namespace Tizen::Ui::Controls;
  81
  82 bool
  83 ProgressSample::Initialize(void)
  84 {
  85         Construct(FORM_STYLE_NORMAL);
  86         return true;
  87 }
  88
  89 result
  90 ProgressSample::OnInitializing(void)
  91 {
  92         result r = E_SUCCESS;
  93
  94         // Creates an instance of Progress
  95         __pProgress = new Progress();
  96         __pProgress->Construct(Rectangle(50, 50, GetClientAreaBounds().width - 100, 100), 0, 100);
  97         __pProgress->SetValue(__pValue);
  98
  99         // Creates an instance of pButton to control progress value
 100         Button* pButton = new Button();
 101         pButton->Construct(Rectangle(50, 200, 150, 100), L"Here");
 102         pButton->SetActionId(ID_BUTTON_CHECKED);
 103         pButton->AddActionEventListener(*this);
 104
 105         // Adds the __pProgress and the pButton to the form
 106         AddControl(*__pProgress);
 107         AddControl(*pButton);
 108
 109         return r;
 110 }
 111
 112 void
 113 ProgressSample::OnActionPerformed(const Control& source, int actionId)
 114 {
 115         switch (actionId)
 116         {
 117         case ID_BUTTON_CHECKED :
 118                 {
 119                         if (__pValue >= 100)
 120                         {
 121                                 __pValue = 0;
 122                         }
 123                         else
 124                         {
 125                                 __pValue += 10;
 126                         }
 127                         __pProgress->SetValue(__pValue);
 128                         __pProgress->Invalidate(true);
 129                 }
 130                 break;
 131         default:
 132                 break;
 133         }
 134 }
 135  * @endcode
 136  *
 137  */
 138 class _OSP_EXPORT_ Progress
 139         : public Tizen::Ui::Control
 140 {
 141 public:
 142         /**
 143          * 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.
 144          *
 145          * @since       2.0
 146          */
 147         Progress(void);
 148
 149
 150         /**
 151          * 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.
 152          *
 153          * @since       2.0
 154          */
 155         virtual ~Progress(void);
 156
 157
 158         /**
 159          * Initializes this instance of %Progress with the specified parameters.
 160          *
 161          * @since               2.0
 162          *
 163          * @return              An error code
 164          * @param[in]   rect                            An instance of the Rectangle class @n
 165          *                                                          This instance represents the x and y coordinates of the top-left corner of the created window along with
 166          *                                  its width and height.
 167          * @param[in]   minValue                        The minimum value of the current instance of %Progress
 168          * @param[in]   maxValue                        The maximum value of the current instance of %Progress
 169          * @exception   E_SUCCESS                       The method is successful.
 170          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 171          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 172          *                                                                      The specified values should be positive and @c minValue should be less than @c maxValue.
 173          * @exception   E_SYSTEM                        A system error has occurred.
 174          * @remarks     A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier. @n
 175          * @remarks     The size of the control must be within the range defined by the minimum size and the maximum size.
 176          */
 177         result Construct(const Tizen::Graphics::Rectangle& rect, int minValue, int maxValue);
 178
 179 public:
 180         /**
 181          * Sets the current value of the %Progress control. @n
 182          * 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.
 183          *
 184          * @since               2.0
 185          *
 186          * @param[in]   value   The current progress value
 187          */
 188         void SetValue(int value);
 189
 190
 191         /**
 192          * Sets the minimum and maximum value of the %Progress control.
 193          *
 194          * @since               2.0
 195          *
 196          * @return              An error code
 197          * @param[in]   minValue                        The minimum value of the current instance of %Progress
 198          * @param[in]   maxValue                        The maximum value of the current instance of %Progress
 199          * @exception   E_SUCCESS                       The method is successful.
 200          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 201          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 202          *                                                                      The specified values should be positive.
 203          * @exception   E_SYSTEM                        A system error has occurred.
 204          */
 205         result SetRange(int minValue, int maxValue);
 206
 207
 208         /**
 209          * Gets the current value of the %Progress control.
 210          *
 211          * @since       2.0
 212          *
 213          * @return      An integer value representing the current value of progress, @n
 214          *                      else @c -1 if an error occurs
 215          */
 216         int GetValue(void) const;
 217
 218
 219         /**
 220          * Gets the minimum value and the maximum value of the %Progress control.
 221          *
 222          * @since               2.0
 223          *
 224          * @param[out]  minValue        The minimum value
 225          * @param[out]  maxValue        The maximum value
 226         */
 227         void GetRange(int& minValue, int& maxValue) const;
 228
 229
 230         /**
 231          * Gets the percent value of the %Progress control.
 232          *
 233          * @since       2.0
 234          *
 235          * @return      The progress as a percentage, @n
 236          *                      else @c -1 if an error occurs
 237          */
 238         int GetPercentComplete(void) const;
 239
 240
 241         /**
 242          * Sets the color of the bar.
 243          *
 244          * @since     2.0
 245          *
 246          * @return    An error code
 247          * @param[in] color             The color to be set
 248          * @exception E_SUCCESS         The method is successful.
 249          * @exception E_SYSTEM          A system error has occurred.
 250          * @remarks   The method ignores the alpha value of the @c color parameter and sets the alpha value to @c 255.
 251          */
 252         result SetBarColor(const Tizen::Graphics::Color& color);
 253
 254
 255         /**
 256          * Gets the color of the bar.
 257          *
 258          * @since     2.0
 259          *
 260          * @return    The color of the bar, @n
 261          *                        else RGBA(0, 0, 0, 0) if an error occurs
 262          * @exception E_SUCCESS         The method is successful.
 263          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 264          */
 265         Tizen::Graphics::Color GetBarColor(void) const;
 266
 267 private:
 268         //
 269         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 270         //
 271         Progress(const Progress& rhs);
 272
 273         //
 274         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 275         //
 276         Progress& operator =(const Progress& rhs);
 277
 278         friend class _ProgressImpl;
 279
 280 };  // Progress
 281
 282 }}} // Tizen::Ui::Controls
 283
 284 #endif // _FUI_CTRL_PROGRESS_H_