OGMRip Reference Manual: Settings

## Settings Settings — Common interface for settings managers |

## Functions

void | (*OGMRipSetFunc) ()
void | (*OGMRipGetFunc) ()
void | (*OGMRipNotifyFunc) ()
gulong | ogmrip_settings_add_notify ()
gulong | ogmrip_settings_add_notify_while_alive ()
void | ogmrip_settings_bind ()
void | ogmrip_settings_bind_custom ()
void | ogmrip_settings_block ()
gchar * | ogmrip_settings_build_section ()
gint | ogmrip_settings_compare_versions ()
gboolean | ogmrip_settings_export ()
GParamSpec * | ogmrip_settings_find_key ()
void | ogmrip_settings_get ()
OGMRipSettings * | ogmrip_settings_get_default ()
GSList * | ogmrip_settings_get_keys ()
GType | ogmrip_settings_get_key_type ()
const gchar * | ogmrip_settings_get_section_name ()
GSList * | ogmrip_settings_get_subsections ()
void | ogmrip_settings_get_value ()
gboolean | ogmrip_settings_has_key ()
gboolean | ogmrip_settings_has_section ()
gboolean | ogmrip_settings_import ()
void | ogmrip_settings_install_key ()
void | ogmrip_settings_install_key_from_property ()
gboolean | ogmrip_settings_parse ()
void | ogmrip_settings_remove_key ()
void | ogmrip_settings_remove_notify ()
void | ogmrip_settings_remove_section ()
void | ogmrip_settings_set ()
void | ogmrip_settings_set_default ()
void | ogmrip_settings_set_property_from_key ()
void | ogmrip_settings_set_value ()
void | ogmrip_settings_sync ()
void | ogmrip_settings_unbind ()
void | ogmrip_settings_unblock ()

## Types and Values

| OGMRipSettings

## Includes

    #include <ogmrip-settings.h>

## Description

## Functions

### 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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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

#### Parameters

settings | an OGMRipSettings |

### ogmrip_settings_unbind ()

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

Removes the bindings associated to `object` .

#### Parameters

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.

#### Parameters

settings | an OGMRipSettings |
section | the section |
key | the key |

## Types and Values

### OGMRipSettings

    typedef struct _OGMRipSettings OGMRipSettings;