stash.h File Reference

Lightweight library for reading/writing GKeyFile settings and synchronizing widgets with C variables. More...

Typedefs
typedef struct StashGroup	StashGroup
	Opaque type for a group of settings.
typedef gconstpointer	StashWidgetID
	Can be GtkWidget* or gchar* depending on whether the owner argument is used for stash_group_display() and stash_group_update().

Functions
void	stash_group_add_boolean (StashGroup *group, gboolean *setting, const gchar *key_name, gboolean default_value)
	Adds boolean setting. More...
void	stash_group_add_combo_box (StashGroup *group, gint *setting, const gchar *key_name, gint default_value, StashWidgetID widget_id)
	Adds a GtkComboBox widget pref. More...
void	stash_group_add_combo_box_entry (StashGroup *group, gchar **setting, const gchar *key_name, const gchar *default_value, StashWidgetID widget_id)
	Adds a GtkComboBoxEntry widget pref. More...
void	stash_group_add_double (StashGroup *group, gdouble *setting, const gchar *key_name, gdouble default_value)
	Adds double setting. More...
void	stash_group_add_entry (StashGroup *group, gchar **setting, const gchar *key_name, const gchar *default_value, StashWidgetID widget_id)
	Adds a GtkEntry widget pref. More...
void	stash_group_add_integer (StashGroup *group, gint *setting, const gchar *key_name, gint default_value)
	Adds integer setting. More...
void	stash_group_add_radio_buttons (StashGroup *group, gint *setting, const gchar *key_name, gint default_value, StashWidgetID widget_id, gint enum_id,...) G_GNUC_NULL_TERMINATED
	Adds a GtkRadioButton widget group pref. More...
void	stash_group_add_spin_button_integer (StashGroup *group, gint *setting, const gchar *key_name, gint default_value, StashWidgetID widget_id)
	Adds a GtkSpinButton widget pref. More...
void	stash_group_add_string (StashGroup *group, gchar **setting, const gchar *key_name, const gchar *default_value)
	Adds string setting. More...
void	stash_group_add_string_vector (StashGroup *group, gchar ***setting, const gchar *key_name, const gchar **default_value)
	Adds string vector setting (array of strings). More...
void	stash_group_add_toggle_button (StashGroup *group, gboolean *setting, const gchar *key_name, gboolean default_value, StashWidgetID widget_id)
	Adds a GtkToggleButton (or GtkCheckButton) widget pref. More...
void	stash_group_add_widget_property (StashGroup *group, gpointer setting, const gchar *key_name, gpointer default_value, StashWidgetID widget_id, const gchar *property_name, GType type)
	Adds a widget's read/write property to the stash group. More...
void	stash_group_display (StashGroup *group, GtkWidget *owner)
	Applies Stash settings to widgets, usually called before displaying the widgets. More...
void	stash_group_free (StashGroup *group)
	Frees a group. More...
void	stash_group_free_settings (StashGroup *group)
	Frees the memory allocated for setting values in a group. More...
gboolean	stash_group_load_from_file (StashGroup *group, const gchar *filename)
	Reads group settings from a configuration file using GKeyFile. More...
void	stash_group_load_from_key_file (StashGroup *group, GKeyFile *keyfile)
	Reads key values from keyfile into the group settings. More...
StashGroup *	stash_group_new (const gchar *name)
	Creates a new group. More...
gint	stash_group_save_to_file (StashGroup *group, const gchar *filename, GKeyFileFlags flags)
	Writes group settings to a configuration file using GKeyFile. More...
void	stash_group_save_to_key_file (StashGroup *group, GKeyFile *keyfile)
	Writes group settings into key values in keyfile. More...
void	stash_group_update (StashGroup *group, GtkWidget *owner)
	Applies widget values to Stash settings, usually called after displaying the widgets. More...

Detailed Description

Lightweight library for reading/writing GKeyFile settings and synchronizing widgets with C variables.

Note: Stash should only depend on GLib and GTK, but currently has some minor dependencies on Geany's utils.c.

Terms

'Setting' is used only for data stored on disk or in memory. 'Pref' can also include visual widget information.

Usage

Stash will not duplicate strings if they are normally static arrays, such as keyfile group names and key names, string default values, widget_id names, property names.

Settings

String settings and other dynamically allocated settings will be initialized to NULL when added to a StashGroup (so they can safely be reassigned later).

Support

Widgets very commonly used in configuration dialogs will be supported with their own function. Widgets less commonly used such as GtkExpander or widget settings that aren't commonly needed to be persistent won't be directly supported, to keep the library lightweight. However, you can use stash_group_add_widget_property() to also save these settings for any read/write widget property. Macros could be added for common widget properties such as GtkExpander:"expanded".

Settings Example

