Revision: 4769 http://geany.svn.sourceforge.net/geany/?rev=4769&view=rev Author: ntrel Date: 2010-03-17 17:15:47 +0000 (Wed, 17 Mar 2010)
Log Message: ----------- Add doc-comments for Stash setting functions. Add an example file showing usage of Stash. (Not enabled yet until added to the plugin API).
Modified Paths: -------------- trunk/ChangeLog trunk/doc/Doxyfile.in trunk/doc/Makefile.am trunk/src/stash.c trunk/src/stash.h
Added Paths: ----------- trunk/doc/stash-example.c
Modified: trunk/ChangeLog =================================================================== --- trunk/ChangeLog 2010-03-17 13:39:18 UTC (rev 4768) +++ trunk/ChangeLog 2010-03-17 17:15:47 UTC (rev 4769) @@ -3,6 +3,11 @@ * tagmanager/python.c: Apply patch from Colomban Wendling to parse Python lambda functions (thanks) - modified to only parse toplevel or class member lambdas. + * src/stash.c, src/stash.h, doc/Doxyfile.in, doc/Makefile.am, + doc/stash-example.c: + Add doc-comments for Stash setting functions. + Add an example file showing usage of Stash. + (Not enabled yet until added to the plugin API).
2010-03-17 Lex Trotman <elextr.at.gmail.dot.com>
Modified: trunk/doc/Doxyfile.in =================================================================== --- trunk/doc/Doxyfile.in 2010-03-17 13:39:18 UTC (rev 4768) +++ trunk/doc/Doxyfile.in 2010-03-17 17:15:47 UTC (rev 4769) @@ -124,7 +124,7 @@ EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = EXCLUDE_SYMBOLS = -EXAMPLE_PATH = +EXAMPLE_PATH = . EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = NO IMAGE_PATH =
Modified: trunk/doc/Makefile.am =================================================================== --- trunk/doc/Makefile.am 2010-03-17 13:39:18 UTC (rev 4768) +++ trunk/doc/Makefile.am 2010-03-17 17:15:47 UTC (rev 4769) @@ -2,6 +2,7 @@ DOCDIR = $(DESTDIR)$(docdir) IMAGE_FILES = images/*.png EXTRA_DIST = geany.html geany.css geany.txt geany.1 plugins.dox pluginsymbols.c \ + stash-example.c \ $(srcdir)/$(IMAGE_FILES)
pdf: geany.txt
Added: trunk/doc/stash-example.c =================================================================== --- trunk/doc/stash-example.c (rev 0) +++ trunk/doc/stash-example.c 2010-03-17 17:15:47 UTC (rev 4769) @@ -0,0 +1,33 @@ +GeanyPrefGroup *group; +gboolean china_enabled; +gchar *potter_name = NULL; /* strings must be initialised */ +GKeyFile *keyfile; +const gchar filename[] = "/path/to/data.conf"; +gchar *data; + +/* setup the group */ +group = stash_group_new("cups"); +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 */ +keyfile = g_key_file_new(); +g_key_file_load_from_file(keyfile, filename, G_KEY_FILE_NONE, NULL); +stash_group_load_from_key_file(group, keyfile); +g_key_file_free(keyfile); + +/* now use settings china_enabled and potter_name */ +... + +/* save settings to file */ +keyfile = g_key_file_new(); +stash_group_save_to_key_file(group, keyfile); +data = g_key_file_to_data(keyfile, NULL, NULL); +if (utils_write_file(filename, data) != 0) + dialogs_show_msgbox(GTK_MESSAGE_ERROR, + _("Could not save keyfile %s!"), filename); +g_free(data); +g_key_file_free(keyfile); + +/* free memory */ +stash_group_free(group);
Property changes on: trunk/doc/stash-example.c ___________________________________________________________________ Added: svn:keywords + Author Date Id Revision Added: svn:eol-style + native
Modified: trunk/src/stash.c =================================================================== --- trunk/src/stash.c 2010-03-17 13:39:18 UTC (rev 4768) +++ trunk/src/stash.c 2010-03-17 17:15:47 UTC (rev 4769) @@ -22,28 +22,39 @@ * $Id$ */
-/* Mini-library for reading/writing GKeyFile settings and synchronizing widgets with - * C variables. */ - -/* Terms +/* + * @file stash.h + * Lightweight library for reading/writing @c 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. + * + * @section Terms * 'Setting' is used only for data stored on disk or in memory. * 'Pref' can also include visual widget information. * - * Memory Usage + * @section Memory 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. * - * String Settings + * @section String Settings * String settings and other dynamically allocated settings must be initialized to NULL as they * will be freed before reassigning. * - * Widget Support + * @section Widget 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. + * + * @section Example + * @include stash-example.c */ +/* TODO: Type naming should be changed to be independent of Geany. + * TODO: Rename to GStash as a libstash already exists. + */
/* Implementation Note * We use a GArray to hold prefs. It would be more efficient for user code to declare @@ -56,7 +67,9 @@ * Usually the prefs code isn't what user code will spend most of its time doing, so this * should be efficient enough. But, if desired we could add a stash_group_set_size() function * to reduce reallocation. - * */ + * + * TODO: Maybe using GSlice chunks with an extra 'next' pointer would be more (memory) efficient. + */
#include <gtk/gtk.h> @@ -76,6 +89,8 @@ gpointer fields; /* extra fields */ };
+typedef struct GeanyPrefEntry GeanyPrefEntry; + struct GeanyPrefGroup { const gchar *name; /* group name to use in the keyfile */ @@ -227,18 +242,27 @@ }
+/** Reads all key values (usually from a configuration file) into the group settings. + * @param group . + * @param keyfile . */ void stash_group_load_from_key_file(GeanyPrefGroup *group, GKeyFile *keyfile) { keyfile_action(SETTING_READ, group, keyfile); }
+/** Writes group settings into key values for a configuration file. + * @param group . + * @param keyfile . */ void stash_group_save_to_key_file(GeanyPrefGroup *group, GKeyFile *keyfile) { keyfile_action(SETTING_WRITE, group, keyfile); }
+/** Creates a new group. + * @param name Name used for @c GKeyFile group. + * @return Group. */ GeanyPrefGroup *stash_group_new(const gchar *name) { GeanyPrefGroup *group = g_new0(GeanyPrefGroup, 1); @@ -250,6 +274,8 @@ }
+/** Frees a group. + * @param group . */ void stash_group_free(GeanyPrefGroup *group) { GeanyPrefEntry *entry; @@ -299,6 +325,11 @@ }
+/** Adds boolean setting. + * @param group . + * @param setting Address of setting variable. + * @param key_name Name for key in a @c GKeyFile. + * @param default_value Value to use if the key doesn't exist when loading. */ void stash_group_add_boolean(GeanyPrefGroup *group, gboolean *setting, const gchar *key_name, gboolean default_value) { @@ -306,6 +337,11 @@ }
+/** Adds integer setting. + * @param group . + * @param setting Address of setting variable. + * @param key_name Name for key in a @c GKeyFile. + * @param default_value Value to use if the key doesn't exist when loading. */ void stash_group_add_integer(GeanyPrefGroup *group, gint *setting, const gchar *key_name, gint default_value) { @@ -313,9 +349,13 @@ }
-/* The contents of @a setting will be freed before being replaced, so make sure it is +/** Adds string setting. + * The contents of @a setting will be freed before being replaced, so make sure it is * allocated, or initialized to @c NULL. - * @param default_value Not duplicated. */ + * @param group . + * @param setting Address of setting variable. + * @param key_name Name for key in a @c GKeyFile. + * @param default_value Value to use if the key doesn't exist when loading. Not duplicated. */ void stash_group_add_string(GeanyPrefGroup *group, gchar **setting, const gchar *key_name, const gchar *default_value) { @@ -323,9 +363,13 @@ }
-/* The contents of @a setting will be freed before being replaced, so make sure it is +/** Adds string vector setting (array of strings). + * The contents of @a setting will be freed before being replaced, so make sure it is * allocated, or initialized to @c NULL. - * @param default_value Not duplicated. */ + * @param group . + * @param setting Address of setting variable. + * @param key_name Name for key in a @c GKeyFile. + * @param default_value Value to use if the key doesn't exist when loading. Not duplicated. */ void stash_group_add_string_vector(GeanyPrefGroup *group, gchar ***setting, const gchar *key_name, const gchar **default_value) { @@ -572,7 +616,7 @@ }
-/** @param owner If non-NULL, used to lookup widgets by name. */ +/* @param owner If non-NULL, used to lookup widgets by name. */ void stash_group_display(GeanyPrefGroup *group, GtkWidget *owner) { pref_action(PREF_DISPLAY, group, owner);
Modified: trunk/src/stash.h =================================================================== --- trunk/src/stash.h 2010-03-17 13:39:18 UTC (rev 4768) +++ trunk/src/stash.h 2010-03-17 17:15:47 UTC (rev 4769) @@ -25,12 +25,11 @@ #ifndef GEANY_STASH_H #define GEANY_STASH_H
-typedef struct GeanyPrefEntry GeanyPrefEntry; - +/** Opaque type for a group of settings. */ typedef struct GeanyPrefGroup GeanyPrefGroup;
-/* Can be (GtkWidget*) or (gchar*) depending on whether owner argument is used for - * stash_group_display/stash_group_update. */ +/* Can be @c GtkWidget* or @c gchar* depending on whether the @c owner argument is used for + * stash_group_display() and stash_group_update(). */ typedef gpointer GeanyWidgetID;
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.