diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/elementary/src/lib/elm_slider.h | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/libraries/elementary/src/lib/elm_slider.h b/libraries/elementary/src/lib/elm_slider.h new file mode 100644 index 0000000..5375aaf --- /dev/null +++ b/libraries/elementary/src/lib/elm_slider.h | |||
@@ -0,0 +1,400 @@ | |||
1 | /** | ||
2 | * @defgroup Slider Slider | ||
3 | * @ingroup Elementary | ||
4 | * | ||
5 | * @image html img/widget/slider/preview-00.png | ||
6 | * @image latex img/widget/slider/preview-00.eps width=\textwidth | ||
7 | * | ||
8 | * The slider adds a draggable “slider” widget for selecting the value of | ||
9 | * something within a range. | ||
10 | * | ||
11 | * A slider can be horizontal or vertical. It can contain an Icon and has a | ||
12 | * primary label as well as a units label (that is formatted with floating | ||
13 | * point values and thus accepts a printf-style format string, like | ||
14 | * “%1.2f units”. There is also an indicator string that may be somewhere | ||
15 | * else (like on the slider itself) that also accepts a format string like | ||
16 | * units. Label, Icon Unit and Indicator strings/objects are optional. | ||
17 | * | ||
18 | * A slider may be inverted which means values invert, with high vales being | ||
19 | * on the left or top and low values on the right or bottom (as opposed to | ||
20 | * normally being low on the left or top and high on the bottom and right). | ||
21 | * | ||
22 | * The slider should have its minimum and maximum values set by the | ||
23 | * application with elm_slider_min_max_set() and value should also be set by | ||
24 | * the application before use with elm_slider_value_set(). The span of the | ||
25 | * slider is its length (horizontally or vertically). This will be scaled by | ||
26 | * the object or applications scaling factor. At any point code can query the | ||
27 | * slider for its value with elm_slider_value_get(). | ||
28 | * | ||
29 | * Smart callbacks one can listen to: | ||
30 | * - "changed" - Whenever the slider value is changed by the user. | ||
31 | * - "slider,drag,start" - dragging the slider indicator around has started. | ||
32 | * - "slider,drag,stop" - dragging the slider indicator around has stopped. | ||
33 | * - "delay,changed" - A short time after the value is changed by the user. | ||
34 | * This will be called only when the user stops dragging for | ||
35 | * a very short period or when they release their | ||
36 | * finger/mouse, so it avoids possibly expensive reactions to | ||
37 | * the value change. | ||
38 | * | ||
39 | * Available styles for it: | ||
40 | * - @c "default" | ||
41 | * | ||
42 | * Default content parts of the slider widget that you can use for are: | ||
43 | * @li "icon" - An icon of the slider | ||
44 | * @li "end" - A end part content of the slider | ||
45 | * | ||
46 | * Default text parts of the slider widget that you can use for are: | ||
47 | * @li "default" - Label of the slider | ||
48 | * | ||
49 | * Supported elm_object common APIs. | ||
50 | * @li @ref elm_object_disabled_set | ||
51 | * @li @ref elm_object_disabled_get | ||
52 | * @li @ref elm_object_part_text_set | ||
53 | * @li @ref elm_object_part_text_get | ||
54 | * @li @ref elm_object_part_content_set | ||
55 | * @li @ref elm_object_part_content_get | ||
56 | * @li @ref elm_object_part_content_unset | ||
57 | * | ||
58 | * Here is an example on its usage: | ||
59 | * @li @ref slider_example | ||
60 | */ | ||
61 | |||
62 | /** | ||
63 | * @addtogroup Slider | ||
64 | * @{ | ||
65 | */ | ||
66 | |||
67 | /** | ||
68 | * Add a new slider widget to the given parent Elementary | ||
69 | * (container) object. | ||
70 | * | ||
71 | * @param parent The parent object. | ||
72 | * @return a new slider widget handle or @c NULL, on errors. | ||
73 | * | ||
74 | * This function inserts a new slider widget on the canvas. | ||
75 | * | ||
76 | * @ingroup Slider | ||
77 | */ | ||
78 | EAPI Evas_Object *elm_slider_add(Evas_Object *parent); | ||
79 | |||
80 | /** | ||
81 | * Set the (exact) length of the bar region of a given slider widget. | ||
82 | * | ||
83 | * @param obj The slider object. | ||
84 | * @param size The length of the slider's bar region. | ||
85 | * | ||
86 | * This sets the minimum width (when in horizontal mode) or height | ||
87 | * (when in vertical mode) of the actual bar area of the slider | ||
88 | * @p obj. This in turn affects the object's minimum size. Use | ||
89 | * this when you're not setting other size hints expanding on the | ||
90 | * given direction (like weight and alignment hints) and you would | ||
91 | * like it to have a specific size. | ||
92 | * | ||
93 | * @note Icon, end, label, indicator and unit text around @p obj | ||
94 | * will require their | ||
95 | * own space, which will make @p obj to require more the @p size, | ||
96 | * actually. | ||
97 | * | ||
98 | * @see elm_slider_span_size_get() | ||
99 | * | ||
100 | * @ingroup Slider | ||
101 | */ | ||
102 | EAPI void elm_slider_span_size_set(Evas_Object *obj, Evas_Coord size); | ||
103 | |||
104 | /** | ||
105 | * Get the length set for the bar region of a given slider widget | ||
106 | * | ||
107 | * @param obj The slider object. | ||
108 | * @return The length of the slider's bar region. | ||
109 | * | ||
110 | * If that size was not set previously, with | ||
111 | * elm_slider_span_size_set(), this call will return @c 0. | ||
112 | * | ||
113 | * @ingroup Slider | ||
114 | */ | ||
115 | EAPI Evas_Coord elm_slider_span_size_get(const Evas_Object *obj); | ||
116 | |||
117 | /** | ||
118 | * Set the format string for the unit label. | ||
119 | * | ||
120 | * @param obj The slider object. | ||
121 | * @param format The format string for the unit display. | ||
122 | * | ||
123 | * Unit label is displayed all the time, if set, after slider's bar. | ||
124 | * In horizontal mode, at right and in vertical mode, at bottom. | ||
125 | * | ||
126 | * If @c NULL, unit label won't be visible. If not it sets the format | ||
127 | * string for the label text. To the label text is provided a floating point | ||
128 | * value, so the label text can display up to 1 floating point value. | ||
129 | * Note that this is optional. | ||
130 | * | ||
131 | * Use a format string such as "%1.2f meters" for example, and it will | ||
132 | * display values like: "3.14 meters" for a value equal to 3.14159. | ||
133 | * | ||
134 | * Default is unit label disabled. | ||
135 | * | ||
136 | * @see elm_slider_indicator_format_get() | ||
137 | * | ||
138 | * @ingroup Slider | ||
139 | */ | ||
140 | EAPI void elm_slider_unit_format_set(Evas_Object *obj, const char *format); | ||
141 | |||
142 | /** | ||
143 | * Get the unit label format of the slider. | ||
144 | * | ||
145 | * @param obj The slider object. | ||
146 | * @return The unit label format string in UTF-8. | ||
147 | * | ||
148 | * Unit label is displayed all the time, if set, after slider's bar. | ||
149 | * In horizontal mode, at right and in vertical mode, at bottom. | ||
150 | * | ||
151 | * @see elm_slider_unit_format_set() for more | ||
152 | * information on how this works. | ||
153 | * | ||
154 | * @ingroup Slider | ||
155 | */ | ||
156 | EAPI const char *elm_slider_unit_format_get(const Evas_Object *obj); | ||
157 | |||
158 | /** | ||
159 | * Set the format string for the indicator label. | ||
160 | * | ||
161 | * @param obj The slider object. | ||
162 | * @param indicator The format string for the indicator display. | ||
163 | * | ||
164 | * The slider may display its value somewhere else then unit label, | ||
165 | * for example, above the slider knob that is dragged around. This function | ||
166 | * sets the format string used for this. | ||
167 | * | ||
168 | * If @c NULL, indicator label won't be visible. If not it sets the format | ||
169 | * string for the label text. To the label text is provided a floating point | ||
170 | * value, so the label text can display up to 1 floating point value. | ||
171 | * Note that this is optional. | ||
172 | * | ||
173 | * Use a format string such as "%1.2f meters" for example, and it will | ||
174 | * display values like: "3.14 meters" for a value equal to 3.14159. | ||
175 | * | ||
176 | * Default is indicator label disabled. | ||
177 | * | ||
178 | * @see elm_slider_indicator_format_get() | ||
179 | * | ||
180 | * @ingroup Slider | ||
181 | */ | ||
182 | EAPI void elm_slider_indicator_format_set(Evas_Object *obj, const char *indicator); | ||
183 | |||
184 | /** | ||
185 | * Get the indicator label format of the slider. | ||
186 | * | ||
187 | * @param obj The slider object. | ||
188 | * @return The indicator label format string in UTF-8. | ||
189 | * | ||
190 | * The slider may display its value somewhere else then unit label, | ||
191 | * for example, above the slider knob that is dragged around. This function | ||
192 | * gets the format string used for this. | ||
193 | * | ||
194 | * @see elm_slider_indicator_format_set() for more | ||
195 | * information on how this works. | ||
196 | * | ||
197 | * @ingroup Slider | ||
198 | */ | ||
199 | EAPI const char *elm_slider_indicator_format_get(const Evas_Object *obj); | ||
200 | |||
201 | /** | ||
202 | * Set the format function pointer for the indicator label | ||
203 | * | ||
204 | * @param obj The slider object. | ||
205 | * @param func The indicator format function. | ||
206 | * @param free_func The freeing function for the format string. | ||
207 | * | ||
208 | * Set the callback function to format the indicator string. | ||
209 | * | ||
210 | * @see elm_slider_indicator_format_set() for more info on how this works. | ||
211 | * | ||
212 | * @ingroup Slider | ||
213 | */ | ||
214 | EAPI void elm_slider_indicator_format_function_set(Evas_Object *obj, char *(*func)(double val), void (*free_func)(char *str)); | ||
215 | |||
216 | /** | ||
217 | * Set the format function pointer for the units label | ||
218 | * | ||
219 | * @param obj The slider object. | ||
220 | * @param func The units format function. | ||
221 | * @param free_func The freeing function for the format string. | ||
222 | * | ||
223 | * Set the callback function to format the indicator string. | ||
224 | * | ||
225 | * @see elm_slider_units_format_set() for more info on how this works. | ||
226 | * | ||
227 | * @ingroup Slider | ||
228 | */ | ||
229 | EAPI void elm_slider_units_format_function_set(Evas_Object *obj, char *(*func)(double val), void (*free_func)(char *str)); | ||
230 | |||
231 | /** | ||
232 | * Set the orientation of a given slider widget. | ||
233 | * | ||
234 | * @param obj The slider object. | ||
235 | * @param horizontal Use @c EINA_TRUE to make @p obj to be | ||
236 | * @b horizontal, @c EINA_FALSE to make it @b vertical. | ||
237 | * | ||
238 | * Use this function to change how your slider is to be | ||
239 | * disposed: vertically or horizontally. | ||
240 | * | ||
241 | * By default it's displayed horizontally. | ||
242 | * | ||
243 | * @see elm_slider_horizontal_get() | ||
244 | * | ||
245 | * @ingroup Slider | ||
246 | */ | ||
247 | EAPI void elm_slider_horizontal_set(Evas_Object *obj, Eina_Bool horizontal); | ||
248 | |||
249 | /** | ||
250 | * Retrieve the orientation of a given slider widget | ||
251 | * | ||
252 | * @param obj The slider object. | ||
253 | * @return @c EINA_TRUE, if @p obj is set to be @b horizontal, | ||
254 | * @c EINA_FALSE if it's @b vertical (and on errors). | ||
255 | * | ||
256 | * @see elm_slider_horizontal_set() for more details. | ||
257 | * | ||
258 | * @ingroup Slider | ||
259 | */ | ||
260 | EAPI Eina_Bool elm_slider_horizontal_get(const Evas_Object *obj); | ||
261 | |||
262 | /** | ||
263 | * Set the minimum and maximum values for the slider. | ||
264 | * | ||
265 | * @param obj The slider object. | ||
266 | * @param min The minimum value. | ||
267 | * @param max The maximum value. | ||
268 | * | ||
269 | * Define the allowed range of values to be selected by the user. | ||
270 | * | ||
271 | * If actual value is less than @p min, it will be updated to @p min. If it | ||
272 | * is bigger then @p max, will be updated to @p max. Actual value can be | ||
273 | * get with elm_slider_value_get(). | ||
274 | * | ||
275 | * By default, min is equal to 0.0, and max is equal to 1.0. | ||
276 | * | ||
277 | * @warning Maximum must be greater than minimum, otherwise behavior | ||
278 | * is undefined. | ||
279 | * | ||
280 | * @see elm_slider_min_max_get() | ||
281 | * | ||
282 | * @ingroup Slider | ||
283 | */ | ||
284 | EAPI void elm_slider_min_max_set(Evas_Object *obj, double min, double max); | ||
285 | |||
286 | /** | ||
287 | * Get the minimum and maximum values of the slider. | ||
288 | * | ||
289 | * @param obj The slider object. | ||
290 | * @param min Pointer to store the minimum value. | ||
291 | * @param max Pointer to store the maximum value. | ||
292 | * | ||
293 | * @note If only one value is needed, the other pointer can be passed | ||
294 | * as @c NULL. | ||
295 | * | ||
296 | * @see elm_slider_min_max_set() for details. | ||
297 | * | ||
298 | * @ingroup Slider | ||
299 | */ | ||
300 | EAPI void elm_slider_min_max_get(const Evas_Object *obj, double *min, double *max); | ||
301 | |||
302 | /** | ||
303 | * Set the value the slider displays. | ||
304 | * | ||
305 | * @param obj The slider object. | ||
306 | * @param val The value to be displayed. | ||
307 | * | ||
308 | * Value will be presented on the unit label following format specified with | ||
309 | * elm_slider_unit_format_set() and on indicator with | ||
310 | * elm_slider_indicator_format_set(). | ||
311 | * | ||
312 | * @warning The value must to be between min and max values. This values | ||
313 | * are set by elm_slider_min_max_set(). | ||
314 | * | ||
315 | * @see elm_slider_value_get() | ||
316 | * @see elm_slider_unit_format_set() | ||
317 | * @see elm_slider_indicator_format_set() | ||
318 | * @see elm_slider_min_max_set() | ||
319 | * | ||
320 | * @ingroup Slider | ||
321 | */ | ||
322 | EAPI void elm_slider_value_set(Evas_Object *obj, double val); | ||
323 | |||
324 | /** | ||
325 | * Get the value displayed by the spinner. | ||
326 | * | ||
327 | * @param obj The spinner object. | ||
328 | * @return The value displayed. | ||
329 | * | ||
330 | * @see elm_spinner_value_set() for details. | ||
331 | * | ||
332 | * @ingroup Slider | ||
333 | */ | ||
334 | EAPI double elm_slider_value_get(const Evas_Object *obj); | ||
335 | |||
336 | /** | ||
337 | * Invert a given slider widget's displaying values order | ||
338 | * | ||
339 | * @param obj The slider object. | ||
340 | * @param inverted Use @c EINA_TRUE to make @p obj inverted, | ||
341 | * @c EINA_FALSE to bring it back to default, non-inverted values. | ||
342 | * | ||
343 | * A slider may be @b inverted, in which state it gets its | ||
344 | * values inverted, with high vales being on the left or top and | ||
345 | * low values on the right or bottom, as opposed to normally have | ||
346 | * the low values on the former and high values on the latter, | ||
347 | * respectively, for horizontal and vertical modes. | ||
348 | * | ||
349 | * @see elm_slider_inverted_get() | ||
350 | * | ||
351 | * @ingroup Slider | ||
352 | */ | ||
353 | EAPI void elm_slider_inverted_set(Evas_Object *obj, Eina_Bool inverted); | ||
354 | |||
355 | /** | ||
356 | * Get whether a given slider widget's displaying values are | ||
357 | * inverted or not. | ||
358 | * | ||
359 | * @param obj The slider object. | ||
360 | * @return @c EINA_TRUE, if @p obj has inverted values, | ||
361 | * @c EINA_FALSE otherwise (and on errors). | ||
362 | * | ||
363 | * @see elm_slider_inverted_set() for more details. | ||
364 | * | ||
365 | * @ingroup Slider | ||
366 | */ | ||
367 | EAPI Eina_Bool elm_slider_inverted_get(const Evas_Object *obj); | ||
368 | |||
369 | /** | ||
370 | * Set whether to enlarge slider indicator (augmented knob) or not. | ||
371 | * | ||
372 | * @param obj The slider object. | ||
373 | * @param show @c EINA_TRUE will make it enlarge, @c EINA_FALSE will | ||
374 | * let the knob always at default size. | ||
375 | * | ||
376 | * By default, indicator will be bigger while dragged by the user. | ||
377 | * | ||
378 | * @warning It won't display values set with | ||
379 | * elm_slider_indicator_format_set() if you disable indicator. | ||
380 | * | ||
381 | * @ingroup Slider | ||
382 | */ | ||
383 | EAPI void elm_slider_indicator_show_set(Evas_Object *obj, Eina_Bool show); | ||
384 | |||
385 | /** | ||
386 | * Get whether a given slider widget's enlarging indicator or not. | ||
387 | * | ||
388 | * @param obj The slider object. | ||
389 | * @return @c EINA_TRUE, if @p obj is enlarging indicator, or | ||
390 | * @c EINA_FALSE otherwise (and on errors). | ||
391 | * | ||
392 | * @see elm_slider_indicator_show_set() for details. | ||
393 | * | ||
394 | * @ingroup Slider | ||
395 | */ | ||
396 | EAPI Eina_Bool elm_slider_indicator_show_get(const Evas_Object *obj); | ||
397 | |||
398 | /** | ||
399 | * @} | ||
400 | */ | ||