settings: Gwyddion Application Library Reference Manual

## settings settings — Application and module settings |

## Functions

GQuark | gwy_app_settings_error_quark ()
GwyContainer * | 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 ()
gboolean | gwy_app_gl_init ()
gboolean | gwy_app_gl_is_ok ()

## Types and Values

#define | GWY_APP_SETTINGS_ERROR
enum | GwyAppSettingsError

## Includes

    #include <app/gwyapp.h>

## Description

All application and module settings are stored in a one big GwyContainer which can be obtained by `gwy_app_settings_get()`. Then you can use GwyContainer 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 ()

    GwyContainer *
    gwy_app_settings_get (void);

Gets the Gwyddion settings.

The program settings are a GwyContainer automatically loaded at program startup and saved ad its exit. 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 GwyContainer.

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

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

Since: 2.63

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

### 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_gl_init ()

    gboolean
    gwy_app_gl_init (int *argc,
                     char ***argv);

Checks for working OpenGL and initializes it.

When OpenGL support is not compiled in, this function does not do anything. When OpenGL is supported, it calls `gtk_gl_init_check()` and `gwy_widgets_gl_init()` (if the former succeeeds).

#### Parameters

argc | Address of the argc parameter of `main()`. Passed to `gtk_gl_init_check()`. |
argv | Address of the argv parameter of `main()`. Passed to `gtk_gl_init_check()`. |

#### Returns

`TRUE` if OpenGL initialization succeeeded.

### gwy_app_gl_is_ok ()

    gboolean
    gwy_app_gl_is_ok (void);

Returns OpenGL availability.

#### Returns

The return value is the same as the return value of `gwy_app_gl_init()` which needs to be called prior to this function (until then, the return value is always `FALSE`).

## 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 corrupted. |
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 (Since 2.45). This was previously reported as `GWY_APP_SETTINGS_ERROR_CORRUPT` but empty settings files can be overwritten without losing anything. |

## See Also

GwyParamDef, GwyParams -- a higher level module settings interface