2 * plugindata.h - this file is part of Geany, a fast and lightweight IDE
4 * Copyright 2007-2012 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
5 * Copyright 2007-2012 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License along
18 * with this program; if not, write to the Free Software Foundation, Inc.,
19 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 * This file defines the plugin API, the interface between Geany and its plugins.
25 * For detailed documentation of the plugin system please read the plugin
28 /* Note: Remember to increment GEANY_API_VERSION (and GEANY_ABI_VERSION if necessary)
29 * when making changes (see 'Keeping the plugin ABI stable' in the HACKING file). */
32 #ifndef GEANY_PLUGIN_DATA_H
33 #define GEANY_PLUGIN_DATA_H 1
35 #include "build.h" /* GeanyBuildGroup, GeanyBuildSource, GeanyBuildCmdEntries enums */
36 #include "document.h" /* GeanyDocument */
37 #include "editor.h" /* GeanyEditor, GeanyIndentType */
38 #include "filetypes.h" /* GeanyFiletype */
40 #include "gtkcompat.h"
44 /* Compatibility for sharing macros between API and core.
45 * First include geany.h, then plugindata.h, then other API headers. */
47 #define GEANY(symbol_name) geany->symbol_name
50 /** The Application Programming Interface (API) version, incremented
51 * whenever any plugin data types are modified or appended to.
53 * You can protect code that needs a higher API than e.g. 200 with:
54 * @code #if GEANY_API_VERSION >= 200
55 * some_newer_function();
58 * @warning You should not test for values below 200 as previously
59 * @c GEANY_API_VERSION was defined as an enum value, not a macro.
61 #define GEANY_API_VERSION 224
63 /* hack to have a different ABI when built with GTK3 because loading GTK2-linked plugins
64 * with GTK3-linked Geany leads to crash */
65 #if GTK_CHECK_VERSION(3, 0, 0)
66 # define GEANY_ABI_SHIFT 8
68 # define GEANY_ABI_SHIFT 0
70 /** The Application Binary Interface (ABI) version, incremented whenever
71 * existing fields in the plugin data types have to be changed or reordered.
72 * Changing this forces all plugins to be recompiled before Geany can load them. */
73 /* This should usually stay the same if fields are only appended, assuming only pointers to
74 * structs and not structs themselves are declared by plugins. */
75 #define GEANY_ABI_VERSION (71 << GEANY_ABI_SHIFT)
78 /** Defines a function to check the plugin is safe to load.
79 * This performs runtime checks that try to ensure:
80 * - Geany ABI data types are compatible with this plugin.
81 * - Geany sources provide the required API for this plugin.
82 * @param api_required The minimum API number your plugin requires.
83 * Look at the source for the value of @c GEANY_API_VERSION to use if you
84 * want your plugin to require the current Geany version on your machine.
85 * You should update this value when using any new API features. */
86 #define PLUGIN_VERSION_CHECK(api_required) \
87 gint plugin_version_check(gint abi_ver) \
89 if (abi_ver != GEANY_ABI_VERSION) \
91 return (api_required); \
95 /** Basic information about a plugin available to Geany without loading the plugin.
96 * The fields are set in plugin_set_info(), usually with the PLUGIN_SET_INFO() macro. */
97 typedef struct PluginInfo
99 /** The name of the plugin. */
101 /** The description of the plugin. */
102 const gchar
*description
;
103 /** The version of the plugin. */
104 const gchar
*version
;
105 /** The author of the plugin. */
111 /** Sets the plugin name and some other basic information about a plugin.
113 * @note If you want some of the arguments to be translated, see @ref PLUGIN_SET_TRANSLATABLE_INFO()
116 * @code PLUGIN_SET_INFO("Cool Feature", "Adds cool feature support.", "0.1", "Joe Author") @endcode */
117 /* plugin_set_info() could be written manually for plugins if we want to add any
118 * extra PluginInfo features (such as an icon), so we don't need to break API
119 * compatibility. Alternatively just add a new macro, PLUGIN_SET_INFO_FULL(). -ntrel */
120 #define PLUGIN_SET_INFO(p_name, p_description, p_version, p_author) \
121 void plugin_set_info(PluginInfo *info) \
123 info->name = (p_name); \
124 info->description = (p_description); \
125 info->version = (p_version); \
126 info->author = (p_author); \
129 /** Sets the plugin name and some other basic information about a plugin.
130 * This macro is like @ref PLUGIN_SET_INFO() but allows the passed information to be translated
131 * by setting up the translation mechanism with @ref main_locale_init().
132 * You therefore don't need to call it manually in plugin_init().
135 * @code PLUGIN_SET_TRANSLATABLE_INFO(LOCALEDIR, GETTEXT_PACKAGE, _("Cool Feature"), _("Adds a cool feature."), "0.1", "John Doe") @endcode
138 #define PLUGIN_SET_TRANSLATABLE_INFO(localedir, package, p_name, p_description, p_version, p_author) \
139 void plugin_set_info(PluginInfo *info) \
141 main_locale_init((localedir), (package)); \
142 info->name = (p_name); \
143 info->description = (p_description); \
144 info->version = (p_version); \
145 info->author = (p_author); \
149 /** @deprecated - use plugin_set_key_group() instead.
150 * @see PLUGIN_KEY_GROUP() macro. */
151 typedef struct GeanyKeyGroupInfo
153 const gchar
*name
; /**< Group name used in the configuration file, such as @c "html_chars" */
154 gsize count
; /**< The number of keybindings the group will hold */
158 /** @deprecated - use plugin_set_key_group() instead.
159 * Declare and initialise a keybinding group.
160 * @code GeanyKeyGroup *plugin_key_group; @endcode
161 * You must then set the @c plugin_key_group::keys[] entries for the group in plugin_init(),
162 * normally using keybindings_set_item().
163 * The @c plugin_key_group::label field is set by Geany after @c plugin_init()
164 * is called, to the name of the plugin.
165 * @param group_name A unique group name (without quotes) to be used in the
166 * configuration file, such as @c html_chars.
167 * @param key_count The number of keybindings the group will hold. */
168 #define PLUGIN_KEY_GROUP(group_name, key_count) \
169 /* We have to declare this as a single element array.
170 * Declaring as a pointer to a struct doesn't work with g_module_symbol(). */ \
171 GeanyKeyGroupInfo plugin_key_group_info[1] = \
173 {G_STRINGIFY(group_name), key_count} \
175 GeanyKeyGroup *plugin_key_group = NULL;
178 /** Callback array entry type used with the @ref plugin_callbacks symbol. */
179 typedef struct PluginCallback
181 /** The name of signal, must be an existing signal. For a list of available signals,
182 * please see the @link pluginsignals.c Signal documentation @endlink. */
183 const gchar
*signal_name
;
184 /** A callback function which is called when the signal is emitted. */
186 /** Set to TRUE to connect your handler with g_signal_connect_after(). */
188 /** The user data passed to the signal handler. */
194 /** @deprecated Use @ref ui_add_document_sensitive() instead.
195 * Flags to be set by plugins in PluginFields struct. */
198 /** Whether a plugin's menu item should be disabled when there are no open documents */
199 PLUGIN_IS_DOCUMENT_SENSITIVE
= 1 << 0
203 /** @deprecated Use @ref ui_add_document_sensitive() instead.
204 * Fields set and owned by the plugin. */
205 typedef struct PluginFields
207 /** Bitmask of @c PluginFlags. */
209 /** Pointer to a plugin's menu item which will be automatically enabled/disabled when there
210 * are no open documents and @c PLUGIN_IS_DOCUMENT_SENSITIVE is set.
211 * This is required if using @c PLUGIN_IS_DOCUMENT_SENSITIVE, ignored otherwise */
212 GtkWidget
*menu_item
;
217 /** This contains pointers to global variables owned by Geany for plugins to use.
218 * Core variable pointers can be appended when needed by plugin authors, if appropriate. */
219 typedef struct GeanyData
221 struct GeanyApp
*app
; /**< Geany application data fields */
222 struct GeanyMainWidgets
*main_widgets
; /**< Important widgets in the main window */
223 GPtrArray
*documents_array
; /**< See document.h#documents_array. */
224 GPtrArray
*filetypes_array
; /**< Dynamic array of GeanyFiletype pointers */
225 struct GeanyPrefs
*prefs
; /**< General settings */
226 struct GeanyInterfacePrefs
*interface_prefs
; /**< Interface settings */
227 struct GeanyToolbarPrefs
*toolbar_prefs
; /**< Toolbar settings */
228 struct GeanyEditorPrefs
*editor_prefs
; /**< Editor settings */
229 struct GeanyFilePrefs
*file_prefs
; /**< File-related settings */
230 struct GeanySearchPrefs
*search_prefs
; /**< Search-related settings */
231 struct GeanyToolPrefs
*tool_prefs
; /**< Tool settings */
232 struct GeanyTemplatePrefs
*template_prefs
; /**< Template settings */
233 struct GeanyBuildInfo
*build_info
; /**< Current build information */
234 GSList
*filetypes_by_title
; /**< See filetypes.h#filetypes_by_title. */
238 #define geany geany_data /**< Simple macro for @c geany_data that reduces typing. */
240 /** Basic information for the plugin and identification.
241 * @see geany_plugin. */
242 typedef struct GeanyPlugin
244 PluginInfo
*info
; /**< Fields set in plugin_set_info(). */
245 GeanyData
*geany_data
; /**< Pointer to global GeanyData intance */
247 struct GeanyPluginPrivate
*priv
; /* private */
251 #ifndef GEANY_PRIVATE
253 /* Prototypes for building plugins with -Wmissing-prototypes
254 * Also allows the compiler to check if the signature of the plugin's
255 * symbol properly matches what we expect. */
256 gint
plugin_version_check(gint abi_ver
);
257 void plugin_set_info(PluginInfo
*info
);
259 void plugin_init(GeanyData
*data
);
260 GtkWidget
*plugin_configure(GtkDialog
*dialog
);
261 void plugin_configure_single(GtkWidget
*parent
);
262 void plugin_help(void);
263 void plugin_cleanup(void);
265 /** Called by Geany when a plugin library is loaded.
267 * This is the original entry point. Implement and export this function to be loadable at all.
268 * Then fill in GeanyPlugin::info and GeanyPlugin::funcs of the passed @p plugin. Finally
269 * GEANY_PLUGIN_REGISTER() and specify a minimum supported API version.
271 * @param plugin The unique plugin handle to your plugin. You must set some fields here.
273 * @since 1.26 (API 225)
275 gboolean
geany_load_module(GeanyPlugin
*plugin
);
279 /** Callback functions that need to be implemented for every plugin.
281 * These callbacks should be registered by the plugin within Geany's call to
282 * geany_load_module() by calling geany_plugin_register() with an instance of this type.
284 * Geany will then call the callbacks at appropriate times. Each gets passed the
285 * plugin-defined data pointer as well as the corresponding GeanyPlugin instance
288 * @since 1.26 (API 225)
290 typedef struct GeanyPluginFuncs
292 /** Array of plugin-provided signal handlers @see PluginCallback */
293 PluginCallback
*callbacks
;
294 /** Called to initialize the plugin, when the user activates it (must not be @c NULL) */
295 void (*init
) (GeanyPlugin
*plugin
, gpointer pdata
);
296 /** plugins configure dialog, optional (can be @c NULL) */
297 GtkWidget
* (*configure
) (GeanyPlugin
*plugin
, GtkDialog
*dialog
, gpointer pdata
);
298 /** Called when the plugin should show some help, optional (can be @c NULL) */
299 void (*help
) (GeanyPlugin
*plugin
, gpointer pdata
);
300 /** Called when the plugin is disabled or when Geany exits (must not be @c NULL) */
301 void (*cleanup
) (GeanyPlugin
*plugin
, gpointer pdata
);
305 gboolean
geany_plugin_register(GeanyPlugin
*plugin
, gint api_version
, gint min_api_version
,
306 gint abi_version
, GeanyPluginFuncs
*cbs
, gpointer pdata
);
308 /** Convinience macro to register a plugin.
310 * It simply calls geany_plugin_register() with GEANY_API_VERSION and GEANY_ABI_VERSION.
312 * @since 1.26 (API 225)
314 #define GEANY_PLUGIN_REGISTER(plugin, min_api_version) \
315 geany_plugin_register((plugin), GEANY_API_VERSION, \
316 (min_api_version), GEANY_ABI_VERSION)
318 /* Deprecated aliases */
319 #ifndef GEANY_DISABLE_DEPRECATED
321 /* This remains so that older plugins that contain a `GeanyFunctions *geany_functions;`
322 * variable in their plugin - as was previously required - will still compile
323 * without changes. */
324 typedef struct GeanyFunctionsUndefined GeanyFunctions
;
326 #define document_reload_file document_reload_force
328 /** @deprecated - copy into your plugin code if needed.
329 * @c NULL-safe way to get the index of @a doc_ptr in the documents array. */
330 #define DOC_IDX(doc_ptr) \
331 (doc_ptr ? doc_ptr->index : -1)
332 #define DOC_IDX_VALID(doc_idx) \
333 ((doc_idx) >= 0 && (guint)(doc_idx) < documents_array->len && documents[doc_idx]->is_valid)
335 #define GEANY_WINDOW_MINIMAL_WIDTH 550
336 #define GEANY_WINDOW_MINIMAL_HEIGHT GEANY_DEFAULT_DIALOG_HEIGHT
338 #endif /* GEANY_DISABLE_DEPRECATED */
342 #endif /* GEANY_PLUGIN_DATA_H */