Geany dev
Data Structures | Macros | Typedefs | Enumerations | Functions
plugindata.h File Reference

This file defines the plugin API, the interface between Geany and its plugins. More...

Data Structures

struct  GeanyData
 This contains pointers to global variables owned by Geany for plugins to use. More...
 
struct  GeanyPlugin
 Basic information for the plugin and identification. More...
 
struct  GeanyPluginFuncs
 Callback functions that need to be implemented for every plugin. More...
 
struct  GeanyProxyFuncs
 Hooks that need to be implemented by every proxy. More...
 
struct  PluginCallback
 Callback array entry type used with the plugin_callbacks symbol. More...
 
struct  PluginInfo
 Basic information about a plugin available to Geany without loading the plugin. More...
 

Macros

#define geany   geany_data
 Simple macro for geany_data that reduces typing.
 
#define GEANY_ABI_VERSION   (73 << GEANY_ABI_SHIFT)
 The Application Binary Interface (ABI) version, incremented whenever existing fields in the plugin data types have to be changed or reordered. More...
 
#define GEANY_API_VERSION   247
 The Application Programming Interface (API) version, incremented whenever any plugin data types are modified or appended to. More...
 
#define GEANY_PLUGIN_REGISTER(plugin, min_api_version)
 Convenience macro to register a plugin. More...
 
#define GEANY_PLUGIN_REGISTER_FULL(plugin, min_api_version, pdata, free_func)
 Convenience macro to register a plugin with data. More...
 
#define PLUGIN_SET_INFO(p_name, p_description, p_version, p_author)
 Sets the plugin name and some other basic information about a plugin. More...
 
#define PLUGIN_SET_TRANSLATABLE_INFO(localedir, package, p_name, p_description, p_version, p_author)
 Sets the plugin name and some other basic information about a plugin. More...
 
#define PLUGIN_VERSION_CHECK(api_required)
 Defines a function to check the plugin is safe to load. More...
 

Typedefs

typedef struct GeanyData GeanyData
 This contains pointers to global variables owned by Geany for plugins to use. More...
 
typedef struct GeanyPlugin GeanyPlugin
 Basic information for the plugin and identification. More...
 
typedef struct PluginCallback PluginCallback
 Callback array entry type used with the plugin_callbacks symbol.
 
typedef struct PluginInfo PluginInfo
 Basic information about a plugin available to Geany without loading the plugin. More...
 

Enumerations

enum  GeanyProxyProbeResults { GEANY_PROXY_IGNORE , GEANY_PROXY_MATCH , GEANY_PROXY_RELATED = GEANY_PROXY_MATCH | 0x100 }
 Return values for GeanyProxyHooks::probe() More...
 

Functions

void geany_load_module (GeanyPlugin *plugin)
 Called by Geany when a plugin library is loaded. More...
 
gpointer geany_plugin_get_data (const GeanyPlugin *plugin)
 Get the additional data that corresponds to the plugin. More...
 
gboolean geany_plugin_register (GeanyPlugin *plugin, gint api_version, gint min_api_version, gint abi_version)
 Register a plugin to Geany. More...
 
gboolean geany_plugin_register_full (GeanyPlugin *plugin, gint api_version, gint min_api_version, gint abi_version, gpointer data, GDestroyNotify free_func)
 Register a plugin to Geany, with plugin-defined data. More...
 
gint geany_plugin_register_proxy (GeanyPlugin *plugin, const gchar **extensions)
 Register the plugin as a proxy for other plugins. More...
 
void geany_plugin_set_data (GeanyPlugin *plugin, gpointer data, GDestroyNotify free_func)
 Add additional data that corresponds to the plugin. More...
 

Detailed Description

This file defines the plugin API, the interface between Geany and its plugins.

For detailed documentation of the plugin system please read the plugin API documentation.

Macro Definition Documentation

◆ GEANY_ABI_VERSION

