Revision: 5065 http://geany.svn.sourceforge.net/geany/?rev=5065&view=rev Author: ntrel Date: 2010-06-25 16:50:27 +0000 (Fri, 25 Jun 2010)
Log Message: ----------- Move plugin signals docs to pluginsignals.c, using function pointer syntax instead of @signaldef as this puts a summary of the signal names at the top of the page and sorts alphabetically. (Note: the syntax is similar to Vala signal syntax).
Modified Paths: -------------- trunk/ChangeLog trunk/doc/Makefile.am trunk/doc/plugins.dox trunk/doc/pluginsymbols.c trunk/src/main.c trunk/src/plugindata.h trunk/src/pluginutils.c trunk/src/sciwrappers.c
Added Paths: ----------- trunk/doc/pluginsignals.c
Modified: trunk/ChangeLog =================================================================== --- trunk/ChangeLog 2010-06-24 06:39:24 UTC (rev 5064) +++ trunk/ChangeLog 2010-06-25 16:50:27 UTC (rev 5065) @@ -1,3 +1,14 @@ +2010-06-25 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com> + + * src/sciwrappers.c, src/plugindata.h, src/pluginutils.c, src/main.c, + doc/pluginsignals.c, doc/pluginsymbols.c, doc/Makefile.am, + doc/plugins.dox: + Move plugin signals docs to pluginsignals.c, using function + pointer syntax instead of @signaldef as this puts a summary of + the signal names at the top of the page and sorts alphabetically. + (Note: the syntax is similar to Vala signal syntax). + + 2010-06-24 Lex Trotman <elextr(at)gmail(dot)com>
* src/build.c
Modified: trunk/doc/Makefile.am =================================================================== --- trunk/doc/Makefile.am 2010-06-24 06:39:24 UTC (rev 5064) +++ trunk/doc/Makefile.am 2010-06-25 16:50:27 UTC (rev 5065) @@ -1,9 +1,10 @@ man_MANS=geany.1 DOCDIR = $(DESTDIR)$(docdir) IMAGE_FILES = images/*.png -EXTRA_DIST = geany.html geany.css geany.txt geany.1 plugins.dox pluginsymbols.c \ - stash-example.c \ - $(srcdir)/$(IMAGE_FILES) +EXTRA_DIST = geany.html geany.css geany.txt geany.1 \ + plugins.dox pluginsymbols.c pluginsignals.c \ + stash-example.c \ + $(srcdir)/$(IMAGE_FILES)
pdf: geany.txt rst2latex -stg --documentoptions="10pt,a4paper" --output-encoding=utf8 $(srcdir)/geany.txt geany.tex
Modified: trunk/doc/plugins.dox =================================================================== --- trunk/doc/plugins.dox 2010-06-24 06:39:24 UTC (rev 5064) +++ trunk/doc/plugins.dox 2010-06-25 16:50:27 UTC (rev 5065) @@ -44,7 +44,7 @@ * - @link howto Plugin HowTo @endlink - get started * - @link pluginsymbols.c Plugin Symbols @endlink * - @link plugindata.h Plugin Datatypes and Macros @endlink - * - @link signals Plugin Signals @endlink + * - @link pluginsignals.c Plugin Signals @endlink * - @link pluginutils.h Plugin Utility Functions @endlink * - @link guidelines Plugin Writing Guidelines @endlink * - <b>plugins/demoplugin.c</b> - in Geany's source, bigger than the howto example @@ -71,267 +71,6 @@ */
/** - * @page signals 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). - * - * 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. - * - * @section Signals - * - * @signaldef document-new - * @signalproto - * void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data); - * @endsignalproto - * @signaldesc - * Sent when a new document is created. - * - * You need to include "document.h" for the declaration of GeanyDocument. - * - * @param obj a GeanyObject instance, should be ignored. - * @param doc the new document. - * @param user_data user data. - * @endsignaldef - * - * @signaldef document-open - * @signalproto - * void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data); - * @endsignalproto - * @signaldesc - * Sent when a new document is opened. - * - * You need to include "document.h" for the declaration of GeanyDocument. - * - * @param obj a GeanyObject instance, should be ignored. - * @param doc the opened document. - * @param user_data user data. - * @endsignaldef - * - * @signaldef document-before-save - * @signalproto - * void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data); - * @endsignalproto - * @signaldesc - * Sent before a document is saved. - * - * You need to include "document.h" for the declaration of GeanyDocument. - * - * @param obj a GeanyObject instance, should be ignored. - * @param doc the document to be saved. - * @param user_data user data. - * @endsignaldef - * - * @signaldef document-save - * @signalproto - * void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data); - * @endsignalproto - * @signaldesc - * Sent when a new document is saved. - * - * You need to include "document.h" for the declaration of GeanyDocument. - * - * @param obj a GeanyObject instance, should be ignored. - * @param doc the saved document. - * @param user_data user data. - * @endsignaldef - * - * @signaldef document-filetype-set - * @signalproto - * void user_function(GObject *obj, GeanyDocument *doc, GeanyFiletype *filetype_old, gpointer user_data); - * @endsignalproto - * @signaldesc - * 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. - * @endsignaldef - * - * @signaldef document-activate - * @signalproto - * void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data); - * @endsignalproto - * @signaldesc - * Sent when switching notebook pages. - * - * You need to include "document.h" for the declaration of GeanyDocument. - * - * @param obj a GeanyObject instance, should be ignored. - * @param doc the current document. - * @param user_data user data. - * @endsignaldef - * - * @signaldef document-close - * @signalproto - * void user_function(GObject *obj, GeanyDocument *doc, gpointer user_data); - * @endsignalproto - * @signaldesc - * Sent before closing a document. - * - * You need to include "document.h" for the declaration of GeanyDocument. - * - * @param obj a GeanyObject instance, should be ignored. - * @param doc the document about to be closed. - * @param user_data user data. - * @endsignaldef - * - * @signaldef project-open - * @signalproto - * void user_function(GObject *obj, GKeyFile *config, gpointer user_data); - * @endsignalproto - * @signaldesc - * 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. - * @endsignaldef - * - * @signaldef project-save - * @signalproto - * void user_function(GObject *obj, GKeyFile *config, gpointer user_data); - * @endsignalproto - * @signaldesc - * 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. - * @endsignaldef - * - * @signaldef project-close - * @signalproto - * void user_function(GObject *obj, gpointer user_data); - * @endsignalproto - * @signaldesc - * Sent after a project is closed. - * @param obj a GeanyObject instance, should be ignored. - * @param user_data user data. - * @endsignaldef - * - * @signaldef geany-startup-complete - * @signalproto - * void user_function(GObject *obj, gpointer user_data); - * @endsignalproto - * @signaldesc - * 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. - * @endsignaldef - * - * @signaldef build-start - * @signalproto - * void user_function(GObject *obj, gpointer user_data); - * @endsignalproto - * @signaldesc - * Sent before build is started. Plugins can use this signal e.g. to save the opened documents - * before the build starts. - * - * @param obj a GeanyObject instance, should be ignored. - * @param user_data user data. - * @endsignaldef - * - * @signaldef update-editor-menu - * @signalproto - * void user_function(GObject *obj, const gchar *word, gint pos, GeanyDocument *doc, - * gpointer user_data); - * @endsignalproto - * @signaldesc - * 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(). - * - * You need to include "document.h" for the declaration of GeanyDocument. - * - * @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. - * @endsignaldef - * - * @signaldef editor-notify - * @signalproto - * gboolean user_function(GObject *obj, GeanyEditor *editor, SCNotification *nt, - * gpointer user_data); - * @endsignalproto - * @signaldesc - * 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 @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. - * - * You need to include "editor.h" for the declaration of GeanyEditor and "Scintilla.h" for - * SCNotification. - * - * @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 - * @endsignaldef - * - * - * * @page guidelines Plugin Writing Guidelines * * @section intro Introduction
Added: trunk/doc/pluginsignals.c =================================================================== --- trunk/doc/pluginsignals.c (rev 0) +++ trunk/doc/pluginsignals.c 2010-06-25 16:50:27 UTC (rev 5065) @@ -0,0 +1,235 @@ +/* + * pluginsignals.c - this file is part of Geany, a fast and lightweight IDE + * + * Copyright 2008-2010 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de> + * Copyright 2008-2010 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. + * + * $Id$ + */ + +/* 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. + * + * You need to include "document.h" for the declaration of GeanyDocument. + * + * @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. + * + * You need to include "document.h" for the declaration of GeanyDocument. + * + * @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 before a document is saved. + * + * You need to include "document.h" for the declaration of GeanyDocument. + * + * @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. + * + * You need to include "document.h" for the declaration of GeanyDocument. + * + * @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. + * + * You need to include "document.h" for the declaration of GeanyDocument. + * + * @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. + * + * You need to include "document.h" for the declaration of GeanyDocument. + * + * @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 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. Plugins can use this signal e.g. to save the opened 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(). + * + * You need to include "document.h" for the declaration of GeanyDocument. + * + * @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. + * + * You need to include "editor.h" for the declaration of GeanyEditor and "Scintilla.h" for + * SCNotification. + * + * @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);
Property changes on: trunk/doc/pluginsignals.c ___________________________________________________________________ Added: svn:keywords + Author Date Id Revision Added: svn:eol-style + native
Modified: trunk/doc/pluginsymbols.c =================================================================== --- trunk/doc/pluginsymbols.c 2010-06-24 06:39:24 UTC (rev 5064) +++ trunk/doc/pluginsymbols.c 2010-06-25 16:50:27 UTC (rev 5065) @@ -66,7 +66,7 @@ PluginFields *plugin_fields;
/** An array for connecting GeanyObject events, which should be terminated with - * @c {NULL, NULL, FALSE, NULL}. See @link signals Signal documentation @endlink. + * @c {NULL, NULL, FALSE, NULL}. See @link pluginsignals.c Signal documentation @endlink. * @see plugin_signal_connect(). */ PluginCallback plugin_callbacks[];
Modified: trunk/src/main.c =================================================================== --- trunk/src/main.c 2010-06-24 06:39:24 UTC (rev 5064) +++ trunk/src/main.c 2010-06-25 16:50:27 UTC (rev 5065) @@ -400,8 +400,8 @@ * This is because the main window is realized (i.e. actually drawn on the screen) at the * end of the startup process. * - * @note Maybe you want to use the @ref geany-startup-complete signal to get notified about - * the completed startup process. + * @note Maybe you want to use the @link pluginsignals.c @c "geany-startup-complete" signal @endlink + * to get notified about the completed startup process. * * @return @c TRUE if the Geany main window has been realized or @c FALSE otherwise. *
Modified: trunk/src/plugindata.h =================================================================== --- trunk/src/plugindata.h 2010-06-24 06:39:24 UTC (rev 5064) +++ trunk/src/plugindata.h 2010-06-25 16:50:27 UTC (rev 5065) @@ -173,7 +173,7 @@ typedef struct PluginCallback { /** The name of signal, must be an existing signal. For a list of available signals, - * please see the @link signals Signal documentation @endlink. */ + * please see the @link pluginsignals.c Signal documentation @endlink. */ const gchar *signal_name; /** A callback function which is called when the signal is emitted. */ GCallback callback;
Modified: trunk/src/pluginutils.c =================================================================== --- trunk/src/pluginutils.c 2010-06-24 06:39:24 UTC (rev 5064) +++ trunk/src/pluginutils.c 2010-06-25 16:50:27 UTC (rev 5065) @@ -100,9 +100,9 @@
/** Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault. * @param plugin Must be @ref geany_plugin. - * @param object Object to connect to, or @c NULL when using @link signals Geany signals @endlink. + * @param object Object to connect to, or @c NULL when using @link pluginsignals.c Geany signals @endlink. * @param signal_name The name of the signal. For a list of available - * signals, please see the @link signals Signal documentation @endlink. + * signals, please see the @link pluginsignals.c Signal documentation @endlink. * @param after Set to @c TRUE to call your handler after the main signal handlers have been called * (if supported by @a signal_name). * @param callback The function to call when the signal is emitted.
Modified: trunk/src/sciwrappers.c =================================================================== --- trunk/src/sciwrappers.c 2010-06-24 06:39:24 UTC (rev 5064) +++ trunk/src/sciwrappers.c 2010-06-25 16:50:27 UTC (rev 5065) @@ -25,7 +25,8 @@ * Wrapper functions for the Scintilla editor widget @c SCI_* messages. * You should also check the http://scintilla.org documentation, as it is more detailed. * - * To get Scintilla notifications, use the @c editor-notify @link signals Geany Signal @endlink. + * To get Scintilla notifications, use the + * @link pluginsignals.c @c "editor-notify" signal @endlink. * * @note These functions were originally from the cssed project * (http://cssed.sf.net, thanks).
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.