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  GeanyKeyGroupInfo
 
struct  GeanyPlugin
 Basic information for the plugin and identification. More...
 
struct  GeanyPluginFuncs
 Callback functions that need to be implemented for every plugin. More...
 
struct  PluginCallback
 Callback array entry type used with the plugin_callbacks symbol. More...
 
struct  PluginFields
 
struct  PluginInfo
 Basic information about a plugin available to Geany without loading the plugin. More...
 

Macros

#define DOC_IDX(doc_ptr)   (doc_ptr ? doc_ptr->index : -1)
 
#define geany   geany_data
 Simple macro for geany_data that reduces typing. More...
 
#define GEANY_ABI_VERSION   (71 << 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   225
 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)
 Convinience macro to register a plugin. More...
 
#define GEANY_PLUGIN_REGISTER_FULL(plugin, min_api_version, pdata, free_func)
 Convinience macro to register a plugin with data. More...
 
#define PLUGIN_KEY_GROUP(group_name, key_count)
 
#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 GeanyKeyGroupInfo GeanyKeyGroupInfo
 
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. More...
 
typedef struct PluginFields PluginFields
 
typedef struct PluginInfo PluginInfo
 Basic information about a plugin available to Geany without loading the plugin. More...
 

Enumerations

enum  PluginFlags { PLUGIN_IS_DOCUMENT_SENSITIVE = 1 << 0 }
 

Functions

void geany_load_module (GeanyPlugin *plugin)
 Called by Geany when a plugin library is loaded. 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...
 
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

#define DOC_IDX (   doc_ptr)    (doc_ptr ? doc_ptr->index : -1)
Deprecated:
  • copy into your plugin code if needed.

NULL-safe way to get the index of doc_ptr in the documents array.

#define geany   geany_data

Simple macro for geany_data that reduces typing.

#define GEANY_ABI_VERSION   (71 << 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.

#define GEANY_API_VERSION   225

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.
#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:61
gboolean geany_plugin_register(GeanyPlugin *plugin, gint api_version, gint min_api_version, gint abi_version)
Register a plugin to Geany.
Definition: plugins.c:291
#define GEANY_ABI_VERSION
The Application Binary Interface (ABI) version, incremented whenever existing fields in the plugin da...
Definition: plugindata.h:75

Convinience 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
#define GEANY_PLUGIN_REGISTER_FULL (   plugin,
  min_api_version,
  pdata,
  free_func 
)
Value:
(min_api_version), GEANY_ABI_VERSION, (pdata), (free_func))
#define GEANY_API_VERSION
The Application Programming Interface (API) version, incremented whenever any plugin data types are m...
Definition: plugindata.h:61
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:358
#define GEANY_ABI_VERSION
The Application Binary Interface (ABI) version, incremented whenever existing fields in the plugin da...
Definition: plugindata.h:75

Convinience 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
#define PLUGIN_KEY_GROUP (   group_name,
  key_count 
)
Value:
/* We have to declare this as a single element array.
* Declaring as a pointer to a struct doesn't work with g_module_symbol(). */ \
GeanyKeyGroupInfo plugin_key_group_info[1] = \
{ \
{G_STRINGIFY(group_name), key_count} \
};\
struct GeanyKeyGroup GeanyKeyGroup
A collection of keybindings grouped together.
Definition: keybindings.h:71
struct GeanyKeyGroupInfo GeanyKeyGroupInfo
KeyBindingGroup * plugin_key_group
Plugins must use the PLUGIN_KEY_GROUP() macro to define it.
Definition: pluginsymbols.c:79
Deprecated:

Declare and initialise a keybinding group.

You must then set the plugin_key_group::keys[] entries for the group in plugin_init(), normally using keybindings_set_item(). The plugin_key_group::label field is set by Geany after plugin_init() is called, to the name of the plugin.

Parameters
group_nameA unique group name (without quotes) to be used in the configuration file, such as html_chars.
key_countThe number of keybindings the group will hold.
#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:97

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_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); \
}
void plugin_set_info(PluginInfo *info)
Use the PLUGIN_SET_INFO() macro to define it.
void main_locale_init(const gchar *locale_dir, const gchar *gettext_package)
Initialises the gettext translation system.
Definition: libmain.c:450
Basic information about a plugin available to Geany without loading the plugin.
Definition: plugindata.h:97

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
#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)
Use the PLUGIN_VERSION_CHECK() macro instead.
#define GEANY_ABI_VERSION
The Application Binary Interface (ABI) version, incremented whenever existing fields in the plugin da...
Definition: plugindata.h:75

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

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.

typedef struct GeanyPlugin GeanyPlugin

Basic information for the plugin and identification.

See Also
geany_plugin.

Callback array entry type used with the plugin_callbacks symbol.

typedef struct PluginFields PluginFields
Deprecated:
Use ui_add_document_sensitive() instead.

Fields set and owned by the plugin.

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

Deprecated:
Use ui_add_document_sensitive() instead.

Flags to be set by plugins in PluginFields struct.

Enumerator
PLUGIN_IS_DOCUMENT_SENSITIVE 

Whether a plugin's menu item should be disabled when there are no open documents.

Function Documentation

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