2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0/
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.
19 * @file FUiCtrlSlider.h
20 * @brief This is the header file for the %Slider class.
22 * This header file contains the declarations of the %Slider class and its helper classes.
25 #ifndef _FUI_CTRL_SLIDER_H_
26 #define _FUI_CTRL_SLIDER_H_
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>
42 namespace Tizen { namespace Ui { namespace Controls
47 * @brief This class is an implementation of a %Slider control.
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.
54 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_slider.htm">Slider</a>.
56 * The following example demonstrates how to use the %Slider class.
59 // Sample code for SliderSample.h
63 : public Tizen::Ui::Controls::Form
64 , public Tizen::Ui::IAdjustmentEventListener
70 bool Initialize(void);
71 virtual result OnInitializing(void);
72 virtual void OnAdjustmentValueChanged(const Tizen::Ui::Control& source, int adjustment);
75 Tizen::Ui::Controls::Slider* __pSlider;
80 // Sample code for SliderSample.cpp
81 #include <FGraphics.h>
83 #include "SliderSample.h"
85 using namespace Tizen::Graphics;
86 using namespace Tizen::Ui::Controls;
89 SliderSample::Initialize(void)
91 Construct(FORM_STYLE_NORMAL);
96 SliderSample::OnInitializing(void)
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);
106 // Adds the slider to the form
107 AddControl(__pSlider);
112 // IAdjustmentEventListener implementation
114 SliderSample::OnAdjustmentValueChanged(const Control& source, int adjustment)
121 class _OSP_EXPORT_ Slider
122 : public Tizen::Ui::Control
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.
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.
140 virtual ~Slider(void);
143 * Initializes this instance of %Slider with the specified parameters.
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
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.
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.
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);
173 * Initializes this instance of %Slider with the specified parameters.
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
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.
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.
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);
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.
208 * @param[in] listener The event listener to add
210 void AddAdjustmentEventListener(Tizen::Ui::IAdjustmentEventListener& listener);
213 * Removes a IAdjustmentEventListener instance. @n
214 * The removed listener cannot listen to events when they are fired.
218 * @param[in] listener The event listener to remove
220 void RemoveAdjustmentEventListener(Tizen::Ui::IAdjustmentEventListener& listener);
225 * Sets the range of the %Slider control.
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.
237 result SetRange(int minValue, int maxValue);
240 * Gets the minimum value and the maximum value of the slider.
244 * @param[out] minValue The minimum value of the slider
245 * @param[out] maxValue The maximum value of the slider
247 void GetRange(int& minValue, int& maxValue) const;
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.
256 * @param[in] value The value of the position
258 void SetValue(int value);
261 * Gets the value of the current thumb position.
265 * @return The current thumb position
267 int GetValue(void) const;
270 * Sets the icon of the slider.
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.
278 void SetIcon(IconPosition position, const Tizen::Graphics::Bitmap& icon);
281 * Sets the title of the slider.
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.
290 result SetTitleText(const Tizen::Base::String& title);
293 * Gets the title of the slider.
297 * @return The title text of the entered string
299 * @remarks By default returns an empty string.
301 Tizen::Base::String GetTitleText(void) const;
304 * Sets the title text color of the %Slider control.
308 * @param[in] color The title text color to set
310 void SetTitleTextColor(const Tizen::Graphics::Color& color);
313 * Gets the title text color of the %Slider control.
317 * @return The title text color
319 Tizen::Graphics::Color GetTitleTextColor(void) const;
322 * Initializes this instance of %Slider with the specified parameters.
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.
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.
348 result Construct(const Tizen::Graphics::Rectangle& rect, unsigned long sliderStyle, int minValue = 0, int maxValue = 100);
351 * Initializes this instance of %Slider with the specified parameters.
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.
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.
377 result Construct(const Tizen::Graphics::FloatRectangle& rect, unsigned long sliderStyle, int minValue = 0, int maxValue = 100);
380 * Adds a ISliderEventListener instance. @n
381 * The added listener can listen to the slider-related events.
385 * @param[in] listener The event listener to add
387 void AddSliderEventListener(ISliderEventListener& listener);
390 * Removes a ISliderEventListener instance. @n
391 * The removed listener cannot listen to events when they are fired.
395 * @param[in] listener The event listener to remove
397 void RemoveSliderEventListener(ISliderEventListener& listener);
400 * Sets the color of the bar.
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.
410 result SetBarColor(const Tizen::Graphics::Color& color);
413 * Gets the color of the bar.
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.
422 Tizen::Graphics::Color GetBarColor(void) const;
425 * Sets the background color of the bar.
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()
433 void SetBarBackgroundColor(const Tizen::Graphics::Color& barBackgroundColor);
436 * Gets the background color of the bar.
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()
445 Tizen::Graphics::Color GetBarBackgroundColor(void) const;
448 * Sets the color of the slider.
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.
460 result SetColor(const Tizen::Graphics::Color& color);
463 * Gets the color of the slider.
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.
473 Tizen::Graphics::Color GetColor(void) const;
476 * Sets the bitmap image to the %Slider control Thumb.
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.
486 result SetThumbBitmap(SliderThumbStatus status, const Tizen::Graphics::Bitmap& bitmap);
489 * Sets the text color of the %Slider control Thumb.
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
497 void SetThumbTextColor(SliderThumbStatus status, const Tizen::Graphics::Color& color);
501 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
503 Slider(const Slider&);
506 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
508 Slider& operator =(const Slider&);
510 friend class _SliderImpl;
514 }}} // Tizen::Ui::Controls
516 #endif // _FUI_CTRL_SLIDER_H_