GnuCash  4.11-148-gc20d717b33+
Files | Data Structures | Macros | Functions
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
klassThe new class structure created by the object system.

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

79 {
80  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
81 
82  parent_class = g_type_class_peek_parent (klass);
83  gobject_class->finalize = gnc_plugin_finalize;
84 }

◆ 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_mergeA pointer to the UI manager data structure for a window.
action_groupThe set of actions provided by a given plugin.
filenameThe 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.

312 {
313  GError *error = NULL;
314  gchar *pathname;
315  gint merge_id;
316 
317  g_return_val_if_fail (ui_merge, 0);
318  g_return_val_if_fail (action_group, 0);
319  g_return_val_if_fail (filename, 0);
320 
321  ENTER("ui_merge %p, action_group %p, filename %s",
322  ui_merge, action_group, filename);
323  gtk_ui_manager_insert_action_group (ui_merge, action_group, 0);
324 
325  pathname = gnc_filepath_locate_ui_file (filename);
326  if (pathname == NULL)
327  {
328  LEAVE("fail");
329  return 0;
330  }
331 
332  merge_id = gtk_ui_manager_add_ui_from_file (ui_merge, pathname, &error);
333  DEBUG("merge_id is %d", merge_id);
334 
335  g_assert(merge_id || error);
336  if (merge_id)
337  {
338  gtk_ui_manager_ensure_update (ui_merge);
339  }
340  else
341  {
342  g_critical("Failed to load ui file.\n Filename %s\n Error %s",
343  filename, error->message);
344  g_error_free(error);
345  }
346 
347  g_free(pathname);
348  LEAVE(" ");
349  return merge_id;
350 }
#define DEBUG(format, args...)
Print a debugging message.
Definition: qoflog.h:264
gchar * gnc_filepath_locate_ui_file(const gchar *name)
Given a ui file name, find the file in the ui directory associated with this application.
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282

◆ 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
pluginThe plugin to be added.
windowAdd the plugin to this window.
typeAn identifier for the type of window specified.

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

131 {
132  GncPluginClass *klass;
133  GtkActionGroup *action_group;
134 
135  g_return_if_fail (GNC_IS_PLUGIN (plugin));
136  klass = GNC_PLUGIN_GET_CLASS (plugin);
137  ENTER (": plugin %s(%p), window %p", gnc_plugin_get_name(plugin),
138  plugin, window);
139 
140  /*
141  * Update window with additional UI items
142  */
143  if (klass->actions_name)
144  {
145  DEBUG ("%s: %d actions to merge with gui from %s",
146  klass->actions_name, (klass->n_actions + klass->n_toggle_actions), klass->ui_filename);
148  klass->actions, klass->n_actions,
149  klass->toggle_actions, klass->n_toggle_actions,
150  klass->ui_filename, plugin);
151 
152 
153  if (klass->important_actions)
154  {
155  action_group =
158  klass->important_actions);
159  }
160  }
161 
162  /*
163  * Do plugin specific actions.
164  */
165  if (GNC_PLUGIN_GET_CLASS (plugin)->add_to_window)
166  {
167  DEBUG ("Calling child class function %p", GNC_PLUGIN_GET_CLASS (plugin)->add_to_window);
168  GNC_PLUGIN_GET_CLASS (plugin)->add_to_window (plugin, window, type);
169  }
170  LEAVE ("");
171 }
guint n_actions
The number of actions in the actions array.
Definition: gnc-plugin.h:124
void gnc_main_window_merge_actions(GncMainWindow *window, const gchar *group_name, GtkActionEntry *actions, guint n_actions, GtkToggleActionEntry *toggle_actions, guint n_toggle_actions, const gchar *filename, gpointer user_data)
Add a set of actions to the specified window.
#define DEBUG(format, args...)
Print a debugging message.
Definition: qoflog.h:264
The class data structure for a menu-only plugin.
Definition: gnc-plugin.h:107
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
guint n_toggle_actions
The number of toggle actions in the toggle actions array.
Definition: gnc-plugin.h:129
const gchar * ui_filename
The relative name of the XML file describing the menu/toolbar action items.
Definition: gnc-plugin.h:137
GtkActionEntry * actions
An array of actions that should automatically be added to any GnuCash "main" content window that is o...
Definition: gnc-plugin.h:122
const gchar ** important_actions
A NULL terminated list of actions that should be considered important.
Definition: gnc-plugin.h:134
const gchar * gnc_plugin_get_name(GncPlugin *plugin)
Retrieve the textual name of a plugin.
Definition: gnc-plugin.c:217
GtkToggleActionEntry * toggle_actions
An array of toggle actions that should automatically be added to any GnuCash "main" content window th...
Definition: gnc-plugin.h:127
const gchar * actions_name
A name for the set of actions that will be added by this plugin.
Definition: gnc-plugin.h:119
GtkActionGroup * gnc_main_window_get_action_group(GncMainWindow *window, const gchar *group_name)
Retrieve a specific set of user interface actions from a window.
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282
void gnc_plugin_set_important_actions(GtkActionGroup *action_group, const gchar **name)
Mark certain actions as "important".
Definition: gnc-plugin.c:256

