summaryrefslogtreecommitdiff
path: root/src/lib/elementary/elm_prefs_data.h
blob: 49a7740aadf1f1f403c5547d32a8bae58e837665 (plain)
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
/**
 * @defgroup Elm_Prefs Elementary Prefs
 * @ingroup Elementary
 *
 * Elementary provides a prefs (for "preferences") infrastructure, which
 * consists of two sets of APIs:
 * - prefs data and
 * - prefs view.
 *
 * @section elm-prefs-data Prefs Data
 *
 * Prefs data are simple key/value storage handles. One is able to
 * set/get their values, which are @c Eina_Value blobs
 * (i.e. dynamically typed). You may also control the version of this
 * data set, for updating purposes. Finally, you may register
 * callbacks on changes on these data.
 *
 * The main user of prefs data is the prefs @b widget. After its
 * creation, it's bound to a given prefs data handle (if not, if gets
 * its values from its definition file, which may have defaults). An
 * elm prefs widget has its visuals defined by an @c .epb file, which
 * is a compiled form of a @c .edc counterpart -- a textual definition
 * much like Edje @c .edc files. On these files, one defines the
 * values (items) a prefs widget hold, which translate to other
 * Elementary widgets. In other words, it does the mapping between UI
 * widgets into prefs data values, and it keeps the synchrony between
 * its child widgets' states and their corresponding prefs data
 * values.
 *
 * @{
 */

/** Modes of resetting a prefs widget. see elm_prefs_reset()
 *
 * @since 1.8
 */
typedef enum
{
  ELM_PREFS_RESET_DEFAULTS = 0, /**< reset to default values, declared in its
                                 * <b>.epb</b> file */
  ELM_PREFS_RESET_LAST /**< prefs will keep a small history of changes, so this
                        *  resets back to last batch of changes on the UI
                        * elements. it does <b>not</b> work on autosave mode */
} Elm_Prefs_Reset_Mode;

/** Elm Prefs item types.
 *
 * @since 1.8
 */
typedef enum
{
  ELM_PREFS_TYPE_UNKNOWN = 0, /**< Unknown type */
  ELM_PREFS_TYPE_ACTION, /**< action type, bound to button-like UI elements */
  ELM_PREFS_TYPE_BOOL, /**< boolean type, bound to checkbox-like UI elements */
  ELM_PREFS_TYPE_INT, /**< integer type, bound to spinner-like UI elements */
  ELM_PREFS_TYPE_FLOAT, /**< floating point type, bound to spinner-like UI elements */
  ELM_PREFS_TYPE_LABEL, /**< label type, bound to read-only, label UI elements */
  ELM_PREFS_TYPE_DATE, /**< date type, bound to date selection UI elements */
  ELM_PREFS_TYPE_TEXT, /**< text type, bound to single-line, text entry UI elements */
  ELM_PREFS_TYPE_TEXTAREA, /**< text area type, bound to multi-line, text entry UI elements */
  ELM_PREFS_TYPE_PAGE, /**< page type, used to nest pages */
  ELM_PREFS_TYPE_RESET, /**< values resetting trigger type, bound to button-like UI elements */
  ELM_PREFS_TYPE_SAVE, /**< saving trigger type, bound to button-like UI elements */
  ELM_PREFS_TYPE_SEPARATOR, /**< separator type, bound to separator-like UI elements */
  ELM_PREFS_TYPE_SWALLOW /**< swallow type, bound to an empty 'spot' on the UI
                          * meant to receive and display external content */
} Elm_Prefs_Item_Type;

/**
 * Types of events a given prefs data handle may issue.
 *
 * @see elm_prefs_data_event_callback_add()
 *
 * @since 1.8
 */
typedef enum {
   ELM_PREFS_DATA_EVENT_GROUP_AUTOSAVED, /** The group of values has been automatically saved (event info is the group's name (key)) */
   ELM_PREFS_DATA_EVENT_ITEM_CHANGED, /** A given item (prefs data value) has been changed (event info is an #Elm_Prefs_Data_Event_Changed pointer) */
   ELM_PREFS_DATA_EVENT_LAST /** sentinel value, don't use it */
} Elm_Prefs_Data_Event_Type;

/**
 * @typedef Elm_Prefs_Data
 *
 * An Elm Prefs Data handle.
 *
 * @since 1.8
 */
