Add Stash setting functions to API.

Remove unnecessary argument to stash_group_load_from_file().



git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4790 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -3,6 +3,11 @@
  * THANKS, src/vte.c:
    Apply patch from Yoann Le Montagner to set VTE bold color (thanks,
    fixes #2976905).
+ * wscript, src/plugindata.h, src/stash.c, src/stash.h, src/plugins.c,
+   src/Makefile.am, doc/plugins.dox, doc/stash-example.c,
+   plugins/geanyfunctions.h, plugins/geanyplugin.h:
+   Add Stash setting functions to API.
+   Remove unnecessary argument to stash_group_load_from_file().
 
 
 2010-03-25  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>

doc/plugins.dox

@@ -57,6 +57,7 @@
  * - @link msgwindow.h @endlink
  * - @link project.h @endlink
  * - @link sciwrappers.h Scintilla Wrapper Functions @endlink
+ * - @link stash.h Stash Pref/Setting Functions @endlink
  * - @link utils.h General Utility Functions @endlink
  * - @link ui_utils.h Widget Utility Functions @endlink
 

doc/stash-example.c

@@ -9,7 +9,7 @@ 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_KEY_FILE_NONE))
+if (!stash_group_load_from_file(group, filename))
 	g_warning(_("Could not load keyfile %s!"), filename);
 
 /* now use settings china_enabled and potter_name */

plugins/geanyfunctions.h

@@ -328,5 +328,25 @@
 	geany_functions->p_main->main_locale_init
 #define main_is_realized \
 	geany_functions->p_main->main_is_realized
+#define stash_group_new \
+	geany_functions->p_stash->stash_group_new
+#define stash_group_add_boolean \
+	geany_functions->p_stash->stash_group_add_boolean
+#define stash_group_add_integer \
+	geany_functions->p_stash->stash_group_add_integer
+#define stash_group_add_string \
+	geany_functions->p_stash->stash_group_add_string
+#define stash_group_add_string_vector \
+	geany_functions->p_stash->stash_group_add_string_vector
+#define stash_group_load_from_key_file \
+	geany_functions->p_stash->stash_group_load_from_key_file
+#define stash_group_save_to_key_file \
+	geany_functions->p_stash->stash_group_save_to_key_file
+#define stash_group_free \
+	geany_functions->p_stash->stash_group_free
+#define stash_group_load_from_file \
+	geany_functions->p_stash->stash_group_load_from_file
+#define stash_group_save_to_file \
+	geany_functions->p_stash->stash_group_save_to_file
 
 #endif

plugins/geanyplugin.h

@@ -34,7 +34,7 @@
 #include "geany.h"
 #include "plugindata.h"
 
-/* only include headers that define types or macros, not just functions */
+/* Note: only include headers that define types or macros, not just functions */
 #include "document.h"
 #include "editor.h"
 #include "encodings.h"
@@ -45,6 +45,7 @@
 #include "prefs.h"
 #include "project.h"
 #include "search.h"
+#include "stash.h"
 #include "support.h"
 #include "templates.h"
 #include "toolbar.h"

src/Makefile.am

@@ -66,6 +66,7 @@ geany_include_HEADERS = \
 	prefs.h \
 	project.h \
 	search.h \
+	stash.h \
 	support.h \
 	templates.h \
 	toolbar.h \

src/plugindata.h

@@ -50,7 +50,7 @@
 enum {
 	/** The Application Programming Interface (API) version, incremented
 	 * whenever any plugin data types are modified or appended to. */
-	GEANY_API_VERSION = 179,
+	GEANY_API_VERSION = 180,
 
 	/** The Application Binary Interface (ABI) version, incremented whenever
 	 * existing fields in the plugin data types have to be changed or reordered. */
@@ -238,6 +238,7 @@ typedef struct GeanyFunctions
 	struct PluginFuncs        	*p_plugin;			/**< See pluginutils.c */
 	struct ScintillaFuncs		*p_scintilla;		/**< See ScintillaFuncs */
 	struct MsgWinFuncs			*p_msgwin;			/**< See msgwindow.h */
+	struct StashFuncs			*p_stash;			/**< See stash.h */
 }
 GeanyFunctions;
 
@@ -591,6 +592,30 @@ typedef struct PluginFuncs
 PluginFuncs;
 
 
+struct StashGroup;
+
+/* See stash.h */
+typedef struct StashFuncs
+{
+	struct StashGroup *(*stash_group_new)(const gchar *name);
+	void (*stash_group_add_boolean)(struct StashGroup *group, gboolean *setting,
+			const gchar *key_name, gboolean default_value);
+	void (*stash_group_add_integer)(struct StashGroup *group, gint *setting,
+			const gchar *key_name, gint default_value);
+	void (*stash_group_add_string)(struct StashGroup *group, gchar **setting,
+			const gchar *key_name, const gchar *default_value);
+	void (*stash_group_add_string_vector)(struct StashGroup *group, gchar ***setting,
+			const gchar *key_name, const gchar **default_value);
+	void (*stash_group_load_from_key_file)(struct StashGroup *group, GKeyFile *keyfile);
+	void (*stash_group_save_to_key_file)(struct StashGroup *group, GKeyFile *keyfile);
+	void (*stash_group_free)(struct StashGroup *group);
+	gboolean (*stash_group_load_from_file)(struct StashGroup *group, const gchar *filename);
+	gint (*stash_group_save_to_file)(struct StashGroup *group, const gchar *filename,
+			GKeyFileFlags flags);
+}
+StashFuncs;
+
+
 /* Deprecated aliases */
 #ifndef GEANY_DISABLE_DEPRECATED
 

