Common object and functions

Files
file	gnc-plugin.c
	Functions for adding plugins to a Gnucash window.
file	gnc-plugin.h
	Functions for adding plugins to a GnuCash window.

Data Structures
struct	GncPluginPrivate
	The instance private data for a menu-only plugin. More...
struct	GncPlugin
	The instance data structure for a menu-only plugin. More...
struct	GncPluginClass
	The class data structure for a menu-only plugin. More...
struct	action_toolbar_labels
	A structure for defining alternate action names for use in the toolbar. More...

Macros
#define	GNC_TYPE_PLUGIN   (gnc_plugin_get_type ())
#define	GNC_PLUGIN(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_PLUGIN, GncPlugin))
#define	GNC_PLUGIN_CLASS(klass)   (G_TYPE_CHECK_CLASS_CAST ((klass), GNC_TYPE_PLUGIN, GncPluginClass))
#define	GNC_IS_PLUGIN(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_PLUGIN))
#define	GNC_IS_PLUGIN_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), GNC_TYPE_PLUGIN))
#define	GNC_PLUGIN_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GNC_PLUGIN, GncPluginClass))
#define	GNC_PLUGIN_NAME   "GncPlugin"

Functions
	GNC_DEFINE_TYPE_WITH_CODE (GncPlugin, gnc_plugin, G_TYPE_OBJECT, G_ADD_PRIVATE(GncPlugin))
	Initialize the class for the new gnucash plugin object. More...
void	gnc_plugin_add_to_window (GncPlugin *plugin, GncMainWindow *window, GQuark type)
	Add the specified plugin from the specified window. More...
void	gnc_plugin_remove_from_window (GncPlugin *plugin, GncMainWindow *window, GQuark type)
	Remove the specified plugin from the specified window. More...
const gchar *	gnc_plugin_get_name (GncPlugin *plugin)
	Retrieve the textual name of a plugin. More...
void	gnc_plugin_init_short_names (GtkActionGroup *action_group, action_toolbar_labels *toolbar_labels)
	Add "short" labels to existing actions. More...
void	gnc_plugin_set_important_actions (GtkActionGroup *action_group, const gchar **name)
	Mark certain actions as "important". More...
void	gnc_plugin_update_actions (GtkActionGroup *action_group, const gchar **action_names, const gchar *property_name, gboolean value)
	Update a property on a set of existing GtkActions. More...
gint	gnc_plugin_add_actions (GtkUIManager *ui_merge, GtkActionGroup *action_group, const gchar *filename)
	Load a new set of actions into an existing UI. More...
GType	gnc_plugin_get_type (void)
	Get the type of a menu-only plugin. More...

Detailed Description

Function Documentation

GNC_DEFINE_TYPE_WITH_CODE()

GNC_DEFINE_TYPE_WITH_CODE	(	GncPlugin	,
		gnc_plugin	,
		G_TYPE_OBJECT	,
		G_ADD_PRIVATE(GncPlugin)
	)

Initialize the class for the new gnucash plugin object.

This will set up any function pointers that override functions in the parent class, and also installs the proprieties that are unique to this class.

Parameters

klass

The new class structure created by the object system.

Definition at line 64 of file gnc-plugin.c.

{
    GObjectClass *gobject_class = G_OBJECT_CLASS (klass);

    parent_class = g_type_class_peek_parent (klass);
    gobject_class->finalize = gnc_plugin_finalize;
}

gnc_plugin_add_actions()

gint gnc_plugin_add_actions	(	GtkUIManager *	ui_merge,
		GtkActionGroup *	action_group,
		const gchar *	filename
	)

Load a new set of actions into an existing UI.

See gnc-plugin.h for documentation on the function arguments.

The actions from the provided group will be merged into the pre-existing ui, as directed by the specified file.

Parameters

ui_merge	A pointer to the UI manager data structure for a window.
action_group	The set of actions provided by a given plugin.
filename	The name of the ui description file. This file name will be searched for in the ui directory.

Returns

The merge_id number for the newly merged UI. If an error occurred, the return value is 0.

Definition at line 309 of file gnc-plugin.c.

