#include "pluginutils.h"
#include "app.h"
#include "geanyobject.h"
#include "keybindings.h"
#include "keybindingsprivate.h"
#include "plugindata.h"
#include "pluginprivate.h"
#include "plugins.h"
#include "support.h"
#include "toolbar.h"
#include "ui_utils.h"
#include "utils.h"

Include dependency graph for pluginutils.c:

Classes
struct	PluginDocDataProxy

struct	PluginSourceData

struct	BuilderConnectData

Typedefs
typedef struct PluginSourceData	PluginSourceData

Functions
gint	geany_api_version (void)
	Returns the runtime API version Geany was compiled with. More...

void	plugin_add_toolbar_item (GeanyPlugin plugin, GtkToolItem item)
	Inserts a toolbar item before the Quit button, or after the previous plugin toolbar item. More...

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

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. More...

static void	psd_register (PluginSourceData psd, GSource source)

static void	psd_unregister (PluginSourceData *psd)

static void	on_plugin_source_destroy (gpointer data)

static gboolean	on_plugin_source_callback (gpointer data)

static guint	plugin_source_add (GeanyPlugin plugin, GSource source, GSourceFunc func, gpointer data)

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). More...

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). More...

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). More...

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. More...

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. More...

static void	on_pref_btn_clicked (gpointer btn, Plugin *p)

static GtkWidget *	create_pref_page (Plugin p, GtkWidget dialog)

static void	configure_plugins (Plugin *current_plugin)

void	plugin_show_configure (GeanyPlugin *plugin)
	Shows the plugin's configure dialog. More...

static void	connect_plugin_signals (GtkBuilder builder, GObject object, const gchar signal_name, const gchar handler_name, GObject *connect_object, GConnectFlags flags, gpointer user_data)

void	plugin_builder_connect_signals (GeanyPlugin plugin, GtkBuilder builder, gpointer user_data)
	Allows auto-connecting Glade/GtkBuilder signals in plugins. More...

gpointer	geany_plugin_get_data (const GeanyPlugin *plugin)
	Get the additional data that corresponds to the plugin. More...

void	geany_plugin_set_data (GeanyPlugin *plugin, gpointer pdata, GDestroyNotify free_func)
	Add additional data that corresponds to the plugin. More...

static void	plugin_doc_data_proxy_free (gpointer pdata)

gpointer	plugin_get_document_data (struct GeanyPlugin plugin, struct GeanyDocument doc, const gchar *key)
	Retrieve plugin-specific data attached to a document. 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...

Typedef Documentation

◆ PluginSourceData

typedef struct PluginSourceData PluginSourceData

Function Documentation

◆ configure_plugins()

static void configure_plugins ( Plugin * current_plugin )

static

Definition at line 420 of file pluginutils.c.

References _, active_plugin_list, create_pref_page(), dialog, foreach_list, gtk_widget_show_all(), GeanyPluginPrivate::info, label, main_widgets, PluginInfo::name, NULL, ui_dialog_vbox_new(), utils_beep(), and GeanyMainWidgets::window.

Referenced by plugin_show_configure().

◆ connect_plugin_signals()

static void connect_plugin_signals	(	GtkBuilder *	builder,
		GObject *	object,
		const gchar *	signal_name,
		const gchar *	handler_name,
		GObject *	connect_object,
		GConnectFlags	flags,
		gpointer	user_data
	)

static

Definition at line 502 of file pluginutils.c.

References NULL, BuilderConnectData::plugin, plugin_get_module_symbol(), plugin_signal_connect(), GeanyPlugin::priv, and BuilderConnectData::user_data.

Referenced by plugin_builder_connect_signals().

◆ create_pref_page()

static GtkWidget * create_pref_page	(	Plugin *	p,
		GtkWidget *	dialog
	)

static

Definition at line 379 of file pluginutils.c.

References GeanyPluginPrivate::cb_data, GeanyPluginPrivate::cbs, GeanyPluginFuncs::configure, GeanyPluginPrivate::configure_single, dialog, geany_debug(), gtk_container_add(), GeanyPluginPrivate::info, PluginInfo::name, NULL, on_pref_btn_clicked(), and GeanyPluginPrivate::public.

Referenced by configure_plugins().

◆ geany_api_version()

gint geany_api_version ( void )