#define GEANY_ABI_VERSION   (73 << GEANY_ABI_SHIFT)

The Application Binary Interface (ABI) version, incremented whenever existing fields in the plugin data types have to be changed or reordered.

Changing this forces all plugins to be recompiled before Geany can load them.

◆ GEANY_API_VERSION

#define GEANY_API_VERSION   247

The Application Programming Interface (API) version, incremented whenever any plugin data types are modified or appended to.

You can protect code that needs a higher API than e.g. 200 with:

#if GEANY_API_VERSION >= 200
some_newer_function();
#endif
Warning
You should not test for values below 200 as previously GEANY_API_VERSION was defined as an enum value, not a macro.

◆ GEANY_PLUGIN_REGISTER

#define GEANY_PLUGIN_REGISTER (   plugin,
  min_api_version 
)
Value:
(min_api_version), GEANY_ABI_VERSION)
#define GEANY_API_VERSION
The Application Programming Interface (API) version, incremented whenever any plugin data types are m...
Definition: plugindata.h:60
#define GEANY_ABI_VERSION
The Application Binary Interface (ABI) version, incremented whenever existing fields in the plugin da...
Definition: plugindata.h:71
gboolean geany_plugin_register(GeanyPlugin *plugin, gint api_version, gint min_api_version, gint abi_version)
Register a plugin to Geany.
Definition: plugins.c:315

Convenience macro to register a plugin.

It simply calls geany_plugin_register() with GEANY_API_VERSION and GEANY_ABI_VERSION.

Since
1.26 (API 225)
See also
Plugin HowTo

◆ GEANY_PLUGIN_REGISTER_FULL

#define GEANY_PLUGIN_REGISTER_FULL (   plugin,
  min_api_version,
  pdata,
  free_func 
)
Value:
(min_api_version), GEANY_ABI_VERSION, (pdata), (free_func))
gboolean geany_plugin_register_full(GeanyPlugin *plugin, gint api_version, gint min_api_version, gint abi_version, gpointer data, GDestroyNotify free_func)
Register a plugin to Geany, with plugin-defined data.
Definition: plugins.c:384

Convenience macro to register a plugin with data.

It simply calls geany_plugin_register_full() with GEANY_API_VERSION and GEANY_ABI_VERSION.

Since
1.26 (API 225)
See also
Plugin HowTo

◆ PLUGIN_SET_INFO

#define PLUGIN_SET_INFO (   p_name,
  p_description,
  p_version,
  p_author 
)
Value:
{ \
info->name = (p_name); \
info->description = (p_description); \
info->version = (p_version); \
info->author = (p_author); \
}
void plugin_set_info(PluginInfo *info)
Use the PLUGIN_SET_INFO() macro to define it.
Basic information about a plugin available to Geany without loading the plugin.
Definition: plugindata.h:94

Sets the plugin name and some other basic information about a plugin.

Note
If you want some of the arguments to be translated, see PLUGIN_SET_TRANSLATABLE_INFO()

Example:

PLUGIN_SET_INFO("Cool Feature", "Adds cool feature support.", "0.1", "Joe Author")
#define PLUGIN_SET_INFO(p_name, p_description, p_version, p_author)
Sets the plugin name and some other basic information about a plugin.
Definition: plugindata.h:116

◆ PLUGIN_SET_TRANSLATABLE_INFO

#define PLUGIN_SET_TRANSLATABLE_INFO (   localedir,
  package,
  p_name,
  p_description,
  p_version,
  p_author 
)
Value:
{ \
main_locale_init((localedir), (package)); \
info->name = (p_name); \
info->description = (p_description); \
info->version = (p_version); \
info->author = (p_author); \
}

Sets the plugin name and some other basic information about a plugin.

This macro is like PLUGIN_SET_INFO() but allows the passed information to be translated by setting up the translation mechanism with main_locale_init(). You therefore don't need to call it manually in plugin_init().

Example:

PLUGIN_SET_TRANSLATABLE_INFO(LOCALEDIR, GETTEXT_PACKAGE, _("Cool Feature"), _("Adds a cool feature."), "0.1", "John Doe")
#define PLUGIN_SET_TRANSLATABLE_INFO(localedir, package, p_name, p_description, p_version, p_author)
Sets the plugin name and some other basic information about a plugin.
Definition: plugindata.h:134
Since
0.19

◆ PLUGIN_VERSION_CHECK

#define PLUGIN_VERSION_CHECK (   api_required)
Value:
gint plugin_version_check(gint abi_ver) \
{ \
if (abi_ver != GEANY_ABI_VERSION) \
return -1; \
return (api_required); \
}
gint plugin_version_check(gint abi)
Use the PLUGIN_VERSION_CHECK() macro instead.

Defines a function to check the plugin is safe to load.

This performs runtime checks that try to ensure:

  • Geany ABI data types are compatible with this plugin.
  • Geany sources provide the required API for this plugin.
    Parameters
    api_requiredThe minimum API number your plugin requires. Look at the source for the value of GEANY_API_VERSION to use if you want your plugin to require the current Geany version on your machine. You should update this value when using any new API features.

Typedef Documentation

◆ GeanyData

typedef struct GeanyData GeanyData

This contains pointers to global variables owned by Geany for plugins to use.

Core variable pointers can be appended when needed by plugin authors, if appropriate.

◆ GeanyPlugin

typedef struct GeanyPlugin GeanyPlugin

Basic information for the plugin and identification.

See also
geany_plugin.

◆ PluginInfo

typedef struct PluginInfo PluginInfo

Basic information about a plugin available to Geany without loading the plugin.

The fields are set in plugin_set_info(), usually with the PLUGIN_SET_INFO() macro.

Enumeration Type Documentation

◆ GeanyProxyProbeResults

Return values for GeanyProxyHooks::probe()

See also
geany_plugin_register_proxy() for a full description of the proxy plugin mechanisms.
Enumerator
GEANY_PROXY_IGNORE 

The proxy is not responsible at all, and Geany or other plugins are free to probe it.

Since
1.29 (API 229)
GEANY_PROXY_MATCH 

The proxy is responsible for this file, and creates a plugin for it.

Since
1.29 (API 229)
GEANY_PROXY_RELATED 

The proxy is does not directly load it, but it's still tied to the proxy.

This is for plugins that come in multiple files where only one of these files is relevant for the plugin creation (for the PM dialog). The other files should be ignored by Geany and other proxies. Example: libpeas has a .plugin and a .so per plugin. Geany should not process the .so file if there is a corresponding .plugin.

Since
1.29 (API 229)

Function Documentation

◆ geany_load_module()

void geany_load_module ( GeanyPlugin plugin)

Called by Geany when a plugin library is loaded.

This is the original entry point. Implement and export this function to be loadable at all. Then fill in GeanyPlugin::info and GeanyPlugin::funcs of the passed plugin. Finally GEANY_PLUGIN_REGISTER() and specify a minimum supported API version.

For all glory details please read Plugin HowTo.

Because the plugin is not yet enabled by the user you may not call plugin API functions inside this function, except for the API functions below which are required for proper registration.

API functions which are allowed to be called within this function:

Parameters
pluginThe unique plugin handle to your plugin. You must set some fields here.
Since
1.26 (API 225)
See also
Plugin HowTo

◆ geany_plugin_get_data()

gpointer geany_plugin_get_data ( const GeanyPlugin plugin)

Get the additional data that corresponds to the plugin.

Parameters
pluginThe 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()

◆ geany_plugin_register()

gboolean geany_plugin_register ( GeanyPlugin plugin,
gint  api_version,
gint  min_api_version,
gint  abi_version 
)

Register a plugin to Geany.

The plugin will show up in the plugin manager. The user can interact with it based on the functions it provides and installed GUI elements.

