Settings

## Settings Settings — Common interface for settings managers |

## Synopsis

    #include <ogmrip-settings.h>

                        OGMRipSettings;
    void                (*OGMRipSetFunc)                    (GObject *object,
                                                             const gchar *property,
                                                             const GValue *value,
                                                             gpointer data);
    void                (*OGMRipGetFunc)                    (GObject *object,
                                                             const gchar *property,
                                                             GValue *value,
                                                             gpointer data);
    void                (*OGMRipNotifyFunc)                 (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             const GValue *value,
                                                             gpointer data);
    gulong              ogmrip_settings_add_notify          (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             OGMRipNotifyFunc func,
                                                             gpointer data);
    gulong              ogmrip_settings_add_notify_while_alive
                                                            (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             OGMRipNotifyFunc func,
                                                             gpointer data,
                                                             GObject *object);
    void                ogmrip_settings_bind                (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             GObject *object,
                                                             const gchar *property);
    void                ogmrip_settings_bind_custom         (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             GObject *object,
                                                             const gchar *property,
                                                             OGMRipGetFunc get_func,
                                                             OGMRipSetFunc set_func,
                                                             gpointer data);
    void                ogmrip_settings_block               (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);
    gchar *             ogmrip_settings_build_section       (OGMRipSettings *settings,
                                                             const gchar *element,
                                                             ...);
    gint                ogmrip_settings_compare_versions    (const gchar *version1,
                                                             const gchar *version2);
    gboolean            ogmrip_settings_export              (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *filename,
                                                             GError **error);
    GParamSpec *        ogmrip_settings_find_key            (OGMRipSettings *settings,
                                                             const gchar *key);
    void                ogmrip_settings_get                 (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             ...);
    OGMRipSettings *    ogmrip_settings_get_default         (void);
    GSList *            ogmrip_settings_get_keys            (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             gboolean recursive);
    GType               ogmrip_settings_get_key_type        (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);
    const gchar *       ogmrip_settings_get_section_name    (OGMRipSettings *settings,
                                                             const gchar *section);
    GSList *            ogmrip_settings_get_subsections     (OGMRipSettings *settings,
                                                             const gchar *section);
    void                ogmrip_settings_get_value           (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             GValue *value);
    gboolean            ogmrip_settings_has_key             (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);
    gboolean            ogmrip_settings_has_section         (OGMRipSettings *settings,
                                                             const gchar *section);
    gboolean            ogmrip_settings_import              (OGMRipSettings *settings,
                                                             const gchar *filename,
                                                             gchar **section,
                                                             GError **error);
    void                ogmrip_settings_install_key         (OGMRipSettings *settings,
                                                             GParamSpec *pspec);
    void                ogmrip_settings_install_key_from_property
                                                            (OGMRipSettings *settings,
                                                             GObjectClass *klass,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             const gchar *property);
    gboolean            ogmrip_settings_parse               (OGMRipSettings *settings,
                                                             const gchar *filename,
                                                             OGMRipParseFunc func,
                                                             gpointer user_data,
                                                             GError **error);
    void                ogmrip_settings_remove_key          (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);
    void                ogmrip_settings_remove_notify       (OGMRipSettings *settings,
                                                             gulong handler_id);
    void                ogmrip_settings_remove_section      (OGMRipSettings *settings,
                                                             const gchar *section);
    void                ogmrip_settings_set                 (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             ...);
    void                ogmrip_settings_set_default         (OGMRipSettings *settings);
    void                ogmrip_settings_set_property_from_key
                                                            (OGMRipSettings *settings,
                                                             GObject *object,
                                                             const gchar *property,
                                                             const gchar *section,
                                                             const gchar *key);
    void                ogmrip_settings_set_value           (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             const GValue *value);
    void                ogmrip_settings_sync                (OGMRipSettings *settings);
    void                ogmrip_settings_unbind              (OGMRipSettings *settings,
                                                             GObject *object);
    void                ogmrip_settings_unblock             (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);

## Description

## Details

### OGMRipSettings

    typedef struct _OGMRipSettings OGMRipSettings;