Returns the runtime API version Geany was compiled with.

Unlike GEANY_API_VERSION this version is the value of that define at the time when Geany itself was compiled. This allows to establish soft dependencies which are resolved at runtime depending on Geany's API version.

Returns: Geany's API version

Since: 1.30 (API 231)

Definition at line 65 of file pluginutils.c.

References GEANY_API_VERSION.

◆ geany_plugin_get_data()

gpointer geany_plugin_get_data ( const GeanyPlugin * plugin )

Get the additional data that corresponds to the plugin.

Parameters

plugin The plugin provided by Geany

Returns: The data corresponding to the plugin or NULL if none set.

Since: 1.32 (API 234)

See also: geany_plugin_set_data()

Definition at line 581 of file pluginutils.c.

References GeanyPluginPrivate::cb_data, NULL, BuilderConnectData::plugin, PLUGIN_LOADED_OK, and GeanyPlugin::priv.

◆ geany_plugin_set_data()

void geany_plugin_set_data	(	GeanyPlugin *	plugin,
		gpointer	pdata,
		GDestroyNotify	free_func
	)

Add additional data that corresponds to the plugin.

pdata is the pointer going to be passed to the individual plugin callbacks of GeanyPlugin::funcs. When the plugin is cleaned up, free_func is invoked for the data, which connects the data to the time the plugin is enabled.

One intended use case is to set GObjects as data and have them destroyed automatically by passing g_object_unref() as free_func, so that member functions can be used for the GeanyPluginFuncs (via wrappers) but you can set completely custom data.

Be aware that this can only be called once and only by plugins registered via geany_plugin_register(). So-called legacy plugins cannot use this function.

Note: This function must not be called if the plugin was registered with geany_plugin_register_full().

Parameters

plugin	The plugin provided by Geany
pdata	The plugin's data to associate, must not be `NULL`
free_func	The destroy notify

Since: 1.26 (API 225)

Definition at line 613 of file pluginutils.c.

References GeanyPluginPrivate::cb_data, GeanyPluginPrivate::cb_data_destroy, NULL, BuilderConnectData::plugin, PLUGIN_HAS_LOAD_DATA, PLUGIN_LOADED_OK, and GeanyPlugin::priv.

Referenced by demo_init(), geany_plugin_register_full(), and register_legacy_plugin().

◆ on_plugin_source_callback()

static gboolean on_plugin_source_callback ( gpointer data )

static

Definition at line 229 of file pluginutils.c.

References PluginSourceData::function, and PluginSourceData::user_data.

Referenced by plugin_source_add().

◆ on_plugin_source_destroy()

static void on_plugin_source_destroy ( gpointer data )

static

Definition at line 220 of file pluginutils.c.

References psd_unregister().

Referenced by plugin_source_add().

◆ on_pref_btn_clicked()

static void on_pref_btn_clicked	(	gpointer	btn,
		Plugin *	p
	)

static

Definition at line 373 of file pluginutils.c.

References GeanyPluginPrivate::configure_single, main_widgets, and GeanyMainWidgets::window.

Referenced by create_pref_page().

◆ plugin_add_toolbar_item()

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

plugin	Must be geany_plugin.
item	The item to add.

Definition at line 77 of file pluginutils.c.

References main_widgets, pos, GeanyPlugin::priv, GeanyMainWidgets::toolbar, toolbar_get_insert_position(), toolbar_item_ref(), GeanyPluginPrivate::toolbar_separator, and ui_auto_separator_add_ref().

◆ plugin_builder_connect_signals()

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.

...
GeanyPlugin *geany_plugin;
 
G_MODULE_EXPORT void
myplugin_button_clicked(GtkButton *button, gpointer user_data)
{
  g_print("Button pressed\n");
}
 
void plugin_init(GeanyData *data)
{
  GtkBuilder *builder = gtk_builder_new();
  gtk_builder_add_from_file(builder, "gui.glade", NULL);
  plugin_builder_connect_signals(geany_plugin, builder, NULL);
  ...
}

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

plugin	Must be geany_plugin.
builder	The GtkBuilder to connect signals with.
user_data	User data to pass to the connected signal handlers.

Since: 1.24, plugin API 217.

Definition at line 557 of file pluginutils.c.

