diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/elementary/src/lib/elm_index.h | 373 |
1 files changed, 373 insertions, 0 deletions
diff --git a/libraries/elementary/src/lib/elm_index.h b/libraries/elementary/src/lib/elm_index.h new file mode 100644 index 0000000..33e41be --- /dev/null +++ b/libraries/elementary/src/lib/elm_index.h | |||
@@ -0,0 +1,373 @@ | |||
1 | /** | ||
2 | * @defgroup Index Index | ||
3 | * @ingroup Elementary | ||
4 | * | ||
5 | * @image html img/widget/index/preview-00.png | ||
6 | * @image latex img/widget/index/preview-00.eps | ||
7 | * | ||
8 | * An index widget gives you an index for fast access to whichever | ||
9 | * group of other UI items one might have. It's a list of text | ||
10 | * items (usually letters, for alphabetically ordered access). | ||
11 | * | ||
12 | * Index widgets are by default hidden and just appear when the | ||
13 | * user clicks over it's reserved area in the canvas. In its | ||
14 | * default theme, it's an area one @ref Fingers "finger" wide on | ||
15 | * the right side of the index widget's container. | ||
16 | * | ||
17 | * When items on the index are selected, smart callbacks get | ||
18 | * called, so that its user can make other container objects to | ||
19 | * show a given area or child object depending on the index item | ||
20 | * selected. You'd probably be using an index together with @ref | ||
21 | * List "lists", @ref Genlist "generic lists" or @ref Gengrid | ||
22 | * "general grids". | ||
23 | * | ||
24 | * Smart events one can add callbacks for are: | ||
25 | * - @c "changed" - When the selected index item changes. @c | ||
26 | * event_info is the selected item's data pointer. | ||
27 | * - @c "delay,changed" - When the selected index item changes, but | ||
28 | * after a small idling period. @c event_info is the selected | ||
29 | * item's data pointer. | ||
30 | * - @c "selected" - When the user releases a mouse button and | ||
31 | * selects an item. @c event_info is the selected item's data | ||
32 | * pointer. | ||
33 | * - @c "level,up" - when the user moves a finger from the first | ||
34 | * level to the second level | ||
35 | * - @c "level,down" - when the user moves a finger from the second | ||
36 | * level to the first level | ||
37 | * | ||
38 | * The @c "delay,changed" event is so that it'll wait a small time | ||
39 | * before actually reporting those events and, moreover, just the | ||
40 | * last event happening on those time frames will actually be | ||
41 | * reported. | ||
42 | * | ||
43 | * Here are some examples on its usage: | ||
44 | * @li @ref index_example_01 | ||
45 | * @li @ref index_example_02 | ||
46 | */ | ||
47 | |||
48 | /** | ||
49 | * @addtogroup Index | ||
50 | * @{ | ||
51 | */ | ||
52 | |||
53 | /** | ||
54 | * Add a new index widget to the given parent Elementary | ||
55 | * (container) object | ||
56 | * | ||
57 | * @param parent The parent object | ||
58 | * @return a new index widget handle or @c NULL, on errors | ||
59 | * | ||
60 | * This function inserts a new index widget on the canvas. | ||
61 | * | ||
62 | * @ingroup Index | ||
63 | */ | ||
64 | EAPI Evas_Object *elm_index_add(Evas_Object *parent); | ||
65 | |||
66 | /** | ||
67 | * Enable or disable auto hiding feature for a given index widget. | ||
68 | * | ||
69 | * @param obj The index object | ||
70 | * @param disabled @c EINA_TRUE to disable auto hiding, @c EINA_FALSE to enable | ||
71 | * | ||
72 | * @see elm_index_autohide_disabled_get() | ||
73 | * | ||
74 | * @ingroup Index | ||
75 | */ | ||
76 | EAPI void elm_index_autohide_disabled_set(Evas_Object *obj, Eina_Bool disabled); | ||
77 | |||
78 | /** | ||
79 | * Get whether auto hiding feature is enabled or not for a given index widget. | ||
80 | * | ||
81 | * @param obj The index object | ||
82 | * @return @c EINA_TRUE, if auto hiding is disabled, @c EINA_FALSE otherwise | ||
83 | * | ||
84 | * @see elm_index_autohide_disabled_set() for more details | ||
85 | * | ||
86 | * @ingroup Index | ||
87 | */ | ||
88 | EAPI Eina_Bool elm_index_autohide_disabled_get(const Evas_Object *obj); | ||
89 | |||
90 | /** | ||
91 | * Set the items level for a given index widget. | ||
92 | * | ||
93 | * @param obj The index object. | ||
94 | * @param level @c 0 or @c 1, the currently implemented levels. | ||
95 | * | ||
96 | * @see elm_index_item_level_get() | ||
97 | * | ||
98 | * @ingroup Index | ||
99 | */ | ||
100 | EAPI void elm_index_item_level_set(Evas_Object *obj, int level); | ||
101 | |||
102 | /** | ||
103 | * Get the items level set for a given index widget. | ||
104 | * | ||
105 | * @param obj The index object. | ||
106 | * @return @c 0 or @c 1, which are the levels @p obj might be at. | ||
107 | * | ||
108 | * @see elm_index_item_level_set() for more information | ||
109 | * | ||
110 | * @ingroup Index | ||
111 | */ | ||
112 | EAPI int elm_index_item_level_get(const Evas_Object *obj); | ||
113 | |||
114 | /** | ||
115 | * Set the selected state of an item. | ||
116 | * | ||
117 | * @param it The index item | ||
118 | * @param selected The selected state | ||
119 | * | ||
120 | * This sets the selected state of the given item @p it. | ||
121 | * @c EINA_TRUE for selected, @c EINA_FALSE for not selected. | ||
122 | * | ||
123 | * If a new item is selected the previously selected will be unselected. | ||
124 | * Previously selected item can be get with function | ||
125 | * elm_index_selected_item_get(). | ||
126 | * | ||
127 | * Selected items will be highlighted. | ||
128 | * | ||
129 | * @see elm_index_selected_item_get() | ||
130 | * | ||
131 | * @ingroup Index | ||
132 | */ | ||
133 | EAPI void elm_index_item_selected_set(Elm_Object_Item *it, Eina_Bool selected); | ||
134 | |||
135 | /** | ||
136 | * Returns the last selected item, for a given index widget. | ||
137 | * | ||
138 | * @param obj The index object. | ||
139 | * @param level @c 0 or @c 1, the currently implemented levels. | ||
140 | * @return The last item @b selected on @p obj (or @c NULL, on errors). | ||
141 | * | ||
142 | * @ingroup Index | ||
143 | */ | ||
144 | EAPI Elm_Object_Item *elm_index_selected_item_get(const Evas_Object *obj, int level); | ||
145 | |||
146 | /** | ||
147 | * Append a new item on a given index widget. | ||
148 | * | ||
149 | * @param obj The index object. | ||
150 | * @param letter Letter under which the item should be indexed | ||
151 | * @param func The function to call when the item is selected. | ||
152 | * @param data The item data to set for the index's item | ||
153 | * @return A handle to the item added or @c NULL, on errors | ||
154 | * | ||
155 | * Despite the most common usage of the @p letter argument is for | ||
156 | * single char strings, one could use arbitrary strings as index | ||
157 | * entries. | ||
158 | * | ||
159 | * @c item will be the pointer returned back on @c "changed", @c | ||
160 | * "delay,changed" and @c "selected" smart events. | ||
161 | * | ||
162 | * @ingroup Index | ||
163 | */ | ||
164 | EAPI Elm_Object_Item *elm_index_item_append(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data); | ||
165 | |||
166 | /** | ||
167 | * Prepend a new item on a given index widget. | ||
168 | * | ||
169 | * @param obj The index object. | ||
170 | * @param letter Letter under which the item should be indexed | ||
171 | * @param func The function to call when the item is selected. | ||
172 | * @param data The item data to set for the index's item | ||
173 | * @return A handle to the item added or @c NULL, on errors | ||
174 | * | ||
175 | * Despite the most common usage of the @p letter argument is for | ||
176 | * single char strings, one could use arbitrary strings as index | ||
177 | * entries. | ||
178 | * | ||
179 | * @c item will be the pointer returned back on @c "changed", @c | ||
180 | * "delay,changed" and @c "selected" smart events. | ||
181 | * | ||
182 | * @ingroup Index | ||
183 | */ | ||
184 | EAPI Elm_Object_Item *elm_index_item_prepend(Evas_Object *obj, const char *letter, Evas_Smart_Cb func, const void *data); | ||
185 | |||
186 | /** | ||
187 | * Insert a new item into the index object after item @p after. | ||
188 | * | ||
189 | * @param obj The index object. | ||
190 | * @param after The index item to insert after. | ||
191 | * @param letter Letter under which the item should be indexed | ||
192 | * @param func The function to call when the item is clicked. | ||
193 | * @param data The item data to set for the index's item | ||
194 | * @return A handle to the item added or @c NULL, on errors | ||
195 | * | ||
196 | * Despite the most common usage of the @p letter argument is for | ||
197 | * single char strings, one could use arbitrary strings as index | ||
198 | * entries. | ||
199 | * | ||
200 | * @c item will be the pointer returned back on @c "changed", @c | ||
201 | * "delay,changed" and @c "selected" smart events. | ||
202 | * | ||
203 | * @note If @p relative is @c NULL this function will behave as | ||
204 | * elm_index_item_append(). | ||
205 | * | ||
206 | * @ingroup Index | ||
207 | */ | ||
208 | 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); | ||
209 | |||
210 | /** | ||
211 | * Insert a new item into the index object before item @p before. | ||
212 | * | ||
213 | * @param obj The index object. | ||
214 | * @param before The index item to insert after. | ||
215 | * @param letter Letter under which the item should be indexed | ||
216 | * @param func The function to call when the item is clicked. | ||
217 | * @param data The item data to set for the index's item | ||
218 | * @return A handle to the item added or @c NULL, on errors | ||
219 | * | ||
220 | * Despite the most common usage of the @p letter argument is for | ||
221 | * single char strings, one could use arbitrary strings as index | ||
222 | * entries. | ||
223 | * | ||
224 | * @c item will be the pointer returned back on @c "changed", @c | ||
225 | * "delay,changed" and @c "selected" smart events. | ||
226 | * | ||
227 | * @note If @p relative is @c NULL this function will behave as | ||
228 | * elm_index_item_prepend(). | ||
229 | * | ||
230 | * @ingroup Index | ||
231 | */ | ||
232 | 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); | ||
233 | |||
234 | /** | ||
235 | * Insert a new item into the given index widget, using @p cmp_func | ||
236 | * function to sort items (by item handles). | ||
237 | * | ||
238 | * @param obj The index object. | ||
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 | * @param cmp_func The comparing function to be used to sort index | ||
243 | * items <b>by #index item handles</b> | ||
244 | * @param cmp_data_func A @b fallback function to be called for the | ||
245 | * sorting of index items <b>by item data</b>). It will be used | ||
246 | * when @p cmp_func returns @c 0 (equality), which means an index | ||
247 | * item with provided item data already exists. To decide which | ||
248 | * data item should be pointed to by the index item in question, @p | ||
249 | * cmp_data_func will be used. If @p cmp_data_func returns a | ||
250 | * non-negative value, the previous index item data will be | ||
251 | * replaced by the given @p item pointer. If the previous data need | ||
252 | * to be freed, it should be done by the @p cmp_data_func function, | ||
253 | * because all references to it will be lost. If this function is | ||
254 | * not provided (@c NULL is given), index items will be @b | ||
255 | * duplicated, if @p cmp_func returns @c 0. | ||
256 | * @return A handle to the item added or @c NULL, on errors | ||
257 | * | ||
258 | * Despite the most common usage of the @p letter argument is for | ||
259 | * single char strings, one could use arbitrary strings as index | ||
260 | * entries. | ||
261 | * | ||
262 | * @c item will be the pointer returned back on @c "changed", @c | ||
263 | * "delay,changed" and @c "selected" smart events. | ||
264 | * | ||
265 | * @ingroup Index | ||
266 | */ | ||
267 | 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); | ||
268 | |||
269 | /** | ||
270 | * Find a given index widget's item, <b>using item data</b>. | ||
271 | * | ||
272 | * @param obj The index object | ||
273 | * @param data The item data pointed to by the desired index item | ||
274 | * @return The index item handle, if found, or @c NULL otherwise | ||
275 | * | ||
276 | * @ingroup Index | ||
277 | */ | ||
278 | EAPI Elm_Object_Item *elm_index_item_find(Evas_Object *obj, const void *data); | ||
279 | |||
280 | /** | ||
281 | * Removes @b all items from a given index widget. | ||
282 | * | ||
283 | * @param obj The index object. | ||
284 | * | ||
285 | * If deletion callbacks are set, via elm_object_item_del_cb_set(), | ||
286 | * that callback function will be called for each item in @p obj. | ||
287 | * | ||
288 | * @ingroup Index | ||
289 | */ | ||
290 | EAPI void elm_index_item_clear(Evas_Object *obj); | ||
291 | |||
292 | /** | ||
293 | * Go to a given items level on a index widget | ||
294 | * | ||
295 | * @param obj The index object | ||
296 | * @param level The index level (one of @c 0 or @c 1) | ||
297 | * | ||
298 | * @ingroup Index | ||
299 | */ | ||
300 | EAPI void elm_index_level_go(Evas_Object *obj, int level); | ||
301 | |||
302 | /** | ||
303 | * Get the letter (string) set on a given index widget item. | ||
304 | * | ||
305 | * @param item The index item handle | ||
306 | * @return The letter string set on @p it | ||
307 | * | ||
308 | * @ingroup Index | ||
309 | */ | ||
310 | EAPI const char *elm_index_item_letter_get(const Elm_Object_Item *item); | ||
311 | |||
312 | /** | ||
313 | * Set the indicator as to be disabled. | ||
314 | * | ||
315 | * @param obj The index object | ||
316 | * @param disabled @c EINA_TRUE to disable it, @c EINA_FALSE to enable it | ||
317 | * | ||
318 | * In Index widget, Indicator notes popup text, which shows a letter has been selecting. | ||
319 | * | ||
320 | * @see elm_index_indicator_disabled_get() | ||
321 | * | ||
322 | * @ingroup Index | ||
323 | */ | ||
324 | EAPI void elm_index_indicator_disabled_set(Evas_Object *obj, Eina_Bool disabled); | ||
325 | |||
326 | /** | ||
327 | * Get the value of indicator's disabled status. | ||
328 | * | ||
329 | * @param obj The index object | ||
330 | * @return EINA_TRUE if the indicator is disabled. | ||
331 | * | ||
332 | * @see elm_index_indicator_disabled_set() | ||
333 | * | ||
334 | * @ingroup Index | ||
335 | */ | ||
336 | EAPI Eina_Bool elm_index_indicator_disabled_get(const Evas_Object *obj); | ||
337 | |||
338 | /** | ||
339 | * Enable or disable horizontal mode on the index object | ||
340 | * | ||
341 | * @param obj The index object. | ||
342 | * @param horizontal @c EINA_TRUE to enable horizontal or @c EINA_FALSE to | ||
343 | * disable it, i.e., to enable vertical mode. it's an area one @ref Fingers | ||
344 | * "finger" wide on the bottom side of the index widget's container. | ||
345 | * | ||
346 | * @note Vertical mode is set by default. | ||
347 | * | ||
348 | * On horizontal mode items are displayed on index from left to right, | ||
349 | * instead of from top to bottom. Also, the index will scroll horizontally. | ||
350 | * | ||
351 | * @see elm_index_horizontal_get() | ||
352 | * | ||
353 | * @ingroup Index | ||
354 | */ | ||
355 | EAPI void elm_index_horizontal_set(Evas_Object *obj, Eina_Bool horizontal); | ||
356 | |||
357 | /** | ||
358 | * Get a value whether horizontal mode is enabled or not. | ||
359 | * | ||
360 | * @param obj The index object. | ||
361 | * @return @c EINA_TRUE means horizontal mode selection is enabled. | ||
362 | * @c EINA_FALSE indicates it's disabled. If @p obj is @c NULL, | ||
363 | * @c EINA_FALSE is returned. | ||
364 | * | ||
365 | * @see elm_index_horizontal_set() for details. | ||
366 | * | ||
367 | * @ingroup Index | ||
368 | */ | ||
369 | EAPI Eina_Bool elm_index_horizontal_get(const Evas_Object *obj); | ||
370 | |||
371 | /** | ||
372 | * @} | ||
373 | */ | ||