### OGMRipSetFunc ()

    void                (*OGMRipSetFunc)                    (GObject *object,
                                                             const gchar *property,
                                                             const GValue *value,
                                                             gpointer data);

Specifies the type of functions passed to `ogmrip_settings_bind_custom()` to set the value of the property.

`object` : | A GObject
`property` : | A property
`value` : | A GValue
`data` : | The user data

### OGMRipGetFunc ()

    void                (*OGMRipGetFunc)                    (GObject *object,
                                                             const gchar *property,
                                                             GValue *value,
                                                             gpointer data);

Specifies the type of functions passed to `ogmrip_settings_bind_custom()` to get the value of the property.

`object` : | A GObject
`property` : | A property
`value` : | A GValue
`data` : | The user data

### OGMRipNotifyFunc ()

    void                (*OGMRipNotifyFunc)                 (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             const GValue *value,
                                                             gpointer data);

Specifies the type of functions passed to `ogmrip_settings_add_notify()`, and `ogmrip_settings_add_notify_while_alive()`.

`settings` : | An OGMRipSettings
`section` : | A section
`key` : | A key
`value` : | A GValue
`data` : | The user data

### ogmrip_settings_add_notify ()

    gulong              ogmrip_settings_add_notify          (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             OGMRipNotifyFunc func,
                                                             gpointer data);

Request notification of changes of `key` in `section`.

`settings` : | an OGMRipSettings
`section` : | the section
`key` : | the key
`func` : | function to call when changes occur
`data` : | user data to pass to `func`
Returns : | a connection ID for removing the notification

### ogmrip_settings_add_notify_while_alive ()

    gulong              ogmrip_settings_add_notify_while_alive
                                                            (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             OGMRipNotifyFunc func,
                                                             gpointer data,
                                                             GObject *object);

Request notification of changes of `key` in `section`. When `object` is destroyed, the notification is automatically removed.

`settings` : | an OGMRipSettings
`section` : | the section
`key` : | the key
`func` : | function to call when changes occur
`data` : | user data to pass to `func`
`object` : | a GObject
Returns : | a connection ID for removing the notification

### ogmrip_settings_bind ()

    void                ogmrip_settings_bind                (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             GObject *object,
                                                             const gchar *property);

Binds `key` in `section` with `property` of `object`. Whenever `property` changes, `key` is updated. Whenever `key` changeѕ, `property` is updated.

`settings` : | an OGMRipSettings
`section` : | the section
`key` : | the key
`object` : | a GObject
`property` : | a property of `object`

### ogmrip_settings_bind_custom ()

    void                ogmrip_settings_bind_custom         (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             GObject *object,
                                                             const gchar *property,
                                                             OGMRipGetFunc get_func,
                                                             OGMRipSetFunc set_func,
                                                             gpointer data);

Binds `key` in `section` with `property` of `object`. Whenever `property` changes, `key` is updated. Whenever `key` changeѕ, `property` is updated.

`settings` : | an OGMRipSettings
`section` : | the section
`key` : | the key
`object` : | a GObject
`property` : | a property of `object`
`get_func` : | function called whenever `property` changes setting a custom value to `key`
`set_func` : | function called whenever `key` changes settings a custom value to `object`
`data` : | user data to pass to `get_func` and `set_func`

### ogmrip_settings_block ()

    void                ogmrip_settings_block               (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);

Blocks all notifications related to `key` in `section`. If `section` is NULL, notifications related to `key` from all sections are blocked.

`settings` : | an OGMRipSettings
`section` : | the section
`key` : | the key

### ogmrip_settings_build_section ()

    gchar *             ogmrip_settings_build_section       (OGMRipSettings *settings,
                                                             const gchar *element,
                                                             ...);

Builds a section from many section elements.

`settings` : | an OGMRipSettings
`element` : | the first section element
`...` : | more section elements
Returns : | the new section

### ogmrip_settings_compare_versions ()

    gint                ogmrip_settings_compare_versions    (const gchar *version1,
                                                             const gchar *version2);

Compares the versions of two profiles.

`version1` : | A profile's version
`version2` : | Another profile's version
Returns : | Negative value if `version1` < `version2`; zero if `version1` = `version2`; positive value if `version1` > `version2`

