inc/FUiCtrlSlider.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        FUiCtrlSlider.h
  20  * @brief       This is the header file for the %Slider class.
  21  *
  22  * This header file contains the declarations of the %Slider class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_SLIDER_H_
  26 #define _FUI_CTRL_SLIDER_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseColArrayListT.h>
  31 #include <FBaseString.h>
  32 #include <FGrpBitmap.h>
  33 #include <FGrpRectangle.h>
  34 #include <FUiControl.h>
  35 #include <FUiContainer.h>
  36 #include <FUiIAdjustmentEventListener.h>
  37 #include <FUiCtrlControlsTypes.h>
  38 #include <FUiCtrlSliderTypes.h>
  39 #include <FUiCtrlISliderEventListener.h>
  40
  41
  42 namespace Tizen { namespace Ui { namespace Controls
  43 {
  44
  45 /**
  46  * @class       Slider
  47  * @brief       This class is an implementation of a %Slider control.
  48  *
  49  * @since       2.0
  50  *
  51  * The %Slider class displays a slider that represents changing progress or setting information. The difference between %Slider
  52  * and Progress is that the former accepts user input by the touch of the slider icon.
  53  *
  54  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_slider.htm">Slider</a>.
  55  *
  56  * The following example demonstrates how to use the %Slider class.
  57  *
  58  * @code
  59 // Sample code for SliderSample.h
  60 #include <FUi.h>
  61
  62 class SliderSample
  63         : public Tizen::Ui::Controls::Form
  64         , public Tizen::Ui::IAdjustmentEventListener
  65 {
  66 public:
  67         SliderSample(void)
  68         : __pSlider(null){}
  69
  70         bool Initialize(void);
  71         virtual result OnInitializing(void);
  72         virtual void OnAdjustmentValueChanged(const Tizen::Ui::Control& source, int adjustment);
  73
  74 private:
  75         Tizen::Ui::Controls::Slider* __pSlider;
  76 };
  77  *      @endcode
  78  *
  79  *      @code
  80 // Sample code for SliderSample.cpp
  81 #include <FGraphics.h>
  82
  83 #include "SliderSample.h"
  84
  85 using namespace Tizen::Graphics;
  86 using namespace Tizen::Ui::Controls;
  87
  88 bool
  89 SliderSample::Initialize(void)
  90 {
  91         Construct(FORM_STYLE_NORMAL);
  92         return true;
  93 }
  94
  95 result
  96 SliderSample::OnInitializing(void)
  97 {
  98         result r = E_SUCCESS;
  99
 100         // Creates an instance of Slider
 101         __pSlider = new Slider();
 102         __pSlider->Construct(Rectangle(0, 200, GetClientAreaBounds().width, 200), BACKGROUND_STYLE_DEFAULT, false, 0, 100);
 103         __pSlider->SetValue(50);
 104         __pSlider->AddAdjustmentEventListener(*this);
 105
 106         // Adds the slider to the form
 107         AddControl(__pSlider);
 108
 109         return r;
 110 }
 111
 112 // IAdjustmentEventListener implementation
 113 void
 114 SliderSample::OnAdjustmentValueChanged(const Control& source, int adjustment)
 115 {
 116         // ....
 117 }
 118  * @endcode
 119  *
 120  */
 121 class _OSP_EXPORT_ Slider
 122         : public Tizen::Ui::Control
 123 {
 124 // Lifecycle
 125 public:
 126         /**
 127          * The object is not fully constructed after this constructor is called. @n
 128          * For full construction, the %Construct() method must be called right after calling this constructor.
 129          *
 130          * @since               2.0
 131          */
 132         Slider(void);
 133
 134         /**
 135          * This polymorphic destructor should be overridden if required.@n
 136          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 137          *
 138          * @since               2.0
 139          */
 140         virtual ~Slider(void);
 141
 142         /**
 143          * Initializes this instance of %Slider with the specified parameters.
 144          *
 145          * @since               2.0
 146          *
 147          * @return              An error code
 148          * @param[in]   rect                            An instance of the Graphics::Rectangle class @n
 149          *                                                                      This instance represents the x and y coordinates of the top-left corner of the created window along with
 150          *                                                                      the width and height of the control.@n
 151          *                                                                      The optimal size of the control is defined in
 152          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 153          * @param[in]   backgroundStyle         The background style set of the slider
 154          * @param[in]   showTitle                       Set to @c true to enable the show title, @n
 155          *                                                                      else @c false
 156          * @param[in]   minValue                        The minimum slider value
 157          * @param[in]   maxValue                        The maximum slider value
 158          * @param[in]   groupStyle                      The table view style of the slider
 159          * @exception   E_SUCCESS           The method is successful.
 160          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 161          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 162          *                                  The background style of @c BACKGROUND_STYLE_NONE does not work with group styles except ::GROUP_STYLE_NONE.
 163          * @exception   E_OUT_OF_RANGE          The specified values are less than @c -99 or greater than @c 999.
 164          * @exception   E_SYSTEM                        A system error has occurred.
 165          * @remarks
 166          *                              - A control is fully usable only after it has been added to a container. Therefore, some methods may fail if used earlier.
 167          *                              - If the given size is less than the minimum, it returns @c E_INVALID_ARG.
 168          *                              - The size of the control must be within the range defined by the minimum size and the maximum size.
 169          */
 170         result Construct(const Tizen::Graphics::Rectangle& rect, BackgroundStyle backgroundStyle = BACKGROUND_STYLE_DEFAULT, bool showTitle = false, int minValue = 0, int maxValue = 100, GroupStyle groupStyle = GROUP_STYLE_NONE);
 171
 172         /**
 173          * Initializes this instance of %Slider with the specified parameters.
 174          *
 175          * @since               2.1
 176          *
 177          * @return              An error code
 178          * @param[in]   rect                            An instance of the Tizen::Graphics::FloatRectangle class @n
 179          *                                                                      This instance represents the x and y coordinates of the top-left corner of the created window along with
 180          *                                                                      the width and height of the control.@n
 181          *                                                                      The optimal size of the control is defined in
 182          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 183          * @param[in]   backgroundStyle         The background style set of the slider
 184          * @param[in]   showTitle                       Set to @c true to enable the show title, @n
 185          *                                                                      else @c false
 186          * @param[in]   minValue                        The minimum slider value
 187          * @param[in]   maxValue                        The maximum slider value
 188          * @param[in]   groupStyle                      The table view style of the slider
 189          * @exception   E_SUCCESS           The method is successful.
 190          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 191          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 192          *                                  The background style of @c BACKGROUND_STYLE_NONE does not work with group styles except ::GROUP_STYLE_NONE.
 193          * @exception   E_OUT_OF_RANGE          The specified values are less than @c -99 or greater than @c 999.
 194          * @exception   E_SYSTEM                        A system error has occurred.
 195          * @remarks
 196          *                      - A control is fully usable only after it has been added to a container. Therefore, some methods may fail if used earlier.
 197          *                      - If the given size is less than the minimum, it returns @c E_INVALID_ARG.
 198          *                      - The size of the control must be within the range defined by the minimum size and the maximum size.
 199          */
 200         result Construct(const Tizen::Graphics::FloatRectangle& rect, BackgroundStyle backgroundStyle = BACKGROUND_STYLE_DEFAULT, bool showTitle = false, int minValue = 0, int maxValue = 100, GroupStyle groupStyle = GROUP_STYLE_NONE);
 201
 202         /**
 203          * Adds a IAdjustmentEventListener instance. @n
 204          * The added listener listens to events on the context of the specified event dispatcher when they are fired.
 205          *
 206          * @since               2.0
 207          *
 208          * @param[in]   listener        The event listener to add
 209          */
 210         void AddAdjustmentEventListener(Tizen::Ui::IAdjustmentEventListener& listener);
 211
 212         /**
 213          * Removes a IAdjustmentEventListener instance. @n
 214          * The removed listener cannot listen to events when they are fired.
 215          *
 216          * @since               2.0
 217          *
 218          * @param[in]   listener        The event listener to remove
 219          */
 220         void RemoveAdjustmentEventListener(Tizen::Ui::IAdjustmentEventListener& listener);
 221
 222 // Operation
 223 public:
 224         /**
 225          * Sets the range of the %Slider control.
 226          *
 227          * @since               2.0
 228          *
 229          * @return              An error code
 230          * @param[in]   minValue                The minimum value of the %Slider control
 231          * @param[in]   maxValue                The maximum value of the %Slider control
 232          * @exception   E_SUCCESS       The method is successful.
 233          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 234          * @exception   E_OUT_OF_RANGE  The specified values are greater than @c -99 or less than @c 999.
 235          * @exception   E_SYSTEM                A system error has occurred.
 236          */
 237         result SetRange(int minValue, int maxValue);
 238
 239         /**
 240          * Gets the minimum value and the maximum value of the slider.
 241          *
 242          * @since               2.0
 243          *
 244          * @param[out]  minValue                The minimum value of the slider
 245          * @param[out]  maxValue                The maximum value of the slider
 246          */
 247         void GetRange(int& minValue, int& maxValue) const;
 248
 249         /**
 250          * Sets the value of the current thumb position. @n
 251          * If the specified @c value is greater than @c maxValue, the value is set to @c maxValue, and
 252          * if the specified @c value is less than @c minValue, the value is set to @c minValue.
 253          *
 254          * @since               2.0
 255          *
 256          * @param[in]   value  The value of the position
 257          */
 258         void SetValue(int value);
 259
 260         /**
 261          * Gets the value of the current thumb position.
 262          *
 263          * @since               2.0
 264          *
 265          * @return              The current thumb position
 266          */
 267         int GetValue(void) const;
 268
 269         /**
 270          * Sets the icon of the slider.
 271          *
 272          * @since               2.0
 273          *
 274          * @param[in]   position        The position of the icon (@c ICON_POSITION_LEFT/@c ICON_POSITION_RIGHT)
 275          * @param[in]   icon        The bitmap image of the icon
 276          * @remarks     If the size of the bitmap is greater than the default size, the bitmap image is scaled down.
 277          */
 278         void SetIcon(IconPosition position, const Tizen::Graphics::Bitmap& icon);
 279
 280         /**
 281         * Sets the title of the slider.
 282         *
 283         * @since                2.0
 284         *
 285         * @return               An error code
 286         * @param[in]    title                   The title to set
 287         * @exception    E_SUCCESS                       The method is successful.
 288         * @exception    E_SYSTEM                A system error has occurred.
 289         */
 290         result SetTitleText(const Tizen::Base::String& title);
 291
 292         /**
 293          * Gets the title of the slider.
 294          *
 295          * @since               2.0
 296          *
 297          * @return              The title text of the entered string
 298          *
 299          * @remarks             By default returns an empty string.
 300          */
 301         Tizen::Base::String GetTitleText(void) const;
 302
 303         /**
 304          * Sets the title text color of the %Slider control.
 305          *
 306          * @since                       2.0
 307          *
 308          * @param[in]   color   The title text color to set
 309          */
 310         void SetTitleTextColor(const Tizen::Graphics::Color& color);
 311
 312         /**
 313          * Gets the title text color of the %Slider control.
 314          *
 315          * @since               2.0
 316          *
 317          * @return              The title text color
 318          */
 319         Tizen::Graphics::Color GetTitleTextColor(void) const;
 320
 321         /**
 322          * Initializes this instance of %Slider with the specified parameters.
 323          *
 324          * @since               2.0
 325          *
 326          * @return              An error code
 327          * @param[in]   rect                            An instance of the Graphics::Rectangle class @n
 328          *                                                                  This instance represents the x and y coordinates of the top-left corner of the created window along with
 329          *                                  its width and height.@n
 330          *                                                                      The optimal size of the control is defined in
 331          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 332          * @param[in]   sliderStyle         The style of the slider @n
 333          *                                  Multiple link types can be combined using bitwise OR operator.
 334          * @param[in]   minValue            The minimum slider value
 335          * @param[in]   maxValue            The maximum slider value
 336          * @exception   E_SUCCESS           The method is successful.
 337          * @exception   E_OUT_OF_RANGE      The specified minimum and maximum values are less than @c -99, or greater than @c 999.
 338          * @exception   E_INVALID_ARG       A specified input parameter is invalid, or the specified @c minValue is greater than @c maxVaue.
 339          * @exception   E_SYSTEM            A system error has occurred.
 340          * @remarks
 341          *                              - A control is fully functional only after it has been added to a container. Therefore, some methods may fail if they are used before
 342          *                              adding the control to the container.
 343          *                              - If the specified size is less than the minimum size, the %Slider control is constructed with the minimum size.
 344          *                              - The width and the height of the control must be greater than @c 0.
 345          *                              - The size of the control must be within the range defined by the minimum size and the maximum size.
 346          * @see         SliderStyle
 347          */
 348         result Construct(const Tizen::Graphics::Rectangle& rect, unsigned long sliderStyle, int minValue = 0, int maxValue = 100);
 349
 350         /**
 351          * Initializes this instance of %Slider with the specified parameters.
 352          *
 353          * @since               2.1
 354          *
 355          * @return              An error code
 356          * @param[in]   rect                            An instance of the Tizen::Graphics::FloatRectangle class @n
 357          *                                                                  This instance represents the x and y coordinates of the top-left corner of the created window along with
 358          *                                  its width and height.@n
 359          *                                                                      The optimal size of the control is defined in
 360          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 361          * @param[in]   sliderStyle         The style of the slider @n
 362          *                                  Multiple link types can be combined using bitwise OR operator.
 363          * @param[in]   minValue            The minimum slider value
 364          * @param[in]   maxValue            The maximum slider value
 365          * @exception   E_SUCCESS           The method is successful.
 366          * @exception   E_OUT_OF_RANGE      The specified minimum and maximum values are less than @c -99, or greater than @c 999.
 367          * @exception   E_INVALID_ARG       A specified input parameter is invalid, or the specified @c minValue is greater than @c maxVaue.
 368          * @exception   E_SYSTEM            A system error has occurred.
 369          * @remarks
 370          *                      - A control is fully functional only after it has been added to a container. Therefore, some methods may fail if they are used before
 371          *                      adding the control to the container.
 372          *                      - If the specified size is less than the minimum size, the %Slider control is constructed with the minimum size.
 373          *                      - The width and the height of the control must be greater than @c 0.
 374          *                      - The size of the control must be within the range defined by the minimum size and the maximum size.
 375          * @see         SliderStyle
 376          */
 377         result Construct(const Tizen::Graphics::FloatRectangle& rect, unsigned long sliderStyle, int minValue = 0, int maxValue = 100);
 378
 379         /**
 380          * Adds a ISliderEventListener instance. @n
 381          * The added listener can listen to the slider-related events.
 382          *
 383          * @since     2.0
 384          *
 385          * @param[in] listener    The event listener to add
 386          */
 387         void AddSliderEventListener(ISliderEventListener& listener);
 388
 389         /**
 390          * Removes a ISliderEventListener instance. @n
 391          * The removed listener cannot listen to events when they are fired.
 392          *
 393          * @since     2.0
 394          *
 395          * @param[in] listener    The event listener to remove
 396          */
 397         void RemoveSliderEventListener(ISliderEventListener& listener);
 398
 399         /**
 400          * Sets the color of the bar.
 401          *
 402          * @since     2.0
 403          *
 404          * @return    An error code
 405          * @param[in] color             The color to set
 406          * @exception E_SUCCESS         The method is successful.
 407          * @exception E_SYSTEM          A system error has occurred.
 408          * @remarks   The method ignores the alpha value of the @c color parameter and sets the alpha value to @c 255.
 409          */
 410         result SetBarColor(const Tizen::Graphics::Color& color);
 411
 412         /**
 413          * Gets the color of the bar.
 414          *
 415          * @since     2.0
 416          *
 417          * @return    The color of the bar, @n
 418          *                        else RGBA(0, 0, 0, 0) if an error occurs
 419          * @exception E_SUCCESS         The method is successful.
 420          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 421          */
 422         Tizen::Graphics::Color GetBarColor(void) const;
 423
 424         /**
 425          * Sets the background color of the bar.
 426          *
 427          * @since     2.1
 428          *
 429          * @param[in] barBackgroundColor             The color to set
 430          * @remarks   This method ignores the alpha value of the @c color parameter and sets the alpha value to @c 255.
 431          * @see GetBarBackgroundColor()
 432          */
 433         void SetBarBackgroundColor(const Tizen::Graphics::Color& barBackgroundColor);
 434
 435         /**
 436          * Gets the background color of the bar.
 437          *
 438          * @since     2.1
 439          *
 440          * @return    The background color of the bar, @n
 441          *                        else RGBA(0, 0, 0, 0) if an error occurs
 442          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 443          * @see SetBarBackgroundColor()
 444          */
 445         Tizen::Graphics::Color GetBarBackgroundColor(void) const;
 446
 447         /**
 448          * Sets the color of the slider.
 449          *
 450          * @since     2.0
 451          *
 452          * @return    An error code
 453          * @param[in] color                     The color to set
 454          * @exception E_SUCCESS                 The method is successful.
 455          * @exception E_INVALID_OPERATION               The current state of the instance prohibits the execution of the specified operation. @n
 456          *                                                                              The operation is not supported if the background style of the %Slider control is ::BACKGROUND_STYLE_NONE.
 457          * @exception E_SYSTEM                  A system error has occurred.
 458          * @remarks   If a device supports only the 16-bit color space, this method considers the color as opaque by ignoring the alpha value of @c color.
 459          */
 460         result SetColor(const Tizen::Graphics::Color& color);
 461
 462         /**
 463          * Gets the color of the slider.
 464          *
 465          * @since               2.0
 466          *
 467          * @return              The color , @n
 468          *                              else RGBA(0, 0, 0, 0) if an instance is invalid or the background style is ::BACKGROUND_STYLE_NONE
 469          * @exception   E_SUCCESS                       The method is successful.
 470          * @exception   E_INVALID_OPERATION     The background style is not proper.
 471          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 472          */
 473         Tizen::Graphics::Color GetColor(void) const;
 474
 475         /**
 476          * Sets the bitmap image to the %Slider control Thumb.
 477          *
 478          * @since 2.0
 479          *
 480          * @return    An error code
 481          * @param[in] status                    The state of the slider thumb
 482          * @param[in] bitmap                    The Thumb bitmap image
 483          * @exception E_SUCCESS             The method is successful.
 484          * @exception E_OUT_OF_MEMORY       The memory is insufficient.
 485          */
 486         result SetThumbBitmap(SliderThumbStatus status, const Tizen::Graphics::Bitmap& bitmap);
 487
 488         /**
 489          * Sets the text color of the %Slider control Thumb.
 490          *
 491          * @since 2.0
 492          *
 493          * @return        An error code
 494          * @param[in] status                                    The state of the slider thumb
 495          * @param[in] color                                     The color should be set for the thumb text
 496          */
 497         void SetThumbTextColor(SliderThumbStatus status, const Tizen::Graphics::Color& color);
 498
 499 private:
 500         //
 501         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 502         //
 503         Slider(const Slider&);
 504
 505         //
 506         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 507         //
 508         Slider& operator =(const Slider&);
 509
 510         friend class _SliderImpl;
 511
 512 };      // Slider
 513
 514 }}}     // Tizen::Ui::Controls
 515
 516 #endif // _FUI_CTRL_SLIDER_H_