1 files changed, 298 insertions, 0 deletions
diff --git a/legacy/elementary/src/lib/elm_prefs_data.h b/legacy/elementary/src/lib/elm_prefs_data.h
new file mode 100644
index 0000000000..bf3b8af2c8
--- /dev/null
+++ b/legacy/elementary/src/lib/elm_prefs_data.h
@@ -0,0 +1,298 @@
+/**
+ * @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.
+ *
+ * @{
+ */
+
+/**
+ * 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);
+
+/**
+ * @}
+ */