### ogmrip_settings_export ()

    gboolean            ogmrip_settings_export              (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *filename,
                                                             GError **error);

Exports settings from `section` in `filename`.

`settings` : | An OGMRipSettings
`section` : | The section to export
`filename` : | A filename to export into
`error` : | Return location for error
Returns : | `TRUE` if `section` has been exported, `FALSE` otherwise

### ogmrip_settings_find_key ()

    GParamSpec *        ogmrip_settings_find_key            (OGMRipSettings *settings,
                                                             const gchar *key);

Looks up the GParamSpec for a key.

`settings` : | an OGMRipSettings
`key` : | the name of the key to look up
Returns : | the GParamSpec for the key, or NULL

### ogmrip_settings_get ()

    void                ogmrip_settings_get                 (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             ...);

Gets the values associated with any number of settings in the same section.

`settings` : | an OGMRipSettings
`section` : | the section of the keys
`key` : | the name of the first key to fetch
`...` : | pointers to the locations to store the value of the first key, followed by more name/pointer groupings, followed by `NULL`.

### ogmrip_settings_get_default ()

    OGMRipSettings *    ogmrip_settings_get_default         (void);

Gets the default setting manager if it exists.

Returns : | the default OGMRipSettings, or NULL

### ogmrip_settings_get_keys ()

    GSList *            ogmrip_settings_get_keys            (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             gboolean recursive);

Lists the keys in `section`. The returned list contains allocated strings. You should `g_free()` each string in the list, then `g_slist_free()` the list itself.

`settings` : | an OGMRipSettings
`section` : | the section from which to get the keys
`recursive` : | perform a recursive search
Returns : | List of allocated key names

### ogmrip_settings_get_key_type ()

    GType               ogmrip_settings_get_key_type        (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);

Gets the type of the setting named by `key` in `section`.

`settings` : | an OGMRipSettings
`section` : | the section of the key
`key` : | the name of the key to fetch
Returns : | the type of `key`, or `G_TYPE_NONE`

### ogmrip_settings_get_section_name ()

    const gchar *       ogmrip_settings_get_section_name    (OGMRipSettings *settings,
                                                             const gchar *section);

Gets the name of the section.

`settings` : | an OGMRipSettings
`section` : | a section
Returns : | the name of the section

### ogmrip_settings_get_subsections ()

    GSList *            ogmrip_settings_get_subsections     (OGMRipSettings *settings,
                                                             const gchar *section);

Lists the subsections in `section`. The returned list contains allocated strings. You should `g_free()` each string in the list, then `g_slist_free()` the list itself.

`settings` : | an OGMRipSettings
`section` : | the section from which to get the subsections
Returns : | List of allocated subsection names

### ogmrip_settings_get_value ()

    void                ogmrip_settings_get_value           (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             GValue *value);

Gets the value associated with the setting named by `key` in `section`.

`settings` : | an OGMRipSettings
`section` : | the section of the key
`key` : | the name of the key to fetch
`value` : | a GValue of the correct type

### ogmrip_settings_has_key ()

    gboolean            ogmrip_settings_has_key             (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);

Returns whether a key exists or not.

`settings` : | an OGMRipSettings
`section` : | the section
`key` : | the key
Returns : | `TRUE` if `key` exists, `FALSE` otherwise

### ogmrip_settings_has_section ()

    gboolean            ogmrip_settings_has_section         (OGMRipSettings *settings,
                                                             const gchar *section);

Returns whether a section exists or not.

`settings` : | an OGMRipSettings
`section` : | the section
Returns : | `TRUE` if `section` exists, `FALSE` otherwise

### ogmrip_settings_import ()

    gboolean            ogmrip_settings_import              (OGMRipSettings *settings,
                                                             const gchar *filename,
                                                             gchar **section,
                                                             GError **error);

Imports settings from `filename` in `section`.

`settings` : | An OGMRipSettings
`filename` : | A filename to import from
`section` : | The section in which to import
`error` : | Return location for error
Returns : | `TRUE` if `filename` has been imported, `FALSE` otherwise

