1 /* 2 * plugindata.h - this file is part of Geany, a fast and lightweight IDE 3 * 4 * Copyright 2007 The Geany contributors 5 * 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. 10 * 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. 15 * 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. 19 */ 20 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). */ 29 30 31 #ifndef GEANY_PLUGIN_DATA_H 32 #define GEANY_PLUGIN_DATA_H 1 33 34 #include "geany.h" /* for GEANY_DEPRECATED */ 35 #include "build.h" /* GeanyBuildGroup, GeanyBuildSource, GeanyBuildCmdEntries enums */ 36 #include "document.h" /* GeanyDocument */ 37 #include "editor.h" /* GeanyEditor, GeanyIndentType */ 38 #include "filetypes.h" /* GeanyFiletype */ 39 40 #include "gtkcompat.h" 41 42 G_BEGIN_DECLS 43 44 /* Compatibility for sharing macros between API and core. 45 * First include geany.h, then plugindata.h, then other API headers. */ 46 #undef GEANY 47 #define GEANY(symbol_name) geany->symbol_name 48 49 50 /** The Application Programming Interface (API) version, incremented 51 * whenever any plugin data types are modified or appended to. 52 * 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(); 56 * #endif @endcode 57 * 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. 60 */ 61 #define GEANY_API_VERSION 239 62 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 67 #else 68 # define GEANY_ABI_SHIFT 0 69 #endif 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 (72 << GEANY_ABI_SHIFT) 76 77 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) \ 88 { \ 89 if (abi_ver != GEANY_ABI_VERSION) \ 90 return -1; \ 91 return (api_required); \ 92 } 93 94 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 98 { 99 /** The name of the plugin. */ 100 const gchar *name; 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. */ 106 const gchar *author; 107 } 108 PluginInfo; 109 110 111 /** Sets the plugin name and some other basic information about a plugin. 112 * 113 * @note If you want some of the arguments to be translated, see @ref PLUGIN_SET_TRANSLATABLE_INFO() 114 * 115 * Example: 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) \ 122 { \ 123 info->name = (p_name); \ 124 info->description = (p_description); \ 125 info->version = (p_version); \ 126 info->author = (p_author); \ 127 } 128 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(). 133 * 134 * Example: 135 * @code PLUGIN_SET_TRANSLATABLE_INFO(LOCALEDIR, GETTEXT_PACKAGE, _("Cool Feature"), _("Adds a cool feature."), "0.1", "John Doe") @endcode 136 * 137 * @since 0.19 */ 138 #define PLUGIN_SET_TRANSLATABLE_INFO(localedir, package, p_name, p_description, p_version, p_author) \ 139 void plugin_set_info(PluginInfo *info) \ 140 { \ 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); \ 146 } 147 148 149 /** Callback array entry type used with the @ref plugin_callbacks symbol. */ 150 typedef struct PluginCallback 151 { 152 /** The name of signal, must be an existing signal. For a list of available signals, 153 * please see the @link pluginsignals.c Signal documentation @endlink. */ 154 const gchar *signal_name; 155 /** A callback function which is called when the signal is emitted. */ 156 GCallback callback; 157 /** Set to TRUE to connect your handler with g_signal_connect_after(). */ 158 gboolean after; 159 /** The user data passed to the signal handler. If set to NULL then the signal 160 * handler will receive the data set with geany_plugin_register_full() or 161 * geany_plugin_set_data() */ 162 gpointer user_data; 163 } 164 PluginCallback; 165 166 167 /** This contains pointers to global variables owned by Geany for plugins to use. 168 * Core variable pointers can be appended when needed by plugin authors, if appropriate. */ 169 typedef struct GeanyData 170 { 171 struct GeanyApp *app; /**< Geany application data fields */ 172 struct GeanyMainWidgets *main_widgets; /**< Important widgets in the main window */ 173 /** Dynamic array of GeanyDocument pointers. 174 * Once a pointer is added to this, it is never freed. This means the same document pointer 175 * can represent a different document later on, or it may have been closed and become invalid. 176 * For this reason, you should use document_find_by_id() instead of storing 177 * document pointers over time if there is a chance the user can close the 178 * document. 179 * 180 * @warning You must check @c GeanyDocument::is_valid when iterating over this array. 181 * This is done automatically if you use the foreach_document() macro. 182 * 183 * @note 184 * Never assume that the order of document pointers is the same as the order of notebook tabs. 185 * One reason is that notebook tabs can be reordered. 186 * Use @c document_get_from_page() to lookup a document from a notebook tab number. 187 * 188 * @see documents. 189 * 190 * @elementtype{GeanyDocument} 191 */ 192 GPtrArray *documents_array; 193 /** Dynamic array of filetype pointers 194 * 195 * List the list is dynamically expanded for custom filetypes filetypes so don't expect 196 * the list of known filetypes to be a constant. 197 * 198 * @elementtype{GeanyFiletype} 199 */ 200 GPtrArray *filetypes_array; 201 struct GeanyPrefs *prefs; /**< General settings */ 202 struct GeanyInterfacePrefs *interface_prefs; /**< Interface settings */ 203 struct GeanyToolbarPrefs *toolbar_prefs; /**< Toolbar settings */ 204 struct GeanyEditorPrefs *editor_prefs; /**< Editor settings */ 205 struct GeanyFilePrefs *file_prefs; /**< File-related settings */ 206 struct GeanySearchPrefs *search_prefs; /**< Search-related settings */ 207 struct GeanyToolPrefs *tool_prefs; /**< Tool settings */ 208 struct GeanyTemplatePrefs *template_prefs; /**< Template settings */ 209 gpointer *_compat; /* Remove field on next ABI break (abi-todo) */ 210 /** List of filetype pointers sorted by name, but with @c filetypes_index(GEANY_FILETYPES_NONE) 211 * first, as this is usually treated specially. 212 * The list does not change (after filetypes have been initialized), so you can use 213 * @code g_slist_nth_data(filetypes_by_title, n) @endcode and expect the same result at different times. 214 * @see filetypes_get_sorted_by_name(). 215 * 216 * @elementtype{GeanyFiletype} 217 */ 218 GSList *filetypes_by_title; 219 /** @gironly 220 * Global object signalling events via signals 221 * 222 * This is mostly for language bindings. Otherwise prefer to use 223 * plugin_signal_connect() instead this which adds automatic cleanup. */ 224 GObject *object; 225 } 226 GeanyData; 227 228 #define geany geany_data /**< Simple macro for @c geany_data that reduces typing. */ 229 230 typedef struct GeanyPluginFuncs GeanyPluginFuncs; 231 typedef struct GeanyProxyFuncs GeanyProxyFuncs; 232 233 /** Basic information for the plugin and identification. 234 * @see geany_plugin. */ 235 typedef struct GeanyPlugin 236 { 237 PluginInfo *info; /**< Fields set in plugin_set_info(). */ 238 GeanyData *geany_data; /**< Pointer to global GeanyData intance */ 239 GeanyPluginFuncs *funcs; /**< Functions implemented by the plugin, set in geany_load_module() */ 240 GeanyProxyFuncs *proxy_funcs; /**< Hooks implemented by the plugin if it wants to act as a proxy 241 Must be set prior to calling geany_plugin_register_proxy() */ 242 struct GeanyPluginPrivate *priv; /* private */ 243 } 244 GeanyPlugin; 245 246 #ifndef GEANY_PRIVATE 247 248 /* Prototypes for building plugins with -Wmissing-prototypes 249 * Also allows the compiler to check if the signature of the plugin's 250 * symbol properly matches what we expect. */ 251 gint plugin_version_check(gint abi_ver); 252 void plugin_set_info(PluginInfo *info); 253 254 void plugin_init(GeanyData *data); 255 GtkWidget *plugin_configure(GtkDialog *dialog); 256 void plugin_configure_single(GtkWidget *parent); 257 void plugin_help(void); 258 void plugin_cleanup(void); 259 260 /** Called by Geany when a plugin library is loaded. 261 * 262 * This is the original entry point. Implement and export this function to be loadable at all. 263 * Then fill in GeanyPlugin::info and GeanyPlugin::funcs of the passed @p plugin. Finally 264 * GEANY_PLUGIN_REGISTER() and specify a minimum supported API version. 265 * 266 * For all glory details please read @ref howto. 267 * 268 * Because the plugin is not yet enabled by the user you may not call plugin API functions inside 269 * this function, except for the API functions below which are required for proper registration. 270 * 271 * API functions which are allowed to be called within this function: 272 * - main_locale_init() 273 * - geany_plugin_register() (and GEANY_PLUGIN_REGISTER()) 274 * - geany_plugin_register_full() (and GEANY_PLUGIN_REGISTER_FULL()) 275 * - plugin_module_make_resident() 276 * 277 * @param plugin The unique plugin handle to your plugin. You must set some fields here. 278 * 279 * @since 1.26 (API 225) 280 * @see @ref howto 281 */ 282 void geany_load_module(GeanyPlugin *plugin); 283 284 #endif 285 286 /** Callback functions that need to be implemented for every plugin. 287 * 288 * These callbacks should be registered by the plugin within Geany's call to 289 * geany_load_module() by calling geany_plugin_register() with an instance of this type. 290 * 291 * Geany will then call the callbacks at appropriate times. Each gets passed the 292 * plugin-defined data pointer as well as the corresponding GeanyPlugin instance 293 * pointer. 294 * 295 * @since 1.26 (API 225) 296 * @see @ref howto 297 **/ 298 struct GeanyPluginFuncs 299 { 300 /** Array of plugin-provided signal handlers @see PluginCallback */ 301 PluginCallback *callbacks; 302 /** Called to initialize the plugin, when the user activates it (must not be @c NULL) */ 303 gboolean (*init) (GeanyPlugin *plugin, gpointer pdata); 304 /** plugins configure dialog, optional (can be @c NULL) */ 305 GtkWidget* (*configure) (GeanyPlugin *plugin, GtkDialog *dialog, gpointer pdata); 306 /** Called when the plugin should show some help, optional (can be @c NULL) */ 307 void (*help) (GeanyPlugin *plugin, gpointer pdata); 308 /** Called when the plugin is disabled or when Geany exits (must not be @c NULL) */ 309 void (*cleanup) (GeanyPlugin *plugin, gpointer pdata); 310 }; 311 312 gboolean geany_plugin_register(GeanyPlugin *plugin, gint api_version, 313 gint min_api_version, gint abi_version); 314 gboolean geany_plugin_register_full(GeanyPlugin *plugin, gint api_version, 315 gint min_api_version, gint abi_version, 316 gpointer data, GDestroyNotify free_func); 317 gpointer geany_plugin_get_data(const GeanyPlugin *plugin); 318 void geany_plugin_set_data(GeanyPlugin *plugin, gpointer data, GDestroyNotify free_func); 319 320 /** Convenience macro to register a plugin. 321 * 322 * It simply calls geany_plugin_register() with GEANY_API_VERSION and GEANY_ABI_VERSION. 323 * 324 * @since 1.26 (API 225) 325 * @see @ref howto 326 **/ 327 #define GEANY_PLUGIN_REGISTER(plugin, min_api_version) \ 328 geany_plugin_register((plugin), GEANY_API_VERSION, \ 329 (min_api_version), GEANY_ABI_VERSION) 330 331 /** Convenience macro to register a plugin with data. 332 * 333 * It simply calls geany_plugin_register_full() with GEANY_API_VERSION and GEANY_ABI_VERSION. 334 * 335 * @since 1.26 (API 225) 336 * @see @ref howto 337 **/ 338 #define GEANY_PLUGIN_REGISTER_FULL(plugin, min_api_version, pdata, free_func) \ 339 geany_plugin_register_full((plugin), GEANY_API_VERSION, \ 340 (min_api_version), GEANY_ABI_VERSION, (pdata), (free_func)) 341 342 /** Return values for GeanyProxyHooks::probe() 343 * 344 * @see geany_plugin_register_proxy() for a full description of the proxy plugin mechanisms. 345 */ 346 typedef enum 347 { 348 /** The proxy is not responsible at all, and Geany or other plugins are free 349 * to probe it. 350 * 351 * @since 1.29 (API 229) 352 **/ 353 GEANY_PROXY_IGNORE, 354 /** The proxy is responsible for this file, and creates a plugin for it. 355 * 356 * @since 1.29 (API 229) 357 */ 358 GEANY_PROXY_MATCH, 359 /** The proxy is does not directly load it, but it's still tied to the proxy. 360 * 361 * This is for plugins that come in multiple files where only one of these 362 * files is relevant for the plugin creation (for the PM dialog). The other 363 * files should be ignored by Geany and other proxies. Example: libpeas has 364 * a .plugin and a .so per plugin. Geany should not process the .so file 365 * if there is a corresponding .plugin. 366 * 367 * @since 1.29 (API 229) 368 */ 369 GEANY_PROXY_RELATED = GEANY_PROXY_MATCH | 0x100 370 } 371 GeanyProxyProbeResults; 372 373 /** @deprecated Use GEANY_PROXY_IGNORE instead. 374 * @since 1.26 (API 226) 375 */ 376 #define PROXY_IGNORED GEANY_PROXY_IGNORE 377 /** @deprecated Use GEANY_PROXY_MATCH instead. 378 * @since 1.26 (API 226) 379 */ 380 #define PROXY_MATCHED GEANY_PROXY_MATCH 381 /** @deprecated Use GEANY_PROXY_RELATED instead. 382 * @since 1.26 (API 226) 383 */ 384 #define PROXY_NOLOAD 0x100 385 386 /** Hooks that need to be implemented by every proxy 387 * 388 * @see geany_plugin_register_proxy() for a full description of the proxy mechanism. 389 * 390 * @since 1.26 (API 226) 391 **/ 392 struct GeanyProxyFuncs 393 { 394 /** Called to determine whether the proxy is truly responsible for the requested plugin. 395 * A NULL pointer assumes the probe() function would always return @ref GEANY_PROXY_MATCH */ 396 gint (*probe) (GeanyPlugin *proxy, const gchar *filename, gpointer pdata); 397 /** Called after probe(), to perform the actual job of loading the plugin */ 398 gpointer (*load) (GeanyPlugin *proxy, GeanyPlugin *subplugin, const gchar *filename, gpointer pdata); 399 /** Called when the user initiates unloading of a plugin, e.g. on Geany exit */ 400 void (*unload) (GeanyPlugin *proxy, GeanyPlugin *subplugin, gpointer load_data, gpointer pdata); 401 }; 402 403 gint geany_plugin_register_proxy(GeanyPlugin *plugin, const gchar **extensions); 404 405 /* Deprecated aliases */ 406 #ifndef GEANY_DISABLE_DEPRECATED 407 408 /* This remains so that older plugins that contain a `GeanyFunctions *geany_functions;` 409 * variable in their plugin - as was previously required - will still compile 410 * without changes. */ 411 typedef struct GeanyFunctionsUndefined GeanyFunctions GEANY_DEPRECATED; 412 413 /** @deprecated - use plugin_set_key_group() instead. 414 * @see PLUGIN_KEY_GROUP() macro. */ 415 typedef struct GeanyKeyGroupInfo 416 { 417 const gchar *name; /**< Group name used in the configuration file, such as @c "html_chars" */ 418 gsize count; /**< The number of keybindings the group will hold */ 419 } 420 GeanyKeyGroupInfo GEANY_DEPRECATED_FOR(plugin_set_key_group); 421 422 /** @deprecated - use plugin_set_key_group() instead. 423 * Declare and initialise a keybinding group. 424 * @code GeanyKeyGroup *plugin_key_group; @endcode 425 * You must then set the @c plugin_key_group::keys[] entries for the group in plugin_init(), 426 * normally using keybindings_set_item(). 427 * The @c plugin_key_group::label field is set by Geany after @c plugin_init() 428 * is called, to the name of the plugin. 429 * @param group_name A unique group name (without quotes) to be used in the 430 * configuration file, such as @c html_chars. 431 * @param key_count The number of keybindings the group will hold. */ 432 #define PLUGIN_KEY_GROUP(group_name, key_count) \ 433 /* We have to declare this as a single element array. 434 * Declaring as a pointer to a struct doesn't work with g_module_symbol(). */ \ 435 GeanyKeyGroupInfo plugin_key_group_info[1] = \ 436 { \ 437 {G_STRINGIFY(group_name), key_count} \ 438 };\ 439 GeanyKeyGroup *plugin_key_group = NULL; 440 441 /** @deprecated Use @ref ui_add_document_sensitive() instead. 442 * Flags to be set by plugins in PluginFields struct. */ 443 typedef enum 444 { 445 /** Whether a plugin's menu item should be disabled when there are no open documents */ 446 PLUGIN_IS_DOCUMENT_SENSITIVE = 1 << 0 447 } 448 PluginFlags; 449 450 /** @deprecated Use @ref ui_add_document_sensitive() instead. 451 * Fields set and owned by the plugin. */ 452 typedef struct PluginFields 453 { 454 /** Bitmask of @c PluginFlags. */ 455 PluginFlags flags; 456 /** Pointer to a plugin's menu item which will be automatically enabled/disabled when there 457 * are no open documents and @c PLUGIN_IS_DOCUMENT_SENSITIVE is set. 458 * This is required if using @c PLUGIN_IS_DOCUMENT_SENSITIVE, ignored otherwise */ 459 GtkWidget *menu_item; 460 } 461 PluginFields GEANY_DEPRECATED_FOR(ui_add_document_sensitive); 462 463 #define document_reload_file document_reload_force 464 465 /** @deprecated - copy into your plugin code if needed. 466 * @c NULL-safe way to get the index of @a doc_ptr in the documents array. */ 467 #define DOC_IDX(doc_ptr) \ 468 (doc_ptr ? doc_ptr->index : -1) 469 #define DOC_IDX_VALID(doc_idx) \ 470 ((doc_idx) >= 0 && (guint)(doc_idx) < documents_array->len && documents[doc_idx]->is_valid) 471 472 #define GEANY_WINDOW_MINIMAL_WIDTH 550 473 #define GEANY_WINDOW_MINIMAL_HEIGHT GEANY_DEFAULT_DIALOG_HEIGHT 474 475 #endif /* GEANY_DISABLE_DEPRECATED */ 476 477 G_END_DECLS 478 479 #endif /* GEANY_PLUGIN_DATA_H */ 480