Plugin Signals

Usage

To use plugin signals in Geany, you have two options:

  1. Create a PluginCallback array with the 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 after plugin_init() has been called.
  2. Use plugin_signal_connect(), which can be called at any time and can also connect to non-Geany signals (such as GTK widget signals).

The following code demonstrates how to use signals in Geany plugins. The code can be inserted in your plugin code at any desired position.

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 }
};
Note:
The PluginCallback array has to be ended with a final NULL entry.

Signals

document-new

  void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data);

Sent when a new document is created.

You need to include "document.h" for the declaration of GeanyDocument.

Parameters:
obj a GeanyObject instance, should be ignored.
doc the new document.
user_data user data.

document-open

  void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data);

Sent when a new document is opened.

You need to include "document.h" for the declaration of GeanyDocument.

Parameters:
obj a GeanyObject instance, should be ignored.
doc the opened document.
user_data user data.

document-before-save

  void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data);

Sent before a document is saved.

You need to include "document.h" for the declaration of GeanyDocument.

Parameters:
obj a GeanyObject instance, should be ignored.
doc the document to be saved.
user_data user data.

document-save

  void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data);

Sent when a new document is saved.

You need to include "document.h" for the declaration of GeanyDocument.

Parameters:
obj a GeanyObject instance, should be ignored.
doc the saved document.
user_data user data.

document-filetype-set

  void user_function(GObject *obj, GeanyDocument *doc, GeanyFiletype *filetype_old, 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: 

     GeanyFiletype *ft = doc->file_type;

Parameters:
obj a GeanyObject instance, should be ignored.
doc the saved document.
filetype_old the previous filetype of the document.
user_data user data.

document-activate

  void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data);

Sent when switching notebook pages.

You need to include "document.h" for the declaration of GeanyDocument.

Parameters:
obj a GeanyObject instance, should be ignored.
doc the current document.
user_data user data.

document-close

  void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data);

Sent before closing a document.

You need to include "document.h" for the declaration of GeanyDocument.

Parameters:
obj a GeanyObject instance, should be ignored.
doc the document about to be closed.
user_data user data.

project-open

  void user_function(GObject *obj, GKeyFile *config, gpointer user_data);

Sent after a project is opened but before session files are loaded.

Parameters:
obj a GeanyObject instance, should be ignored.
config an exising GKeyFile object which can be used to read and write data. It must not be closed or freed.
user_data user data.

project-save

  void user_function(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.

Parameters:
obj a GeanyObject instance, should be ignored.
config an exising GKeyFile object which can be used to read and write data. It must not be closed or freed.
user_data user data.

project-close

  void user_function(GObject *obj, gpointer user_data);

Sent after a project is closed.

Parameters:
obj a GeanyObject instance, should be ignored.
user_data user data.

geany-startup-complete

  void user_function(GObject *obj, 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.

Parameters:
obj a GeanyObject instance, should be ignored.
user_data user data.

build-start

  void user_function(GObject *obj, gpointer user_data);

Sent before build is started. Plugins can use this signal e.g. to save the opened documents before the build starts.

Parameters:
obj a GeanyObject instance, should be ignored.
user_data user data.

update-editor-menu

  void user_function(GObject *obj, const gchar *word, gint pos, GeanyDocument *doc,
        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 plugin_init() using geany->main_widgets->editor_menu, remembering to destroy them in plugin_cleanup().
You need to include "document.h" for the declaration of GeanyDocument.

Parameters:
obj a GeanyObject instance, should be ignored.
word the current word (in UTF-8 encoding) below the cursor position where the popup menu will be opened.
click_pos the cursor position where the popup will be opened.
doc the current document.
user_data user data.

editor-notify

  gboolean user_function(GObject *obj, GeanyEditor *editor, SCNotification *nt,
        gpointer user_data);

This signal is sent whenever something in the editor widget changes (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 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.
You need to include "editor.h" for the declaration of GeanyEditor and "Scintilla.h" for SCNotification.

Parameters:
obj a GeanyObject instance, should be ignored.
editor The current GeanyEditor.
nt A pointer to the SCNotification struct which holds additional information for the event.
user_data user data.
Returns:
TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
Since:
0.16
Generated on Fri Jun 25 04:41:30 2010 for Geany by  doxygen 1.5.9