Branch: refs/heads/master Author: Colomban Wendling ban@herbesfolles.org Committer: Colomban Wendling ban@herbesfolles.org Date: Sun, 27 Apr 2014 02:11:31 UTC Commit: edaa6f713f1b8e037a56652da15032aac56e2227 https://github.com/geany/geany/commit/edaa6f713f1b8e037a56652da15032aac56e22...

Log Message: ----------- Strip double leading spaces

These are weird and break Doxygen Markdown support.

Modified Paths: -------------- doc/plugins.dox

Modified: doc/plugins.dox 344 lines changed, 172 insertions(+), 172 deletions(-) =================================================================== @@ -67,169 +67,169 @@ */

/** - * @page guidelines Plugin Writing Guidelines + * @page guidelines Plugin Writing Guidelines * - * @section intro Introduction + * @section intro Introduction * - * The following hints and guidelines are only recommendations. Nobody is forced to follow - * them at all. + * The following hints and guidelines are only recommendations. Nobody is forced to follow + * them at all. * - * @section general General notes + * @section general General notes * - * @subsection ideas Getting a plugin idea + * @subsection ideas Getting a plugin idea * - * If you want to write a plugin but don't know yet what it should do, have a look at - * http://www.geany.org/Support/PluginWishlist to get an idea about what users wish. + * If you want to write a plugin but don't know yet what it should do, have a look at + * http://www.geany.org/Support/PluginWishlist to get an idea about what users wish. * - * @subsection code Managing the source code + * @subsection code Managing the source code * - * For authors of plugins for Geany, we created a dedicated @a geany-plugins project - * on Sourceforge and GitHub to ease development of plugins and help new authors. - * All information about this project you can find at http://plugins.geany.org/ + * For authors of plugins for Geany, we created a dedicated @a geany-plugins project + * on Sourceforge and GitHub to ease development of plugins and help new authors. + * All information about this project you can find at http://plugins.geany.org/ * - * To add a new plugin to this project, get in touch with the people on the - * geany-devel-mailing list and create a fork of the geany-plugins project - * at https://github.com/geany/geany-plugins. - * Beside of adding a new plugin, geany-devel-mailing list is also the place where - * to discuss development related questions. - * However, once you have done your fork of geany-plugins you can develop - * your plugin until you think its the right time to publish it. At this point, - * create a pull request for adding your patch set into the master branch of the main - * geany-plugins repository. + * To add a new plugin to this project, get in touch with the people on the + * geany-devel-mailing list and create a fork of the geany-plugins project + * at https://github.com/geany/geany-plugins. + * Beside of adding a new plugin, geany-devel-mailing list is also the place where + * to discuss development related questions. + * However, once you have done your fork of geany-plugins you can develop + * your plugin until you think its the right time to publish it. At this point, + * create a pull request for adding your patch set into the master branch of the main + * geany-plugins repository. * - * Of course, you don't need to use GitHub - any Git is fine. But GitHub - * is making it way easier for review, merging and get in touch with you for - * comments. + * Of course, you don't need to use GitHub - any Git is fine. But GitHub + * is making it way easier for review, merging and get in touch with you for + * comments. * - * If you don't want your plugin to be part of the geany-plugins project it is also fine. - * Just skip the part about forking geany-plugins and sending a pull request. - * In this case it is of course also a good idea to post some kind of announcement - * to geany-devel and maybe to the main geany mailing list -- it's up to you. - * You can also ask for your plugin to be listed on the http://plugins.geany.org/ - * website as a third party plugin, helping Geany user to know about your plugin. + * If you don't want your plugin to be part of the geany-plugins project it is also fine. + * Just skip the part about forking geany-plugins and sending a pull request. + * In this case it is of course also a good idea to post some kind of announcement + * to geany-devel and maybe to the main geany mailing list -- it's up to you. + * You can also ask for your plugin to be listed on the http://plugins.geany.org/ + * website as a third party plugin, helping Geany user to know about your plugin. * - * At time of writing, there are some plugins already available in the - * repositories. Feel free to use any of these plugins as a start for your own, - * maybe by copying the directory structure and the autotools files - * (Makefile.am, configure.in, ...). Most of the available plugins are also ready for - * i18n support, just for reference. + * At time of writing, there are some plugins already available in the + * repositories. Feel free to use any of these plugins as a start for your own, + * maybe by copying the directory structure and the autotools files + * (Makefile.am, configure.in, ...). Most of the available plugins are also ready for + * i18n support, just for reference. * - * We encourage authors using this service to only commit changes to their - * own plugin and not to others' plugins. Instead just send patches to - * geany-devel at uvena.de or the plugin author directly. + * We encourage authors using this service to only commit changes to their + * own plugin and not to others' plugins. Instead just send patches to + * geany-devel at uvena.de or the plugin author directly. * - * @section paths Installation paths + * @section paths Installation paths * - * - The plugin binary (@c pluginname.so) should be installed in Geany's libdir. This is - * necessary so that Geany can find the plugin. - * An easy way to retrieve Geany's libdir is to use the pkg-config tool, e.g. @code - * `$PKG_CONFIG --variable=libdir geany`/ geany - * @endcode - * - If your plugin creates other binary files like helper programs or helper libraries, - * they should go into @c $prefix/bin (for programs, ideally prefixed with @a geany), - * additional libraries should be installed in Geany's libdir, maybe in a subdirectory. - * - Plugins should install their documentation files (README, NEWS, ChangeLog, licences and - * other documentation files) into the common documentation directory - * @c $prefix/share/doc/geany-plugins/$pluginname/ - * - Translation files should be installed normally into @c $prefix/share/locale. There is no - * need to use Geany's translation directory. To set up translation support properly and - * for additional information, see main_locale_init(). - * - Do @a never install anything into a user's home directory like installing - * the plugin binary in @c ~/.config/geany/plugins/. + * - The plugin binary (@c pluginname.so) should be installed in Geany's libdir. This is + * necessary so that Geany can find the plugin. + * An easy way to retrieve Geany's libdir is to use the pkg-config tool, e.g. @code + * `$PKG_CONFIG --variable=libdir geany`/ geany + * @endcode + * - If your plugin creates other binary files like helper programs or helper libraries, + * they should go into @c $prefix/bin (for programs, ideally prefixed with @a geany), + * additional libraries should be installed in Geany's libdir, maybe in a subdirectory. + * - Plugins should install their documentation files (README, NEWS, ChangeLog, licences and + * other documentation files) into the common documentation directory + * @c $prefix/share/doc/geany-plugins/$pluginname/ + * - Translation files should be installed normally into @c $prefix/share/locale. There is no + * need to use Geany's translation directory. To set up translation support properly and + * for additional information, see main_locale_init(). + * - Do @a never install anything into a user's home directory like installing + * the plugin binary in @c ~/.config/geany/plugins/. * * - * @page howto Plugin HowTo + * @page howto Plugin HowTo * - * @section intro Introduction + * @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 or C++. + * 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 or C++. * * - * @section buildenv Build environment + * @section 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. The following 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. + * To be able to write plugins for Geany, you need the source code and some development + * packages for GTK and its dependencies. The following 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 have Geany installed. 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 plugins for Geany. On other - * distributions, the package names and commands to use may differ. + * First you need to have Geany installed. 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 plugins for Geany. On other + * distributions, the package names and commands to use may differ. * - * Basically, you are done at this point and could continue with writing the plugin code. + * Basically, you are done at this point and could continue with writing the plugin code. * - * [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. + * [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. * - * @section helloworld "Hello World" + * @section helloworld "Hello World" * - * When writing a plugin, you will find a couple of functions or macros which are mandatory - * and some which are free to use for implementing some useful feature once your plugin - * becomes more powerful like including a configuration or help dialog. + * When writing a plugin, you will find a couple of functions or macros which are mandatory + * and some which are free to use for implementing some useful feature once your plugin + * becomes more powerful like including a configuration or help dialog. * - * You should start your plugin with including some of the needed C header files and defining - * some basic global variables which will help you to access all needed functions of the plugin - * API in a more comfortable way. - * - * Let's start with the very basic headers and add more later if necessary. - * @code + * You should start your plugin with including some of the needed C header files and defining + * some basic global variables which will help you to access all needed functions of the plugin + * API in a more comfortable way. + * + * Let's start with the very basic headers and add more later if necessary. + * @code #include <geanyplugin.h> - * @endcode + * @endcode * - * @a geanyplugin.h includes all of the Geany API and also the necessary GTK header files, - * so there is no need to include @a gtk/gtk.h yourself. + * @a geanyplugin.h includes all of the Geany API and also the necessary GTK header files, + * so there is no need to include @a gtk/gtk.h yourself. * - * @note - * @a plugindata.h contains the biggest part of the plugin API and provides some basic macros. - * @a geanyfunctions.h provides some macros for convenient access to plugin API functions. + * @note + * @a plugindata.h contains the biggest part of the plugin API and provides some basic macros. + * @a geanyfunctions.h provides some macros for convenient access to plugin API functions. * - * Then you should define three basic variables which will give access to data fields and - * functions provided by the plugin API. - * @code + * Then you should define three basic variables which will give access to data fields and + * functions provided by the plugin API. + * @code GeanyPlugin *geany_plugin; GeanyData *geany_data; GeanyFunctions *geany_functions; - * @endcode + * @endcode * - * Now you can go on and write your first lines for your new plugin. As mentioned before, - * you will need to implement and fill out a couple of functions/macros to make the plugin work. - * So let's start with PLUGIN_VERSION_CHECK(). + * Now you can go on and write your first lines for your new plugin. As mentioned before, + * you will need to implement and fill out a couple of functions/macros to make the plugin work. + * So let's start with PLUGIN_VERSION_CHECK(). * - * PLUGIN_VERSION_CHECK() is a convenient way to tell Geany which version of Geany's plugin API - * is needed at minimum to run your plugin. The value is defined in - * @a plugindata.h by @a GEANY_API_VERSION. In most cases this should be your minimum. - * Nevertheless when setting this value, you should choose the lowest possible version here to - * make the plugin compatible with a bigger number of versions of Geany. + * PLUGIN_VERSION_CHECK() is a convenient way to tell Geany which version of Geany's plugin API + * is needed at minimum to run your plugin. The value is defined in + * @a plugindata.h by @a GEANY_API_VERSION. In most cases this should be your minimum. + * Nevertheless when setting this value, you should choose the lowest possible version here to + * make the plugin compatible with a bigger number of versions of Geany. * - * For the next step, you will need to tell Geany some basic information about your plugin - * which will be shown in the plugin manager dialog. + * For the next step, you will need to tell Geany some basic information about your plugin + * which will be shown in the plugin manager dialog. * - * To do this you should use the PLUGIN_SET_INFO() macro, which expects 4 parameters: - * - Plugin name - * - Short description - * - Version - * - Author + * To do this you should use the PLUGIN_SET_INFO() macro, which expects 4 parameters: + * - Plugin name + * - Short description + * - Version + * - Author * - * Based on this, the line could look like: - * @code + * Based on this, the line could look like: + * @code PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world", "1.0", "John Doe john.doe@example.org"); - * @endcode + * @endcode * - * Once this is done, you will need to implement the function which will be executed when the - * plugin is loaded. Part of that function could be adding and removing of an item to - * Geany's Tools menu, setting up keybindings or registering some callbacks. Also you will - * need to implement the function that is called when your plugin is unloaded. - * These functions are called plugin_init() and plugin_cleanup(). Let's see what this - * looks like: - * @code + * Once this is done, you will need to implement the function which will be executed when the + * plugin is loaded. Part of that function could be adding and removing of an item to + * Geany's Tools menu, setting up keybindings or registering some callbacks. Also you will + * need to implement the function that is called when your plugin is unloaded. + * These functions are called plugin_init() and plugin_cleanup(). Let's see what this + * looks like: + * @code PLUGIN_VERSION_CHECK(211)

PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world", @@ -242,18 +242,18 @@ void plugin_init(GeanyData *data) void plugin_cleanup(void) { } - * @endcode + * @endcode * - * If you think this plugin seems not to implement any functionality right now and only wastes - * some memory, you are right. But it should compile and load/unload in Geany nicely. - * Now you have the very basic layout of a new plugin. Great, isn't it? + * If you think this plugin seems not to implement any functionality right now and only wastes + * some memory, you are right. But it should compile and load/unload in Geany nicely. + * Now you have the very basic layout of a new plugin. Great, isn't it? * - * @note + * @note * - * If you would rather write the plugin in C++, you can do that by marking the - * plugin functions that it implements as @c extern @c "C", for example: + * If you would rather write the plugin in C++, you can do that by marking the + * plugin functions that it implements as @c extern @c "C", for example: * - * @code + * @code * extern "C" void plugin_init(GeanyData *data) { @@ -262,34 +262,34 @@ extern "C" void plugin_init(GeanyData *data) extern "C" void plugin_cleanup(void) { } - * @endcode + * @endcode * - * @section building Building + * @section building Building * - * First make plugin.o: + * First make plugin.o: * - * @code gcc -c plugin.c -fPIC `pkg-config --cflags geany` @endcode + * @code gcc -c plugin.c -fPIC `pkg-config --cflags geany` @endcode * - * Then make the plugin library plugin.so (or plugin.dll on Windows): + * Then make the plugin library plugin.so (or plugin.dll on Windows): * - * @code gcc plugin.o -o plugin.so -shared `pkg-config --libs geany` @endcode + * @code gcc plugin.o -o plugin.so -shared `pkg-config --libs geany` @endcode * - * If all went OK, put the library into one of the paths Geany looks for plugins, - * e.g. $prefix/lib/geany. See @ref paths "Installation paths" for details. + * If all went OK, put the library into one of the paths Geany looks for plugins, + * e.g. $prefix/lib/geany. See @ref paths "Installation paths" for details. * - * @note + * @note * - * If you are writing the plugin in C++, then you will need to use your C++ - * compiler here, for example @c g++. + * If you are writing the plugin in C++, then you will need to use your C++ + * compiler here, for example @c g++. * - * @section realfunc Adding functionality + * @section realfunc Adding functionality * - * Let's go on and implement some real functionality. + * Let's go on and implement some real functionality. * - * As mentioned before, plugin_init() will be called when the plugin is loaded in Geany. - * So it should implement everything that needs to be done during startup. In this case, - * we'd like to add a menu item to Geany's Tools menu which runs a dialog printing "Hello World". - * @code + * As mentioned before, plugin_init() will be called when the plugin is loaded in Geany. + * So it should implement everything that needs to be done during startup. In this case, + * we'd like to add a menu item to Geany's Tools menu which runs a dialog printing "Hello World". + * @code void plugin_init(GeanyData *data) { GtkWidget *main_menu_item; @@ -307,36 +307,36 @@ void plugin_init(GeanyData *data) g_signal_connect(main_menu_item, "activate", G_CALLBACK(item_activate_cb), NULL); } - * @endcode + * @endcode * - * This will add an item to the Tools menu and connect this item to a function which implements - * what should be done when the menu item is activated by the user. - * This is done by g_signal_connect(). The Tools menu can be accessed with - * geany->main_widgets->tools_menu. The structure @a main_widgets contains pointers to the - * main GUI elements in Geany. + * This will add an item to the Tools menu and connect this item to a function which implements + * what should be done when the menu item is activated by the user. + * This is done by g_signal_connect(). The Tools menu can be accessed with + * geany->main_widgets->tools_menu. The structure @a main_widgets contains pointers to the + * main GUI elements in Geany. * - * Geany has a simple API for showing message dialogs. So our function contains - * only a few lines: - * @code + * Geany has a simple API for showing message dialogs. So our function contains + * only a few lines: + * @code void item_activate_cb(GtkMenuItem *menuitem, gpointer user_data) { dialogs_show_msgbox(GTK_MESSAGE_INFO, "Hello World"); } - * @endcode + * @endcode * - * For the moment you don't need to worry about the parameters of that function. + * For the moment you don't need to worry about the parameters of that function. * - * Now we need to clean up properly when the plugin is unloaded. + * Now we need to clean up properly when the plugin is unloaded. * - * To remove the menu item from the Tools menu, you can use gtk_widget_destroy(). - * gtk_widget_destroy() expects a pointer to a GtkWidget object. + * To remove the menu item from the Tools menu, you can use gtk_widget_destroy(). + * gtk_widget_destroy() expects a pointer to a GtkWidget object. * - * First you should add gtk_widget_destroy() to your plugin_cleanup() function. - * The argument for gtk_widget_destroy() is the widget object you created earlier in - * plugin_init(). To be able to access this pointer in plugin_cleanup(), you need to move - * its definition from plugin_init() into the global context so its visibility will increase - * and it can be accessed in all functions. - * @code + * First you should add gtk_widget_destroy() to your plugin_cleanup() function. + * The argument for gtk_widget_destroy() is the widget object you created earlier in + * plugin_init(). To be able to access this pointer in plugin_cleanup(), you need to move + * its definition from plugin_init() into the global context so its visibility will increase + * and it can be accessed in all functions. + * @code static GtkWidget *main_menu_item = NULL;

// ... @@ -351,15 +351,15 @@ void plugin_cleanup(void) { gtk_widget_destroy(main_menu_item); } - * @endcode + * @endcode * - * This will ensure your menu item is removed from the Tools menu as well as from - * memory once your plugin is unloaded, so you don't leave any memory leaks. - * Once this is done, your first plugin is ready. Congratulations! + * This will ensure your menu item is removed from the Tools menu as well as from + * memory once your plugin is unloaded, so you don't leave any memory leaks. + * Once this is done, your first plugin is ready. Congratulations! * - * @section listing Complete listing (without comments) + * @section listing Complete listing (without comments) * - * @code + * @code #include <geanyplugin.h>

GeanyPlugin *geany_plugin;

-------------- This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).