doc/pluginsymbols.c

   1 /*
   2  *      pluginsymbols.c - this file is part of Geany, a fast and lightweight IDE
   3  *
   4  *      Copyright 2008-2011 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
   5  *      Copyright 2008-2011 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
  18  *      along with this program; if not, write to the Free Software
  19  *      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  20  *      MA 02110-1301, USA.
  21  */
  22
  23 /* Note: this file is for Doxygen only. */
  24
  25 /**
  26  * @file pluginsymbols.c
  27  * Symbols declared from within plugins.
  28  *
  29  * Geany looks for these symbols (arrays, pointers and functions) when initializing
  30  * plugins. Some of them are optional, i.e. they can be omitted; others are required
  31  * and must be defined. Some symbols should only be declared using specific macros in
  32  * @link plugindata.h @endlink.
  33  */
  34
  35 /** Use the PLUGIN_VERSION_CHECK() macro instead. Required by Geany.
  36  * @return . */
  37 gint plugin_version_check(gint);
  38
  39 /** Use the PLUGIN_SET_INFO() macro to define it. Required by Geany.
  40  * This function is called before the plugin is initialized, so Geany
  41  * can read the plugin's name.
  42  * @param info The data struct which should be initialized by this function. */
  43 void plugin_set_info(PluginInfo *info);
  44
  45 /** @deprecated Use @ref GeanyPlugin.info instead.
  46  * Basic information about a plugin, which is set in plugin_set_info(). */
  47 const PluginInfo *plugin_info;
  48
  49 /** Basic information for the plugin and identification. */
  50 const GeanyPlugin *geany_plugin;
  51
  52 /** Geany owned data pointers.
  53  * Example: @c assert(geany_data->app->configdir != NULL); */
  54 const GeanyData *geany_data;
  55
  56 /** Geany owned function pointers, split into groups.
  57  * Example: @code #include "geanyfunctions.h"
  58  * ...
  59  * document_new_file(NULL, NULL, NULL); @endcode
  60  * This is equivalent of @c geany_functions->p_document->document_new_file(NULL, NULL, NULL); */
  61 const GeanyFunctions *geany_functions;
  62
  63 /** @deprecated Use @ref ui_add_document_sensitive() instead.
  64  * Plugin owned fields, including flags. */
  65 PluginFields *plugin_fields;
  66
  67 /** An array for connecting GeanyObject events, which should be terminated with
  68  * @c {NULL, NULL, FALSE, NULL}. See @link pluginsignals.c Signal documentation @endlink.
  69  * @see plugin_signal_connect(). */
  70 PluginCallback plugin_callbacks[];
  71
  72 /** Plugins must use the PLUGIN_KEY_GROUP() macro to define it.
  73  * To setup a variable number of keybindings, e.g. based on the
  74  * plugin's configuration file settings, use plugin_set_key_group() instead. */
  75 KeyBindingGroup *plugin_key_group;
  76
  77
  78 /** Called before showing the plugin preferences dialog for multiple plugins.
  79  * Can be omitted when not needed.
  80  * The dialog will show all plugins that support this symbol together.
  81  * @param dialog The plugin preferences dialog widget - this should only be used to
  82  * connect the @c "response" signal. If settings should be read from the dialog, the
  83  * reponse will be either @c GTK_RESPONSE_OK or @c GTK_RESPONSE_APPLY.
  84  * @return A container widget holding preference widgets.
  85  * @note Using @link stash.h Stash @endlink can make implementing preferences easier.
  86  * @see plugin_configure_single(). */
  87 GtkWidget *plugin_configure(GtkDialog *dialog);
  88
  89 /** Called when a plugin should show a preferences dialog, if plugin_configure() has not been
  90  * implemented.
  91  * @warning It's better to implement plugin_configure() instead, but this is simpler.
  92  * This does not integrate as well with the multiple-plugin dialog.
  93  * @param parent Pass this as the parent widget if showing a dialog.
  94  * @see plugin_configure(). */
  95 void plugin_configure_single(GtkWidget *parent);
  96
  97 /** Called after loading the plugin.
  98  * @param data The same as #geany_data. */
  99 void plugin_init(GeanyData *data);
 100
 101 /** Called before unloading the plugin. Required for normal plugins - it should undo
 102  * everything done in plugin_init() - e.g. destroy menu items, free memory. */
 103 void plugin_cleanup();
 104
 105 /** Called whenever the plugin should show its documentation (if any). This may open a dialog,
 106  * a browser with a website or a local installed HTML help file(see utils_start_browser())
 107  * or something else.
 108  * Can be omitted when not needed. */
 109 void plugin_help();
 110