### ogmrip_settings_install_key ()

    void                ogmrip_settings_install_key         (OGMRipSettings *settings,
                                                             GParamSpec *pspec);

Installs a new key.

`settings` : | an OGMRipSettings
`pspec` : | a GParamSpec

### ogmrip_settings_install_key_from_property ()

    void                ogmrip_settings_install_key_from_property
                                                            (OGMRipSettings *settings,
                                                             GObjectClass *klass,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             const gchar *property);

Installs a new key using the GParamSpec of `property`.

`settings` : | An OGMRipSettings
`klass` : | A GObjectClass
`section` : | A section
`key` : | A key
`property` : | A property

### ogmrip_settings_parse ()

    gboolean            ogmrip_settings_parse               (OGMRipSettings *settings,
                                                             const gchar *filename,
                                                             OGMRipParseFunc func,
                                                             gpointer user_data,
                                                             GError **error);

Parses the settings in `filename`, calling `func` for each entries.

`settings` : | An OGMRipSettings
`filename` : | A filename to parse
`func` : | The function to call for each entries
`user_data` : | User data passed to the function
`error` : | Return location for error
Returns : | `TRUE` on success, `FALSE` if an error was set

### ogmrip_settings_remove_key ()

    void                ogmrip_settings_remove_key          (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);

Removeѕ `key` from `section`.

`settings` : | an OGMRipSettings
`section` : | a section
`key` : | the key to remove

### ogmrip_settings_remove_notify ()

    void                ogmrip_settings_remove_notify       (OGMRipSettings *settings,
                                                             gulong handler_id);

Remove a notification using the ID returned from `ogmrip_settings_add_notify()` or `ogmrip_settings_add_notify_while_alive()`.

`settings` : | an OGMRipSettings
`handler_id` : | a connection ID

### ogmrip_settings_remove_section ()

    void                ogmrip_settings_remove_section      (OGMRipSettings *settings,
                                                             const gchar *section);

Removeѕ `section` and all its keys and subsections.

`settings` : | an OGMRipSettings
`section` : | the section to remove

### ogmrip_settings_set ()

    void                ogmrip_settings_set                 (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             ...);

Sets the values associated with any number of settings in the same section.

`settings` : | an OGMRipSettings
`section` : | the section of the keys
`key` : | the name of the first key to set
`...` : | pointers to the value of the first key, followed by more name/pointer groupings, followed by `NULL`.

### ogmrip_settings_set_default ()

    void                ogmrip_settings_set_default         (OGMRipSettings *settings);

Sets the default setting manager. If `settings` is NULL, the current default setting manager is removed.

`settings` : | an OGMRipSettings, or NULL

### ogmrip_settings_set_property_from_key ()

    void                ogmrip_settings_set_property_from_key
                                                            (OGMRipSettings *settings,
                                                             GObject *object,
                                                             const gchar *property,
                                                             const gchar *section,
                                                             const gchar *key);

Sets a property of an object using the value of a settings key.

`settings` : | An OGMRipSettings
`object` : | A GObject
`property` : | Name of the property to set
`section` : | Section of a key
`key` : | Name of a key

### ogmrip_settings_set_value ()

    void                ogmrip_settings_set_value           (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key,
                                                             const GValue *value);

Sets the setting named by `key` in `section` to `value`.

`settings` : | an OGMRipSettings
`section` : | the section of the key
`key` : | the name of the key to fetch
`value` : | a GValue of the correct type

### ogmrip_settings_sync ()

    void                ogmrip_settings_sync                (OGMRipSettings *settings);

Blah

`settings` : | an OGMRipSettings

### ogmrip_settings_unbind ()

    void                ogmrip_settings_unbind              (OGMRipSettings *settings,
                                                             GObject *object);

Removes the bindings associated to `object`.

`settings` : | an OGMRipSettings
`object` : | a GObject

### ogmrip_settings_unblock ()

    void                ogmrip_settings_unblock             (OGMRipSettings *settings,
                                                             const gchar *section,
                                                             const gchar *key);

Unblocks all notifications related to `key` in `section`. If `section` is NULL, notifications related to `key` from all sections are unblocked.

`settings` : | an OGMRipSettings
`section` : | the section
`key` : | the key