geany/doc/plugins.dox

/*
 *      plugins.dox - this file is part of Geany, a fast and lightweight IDE
 *
 *      Copyright 2008-2009 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
 *      Copyright 2008-2009 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$
 *
 * This file contains additional plugin documentation like the signal system and a small howto.
 * It is best viewed when filetype is set to C or C++.
 */


/**
 *
 *  @mainpage Geany Plugin API Documentation
 *
 *  @author Enrico Tröger, Nick Treleaven
 *  @date $Date$
 *
 *  @section Intro
 *  This is the Geany API documentation. It is far from being complete and should be
 *  considered as a work in progress.
 *  We will try to %document as many functions and structs as possible.
 *
 *  To get started, see the @link howto Plugin Howto @endlink.
 *
 *  Other pages:
 *  - @link plugindata.h Main Datatypes and Macros @endlink
 *  - @link pluginsymbols.c Plugin Symbols @endlink
 *  - @link signals Plugin Signals @endlink
 *
 *  @note Some of these pages are also listed in Related Pages.
 */

/**
 *  @page signals Plugin Signals
 *
 *
 *  @section Usage
 *
 *  To use plugin signals in Geany, you simply create a PluginCallback array, 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.
 *  @note The PluginCallback array has to be ended with a final NULL entry.
 *
 *  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
 *
 * 	@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.
 *  @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.
 *  @param obj a GeanyObject instance, should be ignored.
 *  @param doc the opened document.
 *  @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.
 *  @param obj a GeanyObject instance, should be ignored.
 *  @param doc the saved 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.
 *  @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.
 *  @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 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().
 *  @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.
 *
 *  @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.
 *  @endsignaldef
 *
 *
 *
 *  @page howto Plugin Howto
 *
 *  @section intro Introduction
 *
 *  Since Geany 0.12 there is a plugin interface to extend Geany's functionality and
 *  add new features. This %document gives a brief overview about how to add new
 *  plugins by writing a simple "Hello World" plugin in C.
 *
 *
 *  @section start Getting started
 *
 *  @subsection structure Plugin structure
 *
 *  Every plugin must contain some essential symbols unless it won't work. A complete
 *  list of all necessary and optional symbols can be found in
 *  @link pluginsymbols.c Plugin Symbols @endlink.
 *  Every plugin should include "geany.h" and "plugindata.h" which provide necessary
 *  preprocessor macros and other basic information.
 *  There are two important preprocessor macros which need to be used at the beginning:
 *  PLUGIN_SET_INFO() and PLUGIN_VERSION_CHECK().
 *
 *  PLUGIN_SET_INFO() tells Geany about basic plugin information like name, description,
 *  version and author of the plugin.
 *
 *  PLUGIN_VERSION_CHECK() checks for compatibility of the API version which
 *  the plugin uses with the used Geany sources. Furthermore, it also checks
 *  the binary compatiblity of the plugin with Geany.
 *
 *  A few functions are necessary to let Geany work with the plugin, at least plugin_init() must
 *  exist in the plugin. plugin_cleanup() should also be used to free allocated memory or destroy
 *  created widgets.
 *
 *  @subsection buildenv Build environment
 *
 *  To be able to write plugins for Geany, you need the source code and some development
 *  packages for GTK and its dependencies. I will only describe the way to compile and
 *  build plugins on Unix-like systems [1].
 *  If you already have the Geany source code and compiled it from them, you can skip the
 *  following.
 *
 *  First you need to get the source code of Geany from the website at
 *  http://www.geany.org/Download/Releases [2]. Then install the development files for GTK
 *  and its dependencies. The easiest way to do this is to use your distribution's package
 *  management system, e.g. on Debian and Ubuntu systems you can use
 *  @code apt-get install libgtk2.0-dev intltool @endcode
 *  This will install all necessary files to be able to compile Geany and plugins. On other
 *  distributions, the package names and commands to use may differ.
 *
 *  Basically, we are done at this point and could continue with writing the plugin code.
 *  You don't need necessarily to configure and build the Geany sources when the sources
 *  have the same version as your running Geany installation. But if the version of the
 *  sources differ from your Geany installation or especially when you used the source code
 *  from the Subversion repository, we strongly recommend to configure and build these
 *  sources and use it. To do so, run @code
    ./configure && make
    su -c "make install"
 *  @endcode
 *  in your Geany source directory. This will build and install Geany on your system.
 *
 *  [1] For Windows, it is basically the same but you might have some more work on setting up
 *  the general build environment(compiler, GTK development files, ...). This is described on
 *  Geany's website at http://www.geany.org/Support/BuildingOnWin32.
 *
 *  [2] You can also use the bleedging edge source code from our Subversion repository.
 *  More information about this can be found at http://www.geany.org/Download/SVN.
 *
 * @section helloworld "Hello World"
 *
 *  We want to write a really simple "Hello World" plugin which opens a message dialog
 *  and just prints "Hello World".
 *
 *
 *  ... to be continued ...
 *
 *
 **/