src/plugins.c

@@ -301,6 +301,19 @@ static MainFuncs main_funcs = {
 	&main_is_realized
 };
 
+static StashFuncs stash_funcs = {
+	&stash_group_new,
+	&stash_group_add_boolean,
+	&stash_group_add_integer,
+	&stash_group_add_string,
+	&stash_group_add_string_vector,
+	&stash_group_load_from_key_file,
+	&stash_group_save_to_key_file,
+	&stash_group_free,
+	&stash_group_load_from_file,
+	&stash_group_save_to_file
+};
+
 static GeanyFunctions geany_functions = {
 	&doc_funcs,
 	&sci_funcs,
@@ -321,7 +334,8 @@ static GeanyFunctions geany_functions = {
 	&main_funcs,
 	&plugin_funcs,
 	&scintilla_funcs,
-	&msgwin_funcs
+	&msgwin_funcs,
+	&stash_funcs
 };
 
 static GeanyData geany_data;

src/stash.c

@@ -22,7 +22,7 @@
  * $Id$
  */
 
-/*
+/**
  * @file stash.h
  * Lightweight library for reading/writing @c GKeyFile settings and synchronizing widgets with
  * C variables.
@@ -40,7 +40,7 @@
  *
  * @section String Settings
  * String settings and other dynamically allocated settings will be initialized to NULL when
- * added to a StashGroup (so they can safely be reassigned).
+ * added to a StashGroup (so they can safely be reassigned later).
  *
  * @section Widget Support
  * Widgets very commonly used in configuration dialogs will be supported with their own function.
@@ -240,16 +240,19 @@ static void keyfile_action(SettingAction action, StashGroup *group, GKeyFile *ke
 }
 
 
-/** Reads all key values (usually from a configuration file) into the group settings.
+/** Reads key values from @a 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.
  * @param group .
- * @param keyfile . */
+ * @param keyfile Usually loaded from a configuration file first. */
 void stash_group_load_from_key_file(StashGroup *group, GKeyFile *keyfile)
 {
 	keyfile_action(SETTING_READ, group, keyfile);
 }
 
 
-/** Writes group settings into key values for a configuration file.
+/** Writes group settings into key values in @a keyfile.
+ * @a keyfile is usually written to a configuration file afterwards.
  * @param group .
  * @param keyfile . */
 void stash_group_save_to_key_file(StashGroup *group, GKeyFile *keyfile)
@@ -259,20 +262,20 @@ void stash_group_save_to_key_file(StashGroup *group, GKeyFile *keyfile)
 
 
 /** Reads group settings from a configuration file using @c GKeyFile.
+ * @note Stash settings will be initialized to defaults if the keyfile
+ * couldn't be loaded from disk.
  * @param group .
- * @param filename Filename of the file to write, in locale encoding.
- * @param flags Keyfile options - @c G_KEY_FILE_NONE is the most efficient.
+ * @param filename Filename of the file to read, in locale encoding.
  * @return @c TRUE if a key file could be loaded.
  * @see stash_group_load_from_key_file().
  **/
-gboolean stash_group_load_from_file(StashGroup *group, const gchar *filename,
-		GKeyFileFlags flags)
+gboolean stash_group_load_from_file(StashGroup *group, const gchar *filename)
 {
 	GKeyFile *keyfile;
 	gboolean ret;
 
 	keyfile = g_key_file_new();
-	ret = g_key_file_load_from_file(keyfile, filename, flags, NULL);
+	ret = g_key_file_load_from_file(keyfile, filename, 0, NULL);
 	/* even on failure we load settings to apply defaults */
 	stash_group_load_from_key_file(group, keyfile);
 
@@ -282,8 +285,6 @@ gboolean stash_group_load_from_file(StashGroup *group, const gchar *filename,
 
 
 /** Writes group settings to a configuration file using @c GKeyFile.
- * If the file doesn't exist, it will be created.
- * If it already exists, it will be overwritten.
  *
  * @param group .
  * @param filename Filename of the file to write, in locale encoding.
@@ -375,6 +376,7 @@ add_pref(StashGroup *group, GType type, gpointer setting,
 	/* init any pointer settings to NULL so they can be freed later */
 	if (type == G_TYPE_STRING ||
 		type == G_TYPE_STRV)
+		if (group->use_defaults)
 			*(gpointer**)setting = NULL;
 
 	g_array_append_val(array, entry);

src/stash.h

@@ -55,8 +55,7 @@ void stash_group_load_from_key_file(StashGroup *group, GKeyFile *keyfile);
 
 void stash_group_save_to_key_file(StashGroup *group, GKeyFile *keyfile);
 
-gboolean stash_group_load_from_file(StashGroup *group, const gchar *filename,
-		GKeyFileFlags flags);
+gboolean stash_group_load_from_file(StashGroup *group, const gchar *filename);
 
 gint stash_group_save_to_file(StashGroup *group, const gchar *filename,
 		GKeyFileFlags flags);

wscript

@@ -482,7 +482,7 @@ def build(bld):
 		bld.install_files('${PREFIX}/include/geany', '''
 			src/document.h src/editor.h src/encodings.h src/filetypes.h src/geany.h
 			src/highlighting.h src/keybindings.h src/msgwindow.h src/plugindata.h
-			src/prefs.h src/project.h src/search.h src/support.h
+			src/prefs.h src/project.h src/search.h src/stash.h src/support.h
 			src/templates.h src/toolbar.h src/ui_utils.h src/utils.h
 			plugins/geanyplugin.h plugins/geanyfunctions.h''')
 		bld.install_files('${PREFIX}/include/geany/scintilla', '''