References builder, connect_plugin_signals(), NULL, BuilderConnectData::plugin, GeanyPlugin::priv, and BuilderConnectData::user_data.

◆ plugin_doc_data_proxy_free()

static void plugin_doc_data_proxy_free ( gpointer pdata )

static

Definition at line 643 of file pluginutils.c.

References PluginDocDataProxy::data, PluginDocDataProxy::free_func, and NULL.

Referenced by plugin_set_document_data_full().

◆ plugin_get_document_data()

gpointer plugin_get_document_data	(	struct GeanyPlugin *	plugin,
		struct GeanyDocument *	doc,
		const gchar *	key
	)

Retrieve plugin-specific data attached to a document.

Parameters

plugin	The plugin who attached the data.
doc	The document which the data was attached to.
key	The 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

Definition at line 669 of file pluginutils.c.

References PluginDocDataProxy::data, document_get_data(), GeanyPlugin::info, PluginInfo::name, NULL, and BuilderConnectData::plugin.

◆ plugin_idle_add()

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

plugin	Must be geany_plugin.
function	The function to call in IDLE time.
data	The 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.

Definition at line 314 of file pluginutils.c.

References plugin_source_add().

Referenced by on_document_close(), and on_document_focus_out().

◆ plugin_module_make_resident()

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

plugin Must be geany_plugin.

Since: 0.16

Definition at line 121 of file pluginutils.c.

References plugin_make_resident(), and GeanyPlugin::priv.

◆ plugin_set_document_data()

void plugin_set_document_data	(	struct GeanyPlugin *	plugin,
		struct GeanyDocument *	doc,
		const gchar *	key,
		gpointer	data
	)

Attach plugin-specific data to a document.

Parameters

plugin	The plugin attaching data to the document.
doc	The document to attach the data to.
key	The key name for the data.
data	The pointer to attach to the document.

Since: 1.29 (Plugin API 228)

See also: plugin_get_document_data plugin_set_document_data_full

Definition at line 699 of file pluginutils.c.

References NULL, BuilderConnectData::plugin, and plugin_set_document_data_full().

◆ 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:

void on_document_open(GObject *unused, GeanyDocument *doc, GeanyPlugin *plugin)
{
    plugin_set_document_data_full(plugin, doc, "my-data",
        g_strdup("some-data"), g_free);
}
 
void on_document_save(GObject *unused, GeanyDocument *doc, GeanyPlugin *plugin)
{
    const gchar *some_data = plugin_get_document_data(plugin, doc, "my-data");
    g_print("my-data: %s\n", some_data);
}
 
gboolean plugin_init(GeanyPlugin *plugin, gpointer unused)
{
    plugin_signal_connect(plugin, NULL, "document-open", TRUE,
        G_CALLBACK(on_document_open), plugin);
    plugin_signal_connect(plugin, NULL, "document-new", TRUE,
        G_CALLBACK(on_document_open), plugin);
    plugin_signal_connect(plugin, NULL, "document-save", TRUE,
        G_CALLBACK(on_document_save), plugin);
    return TRUE;
}
 
void geany_load_module(GeanyPlugin *plugin)
{
  // ...
  plugin->funcs->init = plugin_init;
  // ...
}

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

plugin	The plugin attaching data to the document.
doc	The document to attach the data to.
key	The key name for the data.
data	The pointer to attach to the document.
free_func	The function to call with data when removed.

Since: 1.29 (Plugin API 228)

See also: plugin_get_document_data plugin_set_document_data

Definition at line 766 of file pluginutils.c.

References PluginDocDataProxy::data, document_set_data_full(), PluginDocDataProxy::free_func, GeanyPlugin::info, PluginInfo::name, NULL, BuilderConnectData::plugin, and plugin_doc_data_proxy_free().

Referenced by plugin_set_document_data().

◆ plugin_set_key_group()

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

plugin	Must be geany_plugin.
section_name	Name of the section used for this group in the keybindings configuration file, i.e. `"html_chars"`.
count	Number 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.

Definition at line 331 of file pluginutils.c.

References count, keybindings_set_group(), GeanyPlugin::priv, and priv.

Referenced by plugin_init(), plugin_set_key_group_full(), and read_key_group().

◆ plugin_set_key_group_full()

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

plugin	Must be geany_plugin.
section_name	Name of the section used for this group in the keybindings configuration file, i.e. `"html_chars"`.
count	Number of keybindings for the group.
cb	New-style group callback, or `NULL` if you only want individual keybinding callbacks.
pdata	Plugin specific data, passed to the group callback cb.
destroy_notify	Function 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

Definition at line 358 of file pluginutils.c.

References count, group, NULL, and plugin_set_key_group().

◆ plugin_show_configure()

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

plugin Must be geany_plugin.

Since: 0.19.

Definition at line 474 of file pluginutils.c.

References GeanyPluginPrivate::cbs, GeanyPluginFuncs::configure, configure_plugins(), GeanyPluginPrivate::configure_single, main_widgets, NULL, GeanyPlugin::priv, and GeanyMainWidgets::window.

Referenced by on_plugin_preferences1_activate(), on_show_preferences(), and pm_on_plugin_button_clicked().

◆ plugin_signal_connect()

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

plugin	Must be geany_plugin.
object	Object to connect to, or `NULL` when using Geany signals .
signal_name	The name of the signal. For a list of available signals, please see the Signal documentation .
after	Set to `TRUE` to call your handler after the main signal handlers have been called (if supported by signal_name).
callback	The function to call when the signal is emitted.
user_data	The 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.

Definition at line 158 of file pluginutils.c.

References geany_object, SignalConnection::handler_id, NULL, SignalConnection::object, plugin_watch_object(), GeanyPlugin::priv, and GeanyPluginPrivate::signal_ids.

Referenced by add_callbacks(), connect_plugin_signals(), and plugin_init().

◆ plugin_source_add()

static guint plugin_source_add	(	GeanyPlugin *	plugin,
		GSource *	source,
		GSourceFunc	func,
		gpointer	data
	)

static

Definition at line 239 of file pluginutils.c.

References PluginSourceData::function, NULL, on_plugin_source_callback(), on_plugin_source_destroy(), PluginSourceData::plugin, GeanyPlugin::priv, psd_register(), and PluginSourceData::user_data.

Referenced by plugin_idle_add(), plugin_timeout_add(), and plugin_timeout_add_seconds().

◆ plugin_timeout_add()

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

plugin	Must be geany_plugin.
interval	The time between calls to the function, in milliseconds.
function	The function to call after the given timeout.
data	The 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.

Definition at line 272 of file pluginutils.c.

References plugin_source_add().

◆ plugin_timeout_add_seconds()

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

plugin	Must be geany_plugin.
interval	The time between calls to the function, in seconds.
function	The function to call after the given timeout.
data	The 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.

Definition at line 293 of file pluginutils.c.

References plugin_source_add().

◆ psd_register()

static void psd_register	(	PluginSourceData *	psd,
		GSource *	source
	)

static

Definition at line 197 of file pluginutils.c.

References PluginSourceData::list_link, NULL, PluginSourceData::plugin, and GeanyPluginPrivate::sources.

Referenced by plugin_source_add().

◆ psd_unregister()

static void psd_unregister ( PluginSourceData * psd )

static

Definition at line 209 of file pluginutils.c.

References PluginSourceData::list_link, PluginSourceData::plugin, and GeanyPluginPrivate::sources.

Referenced by on_plugin_source_destroy().

Classes

Typedefs

Functions

Typedef Documentation

◆ PluginSourceData

Function Documentation

◆ configure_plugins()

◆ connect_plugin_signals()

◆ create_pref_page()

◆ geany_api_version()

◆ geany_plugin_get_data()

◆ geany_plugin_set_data()

◆ on_plugin_source_callback()

◆ on_plugin_source_destroy()

◆ on_pref_btn_clicked()

◆ plugin_add_toolbar_item()

◆ plugin_builder_connect_signals()

◆ plugin_doc_data_proxy_free()

◆ plugin_get_document_data()

◆ plugin_idle_add()

◆ plugin_module_make_resident()

◆ plugin_set_document_data()

◆ plugin_set_document_data_full()

◆ plugin_set_key_group()

◆ plugin_set_key_group_full()

◆ plugin_show_configure()

◆ plugin_signal_connect()

◆ plugin_source_add()

◆ plugin_timeout_add()

◆ plugin_timeout_add_seconds()

◆ psd_register()

◆ psd_unregister()