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.
64 elm_index_add(Evas_Object *parent)
68 * Set whether a given index widget is or not visible,
71 * @param obj The index object
72 * @param active @c EINA_TRUE to show it, @c EINA_FALSE to hide it
74 * Not to be confused with visible as in @c evas_object_show() --
75 * visible with regard to the widget's auto hiding feature.
77 * @see elm_index_active_get()
81 EAPI void elm_index_active_set(Evas_Object *obj, Eina_Bool active) EINA_ARG_NONNULL(1);
84 * Get whether a given index widget is currently visible or not.
86 * @param obj The index object
87 * @return @c EINA_TRUE, if it's shown, @c EINA_FALSE otherwise
89 * @see elm_index_active_set() for more details
93 EAPI Eina_Bool elm_index_active_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
96 * Set the items level for a given index widget.
98 * @param obj The index object.
99 * @param level @c 0 or @c 1, the currently implemented levels.
101 * @see elm_index_item_level_get()
105 EAPI void elm_index_item_level_set(Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
108 * Get the items level set for a given index widget.
110 * @param obj The index object.
111 * @return @c 0 or @c 1, which are the levels @p obj might be at.
113 * @see elm_index_item_level_set() for more information
117 EAPI int elm_index_item_level_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
120 * Returns the last selected item, for a given index widget.
122 * @param obj The index object.
123 * @return The last item @b selected on @p obj (or @c NULL, on errors).
127 EAPI Elm_Object_Item *elm_index_item_selected_get(const Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
130 * Append a new item on a given index widget.
132 * @param obj The index object.
133 * @param letter Letter under which the item should be indexed
134 * @param item The item data to set for the index's item
136 * Despite the most common usage of the @p letter argument is for
137 * single char strings, one could use arbitrary strings as index
140 * @c item will be the pointer returned back on @c "changed", @c
141 * "delay,changed" and @c "selected" smart events.
145 EAPI void elm_index_item_append(Evas_Object *obj, const char *letter, const void *item) EINA_ARG_NONNULL(1);
148 * Prepend a new item on a given index widget.
150 * @param obj The index object.
151 * @param letter Letter under which the item should be indexed
152 * @param item The item data to set for the index's item
154 * Despite the most common usage of the @p letter argument is for
155 * single char strings, one could use arbitrary strings as index
158 * @c item will be the pointer returned back on @c "changed", @c
159 * "delay,changed" and @c "selected" smart events.
163 EAPI void elm_index_item_prepend(Evas_Object *obj, const char *letter, const void *item) EINA_ARG_NONNULL(1);
166 * Append a new item, on a given index widget, <b>after the item
167 * having @p relative as data</b>.
169 * @param obj The index object.
170 * @param letter Letter under which the item should be indexed
171 * @param item The item data to set for the index's item
172 * @param relative The index item to be the predecessor of this new one
174 * Despite the most common usage of the @p letter argument is for
175 * single char strings, one could use arbitrary strings as index
178 * @c item will be the pointer returned back on @c "changed", @c
179 * "delay,changed" and @c "selected" smart events.
181 * @note If @p relative is @c NULL this function will behave as
182 * elm_index_item_append().
186 EAPI void elm_index_item_append_relative(Evas_Object *obj, const char *letter, const void *item, const Elm_Object_Item *relative) EINA_ARG_NONNULL(1);
189 * Prepend a new item, on a given index widget, <b>after the item
190 * having @p relative as data</b>.
192 * @param obj The index object.
193 * @param letter Letter under which the item should be indexed
194 * @param item The item data to set for the index's item
195 * @param relative The index item to be the successor of this new one
197 * Despite the most common usage of the @p letter argument is for
198 * single char strings, one could use arbitrary strings as index
201 * @c item will be the pointer returned back on @c "changed", @c
202 * "delay,changed" and @c "selected" smart events.
204 * @note If @p relative is @c NULL this function will behave as
205 * elm_index_item_prepend().
209 EAPI void elm_index_item_prepend_relative(Evas_Object *obj, const char *letter, const void *item, const Elm_Object_Item *relative) EINA_ARG_NONNULL(1);
212 * Insert a new item into the given index widget, using @p cmp_func
213 * function to sort items (by item handles).
215 * @param obj The index object.
216 * @param letter Letter under which the item should be indexed
217 * @param item The item data to set for the index's item
218 * @param cmp_func The comparing function to be used to sort index
219 * items <b>by #index item handles</b>
220 * @param cmp_data_func A @b fallback function to be called for the
221 * sorting of index items <b>by item data</b>). It will be used
222 * when @p cmp_func returns @c 0 (equality), which means an index
223 * item with provided item data already exists. To decide which
224 * data item should be pointed to by the index item in question, @p
225 * cmp_data_func will be used. If @p cmp_data_func returns a
226 * non-negative value, the previous index item data will be
227 * replaced by the given @p item pointer. If the previous data need
228 * to be freed, it should be done by the @p cmp_data_func function,
229 * because all references to it will be lost. If this function is
230 * not provided (@c NULL is given), index items will be @b
231 * duplicated, if @p cmp_func returns @c 0.
233 * Despite the most common usage of the @p letter argument is for
234 * single char strings, one could use arbitrary strings as index
237 * @c item will be the pointer returned back on @c "changed", @c
238 * "delay,changed" and @c "selected" smart events.
242 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) EINA_ARG_NONNULL(1);
245 * Remove an item from a given index widget, <b>to be referenced by
246 * it's data value</b>.
248 * @param obj The index object
249 * @param item The item to be removed from @p obj
251 * If a deletion callback is set, via elm_index_item_del_cb_set(),
252 * that callback function will be called by this one.
256 EAPI void elm_index_item_del(Evas_Object *obj, Elm_Object_Item *item) EINA_ARG_NONNULL(1);
259 * Find a given index widget's item, <b>using item data</b>.
261 * @param obj The index object
262 * @param item The item data pointed to by the desired index item
263 * @return The index item handle, if found, or @c NULL otherwise
267 EAPI Elm_Object_Item *elm_index_item_find(Evas_Object *obj, const void *item) EINA_ARG_NONNULL(1);
270 * Removes @b all items from a given index widget.
272 * @param obj The index object.
274 * If deletion callbacks are set, via elm_index_item_del_cb_set(),
275 * that callback function will be called for each item in @p obj.
279 EAPI void elm_index_item_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
282 * Go to a given items level on a index widget
284 * @param obj The index object
285 * @param level The index level (one of @c 0 or @c 1)
289 EAPI void elm_index_item_go(Evas_Object *obj, int level) EINA_ARG_NONNULL(1);
292 * Return the data associated with a given index widget item
294 * @param it The index widget item handle
295 * @return The data associated with @p it
297 * @see elm_index_item_data_set()
298 * @deprecated Use elm_object_item_data_get() instead
302 EINA_DEPRECATED EAPI void *elm_index_item_data_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);
305 * Set the data associated with a given index widget item
307 * @param it The index widget item handle
308 * @param data The new data pointer to set to @p it
310 * This sets new item data on @p it.
312 * @warning The old data pointer won't be touched by this function, so
313 * the user had better to free that old data himself/herself.
315 * @deprecated Use elm_object_item_data_set() instead
318 EINA_DEPRECATED EAPI void elm_index_item_data_set(Elm_Object_Item *it, const void *data) EINA_ARG_NONNULL(1);
321 * Set the function to be called when a given index widget item is freed.
323 * @param it The item to set the callback on
324 * @param func The function to call on the item's deletion
326 * When called, @p func will have both @c data and @c event_info
327 * arguments with the @p it item's data value and, naturally, the
328 * @c obj argument with a handle to the parent index widget.
332 EAPI void elm_index_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
335 * Get the letter (string) set on a given index widget item.
337 * @param it The index item handle
338 * @return The letter string set on @p it
342 EAPI const char *elm_index_item_letter_get(const Elm_Object_Item *item) EINA_ARG_NONNULL(1);