2 * @defgroup Index Index
5 * @image html index_inheritance_tree.png
6 * @image latex index_inheritance_tree.eps
8 * @image html img/widget/index/preview-00.png
9 * @image latex img/widget/index/preview-00.eps
11 * An index widget gives you an index for fast access to whichever
12 * group of other UI items one might have. It's a list of text
13 * items (usually letters, for alphabetically ordered access).
15 * Index widgets are by default hidden and just appear when the
16 * user clicks over it's reserved area in the canvas. In its
17 * default theme, it's an area one @ref Fingers "finger" wide on
18 * the right side of the index widget's container.
20 * When items on the index are selected, smart callbacks get
21 * called, so that its user can make other container objects to
22 * show a given area or child object depending on the index item
23 * selected. You'd probably be using an index together with @ref
24 * List "lists", @ref Genlist "generic lists" or @ref Gengrid
27 * This widget inherits from the @ref Layout one, so that all the
28 * functions acting on it also work for index objects.
30 * This widget emits the following signals, besides the ones sent from
32 * - @c "changed" - When the selected index item changes. @c
33 * event_info is the selected item's data pointer.
34 * - @c "delay,changed" - When the selected index item changes, but
35 * after a small idling period. @c event_info is the selected
36 * item's data pointer.
37 * - @c "selected" - When the user releases a mouse button and
38 * selects an item. @c event_info is the selected item's data
40 * - @c "level,up" - when the user moves a finger from the first
41 * level to the second level
42 * - @c "level,down" - when the user moves a finger from the second
43 * level to the first level
44 * - @c "language,changed" - the program's language changed
46 * The @c "delay,changed" event is so that it'll wait a small time
47 * before actually reporting those events and, moreover, just the
48 * last event happening on those time frames will actually be
51 * Here are some examples on its usage:
52 * @li @ref index_example_01
53 * @li @ref index_example_02
62 * Add a new index widget to the given parent Elementary
65 * @param parent The parent object
66 * @return a new index widget handle or @c NULL, on errors
68 * This function inserts a new index widget on the canvas.
72 EAPI Evas_Object *elm_index_add(Evas_Object *parent);
75 * Enable or disable auto hiding feature for a given index widget.
77 * @param obj The index object
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);
87 * Get whether auto hiding feature is enabled or not for a given index widget.
89 * @param obj The index object
90 * @return @c EINA_TRUE, if auto hiding is disabled, @c EINA_FALSE otherwise
92 * @see elm_index_autohide_disabled_set() for more details
96 EAPI Eina_Bool elm_index_autohide_disabled_get(const Evas_Object *obj);
99 * Set the items level for a given index widget.
101 * @param obj The index object.
102 * @param level @c 0 or @c 1, the currently implemented levels.
104 * @see elm_index_item_level_get()
108 EAPI void elm_index_item_level_set(Evas_Object *obj, int level);
111 * Get the items level set for a given index widget.
113 * @param obj The index object.
114 * @return @c 0 or @c 1, which are the levels @p obj might be at.
116 * @see elm_index_item_level_set() for more information
120 EAPI int elm_index_item_level_get(const Evas_Object *obj);
123 * Set the selected state of an item.
125 * @param it The index item
126 * @param selected The selected state
128 * This sets the selected state of the given item @p it.
129 * @c EINA_TRUE for selected, @c EINA_FALSE for not selected.
131 * If a new item is selected the previously selected will be unselected.
132 * Previously selected item can be get with function
133 * elm_index_selected_item_get().
135 * Selected items will be highlighted.
137 * @see elm_index_selected_item_get()
141 EAPI void elm_index_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
144 * Returns the last selected item, for a given index widget.
146 * @param obj The index object.
147 * @param level @c 0 or @c 1, the currently implemented levels.
148 * @return The last item @b selected on @p obj (or @c NULL, on errors).
152 EAPI Elm_Object_Item *elm_index_selected_item_get(const Evas_Object *obj, int level);
155 * Append a new item on a given index widget.
157 * @param obj The index object.
158 * @param letter Letter under which the item should be indexed
159 * @param func The function to call when the item is selected.
160 * @param data The item data to set for the index's item
161 * @return A handle to the item added or @c NULL, on errors
163 * Despite the most common usage of the @p letter argument is for
164 * single char strings, one could use arbitrary strings as index
167 * @c item will be the pointer returned back on @c "changed", @c
168 * "delay,changed" and @c "selected" smart events.
172 EAPI Elm_Object_Item *elm_index_item_append(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data);
175 * Prepend a new item on a given index widget.
177 * @param obj The index object.
178 * @param letter Letter under which the item should be indexed
179 * @param func The function to call when the item is selected.
180 * @param data The item data to set for the index's item
181 * @return A handle to the item added or @c NULL, on errors
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.
192 EAPI Elm_Object_Item *elm_index_item_prepend(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data);
195 * Insert a new item into the index object after item @p after.
197 * @param obj The index object.
198 * @param after The index item to insert after.
199 * @param letter Letter under which the item should be indexed
200 * @param func The function to call when the item is clicked.
201 * @param data The item data to set for the index's item
202 * @return A handle to the item added or @c NULL, on errors
204 * Despite the most common usage of the @p letter argument is for
205 * single char strings, one could use arbitrary strings as index
208 * @c item will be the pointer returned back on @c "changed", @c
209 * "delay,changed" and @c "selected" smart events.
211 * @note If @p relative is @c NULL this function will behave as
212 * elm_index_item_append().
216 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);
219 * Insert a new item into the index object before item @p before.
221 * @param obj The index object.
222 * @param before The index item to insert after.
223 * @param letter Letter under which the item should be indexed
224 * @param func The function to call when the item is clicked.
225 * @param data The item data to set for the index's item
226 * @return A handle to the item added or @c NULL, on errors
228 * Despite the most common usage of the @p letter argument is for
229 * single char strings, one could use arbitrary strings as index
232 * @c item will be the pointer returned back on @c "changed", @c
233 * "delay,changed" and @c "selected" smart events.
235 * @note If @p relative is @c NULL this function will behave as
236 * elm_index_item_prepend().
240 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);
243 * Insert a new item into the given index widget, using @p cmp_func
244 * function to sort items (by item handles).
246 * @param obj The index object.
247 * @param letter Letter under which the item should be indexed
248 * @param func The function to call when the item is clicked.
249 * @param data The item data to set for the index's item
250 * @param cmp_func The comparing function to be used to sort index
251 * items <b>by index item handles</b>
252 * @param cmp_data_func A @b fallback function to be called for the
253 * sorting of index items <b>by item data</b>). It will be used
254 * when @p cmp_func returns @c 0 (equality), which means an index
255 * item with provided item data already exists. To decide which
256 * data item should be pointed to by the index item in question, @p
257 * cmp_data_func will be used. If @p cmp_data_func returns a
258 * non-negative value, the previous index item data will be
259 * replaced by the given @p item pointer. If the previous data need
260 * to be freed, it should be done by the @p cmp_data_func function,
261 * because all references to it will be lost. If this function is
262 * not provided (@c NULL is given), index items will be @b
263 * duplicated, if @p cmp_func returns @c 0.
264 * @return A handle to the item added or @c NULL, on errors
266 * Despite the most common usage of the @p letter argument is for
267 * single char strings, one could use arbitrary strings as index
270 * @c item will be the pointer returned back on @c "changed", @c
271 * "delay,changed" and @c "selected" smart events.
275 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);
278 * Find a given index widget's item, <b>using item data</b>.
280 * @param obj The index object
281 * @param data The item data pointed to by the desired index item
282 * @return The index item handle, if found, or @c NULL otherwise
286 EAPI Elm_Object_Item *elm_index_item_find(Evas_Object *obj, const void *data);
289 * Removes @b all items from a given index widget.
291 * @param obj The index object.
293 * If deletion callbacks are set, via elm_object_item_del_cb_set(),
294 * that callback function will be called for each item in @p obj.
298 EAPI void elm_index_item_clear(Evas_Object *obj);
301 * Flush the changes made to the index items so they work correctly
303 * This flushes any changes made to items indicating the object is ready to
304 * go. You should call this before any changes you expect to work. This
305 * is similar to elm_list_go().
307 * @param obj The index object
308 * @param level The index level (one of @c 0 or @c 1) where changes were made
310 * @warning If not called, it won't display the index properly.
314 EAPI void elm_index_level_go(Evas_Object *obj, int level);
317 * Get the letter (string) set on a given index widget item.
319 * @param item The index item handle
320 * @return The letter string set on @p it
324 EAPI const char *elm_index_item_letter_get(const Elm_Object_Item *item);
327 * Set the indicator as to be disabled.
329 * @param obj The index object
330 * @param disabled @c EINA_TRUE to disable it, @c EINA_FALSE to enable it
332 * In Index widget, Indicator notes popup text, which shows a letter has been selecting.
334 * @see elm_index_indicator_disabled_get()
338 EAPI void elm_index_indicator_disabled_set(Evas_Object *obj, Eina_Bool disabled);
341 * Get the value of indicator's disabled status.
343 * @param obj The index object
344 * @return EINA_TRUE if the indicator is disabled.
346 * @see elm_index_indicator_disabled_set()
350 EAPI Eina_Bool elm_index_indicator_disabled_get(const Evas_Object *obj);
353 * Enable or disable horizontal mode on the index object
355 * @param obj The index object.
356 * @param horizontal @c EINA_TRUE to enable horizontal or @c EINA_FALSE to
357 * disable it, i.e., to enable vertical mode. it's an area one @ref Fingers
358 * "finger" wide on the bottom side of the index widget's container.
360 * @note Vertical mode is set by default.
362 * On horizontal mode items are displayed on index from left to right,
363 * instead of from top to bottom. Also, the index will scroll horizontally.
365 * @see elm_index_horizontal_get()
369 EAPI void elm_index_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
372 * Get a value whether horizontal mode is enabled or not.
374 * @param obj The index object.
375 * @return @c EINA_TRUE means horizontal mode selection is enabled.
376 * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL,
377 * @c EINA_FALSE is returned.
379 * @see elm_index_horizontal_set() for details.
383 EAPI Eina_Bool elm_index_horizontal_get(const Evas_Object *obj);
386 * Set a delay change time for index object.
388 * @param obj The index object.
389 * @param delay_change_time The delay change time to set.
391 * @note delay time is 0.2 sec by default.
393 * @see elm_index_delay_change_time_get
397 EAPI void elm_index_delay_change_time_set(Evas_Object *obj, double delay_change_time);
400 * Get a delay change time for index object.
402 * @param obj The index object.
403 * @return delay change time in seconds
405 * @see elm_index_delay_change_time_set
409 EAPI double elm_index_delay_change_time_get(const Evas_Object *obj);
412 * Enable or disable omit feature for a given index widget.
414 * @param obj The index object
415 * @param enabled @c EINA_TRUE to enable omit feature, @c EINA_FALSE to disable
417 * @see elm_index_omit_enabled_get()
421 EAPI void elm_index_omit_enabled_set(Evas_Object *obj, Eina_Bool enabled);
424 * Get whether omit feature is enabled or not for a given index widget.
426 * @param obj The index object
427 * @return @c EINA_TRUE, if omit feature is enabled, @c EINA_FALSE otherwise
429 * @see elm_index_omit_enabled_set() for more details
433 EAPI Eina_Bool elm_index_omit_enabled_get(const Evas_Object *obj);