Geany  dev
Typedefs | Functions
stash.h File Reference

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

Typedefs

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

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_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...
 
StashGroupstash_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 how to make a cup - whether it should be made of china and who's going to make it. (Yes, it's a stupid example).

StashGroup *group;
gboolean china_enabled;
gchar *potter_name;
const gchar filename[] = "/path/data.conf";
/* setup the group */
group = stash_group_new("cup");
stash_group_add_boolean(group, &china_enabled, "china", TRUE);
stash_group_add_string(group, &potter_name, "potter_name", "Miss Clay");
/* 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 china_enabled and potter_name */
...
/* 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 */
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.

Typedef Documentation

typedef typedefG_BEGIN_DECLS 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().

Function Documentation

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

Adds boolean setting.

Parameters
group.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.
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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.
widget_idGtkWidget pointer or string to lookup widget later.
See Also
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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.
widget_idGtkWidget pointer or string to lookup widget later.
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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.
widget_idGtkWidget pointer or string to lookup widget later.
void stash_group_add_integer ( StashGroup group,
gint *  setting,
const gchar *  key_name,
gint  default_value 
)

Adds integer setting.

Parameters
group.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.
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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.
widget_idGtkWidget pointer or string to lookup widget later.
enum_idEnum 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);
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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.
widget_idGtkWidget pointer or string to lookup widget later.
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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueString to copy if the key doesn't exist when loading, or NULL.
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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueVector to copy if the key doesn't exist when loading. Usually NULL.
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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.
widget_idGtkWidget pointer or string to lookup widget later.
See Also
stash_group_add_radio_buttons().
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.
settingAddress of e.g. an integer if using an integer property.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading. Should be cast into a pointer e.g. with GINT_TO_POINTER().
widget_idGtkWidget pointer or string to lookup widget later.
property_name.
typecan 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().
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.
ownerIf non-NULL, used to lookup widgets by name, otherwise widget pointers are assumed.
See Also
stash_group_update().
void stash_group_free ( StashGroup group)

Frees a group.

Parameters
group.
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.
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.
filenameFilename 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().
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.
keyfileUsually loaded from a configuration file first.
StashGroup* stash_group_new ( const gchar *  name)

Creates a new group.

Parameters
nameName used for GKeyFile group.
Returns
Group.
gint stash_group_save_to_file ( StashGroup group,
const gchar *  filename,
GKeyFileFlags  flags 
)

Writes group settings to a configuration file using GKeyFile.

Parameters
group.
filenameFilename of the file to write, in locale encoding.
flagsKeyfile 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().
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.
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.
ownerIf non-NULL, used to lookup widgets by name, otherwise widget pointers are assumed.
See Also
stash_group_display().