HybridDog/geany
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Move plugin signals docs to pluginsignals.c, using function

Browse Source 
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).



git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@5065 ea778897-0a13-0410-b9d1-a72fbfd435f5
This commit is contained in:
Nick Treleaven 2010-06-25 16:50:27 +00:00
parent 3d361d3c55
commit 148975afa3
9 changed files with 259 additions and 272 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
ChangeLog
View File

@ -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

3
doc/Makefile.am
View File

@ -1,7 +1,8 @@
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 \
EXTRA_DIST = geany.html geany.css geany.txt geany.1 \
plugins.dox pluginsymbols.c pluginsignals.c \
stash-example.c \
$(srcdir)/$(IMAGE_FILES)

263
doc/plugins.dox
View File

@ -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

235
doc/pluginsignals.c Normal file
View File

@ -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);

2
doc/pluginsymbols.c
View File

@ -66,7 +66,7 @@ const GeanyFunctions *geany_functions;
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[];

4
src/main.c
View File

@ -400,8 +400,8 @@ static void setup_paths(void)
* 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.
*

2
src/plugindata.h
View File

@ -173,7 +173,7 @@ GeanyKeyGroupInfo;
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;

4
src/pluginutils.c
View File

@ -100,9 +100,9 @@ void plugin_module_make_resident(GeanyPlugin *plugin)
/** 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.

3
src/sciwrappers.c
View File

@ -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).