Here we have some settings for a cup - whether it is made of porcelain, who made it, how many we have, and how much they cost. (Yes, it's a stupid example).

StashGroup *group;
gboolean porcelain_enabled;
gchar *potter_name;
gint stock;
gdouble price;
const gchar filename[] = "/path/data.conf";
 
/* setup the group */
group = stash_group_new("cup");
stash_group_add_boolean(group, &porcelain_enabled, "porcelain", TRUE);
stash_group_add_string(group, &potter_name, "potter_name", "Miss Clay");
stash_group_add_integer(group, &stock, "stock", 5);
stash_group_add_double(group, &price, "price", 1.50);
 
/* load the settings from a file */
if (!stash_group_load_from_file(group, filename))
    g_warning(_("Could not load keyfile %s!"), filename);
 
/* now use settings porcelain_enabled, potter_name, stock, and price */
/* ... */
 
/* save settings to file */
if (stash_group_save_to_file(group, filename, G_KEY_FILE_NONE) != 0)
    g_error(_("Could not save keyfile %s!"), filename);
 
/* free memory */
stash_group_free(group);

Note

You might want to handle the warning/error conditions differently from above.

GUI Prefs Example

For prefs, it's the same as the above example but you tell Stash to add widget prefs instead of just data settings.

This example uses lookup strings for widgets as they are more flexible than widget pointers. Code to load and save the settings is omitted - see the first example instead.

Here we show a dialog with a toggle button for whether the cup should have a handle.

gboolean want_handle;
StashGroup *group = ...;
 
/* Add the stash setting first so we can load it from disk if we want.
 * Effectively, stash_group_add_boolean() is called for you.
 * We need to use either a widget pointer or a widget name, and as we
 * haven't created the widget yet we'll use a name - check_handle. */
stash_group_add_toggle_button(group, &want_handle, "handle", TRUE, "check_handle");
 
/* here we could load the setting from disk */
 
...
/* Later we create a dialog holding the toggle button widget.
 * (Note: a check button is a subclass of a toggle button). */
GtkWidget *dialog = ...;
GtkWidget *check_button = gtk_check_button_new_with_label(_("Handle"));
 
/* pack the widget into the dialog */
gtk_container_add(GTK_CONTAINER(dialog->vbox), check_button);
 
/* Now we set a name to lookup the widget from the dialog.
 * We must remember to pass 'dialog' as an argument to Stash later. */
ui_hookup_widget(dialog, check_button, "check_handle");
 
...
/* At some point we want to display the dialog.
 * First we apply the want_handle boolean variable to the widget */
stash_group_display(group, dialog);
 
/* now display the dialog */
gtk_widget_show_all(dialog);
 
/* let the user manipulate widgets */
...
/* Now synchronize the want_handle variable */
stash_group_update(group, dialog);

Note

This example should also work for other widget containers besides dialogs, e.g. popup menus.

Function Documentation

stash_group_add_boolean()

void stash_group_add_boolean	(	StashGroup *	group,
		gboolean *	setting,
		const gchar *	key_name,
		gboolean	default_value
	)

Adds boolean setting.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.

stash_group_add_combo_box()

void stash_group_add_combo_box	(	StashGroup *	group,
		gint *	setting,
		const gchar *	key_name,
		gint	default_value,
		StashWidgetID	widget_id
	)

Adds a GtkComboBox widget pref.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.
widget_id	GtkWidget pointer or string to lookup widget later.

See also

stash_group_add_combo_box_entry().

stash_group_add_combo_box_entry()

void stash_group_add_combo_box_entry	(	StashGroup *	group,
		gchar **	setting,
		const gchar *	key_name,
		const gchar *	default_value,
		StashWidgetID	widget_id
	)

Adds a GtkComboBoxEntry widget pref.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.
widget_id	GtkWidget pointer or string to lookup widget later.

stash_group_add_double()

void stash_group_add_double	(	StashGroup *	group,
		gdouble *	setting,
		const gchar *	key_name,
		gdouble	default_value
	)

Adds double setting.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.

stash_group_add_entry()

void stash_group_add_entry	(	StashGroup *	group,
		gchar **	setting,
		const gchar *	key_name,
		const gchar *	default_value,
		StashWidgetID	widget_id
	)

Adds a GtkEntry widget pref.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.
widget_id	GtkWidget pointer or string to lookup widget later.

stash_group_add_integer()

void stash_group_add_integer	(	StashGroup *	group,
		gint *	setting,
		const gchar *	key_name,
		gint	default_value
	)

Adds integer setting.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.

stash_group_add_radio_buttons()

void stash_group_add_radio_buttons	(	StashGroup *	group,
		gint *	setting,
		const gchar *	key_name,
		gint	default_value,
		StashWidgetID	widget_id,
		gint	enum_id,
			...
	)

Adds a GtkRadioButton widget group pref.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.
widget_id	GtkWidget pointer or string to lookup widget later.
enum_id	Enum value for widget_id.
...	pairs of widget_id, enum_id. Example (using widget lookup strings, but widget pointers can also work): enum {FOO, BAR}; stash_group_add_radio_buttons(group, &which_one_setting, "which_one", BAR, "radio_foo", FOO, "radio_bar", BAR, NULL);

stash_group_add_spin_button_integer()

void stash_group_add_spin_button_integer	(	StashGroup *	group,
		gint *	setting,
		const gchar *	key_name,
		gint	default_value,
		StashWidgetID	widget_id
	)

Adds a GtkSpinButton widget pref.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.
widget_id	GtkWidget pointer or string to lookup widget later.

stash_group_add_string()

void stash_group_add_string	(	StashGroup *	group,
		gchar **	setting,
		const gchar *	key_name,
		const gchar *	default_value
	)

Adds string setting.

The contents of setting will be initialized to NULL.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	String to copy if the key doesn't exist when loading, or NULL.

stash_group_add_string_vector()

void stash_group_add_string_vector	(	StashGroup *	group,
		gchar ***	setting,
		const gchar *	key_name,
		const gchar **	default_value
	)

Adds string vector setting (array of strings).

The contents of setting will be initialized to NULL.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Vector to copy if the key doesn't exist when loading. Usually NULL.

stash_group_add_toggle_button()

void stash_group_add_toggle_button	(	StashGroup *	group,
		gboolean *	setting,
		const gchar *	key_name,
		gboolean	default_value,
		StashWidgetID	widget_id
	)

Adds a GtkToggleButton (or GtkCheckButton) widget pref.

Parameters

group	.
setting	Address of setting variable.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading.
widget_id	GtkWidget pointer or string to lookup widget later.

See also

stash_group_add_radio_buttons().

stash_group_add_widget_property()

void stash_group_add_widget_property	(	StashGroup *	group,
		gpointer	setting,
		const gchar *	key_name,
		gpointer	default_value,
		StashWidgetID	widget_id,
		const gchar *	property_name,
		GType	type
	)

Adds a widget's read/write property to the stash group.

The property will be set when calling stash_group_display(), and read when calling stash_group_update().

Parameters

group	.
setting	Address of e.g. an integer if using an integer property.
key_name	Name for key in a GKeyFile.
default_value	Value to use if the key doesn't exist when loading. Should be cast into a pointer e.g. with GINT_TO_POINTER().
widget_id	GtkWidget pointer or string to lookup widget later.
property_name	.
type	can be 0 if passing a GtkWidget as the widget_id argument to look it up from the GObject data.

Warning

Currently only string GValue properties will be freed before setting; patch for other types - see handle_widget_property().

stash_group_display()

void stash_group_display	(	StashGroup *	group,
		GtkWidget *	owner
	)

Applies Stash settings to widgets, usually called before displaying the widgets.

The owner argument depends on which type you use for StashWidgetID.

Parameters

group	.
owner	If non-NULL, used to lookup widgets by name, otherwise widget pointers are assumed.

See also

stash_group_update().

stash_group_free()

void stash_group_free

(

StashGroup *

group

)

Frees a group.

Parameters

group

.

stash_group_free_settings()

void stash_group_free_settings

(

StashGroup *

group

)

Frees the memory allocated for setting values in a group.

Useful e.g. to avoid freeing strings individually.

Note

This is not called by stash_group_free().

Parameters

group

.

stash_group_load_from_file()

gboolean stash_group_load_from_file	(	StashGroup *	group,
		const gchar *	filename
	)

Reads group settings from a configuration file using GKeyFile.

Note

Stash settings will be initialized to defaults if the keyfile couldn't be loaded from disk.

Parameters

group	.
filename	Filename of the file to read, in locale encoding.

Returns

TRUE if a key file could be loaded.

See also

stash_group_load_from_key_file().

stash_group_load_from_key_file()

void stash_group_load_from_key_file	(	StashGroup *	group,
		GKeyFile *	keyfile
	)

Reads key values from keyfile into the group settings.

Note

You should still call this even if the keyfile couldn't be loaded from disk so that all Stash settings are initialized to defaults.

Parameters

group	.
keyfile	Usually loaded from a configuration file first.

stash_group_new()

StashGroup * stash_group_new

(

const gchar *

name

)

Creates a new group.

Parameters

name	Name used for GKeyFile group.

Returns

Group.

stash_group_save_to_file()

gint stash_group_save_to_file	(	StashGroup *	group,
		const gchar *	filename,
		GKeyFileFlags	flags
	)

Writes group settings to a configuration file using GKeyFile.

Parameters

group	.
filename	Filename of the file to write, in locale encoding.
flags	Keyfile options - G_KEY_FILE_NONE is the most efficient.

Returns

0 if the file was successfully written, otherwise the errno of the failed operation is returned.

See also

stash_group_save_to_key_file().

stash_group_save_to_key_file()

void stash_group_save_to_key_file	(	StashGroup *	group,
		GKeyFile *	keyfile
	)

Writes group settings into key values in keyfile.

keyfile is usually written to a configuration file afterwards.

Parameters

group	.
keyfile	.

stash_group_update()

void stash_group_update	(	StashGroup *	group,
		GtkWidget *	owner
	)

Applies widget values to Stash settings, usually called after displaying the widgets.

The owner argument depends on which type you use for StashWidgetID.

Parameters

group	.
owner	If non-NULL, used to lookup widgets by name, otherwise widget pointers are assumed.

See also

stash_group_display().