Geany  dev
Functions
pluginutils.h File Reference

Plugin utility functions. More...

Functions

void plugin_add_toolbar_item (struct GeanyPlugin *plugin, GtkToolItem *item)
 Inserts a toolbar item before the Quit button, or after the previous plugin toolbar item. More...
 
void plugin_builder_connect_signals (struct GeanyPlugin *plugin, GtkBuilder *builder, gpointer user_data)
 Allows auto-connecting Glade/GtkBuilder signals in plugins. More...
 
gpointer plugin_get_document_data (struct GeanyPlugin *plugin, struct GeanyDocument *doc, const gchar *key)
 Retrieve plugin-specific data attached to a document. More...
 
guint plugin_idle_add (struct GeanyPlugin *plugin, GSourceFunc function, gpointer data)
  Adds a GLib main loop IDLE callback that will be removed when unloading the plugin, preventing it to run after the plugin has been unloaded (which may lead to a segfault). More...
 
void plugin_module_make_resident (struct GeanyPlugin *plugin)
 Ensures that a plugin's module (*.so) will never be unloaded. More...
 
void plugin_set_document_data (struct GeanyPlugin *plugin, struct GeanyDocument *doc, const gchar *key, gpointer data)
 Attach plugin-specific data to a document. More...
 
void plugin_set_document_data_full (struct GeanyPlugin *plugin, struct GeanyDocument *doc, const gchar *key, gpointer data, GDestroyNotify free_func)
 Attach plugin-specific data and a free function to a document. More...
 
struct GeanyKeyGroupplugin_set_key_group (struct GeanyPlugin *plugin, const gchar *section_name, gsize count, GeanyKeyGroupCallback callback)
  Sets up or resizes a keybinding group for the plugin. More...
 
GeanyKeyGroupplugin_set_key_group_full (struct GeanyPlugin *plugin, const gchar *section_name, gsize count, GeanyKeyGroupFunc cb, gpointer pdata, GDestroyNotify destroy_notify)
 Sets up or resizes a keybinding group for the plugin. More...
 
void plugin_show_configure (struct GeanyPlugin *plugin)
 Shows the plugin's configure dialog. More...
 
void plugin_signal_connect (struct GeanyPlugin *plugin, GObject *object, const gchar *signal_name, gboolean after, GCallback callback, gpointer user_data)
  Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault. More...
 
guint plugin_timeout_add (struct GeanyPlugin *plugin, guint interval, GSourceFunc function, gpointer data)
  Adds a GLib main loop timeout callback that will be removed when unloading the plugin, preventing it to run after the plugin has been unloaded (which may lead to a segfault). More...
 
guint plugin_timeout_add_seconds (struct GeanyPlugin *plugin, guint interval, GSourceFunc function, gpointer data)
  Adds a GLib main loop timeout callback that will be removed when unloading the plugin, preventing it to run after the plugin has been unloaded (which may lead to a segfault). More...
 

Detailed Description

Plugin utility functions.

These functions all take the geany_plugin symbol as their first argument.

Function Documentation

void plugin_add_toolbar_item ( GeanyPlugin plugin,
GtkToolItem *  item 
)

Inserts a toolbar item before the Quit button, or after the previous plugin toolbar item.

A separator is added on the first call to this function, and will be shown when item is shown; hidden when item is hidden.

Note
You should still destroy item yourself, usually in plugin_cleanup().
Parameters
pluginMust be geany_plugin.
itemThe item to add.
void plugin_builder_connect_signals ( GeanyPlugin plugin,
GtkBuilder *  builder,
gpointer  user_data 
)

Allows auto-connecting Glade/GtkBuilder signals in plugins.

When a plugin uses GtkBuilder to load some UI from file/string, the gtk_builder_connect_signals() function is unable to automatically connect to the plugin's signal handlers. A plugin could itself use the gtk_builder_connect_signals_full() function to automatically connect to the signal handler functions by loading it's GModule and retrieving pointers to the handler functions, but rather than each plugin having to do that, this function handles it automatically.