typedef struct _Elm_Prefs_Data Elm_Prefs_Data;

typedef void                 (*Elm_Prefs_Data_Event_Cb)(void *cb_data,
                                                        Elm_Prefs_Data_Event_Type type,
                                                        Elm_Prefs_Data *prefs_data,
                                                        void *event_info);

/**
 * @typedef Elm_Prefs_Data_Event_Changed
 *
 * An Elm Prefs #ELM_PREFS_DATA_EVENT_ITEM_CHANGED event info data
 * blob.
 *
 * @since 1.8
 */
typedef struct _Elm_Prefs_Data_Event_Changed
{
   const char       *key; /** key of the data value which changed */
   const Eina_Value *value; /** the value, itself, to be used as a @b read-only Eina_Value (it can be @c NULL, if the data was deleted) */
} Elm_Prefs_Data_Event_Changed;

/**
 * Create a new prefs data handle.
 *
 * @param data_file The (user) file where to read data from
 * @param key The key where the data is stored under
 * @param mode The mode of access to the given file
 * @return A new prefs data handle
 *
 * If @a data_file is @c NULL,
 * efreet_config_home_get()/<appname>/preferences.cfg will be used, by
 * default. If @a key is @c NULL, it is considered a default key --
 * "main".
 *
 * If @a mode is @c EET_FILE_MODE_READ, autosave will be always false
 * for this elm_prefs_data handle. If @a mode is
 * @c EET_FILE_MODE_WRITE, than @a data_file @b won't be read, but just
 * written to.
 *
 * @note An elm prefs data handle starts with a reference count of @b
 * 1 (see elm_prefs_data_ref()). Use elm_prefs_data_unref() to delete
 * it.
 *
 * @since 1.8
 */
EAPI Elm_Prefs_Data *elm_prefs_data_new(const char *data_file,
                                        const char *key,
                                        Eet_File_Mode mode);

/**
 * Set the version field of a given prefs data handle.
 *
 * @param prefs_data A valid prefs data handle
 * @param version The version number
 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 *
 * @see elm_prefs_data_version_get()
 *
 * @since 1.8
 */
EAPI Eina_Bool       elm_prefs_data_version_set(Elm_Prefs_Data *prefs_data,
                                                unsigned int version);

/**
 * Get the version field of a given prefs data handle.
 *
 * @param prefs_data A valid prefs data handle
 * @return The version of @a prefs_data or -1, on errors.
 *
 * @see elm_prefs_data_version_set()
 *
 * @since 1.8
 */
EAPI unsigned int    elm_prefs_data_version_get(const Elm_Prefs_Data *prefs_data);

/**
 * Increment reference count on a given prefs data handle.
 *
 * @param prefs_data A valid prefs data handle
 * @return The same prefs data handle, @a prefs_data
 *
 * This increments the reference count of @a by 1. Use this to pass
 * the handle safely to contexts other than the creation one, for
 * example. Only when the reference count on a prefs data handle
 * reaches @b 0 (see elm_prefs_data_unref()) will it be deleted.
 *
 * @since 1.8
 */
EAPI Elm_Prefs_Data *elm_prefs_data_ref(Elm_Prefs_Data *prefs_data);

/**
 * Decrement reference count on a given prefs data handle.
 *
 * @param prefs_data A valid prefs data handle
 *
 * This decrements the reference count of @a by 1. When the reference
 * count on @a reach @b 0, it will it be deleted.
 *
 * @see elm_prefs_data_ref() for more details.
 *
 * @since 1.8
 */
EAPI void            elm_prefs_data_unref(Elm_Prefs_Data *prefs_data);

/**
 * Set (or delete) one value of a given prefs data handle.
 *
 * @param prefs_data A valid prefs data handle
 * @param path The (unique) name (key) of the given value
 * @param type The item type to which the value is to be associated
 * @param value The value, itself. It must be a valid @c Eina_Value
 *              handle, bound to a given type and value or @c NULL. On
 *              the second case, the call will actually @b delete the
 *              given key from @a prefs_data.
 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 *
 * A prefs data handle holds a list of key/value entries. This will
 * set one of @a's values, by name. The value itself may be any valid
 * and filled up @c Eina_Value handle.
 *
 * @since 1.8
 */
