## settings

settings — Application and module settings

## Synopsis

    #include <app/gwyapp.h>

    #define             GWY_APP_SETTINGS_ERROR
    enum                GwyAppSettingsError;
    GQuark              gwy_app_settings_error_quark        (void);
    GwyContainer*       gwy_app_settings_get                (void);
    void                gwy_app_settings_free               (void);
    gboolean            gwy_app_settings_save               (const gchar *filename,
                                                             GError **error);
    gboolean            gwy_app_settings_load               (const gchar *filename,
                                                             GError **error);
    gboolean            gwy_app_settings_create_config_dir  (GError **error);
    gchar**             gwy_app_settings_get_module_dirs    (void);
    gchar*              gwy_app_settings_get_settings_filename
                                                            (void);
    gchar*              gwy_app_settings_get_log_filename   (void);
    gchar*              gwy_app_settings_get_recent_file_list_filename
                                                            (void);
    gboolean            gwy_app_gl_init                     (int *argc,
                                                             char ***argv);
    gboolean            gwy_app_gl_is_ok                    (void);

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

## Details

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

    typedef enum {
        GWY_APP_SETTINGS_ERROR_FILE,
        GWY_APP_SETTINGS_ERROR_CORRUPT,
        GWY_APP_SETTINGS_ERROR_CFGDIR
    } GwyAppSettingsError;

Error codes returned by application settings functions.

`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_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 settings are a GwyContainer automatically loaded at program startup and saved ad its exit. For storing persistent module data you should use `"/module/YOUR_MODULE_NAME/"` prefix.

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.

`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);

Loads settings file.

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

    gboolean            gwy_app_settings_create_config_dir  (GError **error);

Create gwyddion config directory.

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

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