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