EAPI Eina_Bool       elm_prefs_data_value_set(Elm_Prefs_Data *prefs_data,
                                              const char *path,
                                              const Elm_Prefs_Item_Type type,
                                              const Eina_Value *value);

/**
 * Get one value of a given prefs data handle (by key).
 *
 * @param prefs_data A valid prefs data handle
 * @param path The (unique) name (key) of the given value
 * @param type The item type associated with the value
 * @param value A valid @c Eina_Value handle, where to store the
 *              value, itself.
 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 *
 * This will retrieve one of @a's values, by name. The value itself
 * will be written to @a value, which will be overriden.
 *
 * @since 1.8
 */
EAPI Eina_Bool       elm_prefs_data_value_get(const Elm_Prefs_Data *prefs_data,
                                              const char *path,
                                              Elm_Prefs_Item_Type *type,
                                              Eina_Value *value);

/**
 * Register a callback for one of the prefs data events.
 *
 * @param prefs_data A valid prefs data handle
 * @param type The type of event to register to
 * @param cb The callback function to issue on this event
 * @param cb_data The data pointer to pass to @a cb on this event
 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 *
 * @see #Elm_Prefs_Data_Event_Type for more details on the events.
 * @see elm_prefs_data_event_callback_del()
 *
 * @since 1.8
 */
EAPI Eina_Bool       elm_prefs_data_event_callback_add(Elm_Prefs_Data *prefs_data,
                                                       Elm_Prefs_Data_Event_Type type,
                                                       Elm_Prefs_Data_Event_Cb cb,
                                                       const void *cb_data);
/**
 * Unregister a callback for one of the prefs data events.
 *
 * @param prefs_data A valid prefs data handle
 * @param type The type of event to unregister
 * @param cb The callback function being used to this event
 * @param cb_data The data pointer being passed to @a cb on this event
 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 *
 * @see #Elm_Prefs_Data_Event_Type for more details on the events.
 * @see elm_prefs_data_event_callback_add()
 *
 * @note If a same event callback (with matching type, callback
 * function and data pointers) was added more than once on
 * @a prefs_data, them same number of matching calls of this type have to
 * issued to delete all them.
 *
 * @since 1.8
 */
EAPI Eina_Bool       elm_prefs_data_event_callback_del(Elm_Prefs_Data *prefs_data,
                                                       Elm_Prefs_Data_Event_Type type,
                                                       Elm_Prefs_Data_Event_Cb cb,
                                                       const void *cb_data);

/**
 * Set whether a given elm prefs data handle should save its values
 * back automatically on changes.
 *
 * @param prefs_data A valid prefs data handle
 * @param autosave @c EINA_TRUE to save automatically, @c EINA_FALSE otherwise.
 *
 * If @a autosave is @c EINA_TRUE, every call to
 * elm_prefs_data_value_set() will implicitly issue elm_prefs_data_save() too.
 *
 * @warning This call will do nothing if @a prefs_data was created
 * with mode EET_FILE_MODE_READ -- auto saving will be always disabled
 * in this mode, as it can't write back.
 *
 * @see elm_prefs_data_autosave_get()
 *
 * @since 1.8
 */
EAPI void      elm_prefs_data_autosave_set(Elm_Prefs_Data *prefs_data,
                                           Eina_Bool autosave);

/**
 * Get whether a given elm prefs data handle is saving its values
 * back automatically on changes.
 *
 * @param prefs_data A valid prefs data handle
 * @return @c EINA_TRUE if @a prefs_data is saving automatically,
 *         @c EINA_FALSE otherwise.
 *
 * @see elm_prefs_data_autosave_set()
 *
 * @since 1.8
 */
EAPI Eina_Bool elm_prefs_data_autosave_get(const Elm_Prefs_Data *prefs_data);

/**
 * Save, manually, a given elm prefs data handle data back, on the given
 * file and key.
 *
 * @param prefs_data A valid prefs data handle
 * @param file The file (path) to save to (@c NULL means same file as
 *             it was opened with)
 * @param key The under which to save values (@c NULL means the same
 *            key as it was opened with)
 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 *
 * @see elm_prefs_data_autosave_set()
 *
 * @since 1.8
 */
EAPI Eina_Bool elm_prefs_data_save(const Elm_Prefs_Data *prefs_data,
                                   const char *file,
                                   const char *key);

/**
 * @}
 */