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   248
	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   248

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:

    geany_plugin_register((plugin), GEANY_API_VERSION, \
                          (min_api_version), GEANY_ABI_VERSION)

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:

    geany_plugin_register_full((plugin), GEANY_API_VERSION, \
                               (min_api_version), GEANY_ABI_VERSION, (pdata), (free_func))

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:

    void plugin_set_info(PluginInfo *info) \
    { \
        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.

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") 

PLUGIN_SET_TRANSLATABLE_INFO

#define PLUGIN_SET_TRANSLATABLE_INFO	(		localedir,
			package,
			p_name,
			p_description,
			p_version,
			p_author
	)

Value:

    void plugin_set_info(PluginInfo *info) \
    { \
        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") 

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); \
    }

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_required

  The 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

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

• main_locale_init()
• geany_plugin_register() (and GEANY_PLUGIN_REGISTER())
• geany_plugin_register_full() (and GEANY_PLUGIN_REGISTER_FULL())
• plugin_module_make_resident()

Parameters

plugin

The 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

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

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

plugin	The plugin provided by Geany
api_version	The API version the plugin is compiled against (pass GEANY_API_VERSION)
min_api_version	The minimum API version required by the plugin
abi_version	The 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

plugin	The plugin provided by Geany.
api_version	The API version the plugin is compiled against (pass GEANY_API_VERSION).
min_api_version	The minimum API version required by the plugin.
abi_version	The exact ABI version the plugin is compiled against (pass GEANY_ABI_VERSION).
pdata	Pointer to the plugin-defined data. Must not be NULL.
free_func	Function 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

plugin	The pointer to the plugin's GeanyPlugin instance
extensions	A 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

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)