doc/pluginsignals.c

   1 /*
   2  *      pluginsignals.c - this file is part of Geany, a fast and lightweight IDE
   3  *
   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>
   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 /* Note: this file is for Doxygen only. */
  23
  24 /**
  25  * @file pluginsignals.c
  26  * Plugin Signals
  27  *
  28  *
  29  * @section Usage
  30  *
  31  * To use plugin signals in Geany, you have two options:
  32  *
  33  * -# Create a PluginCallback array with the @ref plugin_callbacks symbol. List the signals
  34  *    you want to listen to and create the appropriate signal callbacks for each signal.
  35  *    The callback array is read @a after plugin_init() has been called.
  36  * -# Use plugin_signal_connect(), which can be called at any time and can also connect
  37  *    to non-Geany signals (such as GTK widget signals).
  38  *
  39  * This page lists the signal prototypes, but you connect to them using the
  40  * string name (which by convention uses @c - hyphens instead of @c _ underscores).
  41  *
  42  * E.g. @c "document-open" for @ref document_open.
  43  *
  44  * The following code demonstrates how to use signals in Geany plugins. The code can be inserted
  45  * in your plugin code at any desired position.
  46  *
  47  * @code
  48 static void on_document_open(GObject *obj, GeanyDocument *doc, gpointer user_data)
  49 {
  50         printf("Example: %s was opened\n", DOC_FILENAME(doc));
  51 }
  52
  53 PluginCallback plugin_callbacks[] =
  54 {
  55         { "document-open", (GCallback) &on_document_open, FALSE, NULL },
  56         { NULL, NULL, FALSE, NULL }
  57 };
  58  * @endcode
  59  * @note The PluginCallback array has to be ended with a final @c NULL entry.
  60  */
  61
  62 /** Sent when a new document is created.
  63  *
  64  * @param obj a GeanyObject instance, should be ignored.
  65  * @param doc the new document.
  66  * @param user_data user data.
  67  */
  68 signal void (*document_new)(GObject *obj, GeanyDocument *doc, gpointer user_data);
  69
  70 /** Sent when a new document is opened.
  71  *
  72  * @param obj a GeanyObject instance, should be ignored.
  73  * @param doc the opened document.
  74  * @param user_data user data.
  75  */
  76 signal void (*document_open)(GObject *obj, GeanyDocument *doc, gpointer user_data);
  77
  78 /** Sent when an existing document is reloaded.
  79  *
  80  * @param obj a GeanyObject instance, should be ignored.
  81  * @param doc the re-opened document.
  82  * @param user_data user data.
  83  *
  84  * @since 0.21
  85  */
  86 signal void (*document_reload)(GObject *obj, GeanyDocument *doc, gpointer user_data);
  87
  88 /** Sent before a document is saved.
  89  *
  90  * @param obj a GeanyObject instance, should be ignored.
  91  * @param doc the document to be saved.
  92  * @param user_data user data.
  93  */
  94 signal void (*document_before_save)(GObject *obj, GeanyDocument *doc, gpointer user_data);
  95
  96 /** Sent when a new document is saved.
  97  *
  98  * @param obj a GeanyObject instance, should be ignored.
  99  * @param doc the saved document.
 100  * @param user_data user data.
 101  */
 102 signal void (*document_save)(GObject *obj, GeanyDocument *doc, gpointer user_data);
 103
 104
 105 /** Sent after the filetype of a document has been changed.
 106  *
 107  * The previous filetype object is passed but it can be NULL (e.g. at startup).
 108  * The new filetype can be read with: @code
 109  *     GeanyFiletype *ft = doc->file_type;
 110  * @endcode
 111  *
 112  * @param obj a GeanyObject instance, should be ignored.
 113  * @param doc the saved document.
 114  * @param filetype_old the previous filetype of the document.
 115  * @param user_data user data.
 116  */
 117 signal void (*document_filetype_set)(GObject *obj, GeanyDocument *doc, GeanyFiletype *filetype_old, gpointer user_data);
 118
 119 /** Sent when switching notebook pages.
 120  *
 121  * @param obj a GeanyObject instance, should be ignored.
 122  * @param doc the current document.
 123  * @param user_data user data.
 124  */
 125 signal void (*document_activate)(GObject *obj, GeanyDocument *doc, gpointer user_data);
 126
 127 /** Sent before closing a document.
 128  *
 129  * @param obj a GeanyObject instance, should be ignored.
 130  * @param doc the document about to be closed.
 131  * @param user_data user data.
 132  */
 133 signal void (*document_close)(GObject *obj, GeanyDocument *doc, gpointer user_data);
 134
 135 /** Sent after a project is opened but before session files are loaded.
 136  *
 137  * @param obj a GeanyObject instance, should be ignored.
 138  * @param config an existing GKeyFile object which can be used to read and write data.
 139  *        It must not be closed or freed.
 140  * @param user_data user data.
 141  */
 142 signal void (*project_open)(GObject *obj, GKeyFile *config, gpointer user_data);
 143
 144 /** Sent when a project is saved (happens when the project is created, the properties
 145  *  dialog is closed, before the project is closed, or when Geany is exited).
 146  *  This signal is emitted shortly before Geany will write the contents of the
 147  *  GKeyFile to the disc.
 148  *
 149  * @param obj a GeanyObject instance, should be ignored.
 150  * @param config an existing GKeyFile object which can be used to read and write data.
 151  *        It must not be closed or freed.
 152  * @param user_data user data.
 153  */
 154 signal void (*project_save)(GObject *obj, GKeyFile *config, gpointer user_data);
 155
 156 /** Sent after a project is closed.
 157  *
 158  * @param obj a GeanyObject instance, should be ignored.
 159  * @param user_data user data.
 160  */
 161 signal void (*project_close)(GObject *obj, gpointer user_data);
 162
 163 /** Sent before a project is closed.
 164  *
 165  * @param obj a GeanyObject instance, should be ignored.
 166  * @param user_data user data.
 167  *
 168  * @since 1.29 (API 230)
 169  */
 170 signal void (*project_before_close)(GObject *obj, gpointer user_data);
 171
 172 /** Sent after a project dialog is opened but before it is displayed. Plugins
 173  *  can append their own project settings tabs by using this signal.
 174  *
 175  * @param obj a GeanyObject instance, should be ignored.
 176  * @param notebook a GtkNotebook instance that can be used by plugins to append their
 177  *        settings tabs.
 178  * @param user_data user data.
 179  */
 180 signal void (*project_dialog_open)(GObject *obj, GtkWidget *notebook, gpointer user_data);
 181
 182 /** Sent when the settings dialog is confirmed by the user. Plugins can use
 183  *  this signal to read the settings widgets previously added by using the
 184  *  @c project-dialog-open signal.
 185  *
 186  * @warning The dialog will still be running afterwards if the user chose 'Apply'.
 187  * @param obj a GeanyObject instance, should be ignored.
 188  * @param notebook a GtkNotebook instance that can be used by plugins to read their
 189  *        settings widgets.
 190  * @param user_data user data.
 191  */
 192 signal void (*project_dialog_confirmed)(GObject *obj, GtkWidget *notebook, gpointer user_data);
 193
 194 /** Sent before project dialog is closed. By using this signal, plugins can remove
 195  *  tabs previously added in project-dialog-open signal handler.
 196  *
 197  * @param obj a GeanyObject instance, should be ignored.
 198  * @param notebook a GtkNotebook instance that can be used by plugins to remove
 199  *        settings tabs previously added in the project-dialog-open signal handler.
 200  * @param user_data user data.
 201  */
 202 signal void (*project_dialog_close)(GObject *obj, GtkWidget *notebook, gpointer user_data);
 203
 204 /** Sent once Geany has finished all initialization and startup tasks and the GUI has been
 205  *  realized. This signal is the very last step in the startup process and is sent once
 206  *  the GTK main event loop has been entered.
 207  *
 208  * @param obj a GeanyObject instance, should be ignored.
 209  * @param user_data user data.
 210  */
 211 signal void (*geany_startup_complete)(GObject *obj, gpointer user_data);
 212
 213 /** Sent before build is started. A plugin could use this signal e.g. to save all unsaved documents
 214  *  before the build starts.
 215  *
 216  * @param obj a GeanyObject instance, should be ignored.
 217  * @param user_data user data.
 218  */
 219 signal void (*build_start)(GObject *obj, gpointer user_data);
 220
 221 /** Sent before the popup menu of the editing widget is shown. This can be used to modify or extend
 222  *  the popup menu.
 223  *
 224  * @note You can add menu items from @c plugin_init() using @c geany->main_widgets->editor_menu,
 225  *       remembering to destroy them in @c plugin_cleanup().
 226  *
 227  * @param obj a GeanyObject instance, should be ignored.
 228  * @param word the current word (in UTF-8 encoding) below the cursor position
 229  *        where the popup menu will be opened.
 230  * @param click_pos the cursor position where the popup will be opened.
 231  * @param doc the current document.
 232  * @param user_data user data.
 233  */
 234 signal void (*update_editor_menu)(GObject *obj, const gchar *word, gint pos, GeanyDocument *doc,
 235                 gpointer user_data);
 236
 237 /** Sent whenever something in the editor widget changes.
 238  *
 239  * E.g. Character added, fold level changes, clicks to the line number margin.
 240  * A detailed description of possible notifications and the SCNotification can be found at
 241  * http://www.scintilla.org/ScintillaDoc.html#Notifications.
 242  *
 243  * If you connect to this signal, you must check @c nt->nmhdr.code for the notification type
 244  * to prevent handling unwanted notifications. This is important because for instance SCN_UPDATEUI
 245  * is sent very often whereas you probably don't want to handle this notification.
 246  *
 247  * By default, the signal is sent before Geany's default handler is processing the event.
 248  * Your callback function should return FALSE to allow Geany processing the event as well. If you
 249  * want to prevent this for some reason, return TRUE.
 250  * Please use this with care as it can break basic functionality of Geany.
 251  *
 252  * The signal can be sent after Geany's default handler has been run when you set
 253  * PluginCallback::after field to TRUE.
 254  *
 255  * An example callback implementation of this signal can be found in the Demo plugin.
 256  *
 257  * @warning This signal has much power and should be used carefully. You should especially
 258  *          care about the return value; make sure to return TRUE only if it is necessary
 259  *          and in the correct situations.
 260  *
 261  * @param obj a GeanyObject instance, should be ignored.
 262  * @param editor The current GeanyEditor.
 263  * @param nt A pointer to the SCNotification struct which holds additional information for
 264  *           the event.
 265  * @param user_data user data.
 266  * @return @c TRUE to stop other handlers from being invoked for the event.
 267  *         @c FALSE to propagate the event further.
 268  *
 269  * @since 0.16
 270  */
 271 signal gboolean (*editor_notify)(GObject *obj, GeanyEditor *editor, SCNotification *nt,
 272                 gpointer user_data);