summaryrefslogtreecommitdiff
path: root/src/lib/elementary/elm_prefs_eo.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/elementary/elm_prefs_eo.h')
-rw-r--r--src/lib/elementary/elm_prefs_eo.h381
1 files changed, 381 insertions, 0 deletions
diff --git a/src/lib/elementary/elm_prefs_eo.h b/src/lib/elementary/elm_prefs_eo.h
new file mode 100644
index 0000000..5f6fad3
--- /dev/null
+++ b/src/lib/elementary/elm_prefs_eo.h
@@ -0,0 +1,381 @@
1#ifndef _ELM_PREFS_EO_H_
2#define _ELM_PREFS_EO_H_
3
4#ifndef _ELM_PREFS_EO_CLASS_TYPE
5#define _ELM_PREFS_EO_CLASS_TYPE
6
7typedef Eo Elm_Prefs;
8
9#endif
10
11#ifndef _ELM_PREFS_EO_TYPES
12#define _ELM_PREFS_EO_TYPES
13
14
15#endif
16/** Elementary preferences class
17 *
18 * @ingroup Elm_Prefs
19 */
20#define ELM_PREFS_CLASS elm_prefs_class_get()
21
22EWAPI const Efl_Class *elm_prefs_class_get(void);
23
24/**
25 * @brief Set user data for a given prefs widget
26 *
27 * Once a prefs widget is created, after elm_prefs_file_set() is issued on it,
28 * all of its UI elements will get default values, when declared on that file.
29 * To fetch an user's own, personal set of those values, one gets to pair a
30 * prefs data handle to the prefs widget. This is what this call is intended
31 * for.
32 *
33 * Prefs data values from @c prefs_data with keys matching the ones present on
34 * the file passed on elm_prefs_file_set() to @c obj will have their values
35 * applied to the respective UI elements of the widget.
36 *
37 * When @c obj dies, the values of the elements declared on its $.epb file (the
38 * one set on elm_prefs_file_set()) marked as permanent will be written back to
39 * prefs_data, if it is writable. One is also able to make this writing event
40 * to take place automatically after each UI element modification by using
41 * elm_prefs_autosave_set().
42 *
43 * @note @c obj will keep a reference of its own for @c prefs_data, but you
44 * should still unreference it by yourself, after the widget is gone.
45 *
46 * @param[in] obj The object.
47 * @param[in] data A valid prefs_data handle
48 *
49 * @return @c true, on success, @c false otherwise
50 *
51 * @since 1.8
52 *
53 * @ingroup Elm_Prefs
54 */
55EOAPI Eina_Bool elm_obj_prefs_data_set(Eo *obj, Elm_Prefs_Data *data);
56
57/**
58 * @brief Set user data for a given prefs widget
59 *
60 * Once a prefs widget is created, after elm_prefs_file_set() is issued on it,
61 * all of its UI elements will get default values, when declared on that file.
62 * To fetch an user's own, personal set of those values, one gets to pair a
63 * prefs data handle to the prefs widget. This is what this call is intended
64 * for.
65 *
66 * Prefs data values from @c prefs_data with keys matching the ones present on
67 * the file passed on elm_prefs_file_set() to @c obj will have their values
68 * applied to the respective UI elements of the widget.
69 *
70 * When @c obj dies, the values of the elements declared on its $.epb file (the
71 * one set on elm_prefs_file_set()) marked as permanent will be written back to
72 * prefs_data, if it is writable. One is also able to make this writing event
73 * to take place automatically after each UI element modification by using
74 * elm_prefs_autosave_set().
75 *
76 * @note @c obj will keep a reference of its own for @c prefs_data, but you
77 * should still unreference it by yourself, after the widget is gone.
78 *
79 * @param[in] obj The object.
80 *
81 * @return A valid prefs_data handle
82 *
83 * @since 1.8
84 *
85 * @ingroup Elm_Prefs
86 */
87EOAPI Elm_Prefs_Data *elm_obj_prefs_data_get(const Eo *obj);
88
89/**
90 * @brief Control whether a given prefs widget should save its values back (on
91 * the user data file, if set) automatically on every UI element changes.
92 *
93 * If @c autosave is @c true, every call to elm_prefs_item_value_set(), every
94 * Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event coming for
95 * its prefs data and every UI element direct value changing will implicitly
96 * make the prefs values to be flushed back to it prefs data. If a prefs data
97 * handle with no writing permissions or no prefs data is set on @c prefs,
98 * naturally nothing will happen.
99 *
100 * @param[in] obj The object.
101 * @param[in] autosave @c true to save automatically, @c false otherwise.
102 *
103 * @since 1.8
104 *
105 * @ingroup Elm_Prefs
106 */
107EOAPI void elm_obj_prefs_autosave_set(Eo *obj, Eina_Bool autosave);
108
109/**
110 * @brief Control whether a given prefs widget should save its values back (on
111 * the user data file, if set) automatically on every UI element changes.
112 *
113 * If @c autosave is @c true, every call to elm_prefs_item_value_set(), every
114 * Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event coming for
115 * its prefs data and every UI element direct value changing will implicitly
116 * make the prefs values to be flushed back to it prefs data. If a prefs data
117 * handle with no writing permissions or no prefs data is set on @c prefs,
118 * naturally nothing will happen.
119 *
120 * @param[in] obj The object.
121 *
122 * @return @c true to save automatically, @c false otherwise.
123 *
124 * @since 1.8
125 *
126 * @ingroup Elm_Prefs
127 */
128EOAPI Eina_Bool elm_obj_prefs_autosave_get(const Eo *obj);
129
130/**
131 * @brief Reset the values of a given prefs widget to a previous state.
132 *
133 * As can be seen on #Elm_Prefs_Reset_Mode, there are two possible actions to
134 * be taken by this call -- either to reset @c prefs' values to the defaults
135 * (declared on the $.epb file it is bound to) or to reset to the state they
136 * were before the last modification it got.
137 *
138 * @param[in] obj The object.
139 * @param[in] mode The reset mode to apply on @c prefs
140 *
141 * @since 1.8
142 *
143 * @ingroup Elm_Prefs
144 */
145EOAPI void elm_obj_prefs_reset(Eo *obj, Elm_Prefs_Reset_Mode mode);
146
147/**
148 * @brief Set the value on a given prefs widget's item.
149 *
150 * This will change the value of item named @c name programatically.
151 *
152 * @param[in] obj The object.
153 * @param[in] name The name of the item (as declared in the prefs collection)
154 * @param[in] value The value to set on the item. It should be typed as the
155 * item expects, preferably, or a conversion will take place
156 *
157 * @return @c true, on success, @c false otherwise
158 *
159 * @since 1.8
160 *
161 * @ingroup Elm_Prefs
162 */
163EOAPI Eina_Bool elm_obj_prefs_item_value_set(Eo *obj, const char *name, const Eina_Value *value);
164
165/**
166 * @brief Get the value of a given prefs widget's item.
167 *
168 * This will retrieve the value of item named @c name.
169 *
170 * @param[in] obj The object.
171 * @param[in] name The name of the item (as declared in the prefs collection)
172 * to get value from
173 * @param[out] value Where to store the value of the item. It will be
174 * overwritten and setup with the type the item is bound to
175 *
176 * @return @c true, on success, @c false otherwise
177 *
178 * @since 1.8
179 *
180 * @ingroup Elm_Prefs
181 */
182EOAPI Eina_Bool elm_obj_prefs_item_value_get(const Eo *obj, const char *name, Eina_Value *value);
183
184/**
185 * @brief Get the Elementary widget bound to a given prefs widget's item.
186 *
187 * This will retrieve a handle to the real widget implementing a given item of
188 * @c prefs, <b>for read-only</b> actions.
189 *
190 * @warning You should never modify the state of the returned widget, because
191 * it's meant to be managed by @c prefs, solely.
192 *
193 * @param[in] obj The object.
194 * @param[in] name The name of the item (as declared in the prefs collection)
195 * to get object from
196 *
197 * @return A valid widget handle, on success, or @c NULL, otherwise
198 *
199 * @since 1.8
200 *
201 * @ingroup Elm_Prefs
202 */
203EOAPI const Efl_Canvas_Object *elm_obj_prefs_item_object_get(Eo *obj, const char *name);
204
205/**
206 * @brief Set whether the widget bound to a given prefs widget's item is
207 * disabled or not.
208 *
209 * @param[in] obj The object.
210 * @param[in] name The name of the item (as declared in the prefs collection)
211 * to act on
212 * @param[in] disabled @c true, to make it disabled, @c false otherwise
213 *
214 * @since 1.8
215 *
216 * @ingroup Elm_Prefs
217 */
218EOAPI void elm_obj_prefs_item_disabled_set(Eo *obj, const char *name, Eina_Bool disabled);
219
220/**
221 * @brief Get whether the widget bound to a given prefs widget's item is
222 * disabled or not.
223 *
224 * @param[in] obj The object.
225 * @param[in] name The name of the item (as declared in the prefs collection)
226 * to get disabled state from
227 *
228 * @return @c true, if it is disabled, @c false otherwise
229 *
230 * @since 1.8
231 *
232 * @ingroup Elm_Prefs
233 */
234EOAPI Eina_Bool elm_obj_prefs_item_disabled_get(const Eo *obj, const char *name);
235
236/**
237 * @brief "Swallows" an object into a SWALLOW item of a prefs widget.
238 *
239 * @param[in] obj The object.
240 * @param[in] name The name of the SWALLOW item (as declared in the prefs
241 * collection)
242 * @param[in] child The object to occupy the item
243 *
244 * @return @c true, on success, @c false otherwise
245 *
246 * @since 1.8
247 *
248 * @ingroup Elm_Prefs
249 */
250EOAPI Eina_Bool elm_obj_prefs_item_swallow(Eo *obj, const char *name, Efl_Canvas_Object *child);
251
252/**
253 * @brief Set whether the widget bound to a given prefs widget's item is
254 * editable or not.
255 *
256 * @note Only @c TEXT or @c TEXTAREA items' default widgets implement the
257 * 'editable' property. Custom registered widgets may as well implement them.
258 *
259 * @param[in] obj The object.
260 * @param[in] name The name of the item (as declared in the prefs collection)
261 * to act on
262 * @param[in] editable @c true, to make it editable, @c false otherwise
263 *
264 * @since 1.8
265 *
266 * @ingroup Elm_Prefs
267 */
268EOAPI void elm_obj_prefs_item_editable_set(Eo *obj, const char *name, Eina_Bool editable);
269
270/**
271 * @brief Get whether the widget bound to a given prefs widget's item is
272 * editable or not.
273 *
274 * @param[in] obj The object.
275 * @param[in] name The name of the item (as declared in the prefs collection)
276 * to get editable state from
277 *
278 * @return @c true, if it is editable, @c false otherwise
279 *
280 * @since 1.8
281 *
282 * @ingroup Elm_Prefs
283 */
284EOAPI Eina_Bool elm_obj_prefs_item_editable_get(const Eo *obj, const char *name);
285
286/**
287 * @brief Unswallow an object from a SWALLOW item of a prefs widget.
288 *
289 * @param[in] obj The object.
290 * @param[in] name The name of the SWALLOW item (as declared in the prefs
291 * collection)
292 *
293 * @return The unswallowed object, or NULL on errors
294 *
295 * @since 1.8
296 *
297 * @ingroup Elm_Prefs
298 */
299EOAPI Efl_Canvas_Object *elm_obj_prefs_item_unswallow(Eo *obj, const char *name);
300
301/**
302 * @brief Set whether the widget bound to given prefs widget's item should be
303 * visible or not.
304 *
305 * Each prefs item may have a default visibility state, declared on the $.epb
306 * @c prefs it was loaded with. By this call one may alter that state,
307 * programatically.
308 *
309 * @param[in] obj The object.
310 * @param[in] name The name of the item (as declared in the prefs collection)
311 * to change visibility of
312 * @param[in] visible @c true, to make it visible, @c false otherwise
313 *
314 * @since 1.8
315 *
316 * @ingroup Elm_Prefs
317 */
318EOAPI void elm_obj_prefs_item_visible_set(Eo *obj, const char *name, Eina_Bool visible);
319
320/**
321 * @brief Get whether the widget bound to a given prefs widget's item is
322 * visible or not.
323 *
324 * @param[in] obj The object.
325 * @param[in] name The name of the item (as declared in the prefs collection)
326 * to get visibility state from
327 *
328 * @return @c true, if it is visible, @c false otherwise
329 *
330 * @since 1.8
331 *
332 * @ingroup Elm_Prefs
333 */
334EOAPI Eina_Bool elm_obj_prefs_item_visible_get(const Eo *obj, const char *name);
335
336EWAPI extern const Efl_Event_Description _ELM_PREFS_EVENT_PAGE_CHANGED;
337
338/** Called when page changed
339 * @return const char *
340 *
341 * @ingroup Elm_Prefs
342 */
343#define ELM_PREFS_EVENT_PAGE_CHANGED (&(_ELM_PREFS_EVENT_PAGE_CHANGED))
344
345EWAPI extern const Efl_Event_Description _ELM_PREFS_EVENT_PAGE_SAVED;
346
347/** Called when page was saved
348 * @return const char *
349 *
350 * @ingroup Elm_Prefs
351 */
352#define ELM_PREFS_EVENT_PAGE_SAVED (&(_ELM_PREFS_EVENT_PAGE_SAVED))
353
354EWAPI extern const Efl_Event_Description _ELM_PREFS_EVENT_PAGE_LOADED;
355
356/** Called when page got loaded
357 * @return const char *
358 *
359 * @ingroup Elm_Prefs
360 */
361#define ELM_PREFS_EVENT_PAGE_LOADED (&(_ELM_PREFS_EVENT_PAGE_LOADED))
362
363EWAPI extern const Efl_Event_Description _ELM_PREFS_EVENT_ITEM_CHANGED;
364
365/** Called when item changed
366 * @return const char *
367 *
368 * @ingroup Elm_Prefs
369 */
370#define ELM_PREFS_EVENT_ITEM_CHANGED (&(_ELM_PREFS_EVENT_ITEM_CHANGED))
371
372EWAPI extern const Efl_Event_Description _ELM_PREFS_EVENT_ACTION;
373
374/** Called when action was done
375 * @return const char *
376 *
377 * @ingroup Elm_Prefs
378 */
379#define ELM_PREFS_EVENT_ACTION (&(_ELM_PREFS_EVENT_ACTION))
380
381#endif