{
    GError *error = NULL;
    gchar *pathname;
    gint merge_id;

    g_return_val_if_fail (ui_merge, 0);
    g_return_val_if_fail (action_group, 0);
    g_return_val_if_fail (filename, 0);

    ENTER("ui_merge %p, action_group %p, filename %s",
          ui_merge, action_group, filename);
    gtk_ui_manager_insert_action_group (ui_merge, action_group, 0);

    pathname = gnc_filepath_locate_ui_file (filename);
    if (pathname == NULL)
    {
        LEAVE("fail");
        return 0;
    }

    merge_id = gtk_ui_manager_add_ui_from_file (ui_merge, pathname, &error);
    DEBUG("merge_id is %d", merge_id);

    g_assert(merge_id || error);
    if (merge_id)
    {
        gtk_ui_manager_ensure_update (ui_merge);
    }
    else
    {
        g_critical("Failed to load ui file.\n  Filename %s\n  Error %s",
                   filename, error->message);
        g_error_free(error);
    }

    g_free(pathname);
    LEAVE(" ");
    return merge_id;
}

gnc_plugin_add_to_window()

void gnc_plugin_add_to_window	(	GncPlugin *	plugin,
		GncMainWindow *	window,
		GQuark	type
	)

Add the specified plugin from the specified window.

Add the specified plugin to the specified window.

This function will add the page's user interface from the window and call the plugin to perform any plugin specific actions.

See gnc-plugin.h for documentation on the function arguments.

This function will add the page's user interface from the window and call the plugin to perform any plugin specific actions.

Parameters

plugin	The plugin to be added.
window	Add the plugin to this window.
type	An identifier for the type of window specified.

Definition at line 128 of file gnc-plugin.c.

{
    GncPluginClass *klass;
    GtkActionGroup *action_group;

    g_return_if_fail (GNC_IS_PLUGIN (plugin));
    klass = GNC_PLUGIN_GET_CLASS (plugin);
    ENTER (": plugin %s(%p), window %p", gnc_plugin_get_name(plugin),
           plugin, window);

    /*
     * Update window with additional UI items
     */
    if (klass->actions_name)
    {
        DEBUG ("%s: %d actions to merge with gui from %s",
               klass->actions_name, (klass->n_actions + klass->n_toggle_actions), klass->ui_filename);
        gnc_main_window_merge_actions (window, klass->actions_name,
                                       klass->actions, klass->n_actions,
                                       klass->toggle_actions, klass->n_toggle_actions,
                                       klass->ui_filename, plugin);


        if (klass->important_actions)
        {
            action_group =
                gnc_main_window_get_action_group(window, klass->actions_name);
            gnc_plugin_set_important_actions(action_group,
                                             klass->important_actions);
        }
    }

    /*
     * Do plugin specific actions.
     */
    if (GNC_PLUGIN_GET_CLASS (plugin)->add_to_window)
    {
        DEBUG ("Calling child class function %p", GNC_PLUGIN_GET_CLASS (plugin)->add_to_window);
        GNC_PLUGIN_GET_CLASS (plugin)->add_to_window (plugin, window, type);
    }
    LEAVE ("");
}

gnc_plugin_get_name()

const gchar * gnc_plugin_get_name

(

GncPlugin *

plugin

)

Retrieve the textual name of a plugin.

Parameters

plugin

The plugin whose name should be returned.

Returns

A string containing the name of this plugin

Definition at line 217 of file gnc-plugin.c.

{
    g_return_val_if_fail (GNC_IS_PLUGIN (plugin), NULL);
    return (GNC_PLUGIN_GET_CLASS(plugin)->plugin_name);
}

gnc_plugin_get_type()

GType gnc_plugin_get_type

(

void

)

Get the type of a menu-only plugin.

Returns

A GType.

gnc_plugin_init_short_names()

void gnc_plugin_init_short_names	(	GtkActionGroup *	action_group,
		action_toolbar_labels *	toolbar_labels
	)

Add "short" labels to existing actions.

The "short" label is the string used on toolbar buttons when the action is visible.

See gnc-plugin.h for documentation on the function arguments.

The "short" label is the string used on toolbar buttons when the action is visible. All toolbar buttons are homogeneous in size and are sized to fit the longest label. Therefore, this structure should be used if an action name is more than one word. This way the menu can have the label "Whizzy Feature", while the toolbar button only has the label "Whizzy".

Parameters

