2 * @defgroup Index Index
4 * @image html img/widget/index/preview-00.png
5 * @image latex img/widget/index/preview-00.eps
7 * An index widget gives you an index for fast access to whichever
8 * group of other UI items one might have. It's a list of text
9 * items (usually letters, for alphabetically ordered access).
11 * Index widgets are by default hidden and just appear when the
12 * user clicks over it's reserved area in the canvas. In its
13 * default theme, it's an area one @ref Fingers "finger" wide on
14 * the right side of the index widget's container.
16 * When items on the index are selected, smart callbacks get
17 * called, so that its user can make other container objects to
18 * show a given area or child object depending on the index item
19 * selected. You'd probably be using an index together with @ref
20 * List "lists", @ref Genlist "generic lists" or @ref Gengrid
23 * Smart events one can add callbacks for are:
24 * - @c "changed" - When the selected index item changes. @c
25 * event_info is the selected item's data pointer.
26 * - @c "delay,changed" - When the selected index item changes, but
27 * after a small idling period. @c event_info is the selected
28 * item's data pointer.
29 * - @c "selected" - When the user releases a mouse button and
30 * selects an item. @c event_info is the selected item's data
32 * - @c "level,up" - when the user moves a finger from the first
33 * level to the second level
34 * - @c "level,down" - when the user moves a finger from the second
35 * level to the first level
37 * The @c "delay,changed" event is so that it'll wait a small time
38 * before actually reporting those events and, moreover, just the
39 * last event happening on those time frames will actually be
42 * Here are some examples on its usage:
43 * @li @ref index_example_01
44 * @li @ref index_example_02
53 * Add a new index widget to the given parent Elementary
56 * @param parent The parent object
57 * @return a new index widget handle or @c NULL, on errors
59 * This function inserts a new index widget on the canvas.
63 EAPI Evas_Object *elm_index_add(Evas_Object *parent);
66 * Enable or disable auto hiding feature for a given index widget.
68 * @param obj The index object
70 * @param active @c EINA_TRUE to enable auto hiding, @c EINA_FALSE to disable
72 * @see elm_index_active_get()
76 EAPI void elm_index_active_set(Evas_Object *obj, Eina_Bool active);
78 * @param disabled @c EINA_TRUE to disable auto hiding, @c EINA_FALSE to enable
80 * @see elm_index_autohide_disabled_get()
84 EAPI void elm_index_autohide_disabled_set(Evas_Object *obj, Eina_Bool disabled);
85 >>>>>>> remotes/origin/upstream
88 * Get whether auto hiding feature is enabled or not for a given index widget.
90 * @param obj The index object
92 * @return @c EINA_TRUE, if auto hiding is enabled, @c EINA_FALSE otherwise
94 * @return @c EINA_TRUE, if auto hiding is disabled, @c EINA_FALSE otherwise
95 >>>>>>> remotes/origin/upstream
97 * @see elm_index_active_set() for more details
102 EAPI Eina_Bool elm_index_active_get(const Evas_Object *obj);
104 EAPI Eina_Bool elm_index_autohide_disabled_get(const Evas_Object *obj);
105 >>>>>>> remotes/origin/upstream
108 * Set the items level for a given index widget.
110 * @param obj The index object.
111 * @param level @c 0 or @c 1, the currently implemented levels.
113 * @see elm_index_item_level_get()
117 EAPI void elm_index_item_level_set(Evas_Object *obj, int level);
120 * Get the items level set for a given index widget.
122 * @param obj The index object.
123 * @return @c 0 or @c 1, which are the levels @p obj might be at.
125 * @see elm_index_item_level_set() for more information
129 EAPI int elm_index_item_level_get(const Evas_Object *obj);
134 * Set the selected state of an item.
136 * @param it The index item
137 * @param selected The selected state
139 * This sets the selected state of the given item @p it.
140 * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
142 * If a new item is selected the previously selected will be unselected.
143 * Previously selected item can be get with function
144 * elm_index_selected_item_get().
146 * Selected items will be highlighted.
148 * @see elm_index_item_selected_get()
149 * @see elm_index_selected_item_get()
153 EAPI void elm_index_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
156 >>>>>>> remotes/origin/upstream
157 * Returns the last selected item, for a given index widget.
159 * @param obj The index object.
160 * @return The last item @b selected on @p obj (or @c NULL, on errors).
165 EAPI Elm_Object_Item *elm_index_item_selected_get(const Evas_Object *obj, int level);
167 EAPI Elm_Object_Item *elm_index_selected_item_get(const Evas_Object *obj, int level);
168 >>>>>>> remotes/origin/upstream
171 * Append a new item on a given index widget.
173 * @param obj The index object.
174 * @param letter Letter under which the item should be indexed
176 * @param item The item data to set for the index's item
178 * @param func The function to call when the item is selected.
179 * @param data The item data to set for the index's item
180 * @return A handle to the item added or @c NULL, on errors
181 >>>>>>> remotes/origin/upstream
183 * Despite the most common usage of the @p letter argument is for
184 * single char strings, one could use arbitrary strings as index
187 * @c item will be the pointer returned back on @c "changed", @c
188 * "delay,changed" and @c "selected" smart events.
193 EAPI void elm_index_item_append(Evas_Object *obj, const char *letter, const void *item);
195 EAPI Elm_Object_Item *elm_index_item_append(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data);
196 >>>>>>> remotes/origin/upstream
199 * Prepend a new item on a given index widget.
201 * @param obj The index object.
202 * @param letter Letter under which the item should be indexed
204 * @param item The item data to set for the index's item
206 * @param func The function to call when the item is selected.
207 * @param data The item data to set for the index's item
208 * @return A handle to the item added or @c NULL, on errors
209 >>>>>>> remotes/origin/upstream
211 * Despite the most common usage of the @p letter argument is for
212 * single char strings, one could use arbitrary strings as index
215 * @c item will be the pointer returned back on @c "changed", @c
216 * "delay,changed" and @c "selected" smart events.
221 EAPI void elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item);
224 * Append a new item, on a given index widget, <b>after the item
225 * having @p relative as data</b>.
227 * @param obj The index object.
228 * @param letter Letter under which the item should be indexed
229 * @param item The item data to set for the index's item
230 * @param relative The index item to be the predecessor of this new one
232 EAPI Elm_Object_Item *elm_index_item_prepend(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data);
235 * Insert a new item into the index object after item @p after.
237 * @param obj The index object.
238 * @param after The index item to insert after.
239 * @param letter Letter under which the item should be indexed
240 * @param func The function to call when the item is clicked.
241 * @param data The item data to set for the index's item
242 * @return A handle to the item added or @c NULL, on errors
243 >>>>>>> remotes/origin/upstream
245 * Despite the most common usage of the @p letter argument is for
246 * single char strings, one could use arbitrary strings as index
249 * @c item will be the pointer returned back on @c "changed", @c
250 * "delay,changed" and @c "selected" smart events.
252 * @note If @p relative is @c NULL this function will behave as
253 * elm_index_item_append().
258 EAPI void elm_index_item_append_relative(Evas_Object *obj, const char *letter, const void *item, const Elm_Object_Item *relative);
261 * Prepend a new item, on a given index widget, <b>after the item
262 * having @p relative as data</b>.
264 * @param obj The index object.
265 * @param letter Letter under which the item should be indexed
266 * @param item The item data to set for the index's item
267 * @param relative The index item to be the successor of this new one
269 EAPI Elm_Object_Item *elm_index_item_insert_after(Evas_Object *obj, Elm_Object_Item *after, const char *letter, Evas_Smart_Cb func, const void *data);
272 * Insert a new item into the index object before item @p before.
274 * @param obj The index object.
275 * @param before The index item to insert after.
276 * @param letter Letter under which the item should be indexed
277 * @param func The function to call when the item is clicked.
278 * @param data The item data to set for the index's item
279 * @return A handle to the item added or @c NULL, on errors
280 >>>>>>> remotes/origin/upstream
282 * Despite the most common usage of the @p letter argument is for
283 * single char strings, one could use arbitrary strings as index
286 * @c item will be the pointer returned back on @c "changed", @c
287 * "delay,changed" and @c "selected" smart events.
289 * @note If @p relative is @c NULL this function will behave as
290 * elm_index_item_prepend().
295 EAPI void elm_index_item_prepend_relative(Evas_Object *obj, const char *letter, const void *item, const Elm_Object_Item *relative);
297 EAPI Elm_Object_Item *elm_index_item_insert_before(Evas_Object *obj, Elm_Object_Item *before, const char *letter, Evas_Smart_Cb func, const void *data);
298 >>>>>>> remotes/origin/upstream
301 * Insert a new item into the given index widget, using @p cmp_func
302 * function to sort items (by item handles).
304 * @param obj The index object.
305 * @param letter Letter under which the item should be indexed
307 * @param item The item data to set for the index's item
309 * @param func The function to call when the item is clicked.
310 * @param data The item data to set for the index's item
311 >>>>>>> remotes/origin/upstream
312 * @param cmp_func The comparing function to be used to sort index
313 * items <b>by #index item handles</b>
314 * @param cmp_data_func A @b fallback function to be called for the
315 * sorting of index items <b>by item data</b>). It will be used
316 * when @p cmp_func returns @c 0 (equality), which means an index
317 * item with provided item data already exists. To decide which
318 * data item should be pointed to by the index item in question, @p
319 * cmp_data_func will be used. If @p cmp_data_func returns a
320 * non-negative value, the previous index item data will be
321 * replaced by the given @p item pointer. If the previous data need
322 * to be freed, it should be done by the @p cmp_data_func function,
323 * because all references to it will be lost. If this function is
324 * not provided (@c NULL is given), index items will be @b
325 * duplicated, if @p cmp_func returns @c 0.
328 * @return A handle to the item added or @c NULL, on errors
329 >>>>>>> remotes/origin/upstream
331 * Despite the most common usage of the @p letter argument is for
332 * single char strings, one could use arbitrary strings as index
335 * @c item will be the pointer returned back on @c "changed", @c
336 * "delay,changed" and @c "selected" smart events.
341 EAPI void elm_index_item_sorted_insert(Evas_Object *obj, const char *letter, const void *item, Eina_Compare_Cb cmp_func, Eina_Compare_Cb cmp_data_func);
343 EAPI Elm_Object_Item *elm_index_item_sorted_insert(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data, Eina_Compare_Cb cmp_func, Eina_Compare_Cb cmp_data_func);
344 >>>>>>> remotes/origin/upstream
347 * Find a given index widget's item, <b>using item data</b>.
349 * @param obj The index object
351 * @param item The item data pointed to by the desired index item
353 * @param data The item data pointed to by the desired index item
354 >>>>>>> remotes/origin/upstream
355 * @return The index item handle, if found, or @c NULL otherwise
360 EAPI Elm_Object_Item *elm_index_item_find(Evas_Object *obj, const void *item);
362 EAPI Elm_Object_Item *elm_index_item_find(Evas_Object *obj, const void *data);
363 >>>>>>> remotes/origin/upstream
366 * Removes @b all items from a given index widget.
368 * @param obj The index object.
370 * If deletion callbacks are set, via elm_object_item_del_cb_set(),
371 * that callback function will be called for each item in @p obj.
375 EAPI void elm_index_item_clear(Evas_Object *obj);
378 * Go to a given items level on a index widget
380 * @param obj The index object
381 * @param level The index level (one of @c 0 or @c 1)
386 EAPI void elm_index_item_go(Evas_Object *obj, int level);
388 EAPI void elm_index_level_go(Evas_Object *obj, int level);
389 >>>>>>> remotes/origin/upstream
392 * Get the letter (string) set on a given index widget item.
394 * @param item The index item handle
395 * @return The letter string set on @p it
399 EAPI const char *elm_index_item_letter_get(const Elm_Object_Item *item);
402 * Set the indicator as to be disabled.
404 * @param obj The index object
405 * @param disabled @c EINA_TRUE to disable it, @c EINA_FALSE to enable it
407 * In Index widget, Indicator notes popup text, which shows a letter has been selecting.
409 * @see elm_index_indicator_disabled_get()
413 EAPI void elm_index_indicator_disabled_set(Evas_Object *obj, Eina_Bool disabled);
416 * Get the value of indicator's disabled status.
418 * @param obj The index object
419 * @return EINA_TRUE if the indicator is disabled.
421 * @see elm_index_indicator_disabled_set()
426 EAPI Eina_Bool elm_index_indicator_disabled_get(const Evas_Object *obj);
428 EAPI void elm_index_button_image_invisible_set(Evas_Object *obj, Eina_Bool invisible);
430 EAPI Eina_Bool elm_index_indicator_disabled_get(const Evas_Object *obj);
433 * Enable or disable horizontal mode on the index object
435 * @param obj The index object.
436 * @param horizontal @c EINA_TRUE to enable horizontal or @c EINA_FALSE to
437 * disable it, i.e., to enable vertical mode. it's an area one @ref Fingers
438 * "finger" wide on the bottom side of the index widget's container.
440 * @note Vertical mode is set by default.
442 * On horizontal mode items are displayed on index from left to right,
443 * instead of from top to bottom. Also, the index will scroll horizontally.
445 * @see elm_index_horizontal_get()
449 EAPI void elm_index_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
452 * Get a value whether horizontal mode is enabled or not.
454 * @param obj The index object.
455 * @return @c EINA_TRUE means horizontal mode selection is enabled.
456 * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
457 * @c EINA_FALSE is returned.
459 * @see elm_index_horizontal_set() for details.
463 EAPI Eina_Bool elm_index_horizontal_get(const Evas_Object *obj);
464 >>>>>>> remotes/origin/upstream