Revision: 4772
http://geany.svn.sourceforge.net/geany/?rev=4772&view=rev
Author: ntrel
Date: 2010-03-18 13:13:11 +0000 (Thu, 18 Mar 2010)
Log Message:
-----------
Improve API docs contents page by listing all commonly-used files.
Fix 'Date' appearing twice on the date line.
Don't generate API docs for prefs.h, toolbar.h (unused).
Move some '@file' doc-comments to the .c file.
Modified Paths:
--------------
trunk/ChangeLog
trunk/doc/plugins.dox
trunk/src/pluginutils.c
trunk/src/prefs.c
trunk/src/prefs.h
trunk/src/toolbar.c
trunk/src/toolbar.h
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2010-03-18 12:35:16 UTC (rev 4771)
+++ trunk/ChangeLog 2010-03-18 13:13:11 UTC (rev 4772)
@@ -3,6 +3,12 @@
* data/filetypes.common:
Set default for wrapped lines to show marker at end of line only
(more expected and doesn't change line alignment - closes #2972386).
+ * src/toolbar.c, src/toolbar.h, src/prefs.c, src/prefs.h,
+ src/pluginutils.c, doc/plugins.dox:
+ Improve API docs contents page by listing all commonly-used files.
+ Fix 'Date' appearing twice on the date line.
+ Don't generate API docs for prefs.h, toolbar.h (unused).
+ Move some '@file' doc-comments to the .c file.
2010-03-17 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
Modified: trunk/doc/plugins.dox
===================================================================
--- trunk/doc/plugins.dox 2010-03-18 12:35:16 UTC (rev 4771)
+++ trunk/doc/plugins.dox 2010-03-18 13:13:11 UTC (rev 4772)
@@ -32,25 +32,38 @@
* @mainpage Geany Plugin API Documentation
*
* @author Enrico Tröger, Nick Treleaven, Frank Lanitz
- * @date $Date$
+ * $Date$
*
* @section Intro
* This is the Geany API documentation. It should be considered work in progress.
* We will try to document as many functions and structs as possible.
*
- * To get started, see the @link howto Plugin Howto @endlink.
+ * @warning Do not use any symbol not in the documentation - it may change.
*
- * Other pages:
+ * @section pluginsupport Plugin Support
+ * - @link howto Plugin HowTo @endlink - get started
* - @link pluginsymbols.c Plugin Symbols @endlink
* - @link plugindata.h Main Datatypes and Macros @endlink
* - @link signals Plugin Signals @endlink
- * - @link pluginutils.c Plugin Utility Functions @endlink
+ * - @link pluginutils.h Plugin Utility Functions @endlink
* - @link guidelines Plugin Writing Guidelines @endlink
* - <b>plugins/demoplugin.c</b> - in Geany's source, bigger than the howto example
- * - Header files for functions and types - see <b>Files</b> link at the top
+ *
+ * @section common Common API files
+ * - @link dialogs.h @endlink
+ * - @link document.h @endlink
+ * - @link editor.h @endlink
+ * - @link filetypes.h @endlink
+ * - @link msgwindow.h @endlink
+ * - @link project.h @endlink
+ * - @link sciwrappers.h Scintilla Wrapper Functions @endlink
+ * - @link utils.h General Utility Functions @endlink
+ * - @link ui_utils.h Widget Utility Functions @endlink
+
+ * @section More
+ * - All API functions and types - see <b>Files</b> link at the top
* - Deprecated symbols - see <b>Related Pages</b> link at the top
*
- * @warning Do not use any symbol not in the documentation - it may change.
* @note See the HACKING file for information about developing the plugin API and
* other useful notes.
*/
@@ -376,7 +389,7 @@
* the plugin binary in @c ~/.config/geany/plugins/.
*
*
- * @page howto Plugin Howto
+ * @page howto Plugin HowTo
*
* @section intro Introduction
*
Modified: trunk/src/pluginutils.c
===================================================================
--- trunk/src/pluginutils.c 2010-03-18 12:35:16 UTC (rev 4771)
+++ trunk/src/pluginutils.c 2010-03-18 13:13:11 UTC (rev 4772)
@@ -22,7 +22,7 @@
* $Id$
*/
-/** @file pluginutils.c
+/** @file pluginutils.h
* Plugin utility functions.
* These functions all take the @ref geany_plugin symbol as their first argument. */
Modified: trunk/src/prefs.c
===================================================================
--- trunk/src/prefs.c 2010-03-18 12:35:16 UTC (rev 4771)
+++ trunk/src/prefs.c 2010-03-18 13:13:11 UTC (rev 4772)
@@ -22,6 +22,11 @@
*/
/*
+ * @file prefs.h
+ * Preferences dialog.
+ */
+
+/*
* Preferences dialog support functions.
* New prefs should use Stash code in keyfile.c - init_pref_groups().
*/
Modified: trunk/src/prefs.h
===================================================================
--- trunk/src/prefs.h 2010-03-18 12:35:16 UTC (rev 4771)
+++ trunk/src/prefs.h 2010-03-18 13:13:11 UTC (rev 4772)
@@ -20,12 +20,6 @@
*
*/
-/**
- * @file prefs.h
- * Preferences dialog.
- **/
-
-
#ifndef GEANY_PREFS_H
#define GEANY_PREFS_H 1
Modified: trunk/src/toolbar.c
===================================================================
--- trunk/src/toolbar.c 2010-03-18 12:35:16 UTC (rev 4771)
+++ trunk/src/toolbar.c 2010-03-18 13:13:11 UTC (rev 4772)
@@ -21,10 +21,11 @@
* $Id$
*/
-
-/** @file toolbar.c
- * Utility functions to create the toolbar.
+/**
+ * @file toolbar.h
+ * Toolbar (prefs).
*/
+/* Utility functions to create the toolbar */
#include "geany.h"
#include "support.h"
Modified: trunk/src/toolbar.h
===================================================================
--- trunk/src/toolbar.h 2010-03-18 12:35:16 UTC (rev 4771)
+++ trunk/src/toolbar.h 2010-03-18 13:13:11 UTC (rev 4772)
@@ -21,12 +21,6 @@
* $Id$
*/
-/**
- * @file toolbar.h
- * Toolbar (prefs).
- **/
-
-
#ifndef GEANY_TOOLBAR_H
#define GEANY_TOOLBAR_H
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
Revision: 4771
http://geany.svn.sourceforge.net/geany/?rev=4771&view=rev
Author: ntrel
Date: 2010-03-18 12:35:16 +0000 (Thu, 18 Mar 2010)
Log Message:
-----------
Set default for wrapped lines to show marker at end of line only
(more expected and doesn't change line alignment - closes #2972386).
Modified Paths:
--------------
trunk/ChangeLog
trunk/data/filetypes.common
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2010-03-17 17:15:47 UTC (rev 4770)
+++ trunk/ChangeLog 2010-03-18 12:35:16 UTC (rev 4771)
@@ -1,3 +1,10 @@
+2010-03-18 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
+
+ * data/filetypes.common:
+ Set default for wrapped lines to show marker at end of line only
+ (more expected and doesn't change line alignment - closes #2972386).
+
+
2010-03-17 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
* tagmanager/python.c:
Modified: trunk/data/filetypes.common
===================================================================
--- trunk/data/filetypes.common 2010-03-17 17:15:47 UTC (rev 4770)
+++ trunk/data/filetypes.common 2010-03-18 12:35:16 UTC (rev 4771)
@@ -73,7 +73,7 @@
# second argument: whether the visual flags to indicate a line is wrapped are drawn near the border
# or near the text. This is a bitmask of the values: 0 - Visual flags drawn near border,
# 1 - Visual flag at end of subline drawn near text, 2 - Visual flag at begin of subline drawn near text
-line_wrap_visuals=3;0;
+line_wrap_visuals=1;0;
# first argument: sets the size of indentation of sublines for wrapped lines in terms of
# the width of a space, only used when the second argument is 0
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
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.