Ruby: delete rspec related kinds
[geany-mirror.git] / doc / pluginsymbols.c
blobbbc8471135a3ea95b8bf8f9c7748ce637b7f5c14
1 /*
2 * pluginsymbols.c - this file is part of Geany, a fast and lightweight IDE
4 * Copyright 2008-2012 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
5 * Copyright 2008-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.
22 /* Note: this file is for Doxygen only. */
24 /**
25 * @file pluginsymbols.c
26 * Symbols declared from within plugins, all of this is <b>deprecated</b>.
28 * @deprecated This is the legacy way of making plugins for Geany. Refer to @ref howto for the
29 * reworked process and @ref legacy to learn how to port your plugin to that new world.
30 * Meanwhile Geany will still load plugins programmed against this interface (even the items that
31 * are marked deprecated individually such as @ref plugin_fields).
33 * Geany looks for these symbols (arrays, pointers and functions) when initializing
34 * plugins. Some of them are optional, i.e. they can be omitted; others are required
35 * and must be defined. Some symbols should only be declared using specific macros in
36 * @link plugindata.h @endlink.
39 /** Use the PLUGIN_VERSION_CHECK() macro instead. Required by Geany.
41 * @param abi ABI version Geany was compiled with
42 * @return The API version the plugin was compiled with, or -1 if the plugin is incompatible. */
43 gint plugin_version_check(gint abi);
45 /** Use the PLUGIN_SET_INFO() macro to define it. Required by Geany.
46 * This function is called before the plugin is initialized, so Geany
47 * can read the plugin's name.
48 * @param info The data struct which should be initialized by this function. */
49 void plugin_set_info(PluginInfo *info);
51 /** Basic information about a plugin, which is set in plugin_set_info().
52 * @deprecated Use @ref GeanyPlugin.info instead.*/
53 const PluginInfo *plugin_info;
55 /** Basic information for the plugin and identification. */
56 const GeanyPlugin *geany_plugin;
58 /** Geany owned data pointers.
59 * Example: @c assert(geany_data->app->configdir != NULL); */
60 const GeanyData *geany_data;
62 /** Geany owned function pointers, split into groups.
63 * Example: @code #include "geanyfunctions.h"
64 * ...
65 * document_new_file(NULL, NULL, NULL); @endcode
66 * This is equivalent of @c geany_functions->p_document->document_new_file(NULL, NULL, NULL); */
67 const GeanyFunctions *geany_functions;
69 /** Plugin owned fields, including flags.
70 * @deprecated Use @ref ui_add_document_sensitive() instead.*/
71 PluginFields *plugin_fields;
73 /** An array for connecting GeanyObject events, which should be terminated with
74 * @c {NULL, NULL, FALSE, NULL}. See @link pluginsignals.c Signal documentation @endlink.
75 * @see plugin_signal_connect(). */
76 PluginCallback plugin_callbacks[];
78 /** Plugins must use the PLUGIN_KEY_GROUP() macro to define it.
79 * To setup a variable number of keybindings, e.g. based on the
80 * plugin's configuration file settings, use plugin_set_key_group() instead. */
81 KeyBindingGroup *plugin_key_group;
84 /** Called before showing the plugin preferences dialog for multiple plugins.
85 * Can be omitted when not needed.
86 * The dialog will show all plugins that support this symbol together.
87 * @param dialog The plugin preferences dialog widget - this should only be used to
88 * connect the @c "response" signal. If settings should be read from the dialog, the
89 * response will be either @c GTK_RESPONSE_OK or @c GTK_RESPONSE_APPLY.
91 * @return @transfer{floating} A container widget holding preference widgets.
93 * @note Using @link stash.h Stash @endlink can make implementing preferences easier.
94 * @see plugin_configure_single(). */
95 GtkWidget *plugin_configure(GtkDialog *dialog);
97 /** Called when a plugin should show a preferences dialog, if plugin_configure() has not been
98 * implemented.
99 * @warning It's better to implement plugin_configure() instead, but this is simpler.
100 * This does not integrate as well with the multiple-plugin dialog.
101 * @param parent Pass this as the parent widget if showing a dialog.
102 * @see plugin_configure(). */
103 void plugin_configure_single(GtkWidget *parent);
105 /** Called after loading the plugin.
106 * @param data The same as #geany_data. */
107 void plugin_init(GeanyData *data);
109 /** Called before unloading the plugin. Required for normal plugins - it should undo
110 * everything done in plugin_init() - e.g. destroy menu items, free memory. */
111 void plugin_cleanup();
113 /** Called whenever the plugin should show its documentation (if any). This may open a dialog,
114 * a browser with a website or a local installed HTML help file(see utils_open_browser())
115 * or something else.
116 * Can be omitted when not needed. */
117 void plugin_help();