Geany  dev
Porting guide from legacy entry points to the current ones

Introduction

This page briefly describes the deprecated, legacy plugin entry points. These have been in place prior to Geany 1.26 and are still loadable and working for the time being. However, do not create new plugins against these. For this reason, the actual description here is rather minimalistic and concentrates on porting legacy plugins to the new interface. Basically its main purpose is to give newcomers an idea of what they are looking at if they come across a legacy plugin.

Overview

The legacy entry points consist of a number of pre-defined symbols (functions and variables) exported by plugins. There is no active registration procedure. It is implicit simply by exporting the mandatory symbols. The entirety of the symbols is described at the page Plugin Symbols .

At the very least plugins must define the functions plugin_init(GeanyData *) and plugin_version_check(gint). Additionally, an instance of the struct PluginInfo named plugin_info must be exported as well, this contains the same metadata already known from GeanyPlugin::info. The functions plugin_cleanup(), plugin_help(), plugin_configure(GtkDialog *) and plugin_configure_single(GtkWidget *) are optional, however Geany prints a warning if plugin_cleanup() is missing and only one of plugin_configure(GtkDialog *) and plugin_configure_single(GtkWidget *) is used for any single plugin.

By convention, plugin_version_check() is implicitly defined through the use of PLUGIN_VERSION_CHECK(), and similarly plugin_info is defined through PLUGIN_SET_INFO() or PLUGIN_SET_TRANSLATABLE_INFO().

The functions should generally perform the same tasks as their equivalents in GeanyPlugin::funcs.

Geany also recognized numerous variable fields if the plugin exported them globally, and actually set a few of them inside the plugins data section.

Porting a Legacy Plugin

Given a legacy plugin it can be modified to use the new entry points without much effort. This section gives a basic recipe that should work for most existing plugins. The transition should be easy and painless so it is recommended that you adapt your plugin as soon as possible.

Note
This guide is intentionally minimalistic (in terms of suggested code changes) in order to allow adaption to the current entry points as quickly as possible and without a lot effort. It should also work even for rather complex plugins comprising multiple source files. On the other hand it does not make use of new features such as geany_plugin_set_data().

Functions

Probably the biggest hurdle is the dropped support of the long-deprecated plugin_configure_single(). This means you first have to port the configuration dialog (if any) to the combined plugin dialog. While you previously created a custom dialog you now attach the main widget of that dialog to the combined plugin dialog simply by returning it from GeanyPluginFuncs::configure. You don't actually add it, Geany will do that for you. The pointer to the dialog is passed to configure simply to allow you to connect to its "response" or "close" signals.

The following lists the function mapping of previous plugin_* functions to the new GeanyPlugin::funcs. They are semantically the same, however the new functions receive more parameters which you may use or not.

Note
GeanyPluginFuncs::init() should return a boolean value: whether or not the plugin loaded successfully. Since legacy plugins couldn't fail in plugin_init() you should return TRUE unconditionally.
Again, plugin_configure_single() is not supported anymore.

Variables

Exported global variables are not recognized anymore. They are replaced in the following ways:

plugin_info is simply removed. Instead, you have to assign the values to GeanyPlugin::info yourself, and it must be done inside your geany_load_module().

Example:

"HelloWorld",
"Just another tool to say hello world",
"1.0", "John Doe <john.doe@example.org>");

becomes

G_MODULE_EXPORT
{
// ...
plugin->info->name = "HelloWorld";
plugin->info->description = "Just another tool to say hello world";
plugin->info->version = "1.0";
plugin->info->author = "John Doe <john.doe@example.org>";
// ...
}
Note
Refer to Translatable plugin information for i18n support for the metadata.

The plugin_callbacks array is supported by assigning the GeanyPluginFuncs::callbacks to the array.

plugin_fields is not supported anymore. Use ui_add_document_sensitive() instead. PLUGIN_KEY_GROUP and plugin_key_group are also not supported anymore. Use plugin_set_key_group() and keybindings_set_item() respectively.

Additionally, Geany traditionally set a few variables. This is not the case anymore. geany_functions has been removed in 1.25 and since then existed only for compatibility and has been empty. You can simply remove its declaration from your source code. geany_plugin is passed to each GeanyPluginFuncs function. You need to store it yourself somewhere if you need it elsewhere. geany_data is now available as a member of GeanyPlugin.

static gboolean my_init(GeanyPlugin *plugin, gpointer pdata)
{
// ...
geany_plugin = plugin;
geany_data = plugin->geany_data;
return TRUE;
}

geany_plugin is now also passed by default to the PluginCallback signal handlers as data pointer if it's set to NULL.

{ "editor-notify", (GCallback) &on_editor_notify_cb, FALSE, NULL },
// ...
};
static gboolean on_editor_notify_cb(GObject *object, GeanyEditor *editor,
SCNotification *nt, gpointer data)
{
GeanyPlugin *plugin = data;
//...
}
G_MODULE_EXPORT
{
// ...
// ...
}
}