action_group	The group of all actions associated with a plugin or plugin page. All actions to me modified must be in this group.
toolbar_labels	A pointer to a NULL terminated array of data action_toolbar_labels items.

Definition at line 234 of file gnc-plugin.c.

{
    GtkAction *action;
    gint i;

    for (i = 0; toolbar_labels[i].action_name; i++)
    {
        /* Add a couple of short labels for the toolbar */
        action = gtk_action_group_get_action (action_group,
                                              toolbar_labels[i].action_name);
        gtk_action_set_short_label (action, _(toolbar_labels[i].label));
    }
}

gnc_plugin_remove_from_window()

void gnc_plugin_remove_from_window	(	GncPlugin *	plugin,
		GncMainWindow *	window,
		GQuark	type
	)

Remove the specified plugin from the specified window.

This function will call the plugin to perform any plugin specific actions and remove the page's user interface from the window.

Parameters

plugin	The plugin to be removed.
window	The window the plugin should be removed from.
type	An identifier for the type of window specified.

Definition at line 180 of file gnc-plugin.c.

{
    GncPluginClass *klass;

    g_return_if_fail (GNC_IS_PLUGIN (plugin));
    klass = GNC_PLUGIN_GET_CLASS (plugin);
    ENTER (": plugin %s(%p), window %p", gnc_plugin_get_name(plugin),
           plugin, window);

    /*
     * Do plugin specific actions.
     */
    if (GNC_PLUGIN_GET_CLASS (plugin)->remove_from_window)
    {
        DEBUG ("Calling child class function %p",
               GNC_PLUGIN_GET_CLASS (plugin)->remove_from_window);
        GNC_PLUGIN_GET_CLASS (plugin)->remove_from_window (plugin, window, type);
    }

    /*
     * Update window to remove UI items
     */
    if (klass->actions_name && !window->just_plugin_prefs)
    {
        DEBUG ("%s: %d actions to unmerge",
               klass->actions_name, (klass->n_actions + klass->n_toggle_actions));
        gnc_main_window_unmerge_actions (window, klass->actions_name);
    }
    LEAVE ("");
}

gnc_plugin_set_important_actions()

void gnc_plugin_set_important_actions	(	GtkActionGroup *	action_group,
		const gchar **	name
	)

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.

See gnc-plugin.h for documentation on the function arguments.

This means that their labels will appear when the toolbar is set to "Icons and important text" (e.g. GTK_TOOLBAR_BOTH_HORIZ) mode.

Parameters

action_group	The group of all actions associated with a plugin or plugin page. All actions to me modified must be in this group.
name	A list of actions names to be marked important. This list must be NULL terminated.

Definition at line 256 of file gnc-plugin.c.

{
    GtkAction *action;
    gint i;

    for (i = 0; name[i]; i++)
    {
        action = gtk_action_group_get_action (action_group, name[i]);
        g_object_set (G_OBJECT(action), "is_important", TRUE, NULL);
    }

    /* If this trips, you've got too many "important" actions.  That
     * can't *all* be that important, can they? */
    g_assert(i <= 3);
}

gnc_plugin_update_actions()

void gnc_plugin_update_actions	(	GtkActionGroup *	action_group,
		const gchar **	action_names,
		const gchar *	property_name,
		gboolean	value
	)

Update a property on a set of existing GtkActions.

This function can be easily used to make a list of actions visible, invisible, sensitive, or insensitive.

Parameters

action_group	The group of all actions associated with a plugin or plugin page. All actions to be modified must be contained in this group.
action_names	A NULL terminated list of actions names that should be modified.
property_name	The property name to be changed on the specified actions. The only two GtkAction properties that it makes sense to modify are "visible" and "sensitive".
value	A boolean specifying the new state for the specified property.

Definition at line 280 of file gnc-plugin.c.

{
    GtkAction    *action;
    gint          i;

    for (i = 0; action_names[i]; i++)
    {
        action = gtk_action_group_get_action (action_group, action_names[i]);
        if (action)
        {
            g_object_set (G_OBJECT(action), property_name, value, NULL);
        }
        else
        {
            g_warning("No such action with name '%s' in action group %s (size %d)",
                      action_names[i], gtk_action_group_get_name(action_group),
                      g_list_length(gtk_action_group_list_actions(action_group)));
        }
    }
}