1 ...
2 GeanyPlugin *geany_plugin;
3 
4 G_MODULE_EXPORT void
5 myplugin_button_clicked(GtkButton *button, gpointer user_data)
6 {
7  g_print("Button pressed\n");
8 }
9 
10 void plugin_init(GeanyData *data)
11 {
12  GtkBuilder *builder = gtk_builder_new();
13  gtk_builder_add_from_file(builder, "gui.glade", NULL);
14  plugin_builder_connect_signals(geany_plugin, builder, NULL);
15  ...
16 }
Note
It's important that you prefix your callback handlers with a plugin-specific prefix to avoid clashing with other plugins since the function symbols will be exported process-wide.
Parameters
pluginMust be geany_plugin.
builderThe GtkBuilder to connect signals with.
user_dataUser data to pass to the connected signal handlers.
Since
1.24, plugin API 217.
gpointer plugin_get_document_data ( struct GeanyPlugin plugin,
struct GeanyDocument doc,
const gchar *  key 
)

Retrieve plugin-specific data attached to a document.

Parameters
pluginThe plugin who attached the data.
docThe document which the data was attached to.
keyThe key name of the attached data.
Returns
The attached data pointer or NULL if the key is not found for the given plugin.
Since
1.29 (Plugin API 228)
See also
plugin_set_document_data plugin_set_document_data_full
guint plugin_idle_add ( GeanyPlugin plugin,
GSourceFunc  function,
gpointer  data 
)

Adds a GLib main loop IDLE callback that will be removed when unloading the plugin, preventing it to run after the plugin has been unloaded (which may lead to a segfault).

