settings: Gwyddion Application Library Reference Manual

## settings settings — Application and module settings |

## Functions

GQuark | gwy_app_settings_error_quark ()
GwyDict * | gwy_app_settings_get ()
void | gwy_app_settings_free ()
gboolean | gwy_app_settings_save ()
gboolean | gwy_app_settings_load ()
gboolean | gwy_app_settings_merge_string ()
gboolean | gwy_app_settings_create_config_dir ()
gchar ** | gwy_app_settings_get_module_dirs ()
gchar * | gwy_app_settings_get_settings_filename ()
gchar * | gwy_app_settings_get_log_filename ()
gchar * | gwy_app_settings_get_recent_file_list_filename ()
void | gwy_app_settings_get_default_mask_color ()

## Types and Values

#define | GWY_APP_SETTINGS_ERROR
enum | GwyAppSettingsError

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

All application and module settings are stored in a one big GwyDict which can be obtained by `gwy_app_settings_get()`. Then you can use GwyDict functions to get and save settings.

The rest of the setting manipulating functions is normally useful only in the main application.

## Functions

### gwy_app_settings_error_quark()

    GQuark
    gwy_app_settings_error_quark (void);

Returns error domain for application settings operations.

See and use `GWY_APP_SETTINGS_ERROR`.

#### Returns

The error domain.

### gwy_app_settings_get()

    GwyDict *
    gwy_app_settings_get (void);

Gets the Gwyddion settings.

The program settings are in a GwyDict, which is normally loaded at program startup using a function like `gwy_app_init()` and saved at exit using a function like `gwy_app_settings_save()`. If you use settings, you should load resources beforehand. Or, better, use `gwy_app_init()`.

For storing persistent module data manually you should use `"/module/YOUR_MODULE_NAME/"` prefix. However, in common cases you should use GwyParamDef and GwyParams which can handle the dirty work themselves.

#### Returns

The settings as a GwyDict.

### gwy_app_settings_free()

    void
    gwy_app_settings_free (void);

Frees Gwyddion settings.

Should not be called only by main application.

### gwy_app_settings_save()

    gboolean
    gwy_app_settings_save (const gchar *filename,
                           GError **error);

Saves the settings.

Use `gwy_app_settings_get_settings_filename()` to obtain a suitable default filename.

#### Parameters

filename | A filename to save the settings to. |
error | Location to store loading error to, or `NULL`. |

#### Returns

Whether it succeeded.

### gwy_app_settings_load()

    gboolean
    gwy_app_settings_load (const gchar *filename,
                           GError **error);

Initialises settings by loading a settings file.

Any existing settings are discarded. Consider `gwy_app_settings_merge_string()` for piecewise settings creation.

#### Parameters

filename | A filename to read settings from. |
error | Location to store loading error to, or `NULL`. |

#### Returns

Whether it succeeded. In either case you can call `gwy_app_settings_get()` then to obtain either the loaded settings or the old ones (if failed), or an empty GwyDict.

### gwy_app_settings_merge_string()

    gboolean
    gwy_app_settings_merge_string (const gchar *s,
                                   gboolean overwrite,
                                   GError **error);

Loads settings from a string and adds them to the global settings.

The contents of string `s` should look like a Gwyddion settings file, including the header line "Gwyddion Settings 1.0", even though it is optional.

If no settings exist when this function is called, they are initialised like calling `gwy_app_settings_get()`.

#### Parameters

s | String contaning a part of Gwyddion settings file. |
overwrite | `TRUE` to replace existing settings; `FALSE` to only set values which do not exist. |
error | Location to store loading error to, or `NULL`. |

#### Returns

Whether it succeeded.

### gwy_app_settings_create_config_dir()

    gboolean
    gwy_app_settings_create_config_dir (GError **error);

Create gwyddion config directory.

#### Parameters

error | Location to store loading error to, or `NULL`. |

#### Returns

Whether it succeeded (also returns `TRUE` if the directory already exists).

### gwy_app_settings_get_module_dirs()

    gchar **
    gwy_app_settings_get_module_dirs (void);

Returns a list of directories to search modules in.

#### Returns

The list of module directories as a newly allocated array of newly allocated strings, to be freed with `g_strfreev()` when not longer needed.

[transfer full]

### gwy_app_settings_get_settings_filename()

    gchar *
    gwy_app_settings_get_settings_filename
                                   (void);

Returns a suitable human-readable settings file name.

#### Returns

The file name as a newly allocated string.

### gwy_app_settings_get_log_filename()

    gchar *
    gwy_app_settings_get_log_filename (void);

Returns a suitable log file name.

#### Returns

The file name as a newly allocated string.

### gwy_app_settings_get_recent_file_list_filename()

    gchar *
    gwy_app_settings_get_recent_file_list_filename
                                   (void);

Returns a suitable recent file list file name.

#### Returns

The file name as a newly allocated string.

### gwy_app_settings_get_default_mask_color()

    void
    gwy_app_settings_get_default_mask_color
                                   (GwyRGBA *color);

Gets the current default mask colour.

Normally, the settings contain the default mask colour. If, for whatever reason, the settings do not exist or the colour it has been deleted, the function fills `color` with the initial default mask colour.

#### Parameters

color | Location where to store the colour. | [out]

## Types and Values

### GWY_APP_SETTINGS_ERROR

    #define GWY_APP_SETTINGS_ERROR gwy_app_settings_error_quark()

Error domain for application settings operations. Errors in this domain will be from the GwyAppSettingsError enumeration. See GError for information on error domains.

### enum GwyAppSettingsError

Error codes returned by application settings functions.

#### Members

GWY_APP_SETTINGS_ERROR_FILE | Settings file is not readable or writable. |
GWY_APP_SETTINGS_ERROR_CORRUPT | Settings file contents is corrupt. |
GWY_APP_SETTINGS_ERROR_CFGDIR | User configuration directory is not readable or writable or it does not exist and its creation failed. |
GWY_APP_SETTINGS_ERROR_EMPTY | Settings file is empty. Unlike corrupt files, which may contain valuable information, empty settings files can be overwritten without losing anything. |

## See Also

GwyParamDef, GwyParams -- a higher level module settings interface