◆ gnc_plugin_get_name()

const gchar * gnc_plugin_get_name ( GncPlugin plugin)

Retrieve the textual name of a plugin.

Parameters
pluginThe plugin whose name should be returned.
Returns
A string containing the name of this plugin

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

218 {
219  g_return_val_if_fail (GNC_IS_PLUGIN (plugin), NULL);
220  return (GNC_PLUGIN_GET_CLASS(plugin)->plugin_name);
221 }

◆ 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_groupThe group of all actions associated with a plugin or plugin page. All actions to me modified must be in this group.
toolbar_labelsA pointer to a NULL terminated array of data action_toolbar_labels items.

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

236 {
237  GtkAction *action;
238  gint i;
239 
240  for (i = 0; toolbar_labels[i].action_name; i++)
241  {
242  /* Add a couple of short labels for the toolbar */
243  action = gtk_action_group_get_action (action_group,
244  toolbar_labels[i].action_name);
245  gtk_action_set_short_label (action, _(toolbar_labels[i].label));
246  }
247 }
const char * action_name
The name of the action.
Definition: gnc-plugin.h:231

◆ 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
pluginThe plugin to be removed.
windowThe window the plugin should be removed from.
typeAn identifier for the type of window specified.

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

183 {
184  GncPluginClass *klass;
185 
186  g_return_if_fail (GNC_IS_PLUGIN (plugin));
187  klass = GNC_PLUGIN_GET_CLASS (plugin);
188  ENTER (": plugin %s(%p), window %p", gnc_plugin_get_name(plugin),
189  plugin, window);
190 
191  /*
192  * Do plugin specific actions.
193  */
194  if (GNC_PLUGIN_GET_CLASS (plugin)->remove_from_window)
195  {
196  DEBUG ("Calling child class function %p",
197  GNC_PLUGIN_GET_CLASS (plugin)->remove_from_window);
198  GNC_PLUGIN_GET_CLASS (plugin)->remove_from_window (plugin, window, type);
199  }
200 
201  /*
202  * Update window to remove UI items
203  */
204  if (klass->actions_name && !window->just_plugin_prefs)
205  {
206  DEBUG ("%s: %d actions to unmerge",
207  klass->actions_name, (klass->n_actions + klass->n_toggle_actions));
209  }
210  LEAVE ("");
211 }
guint n_actions
The number of actions in the actions array.
Definition: gnc-plugin.h:124
#define DEBUG(format, args...)
Print a debugging message.
Definition: qoflog.h:264
The class data structure for a menu-only plugin.
Definition: gnc-plugin.h:107
void gnc_main_window_unmerge_actions(GncMainWindow *window, const gchar *group_name)
Remove a set of actions from the specified window.
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
guint n_toggle_actions
The number of toggle actions in the toggle actions array.
Definition: gnc-plugin.h:129
const gchar * gnc_plugin_get_name(GncPlugin *plugin)
Retrieve the textual name of a plugin.
Definition: gnc-plugin.c:217
const gchar * actions_name
A name for the set of actions that will be added by this plugin.
Definition: gnc-plugin.h:119
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282

◆ 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_groupThe group of all actions associated with a plugin or plugin page. All actions to me modified must be in this group.
nameA list of actions names to be marked important. This list must be NULL terminated.

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

258 {
259  GtkAction *action;
260  gint i;
261 
262  for (i = 0; name[i]; i++)
263  {
264  action = gtk_action_group_get_action (action_group, name[i]);
265  g_object_set (G_OBJECT(action), "is_important", TRUE, NULL);
266  }
267 
268  /* If this trips, you've got too many "important" actions. That
269  * can't *all* be that important, can they? */
270  g_assert(i <= 3);
271 }

◆ 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_groupThe group of all actions associated with a plugin or plugin page. All actions to be modified must be contained in this group.
action_namesA NULL terminated list of actions names that should be modified.
property_nameThe property name to be changed on the specified actions. The only two GtkAction properties that it makes sense to modify are "visible" and "sensitive".
valueA boolean specifying the new state for the specified property.

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

284 {
285  GtkAction *action;
286  gint i;
287 
288  for (i = 0; action_names[i]; i++)
289  {
290  action = gtk_action_group_get_action (action_group, action_names[i]);
291  if (action)
292  {
293  g_object_set (G_OBJECT(action), property_name, value, NULL);
294  }
295  else
296  {
297  g_warning("No such action with name '%s' in action group %s (size %d)",
298  action_names[i], gtk_action_group_get_name(action_group),
299  g_list_length(gtk_action_group_list_actions(action_group)));
300  }
301  }
302 }