Parameters
pluginMust be geany_plugin.
functionThe function to call in IDLE time.
dataThe user data passed to the function.
Returns
the ID of the event source (you generally won't need it, or better use g_idle_add() directly if you want to manage this event source manually).
See also
g_idle_add()
Since
0.21, plugin API 205.
void plugin_module_make_resident ( GeanyPlugin plugin)

Ensures that a plugin's module (*.so) will never be unloaded.

This is necessary if you register new GTypes in your plugin, e.g. when using own classes using the GObject system.

Parameters
pluginMust be geany_plugin.
Since
0.16
void plugin_set_document_data ( struct GeanyPlugin plugin,
struct GeanyDocument doc,
const gchar *  key,
gpointer  data 
)

Attach plugin-specific data to a document.

Parameters
pluginThe plugin attaching data to the document.
docThe document to attach the data to.
keyThe key name for the data.
dataThe pointer to attach to the document.
Since
1.29 (Plugin API 228)
See also
plugin_get_document_data plugin_set_document_data_full
void plugin_set_document_data_full ( struct GeanyPlugin plugin,
struct GeanyDocument doc,
const gchar *  key,
gpointer  data,
GDestroyNotify  free_func 
)

Attach plugin-specific data and a free function to a document.

This is useful for plugins who want to keep some additional data with the document and even have it auto-released appropriately (see below).

This is a simple example showing how a plugin might use this to attach a string to each document and print it when the document is saved:

1 void on_document_open(GObject *unused, GeanyDocument *doc, GeanyPlugin *plugin)
2 {
3  plugin_set_document_data_full(plugin, doc, "my-data",
4  g_strdup("some-data"), g_free);
5 }
6 
7 void on_document_save(GObject *unused, GeanyDocument *doc, GeanyPlugin *plugin)
8 {
9  const gchar *some_data = plugin_get_document_data(plugin, doc, "my-data");
10  g_print("my-data: %s", some_data);
11 }
12 
13 gboolean plugin_init(GeanyPlugin *plugin, gpointer unused)
14 {
15  plugin_signal_connect(plugin, NULL, "document-open", TRUE,
16  G_CALLBACK(on_document_open), plugin);
17  plugin_signal_connect(plugin, NULL, "document-new", TRUE,
18  G_CALLBACK(on_document_open), plugin);
19  plugin_signal_connect(plugin, NULL, "document-save", TRUE,
20  G_CALLBACK(on_document_save), plugin);
21  return TRUE;
22 }
23 
24 void geany_load_module(GeanyPlugin *plugin)
25 {
26  // ...
27  plugin->funcs->init = plugin_init;
28  // ...
29 }

The free_func can be used to tie the lifetime of the data to that of the doc and/or the plugin. The free_func will be called in any of the following cases:

  • When a document is closed.
  • When the plugin is unloaded.
  • When the document data is set again using the same key.
Parameters
pluginThe plugin attaching data to the document.
docThe document to attach the data to.
keyThe key name for the data.
dataThe pointer to attach to the document.
free_funcThe function to call with data when removed.
Since
1.29 (Plugin API 228)
See also
plugin_get_document_data plugin_set_document_data
struct GeanyKeyGroup* plugin_set_key_group ( GeanyPlugin plugin,
const gchar *  section_name,
gsize  count,
GeanyKeyGroupCallback  callback 
)

Sets up or resizes a keybinding group for the plugin.

You should then call keybindings_set_item() for each keybinding in the group.

Parameters
pluginMust be geany_plugin.
section_nameName of the section used for this group in the keybindings configuration file, i.e. "html_chars".
countNumber of keybindings for the group.
callback Group callback, or NULL if you only want individual keybinding callbacks.
Returns
The plugin's keybinding group.
Since
0.19.
GeanyKeyGroup* plugin_set_key_group_full ( GeanyPlugin plugin,
const gchar *  section_name,
gsize  count,
GeanyKeyGroupFunc  cb,
gpointer  pdata,
GDestroyNotify  destroy_notify 
)

Sets up or resizes a keybinding group for the plugin.

You should then call keybindings_set_item() or keybindings_set_item_full() for each keybinding in the group.

Parameters
pluginMust be geany_plugin.
section_nameName of the section used for this group in the keybindings configuration file, i.e. "html_chars".
countNumber of keybindings for the group.
cb New-style group callback, or NULL if you only want individual keybinding callbacks.
pdataPlugin specific data, passed to the group callback cb.
destroy_notifyFunction that is invoked to free the plugin data when not needed anymore.
Returns
(transfer: none) The plugin's keybinding group.
Since
1.26 (API 226)
See also
See keybindings_set_item
See keybindings_set_item_full
void plugin_show_configure ( GeanyPlugin plugin)

Shows the plugin's configure dialog.

The plugin must implement one of the plugin_configure() or plugin_configure_single() symbols.

Parameters
pluginMust be geany_plugin.
Since
0.19.
void plugin_signal_connect ( GeanyPlugin plugin,
GObject *  object,
const gchar *  signal_name,
gboolean  after,
GCallback  callback,
gpointer  user_data 
)

Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault.

Parameters
pluginMust be geany_plugin.
object Object to connect to, or NULL when using Geany signals .
signal_nameThe name of the signal. For a list of available signals, please see the Signal documentation .
afterSet to TRUE to call your handler after the main signal handlers have been called (if supported by signal_name).
callbackThe function to call when the signal is emitted.
user_dataThe user data passed to the signal handler.
See also
plugin_callbacks.
Warning
Before version 1.25 (API < 218), this should only be used on objects that outlive the plugin, never on objects that will get destroyed before the plugin is unloaded. For objects created and destroyed by the plugin, you can simply use g_signal_connect(), since all handlers are disconnected when the object is destroyed anyway. For objects that may or may not outlive the plugin (like a document's ScintillaObject , which is destroyed when the document is closed), you currently have to manually handle both situations, when the plugin is unloaded before the object is destroyed (and then, you have to disconnect the signal on plugin_cleanup()), and when the object is destroyed during the plugin's lifetime (in which case you cannot and should not disconnect manually in plugin_cleanup() since it already has been disconnected and the object has been destroyed), and disconnect yourself or not as appropriate.
Note
Since version 1.25 (API >= 218), the object lifetime is watched and so the above restriction does not apply. However, for objects destroyed by the plugin, g_signal_connect() is safe and has lower overhead.
guint plugin_timeout_add ( GeanyPlugin plugin,
guint  interval,
GSourceFunc  function,
gpointer  data 
)

Adds a GLib main loop timeout callback that will be removed when unloading the plugin, preventing it to run after the plugin has been unloaded (which may lead to a segfault).

Parameters
pluginMust be geany_plugin.
intervalThe time between calls to the function, in milliseconds.
functionThe function to call after the given timeout.
dataThe user data passed to the function.
Returns
the ID of the event source (you generally won't need it, or better use g_timeout_add() directly if you want to manage this event source manually).
See also
g_timeout_add()
Since
0.21, plugin API 205.
guint plugin_timeout_add_seconds ( GeanyPlugin plugin,
guint  interval,
GSourceFunc  function,
gpointer  data 
)

Adds a GLib main loop timeout callback that will be removed when unloading the plugin, preventing it to run after the plugin has been unloaded (which may lead to a segfault).

Parameters
pluginMust be geany_plugin.
intervalThe time between calls to the function, in seconds.
functionThe function to call after the given timeout.
dataThe user data passed to the function.
Returns
the ID of the event source (you generally won't need it, or better use g_timeout_add_seconds() directly if you want to manage this event source manually).
See also
g_timeout_add_seconds()
Since
0.21, plugin API 205.