2 * @defgroup Diskselector Diskselector
5 * @image html diskselector_inheritance_tree.png
6 * @image latex diskselector_inheritance_tree.eps
8 * @image html img/widget/diskselector/preview-00.png
9 * @image latex img/widget/diskselector/preview-00.eps
11 * A diskselector is a kind of list widget. It scrolls horizontally,
12 * and can contain label and icon objects. Three items are displayed
13 * with the selected one in the middle.
15 * It can act like a circular list with round mode and labels can be
16 * reduced for a defined length for side items.
18 * This widget implements the @b @ref elm-scrollable-interface
19 * interface, so that all (non-deprecated) functions for the base @ref
20 * Scroller widget also work for diskselectors.
22 * Some calls on the diskselector's API are marked as @b deprecated,
23 * as they just wrap the scrollable widgets counterpart functions. Use
24 * the ones we point you to, for each case of deprecation here,
25 * instead -- eventually the deprecated ones will be discarded (next
28 * This widget emits the following signals, besides the ones sent from
30 * @li @c "selected" - when item is selected, i.e. scroller stops.
31 * @li @c "clicked" - This is called when a user clicks an item (@since 1.8)
32 * @li @c "scroll,anim,start" - scrolling animation has started
33 * @li @c "scroll,anim,stop" - scrolling animation has stopped
34 * @li @c "scroll,drag,start" - dragging the diskselector has started
35 * @li @c "scroll,drag,stop" - dragging the diskselector has stopped
36 * @note The "scroll,anim,*" and "scroll,drag,*" signals are only emitted by
39 * Available styles for it:
42 * Default content parts of the diskselector items that you can use for are:
43 * @li "icon" - An icon in the diskselector item
45 * Default text parts of the diskselector items that you can use for are:
46 * @li "default" - Label of the diskselector item
48 * Supported elm_object_item common APIs.
49 * @li @ref elm_object_item_part_text_set
50 * @li @ref elm_object_item_part_text_get
51 * @li @ref elm_object_item_part_content_set
52 * @li @ref elm_object_item_part_content_get
55 * @li @ref diskselector_example_01
56 * @li @ref diskselector_example_02
60 * @addtogroup Diskselector
65 * Add a new diskselector widget to the given parent Elementary
68 * @param parent The parent object.
69 * @return a new diskselector widget handle or @c NULL, on errors.
71 * This function inserts a new diskselector widget on the canvas.
73 * @ingroup Diskselector
75 EAPI Evas_Object *elm_diskselector_add(Evas_Object *parent);
78 * Enable or disable round mode.
80 * @param obj The diskselector object.
81 * @param enabled @c EINA_TRUE to enable round mode or @c EINA_FALSE to
84 * Disabled by default. If round mode is enabled the items list will
85 * work like a circular list, so when the user reaches the last item,
86 * the first one will popup.
88 * @see elm_diskselector_round_enabled_get()
90 * @ingroup Diskselector
92 EAPI void elm_diskselector_round_enabled_set(Evas_Object *obj, Eina_Bool enabled);
95 * Get a value whether round mode is enabled or not.
97 * @see elm_diskselector_round_enabled_set() for details.
99 * @param obj The diskselector object.
100 * @return @c EINA_TRUE means round mode is enabled. @c EINA_FALSE indicates
101 * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
103 * @ingroup Diskselector
105 EAPI Eina_Bool elm_diskselector_round_enabled_get(const Evas_Object *obj);
108 * Get the side labels max length.
110 * @see elm_diskselector_side_text_max_length_set() for details.
112 * @param obj The diskselector object.
113 * @return The max length defined for side labels, or 0 if not a valid
116 * @ingroup Diskselector
118 EAPI int elm_diskselector_side_text_max_length_get(const Evas_Object *obj);
121 * Set the side labels max length.
123 * @param obj The diskselector object.
124 * @param len The max length defined for side labels.
126 * Length is the number of characters of items' label that will be
127 * visible when it's set on side positions. It will just crop
128 * the string after defined size. E.g.:
130 * An item with label "January" would be displayed on side position as
131 * "Jan" if max length is set to 3, or "Janu", if this property
134 * When it's selected, the entire label will be displayed, except for
135 * width restrictions. In this case label will be cropped and "..."
136 * will be concatenated.
138 * Default side label max length is 3.
140 * This property will be applied over all items, included before or
141 * later this function call.
143 * @ingroup Diskselector
145 EAPI void elm_diskselector_side_text_max_length_set(Evas_Object *obj, int len);
148 * Set the number of items to be displayed.
150 * @param obj The diskselector object.
151 * @param num The number of items the diskselector will display.
153 * Default value is 3, and also it's the minimum. If @p num is less
154 * than 3, it will be set to 3.
156 * Also, it can be set on theme, using data item @c display_item_num
157 * on group "elm/diskselector/item/X", where X is style set.
160 * group { name: "elm/diskselector/item/X";
162 * item: "display_item_num" "5";
165 * @ingroup Diskselector
167 EAPI void elm_diskselector_display_item_num_set(Evas_Object *obj, int num);
170 * Get the number of items in the diskselector object.
172 * @param obj The diskselector object.
174 * @ingroup Diskselector
176 EAPI int elm_diskselector_display_item_num_get(const Evas_Object *obj);
179 * Set bouncing behaviour when the scrolled content reaches an edge.
181 * Tell the internal scroller object whether it should bounce or not
182 * when it reaches the respective edges for each axis.
184 * @param obj The diskselector object.
185 * @param h_bounce Whether to bounce or not in the horizontal axis.
186 * @param v_bounce Whether to bounce or not in the vertical axis.
188 * @deprecated Use elm_scroller_bounce_set() instead.
190 * @see elm_scroller_bounce_set()
192 * @ingroup Diskselector
194 EINA_DEPRECATED EAPI void elm_diskselector_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
197 * Get the bouncing behaviour of the internal scroller.
199 * Get whether the internal scroller should bounce when the edge of each
200 * axis is reached scrolling.
202 * @param obj The diskselector object.
203 * @param h_bounce Pointer to store the bounce state of the horizontal
205 * @param v_bounce Pointer to store the bounce state of the vertical
208 * @deprecated Use elm_scroller_bounce_get() instead.
210 * @see elm_scroller_bounce_get()
211 * @see elm_diskselector_bounce_set()
213 * @ingroup Diskselector
215 EINA_DEPRECATED EAPI void elm_diskselector_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
218 * Get the scrollbar policy.
220 * @see elm_diskselector_scroller_policy_get() for details.
222 * @param obj The diskselector object.
223 * @param policy_h Pointer to store horizontal scrollbar policy.
224 * @param policy_v Pointer to store vertical scrollbar policy.
226 * @deprecated Use elm_scroller_policy_get() instead.
228 * @see elm_scroller_policy_get()
230 * @ingroup Diskselector
232 EINA_DEPRECATED EAPI void elm_diskselector_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v);
235 * Set the scrollbar policy.
237 * @param obj The diskselector object.
238 * @param policy_h Horizontal scrollbar policy.
239 * @param policy_v Vertical scrollbar policy.
241 * This sets the scrollbar visibility policy for the given
242 * scroller. #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if
243 * it is needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns
244 * it on all the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off.
245 * This applies respectively for the horizontal and vertical scrollbars.
247 * The both are disabled by default, i.e., are set to #ELM_SCROLLER_POLICY_OFF.
249 * @deprecated Use elm_scroller_policy_set() instead.
251 * @see elm_scroller_policy_set()
253 * @ingroup Diskselector
255 EINA_DEPRECATED EAPI void elm_diskselector_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v);
258 * Remove all diskselector's items.
260 * @param obj The diskselector object.
262 * @see elm_object_item_del()
263 * @see elm_diskselector_item_append()
265 * @ingroup Diskselector
267 EAPI void elm_diskselector_clear(Evas_Object *obj);
270 * Get a list of all the diskselector items.
272 * @param obj The diskselector object.
273 * @return An @c Eina_List of diskselector items, #Elm_Object_Item,
274 * or @c NULL on failure.
276 * @see elm_diskselector_item_append()
277 * @see elm_object_item_del()
278 * @see elm_diskselector_clear()
280 * @ingroup Diskselector
282 EAPI const Eina_List *elm_diskselector_items_get(const Evas_Object *obj);
285 * Appends a new item to the diskselector object.
287 * @param obj The diskselector object.
288 * @param label The label of the diskselector item.
289 * @param icon The icon object to use at left side of the item. An
290 * icon can be any Evas object, but usually it is an icon created
291 * with elm_icon_add().
292 * @param func The function to call when the item is selected.
293 * @param data The data to associate with the item for related callbacks.
295 * @return The created item or @c NULL upon failure.
297 * A new item will be created and appended to the diskselector, i.e., will
298 * be set as last item. Also, if there is no selected item, it will
299 * be selected. This will always happens for the first appended item.
301 * If no icon is set, label will be centered on item position, otherwise
302 * the icon will be placed at left of the label, that will be shifted
305 * Items created with this method can be deleted with
306 * elm_object_item_del().
308 * Associated @p data can be properly freed when item is deleted if a
309 * callback function is set with elm_object_item_del_cb_set().
311 * If a function is passed as argument, it will be called every time this item
312 * is selected, i.e., the user stops the diskselector with this
313 * item on center position. If such function isn't needed, just passing
314 * @c NULL as @p func is enough. The same should be done for @p data.
316 * Simple example (with no function callback or data associated):
318 * disk = elm_diskselector_add(win);
319 * ic = elm_icon_add(win);
320 * elm_image_file_set(ic, "path/to/image", NULL);
321 * elm_icon_resizable_set(ic, EINA_TRUE, EINA_TRUE);
322 * elm_diskselector_item_append(disk, "label", ic, NULL, NULL);
325 * @see elm_object_item_del()
326 * @see elm_diskselector_clear()
327 * @see elm_icon_add()
329 * @ingroup Diskselector
331 EAPI Elm_Object_Item *elm_diskselector_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data);
334 * Get the selected item.
336 * @param obj The diskselector object.
337 * @return The selected diskselector item.
339 * The selected item can be unselected with function
340 * elm_diskselector_item_selected_set(), and the first item of
341 * diskselector will be selected.
343 * The selected item always will be centered on diskselector, with
344 * full label displayed, i.e., max length set to side labels won't
345 * apply on the selected item. More details on
346 * elm_diskselector_side_text_max_length_set().
348 * @ingroup Diskselector
350 EAPI Elm_Object_Item *elm_diskselector_selected_item_get(const Evas_Object *obj);
353 * Set the selected state of an item.
355 * @param it The diskselector item
356 * @param selected The selected state
358 * This sets the selected state of the given item @p it.
359 * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
361 * If a new item is selected the previously selected will be unselected.
362 * Previously selected item can be get with function
363 * elm_diskselector_selected_item_get().
365 * If the item @p it is unselected, the first item of diskselector will
368 * Selected items will be visible on center position of diskselector.
369 * So if it was on another position before selected, or was invisible,
370 * diskselector will animate items until the selected item reaches center
373 * @see elm_diskselector_item_selected_get()
374 * @see elm_diskselector_selected_item_get()
376 * @ingroup Diskselector
378 EAPI void elm_diskselector_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
381 * Get whether the @p item is selected or not.
383 * @param it The diskselector item.
384 * @return @c EINA_TRUE means item is selected. @c EINA_FALSE indicates
385 * it's not. If @p obj is @c NULL, @c EINA_FALSE is returned.
387 * @see elm_diskselector_selected_item_set() for details.
388 * @see elm_diskselector_item_selected_get()
390 * @ingroup Diskselector
392 EAPI Eina_Bool elm_diskselector_item_selected_get(const Elm_Object_Item *it);
395 * Get the first item of the diskselector.
397 * @param obj The diskselector object.
398 * @return The first item, or @c NULL if none.
400 * The list of items follows append order. So it will return the first
401 * item appended to the widget that wasn't deleted.
403 * @see elm_diskselector_item_append()
404 * @see elm_diskselector_items_get()
406 * @ingroup Diskselector
408 EAPI Elm_Object_Item *elm_diskselector_first_item_get(const Evas_Object *obj);
411 * Get the last item of the diskselector.
413 * @param obj The diskselector object.
414 * @return The last item, or @c NULL if none.
416 * The list of items follows append order. So it will return last first
417 * item appended to the widget that wasn't deleted.
419 * @see elm_diskselector_item_append()
420 * @see elm_diskselector_items_get()
422 * @ingroup Diskselector
424 EAPI Elm_Object_Item *elm_diskselector_last_item_get(const Evas_Object *obj);
427 * Get the item before @p item in diskselector.
429 * @param it The diskselector item.
430 * @return The item before @p item, or @c NULL if none or on failure.
432 * The list of items follows append order. So it will return item appended
433 * just before @p item and that wasn't deleted.
435 * If it is the first item, @c NULL will be returned.
436 * First item can be get by elm_diskselector_first_item_get().
438 * @see elm_diskselector_item_append()
439 * @see elm_diskselector_items_get()
441 * @ingroup Diskselector
443 EAPI Elm_Object_Item *elm_diskselector_item_prev_get(const Elm_Object_Item *it);
446 * Get the item after @p item in diskselector.
448 * @param it The diskselector item.
449 * @return The item after @p item, or @c NULL if none or on failure.
451 * The list of items follows append order. So it will return item appended
452 * just after @p item and that wasn't deleted.
454 * If it is the last item, @c NULL will be returned.
455 * Last item can be get by elm_diskselector_last_item_get().
457 * @see elm_diskselector_item_append()
458 * @see elm_diskselector_items_get()
460 * @ingroup Diskselector
462 EAPI Elm_Object_Item *elm_diskselector_item_next_get(const Elm_Object_Item *it);