geany  1.38
About: Geany is a text editor (using GTK2) with basic features of an integrated development environment (syntax highlighting, code folding, symbol name auto-completion, ...). F: office T: editor programming GTK+ IDE
  Fossies Dox: geany-1.38.tar.bz2  ("unofficial" and yet experimental doxygen-generated source code documentation)  

stash.h File Reference

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

#include "gtkcompat.h"
Include dependency graph for stash.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef 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

GType stash_group_get_type (void)
 
StashGroupstash_group_new (const gchar *name)
 Creates a new group. More...
 
void stash_group_add_boolean (StashGroup *group, gboolean *setting, const gchar *key_name, gboolean default_value)
 Adds boolean setting. 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_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_load_from_key_file (StashGroup *group, GKeyFile *keyfile)
 Reads key values from keyfile into the group settings. More...
 
void stash_group_save_to_key_file (StashGroup *group, GKeyFile *keyfile)
 Writes group settings into key values in keyfile. More...
 
void stash_group_free (StashGroup *group)
 Frees a group. More...
 
gboolean stash_group_load_from_file (StashGroup *group, const gchar *filename)
 Reads group settings from a configuration file using GKeyFile. 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_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_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_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_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_update (StashGroup *group, GtkWidget *owner)
 Applies widget values to Stash settings, usually called after displaying the widgets. More...
 
void stash_group_free_settings (StashGroup *group)
 Frees the memory allocated for setting values in a group. 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).

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.

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

Definition in file stash.h.

Typedef Documentation

◆ StashGroup

typedef struct StashGroup StashGroup

Opaque type for a group of settings.

Definition at line 29 of file stash.h.

◆ StashWidgetID

typedef gconstpointer StashWidgetID

Can be GtkWidget* or gchar* depending on whether the owner argument is used for stash_group_display() and stash_group_update().

Definition at line 33 of file stash.h.

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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.

Definition at line 472 of file stash.c.

References add_pref(), and group.

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

Definition at line 912 of file stash.c.

References add_widget_pref(), and group.

Referenced by init_pref_groups(), init_prefs(), and init_stash_prefs().

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

Definition at line 929 of file stash.c.

References add_widget_pref(), group, and TYPE_COMBO_BOX_ENTRY.

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

Definition at line 944 of file stash.c.

References add_widget_pref(), and group.

Referenced by init_pref_groups(), init_prefs(), and plugins_init().

◆ 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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_valueValue to use if the key doesn't exist when loading.

Definition at line 485 of file stash.c.

References add_pref(), and group.

Referenced by init_pref_groups(), init_prefs(), and init_stash_prefs().

◆ 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.
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);
#define NULL
Definition: rbtree.h:150
StashGroup * group
Definition: stash-example.c:1
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.
Definition: stash.c:845

Definition at line 845 of file stash.c.

References add_widget_pref(), count, entry, EnumWidget::enum_id, foreach_c_array, group, NULL, and EnumWidget::widget_id.

Referenced by init_pref_groups(), and init_stash_prefs().

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

Definition at line 896 of file stash.c.

References add_widget_pref(), and group.

Referenced by init_pref_groups(), and init_stash_prefs().

◆ 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.
settingAddress of setting variable.
key_nameName for key in a GKeyFile.
default_value String to copy if the key doesn't exist when loading, or NULL.

Definition at line 499 of file stash.c.

References add_pref(), and group.

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

Definition at line 513 of file stash.c.

References add_pref(), and group.

Referenced by plugins_init().

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

Definition at line 822 of file stash.c.

References add_widget_pref(), and group.

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

Definition at line 977 of file stash.c.

References add_widget_pref(), StashPref::extra, group, object_get_property_type(), and StashPref::property_name.

Referenced by sidebar_init().

◆ 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.
ownerIf non-NULL, used to lookup widgets by name, otherwise widget pointers are assumed.
See also
stash_group_update().

Definition at line 781 of file stash.c.

References group, pref_action(), and PREF_DISPLAY.

◆ stash_group_free()

void stash_group_free ( StashGroup group)

Frees a group.

Parameters
group.

Definition at line 407 of file stash.c.

References StashGroup::entries, group, and StashGroup::refcount.

Referenced by configuration_finalize(), and destroy_project().

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

Definition at line 377 of file stash.c.

References StashGroup::entries, entry, foreach_ptr_array, group, and NULL.

◆ stash_group_get_type()

GType stash_group_get_type ( void  )

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

Definition at line 301 of file stash.c.

References filename, group, NULL, and 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.
keyfileUsually loaded from a configuration file first.

Definition at line 275 of file stash.c.

References group, keyfile_action(), and SETTING_READ.

Referenced by add_stash_group(), load_config(), settings_action(), and stash_group_load_from_file().

◆ stash_group_new()

StashGroup * stash_group_new ( const gchar *  name)

Creates a new group.

Parameters
nameName used for GKeyFile group.
Returns
Group.

Definition at line 360 of file stash.c.

References StashGroup::entries, free_stash_pref(), group, name, StashGroup::name, StashGroup::refcount, and StashGroup::use_defaults.

Referenced by init_pref_groups(), init_prefs(), init_stash_prefs(), load_dialog_prefs(), plugins_init(), sidebar_init(), and ui_init_prefs().

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

Definition at line 326 of file stash.c.

References filename, group, NULL, stash_group_save_to_key_file(), and utils_write_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.

Definition at line 286 of file stash.c.

References group, keyfile_action(), and SETTING_WRITE.

Referenced by settings_action(), stash_group_save_to_file(), and write_config().

◆ 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.
ownerIf non-NULL, used to lookup widgets by name, otherwise widget pointers are assumed.
See also
stash_group_display().

Definition at line 794 of file stash.c.

References group, pref_action(), and PREF_UPDATE.