Fix popup position on a wrapping corner case
[geany-mirror.git] / src / plugindata.h
blob7474deb17b76fe2236c0437fb2109c59e97e69fc
1 /*
2 * plugindata.h - this file is part of Geany, a fast and lightweight IDE
4 * Copyright 2007 The Geany contributors
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License along
17 * with this program; if not, write to the Free Software Foundation, Inc.,
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
21 /**
22 * @file plugindata.h
23 * This file defines the plugin API, the interface between Geany and its plugins.
24 * For detailed documentation of the plugin system please read the plugin
25 * API documentation.
26 **/
27 /* Note: Remember to increment GEANY_API_VERSION (and GEANY_ABI_VERSION if necessary)
28 * when making changes (see 'Keeping the plugin ABI stable' in the HACKING file). */
31 #ifndef GEANY_PLUGIN_DATA_H
32 #define GEANY_PLUGIN_DATA_H 1
34 #include "build.h" /* GeanyBuildGroup, GeanyBuildSource, GeanyBuildCmdEntries enums */
35 #include "document.h" /* GeanyDocument */
36 #include "editor.h" /* GeanyEditor, GeanyIndentType */
37 #include "filetypes.h" /* GeanyFiletype */
39 #include "gtkcompat.h"
41 G_BEGIN_DECLS
43 /* Compatibility for sharing macros between API and core.
44 * First include geany.h, then plugindata.h, then other API headers. */
45 #undef GEANY
46 #define GEANY(symbol_name) geany->symbol_name
49 /** The Application Programming Interface (API) version, incremented
50 * whenever any plugin data types are modified or appended to.
52 * You can protect code that needs a higher API than e.g. 200 with:
53 * @code #if GEANY_API_VERSION >= 200
54 * some_newer_function();
55 * #endif @endcode
57 * @warning You should not test for values below 200 as previously
58 * @c GEANY_API_VERSION was defined as an enum value, not a macro.
60 #define GEANY_API_VERSION 247
62 /* hack to have a different ABI when built with different GTK major versions
63 * because loading plugins linked to a different one leads to crashes.
64 * Only GTK3 is currently supported. */
65 #define GEANY_ABI_SHIFT 8
66 /** The Application Binary Interface (ABI) version, incremented whenever
67 * existing fields in the plugin data types have to be changed or reordered.
68 * Changing this forces all plugins to be recompiled before Geany can load them. */
69 /* This should usually stay the same if fields are only appended, assuming only pointers to
70 * structs and not structs themselves are declared by plugins. */
71 #define GEANY_ABI_VERSION (73 << GEANY_ABI_SHIFT)
74 /** Defines a function to check the plugin is safe to load.
75 * This performs runtime checks that try to ensure:
76 * - Geany ABI data types are compatible with this plugin.
77 * - Geany sources provide the required API for this plugin.
78 * @param api_required The minimum API number your plugin requires.
79 * Look at the source for the value of @c GEANY_API_VERSION to use if you
80 * want your plugin to require the current Geany version on your machine.
81 * You should update this value when using any new API features. */
82 #define PLUGIN_VERSION_CHECK(api_required) \
83 gint plugin_version_check(gint abi_ver) \
84 { \
85 if (abi_ver != GEANY_ABI_VERSION) \
86 return -1; \
87 return (api_required); \
91 /** Basic information about a plugin available to Geany without loading the plugin.
92 * The fields are set in plugin_set_info(), usually with the PLUGIN_SET_INFO() macro. */
93 typedef struct PluginInfo
95 /** The name of the plugin. */
96 const gchar *name;
97 /** The description of the plugin. */
98 const gchar *description;
99 /** The version of the plugin. */
100 const gchar *version;
101 /** The author of the plugin. */
102 const gchar *author;
104 PluginInfo;
107 /** Sets the plugin name and some other basic information about a plugin.
109 * @note If you want some of the arguments to be translated, see @ref PLUGIN_SET_TRANSLATABLE_INFO()
111 * Example:
112 * @code PLUGIN_SET_INFO("Cool Feature", "Adds cool feature support.", "0.1", "Joe Author") @endcode */
113 /* plugin_set_info() could be written manually for plugins if we want to add any
114 * extra PluginInfo features (such as an icon), so we don't need to break API
115 * compatibility. Alternatively just add a new macro, PLUGIN_SET_INFO_FULL(). -ntrel */
116 #define PLUGIN_SET_INFO(p_name, p_description, p_version, p_author) \
117 void plugin_set_info(PluginInfo *info) \
119 info->name = (p_name); \
120 info->description = (p_description); \
121 info->version = (p_version); \
122 info->author = (p_author); \
125 /** Sets the plugin name and some other basic information about a plugin.
126 * This macro is like @ref PLUGIN_SET_INFO() but allows the passed information to be translated
127 * by setting up the translation mechanism with @ref main_locale_init().
128 * You therefore don't need to call it manually in plugin_init().
130 * Example:
131 * @code PLUGIN_SET_TRANSLATABLE_INFO(LOCALEDIR, GETTEXT_PACKAGE, _("Cool Feature"), _("Adds a cool feature."), "0.1", "John Doe") @endcode
133 * @since 0.19 */
134 #define PLUGIN_SET_TRANSLATABLE_INFO(localedir, package, p_name, p_description, p_version, p_author) \
135 void plugin_set_info(PluginInfo *info) \
137 main_locale_init((localedir), (package)); \
138 info->name = (p_name); \
139 info->description = (p_description); \
140 info->version = (p_version); \
141 info->author = (p_author); \
145 /** Callback array entry type used with the @ref plugin_callbacks symbol. */
146 typedef struct PluginCallback
148 /** The name of signal, must be an existing signal. For a list of available signals,
149 * please see the @link pluginsignals.c Signal documentation @endlink. */
150 const gchar *signal_name;
151 /** A callback function which is called when the signal is emitted. */
152 GCallback callback;
153 /** Set to TRUE to connect your handler with g_signal_connect_after(). */
154 gboolean after;
155 /** The user data passed to the signal handler. If set to NULL then the signal
156 * handler will receive the data set with geany_plugin_register_full() or
157 * geany_plugin_set_data() */
158 gpointer user_data;
160 PluginCallback;
163 /** This contains pointers to global variables owned by Geany for plugins to use.
164 * Core variable pointers can be appended when needed by plugin authors, if appropriate. */
165 typedef struct GeanyData
167 struct GeanyApp *app; /**< Geany application data fields */
168 struct GeanyMainWidgets *main_widgets; /**< Important widgets in the main window */
169 /** Dynamic array of GeanyDocument pointers.
170 * Once a pointer is added to this, it is never freed. This means the same document pointer
171 * can represent a different document later on, or it may have been closed and become invalid.
172 * For this reason, you should use document_find_by_id() instead of storing
173 * document pointers over time if there is a chance the user can close the
174 * document.
176 * @warning You must check @c GeanyDocument::is_valid when iterating over this array.
177 * This is done automatically if you use the foreach_document() macro.
179 * @note
180 * Never assume that the order of document pointers is the same as the order of notebook tabs.
181 * One reason is that notebook tabs can be reordered.
182 * Use @c document_get_from_page() to lookup a document from a notebook tab number.
184 * @see documents.
186 * @elementtype{GeanyDocument}
188 GPtrArray *documents_array;
189 /** Dynamic array of filetype pointers
191 * List the list is dynamically expanded for custom filetypes filetypes so don't expect
192 * the list of known filetypes to be a constant.
194 * @elementtype{GeanyFiletype}
196 GPtrArray *filetypes_array;
197 struct GeanyPrefs *prefs; /**< General settings */
198 struct GeanyInterfacePrefs *interface_prefs; /**< Interface settings */
199 struct GeanyToolbarPrefs *toolbar_prefs; /**< Toolbar settings */
200 struct GeanyEditorPrefs *editor_prefs; /**< Editor settings */
201 struct GeanyFilePrefs *file_prefs; /**< File-related settings */
202 struct GeanySearchPrefs *search_prefs; /**< Search-related settings */
203 struct GeanyToolPrefs *tool_prefs; /**< Tool settings */
204 struct GeanyTemplatePrefs *template_prefs; /**< Template settings */
205 gpointer *_compat; /* Remove field on next ABI break (abi-todo) */
206 /** List of filetype pointers sorted by name, but with @c filetypes_index(GEANY_FILETYPES_NONE)
207 * first, as this is usually treated specially.
208 * The list does not change (after filetypes have been initialized), so you can use
209 * @code g_slist_nth_data(filetypes_by_title, n) @endcode and expect the same result at different times.
210 * @see filetypes_get_sorted_by_name().
212 * @elementtype{GeanyFiletype}
214 GSList *filetypes_by_title;
215 /** @gironly
216 * Global object signalling events via signals
218 * This is mostly for language bindings. Otherwise prefer to use
219 * plugin_signal_connect() instead this which adds automatic cleanup. */
220 GObject *object;
222 GeanyData;
224 #define geany geany_data /**< Simple macro for @c geany_data that reduces typing. */
226 typedef struct GeanyPluginFuncs GeanyPluginFuncs;
227 typedef struct GeanyProxyFuncs GeanyProxyFuncs;
229 /** Basic information for the plugin and identification.
230 * @see geany_plugin. */
231 typedef struct GeanyPlugin
233 PluginInfo *info; /**< Fields set in plugin_set_info(). */
234 GeanyData *geany_data; /**< Pointer to global GeanyData intance */
235 GeanyPluginFuncs *funcs; /**< Functions implemented by the plugin, set in geany_load_module() */
236 GeanyProxyFuncs *proxy_funcs; /**< Hooks implemented by the plugin if it wants to act as a proxy
237 Must be set prior to calling geany_plugin_register_proxy() */
238 struct GeanyPluginPrivate *priv; /* private */
240 GeanyPlugin;
242 #ifndef GEANY_PRIVATE
244 /* Prototypes for building plugins with -Wmissing-prototypes
245 * Also allows the compiler to check if the signature of the plugin's
246 * symbol properly matches what we expect. */
247 gint plugin_version_check(gint abi_ver);
248 void plugin_set_info(PluginInfo *info);
250 void plugin_init(GeanyData *data);
251 GtkWidget *plugin_configure(GtkDialog *dialog);
252 void plugin_configure_single(GtkWidget *parent);
253 void plugin_help(void);
254 void plugin_cleanup(void);
256 /** Called by Geany when a plugin library is loaded.
258 * This is the original entry point. Implement and export this function to be loadable at all.
259 * Then fill in GeanyPlugin::info and GeanyPlugin::funcs of the passed @p plugin. Finally
260 * GEANY_PLUGIN_REGISTER() and specify a minimum supported API version.
262 * For all glory details please read @ref howto.
264 * Because the plugin is not yet enabled by the user you may not call plugin API functions inside
265 * this function, except for the API functions below which are required for proper registration.
267 * API functions which are allowed to be called within this function:
268 * - main_locale_init()
269 * - geany_plugin_register() (and GEANY_PLUGIN_REGISTER())
270 * - geany_plugin_register_full() (and GEANY_PLUGIN_REGISTER_FULL())
271 * - plugin_module_make_resident()
273 * @param plugin The unique plugin handle to your plugin. You must set some fields here.
275 * @since 1.26 (API 225)
276 * @see @ref howto
278 void geany_load_module(GeanyPlugin *plugin);
280 #endif
282 /** Callback functions that need to be implemented for every plugin.
284 * These callbacks should be registered by the plugin within Geany's call to
285 * geany_load_module() by calling geany_plugin_register() with an instance of this type.
287 * Geany will then call the callbacks at appropriate times. Each gets passed the
288 * plugin-defined data pointer as well as the corresponding GeanyPlugin instance
289 * pointer.
291 * @since 1.26 (API 225)
292 * @see @ref howto
294 struct GeanyPluginFuncs
296 /** Array of plugin-provided signal handlers @see PluginCallback */
297 PluginCallback *callbacks;
298 /** Called to initialize the plugin, when the user activates it (must not be @c NULL) */
299 gboolean (*init) (GeanyPlugin *plugin, gpointer pdata);
300 /** plugins configure dialog, optional (can be @c NULL) */
301 GtkWidget* (*configure) (GeanyPlugin *plugin, GtkDialog *dialog, gpointer pdata);
302 /** Called when the plugin should show some help, optional (can be @c NULL) */
303 void (*help) (GeanyPlugin *plugin, gpointer pdata);
304 /** Called when the plugin is disabled or when Geany exits (must not be @c NULL) */
305 void (*cleanup) (GeanyPlugin *plugin, gpointer pdata);
308 gboolean geany_plugin_register(GeanyPlugin *plugin, gint api_version,
309 gint min_api_version, gint abi_version);
310 gboolean geany_plugin_register_full(GeanyPlugin *plugin, gint api_version,
311 gint min_api_version, gint abi_version,
312 gpointer data, GDestroyNotify free_func);
313 gpointer geany_plugin_get_data(const GeanyPlugin *plugin);
314 void geany_plugin_set_data(GeanyPlugin *plugin, gpointer data, GDestroyNotify free_func);
316 /** Convenience macro to register a plugin.
318 * It simply calls geany_plugin_register() with GEANY_API_VERSION and GEANY_ABI_VERSION.
320 * @since 1.26 (API 225)
321 * @see @ref howto
323 #define GEANY_PLUGIN_REGISTER(plugin, min_api_version) \
324 geany_plugin_register((plugin), GEANY_API_VERSION, \
325 (min_api_version), GEANY_ABI_VERSION)
327 /** Convenience macro to register a plugin with data.
329 * It simply calls geany_plugin_register_full() with GEANY_API_VERSION and GEANY_ABI_VERSION.
331 * @since 1.26 (API 225)
332 * @see @ref howto
334 #define GEANY_PLUGIN_REGISTER_FULL(plugin, min_api_version, pdata, free_func) \
335 geany_plugin_register_full((plugin), GEANY_API_VERSION, \
336 (min_api_version), GEANY_ABI_VERSION, (pdata), (free_func))
338 /** Return values for GeanyProxyHooks::probe()
340 * @see geany_plugin_register_proxy() for a full description of the proxy plugin mechanisms.
342 typedef enum
344 /** The proxy is not responsible at all, and Geany or other plugins are free
345 * to probe it.
347 * @since 1.29 (API 229)
349 GEANY_PROXY_IGNORE,
350 /** The proxy is responsible for this file, and creates a plugin for it.
352 * @since 1.29 (API 229)
354 GEANY_PROXY_MATCH,
355 /** The proxy is does not directly load it, but it's still tied to the proxy.
357 * This is for plugins that come in multiple files where only one of these
358 * files is relevant for the plugin creation (for the PM dialog). The other
359 * files should be ignored by Geany and other proxies. Example: libpeas has
360 * a .plugin and a .so per plugin. Geany should not process the .so file
361 * if there is a corresponding .plugin.
363 * @since 1.29 (API 229)
365 GEANY_PROXY_RELATED = GEANY_PROXY_MATCH | 0x100
367 GeanyProxyProbeResults;
369 /** Hooks that need to be implemented by every proxy
371 * @see geany_plugin_register_proxy() for a full description of the proxy mechanism.
373 * @since 1.26 (API 226)
375 struct GeanyProxyFuncs
377 /** Called to determine whether the proxy is truly responsible for the requested plugin.
378 * A NULL pointer assumes the probe() function would always return @ref GEANY_PROXY_MATCH */
379 gint (*probe) (GeanyPlugin *proxy, const gchar *filename, gpointer pdata);
380 /** Called after probe(), to perform the actual job of loading the plugin */
381 gpointer (*load) (GeanyPlugin *proxy, GeanyPlugin *subplugin, const gchar *filename, gpointer pdata);
382 /** Called when the user initiates unloading of a plugin, e.g. on Geany exit */
383 void (*unload) (GeanyPlugin *proxy, GeanyPlugin *subplugin, gpointer load_data, gpointer pdata);
386 gint geany_plugin_register_proxy(GeanyPlugin *plugin, const gchar **extensions);
388 G_END_DECLS
390 #endif /* GEANY_PLUGIN_DATA_H */