2 * @defgroup Diskselector Diskselector
5 * @image html img/widget/diskselector/preview-00.png
6 * @image latex img/widget/diskselector/preview-00.eps
8 * A diskselector is a kind of list widget. It scrolls horizontally,
9 * and can contain label and icon objects. Three items are displayed
10 * with the selected one in the middle.
12 * It can act like a circular list with round mode and labels can be
13 * reduced for a defined length for side items.
15 * Smart callbacks one can listen to:
16 * - "selected" - when item is selected, i.e. scroller stops.
18 * Available styles for it:
21 * Default contents parts of the diskseletor items that you can use for are:
22 * @li "icon" - An icon in the diskselector item
24 * Default text parts of the diskselector items that you can use for are:
25 * @li "default" - Label of the diskselector item
28 * @li @ref diskselector_example_01
29 * @li @ref diskselector_example_02
33 * @addtogroup Diskselector
38 * Add a new diskselector widget to the given parent Elementary
41 * @param parent The parent object.
42 * @return a new diskselector widget handle or @c NULL, on errors.
44 * This function inserts a new diskselector widget on the canvas.
46 * @ingroup Diskselector
48 EAPI Evas_Object *elm_diskselector_add(Evas_Object *parent);
51 * Enable or disable round mode.
53 * @param obj The diskselector object.
54 * @param round @c EINA_TRUE to enable round mode or @c EINA_FALSE to
57 * Disabled by default. If round mode is enabled the items list will
58 * work like a circle list, so when the user reaches the last item,
59 * the first one will popup.
61 * @see elm_diskselector_round_get()
63 * @ingroup Diskselector
65 EAPI void elm_diskselector_round_set(Evas_Object *obj, Eina_Bool round);
68 * Get a value whether round mode is enabled or not.
70 * @see elm_diskselector_round_set() for details.
72 * @param obj The diskselector object.
73 * @return @c EINA_TRUE means round mode is enabled. @c EINA_FALSE indicates
74 * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
76 * @ingroup Diskselector
78 EAPI Eina_Bool elm_diskselector_round_get(const Evas_Object *obj);
81 * Get the side labels max length.
83 * @see elm_diskselector_side_label_length_set() for details.
85 * @param obj The diskselector object.
86 * @return The max length defined for side labels, or 0 if not a valid
89 * @ingroup Diskselector
91 EAPI int elm_diskselector_side_label_length_get(const Evas_Object *obj);
94 * Set the side labels max length.
96 * @param obj The diskselector object.
97 * @param len The max length defined for side labels.
99 * Length is the number of characters of items' label that will be
100 * visible when it's set on side positions. It will just crop
101 * the string after defined size. E.g.:
103 * An item with label "January" would be displayed on side position as
104 * "Jan" if max length is set to 3, or "Janu", if this property
107 * When it's selected, the entire label will be displayed, except for
108 * width restrictions. In this case label will be cropped and "..."
109 * will be concatenated.
111 * Default side label max length is 3.
113 * This property will be applyed over all items, included before or
114 * later this function call.
116 * @ingroup Diskselector
118 EAPI void elm_diskselector_side_label_length_set(Evas_Object *obj, int len);
121 * Set the number of items to be displayed.
123 * @param obj The diskselector object.
124 * @param num The number of items the diskselector will display.
126 * Default value is 3, and also it's the minimun. If @p num is less
127 * than 3, it will be set to 3.
129 * Also, it can be set on theme, using data item @c display_item_num
130 * on group "elm/diskselector/item/X", where X is style set.
133 * group { name: "elm/diskselector/item/X";
135 * item: "display_item_num" "5";
138 * @ingroup Diskselector
140 EAPI void elm_diskselector_display_item_num_set(Evas_Object *obj, int num);
143 * Get the number of items in the diskselector object.
145 * @param obj The diskselector object.
147 * @ingroup Diskselector
149 EAPI int elm_diskselector_display_item_num_get(const Evas_Object *obj);
152 * Set bouncing behaviour when the scrolled content reaches an edge.
154 * Tell the internal scroller object whether it should bounce or not
155 * when it reaches the respective edges for each axis.
157 * @param obj The diskselector object.
158 * @param h_bounce Whether to bounce or not in the horizontal axis.
159 * @param v_bounce Whether to bounce or not in the vertical axis.
161 * @see elm_scroller_bounce_set()
163 * @ingroup Diskselector
165 EAPI void elm_diskselector_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
168 * Get the bouncing behaviour of the internal scroller.
170 * Get whether the internal scroller should bounce when the edge of each
171 * axis is reached scrolling.
173 * @param obj The diskselector object.
174 * @param h_bounce Pointer where to store the bounce state of the horizontal
176 * @param v_bounce Pointer where to store the bounce state of the vertical
179 * @see elm_scroller_bounce_get()
180 * @see elm_diskselector_bounce_set()
182 * @ingroup Diskselector
184 EAPI void elm_diskselector_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
187 * Get the scrollbar policy.
189 * @see elm_diskselector_scroller_policy_get() for details.
191 * @param obj The diskselector object.
192 * @param policy_h Pointer where to store horizontal scrollbar policy.
193 * @param policy_v Pointer where to store vertical scrollbar policy.
195 * @ingroup Diskselector
197 EAPI void elm_diskselector_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v);
200 * Set the scrollbar policy.
202 * @param obj The diskselector object.
203 * @param policy_h Horizontal scrollbar policy.
204 * @param policy_v Vertical scrollbar policy.
206 * This sets the scrollbar visibility policy for the given scroller.
207 * #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it
208 * is needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns
209 * it on all the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off.
210 * This applies respectively for the horizontal and vertical scrollbars.
212 * The both are disabled by default, i.e., are set to
213 * #ELM_SCROLLER_POLICY_OFF.
215 * @ingroup Diskselector
217 EAPI void elm_diskselector_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v);
220 * Remove all diskselector's items.
222 * @param obj The diskselector object.
224 * @see elm_diskselector_item_del()
225 * @see elm_diskselector_item_append()
227 * @ingroup Diskselector
229 EAPI void elm_diskselector_clear(Evas_Object *obj);
232 * Get a list of all the diskselector items.
234 * @param obj The diskselector object.
235 * @return An @c Eina_List of diskselector items, #Elm_Object_Item,
236 * or @c NULL on failure.
238 * @see elm_diskselector_item_append()
239 * @see elm_diskselector_item_del()
240 * @see elm_diskselector_clear()
242 * @ingroup Diskselector
244 EAPI const Eina_List *elm_diskselector_items_get(const Evas_Object *obj);
247 * Appends a new item to the diskselector object.
249 * @param obj The diskselector object.
250 * @param label The label of the diskselector item.
251 * @param icon The icon object to use at left side of the item. An
252 * icon can be any Evas object, but usually it is an icon created
253 * with elm_icon_add().
254 * @param func The function to call when the item is selected.
255 * @param data The data to associate with the item for related callbacks.
257 * @return The created item or @c NULL upon failure.
259 * A new item will be created and appended to the diskselector, i.e., will
260 * be set as last item. Also, if there is no selected item, it will
261 * be selected. This will always happens for the first appended item.
263 * If no icon is set, label will be centered on item position, otherwise
264 * the icon will be placed at left of the label, that will be shifted
267 * Items created with this method can be deleted with
268 * elm_diskselector_item_del().
270 * Associated @p data can be properly freed when item is deleted if a
271 * callback function is set with elm_object_item_del_cb_set().
273 * If a function is passed as argument, it will be called everytime this item
274 * is selected, i.e., the user stops the diskselector with this
275 * item on center position. If such function isn't needed, just passing
276 * @c NULL as @p func is enough. The same should be done for @p data.
278 * Simple example (with no function callback or data associated):
280 * disk = elm_diskselector_add(win);
281 * ic = elm_icon_add(win);
282 * elm_icon_file_set(ic, "path/to/image", NULL);
283 * elm_icon_scale_set(ic, EINA_TRUE, EINA_TRUE);
284 * elm_diskselector_item_append(disk, "label", ic, NULL, NULL);
287 * @see elm_diskselector_item_del()
288 * @see elm_diskselector_clear()
289 * @see elm_icon_add()
291 * @ingroup Diskselector
293 EAPI Elm_Object_Item *elm_diskselector_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data);
297 * Delete them item from the diskselector.
299 * @param it The item of diskselector to be deleted.
301 * If deleting all diskselector items is required, elm_diskselector_clear()
302 * should be used instead of getting items list and deleting each one.
304 * @see elm_diskselector_clear()
305 * @see elm_diskselector_item_append()
307 * @ingroup Diskselector
309 EAPI void elm_diskselector_item_del(Elm_Object_Item *it);
312 * Get the selected item.
314 * @param obj The diskselector object.
315 * @return The selected diskselector item.
317 * The selected item can be unselected with function
318 * elm_diskselector_item_selected_set(), and the first item of
319 * diskselector will be selected.
321 * The selected item always will be centered on diskselector, with
322 * full label displayed, i.e., max lenght set to side labels won't
323 * apply on the selected item. More details on
324 * elm_diskselector_side_label_length_set().
326 * @ingroup Diskselector
328 EAPI Elm_Object_Item *elm_diskselector_selected_item_get(const Evas_Object *obj);
331 * Set the selected state of an item.
333 * @param it The diskselector item
334 * @param selected The selected state
336 * This sets the selected state of the given item @p it.
337 * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
339 * If a new item is selected the previosly selected will be unselected.
340 * Previoulsy selected item can be get with function
341 * elm_diskselector_selected_item_get().
343 * If the item @p it is unselected, the first item of diskselector will
346 * Selected items will be visible on center position of diskselector.
347 * So if it was on another position before selected, or was invisible,
348 * diskselector will animate items until the selected item reaches center
351 * @see elm_diskselector_item_selected_get()
352 * @see elm_diskselector_selected_item_get()
354 * @ingroup Diskselector
356 EAPI void elm_diskselector_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
359 * Get whether the @p item is selected or not.
361 * @param it The diskselector item.
362 * @return @c EINA_TRUE means item is selected. @c EINA_FALSE indicates
363 * it's not. If @p obj is @c NULL, @c EINA_FALSE is returned.
365 * @see elm_diskselector_selected_item_set() for details.
366 * @see elm_diskselector_item_selected_get()
368 * @ingroup Diskselector
370 EAPI Eina_Bool elm_diskselector_item_selected_get(const Elm_Object_Item *it);
373 * Get the first item of the diskselector.
375 * @param obj The diskselector object.
376 * @return The first item, or @c NULL if none.
378 * The list of items follows append order. So it will return the first
379 * item appended to the widget that wasn't deleted.
381 * @see elm_diskselector_item_append()
382 * @see elm_diskselector_items_get()
384 * @ingroup Diskselector
386 EAPI Elm_Object_Item *elm_diskselector_first_item_get(const Evas_Object *obj);
389 * Get the last item of the diskselector.
391 * @param obj The diskselector object.
392 * @return The last item, or @c NULL if none.
394 * The list of items follows append order. So it will return last first
395 * item appended to the widget that wasn't deleted.
397 * @see elm_diskselector_item_append()
398 * @see elm_diskselector_items_get()
400 * @ingroup Diskselector
402 EAPI Elm_Object_Item *elm_diskselector_last_item_get(const Evas_Object *obj);
405 * Get the item before @p item in diskselector.
407 * @param it The diskselector item.
408 * @return The item before @p item, or @c NULL if none or on failure.
410 * The list of items follows append order. So it will return item appended
411 * just before @p item and that wasn't deleted.
413 * If it is the first item, @c NULL will be returned.
414 * First item can be get by elm_diskselector_first_item_get().
416 * @see elm_diskselector_item_append()
417 * @see elm_diskselector_items_get()
419 * @ingroup Diskselector
421 EAPI Elm_Object_Item *elm_diskselector_item_prev_get(const Elm_Object_Item *it);
424 * Get the item after @p item in diskselector.
426 * @param it The diskselector item.
427 * @return The item after @p item, or @c NULL if none or on failure.
429 * The list of items follows append order. So it will return item appended
430 * just after @p item and that wasn't deleted.
432 * If it is the last item, @c NULL will be returned.
433 * Last item can be get by elm_diskselector_last_item_get().
435 * @see elm_diskselector_item_append()
436 * @see elm_diskselector_items_get()
438 * @ingroup Diskselector
440 EAPI Elm_Object_Item *elm_diskselector_item_next_get(const Elm_Object_Item *it);
443 * Set the text to be shown in the diskselector item.
445 * @param it Target item
446 * @param text The text to set in the content
448 * Setup the text as tooltip to object. The item can have only one tooltip,
449 * so any previous tooltip data is removed.
451 * @see elm_object_tooltip_text_set() for more details.
453 * @ingroup Diskselector
455 EAPI void elm_diskselector_item_tooltip_text_set(Elm_Object_Item *it, const char *text);
458 * Set the content to be shown in the tooltip item.
460 * Setup the tooltip to item. The item can have only one tooltip,
461 * so any previous tooltip data is removed. @p func(with @p data) will
462 * be called every time that need show the tooltip and it should
463 * return a valid Evas_Object. This object is then managed fully by
464 * tooltip system and is deleted when the tooltip is gone.
466 * @param it the diskselector item being attached a tooltip.
467 * @param func the function used to create the tooltip contents.
468 * @param data what to provide to @a func as callback data/context.
469 * @param del_cb called when data is not needed anymore, either when
470 * another callback replaces @p func, the tooltip is unset with
471 * elm_diskselector_item_tooltip_unset() or the owner @a item
472 * dies. This callback receives as the first parameter the
473 * given @a data, and @c event_info is the item.
475 * @see elm_object_tooltip_content_cb_set() for more details.
477 * @ingroup Diskselector
479 EAPI void elm_diskselector_item_tooltip_content_cb_set(Elm_Object_Item *it, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb);
482 * Unset tooltip from item.
484 * @param it diskselector item to remove previously set tooltip.
486 * Remove tooltip from item. The callback provided as del_cb to
487 * elm_diskselector_item_tooltip_content_cb_set() will be called to notify
488 * it is not used anymore.
490 * @see elm_object_tooltip_unset() for more details.
491 * @see elm_diskselector_item_tooltip_content_cb_set()
493 * @ingroup Diskselector
495 EAPI void elm_diskselector_item_tooltip_unset(Elm_Object_Item *it);
498 * Sets a different style for this item tooltip.
500 * @note before you set a style you should define a tooltip with
501 * elm_diskselector_item_tooltip_content_cb_set() or
502 * elm_diskselector_item_tooltip_text_set()
504 * @param it diskselector item with tooltip already set.
505 * @param style the theme style to use (default, transparent, ...)
507 * @see elm_object_tooltip_style_set() for more details.
509 * @ingroup Diskselector
511 EAPI void elm_diskselector_item_tooltip_style_set(Elm_Object_Item *it, const char *style);
514 * Get the style for this item tooltip.
516 * @param it diskselector item with tooltip already set.
517 * @return style the theme style in use, defaults to "default". If the
518 * object does not have a tooltip set, then NULL is returned.
520 * @see elm_object_tooltip_style_get() for more details.
521 * @see elm_diskselector_item_tooltip_style_set()
523 * @ingroup Diskselector
525 EAPI const char *elm_diskselector_item_tooltip_style_get(const Elm_Object_Item *it);
528 * Set the cursor to be shown when mouse is over the diskselector item
530 * @param it Target item
531 * @param cursor the cursor name to be used.
533 * @see elm_object_cursor_set() for more details.
535 * @ingroup Diskselector
537 EAPI void elm_diskselector_item_cursor_set(Elm_Object_Item *it, const char *cursor);
540 * Get the cursor to be shown when mouse is over the diskselector item
542 * @param it diskselector item with cursor already set.
543 * @return the cursor name.
545 * @see elm_object_cursor_get() for more details.
546 * @see elm_diskselector_cursor_set()
548 * @ingroup Diskselector
550 EAPI const char *elm_diskselector_item_cursor_get(const Elm_Object_Item *it);
553 * Unset the cursor to be shown when mouse is over the diskselector item
555 * @param it Target item
557 * @see elm_object_cursor_unset() for more details.
558 * @see elm_diskselector_cursor_set()
560 * @ingroup Diskselector
562 EAPI void elm_diskselector_item_cursor_unset(Elm_Object_Item *it);
565 * Sets a different style for this item cursor.
567 * @note before you set a style you should define a cursor with
568 * elm_diskselector_item_cursor_set()
570 * @param it diskselector item with cursor already set.
571 * @param style the theme style to use (default, transparent, ...)
573 * @see elm_object_cursor_style_set() for more details.
575 * @ingroup Diskselector
577 EAPI void elm_diskselector_item_cursor_style_set(Elm_Object_Item *it, const char *style);
580 * Get the style for this item cursor.
582 * @param it diskselector item with cursor already set.
583 * @return style the theme style in use, defaults to "default". If the
584 * object does not have a cursor set, then @c NULL is returned.
586 * @see elm_object_cursor_style_get() for more details.
587 * @see elm_diskselector_item_cursor_style_set()
589 * @ingroup Diskselector
591 EAPI const char *elm_diskselector_item_cursor_style_get(const Elm_Object_Item *it);
595 * Set if the cursor set should be searched on the theme or should use
596 * the provided by the engine, only.
598 * @note before you set if should look on theme you should define a cursor
599 * with elm_diskselector_item_cursor_set().
600 * By default it will only look for cursors provided by the engine.
602 * @param it widget item with cursor already set.
603 * @param engine_only boolean to define if cursors set with
604 * elm_diskselector_item_cursor_set() should be searched only
605 * between cursors provided by the engine or searched on widget's
608 * @see elm_object_cursor_engine_only_set() for more details.
610 * @ingroup Diskselector
612 EAPI void elm_diskselector_item_cursor_engine_only_set(Elm_Object_Item *it, Eina_Bool engine_only);
615 * Get the cursor engine only usage for this item cursor.
617 * @param it widget item with cursor already set.
618 * @return engine_only boolean to define it cursors should be looked only
619 * between the provided by the engine or searched on widget's theme as well.
620 * If the item does not have a cursor set, then @c EINA_FALSE is returned.
622 * @see elm_object_cursor_engine_only_get() for more details.
623 * @see elm_diskselector_item_cursor_engine_only_set()
625 * @ingroup Diskselector
627 EAPI Eina_Bool elm_diskselector_item_cursor_engine_only_get(const Elm_Object_Item *it);