src/plugindata.h

   1 /*
   2  *      plugindata.h - this file is part of Geany, a fast and lightweight IDE
   3  *
   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>
   6  *
   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.
  11  *
  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.
  16  *
  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.
  20  */
  21
  22 /**
  23  * @file plugindata.h
  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
  26  * API documentation.
  27  **/
  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). */
  30
  31
  32 #ifndef GEANY_PLUGIN_DATA_H
  33 #define GEANY_PLUGIN_DATA_H 1
  34
  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 225
  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 (71 << 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 /** @deprecated - use plugin_set_key_group() instead.
 150  * @see PLUGIN_KEY_GROUP() macro. */
 151 typedef struct GeanyKeyGroupInfo
 152 {
 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 */
 155 }
 156 GeanyKeyGroupInfo;
 157
 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] = \
 172         { \
 173                 {G_STRINGIFY(group_name), key_count} \
 174         };\
 175         GeanyKeyGroup *plugin_key_group = NULL;
 176
 177
 178 /** Callback array entry type used with the @ref plugin_callbacks symbol. */
 179 typedef struct PluginCallback
 180 {
 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. */
 185         GCallback       callback;
 186         /** Set to TRUE to connect your handler with g_signal_connect_after(). */
 187         gboolean        after;
 188         /** The user data passed to the signal handler. If set to NULL then the signal
 189          * handler will receive the data set with geany_plugin_register_full() or
 190          * geany_plugin_set_data() */
 191         gpointer        user_data;
 192 }
 193 PluginCallback;
 194
 195
 196 /** @deprecated Use @ref ui_add_document_sensitive() instead.
 197  * Flags to be set by plugins in PluginFields struct. */
 198 typedef enum
 199 {
 200         /** Whether a plugin's menu item should be disabled when there are no open documents */
 201         PLUGIN_IS_DOCUMENT_SENSITIVE    = 1 << 0
 202 }
 203 PluginFlags;
 204
 205 /** @deprecated Use @ref ui_add_document_sensitive() instead.
 206  * Fields set and owned by the plugin. */
 207 typedef struct PluginFields
 208 {
 209         /** Bitmask of @c PluginFlags. */
 210         PluginFlags     flags;
 211         /** Pointer to a plugin's menu item which will be automatically enabled/disabled when there
 212          *  are no open documents and @c PLUGIN_IS_DOCUMENT_SENSITIVE is set.
 213          *  This is required if using @c PLUGIN_IS_DOCUMENT_SENSITIVE, ignored otherwise */
 214         GtkWidget       *menu_item;
 215 }
 216 PluginFields;
 217
 218
 219 /** This contains pointers to global variables owned by Geany for plugins to use.
 220  * Core variable pointers can be appended when needed by plugin authors, if appropriate. */
 221 typedef struct GeanyData
 222 {
 223         struct GeanyApp                         *app;                           /**< Geany application data fields */
 224         struct GeanyMainWidgets         *main_widgets;          /**< Important widgets in the main window */
 225         GPtrArray                                       *documents_array;       /**< See document.h#documents_array. */
 226         GPtrArray                                       *filetypes_array;       /**< Dynamic array of GeanyFiletype pointers */
 227         struct GeanyPrefs                       *prefs;                         /**< General settings */
 228         struct GeanyInterfacePrefs      *interface_prefs;       /**< Interface settings */
 229         struct GeanyToolbarPrefs        *toolbar_prefs;         /**< Toolbar settings */
 230         struct GeanyEditorPrefs         *editor_prefs;          /**< Editor settings */
 231         struct GeanyFilePrefs           *file_prefs;            /**< File-related settings */
 232         struct GeanySearchPrefs         *search_prefs;          /**< Search-related settings */
 233         struct GeanyToolPrefs           *tool_prefs;            /**< Tool settings */
 234         struct GeanyTemplatePrefs       *template_prefs;        /**< Template settings */
 235         struct GeanyBuildInfo           *build_info;            /**< Current build information */
 236         GSList                                          *filetypes_by_title; /**< See filetypes.h#filetypes_by_title. */
 237 }
 238 GeanyData;
 239
 240 #define geany                   geany_data      /**< Simple macro for @c geany_data that reduces typing. */
 241
 242 typedef struct GeanyPluginFuncs GeanyPluginFuncs;
 243
 244 /** Basic information for the plugin and identification.
 245  * @see geany_plugin. */
 246 typedef struct GeanyPlugin
 247 {
 248         PluginInfo      *info;  /**< Fields set in plugin_set_info(). */
 249         GeanyData       *geany_data;    /**< Pointer to global GeanyData intance */
 250         GeanyPluginFuncs *funcs;        /**< Functions implemented by the plugin, set in geany_load_module() */
 251
 252         struct GeanyPluginPrivate *priv;        /* private */
 253 }
 254 GeanyPlugin;
 255
 256 #ifndef GEANY_PRIVATE
 257
 258 /* Prototypes for building plugins with -Wmissing-prototypes
 259  * Also allows the compiler to check if the signature of the plugin's
 260  * symbol properly matches what we expect. */
 261 gint plugin_version_check(gint abi_ver);
 262 void plugin_set_info(PluginInfo *info);
 263
 264 void plugin_init(GeanyData *data);
 265 GtkWidget *plugin_configure(GtkDialog *dialog);
 266 void plugin_configure_single(GtkWidget *parent);
 267 void plugin_help(void);
 268 void plugin_cleanup(void);
 269
 270 /** Called by Geany when a plugin library is loaded.
 271  *
 272  * This is the original entry point. Implement and export this function to be loadable at all.
 273  * Then fill in GeanyPlugin::info and GeanyPlugin::funcs of the passed @p plugin. Finally
 274  * GEANY_PLUGIN_REGISTER() and specify a minimum supported API version.
 275  *
 276  * For all glory details please read @ref howto.
 277  *
 278  * Because the plugin is not yet enabled by the user you may not call plugin API functions inside
 279  * this function, except for the API functions below which are required for proper registration.
 280  *
 281  * API functions which are allowed to be called within this function:
 282  *  - main_locale_init()
 283  *  - geany_plugin_register() (and GEANY_PLUGIN_REGISTER())
 284  *  - geany_plugin_register_full() (and GEANY_PLUGIN_REGISTER_FULL())
 285  *
 286  * @param plugin The unique plugin handle to your plugin. You must set some fields here.
 287  *
 288  * @since 1.26 (API 225)
 289  * @see @ref howto
 290  */
 291 void geany_load_module(GeanyPlugin *plugin);
 292
 293 #endif
 294
 295 /** Callback functions that need to be implemented for every plugin.
 296  *
 297  * These callbacks should be registered by the plugin within Geany's call to
 298  * geany_load_module() by calling geany_plugin_register() with an instance of this type.
 299  *
 300  * Geany will then call the callbacks at appropriate times. Each gets passed the
 301  * plugin-defined data pointer as well as the corresponding GeanyPlugin instance
 302  * pointer.
 303  *
 304  * @since 1.26 (API 225)
 305  * @see @ref howto
 306  **/
 307 struct GeanyPluginFuncs
 308 {
 309         /** Array of plugin-provided signal handlers @see PluginCallback */
 310         PluginCallback *callbacks;
 311         /** Called to initialize the plugin, when the user activates it (must not be @c NULL) */
 312         gboolean    (*init)      (GeanyPlugin *plugin, gpointer pdata);
 313         /** plugins configure dialog, optional (can be @c NULL) */
 314         GtkWidget*  (*configure) (GeanyPlugin *plugin, GtkDialog *dialog, gpointer pdata);
 315         /** Called when the plugin should show some help, optional (can be @c NULL) */
 316         void        (*help)      (GeanyPlugin *plugin, gpointer pdata);
 317         /** Called when the plugin is disabled or when Geany exits (must not be @c NULL) */
 318         void        (*cleanup)   (GeanyPlugin *plugin, gpointer pdata);
 319 };
 320
 321 gboolean geany_plugin_register(GeanyPlugin *plugin, gint api_version,
 322                                gint min_api_version, gint abi_version);
 323 gboolean geany_plugin_register_full(GeanyPlugin *plugin, gint api_version,
 324                                     gint min_api_version, gint abi_version,
 325                                     gpointer data, GDestroyNotify free_func);
 326 void geany_plugin_set_data(GeanyPlugin *plugin, gpointer data, GDestroyNotify free_func);
 327
 328 /** Convinience macro to register a plugin.
 329  *
 330  * It simply calls geany_plugin_register() with GEANY_API_VERSION and GEANY_ABI_VERSION.
 331  *
 332  * @since 1.26 (API 225)
 333  * @see @ref howto
 334  **/
 335 #define GEANY_PLUGIN_REGISTER(plugin, min_api_version) \
 336         geany_plugin_register((plugin), GEANY_API_VERSION, \
 337                               (min_api_version), GEANY_ABI_VERSION)
 338
 339 /** Convinience macro to register a plugin with data.
 340  *
 341  * It simply calls geany_plugin_register_full() with GEANY_API_VERSION and GEANY_ABI_VERSION.
 342  *
 343  * @since 1.26 (API 225)
 344  * @see @ref howto
 345  **/
 346 #define GEANY_PLUGIN_REGISTER_FULL(plugin, min_api_version, pdata, free_func) \
 347         geany_plugin_register_full((plugin), GEANY_API_VERSION, \
 348                                    (min_api_version), GEANY_ABI_VERSION, (pdata), (free_func))
 349
 350 /* Deprecated aliases */
 351 #ifndef GEANY_DISABLE_DEPRECATED
 352
 353 /* This remains so that older plugins that contain a `GeanyFunctions *geany_functions;`
 354  * variable in their plugin - as was previously required - will still compile
 355  * without changes.  */
 356 typedef struct GeanyFunctionsUndefined GeanyFunctions;
 357
 358 #define document_reload_file document_reload_force
 359
 360 /** @deprecated - copy into your plugin code if needed.
 361  * @c NULL-safe way to get the index of @a doc_ptr in the documents array. */
 362 #define DOC_IDX(doc_ptr) \
 363         (doc_ptr ? doc_ptr->index : -1)
 364 #define DOC_IDX_VALID(doc_idx) \
 365         ((doc_idx) >= 0 && (guint)(doc_idx) < documents_array->len && documents[doc_idx]->is_valid)
 366
 367 #define GEANY_WINDOW_MINIMAL_WIDTH              550
 368 #define GEANY_WINDOW_MINIMAL_HEIGHT             GEANY_DEFAULT_DIALOG_HEIGHT
 369
 370 #endif  /* GEANY_DISABLE_DEPRECATED */
 371
 372 G_END_DECLS
 373
 374 #endif /* GEANY_PLUGIN_DATA_H */