You must initialize the info and funcs fields of GeanyPlugin appropriately prior to calling this, otherwise registration will fail. For info at least a valid name must be set (possibly localized). For funcs, at least init() and cleanup() functions must be implemented and set.

The return value must be checked. It may be FALSE if the plugin failed to register which can mainly happen for two reasons (future Geany versions may add new failure conditions):

  • Not all mandatory fields of GeanyPlugin have been set.
  • The ABI or API versions reported by the plugin are incompatible with the running Geany.

Do not call this directly. Use GEANY_PLUGIN_REGISTER() instead which automatically handles api_version and abi_version.

Parameters
pluginThe plugin provided by Geany
api_versionThe API version the plugin is compiled against (pass GEANY_API_VERSION)
min_api_versionThe minimum API version required by the plugin
abi_versionThe exact ABI version the plugin is compiled against (pass GEANY_ABI_VERSION)
Returns
TRUE if the plugin was successfully registered. Otherwise FALSE.
Since
1.26 (API 225)
See also
GEANY_PLUGIN_REGISTER()

◆ geany_plugin_register_full()

gboolean geany_plugin_register_full ( GeanyPlugin plugin,
gint  api_version,
gint  min_api_version,
gint  abi_version,
gpointer  pdata,
GDestroyNotify  free_func 
)

Register a plugin to Geany, with plugin-defined data.

This is a variant of geany_plugin_register() that also allows to set the plugin-defined data. Refer to that function for more details on registering in general.

pdata is the pointer going to be passed to the individual plugin callbacks of GeanyPlugin::funcs. When the plugin module is unloaded, free_func is invoked on pdata, which connects the data to the plugin's module life time.

You cannot use geany_plugin_set_data() after registering with this function. Use geany_plugin_register() if you need to.

Do not call this directly. Use GEANY_PLUGIN_REGISTER_FULL() instead which automatically handles api_version and abi_version.

Parameters
pluginThe plugin provided by Geany.
api_versionThe API version the plugin is compiled against (pass GEANY_API_VERSION).
min_api_versionThe minimum API version required by the plugin.
abi_versionThe exact ABI version the plugin is compiled against (pass GEANY_ABI_VERSION).
pdataPointer to the plugin-defined data. Must not be NULL.
free_funcFunction used to deallocate pdata, may be NULL.
Returns
TRUE if the plugin was successfully registered. Otherwise FALSE.
Since
1.26 (API 225)
See also
GEANY_PLUGIN_REGISTER_FULL()
geany_plugin_register()

◆ geany_plugin_register_proxy()

gint geany_plugin_register_proxy ( GeanyPlugin plugin,
const gchar **  extensions 
)

Register the plugin as a proxy for other plugins.

Proxy plugins register a list of file extensions and a set of callbacks that are called appropriately. A plugin can be a proxy for multiple types of sub-plugins by handling separate file extensions, however they must share the same set of hooks, because this function can only be called at most once per plugin.

Each callback receives the plugin-defined data as parameter (see geany_plugin_register()). The callbacks must be set prior to calling this, by assigning to plugin->proxy_funcs. GeanyProxyFuncs::load and GeanyProxyFuncs::unload must be implemented.

Nested proxies are unsupported at this point (TODO).

Note
It is entirely up to the proxy to provide access to Geany's plugin API. Native code can naturally call Geany's API directly, for interpreted languages the proxy has to implement some kind of bindings that the plugin can use.
See also
proxy for detailed documentation and an example.
Parameters
pluginThe pointer to the plugin's GeanyPlugin instance
extensionsA NULL-terminated string array of file extensions, excluding the dot.
Returns
TRUE if the proxy was successfully registered, otherwise FALSE
Since
1.26 (API 226)

◆ 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
pluginThe plugin provided by Geany
pdataThe plugin's data to associate, must not be NULL
free_funcThe destroy notify
Since
1.26 (API 225)