[d2a8a1]: doc / pluginsignals.c  Maximize  Restore  History

Download this file

255 lines (232 with data), 10.7 kB

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

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks