summaryrefslogtreecommitdiff
path: root/src/lib/elm_prefs.eo
blob: 96a94e7dc3f06d2ce878fc7ca7b2324df574eca6 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
class Elm_Prefs (Elm_Widget)
{
   eo_prefix: elm_obj_prefs;
   properties {
      data {
         set {
            /*@
            Set user data for a given prefs widget

            @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

            Once a prefs widget is created, after elm_prefs_file_set() is
            issued on it, all of its UI elements will get default values, when
            declared on that file. To fetch an user's own, personal set of
            those values, one gets to pair a <b>prefs data</b> handle to the
            prefs widget. This is what this call is intended for.

            Prefs data values from @a prefs_data with keys matching the ones
            present on the file passed on elm_prefs_file_set() to @a obj will
            have their values applied to the respective UI elements of the
            widget.

            When @a obj dies, the values of the elements declared on its @b
            .epb file (the one set on elm_prefs_file_set()) marked as permanent
            <b>will be written back</b> to @a prefs_data, if it is writable.
            One is also able to make this writing event to take place
            automatically after each UI element modification by using
            elm_prefs_autosave_set().

            @note @a obj will keep a reference of its own for @a prefs_data,
            but you should still unreference it by yourself, after the widget
            is gone.

            @see elm_prefs_data_get()

            @since 1.8 */
            return Eina_Bool;
         }
         get {
            /*@
            Retrieve user data for a given prefs widget

            @return A pointer to the user data of a given prefs widget on success.
            @c NULL otherwise.

            @see elm_prefs_data_set() for more details

            @since 1.8 */
         }
         values {
            Elm_Prefs_Data *data; /*@ A valid prefs_data handle */
         }
      }
      file {
         set {
            /*@
            Set file and page to populate a given prefs widget's interface.

            @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

            Elm prefs widgets start blank, with no child widgets. It's meant to
            have its viewport populated with child elements coming from a
            declaration file. That file (usually with @b .epb extension), is a
            binary format (Eet) one, coming from a human-readable textual
            declaration. This textual form (usually with @b .epc extension) is
            translated to the binary form by means of the @b prefs_cc compiler.

            With this function, one thus populates a prefs widget with UI
            elements.

            If @a file is @c NULL, "elm_app_data_dir_get()/preferences.epb"
            will be used, by default. If @a file is a @b relative path, the
            prefix "elm_app_data_dir_get()/" will be implicitly used with it.
            If @a page is @c NULL, it is considered "main", as default.

            @warning If your binary is not properly installed and
            elm_app_data_dir_get() can't be figured out, a fallback value of
            "." will be tryed, instead.

            @see elm_prefs_file_get()

            @since 1.8 */
            return Eina_Bool;
         }
         get {
            /*@
            Retrieve file and page bound to a given prefs widget.

            @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

            @note Use @c NULL pointers on the components you're not
            interested in: they'll be ignored by the function.

            @see elm_prefs_file_set() for more information

            @since 1.8 */
            return Eina_Bool;
         }
         values {
            const char *file; /*@ The @b .epb (binary) file to get contents from */
            const char *page; /*@ The page, inside @a file, where to get item contents from */
         }
      }
      autosave {
         set {
            /*@
            Set whether a given prefs widget should save its values back (on
            the user data file, if set) automatically on every UI element
            changes.

            If @a autosave is @c EINA_TRUE, every call to
            elm_prefs_item_value_set(), every
            Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event
            coming for its prefs data and every UI element direct value
            changing will implicitly make the prefs values to be flushed back
            to it prefs data. If a prefs data handle with no writing
            permissions or no prefs data is set on @a prefs, naturally nothing
            will happen.

            @see elm_prefs_autosave_get()

            @since 1.8 */
         }
         get {
            /*@
            Get whether a given prefs widget is saving its values back
            automatically on changes.

            @return @c EINA_TRUE if @a prefs is saving automatically,
            @c EINA_FALSE otherwise.

            @see elm_prefs_autosave_set(), for more details

            @since 1.8 */
         }
         values {
            Eina_Bool autosave; /*@ @c EINA_TRUE to save automatically, @c EINA_FALSE
            otherwise. */
         }
      }
   }
   methods {
      reset {
         /*@
         Reset the values of a given prefs widget to a previous state.

         As can be seen on #Elm_Prefs_Reset_Mode, there are two possible
         actions to be taken by this call -- either to reset @a prefs'
         values to the defaults (declared on the @c .epb file it is bound
         to) or to reset to the state they were before the last modification
         it got.

         @since 1.8 */

         params {
            @in Elm_Prefs_Reset_Mode mode; /*@ The reset mode to apply on @a prefs */
         }
      }
      item_value_set {
         /*@
         Set the value on a given prefs widget's item.

         @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

         This will change the value of item named @a name programatically.

         @see elm_prefs_item_value_get()

         @since 1.8 */

         return Eina_Bool;
         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) */
            @in const Eina_Value *value; /*@ The value to set on the item. It should be typed as
            the item expects, preferably, or a conversion will
            take place */
         }
      }
      item_value_get {
         /*@
         Retrieve the value of a given prefs widget's item.

         @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

         This will retrieve the value of item named @a name.

         @see elm_prefs_item_value_set()

         @since 1.8 */

         const;
         return Eina_Bool;
         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) to get value from */
            @out Eina_Value value; /*@ Where to store the value of the item. It will be
            overwritten and setup with the type the item
            is bound to */
         }
      }
      item_object_get {
         /*@
         Retrieve the Elementary widget bound to a given prefs widget's
         item.

         @return A valid widget handle, on success, or @c NULL, otherwise

         This will retrieve a handle to the real widget implementing a given
         item of @a prefs, <b>for read-only</b> actions.

         @warning You should @b never modify the state of the returned
         widget, because it's meant to be managed by @a prefs, solely.

         @see elm_prefs_item_value_set()

         @since 1.8 */

         return const Evas_Object *;
         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) to get object from */
         }
      }
      item_disabled_set {
         /*@
         Set whether the widget bound to a given prefs widget's item is
         disabled or not.

         @see elm_prefs_item_disabled_get()

         @since 1.8 */

         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) to act on */
            @in Eina_Bool disabled; /*@ @c EINA_TRUE, to make it disabled, @c EINA_FALSE
            otherwise */
         }
      }
      item_disabled_get {
         /*@
         Retrieve whether the widget bound to a given prefs widget's item is
         disabled or not.

         @return @c EINA_TRUE, if it is disabled, @c EINA_FALSE
         otherwise

         @see elm_prefs_item_disabled_set()

         @since 1.8 */

         const;
         return Eina_Bool;
         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) to get disabled state from */
         }
      }
      item_swallow {
         /*@
         "Swallows" an object into a SWALLOW item of a prefs widget.

         @return @c EINA_TRUE, on success, @c EINA_FALSE otherwise

         @see elm_prefs_item_swallow() for more details

         @since 1.8 */

         return Eina_Bool;
         params {
            @in const char *name; /*@ the name of the SWALLOW item (as declared in the prefs
            collection) */
            @in Evas_Object *child; /*@ The object to occupy the item */
         }
      }
      item_editable_set {
         /*@
         Set whether the widget bound to a given prefs widget's item is
         editable or not.

         @note Only @c TEXT or @c TEXTAREA items' default widgets implement
         the 'editable' property. Custom registered widgets may as well
         implement them.

         @see elm_prefs_item_editable_get()

         @since 1.8 */

         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) to act on */
            @in Eina_Bool editable; /*@ @c EINA_TRUE, to make it editable, @c EINA_FALSE
            otherwise */
         }
      }
      item_editable_get {
         /*@
         Retrieve whether the widget bound to a given prefs widget's item is
         editable or not.

         @return @c EINA_TRUE, if it is editable, @c EINA_FALSE
         otherwise

         @see elm_prefs_item_editable_set() for more details

         @since 1.8 */

         const;
         return Eina_Bool;
         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) to get editable state from */
         }
      }
      item_unswallow {
         /*@
         Unswallow an object from a SWALLOW item of a prefs widget.

         @return The unswallowed object, or NULL on errors

         @see elm_prefs_item_unswallow() for more details

         @since 1.8 */

         return Evas_Object *;
         params {
            @in const char *name; /*@ the name of the SWALLOW item (as declared in the prefs
            collection) */
         }
      }
      item_visible_set {
         /*@
         Set whether the widget bound to given prefs widget's item should be
         visible or not.

         Each prefs item may have a default visibility state, declared on
         the @c .epb @a prefs it was loaded with. By this call one may alter
         that state, programatically.

         @see elm_prefs_item_visible_get()

         @since 1.8 */

         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) to change visibility of */
            @in Eina_Bool visible; /*@ @c EINA_TRUE, to make it visible, @c EINA_FALSE
            otherwise */
         }
      }
      item_visible_get {
         /*@
         Retrieve whether the widget bound to a given prefs widget's item is
         visible or not.

         @return @c EINA_TRUE, if it is visible, @c EINA_FALSE
         otherwise

         @see elm_prefs_item_visible_set() for more details

         @since 1.8 */

         const;
         return Eina_Bool;
         params {
            @in const char *name; /*@ The name of the item (as declared in the prefs
            collection) to get visibility state from */
         }
      }
   }
   implements {
      class.constructor;
      Eo_Base.constructor;
      Evas_Object_Smart.del;
      Evas_Object_Smart.add;
      Elm_Widget.focus_next;
   }
   events {
      page,changed; /*@ s */
      page,saved; /*@ s */
      page,reset; /*@ s */
      page,loaded; /*@ s */
      item,changed; /*@ s */
      action; /*@ ss */
   }

}