settings (HEAD)

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