[Gnucash-changes] r11929 - gnucash/trunk - Add documentation.
David Hampton
hampton at cvs.gnucash.org
Mon Nov 14 00:14:22 EST 2005
Author: hampton
Date: 2005-11-14 00:14:21 -0500 (Mon, 14 Nov 2005)
New Revision: 11929
Trac: http://svn.gnucash.org/trac/changeset/11929
Modified:
gnucash/trunk/ChangeLog
gnucash/trunk/src/gnome-utils/dialog-preferences.c
gnucash/trunk/src/gnome-utils/gnc-embedded-window.c
gnucash/trunk/src/gnome-utils/gnc-embedded-window.h
gnucash/trunk/src/gnome-utils/gnc-main-window.c
gnucash/trunk/src/gnome-utils/gnc-main-window.h
gnucash/trunk/src/gnome-utils/gnc-plugin-file-history.c
gnucash/trunk/src/gnome-utils/gnc-plugin-file-history.h
gnucash/trunk/src/gnome-utils/gnc-plugin-manager.h
gnucash/trunk/src/gnome-utils/gnc-plugin-menu-additions.c
gnucash/trunk/src/gnome-utils/gnc-plugin-menu-additions.h
gnucash/trunk/src/gnome-utils/gnc-plugin-page.c
gnucash/trunk/src/gnome-utils/gnc-plugin-page.h
gnucash/trunk/src/gnome-utils/gnc-plugin.c
gnucash/trunk/src/gnome-utils/gnc-plugin.h
gnucash/trunk/src/gnome-utils/gnc-tree-model-account.c
gnucash/trunk/src/gnome-utils/gnc-tree-model-account.h
gnucash/trunk/src/gnome-utils/gnc-tree-model-commodity.c
gnucash/trunk/src/gnome-utils/gnc-tree-model-commodity.h
gnucash/trunk/src/gnome-utils/gnc-tree-model-price.c
gnucash/trunk/src/gnome-utils/gnc-tree-model-price.h
gnucash/trunk/src/gnome-utils/gnc-tree-model.c
gnucash/trunk/src/gnome-utils/gnc-tree-model.h
gnucash/trunk/src/gnome-utils/gnc-window.h
gnucash/trunk/src/gnome/gnc-plugin-account-tree.c
gnucash/trunk/src/gnome/gnc-plugin-account-tree.h
gnucash/trunk/src/gnome/gnc-plugin-basic-commands.c
gnucash/trunk/src/gnome/gnc-plugin-basic-commands.h
gnucash/trunk/src/gnome/gnc-plugin-page-account-tree.c
gnucash/trunk/src/gnome/gnc-plugin-page-account-tree.h
gnucash/trunk/src/gnome/gnc-plugin-page-register.c
gnucash/trunk/src/gnome/gnc-plugin-page-register.h
Log:
Add documentation.
Modified: gnucash/trunk/ChangeLog
===================================================================
--- gnucash/trunk/ChangeLog 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/ChangeLog 2005-11-14 05:14:21 UTC (rev 11929)
@@ -1,5 +1,10 @@
2005-11-13 David Hampton <hampton at employees.org>
+ * various src/gnome-utils and src/gnome files: Add documentation.
+
+ * src/gnome-utils/gnc-menu-extensions.[ch]: Remove unused
+ functions.
+
* src/gnome-utils/gnc-plugin.[ch]:
* src/gnome/gnc-plugin-budget.c:
* src/gnome/gnc-plugin-register.c:
Modified: gnucash/trunk/src/gnome/gnc-plugin-account-tree.c
===================================================================
--- gnucash/trunk/src/gnome/gnc-plugin-account-tree.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome/gnc-plugin-account-tree.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -22,6 +22,15 @@
* Boston, MA 02111-1307, USA gnu at gnu.org
*/
+/** @addtogroup MenuPlugins
+ @{ */
+/** @addtogroup GncPluginAccountTree An Account Tree Plugin
+ @{ */
+/** @file gnc-plugin-account-tree.c
+ @brief Provide the menus to create a chart of account page.
+ @author Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
+*/
+
#include "config.h"
#include <string.h>
@@ -42,14 +51,18 @@
#define PLUGIN_ACTIONS_NAME "gnc-plugin-account-tree-actions"
#define PLUGIN_UI_FILENAME "gnc-plugin-account-tree-ui.xml"
+/** An array of all of the actions provided by the account tree
+ * plugin. */
static GtkActionEntry gnc_plugin_actions [] = {
{ "FileNewAccountTreeAction", NULL, N_("New Accounts _Page"), NULL,
N_("Open a new Account Tree page"),
G_CALLBACK (gnc_plugin_account_tree_cmd_new_account_tree) },
};
+/** The number of actions provided by this plugin. */
static guint gnc_plugin_n_actions = G_N_ELEMENTS (gnc_plugin_actions);
+/** The instance private data structure for an account tree plugin. */
typedef struct GncPluginAccountTreePrivate
{
gpointer dummy;
@@ -58,8 +71,11 @@
#define GNC_PLUGIN_ACCOUNT_TREE_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_PLUGIN_ACCOUNT_TREE, GncPluginAccountTreePrivate))
+/** A pointer to the parent class of a plugin page. */
static GObjectClass *parent_class = NULL;
+
+/* Get the type of the account tree menu plugin. */
GType
gnc_plugin_account_tree_get_type (void)
{
@@ -86,6 +102,8 @@
return gnc_plugin_account_tree_type;
}
+
+/* Create a new account tree menu plugin. */
GncPlugin *
gnc_plugin_account_tree_new (void)
{
@@ -101,6 +119,14 @@
return GNC_PLUGIN (plugin);
}
+
+/** Initialize the class for a new account tree plugin. This will set
+ * up any function pointers that override functions in the parent
+ * class, and also configure the private data storage for this
+ * widget.
+ *
+ * @param klass The new class structure created by the object system.
+ */
static void
gnc_plugin_account_tree_class_init (GncPluginAccountTreeClass *klass)
{
@@ -123,11 +149,26 @@
g_type_class_add_private(klass, sizeof(GncPluginAccountTreePrivate));
}
+
+/** Initialize a new instance of a gnucash content plugin. This
+ * function currently does nothing.
+ *
+ * @param page The new object instance created by the object
+ * system. */
static void
gnc_plugin_account_tree_init (GncPluginAccountTree *plugin)
{
}
+
+/** Finalize the account tree plugin object. This function is called
+ * from the G_Object level to complete the destruction of the object.
+ * It should release any memory not previously released by the
+ * destroy function (i.e. the private data structure), then chain up
+ * to the parent's destroy function. This function currently does
+ * nothing.
+ *
+ * @param object The object being destroyed. */
static void
gnc_plugin_account_tree_finalize (GObject *object)
{
@@ -157,3 +198,6 @@
page = gnc_plugin_page_account_tree_new ();
gnc_main_window_open_page (data->window, page);
}
+
+/** @} */
+/** @} */
Modified: gnucash/trunk/src/gnome/gnc-plugin-account-tree.h
===================================================================
--- gnucash/trunk/src/gnome/gnc-plugin-account-tree.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome/gnc-plugin-account-tree.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -22,6 +22,15 @@
* Boston, MA 02111-1307, USA gnu at gnu.org
*/
+/** @addtogroup MenuPlugins
+ @{ */
+/** @addtogroup GncPluginAccountTree An Account Tree Plugin
+ @{ */
+/** @file gnc-plugin-account-tree.h
+ @brief Provide the menus to create a chart of account page.
+ @author Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
+*/
+
#ifndef __GNC_PLUGIN_ACCOUNT_TREE_H
#define __GNC_PLUGIN_ACCOUNT_TREE_H
@@ -42,19 +51,36 @@
#define GNC_PLUGIN_ACCOUNT_TREE_NAME "gnc-plugin-account-tree"
/* typedefs & structures */
+
+/** The instance data structure for an account tree menu plugin. */
typedef struct {
+ /** The parent object for this widget */
GncPlugin gnc_plugin;
} GncPluginAccountTree;
+/** The class data structure for an account tree menu plugin. */
typedef struct {
+ /** The parent class for this widget. */
GncPluginClass gnc_plugin;
} GncPluginAccountTreeClass;
-/* function prototypes */
-GType gnc_plugin_account_tree_get_type (void);
-GncPlugin *gnc_plugin_account_tree_new (void);
+/** Get the type of the account tree menu plugin.
+ *
+ * @return A GType.
+ */
+GType gnc_plugin_account_tree_get_type (void);
+
+/** Create a new account tree menu plugin.
+ *
+ * @return A pointer to the new object.
+ */
+GncPlugin *gnc_plugin_account_tree_new (void);
+
G_END_DECLS
#endif /* __GNC_PLUGIN_ACCOUNT_TREE_H */
+
+/** @} */
+/** @} */
Modified: gnucash/trunk/src/gnome/gnc-plugin-basic-commands.c
===================================================================
--- gnucash/trunk/src/gnome/gnc-plugin-basic-commands.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome/gnc-plugin-basic-commands.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -21,6 +21,15 @@
* Boston, MA 02111-1307, USA gnu at gnu.org
*/
+/** @addtogroup MenuPlugins
+ @{ */
+/** @addtogroup GncPluginAccountTree An Account Tree Plugin
+ @{ */
+/** @file gnc-plugin-basic-commands.c
+ @brief Functions providing a basic set of menu items.
+ @author Copyright (C) 2005 David Hampton <hampton at employees.org>
+*/
+
#include "config.h"
#include <string.h>
@@ -73,6 +82,8 @@
#define PLUGIN_ACTIONS_NAME "gnc-plugin-basic-commands-actions"
#define PLUGIN_UI_FILENAME "gnc-plugin-basic-commands-ui.xml"
+/** An array of all of the actions provided by the basic commands
+ * plugin. */
static GtkActionEntry gnc_plugin_actions [] = {
/* File menu */
@@ -145,14 +156,21 @@
N_("View the Tips of the Day"),
G_CALLBACK (gnc_main_window_cmd_help_totd) },
};
+/** The number of actions provided by this plugin. */
static guint gnc_plugin_n_actions = G_N_ELEMENTS (gnc_plugin_actions);
+
+/** These are the "important" actions provided by the basic commands
+ * plugin. Their labels will appear when the toolbar is set to
+ * "Icons and important text" (e.g. GTK_TOOLBAR_BOTH_HORIZ) mode. */
static const gchar *gnc_plugin_important_actions[] = {
"FileSaveAction",
NULL,
};
+/** The instance private data structure for an basic commands
+ * plugin. */
typedef struct GncPluginBasicCommandsPrivate
{
gpointer dummy;
@@ -161,8 +179,11 @@
#define GNC_PLUGIN_BASIC_COMMANDS_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_PLUGIN_BASIC_COMMANDS, GncPluginBasicCommandsPrivate))
+/** A pointer to the parent class of a plugin page. */
static GObjectClass *parent_class = NULL;
+
+/* Get the type of the basic commands menu plugin. */
GType
gnc_plugin_basic_commands_get_type (void)
{
@@ -189,6 +210,8 @@
return gnc_plugin_basic_commands_type;
}
+
+/** Create a new basic commands menu plugin. */
GncPlugin *
gnc_plugin_basic_commands_new (void)
{
@@ -199,6 +222,14 @@
return GNC_PLUGIN (plugin);
}
+
+/** Initialize the class for a new basic commands plugin. This will
+ * set up any function pointers that override functions in the parent
+ * class, and also configure the private data storage for this
+ * widget.
+ *
+ * @param klass The new class structure created by the object system.
+ */
static void
gnc_plugin_basic_commands_class_init (GncPluginBasicCommandsClass *klass)
{
@@ -222,11 +253,26 @@
g_type_class_add_private(klass, sizeof(GncPluginBasicCommandsPrivate));
}
+
+/** Initialize a new instance of a basic commands plugin. This
+ * function currently does nothing.
+ *
+ * @param page The new object instance created by the object
+ * system. */
static void
gnc_plugin_basic_commands_init (GncPluginBasicCommands *plugin)
{
}
+
+/** Finalize the basic commands plugin object. This function is
+ * called from the G_Object level to complete the destruction of the
+ * object. It should release any memory not previously released by
+ * the destroy function (i.e. the private data structure), then chain
+ * up to the parent's destroy function. This function currently does
+ * nothing.
+ *
+ * @param object The object being destroyed. */
static void
gnc_plugin_basic_commands_finalize (GObject *object)
{
@@ -431,3 +477,6 @@
gnc_totd_dialog(GTK_WINDOW(data->window), FALSE);
}
+
+/** @} */
+/** @} */
Modified: gnucash/trunk/src/gnome/gnc-plugin-basic-commands.h
===================================================================
--- gnucash/trunk/src/gnome/gnc-plugin-basic-commands.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome/gnc-plugin-basic-commands.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -21,6 +21,15 @@
* Boston, MA 02111-1307, USA gnu at gnu.org
*/
+/** @addtogroup MenuPlugins
+ @{ */
+/** @addtogroup GncPluginAccountTree An Account Tree Plugin
+ @{ */
+/** @file gnc-plugin-basic-commands.h
+ @brief Functions providing a basic set of menu items.
+ @author Copyright (C) 2005 David Hampton <hampton at employees.org>
+*/
+
#ifndef __GNC_PLUGIN_BASIC_COMMANDS_H
#define __GNC_PLUGIN_BASIC_COMMANDS_H
@@ -41,21 +50,37 @@
#define GNC_PLUGIN_BASIC_COMMANDS_NAME "gnc-plugin-basic-commands"
/* typedefs & structures */
+
+/** The instance data structure for an basic commands menu plugin. */
typedef struct {
+ /** The parent object for this widget */
GncPlugin gnc_plugin;
} GncPluginBasicCommands;
+
+/** The class data structure for a basic commands menu plugin. */
typedef struct {
+ /** The parent class for this widget. */
GncPluginClass gnc_plugin;
} GncPluginBasicCommandsClass;
-/* function prototypes */
-GType gnc_plugin_basic_commands_get_type (void);
-GncPlugin *gnc_plugin_basic_commands_new (void);
+/** Get the type of the basic commands menu plugin.
+ *
+ * @return A GType.
+ */
+GType gnc_plugin_basic_commands_get_type (void);
-void gnc_new_basic_commands (GncMainWindow *window);
+/** Create a new basic commands menu plugin.
+ *
+ * @return A pointer to the new object.
+ */
+GncPlugin *gnc_plugin_basic_commands_new (void);
+
G_END_DECLS
#endif /* __GNC_PLUGIN_BASIC_COMMANDS_H */
+
+/** @} */
+/** @} */
Modified: gnucash/trunk/src/gnome/gnc-plugin-page-account-tree.c
===================================================================
--- gnucash/trunk/src/gnome/gnc-plugin-page-account-tree.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome/gnc-plugin-page-account-tree.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -27,7 +27,7 @@
/** @addtogroup GncPluginPageAccountTree An Account Tree Plugin
@{ */
/** @file gnc-plugin-page-account-tree.c
- @brief utility functions for the GnuCash UI
+ @brief Functions providing a chart of account page.
@author Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
Copyright (C) 2003,2005 David Hampton <hampton at employees.org>
*/
@@ -202,8 +202,12 @@
N_("Edit the account view options"),
G_CALLBACK (gnc_plugin_page_account_tree_cmd_view_options) },
};
+/** The number of actions provided by this plugin. */
static guint gnc_plugin_page_account_tree_n_actions = G_N_ELEMENTS (gnc_plugin_page_account_tree_actions);
+
+/** Actions that require an account to be selected before they are
+ * enabled. */
static const gchar *actions_requiring_account[] = {
"FileOpenAccountAction",
"FileOpenSubaccountsAction",
Modified: gnucash/trunk/src/gnome/gnc-plugin-page-account-tree.h
===================================================================
--- gnucash/trunk/src/gnome/gnc-plugin-page-account-tree.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome/gnc-plugin-page-account-tree.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -27,7 +27,7 @@
/** @addtogroup GncPluginPageAccountTree An Account Tree Plugin
@{ */
/** @file gnc-plugin-page-account-tree.h
- @brief utility functions for the GnuCash UI
+ @brief Functions providing a chart of account page.
@author Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
@author Copyright (C) 2003 David Hampton <hampton at employees.org>
*/
Modified: gnucash/trunk/src/gnome/gnc-plugin-page-register.c
===================================================================
--- gnucash/trunk/src/gnome/gnc-plugin-page-register.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome/gnc-plugin-page-register.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -27,7 +27,7 @@
/** @addtogroup RegisterPlugin Register Page
@{ */
/** @file gnc-plugin-page-register.c
- @brief Functions for creating a register page for the GnuCash UI
+ @brief Functions providing a register page for the GnuCash UI
@author Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
@author Copyright (C) 2003,2005 David Hampton <hampton at employees.org>
*/
@@ -265,11 +265,18 @@
};
static guint n_radio_entries_2 = G_N_ELEMENTS (radio_entries_2);
+
+/** These are the "important" actions provided by the register page.
+ * Their labels will appear when the toolbar is set to "Icons and
+ * important text" (e.g. GTK_TOOLBAR_BOTH_HORIZ) mode. */
static const gchar *important_actions[] = {
"SplitTransactionAction",
NULL,
};
+
+/** Actions that require an account to be selected before they are
+ * enabled. */
static const gchar *actions_requiring_account[] = {
"EditEditAccountAction",
"ActionsReconcileAction",
@@ -992,7 +999,7 @@
}
-/** This function is called when a radion button in the "Sort By..."
+/** This function is called when a radio button in the "Sort By..."
* dialog is clicked.
*
* @param button The button that was toggled.
@@ -1266,7 +1273,7 @@
* time limitation on the register query. This is handled by a
* helper function when the radio button is selected (as potentially
* all the widgets in the table need to be inspected), and is trivial
- * for th eother case.
+ * for the other case.
*
* @param button A pointer to the "select range" radio button.
*
Modified: gnucash/trunk/src/gnome/gnc-plugin-page-register.h
===================================================================
--- gnucash/trunk/src/gnome/gnc-plugin-page-register.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome/gnc-plugin-page-register.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -27,7 +27,7 @@
/** @addtogroup RegisterPlugin Register Page
@{ */
/** @file gnc-plugin-page-register.h
- @brief utility functions for the GnuCash UI
+ @brief Functions providing a register page for the GnuCash UI
@author Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
@author Copyright (C) 2003 David Hampton <hampton at employees.org>
*/
@@ -140,7 +140,7 @@
*
* @param page A "register" page.
*
- * @return The account if the register contsins only a single
+ * @return The account if the register contains only a single
* account, or an account and its sub-accounts. NULL otherwise.
*/
Account *gnc_plugin_page_register_get_account (GncPluginPageRegister *page);
Modified: gnucash/trunk/src/gnome-utils/dialog-preferences.c
===================================================================
--- gnucash/trunk/src/gnome-utils/dialog-preferences.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/dialog-preferences.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -80,7 +80,7 @@
#define WIDGET_HASH "widget_hash"
#define NOTEBOOK "notebook"
-/* This static indicates the debugging module that this .o belongs to. */
+/** The debugging module that this .o belongs to. */
static QofLogModule log_module = GNC_MOD_PREFS;
void gnc_preferences_response_cb(GtkDialog *dialog, gint response, GtkDialog *unused);
@@ -89,13 +89,27 @@
void gnc_reset_warnings_response_cb (GtkDialog *dialog, gint arg1, gpointer user_data);
+/** This data structure holds the information for a single addition to
+ * the preferences dialog. */
typedef struct addition_t {
+ /** The relative name of the file where the glade data for this
+ * addition can be found. */
gchar *filename;
+ /** The name of the widget within the glade data file that should be
+ * added to the preferences dialog. This should point to a
+ * GtkTable widget that has four columns. */
gchar *widgetname;
+ /** The name of the tab within the preferences dialog where these
+ * widgets should be placed. */
gchar *tabname;
+ /** TRUE if this addition represents a full page in the preferences
+ * dialog. FALSE if this page may be combined with other pages. */
gboolean full_page;
} addition;
+/** A list of all additions that have been made to the preferences
+ * dialog. The data fields for this list are ::addition data
+ * structures. */
GSList *add_ins = NULL;
@@ -121,7 +135,7 @@
/** This is the common function that adds any set of preferences to
* the preferences dialog. It allocates a data structure to remember
* the passed in data and queues it for later when the dialog is
- * actually built. This code does check to insure there arent any
+ * actually built. This code does check to insure there aren't any
* conflicts, like multiple additions of the same tab name when the
* two pages being added aren't compatible.
*
@@ -270,27 +284,43 @@
}
+/** This data structure is used while building the preferences dialog
+ * to perform lookups in the dialog under construction. It maintains
+ * state information between invocations of the function
+ * gnc_prefs_find_page which is called via a foreach loop over each
+ * addition. */
struct find_data {
+ /** The notebook being searched. */
GtkNotebook *notebook;
+ /** The name of the tab being searched for. */
const gchar *tabname;
+ /** The notebook index where the tab was found. */
gint index;
+ /** If TRUE, the code will search for an exact match of tab name. If
+ * FALSE, the code will search for where this tab falls
+ * alphabetically. */
gboolean exact;
};
+
+/** This data structure is used while building the preferences dialog
+ * to copy a table from a glade file to the dialog under
+ * construction. It maintains state information between invocations
+ * of the function gnc_prefs_move_table_entry which is called via a
+ * foreach loop over each item in the table. */
struct copy_data {
+ /** The table being copied from. */
GtkTable *table_from;
+ /** The table being copied to. */
GtkTable *table_to;
+ /** The number of lines offset from the old table to the new
+ * table. */
gint row_offset;
};
-struct page_data {
- GtkNotebook *notebook;
- GList *widgets;
-};
-
/** This function is used while building the preferences dialog. It
- * searches through the existing pages in the dialog to determin
+ * searches through the existing pages in the dialog to determine
* where a new page should go alphabetically. If a matching page
* name is found, a pointer to that page will be returned. This
* function can also be called and asked to perform an exact match
@@ -387,7 +417,7 @@
/** At dialog creation time, this function will be called once per
- * adds-in. It performs the work of addding the page into the main
+ * adds-in. It performs the work of adding the page into the main
* dialog. It handles both the case of a full page being added to
* the dialog, and a partial page being added.
*
@@ -516,7 +546,7 @@
/** The user clicked on a radio button. Update gconf. Radio button
* group choices are stored as a string. The last component of the
- * widget name is the string that will be stored. I.E. The widet name
+ * widget name is the string that will be stored. I.E. The widget name
* must be in this form "gconf/<some-key-name>/value".
*
* @internal
@@ -1302,7 +1332,7 @@
*
* @param user_data The name of the gconf key that was changed.
*
- * @return Zero if the gconf key is a sublse of this button's
+ * @return Zero if the gconf key is a subset of this button's
* name. Non-zero otherwise.
*/
static gboolean
@@ -1470,7 +1500,7 @@
/* This function creates the preferences dialog and presents it to
- * the user. The preferences dialog is a singletone, so if a
+ * the user. The preferences dialog is a singleton, so if a
* preferences dialog already exists it will be raised to the top of
* the window stack instead of creating a new dialog. */
void
Modified: gnucash/trunk/src/gnome-utils/gnc-embedded-window.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-embedded-window.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-embedded-window.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -40,10 +40,15 @@
#include "gnc-window.h"
#include "messages.h"
-/** Static Globals *******************************************************/
+/* Static Globals *******************************************************/
+
+/** The debugging module that this .o belongs to. */
static QofLogModule log_module = GNC_MOD_GUI;
+/** A pointer to the parent class of an embedded window. */
+static GObjectClass *parent_class = NULL;
-/** Declarations *********************************************************/
+
+/* Declarations *********************************************************/
static void gnc_embedded_window_class_init (GncEmbeddedWindowClass *klass);
static void gnc_embedded_window_init (GncEmbeddedWindow *window, GncEmbeddedWindowClass *klass);
static void gnc_embedded_window_finalize (GObject *object);
@@ -54,23 +59,40 @@
static void gnc_embedded_window_setup_window (GncEmbeddedWindow *window);
+/** The instance private data for an embedded window object. */
typedef struct GncEmbeddedWindowPrivate
{
+ /** The dock (vbox) at the top of the window containing the menubar
+ * and toolbar. These items are generated bu the UI manager and
+ * stored here when the UI manager provides them to the main
+ * window. */
GtkWidget *menu_dock;
- GtkWidget *toolbar_dock;
+ /* The toolbar created by the UI manager. This pointer provides
+ * easy access for showing/hiding the toolbar. */
+ GtkWidget *toolbar;
+ /** A pointer to the status bar at the bottom edge of the window.
+ * This pointer provides easy access for updating/showing/hiding
+ * the status bar. */
GtkWidget *statusbar;
+ /** The group of all actions provided by the main window itself.
+ * This does not include any action provided by menu or content
+ * plugins. */
GtkActionGroup *action_group;
+ /** The currently selected page. */
GncPluginPage *page;
- GtkWidget *parent_window;
+ /** The parent of this embedded "window". This points to a real
+ * GtkWindow widget. */
+ GtkWidget *parent_window;
} GncEmbeddedWindowPrivate;
#define GNC_EMBEDDED_WINDOW_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_EMBEDDED_WINDOW, GncEmbeddedWindowPrivate))
-static GObjectClass *parent_class = NULL;
+
+/* Get the type of a gnc embedded window. */
GType
gnc_embedded_window_get_type (void)
{
@@ -106,6 +128,8 @@
return gnc_embedded_window_type;
}
+
+/* Display a data plugin page in a window. */
void
gnc_embedded_window_open_page (GncEmbeddedWindow *window,
GncPluginPage *page)
@@ -129,6 +153,8 @@
LEAVE(" ");
}
+
+/* Remove a data plugin page from a window. */
void
gnc_embedded_window_close_page (GncEmbeddedWindow *window,
GncPluginPage *page)
@@ -157,6 +183,8 @@
LEAVE(" ");
}
+
+/* Retrieve the plugin that is embedded in the specified window. */
GncPluginPage *
gnc_embedded_window_get_page (GncEmbeddedWindow *window)
{
@@ -167,6 +195,12 @@
}
+/** Initialize the class for a new gnucash embedded window. This will
+ * set up any function pointers that override functions in the parent
+ * class.
+ *
+ * @param klass The new class structure created by the object system.
+ */
static void
gnc_embedded_window_class_init (GncEmbeddedWindowClass *klass)
{
@@ -183,6 +217,15 @@
LEAVE(" ");
}
+
+/** Initialize a new instance of a gnucash embedded window. This
+ * function initializes the object private storage space. It also
+ * adds the new object to a list (for memory tracking purposes).
+ *
+ * @param view The new object instance created by the object system.
+ *
+ * @param klass A pointer to the class data structure for this
+ * object. */
static void
gnc_embedded_window_init (GncEmbeddedWindow *window,
GncEmbeddedWindowClass *klass)
@@ -196,6 +239,10 @@
LEAVE(" ");
}
+
+/** Finish destruction of an embedded window.
+ *
+ * @object The window being destroyed. */
static void
gnc_embedded_window_finalize (GObject *object)
{
@@ -214,6 +261,11 @@
LEAVE(" ");
}
+
+/** Begin destruction of an embedded window. This function should
+ * release all objects referenced by the window (i.e. the page).
+ *
+ * @object The window being destroyed. */
static void
gnc_embedded_window_dispose (GObject *object)
{
@@ -237,6 +289,7 @@
LEAVE(" ");
}
+
static void
gnc_embedded_window_add_widget (GtkUIManager *merge,
GtkWidget *widget,
@@ -247,7 +300,7 @@
ENTER("merge %p, new widget %p, window %p", merge, widget, window);
priv = GNC_EMBEDDED_WINDOW_GET_PRIVATE(window);
if (GTK_IS_TOOLBAR (widget)) {
- priv->toolbar_dock = widget;
+ priv->toolbar = widget;
}
gtk_box_pack_start (GTK_BOX (priv->menu_dock), widget, FALSE, FALSE, 0);
@@ -255,6 +308,10 @@
LEAVE(" ");
}
+
+/** Initialize the data structures of a gnucash embedded window.
+ *
+ * @param window The object to initialize. */
static void
gnc_embedded_window_setup_window (GncEmbeddedWindow *window)
{
@@ -283,6 +340,8 @@
LEAVE(" ");
}
+
+/** Create a new gnc embedded window plugin. */
GncEmbeddedWindow *
gnc_embedded_window_new (const gchar *action_group_name,
GtkActionEntry *action_entries,
@@ -340,6 +399,12 @@
return window;
}
+
+/** Retrieve the gtk window associated with an embedded window object.
+ * This function is called via a vector off a generic window
+ * interface.
+ *
+ * @param window_in A pointer to a generic window. */
static GtkWindow *
gnc_embedded_window_get_gtk_window (GncWindow *window_in)
{
@@ -353,6 +418,12 @@
return GTK_WINDOW(priv->parent_window);
}
+
+/** Retrieve the status bar associated with an embedded window object.
+ * This function is called via a vector off a generic window
+ * interface.
+ *
+ * @param window_in A pointer to a generic window. */
static GtkWidget *
gnc_embedded_window_get_statusbar (GncWindow *window_in)
{
@@ -366,6 +437,11 @@
return priv->statusbar;
}
+
+/** Initialize the generic window interface for an embedded window.
+ *
+ * @param iface A pointer to the interface data structure to
+ * populate. */
static void
gnc_window_embedded_window_init (GncWindowIface *iface)
{
Modified: gnucash/trunk/src/gnome-utils/gnc-embedded-window.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-embedded-window.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-embedded-window.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -1,6 +1,6 @@
/*
* gnc-embedded-window.h -- GtkWindow which represents an
- * emvedded GnuCash window.
+ * embedded GnuCash window.
*
* Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
* Copyright (C) 2003 David Hampton <hampton at employees.org>
@@ -51,32 +51,69 @@
#define GNC_EMBEDDED_WINDOW_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GNC_TYPE_EMBEDDED_WINDOW, GncEmbeddedWindowClass))
/* typedefs & structures */
+
+/** The instance data structure for an embedded window object. */
typedef struct {
+ /** The parent object for an embedded window. */
GtkVBox vbox;
- GtkUIManager *ui_merge;
+ /** A pointer to the UI Manager data structure for the whole
+ * window. */
+ GtkUIManager *ui_merge;
} GncEmbeddedWindow;
+
+/** The class data structure for an embedded window object. */
typedef struct {
+ /** The parent class for an embedded window. */
GtkVBoxClass vbox;
} GncEmbeddedWindowClass;
+
/* function prototypes */
-GType gnc_embedded_window_get_type (void);
-GncEmbeddedWindow * gnc_embedded_window_new (const gchar *action_group_name,
- GtkActionEntry *action_entries,
- gint n_action_entries,
- const gchar *ui_filename,
- GtkWidget *enclosing_win,
- gboolean add_accelerators,
- gpointer user_data);
+/** Get the type of a gnc embedded window.
+ *
+ * @return A GType. */
+GType gnc_embedded_window_get_type (void);
-void gnc_embedded_window_open_page (GncEmbeddedWindow *window,
- GncPluginPage *page);
-void gnc_embedded_window_close_page (GncEmbeddedWindow *window,
- GncPluginPage *page);
-GncPluginPage *gnc_embedded_window_get_page (GncEmbeddedWindow *window);
+/** Create a new gnc embedded window plugin.
+ *
+ * @return A pointer to the new object.
+ */
+GncEmbeddedWindow *gnc_embedded_window_new (const gchar *action_group_name,
+ GtkActionEntry *action_entries,
+ gint n_action_entries,
+ const gchar *ui_filename,
+ GtkWidget *enclosing_win,
+ gboolean add_accelerators,
+ gpointer user_data);
+
+
+/** Display a data plugin page in a window.
+ *
+ * @param window The window to display a new page in.
+ *
+ * @param page The new page of data to be displayed.
+ */
+void gnc_embedded_window_open_page (GncEmbeddedWindow *window,
+ GncPluginPage *page);
+
+
+/** Remove a data plugin page from a window.
+ *
+ * @param page The page of data to be removed. */
+void gnc_embedded_window_close_page (GncEmbeddedWindow *window,
+ GncPluginPage *page);
+
+
+/** Retrieve the plugin that is embedded in the specified window.
+ *
+ * @param window The window whose plugin is desired.
+ *
+ * @return A pointer to a GncPluginPage. */
+GncPluginPage *gnc_embedded_window_get_page (GncEmbeddedWindow *window);
+
G_END_DECLS
#endif /* __GNC_EMBEDDED_WINDOW_H */
Modified: gnucash/trunk/src/gnome-utils/gnc-main-window.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-main-window.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-main-window.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -67,6 +67,7 @@
#include "gnc-html.h"
#include <g-wrap-wct.h>
+/** Names of signals generated by the main window. */
enum {
PAGE_ADDED,
PAGE_CHANGED,
@@ -82,11 +83,19 @@
#define KEY_SHOW_CLOSE_BUTTON "tab_close_buttons"
-/** Static Globals *******************************************************/
+/* Static Globals *******************************************************/
+
+/** The debugging module that this .o belongs to. */
static QofLogModule log_module = GNC_MOD_GUI;
+/** A pointer to the parent class of an embedded window. */
+static GObjectClass *parent_class = NULL;
+/** An identifier that indicates a "main" window. */
+static GQuark window_type = 0;
+/** A list of all extant main windows. This is for convenience as the
+ * same information can be obtained from the object tracking code. */
static GList *active_windows = NULL;
-/** Declarations *********************************************************/
+/* Declarations *********************************************************/
static void gnc_main_window_class_init (GncMainWindowClass *klass);
static void gnc_main_window_init (GncMainWindow *window, GncMainWindowClass *klass);
static void gnc_main_window_finalize (GObject *object);
@@ -128,34 +137,71 @@
static GtkAction *gnc_main_window_find_action (GncMainWindow *window, const gchar *name);
+/** The instance private data structure for an embedded window
+ * object. */
typedef struct GncMainWindowPrivate
{
+ /** The dock (vbox) at the top of the window containing the
+ * menubar and toolbar. These items are generated bu the UI
+ * manager and stored here when the UI manager provides them
+ * to the main window. */
GtkWidget *menu_dock;
- GtkWidget *toolbar_dock;
+ /* The toolbar created by the UI manager. This pointer
+ * provides easy access for showing/hiding the toolbar. */
+ GtkWidget *toolbar;
+ /** The notebook containing all the pages in this window. */
GtkWidget *notebook;
+ /** A pointer to the status bar at the bottom edge of the
+ * window. This pointer provides easy access for
+ * updating/showing/hiding the status bar. */
GtkWidget *statusbar;
+ /** A pointer to the progress bar at the bottom right of the
+ * window that is contained in the status bar. This pointer
+ * provides easy access for updating the progressbar. */
GtkWidget *progressbar;
+ /** The group of all actions provided by the main window
+ * itself. This does not include any action provided by menu
+ * or content plugins. */
GtkActionGroup *action_group;
+ /** A list of all pages that are installed in this window. */
+ GList *installed_pages;
+ /** The currently selected page. */
GncPluginPage *current_page;
- GList *installed_pages;
+ /** The identifier for this window's engine event handler. */
gint event_handler_id;
-
+ /** A hash table of all action groups that have been installed
+ * into this window. The keys are the name of an action
+ * group, the values are structures of type
+ * MergedActionEntry. */
GHashTable *merged_actions_table;
} GncMainWindowPrivate;
#define GNC_MAIN_WINDOW_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_MAIN_WINDOW, GncMainWindowPrivate))
+/** This data structure maintains information about one action groups
+ * that has been installed in this window. */
typedef struct {
+ /** The merge identifier for this action group. This number
+ * is provided by the UI manager. */
guint merge_id;
+ /** The action group itself. This contains all actions added
+ * by a single menu or content plugin. */
GtkActionGroup *action_group;
} MergedActionEntry;
+/** A holding place for all the signals generated by the main window
+ * code. */
static guint main_window_signals[LAST_SIGNAL] = { 0 };
+
+/** An array of all of the actions provided by the main window code.
+ * This includes some placeholder actions for the menus that are
+ * visible in the menu bar but have no action associated with
+ * them. */
static GtkActionEntry gnc_menu_actions [] =
{
/* Toplevel */
@@ -241,8 +287,11 @@
N_("Testing stuff"), G_CALLBACK (gnc_main_window_cmd_test) },
};
+/** The number of actions provided by the main window. */
static guint gnc_menu_n_actions = G_N_ELEMENTS (gnc_menu_actions);
+/** An array of all of the toggle action provided by the main window
+ * code. */
static GtkToggleActionEntry toggle_actions [] =
{
{ "ViewToolbarAction", NULL, N_("_Toolbar"), NULL,
@@ -255,8 +304,11 @@
N_("Show/hide the status bar on this window"),
G_CALLBACK (gnc_main_window_cmd_view_statusbar), TRUE },
};
+/** The number of toggle actions provided by the main window. */
static guint n_toggle_actions = G_N_ELEMENTS (toggle_actions);
+/** An array of all of the radio action provided by the main window
+ * code. */
static GtkRadioActionEntry radio_entries [] =
{
{ "Window0Action", NULL, N_("Window _1"), NULL, NULL, 0 },
@@ -270,14 +322,19 @@
{ "Window8Action", NULL, N_("Window _9"), NULL, NULL, 8 },
{ "Window9Action", NULL, N_("Window _0"), NULL, NULL, 9 },
};
+/** The number of radio actions provided by the main window. */
static guint n_radio_entries = G_N_ELEMENTS (radio_entries);
+/** These are the "important" actions provided by the main window.
+ * Their labels will appear when the toolbar is set to "Icons and
+ * important text" (e.g. GTK_TOOLBAR_BOTH_HORIZ) mode. */
static const gchar *gnc_menu_important_actions[] = {
"FileCloseAction",
NULL,
};
+
/** The following are in the main window so they will always be
* present in the menu structure, but they are never sensitive.
* These actions should be overridden in child windows where they
@@ -290,13 +347,15 @@
NULL
};
+
/** If a page is flagged as immutable, then the following actions
- * cannot be peformed on that page. */
+ * cannot be performed on that page. */
static const gchar *immutable_page_actions[] = {
"FileCloseAction",
NULL
};
+
/** The following actions can only be performed if there are multiple
* pages in a window. */
static const gchar *multiple_page_actions[] = {
@@ -304,10 +363,7 @@
NULL
};
-static GObjectClass *parent_class = NULL;
-static GQuark window_type = 0;
-
/************************************************************
* *
************************************************************/
@@ -848,7 +904,7 @@
* According to the HIG, the secondary context should include
* context about the number of changes that will be lost (either in
* time or a count). While it is possible to simply provide the
- * time since the last save, that doesn't appear too usefule. If
+ * time since the last save, that doesn't appear too useful. If
* the user has had Gnucash open for hours in the background, but
* only made a change in the last few minutes, then telling them
* they will lose hours work of work is wring. The QOF code needs
@@ -1264,7 +1320,7 @@
/** Show/hide the close box on the tab of a notebook page. This
* function first checks to see if the specified page has a close
- * box, and if so, sets its isibility to the requested state.
+ * box, and if so, sets its visibility to the requested state.
*
* @internal
*
@@ -1508,14 +1564,12 @@
}
-/** Initialize the class for the new gnucash main window. This will
- * set up any function pointers that override functions in the parent
- * class, and also the signals that this class of widget can
- * generate.
+/** Initialize the class for a new gnucash main window. This will set
+ * up any function pointers that override functions in the parent
+ * class, and also initialize the signals that this class of widget
+ * can generate.
*
* @param klass The new class structure created by the object system.
- *
- * @internal
*/
static void
gnc_main_window_class_init (GncMainWindowClass *klass)
@@ -1587,13 +1641,13 @@
/** Initialize a new instance of a gnucash main window. This function
- * allocates and initializes the object private storage space. It
- * also adds the new object to a list (for memory tracking purposes).
+ * initializes the object private storage space. It also adds the
+ * new object to a list (for memory tracking purposes).
*
* @param view The new object instance created by the object system.
*
- * @internal
- */
+ * @param klass A pointer to the class data structure for this
+ * object. */
static void
gnc_main_window_init (GncMainWindow *window,
GncMainWindowClass *klass)
@@ -1706,21 +1760,19 @@
/** Connect a GncPluginPage to the window. This function will insert
* the page in to the window's notebook and its list of active pages.
* It will also emit the "inserted" signal on the page, and the
- * "add_page" signal on the window. This function does not connect
- * the page's summarybar widget (if any). That will be connected in
- * a callback function generated by the page being inserted into the
- * notebook.
+ * "add_page" signal on the window.
*
* @param window The window where the new page should be added.
*
* @param page The GncPluginPage that should be added to the window.
* The visible widget for this plugin must have already been created.
*
- * @param tab_widget The widget that should be added into the
- * notebook tab for this page. Generally this is a GtkLabel, but
- * could also be a GtkHBox containing an icon and a label.
+ * @param tab_hbox The widget that should be added into the notebook
+ * tab for this page. Generally this is a GtkLabel, but could also
+ * be a GtkHBox containing an icon and a label.
*
- * @internal
+ * @param menu_label The widget that should be added into the
+ * notebook popup menu for this page. This should be a GtkLabel.
*/
static void
gnc_main_window_connect (GncMainWindow *window,
@@ -1998,8 +2050,8 @@
/* Manually add a set of actions to the specified window. Plugins
- * whose user interface is not hard coded (e.g. the menu-additions *
- * plugin) must create their actions at run time, then use this *
+ * whose user interface is not hard coded (e.g. the menu-additions
+ * plugin) must create their actions at run time, then use this
* function to install them into the window.
*/
void
@@ -2362,7 +2414,7 @@
priv = GNC_MAIN_WINDOW_GET_PRIVATE(window);
if (GTK_IS_TOOLBAR (widget)) {
- priv->toolbar_dock = widget;
+ priv->toolbar = widget;
}
gtk_box_pack_start (GTK_BOX (priv->menu_dock), widget, FALSE, FALSE, 0);
@@ -2372,7 +2424,7 @@
/** Should a summary bar be visible in this window? In order to
* prevent synchronization issues, the "ViewSummaryBar"
* GtkToggleAction is the sole source of information for whether or
- * not any summary bar should be visibile in a window.
+ * not any summary bar should be visible in a window.
*
* @param window A pointer to the window in question.
*
@@ -2519,7 +2571,7 @@
session = qof_session_get_current_session();
if (qof_book_not_saved(qof_session_get_book(session))) {
if (gnc_main_window_prompt_for_save(GTK_WIDGET(window))) {
- /* User cancelled */
+ /* User canceled */
return;
}
}
@@ -2588,9 +2640,9 @@
priv = GNC_MAIN_WINDOW_GET_PRIVATE(window);
if (gtk_toggle_action_get_active(GTK_TOGGLE_ACTION(action))) {
- gtk_widget_show (priv->toolbar_dock);
+ gtk_widget_show (priv->toolbar);
} else {
- gtk_widget_hide (priv->toolbar_dock);
+ gtk_widget_hide (priv->toolbar);
}
}
@@ -2715,8 +2767,12 @@
{
GtkWindow *w = GTK_WINDOW(gtk_window_new( GTK_WINDOW_TOPLEVEL ));
gnc_html *gnchtml = gnc_html_new( w );
- gchar *html = "<html><head><title>testing</title></head><body><h1>testing</h1><h2>testing 2</h2> <p>Tes<br />ting<object classid=\"gnc-guppi-pie\" width=\"300\" height=\"200\">No pie for you!</object></p></body></html>";
- gtk_container_add( GTK_CONTAINER(w), GTK_WIDGET(gnc_html_get_widget(gnchtml)) );
+ gchar *html = "<html><head><title>testing</title></head>"
+ "<body><h1>testing</h1><h2>testing 2</h2> <p>Tes<br />ting"
+ "<object classid=\"gnc-guppi-pie\" width=\"300\" height=\"200\">"
+ "No pie for you!</object></p></body></html>";
+ gtk_container_add( GTK_CONTAINER(w),
+ GTK_WIDGET(gnc_html_get_widget(gnchtml)) );
gnc_html_show_data( gnchtml, html, strlen( html ) );
@@ -2765,6 +2821,10 @@
* *
************************************************************/
+/** Get a pointer to a top level window... any top level window. This
+ * function just returns a pointer to the first window.
+ *
+ * @return A pointer to a GtkWindow object. */
gncUIWidget
gnc_ui_get_toplevel (void)
{
@@ -2773,6 +2833,12 @@
return NULL;
}
+
+/** Retrieve the gtk window associated with a main window object.
+ * This function is called via a vector off a generic window
+ * interface.
+ *
+ * @param window_in A pointer to a generic window. */
static GtkWindow *
gnc_main_window_get_gtk_window (GncWindow *window)
{
@@ -2780,6 +2846,12 @@
return GTK_WINDOW(window);
}
+
+/** Retrieve the status bar associated with a main window object.
+ * This function is called via a vector off a generic window
+ * interface.
+ *
+ * @param window_in A pointer to a generic window. */
static GtkWidget *
gnc_main_window_get_statusbar (GncWindow *window_in)
{
@@ -2793,6 +2865,12 @@
return priv->statusbar;
}
+
+/** Retrieve the progress bar associated with a main window object.
+ * This function is called via a vector off a generic window
+ * interface.
+ *
+ * @param window_in A pointer to a generic window. */
static GtkWidget *
gnc_main_window_get_progressbar (GncWindow *window_in)
{
@@ -2806,6 +2884,11 @@
return priv->progressbar;
}
+
+/** Initialize the generic window interface for a main window.
+ *
+ * @param iface A pointer to the interface data structure to
+ * populate. */
static void
gnc_window_main_window_init (GncWindowIface *iface)
{
Modified: gnucash/trunk/src/gnome-utils/gnc-main-window.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-main-window.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-main-window.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -51,13 +51,18 @@
#define GNC_MAIN_WINDOW_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GNC_TYPE_MAIN_WINDOW, GncMainWindowClass))
/* typedefs & structures */
+
+/** The instance data structure for a main window object. */
typedef struct GncMainWindow {
- GtkWindow gtk_window;
- GtkUIManager *ui_merge;
+ GtkWindow gtk_window; /**< The parent object for a main window. */
+ GtkUIManager *ui_merge; /**< A pointer to the UI Manager data
+ structure for the whole window. */
} GncMainWindow;
+/** The class data structure for a main window object. */
typedef struct {
- GtkWindowClass gtk_window;
+ GtkWindowClass gtk_window; /**< The parent class for a
+ main window. */
/* callbacks */
void (*page_added) (GncMainWindow *window,
@@ -177,7 +182,7 @@
* should be unique among all groups added to the window, and will be
* needed to remove the actions from this window.
*
- * @param entries A pointer to an array of GtkActionEntries. These
+ * @param entries A pointer to an array of GtkActionEntry. These
* are the actions that will be added to the user interface.
*
* @param n_entries The number of actions in the array.
@@ -254,7 +259,7 @@
* any Gnucash window. If this was a "right-click" then Gnucash will
* popup the contextual menu.
*
- * @param widget Whatever widget had focus when the user issued the
+ * @param whatever Whatever widget had focus when the user issued the
* keyboard context-menu request.
*
* @param event The event parameter describing where on the screen
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin-file-history.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin-file-history.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin-file-history.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -24,9 +24,8 @@
@{ */
/** @addtogroup PluginFileHistory File History Menu Items
@{ */
-/** @internal
- @file gnc-plugin-file-history.c
- @brief Utility functions for writing import modules.
+/** @file gnc-plugin-file-history.c
+ @brief Functions providing the file history menu.
@author Copyright (C) 2003,2005 David Hampton <hampton at employees.org>
*/
@@ -55,15 +54,25 @@
static void gnc_plugin_file_history_add_to_window (GncPlugin *plugin, GncMainWindow *window, GQuark type);
static void gnc_plugin_file_history_remove_from_window (GncPlugin *plugin, GncMainWindow *window, GQuark type);
+
+/** The debugging module used by this file. */
static QofLogModule log_module = GNC_MOD_GUI;
/* Command callbacks */
static void gnc_plugin_file_history_cmd_open_file (GtkAction *action, GncMainWindowActionData *data);
+/** The label given to the main window for this plugin. */
#define PLUGIN_ACTIONS_NAME "gnc-plugin-file-history-actions"
+/** The name of the UI description file for this plugin. */
#define PLUGIN_UI_FILENAME "gnc-plugin-file-history-ui.xml"
+
+/** A placeholder set of actions that are filled in by this plugin.
+ * As the user opens files, the names and visibility of these actions
+ * will be updated to reflect the users recent choices. This list is
+ * limited to ten actions, although there may be a smaller limit set
+ * by the user. The typical limit is four. */
static GtkActionEntry gnc_plugin_actions [] = {
{ "RecentFile0Action", NULL, "", NULL, NULL, G_CALLBACK (gnc_plugin_file_history_cmd_open_file) },
{ "RecentFile1Action", NULL, "", NULL, NULL, G_CALLBACK (gnc_plugin_file_history_cmd_open_file) },
@@ -76,14 +85,18 @@
{ "RecentFile8Action", NULL, "", NULL, NULL, G_CALLBACK (gnc_plugin_file_history_cmd_open_file) },
{ "RecentFile9Action", NULL, "", NULL, NULL, G_CALLBACK (gnc_plugin_file_history_cmd_open_file) },
};
+/** The number of actions provided by this plugin. */
static guint gnc_plugin_n_actions = G_N_ELEMENTS (gnc_plugin_actions);
+/** The instance private data for a file history plugin. This data
+ * structure is unused. */
typedef struct GncPluginFileHistoryPrivate
{
gpointer dummy;
} GncPluginFileHistoryPrivate;
+
#define GNC_PLUGIN_FILE_HISTORY_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_PLUGIN_FILE_HISTORY, GncPluginFileHistoryPrivate))
@@ -91,6 +104,45 @@
* Other Functions *
************************************************************/
+/** Convert an array index into a gconf key string.
+ *
+ * @param index An index number that can be used with the
+ * gnc_plugin_actions array.
+ *
+ * @return The partial gconf key associated with this array entry. It
+ * is the callers responsibility to free this string when
+ * finished. */
+static gchar *
+gnc_history_gconf_index_to_key (guint index)
+{
+ return g_strdup_printf(HISTORY_STRING_FILE_N, index);
+}
+
+
+/** Convert a gconf key string into an array index. This function
+ * uses sscanf to pull the number off the end of the key and convert
+ * it to an integer.
+ *
+ * @param fullkey The full gconf key starting with "/apps/...".
+ *
+ * @return An index number that can be used with the
+ * gnc_plugin_actions array. */
+static gint
+gnc_history_gconf_key_to_index (const gchar *fullkey)
+{
+ char *key;
+ gint index, result;
+
+ key = rindex(fullkey, '/');
+ result = sscanf(key+1, HISTORY_STRING_FILE_N, &index);
+ if (result != 1)
+ return -1;
+ if ((index < 0) || (index >= gnc_plugin_n_actions))
+ return -1;
+ return index;
+}
+
+
/* Add a file name to the front of the file "history list". If the
* name already exist on the list, then it is moved from its current
* location to the front of the list. The "list" is actually a
@@ -112,7 +164,7 @@
*/
last = MAX_HISTORY_FILES - 1;
for (i = 0; i < MAX_HISTORY_FILES; i++) {
- from = g_strdup_printf(HISTORY_STRING_FILE_N, i);
+ from = gnc_history_gconf_index_to_key(i);
filename = gnc_gconf_get_string(HISTORY_STRING_SECTION, from, NULL);
g_free(from);
@@ -131,9 +183,9 @@
/*
* Shuffle filenames upward through gconf.
*/
- to = g_strdup_printf(HISTORY_STRING_FILE_N, last);
+ to = gnc_history_gconf_index_to_key(last);
for (i = last - 1; i >= 0; i--) {
- from = g_strdup_printf(HISTORY_STRING_FILE_N, i);
+ from = gnc_history_gconf_index_to_key(i);
filename = gnc_gconf_get_string(HISTORY_STRING_SECTION, from, NULL);
if (filename) {
gnc_gconf_set_string(HISTORY_STRING_SECTION, to, filename, NULL);
@@ -161,7 +213,7 @@
{
char *filename, *key;
- key = g_strdup_printf(HISTORY_STRING_FILE_N, 0);
+ key = gnc_history_gconf_index_to_key(0);
filename = gnc_gconf_get_string(HISTORY_STRING_SECTION, key, NULL);
g_free(key);
@@ -173,32 +225,11 @@
* Other Functions *
************************************************************/
-#if 0
-static gchar *
-gnc_history_gconf_index_to_key (guint index)
-{
- return g_strdup_printf(HISTORY_STRING_FILE_N, index);
-}
-#endif
-
-
-static gint
-gnc_history_gconf_key_to_index (const gchar *fullkey)
-{
- char *key;
- gint index, result;
-
- key = rindex(fullkey, '/');
- result = sscanf(key+1, HISTORY_STRING_FILE_N, &index);
- return (result == 1) ? index : -1;
-}
-
-
/** This routine takes a filename and modifies it so that it will
- * display correctly in a GtkLabel. It also adds a mnemonic to
- * the start of the menu item.
+ * display correctly in a GtkLabel. It also adds a mnemonic to the
+ * start of the menu item.
*
- * @filename A pointer to the filename to mangle.
+ * @param filename A pointer to the filename to mangle.
*
* @return A pointer to the mangled filename. The Caller is
* responsible for freeing this memory.
@@ -246,11 +277,12 @@
* filename so that it will display correctly in the menu, and also
* add a mnemonic for the menu item.
*
- * @window A pointer to window whose file history should be updated.
+ * @param window A pointer to window whose file history should be
+ * updated.
*
- * @index Update this item in the menu (base-0).
+ * @param index Update this item in the menu (base-0).
*
- * @filename The new filename to associate with this menu item.
+ * @param filename The new filename to associate with this menu item.
*/
static void
gnc_history_update_action (GncMainWindow *window,
@@ -293,20 +325,21 @@
* history section is changed. It is responsible for updating the
* menu item that corresponds to that key.
*
- * @client A pointer to gconf client that noticed an entry change.
+ * @param client A pointer to gconf client that noticed an entry
+ * change.
*
- * @cnxn_id Unused.
+ * @param cnxn_id Unused.
*
- * @entry A pointer to gconf entry that changed.
+ * @param entry A pointer to gconf entry that changed.
*
- * @user_data A pointer to the window that this gconf client is
+ * @param user_data A pointer to the window that this gconf client is
* associated with.
*/
static void
gnc_plugin_history_list_changed (GConfClient *client,
guint cnxn_id,
GConfEntry *entry,
- gpointer user_data)
+ gpointer user_data)
{
GncMainWindow *window;
GConfValue *value;
@@ -337,8 +370,8 @@
* forces a read/menu update on each key. It should only be called
* once when the window is created.
*
- * @window A pointer to the window whose file history menu should be
- * updated.
+ * @param window A pointer to the window whose file history menu
+ * should be updated.
*/
static void
gnc_history_update_menus (GncMainWindow *window)
@@ -348,7 +381,7 @@
ENTER("");
for (i = 0; i < MAX_HISTORY_FILES; i++) {
- key = g_strdup_printf(HISTORY_STRING_FILE_N, i);
+ key = gnc_history_gconf_index_to_key(i);
filename = gnc_gconf_get_string(HISTORY_STRING_SECTION, key, NULL);
gnc_history_update_action(window, i, filename);
g_free(filename);
@@ -362,8 +395,7 @@
* Object Implementation *
************************************************************/
-/* Get the type of a file history plugin.
- */
+/* Get the type of a file history plugin. */
GType
gnc_plugin_file_history_get_type (void)
{
@@ -382,14 +414,17 @@
(GInstanceInitFunc) gnc_plugin_file_history_init
};
- gnc_plugin_file_history_type = g_type_register_static (GNC_TYPE_PLUGIN,
- "GncPluginFileHistory",
- &our_info, 0);
+ gnc_plugin_file_history_type =
+ g_type_register_static (GNC_TYPE_PLUGIN,
+ "GncPluginFileHistory",
+ &our_info, 0);
}
return gnc_plugin_file_history_type;
}
+
+/** Initialize the file history plugin class. */
static void
gnc_plugin_file_history_class_init (GncPluginFileHistoryClass *klass)
{
@@ -405,7 +440,8 @@
/* function overrides */
plugin_class->add_to_window = gnc_plugin_file_history_add_to_window;
- plugin_class->remove_from_window = gnc_plugin_file_history_remove_from_window;
+ plugin_class->remove_from_window =
+ gnc_plugin_file_history_remove_from_window;
/* widget addition/removal */
plugin_class->actions_name = PLUGIN_ACTIONS_NAME;
@@ -419,6 +455,8 @@
g_type_class_add_private(klass, sizeof(GncPluginFileHistoryPrivate));
}
+
+/** Initialize an instance of the file history plugin. */
static void
gnc_plugin_file_history_init (GncPluginFileHistory *plugin)
{
@@ -426,6 +464,8 @@
LEAVE("");
}
+
+/** Finalize an instance of the file history plugin. */
static void
gnc_plugin_file_history_finalize (GObject *object)
{
@@ -468,7 +508,7 @@
* first calling a function that initializes the menu to the current
* as maintained in gconf. It then creates a gconf client that will
* listens for any changes to the file history menu, and will update
- * the meny when they are signalled.
+ * the menu when they are signaled.
*
* @param plugin A pointer to the gnc-plugin object responsible for
* adding/removing the file history menu.
@@ -531,7 +571,7 @@
g_return_if_fail(data != NULL);
/* DRH - Do we need to close all open windows but the first?
- * Which progressbar should we be using? One in a window, or
+ * Which progress bar should we be using? One in a window, or
* in a new "file loading" dialog???
*/
filename = g_object_get_data(G_OBJECT(action), FILENAME_STRING);
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin-file-history.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin-file-history.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin-file-history.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -25,8 +25,11 @@
/** @addtogroup PluginFileHistory File History Menu Items
@{ */
/** @file gnc-plugin-file-history.h
- @brief Utility functions for writing import modules.
+ @brief Functions providing the file history menu.
@author Copyright (C) 2003,2005 David Hampton <hampton at employees.org>
+
+ This plugin handles the file history information that appears in
+ the application menus.
*/
#ifndef __GNC_PLUGIN_FILE_HISTORY_H
@@ -52,10 +55,14 @@
#define HISTORY_STRING_FILE_N "file%d"
/* typedefs & structures */
+
+/** The instance data structure for a file history plugin. */
typedef struct {
GncPlugin gnc_plugin;
} GncPluginFileHistory;
+
+/** The class data structure for a file history plugin. */
typedef struct {
GncPluginClass gnc_plugin;
} GncPluginFileHistoryClass;
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin-manager.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin-manager.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin-manager.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -30,11 +30,11 @@
@brief Plugin management functions for the GnuCash UI
@author Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
- The plugin manager maintains a list of all plugins that have been
- instantiated by various parts of Gnucash. The manager will
- provide this list upon request, it will also look up individual
- plugins on request. The main client of this manager is the main
- gnucash window code. All plugins registered here will
+ The plugin manager maintains a list of all non-content plugins
+ that have been instantiated by various parts of Gnucash. The
+ manager will provide this list upon request, it will also look up
+ individual plugins on request. The main client of this manager is
+ the main gnucash window code. All plugins registered here will
automatically be installed in each top level gnucash window that
is created.
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin-menu-additions.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin-menu-additions.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin-menu-additions.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -28,10 +28,9 @@
@{ */
/** @addtogroup PluginMenuAdditions Non-GtkAction Menu Support
@{ */
-/** @internal
- @file gnc-plugin-menu-additions.c
- @brief Utility functions for writing import modules.
- @author Copyright (C) 2002 David Hampton <hampton at employees.org>
+/** @file gnc-plugin-menu-additions.c
+ @brief Functions providing menu items from scheme code.
+ @author Copyright (C) 2005 David Hampton <hampton at employees.org>
*/
#include "config.h"
@@ -69,6 +68,7 @@
#define PLUGIN_ACTIONS_NAME "gnc-plugin-menu-additions-actions"
+/** Private data for this plugin. This data structure is unused. */
typedef struct GncPluginMenuAdditionsPrivate
{
gpointer dummy;
@@ -77,8 +77,14 @@
#define GNC_PLUGIN_MENU_ADDITIONS_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_PLUGIN_MENU_ADDITIONS, GncPluginMenuAdditionsPrivate))
+
+/** Per-window private data for this plugin. This plugin is unique in
+ * that it manages its own menu items. */
typedef struct _GncPluginMenuAdditionsPerWindow
{
+ /** The menu/toolbar action information associated with a specific
+ window. This plugin must maintain its own data because of the
+ way the menus are currently built. */
GncMainWindow *window;
GtkUIManager *ui_manager;
GtkActionGroup *group;
@@ -158,6 +164,12 @@
LEAVE("");
}
+
+/* Create a new menu_additions plugin. This plugin attaches the menu
+ * items from Scheme code to any window that is opened.
+ *
+ * @return A pointer to the new object.
+ */
GncPlugin *
gnc_plugin_menu_additions_new (void)
{
@@ -193,17 +205,17 @@
return gw_wcp_assimilate_ptr ((void *)window, main_window_type);
}
-/** The user has selected one of the items in the File History menu.
- * Close down the current session and start up a new one with the
- * requested file.
+
+/** The user has selected one of the items added by this plugin.
+ * Invoke the callback function that was registered along with the
+ * menu item.
*
* @param action A pointer to the action selected by the user. This
* action represents one of the items in the file history menu.
*
* @param data A pointer to the gnc-main-window data to be used by
* this function. This is mainly to find out which window it was
- * that had a menu selected. That's not really important for this
- * function and we're about to close all the windows anyway.
+ * that had a menu selected.
*/
static void
gnc_plugin_menu_additions_action_cb (GtkAction *action,
@@ -216,12 +228,34 @@
gnc_extension_invoke_cb(data->data, gnc_main_window_to_scm(data->window));
}
+
+/** Compare two extension menu item and indicate which should appear
+ * first in the menu listings. The strings being compared are
+ * collation keys produced by g_utf8_collate_key(), so this function
+ * doesn't have to be anything more than a wrapper around strcmp,
+ *
+ * @param a A menu extension.
+ *
+ * @param b A second menu extension.
+ *
+ * @return -1 if extension 'a' should appear first. 1 if extension
+ * 'b' should appear first. */
static gint
gnc_menu_additions_alpha_sort (ExtensionInfo *a, ExtensionInfo *b)
{
return strcmp(a->sort_key, b->sort_key);
}
+
+/** Add one extension item to the UI manager. This function creates a
+ * per-callback data structure for easy access to the opaque Scheme
+ * data block in the callback. It then adds the action to the UI
+ * manager.
+ *
+ * @param ext_info The extension info data block.
+ *
+ * @param per_window The per-window data block maintained by the
+ * plugin. */
static void
gnc_menu_additions_menu_setup_one (ExtensionInfo *ext_info,
GncPluginMenuAdditionsPerWindow *per_window)
@@ -246,15 +280,16 @@
gtk_ui_manager_ensure_update(per_window->ui_manager);
}
+
/** Initialize the report menu and other additional menus. This
- * function is called as part of the initialization of a window,
- * after all the plugin menu items have been added to the menu
- * structure.
+ * function is called as part of the initialization of a window, when
+ * the plugin menu items are being added to the menu structure.
*
* @param plugin A pointer to the gnc-plugin object responsible for
- * adding/removing the file history menu.
+ * adding/removing the additional menu items.
*
- * @param window A pointer the gnc-main-window that is being initialized.
+ * @param window A pointer the gnc-main-window where this plugin
+ * should add its actions.
*
* @param type Unused
*/
@@ -289,13 +324,12 @@
}
-/** Finalize the file history menu for this window. This function is
- * called as part of the destruction of a window.
+/** Tear down the report menu and other additional menus. This
+ * function is called as part of the cleanup of a window, while the
+ * plugin menu items are being removed from the menu structure.
*
* @param plugin A pointer to the gnc-plugin object responsible for
- * adding/removing the file history menu. It stops the gconf
- * notifications for this window, and destroys the gconf client
- * object.
+ * adding/removing the additional menu items.
*
* @param window A pointer the gnc-main-window that is being destroyed.
*
@@ -316,6 +350,10 @@
if (group)
gtk_ui_manager_remove_action_group(window->ui_merge, group);
+ /* Note: This code does not clean up the per-callback data structures
+ * that are created by the gnc_menu_additions_menu_setup_one()
+ * function. Its not much memory and shouldn't be a problem. */
+
LEAVE(" ");
}
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin-menu-additions.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin-menu-additions.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin-menu-additions.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -25,8 +25,14 @@
/** @addtogroup PluginMenuAdditions Non-GtkAction Menu Support
@{ */
/** @file gnc-plugin-menu-additions.h
- @brief Utility functions for writing import modules.
- @author Copyright (C) 2002 David Hampton <hampton at employees.org>
+ @brief Functions providing menu items from scheme code.
+ @author Copyright (C) 2005 David Hampton <hampton at employees.org>
+
+ The GncPluginMenuAdditions code handles menu/toolbar actions that
+ come from the Scheme side of Gnucash. It is responsible for
+ adding these actions to any new window that is opened. This code
+ does not use the base object code to automatically handle these
+ functions, but performs them manually.
*/
#ifndef __GNC_PLUGIN_MENU_ADDITIONS_H
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin-page.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin-page.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin-page.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -27,7 +27,7 @@
/** @addtogroup ContentPluginBase Common object and functions
@{ */
/** @file gnc-plugin-page.c
- @brief Functions for adding plugins to a Gnucash window.
+ @brief Functions for adding plugins to a GnuCash window.
@author Copyright (C) 2003 Jan Arne Petersen
@author Copyright (C) 2003,2005 David Hampton <hampton at employees.org>
*/
@@ -41,11 +41,11 @@
#include "gnc-plugin-page.h"
#include "gnc-gobject-utils.h"
-/* This static indicates the debugging module that this .o belongs to. */
+/** The debugging module that this .o belongs to. */
static QofLogModule log_module = GNC_MOD_GUI;
+/** A pointer to the parent class of a plugin page. */
+static gpointer parent_class = NULL;
-static gpointer parent_class = NULL;
-
static void gnc_plugin_page_class_init (GncPluginPageClass *klass);
static void gnc_plugin_page_init (GncPluginPage *plugin_page,
GncPluginPageClass *klass);
@@ -81,10 +81,11 @@
static guint signals[LAST_SIGNAL] = { 0 };
-typedef struct _GncPluginPagePrivate GncPluginPagePrivate;
-struct _GncPluginPagePrivate
+/** The instance private data for a content plugin. */
+typedef struct _GncPluginPagePrivate
{
+ /** The group of all actions provided by this plugin. */
GtkActionGroup *action_group;
GtkUIManager *ui_merge;
guint merge_id;
@@ -97,7 +98,7 @@
gchar *page_name;
gchar *uri;
gchar *statusbar_text;
-};
+} GncPluginPagePrivate;
#define GNC_PLUGIN_PAGE_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_PLUGIN_PAGE, GncPluginPagePrivate))
@@ -129,6 +130,12 @@
return gnc_plugin_page_type;
}
+
+/* Create the display widget that corresponds to this plugin. This
+ * function will be called by the main/embedded window manipulation
+ * code to create a widget that they can display. The returned
+ * widget should encompass all information that goes with this page,
+ * including scroll bars, a summary bar, etc. */
GtkWidget *
gnc_plugin_page_create_widget (GncPluginPage *plugin_page)
{
@@ -155,6 +162,10 @@
return widget;
}
+
+/* Destroy the display widget that corresponds to this plugin. This
+ * function will be called by the main/embedded window manipulation
+ * code when a page is closed. */
void
gnc_plugin_page_destroy_widget (GncPluginPage *plugin_page)
{
@@ -169,6 +180,8 @@
return klass->destroy_widget (plugin_page);
}
+
+/* Show/hide the summarybar associated with this page. */
void
gnc_plugin_page_show_summarybar (GncPluginPage *page,
gboolean visible)
@@ -186,16 +199,10 @@
}
-/** Call a plugin specific function to save enough information about
- * this page that it can be recreated next time the user starts
- * gnucash.
- *
- * @param page The page to save.
- *
- * @param key_file A pointer to the GKeyFile data structure where the
- * page information should be written.
- *
- * @param group_name The group name to use when saving data. */
+/* Call the plugin specific function that will save the state of a
+ * content page to a disk. That function must save enough
+ * information about the page that it can be recreated next time the
+ * user starts gnucash. */
void
gnc_plugin_page_save_page (GncPluginPage *page,
GKeyFile *key_file,
@@ -217,17 +224,9 @@
}
-/** This function looks up a specific plugin type and then calls its
- * function to create a new page.
- *
- * @param window The window where this page should be installed.
- *
- * @param page_type The name of the page type to create.
- *
- * @param key_file A pointer to the GKeyFile data structure where the
- * page information should be read.
- *
- * @param group_name The group name to use when restoring data. */
+/* This function looks up a specific plugin type by name, and then
+ * calls a plugin specific function to create a new page and restore
+ * its content to a previous state. */
GncPluginPage *
gnc_plugin_page_recreate_page(GtkWidget *window,
const gchar *page_type,
@@ -263,6 +262,8 @@
return page;
}
+
+/* Add the actions for a content page to the specified window. */
void
gnc_plugin_page_merge_actions (GncPluginPage *page,
GtkUIManager *ui_merge)
@@ -278,6 +279,8 @@
priv->ui_description);
}
+
+/* Remove the actions for a content page from the specified window. */
void
gnc_plugin_page_unmerge_actions (GncPluginPage *page,
GtkUIManager *ui_merge)
@@ -297,6 +300,8 @@
priv->merge_id = 0;
}
+
+/* Retrieve the textual name of a plugin. */
const gchar *
gnc_plugin_page_get_plugin_name (GncPluginPage *plugin_page)
{
@@ -344,6 +349,14 @@
g_signal_emit (G_OBJECT (plugin_page), signals[UNSELECTED], 0);
}
+
+/** Initialize the class for a new generic plugin page. This will set
+ * up any function pointers that override functions in the parent
+ * class, set up all properties and signals, and also configure the
+ * private data storage for this widget.
+ *
+ * @param klass The new class structure created by the object system.
+ */
static void
gnc_plugin_page_class_init (GncPluginPageClass *klass)
{
@@ -469,6 +482,15 @@
0);
}
+
+/** Initialize a new instance of a gnucash content plugin. This
+ * function initializes the object private storage space, and adds
+ * the object to the tracking system.
+ *
+ * @param page The new object instance created by the object system.
+ *
+ * @param klass A pointer to the class data structure for this
+ * object. */
static void
gnc_plugin_page_init (GncPluginPage *page, GncPluginPageClass *klass)
{
@@ -484,6 +506,14 @@
gnc_gobject_tracking_remember(G_OBJECT(page), G_OBJECT_CLASS(klass));
}
+
+/** Finalize the gnucash plugin object. This function is called from
+ * the G_Object level to complete the destruction of the object. It
+ * should release any memory not previously released by the destroy
+ * function (i.e. the private data structure), then chain up to the
+ * parent's destroy function.
+ *
+ * @param object The object being destroyed. */
static void
gnc_plugin_page_finalize (GObject *object)
{
@@ -519,13 +549,23 @@
/* g_object other functions */
/************************************************************/
+
/** Retrieve a property specific to this GncPluginPage object. This is
* nothing more than a dispatch function for routines that can be
* called directly. It has the nice feature of allowing a single
* function call to retrieve multiple properties.
*
- * @internal
- */
+ * @param object The object whose property should be retrieved.
+ *
+ * @param prop_id The numeric identifier of the property. This
+ * should be a PROP_XXX constant as specified at the beginning of
+ * this file.
+ *
+ * @param value A pointer to where this property value should be
+ * stored.
+ *
+ * @param pspec A pointer to the meta data that described the property
+ * being retrieved. */
static void
gnc_plugin_page_get_property (GObject *object,
guint prop_id,
@@ -575,8 +615,16 @@
* to be created with a varargs list specifying the properties,
* instead of having to explicitly call each property function.
*
- * @internal
- */
+ * @param object The object whose property should be set.
+ *
+ * @param prop_id The numeric identifier of the property. This
+ * should be a PROP_XXX constant as specified at the beginning of
+ * this file.
+ *
+ * @param value A pointer to then new value for this property value.
+ *
+ * @param pspec A pointer to the meta data that described the property
+ * being retrieved. */
static void
gnc_plugin_page_set_property (GObject *object,
guint prop_id,
@@ -616,6 +664,7 @@
/* */
/************************************************************/
+/* Add a book reference to the specified page. */
void
gnc_plugin_page_add_book (GncPluginPage *page, QofBook *book)
{
@@ -632,6 +681,10 @@
priv->books = g_list_append(priv->books, guid);
}
+
+/* Query a page to see if it has a reference to a given book. This
+ * function takes a guid instead of a QofBook because that's what the
+ * engine event mechanism provides. */
gboolean
gnc_plugin_page_has_book (GncPluginPage *page, GUID *entity)
{
@@ -650,6 +703,8 @@
return FALSE;
}
+
+/* Query a page to see if it has a reference to any book. */
gboolean
gnc_plugin_page_has_books (GncPluginPage *page)
{
@@ -661,6 +716,9 @@
return (priv->books != NULL);
}
+
+/* Retrieve a pointer to the GncMainWindow (GtkWindow) containing
+ * this page. */
GtkWidget *
gnc_plugin_page_get_window (GncPluginPage *page)
{
@@ -669,6 +727,9 @@
return page->window;
}
+
+/* Retrieve the name of this page. This is the string used in the
+ * window title, and in the notebook tab and page selection menus. */
const gchar *
gnc_plugin_page_get_page_name (GncPluginPage *page)
{
@@ -680,6 +741,9 @@
return priv->page_name;
}
+
+/* Set the name of this page. This is the string used in the window
+ * title, and in the notebook tab and page selection menus. */
void
gnc_plugin_page_set_page_name (GncPluginPage *page, const gchar *name)
{
@@ -700,6 +764,8 @@
}
}
+
+/* Retrieve the Uniform Resource Identifier for this page. */
const gchar *
gnc_plugin_page_get_uri (GncPluginPage *page)
{
@@ -711,6 +777,8 @@
return priv->uri;
}
+
+/* Set the Uniform Resource Identifier for this page. */
void
gnc_plugin_page_set_uri (GncPluginPage *page, const gchar *name)
{
@@ -724,6 +792,8 @@
priv->uri = g_strdup(name);
}
+
+/* Retrieve the statusbar text associated with this page. */
const gchar *
gnc_plugin_page_get_statusbar_text (GncPluginPage *page)
{
@@ -735,6 +805,8 @@
return priv->statusbar_text;
}
+
+/* Set the statusbar text associated with this page. */
void
gnc_plugin_page_set_statusbar_text (GncPluginPage *page, const gchar *message)
{
@@ -748,6 +820,8 @@
priv->statusbar_text = g_strdup(message);
}
+
+/* Retrieve the "use new window" setting associated with this page. */
gboolean
gnc_plugin_page_get_use_new_window (GncPluginPage *page)
{
@@ -759,6 +833,11 @@
return priv->use_new_window;
}
+
+/* Set the "use new window" setting associated with this page. If
+ * this setting is TRUE, the page will be installed into a new
+ * window. Otherwise the page will be installed into an existing
+ * window. */
void
gnc_plugin_page_set_use_new_window (GncPluginPage *page, gboolean use_new)
{
@@ -770,6 +849,8 @@
priv->use_new_window = use_new;
}
+
+/* Retrieve the name of the XML UI file associated with this page. */
const gchar *
gnc_plugin_page_get_ui_description (GncPluginPage *page)
{
@@ -781,6 +862,9 @@
return priv->ui_description;
}
+
+/* Set an alternate UI for the specified page. This alternate ui
+ * may only use actions specified in the source for the page. */
void
gnc_plugin_page_set_ui_description (GncPluginPage *page,
const char *ui_filename)
@@ -795,6 +879,8 @@
priv->ui_description = g_strdup(ui_filename);
}
+
+/* Retrieve the GtkUIManager object associated with this page. */
GtkUIManager *
gnc_plugin_page_get_ui_merge (GncPluginPage *page)
{
@@ -806,6 +892,8 @@
return priv->ui_merge;
}
+
+/* Retrieve the GtkActionGroup object associated with this page. */
GtkActionGroup *
gnc_plugin_page_get_action_group(GncPluginPage *page)
{
@@ -816,6 +904,8 @@
return priv->action_group;
}
+
+/* Create the GtkActionGroup object associated with this page. */
GtkActionGroup *
gnc_plugin_page_create_action_group (GncPluginPage *page, const gchar *group_name)
{
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin-page.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin-page.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin-page.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -28,7 +28,7 @@
/** @addtogroup ContentPluginBase Common object and functions
@{ */
/** @file gnc-plugin-page.h
- @brief Functions for adding plugins to a Gnucash window.
+ @brief Functions for adding plugins to a GnuCash window.
@author Copyright (C) 2003 Jan Arne Petersen
@author Copyright (C) 2003,2005 David Hampton <hampton at employees.org>
*/
@@ -57,6 +57,8 @@
#endif
#endif
+
+/** The instance data structure for a content plugin. */
typedef struct GncPluginPage {
GObject gobject; /**< The parent object data. */
@@ -76,10 +78,15 @@
* code. */
} GncPluginPage;
+
+/** The class data structure for a content plugin. */
typedef struct {
GObjectClass gobject;
+ /** The relative name of the icon that should be shown on the
+ * tab for this page. */
const gchar *tab_icon;
+ /** The textual name of this plugin. */
const gchar *plugin_name;
/* Signals */
@@ -89,7 +96,22 @@
void (* unselected) (GncPluginPage *plugin_page);
/* Virtual Table */
+
+ /** Function called to create the display widget for a
+ * particular type of plugin. The returned widget should
+ * encompass all information that goes with this page,
+ * including scroll bars, a summary bar, etc.
+ *
+ * @param plugin_page A pointer to the plugin for which a
+ * display widget should be created.
+ *
+ * @return A displayable gtk widget. */
GtkWidget *(* create_widget) (GncPluginPage *plugin_page);
+ /** Function called to destroy the display widget for a
+ * particular type of plugin.
+ *
+ * @param plugin_page A pointer to the plugin whose display
+ * widget should be destroyed. */
void (* destroy_widget) (GncPluginPage *plugin_page);
/** Save enough information about this page so that it can be
@@ -123,6 +145,15 @@
* @return A pointer to the new page. */
GncPluginPage * (* recreate_page) (GtkWidget *window, GKeyFile *file, const gchar *group);
+ /** Perform plugin specific actions when a page is added to a
+ * window (or has been removed from one window and added to a
+ * new window). This function is called after the page is
+ * installed in the window, just before the window's
+ * PAGE_ADDED signal is generated.
+ *
+ * @param page The page that was added to a window.
+ *
+ * @param window The window where the page was added. */
void (* window_changed) (GncPluginPage *plugin_page, GtkWidget *window);
/** This function vector allows page specific actions to occur
@@ -134,35 +165,109 @@
void (* page_name_changed) (GncPluginPage *plugin_page, const gchar *name);
} GncPluginPageClass;
-/* function prototypes */
-GType gnc_plugin_page_get_type (void);
-GtkWidget *gnc_plugin_page_create_widget (GncPluginPage *plugin_page);
-void gnc_plugin_page_destroy_widget (GncPluginPage *plugin_page);
+/** Get the type of a content plugin.
+ *
+ * @return A GType.
+ */
+GType gnc_plugin_page_get_type (void);
-/** Show the summarybar associated with this page.
+
+/** Create the display widget that corresponds to this plugin. This
+ * function will be called by the main/embedded window manipulation
+ * code to create a widget that they can display. The returned
+ * widget should encompass all information that goes with this page,
+ * including scroll bars, a summary bar, etc.
*
+ * @param plugin_page A pointer to the plugin for which a display
+ * widget should be created.
+ *
+ * @return A displayable gtk widget. */
+GtkWidget *gnc_plugin_page_create_widget (GncPluginPage *plugin_page);
+
+
+/** Destroy the display widget that corresponds to this plugin. This
+ * function will be called by the main/embedded window manipulation
+ * code when a page is closed.
+ *
+ * @param plugin_page A pointer to the plugin whose display widget
+ * should be destroyed. */
+void gnc_plugin_page_destroy_widget (GncPluginPage *plugin_page);
+
+
+/** Show/hide the summarybar associated with this page.
+ *
* @param page The page whose summarybar visibility should be changed.
*
* @param visible Whether or not the summarybar should be shown..
*/
void gnc_plugin_page_show_summarybar (GncPluginPage *page, gboolean visible);
-void gnc_plugin_page_save_page (GncPluginPage *page,
- GKeyFile *key_file,
- const gchar *group_name);
-GncPluginPage * gnc_plugin_page_recreate_page (GtkWidget *window,
- const gchar *page_type,
- GKeyFile *key_file,
- const gchar *group_name);
-void gnc_plugin_page_merge_actions (GncPluginPage *plugin_page,
- GtkUIManager *merge);
-void gnc_plugin_page_unmerge_actions (GncPluginPage *plugin_page,
- GtkUIManager *merge);
+/** Call the plugin specific function that will save the state of a
+ * content page to a disk. That function must save enough
+ * information about the page that it can be recreated next time the
+ * user starts gnucash.
+ *
+ * @param page The page to save.
+ *
+ * @param key_file A pointer to the GKeyFile data structure where the
+ * page information should be written.
+ *
+ * @param group_name The group name to use when saving data. */
+void gnc_plugin_page_save_page (GncPluginPage *page,
+ GKeyFile *key_file,
+ const gchar *group_name);
-const gchar * gnc_plugin_page_get_plugin_name (GncPluginPage *plugin_page);
+/** This function looks up a specific plugin type by name, and then
+ * calls a plugin specific function to create a new page and restore
+ * its content to a previous state.
+ *
+ * @param window The window where this page should be installed.
+ *
+ * @param page_type The name of the page type to create.
+ *
+ * @param key_file A pointer to the GKeyFile data structure where the
+ * page information should be read.
+ *
+ * @param group_name The group name to use when restoring data. */
+GncPluginPage *gnc_plugin_page_recreate_page (GtkWidget *window,
+ const gchar *page_type,
+ GKeyFile *key_file,
+ const gchar *group_name);
+
+
+/** Add the actions for a content page to the specified window.
+ *
+ * @param plugin_page A pointer to the page whose actions should be
+ * added to the user interface.
+ *
+ * @param merge A pointer to the UI manager data structure for a
+ * window. */
+void gnc_plugin_page_merge_actions (GncPluginPage *plugin_page, GtkUIManager *merge);
+
+
+/** Remove the actions for a content page from the specified window.
+ *
+ * @param plugin_page A pointer to the page whose actions should be
+ * removed from the user interface.
+ *
+ * @param merge A pointer to the UI manager data structure for a
+ * window. */
+void gnc_plugin_page_unmerge_actions (GncPluginPage *plugin_page, GtkUIManager *merge);
+
+
+/** Retrieve the textual name of a plugin.
+ *
+ * @param plugin_page A pointer to the page whose actions name
+ * should be retrieved.
+ *
+ * @return The name of this plugin. This string is owned by the
+ * plugin. */
+const gchar *gnc_plugin_page_get_plugin_name (GncPluginPage *plugin_page);
+
+
/** Add a book reference to the specified page.
*
* @param page The page to be modified.
@@ -171,6 +276,7 @@
*/
void gnc_plugin_page_add_book (GncPluginPage *page, QofBook *book);
+
/** Query a page to see if it has a reference to a given book. This
* function takes a guid instead of a QofBook because that's what the
* engine event mechanism provides.
@@ -184,6 +290,7 @@
*/
gboolean gnc_plugin_page_has_book (GncPluginPage *page, GUID *book);
+
/** Query a page to see if it has a reference to any book.
*
* @param page The page to query.
@@ -192,6 +299,7 @@
*/
gboolean gnc_plugin_page_has_books (GncPluginPage *page);
+
/** Retrieve a pointer to the GncMainWindow (GtkWindow) containing
* this page.
*
@@ -201,6 +309,7 @@
*/
GtkWidget *gnc_plugin_page_get_window (GncPluginPage *page);
+
/** Retrieve the name of this page. This is the string used in the
* window title, and in the notebook tab and page selection menus.
*
@@ -211,8 +320,9 @@
*/
const gchar *gnc_plugin_page_get_page_name (GncPluginPage *page);
-/** Set the name of this page. This is the string used in the
- * window title, and in the notebook tab and page selection menus.
+
+/** Set the name of this page. This is the string used in the window
+ * title, and in the notebook tab and page selection menus.
*
* @param page The page whose name should be set.
*
@@ -220,6 +330,7 @@
*/
void gnc_plugin_page_set_page_name (GncPluginPage *page, const char *name);
+
/** Retrieve the Uniform Resource Identifier for this page.
*
* @param page The page whose URI should be retrieved.
@@ -229,6 +340,7 @@
*/
const gchar *gnc_plugin_page_get_uri (GncPluginPage *page);
+
/** Set the Uniform Resource Identifier for this page.
*
* @param page The page whose URI should be set.
@@ -237,6 +349,7 @@
*/
void gnc_plugin_page_set_uri (GncPluginPage *page, const char *name);
+
/** Retrieve the statusbar text associated with this page.
*
* @param page The page whose statusbar should text be retrieved.
@@ -246,6 +359,7 @@
*/
const gchar *gnc_plugin_page_get_statusbar_text (GncPluginPage *page);
+
/** Set the statusbar text associated with this page.
*
* @param page The page whose statusbar text should be set.
@@ -263,6 +377,7 @@
*/
gboolean gnc_plugin_page_get_use_new_window (GncPluginPage *page);
+
/** Set the "use new window" setting associated with this page. If
* this setting is TRUE, the page will be installed into a new
* window. Otherwise the page will be installed into an existing
@@ -321,7 +436,7 @@
* created.
*
* @param group_name The name associate with this action group. The
- * name is used to associate keybindings with actions, so it should
+ * name is used to associate key bindings with actions, so it should
* be consistent across all pages of the same type.
*
* @return A pointer to the newly created GtkActionGroup object for
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -42,14 +42,19 @@
#include "gnc-gobject-utils.h"
#include "messages.h"
+/** The debugging module that this .o belongs to. */
+static QofLogModule log_module = GNC_MOD_GUI;
+/** A pointer to the parent class of a plugin. */
static gpointer parent_class = NULL;
-static QofLogModule log_module = GNC_MOD_GUI;
static void gnc_plugin_class_init (GncPluginClass *klass);
static void gnc_plugin_init (GncPlugin *plugin_page,
GncPluginClass *klass);
static void gnc_plugin_finalize (GObject *object);
+
+/** The instance private data for a menu-only plugin. This data
+ * structure is unused. */
typedef struct GncPluginPrivate {
gpointer dummy;
} GncPluginPrivate;
@@ -93,8 +98,6 @@
* class.
*
* @param klass The new class structure created by the object system.
- *
- * @internal
*/
static void
gnc_plugin_class_init (GncPluginClass *klass)
@@ -108,14 +111,14 @@
}
-/** Initialize a new instance of a gnucash plugin object. This
- * function allocates and initializes the object private storage
- * space.
+/** Initialize a new instance of a gnucash menu-only plugin. This
+ * function adds the object to the tracking system.
*
- * @param view The new object instance created by the object system.
+ * @param plugin_page The new object instance created by the object
+ * system.
*
- * @internal
- */
+ * @param klass A pointer to the class data structure for this
+ * object. */
static void
gnc_plugin_init (GncPlugin *plugin_page, GncPluginClass *klass)
{
@@ -130,10 +133,7 @@
* function (i.e. the private data structure), then chain up to the
* parent's destroy function.
*
- * @param object The object being destroyed.
- *
- * @internal
- */
+ * @param object The object being destroyed. */
static void
gnc_plugin_finalize (GObject *object)
{
@@ -154,7 +154,8 @@
* will add the page's user interface from the window, set up gconf
* notifications if the page uses gconf, and call the plugin to
* perform any plugin specific actions.
- */
+ *
+ * See gnc-plugin.h for documentation on the function arguments. */
void
gnc_plugin_add_to_window (GncPlugin *plugin,
GncMainWindow *window,
@@ -211,7 +212,8 @@
* function will call the plugin to perform any plugin specific
* actions, remove any gconf notifications that were set up for the
* page, and remove the page's user interface from the window.
- */
+ *
+ * See gnc-plugin.h for documentation on the function arguments. */
void
gnc_plugin_remove_from_window (GncPlugin *plugin,
GncMainWindow *window,
@@ -253,7 +255,7 @@
}
-/** Retrieve the name of a plugin.
+/** Retrieve the textual name of a plugin.
*/
const gchar *
gnc_plugin_get_name (GncPlugin *plugin)
@@ -294,7 +296,9 @@
/** Mark certain actions as "important". This means that their labels
* will appear when the toolbar is set to "Icons and important text"
- * (e.g. GTK_TOOLBAR_BOTH_HORIZ) mode. */
+ * (e.g. GTK_TOOLBAR_BOTH_HORIZ) mode.
+ *
+ * See gnc-plugin.h for documentation on the function arguments. */
void
gnc_plugin_set_important_actions (GtkActionGroup *action_group,
const gchar **name)
@@ -313,9 +317,11 @@
}
-/** Update the status of existing UI actions. This function can
+/* Update a property of existing UI actions. This function can
* modify actions making them visible, invisible, sensitive, or
- * insensitive. */
+ * insensitive.
+ *
+ * See gnc-plugin.h for documentation on the function arguments. */
void
gnc_plugin_update_actions (GtkActionGroup *action_group,
const gchar **action_names,
@@ -336,7 +342,9 @@
}
-/** Load a new set of actions into an existing UI. */
+/** Load a new set of actions into an existing UI.
+ *
+ * See gnc-plugin.h for documentation on the function arguments. */
gint
gnc_plugin_add_actions (GtkUIManager *ui_merge,
GtkActionGroup *action_group,
Modified: gnucash/trunk/src/gnome-utils/gnc-plugin.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-plugin.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-plugin.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -1,6 +1,6 @@
/*
* gnc-plugin.h -- A module or plugin which can add more
- * functionality to gnucash.
+ * functionality to GnuCash.
* Copyright (C) 2003 Jan Arne Petersen <jpetersen at uni-bonn.de>
* Copyright (C) 2003,2005 David Hampton <hampton at employees.org>
*
@@ -58,9 +58,22 @@
/** @addtogroup MenuPluginBase Common object and functions
@{ */
/** @file gnc-plugin.h
- @brief Functions for adding plugins to a Gnucash window.
+ @brief Functions for adding plugins to a GnuCash window.
@author Copyright (C) 2003 Jan Arne Petersen
@author Copyright (C) 2003,2005 David Hampton <hampton at employees.org>
+
+ A GncPlugin is the basic object for adding a menu item or items to
+ the GnuCash user interface. This object should be instantiated
+ once at startup time and passed to the plugin manager. Whenever a
+ new window is opened, the main window code will ask the plugin
+ manager for a list of all plugins, and will add each plugin to the
+ new window by calling the gnc_plugin_add_to_window function. This
+ function handles installing the plugin's actions, and then calls
+ the plugin to allow it to perform any plugin specific actions.
+ When a main window is closed, the gnc_plugin_remove_from_window
+ function is called, which first calls the plugin to perform plugin
+ specific actions and then removes the plugin's actions from the
+ window.
*/
#ifndef __GNC_PLUGIN_H
@@ -82,40 +95,106 @@
/* typedefs & structures */
+/** The instance data structure for a menu-only plugin. */
typedef struct {
+ /** The parent object for this widget */
GObject gobject;
} GncPlugin;
+/** The class data structure for a menu-only plugin. */
typedef struct {
+ /** The parent class for this widget. */
GObjectClass gobject;
+ /** The textual name of this plugin. */
const gchar *plugin_name;
+ /* Actions section */
+
+ /** A name for the set of actions that will be added by this
+ * plugin. The actual name is irrelevant, as long as it is
+ * unique within GnuCash. */
const gchar *actions_name;
+ /** An array of actions that should automatically be added to
+ * any GnuCash "main" content window that is opened. */
GtkActionEntry *actions;
+ /** The number of actions in the actions array. */
guint n_actions;
+ /** A NULL terminated list of actions that should be considered
+ * important. In the toolbar, these actions will display the
+ * action name when the toolbar is in "text beside icons"
+ * mode. */
const gchar **important_actions;
+ /** The relative name of the XML file describing the
+ * menu/toolbar action items. */
const gchar *ui_filename;
+ /* GConf section */
+
+ /** The partial section name that will be used in GConf for
+ * any preferences that are automatically stored for this
+ * page. This will be converted to a full section name by
+ * prefixing the string "/apps/gnucash/" to whatever is
+ * here. */
const gchar* gconf_section;
- void (* gconf_notifications) (GConfClient *client, guint cnxn_id, GConfEntry *entry, gpointer user_data);
+ /** A callback that will be invoked when any key in the
+ * specified GConf section is changed.
+ *
+ * @param client A pointer to the gconf client instance.
+ *
+ * @param cnxn_id The id number for this callback function.
+ *
+ * @param entry A pointer to the changed data.
+ *
+ * @param user_data A pointer to the GncWindow where the
+ * plugin is installed. */
+ void (* gconf_notifications)
+ (GConfClient *client, guint cnxn_id, GConfEntry *entry, gpointer user_data);
- /* Virtual Table */
+ /* Virtual Table */
+
+ /** A callback that will be invoked when this plugin is added
+ * to a window. This allows the plugin to perform any
+ * special actions at insertion time.
+ *
+ * @param user_data A pointer to the this GncPlugin data
+ * structure.
+ *
+ * @param window A pointer to the window in which this plugin
+ * has just been installed.
+ *
+ * @param type An identifier for the type of window
+ * specified. Currently the only type is a "main" content
+ * window. */
void (* add_to_window)
(GncPlugin *plugin, GncMainWindow *window, GQuark type);
+
+ /** A callback that will be invoked when this plugin is
+ * removed from a window. This allows the plugin to perform
+ * any special actions at removal time.
+ *
+ * @param user_data A pointer to the this GncPlugin data
+ * structure.
+ *
+ * @param window A pointer to the window from which this
+ * plugin is about to be removed.
+ *
+ * @param type An identifier for the type of window
+ * specified. Currently the only type is a "main" content
+ * window. */
void (* remove_from_window)
(GncPlugin *plugin, GncMainWindow *window, GQuark type);
} GncPluginClass;
/* function prototypes */
-/** Get the type of a gnc window plugin.
+/** Get the type of a menu-only plugin.
*
* @return A GType.
*/
GType gnc_plugin_get_type (void);
-/** Add the specified plugin from the specified window. This function
+/** Add the specified plugin to the specified window. This function
* will add the page's user interface from the window, set up gconf
* notifications if the page uses gconf, and call the plugin to
* perform any plugin specific actions.
@@ -147,12 +226,11 @@
GQuark type);
-/** Retrieve the name of a plugin.
+/** Retrieve the textual name of a plugin.
*
* @param plugin The plugin whose name should be returned.
*
- * @return short_labels A pointer to a data structure containing
- * [action name, label string] string pairs.
+ * @return A string containing the name of this plugin
*/
const gchar *gnc_plugin_get_name (GncPlugin *plugin);
@@ -229,17 +307,17 @@
gboolean value);
-/** Load a new set of actions into an existing UI.
+/** Load a new set of actions into an existing UI. The actions from
+ * the provided group will be merged into the pre-existing ui, as
+ * directed by the specified file.
*
- * @param ui_merge The existing set of merged actions. This is the ui
- * that a user sees. The actions from the ui file will be added to
- * this ui.
+ * @param ui_merge A pointer to the UI manager data structure for a
+ * window.
*
- * @param action_group The local action group. The actions from the
- * ui file will be added to this private action group.
+ * @param action_group The set of actions provided by a given plugin.
*
- * @param filename The name of the ui file to load. This file name
- * will be searched for in the ui directory.
+ * @param filename The name of the ui description file. This file
+ * name will be searched for in the ui directory.
*
* @return The merge_id number for the newly merged UI. If an error
* occurred, the return value is 0.
Modified: gnucash/trunk/src/gnome-utils/gnc-tree-model-account.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-tree-model-account.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-tree-model-account.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -91,6 +91,7 @@
GNCEngineEventType event_type,
gpointer user_data);
+/** The instance private data for a account tree model. */
typedef struct GncTreeModelAccountPrivate
{
QofBook *book;
@@ -133,6 +134,7 @@
/* g_object required functions */
/************************************************************/
+/** A pointer to the parent class of a account tree model. */
static GtkObjectClass *parent_class = NULL;
GType
@@ -596,7 +598,7 @@
GncTreeModelAccount *model = GNC_TREE_MODEL_ACCOUNT (tree_model);
GncTreeModelAccountPrivate *priv;
Account *account;
- gboolean negative; /* used to set "defecit style" aka red numbers */
+ gboolean negative; /* used to set "deficit style" aka red numbers */
gchar *string;
ENTER("model %p, iter %s, col %d", tree_model,
@@ -896,7 +898,7 @@
if (group == NULL || xaccGroupGetNumAccounts (group) == 0) {
iter->stamp = 0;
- LEAVE("failed (chilren group was %s)",
+ LEAVE("failed (children group was %s)",
group ? "empty" : "null");
return FALSE;
}
Modified: gnucash/trunk/src/gnome-utils/gnc-tree-model-account.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-tree-model-account.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-tree-model-account.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -90,19 +90,27 @@
} GncTreeModelAccountColumn;
/* typedefs & structures */
+
+/** The instance data structure for an account tree model. */
typedef struct {
- GncTreeModel gnc_tree_model;
- int stamp;
+ GncTreeModel gnc_tree_model; /**< The parent object data. */
+ int stamp; /**< The state of the model. Any state
+ * change increments this number. */
} GncTreeModelAccount;
+
+/** The class data structure for an account tree model. */
typedef struct {
- GncTreeModelClass gnc_tree_model;
+ GncTreeModelClass gnc_tree_model;/**< The parent object data. */
} GncTreeModelAccountClass;
-/* Standard g_object type */
-GType gnc_tree_model_account_get_type (void);
+/** Get the type of an account tree plugin.
+ *
+ * @return A GType.
+ */
+GType gnc_tree_model_account_get_type (void);
/** @name Account Tree Model Constructors
@@ -111,7 +119,7 @@
/** Create a new GtkTreeModel for manipulating gnucash accounts.
*
* @param group The account group to put at the top level of the tree hierarchy. */
-GtkTreeModel *gnc_tree_model_account_new (AccountGroup *group);
+GtkTreeModel *gnc_tree_model_account_new (AccountGroup *group);
/** @} */
@@ -130,7 +138,7 @@
*
* @return The top-level pseudo-account.
*/
-Account *gnc_tree_model_account_get_toplevel (GncTreeModelAccount *model);
+Account *gnc_tree_model_account_get_toplevel (GncTreeModelAccount *model);
/** Convert a model/iter pair to a gnucash account. This routine should
@@ -145,8 +153,8 @@
*
* @return A pointer to the corresponding account.
*/
-Account *gnc_tree_model_account_get_account (GncTreeModelAccount *model,
- GtkTreeIter *iter);
+Account *gnc_tree_model_account_get_account (GncTreeModelAccount *model,
+ GtkTreeIter *iter);
/** Convert a model/account pair into a gtk_tree_model_iter. This
@@ -165,9 +173,9 @@
* @return TRUE if the account was found and the iter filled
* in. FALSE otherwise.
*/
-gboolean gnc_tree_model_account_get_iter_from_account (GncTreeModelAccount *model,
- Account *account,
- GtkTreeIter *iter);
+gboolean gnc_tree_model_account_get_iter_from_account (GncTreeModelAccount *model,
+ Account *account,
+ GtkTreeIter *iter);
/** Convert a model/account pair into a gtk_tree_model_path. This
@@ -183,8 +191,8 @@
* @return A pointer to a path describing the account. It is the
* responsibility of the caller to free this path when done.
*/
-GtkTreePath *gnc_tree_model_account_get_path_from_account (GncTreeModelAccount *model,
- Account *account);
+GtkTreePath *gnc_tree_model_account_get_path_from_account (GncTreeModelAccount *model,
+ Account *account);
/** @} */
G_END_DECLS
Modified: gnucash/trunk/src/gnome-utils/gnc-tree-model-commodity.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-tree-model-commodity.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-tree-model-commodity.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -87,6 +87,7 @@
GNCEngineEventType event_type,
gpointer user_data);
+/** The instance private data for a commodity database tree model. */
typedef struct GncTreeModelCommodityPrivate
{
QofBook *book;
@@ -97,6 +98,7 @@
#define GNC_TREE_MODEL_COMMODITY_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_TREE_MODEL_COMMODITY, GncTreeModelCommodityPrivate))
+/** A pointer to the parent class of a commodity tree model. */
static GtkObjectClass *parent_class = NULL;
GType
Modified: gnucash/trunk/src/gnome-utils/gnc-tree-model-commodity.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-tree-model-commodity.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-tree-model-commodity.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -75,19 +75,28 @@
} GncTreeModelCommodityColumn;
/* typedefs & structures */
+
+/** The instance data structure for a commodity tree model. */
typedef struct {
- GncTreeModel gnc_tree_model;
- int stamp;
+ GncTreeModel gnc_tree_model; /**< The parent object data. */
+ int stamp; /**< The state of the model. Any state
+ * change increments this number. */
} GncTreeModelCommodity;
+
+/** The class data structure for a commodity tree model. */
typedef struct {
- GncTreeModelClass gnc_tree_model;
+ GncTreeModelClass gnc_tree_model;/**< The parent object data. */
} GncTreeModelCommodityClass;
-/* function prototypes */
-GType gnc_tree_model_commodity_get_type (void);
+/** Get the type of a commodity tree plugin.
+ *
+ * @return A GType.
+ */
+GType gnc_tree_model_commodity_get_type (void);
+
/** @name Account Tree Model Constructors
@{ */
@@ -147,8 +156,8 @@
* the model.
*
* @return A pointer to the corresponding namespace. */
-gnc_commodity_namespace *gnc_tree_model_commodity_get_namespace (GncTreeModelCommodity *model,
- GtkTreeIter *iter);
+gnc_commodity_namespace *gnc_tree_model_commodity_get_namespace (GncTreeModelCommodity *model,
+ GtkTreeIter *iter);
/** Convert a model/iter pair to a gnucash commodity. This routine
* should only be called from a commodity tree view filter function.
@@ -161,8 +170,8 @@
* the model.
*
* @return A pointer to the corresponding commodity. */
-gnc_commodity *gnc_tree_model_commodity_get_commodity (GncTreeModelCommodity *model,
- GtkTreeIter *iter);
+gnc_commodity *gnc_tree_model_commodity_get_commodity (GncTreeModelCommodity *model,
+ GtkTreeIter *iter);
/** @} */
@@ -208,8 +217,8 @@
* namespace. This pointer must be freed by the caller when no
* longer needed. This routine will return NULL if the namespace
* does not exist in the tree. */
-GtkTreePath * gnc_tree_model_commodity_get_path_from_namespace (GncTreeModelCommodity *model,
- gnc_commodity_namespace *namespace);
+GtkTreePath *gnc_tree_model_commodity_get_path_from_namespace (GncTreeModelCommodity *model,
+ gnc_commodity_namespace *namespace);
/** Convert a commodity pointer into a GtkTreePath.
*
@@ -221,8 +230,8 @@
* commodity. This pointer must be freed by the caller when no
* longer needed. This routine will return NULL if the commodity
* does not exist in the tree. */
-GtkTreePath * gnc_tree_model_commodity_get_path_from_commodity (GncTreeModelCommodity *model,
- gnc_commodity *commodity);
+GtkTreePath *gnc_tree_model_commodity_get_path_from_commodity (GncTreeModelCommodity *model,
+ gnc_commodity *commodity);
/** @} */
G_END_DECLS
Modified: gnucash/trunk/src/gnome-utils/gnc-tree-model-price.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-tree-model-price.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-tree-model-price.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -105,6 +105,7 @@
GNCEngineEventType event_type,
gpointer user_data);
+/** The instance private data for a price database tree model. */
typedef struct GncTreeModelPricePrivate
{
QofBook *book;
@@ -116,6 +117,7 @@
#define GNC_TREE_MODEL_PRICE_GET_PRIVATE(o) \
(G_TYPE_INSTANCE_GET_PRIVATE ((o), GNC_TYPE_TREE_MODEL_PRICE, GncTreeModelPricePrivate))
+/** A pointer to the parent class of a price tree model. */
static GObjectClass *parent_class = NULL;
GType
@@ -1404,7 +1406,7 @@
* gnc_tree_model_price_event_handler() function. It must be armed
* each time an item is removed from the model. This function will
* be called as an idle function some time after the user requests
- * the deleteion. (Most likely when the event handler for the "OK"
+ * the deletion. (Most likely when the event handler for the "OK"
* button click returns. This function will send the "row_deleted"
* signal to any/all parent models for each entry deleted.
*
Modified: gnucash/trunk/src/gnome-utils/gnc-tree-model-price.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-tree-model-price.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-tree-model-price.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -69,22 +69,32 @@
} GncTreeModelPriceColumn;
/* typedefs & structures */
+
+/** The instance data structure for a price tree model. */
typedef struct {
- GncTreeModel gnc_tree_model;
- int stamp;
+ GncTreeModel gnc_tree_model; /**< The parent object data. */
+ int stamp; /**< The state of the model. Any state
+ * change increments this number. */
} GncTreeModelPrice;
+
+/** The class data structure for a price tree model. */
typedef struct {
- GncTreeModelClass gnc_tree_model;
+ GncTreeModelClass gnc_tree_model;/**< The parent object data. */
} GncTreeModelPriceClass;
-/* function prototypes */
-GType gnc_tree_model_price_get_type (void);
+/** Get the type of a price tree plugin.
+ *
+ * @return A GType.
+ */
+GType gnc_tree_model_price_get_type (void);
+
+
/** @name Account Tree Model Constructors
@{ */
-/** Create a new GtkTreeModel for manipulating gnucash commodities.
+/** Create a new GtkTreeModel for manipulating gnucash commodity prices.
*
* @param book The book that holds these prices.
*
@@ -99,9 +109,9 @@
@{ */
/** Determine whether or not the specified GtkTreeIter points to a
- * commodity namespace. This routine should only be called from a
- * price tree view filter function. The model and iter values
- * will be provided as part of the call to the filter.
+ * "commodity namespace". This routine should only be called from a
+ * price tree view filter function. The model and iter values will
+ * be provided as part of the call to the filter.
*
* @param model A pointer to the price tree model.
*
@@ -248,8 +258,8 @@
* namespace. This pointer must be freed by the caller when no
* longer needed. This routine will return NULL if the namespace
* does not exist in the tree. */
-GtkTreePath * gnc_tree_model_price_get_path_from_namespace (GncTreeModelPrice *model,
- gnc_commodity_namespace *namespace);
+GtkTreePath *gnc_tree_model_price_get_path_from_namespace (GncTreeModelPrice *model,
+ gnc_commodity_namespace *namespace);
/** Convert a commodity pointer into a GtkTreePath.
*
@@ -261,8 +271,8 @@
* commodity. This pointer must be freed by the caller when no
* longer needed. This routine will return NULL if the commodity
* does not exist in the tree. */
-GtkTreePath * gnc_tree_model_price_get_path_from_commodity (GncTreeModelPrice *model,
- gnc_commodity *commodity);
+GtkTreePath *gnc_tree_model_price_get_path_from_commodity (GncTreeModelPrice *model,
+ gnc_commodity *commodity);
/** Convert a price pointer into a GtkTreePath.
*
@@ -274,8 +284,8 @@
* price. This pointer must be freed by the caller when no longer
* needed. This routine will return NULL if the price does not exist
* in the tree. */
-GtkTreePath * gnc_tree_model_price_get_path_from_price (GncTreeModelPrice *model,
- GNCPrice *price);
+GtkTreePath *gnc_tree_model_price_get_path_from_price (GncTreeModelPrice *model,
+ GNCPrice *price);
/** @} */
Modified: gnucash/trunk/src/gnome-utils/gnc-tree-model.c
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-tree-model.c 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-tree-model.c 2005-11-14 05:14:21 UTC (rev 11929)
@@ -42,6 +42,7 @@
static void gnc_tree_model_finalize (GObject *object);
static void gnc_tree_model_destroy (GtkObject *object);
+/** The instance private data for a generic tree model. */
typedef struct GncTreeModelPrivate
{
gpointer dummy;
@@ -55,6 +56,7 @@
/* g_object required functions */
/************************************************************/
+/** A pointer to the parent class of a generic tree model. */
static GtkObjectClass *parent_class = NULL;
GType
Modified: gnucash/trunk/src/gnome-utils/gnc-tree-model.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-tree-model.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-tree-model.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -50,20 +50,26 @@
#define GNC_TREE_MODEL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GNC_TYPE_TREE_MODEL, GncTreeModelClass))
#define GNC_TREE_MODEL_NAME "GncTreeModel"
+/* typedefs & structures */
-/* typedefs & structures */
+/** The instance data structure for a generic tree model. */
typedef struct {
- GtkObject gtk_object;
+ GtkObject gtk_object; /**< The parent object data. */
} GncTreeModel;
+
+/** The class data structure for a generic tree model. */
typedef struct {
- GtkObjectClass gtk_object;
+ GtkObjectClass gtk_object; /**< The parent object data. */
} GncTreeModelClass;
-/* Standard g_object type */
-GType gnc_tree_model_get_type (void);
+/** Get the type of a generic tree model plugin.
+ *
+ * @return A GType.
+ */
+GType gnc_tree_model_get_type (void);
G_END_DECLS
Modified: gnucash/trunk/src/gnome-utils/gnc-window.h
===================================================================
--- gnucash/trunk/src/gnome-utils/gnc-window.h 2005-11-14 05:13:27 UTC (rev 11928)
+++ gnucash/trunk/src/gnome-utils/gnc-window.h 2005-11-14 05:14:21 UTC (rev 11929)
@@ -24,7 +24,7 @@
/** @addtogroup Windows
@{ */
-/** @addtogroup GncWindow Basic Window Functions
+/** @addtogroup GncWindow Common Window Functions
@{ */
/** @file gnc-window.h
@brief Functions that are supported by all types of windows.
More information about the gnucash-changes
mailing list