Remove comment noise from doc/plugins.dox and make it a build depend
This commit is contained in:
Matthew Brush
parent
747be883cd
commit
5475d15b87
@ -52,6 +52,7 @@ if WITH_DOXYGEN
|
||||
|
||||
doxygen_sources = \
|
||||
$(srcdir)/*.[ch] \
|
||||
$(srcdir)/*.dox \
|
||||
$(top_srcdir)/src/*.[ch] \
|
||||
$(top_srcdir)/plugins/geanyplugin.h \
|
||||
$(top_srcdir)/plugins/geanyfunctions.h \
|
||||
|
||||
680
doc/plugins.dox
680
doc/plugins.dox
@ -4,6 +4,7 @@
|
||||
* Copyright 2008-2011 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
|
||||
* Copyright 2008-2011 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
|
||||
* Copyright 2009-2012 Frank Lanitz <frank(at)frank(dot)uvena(dot)de>
|
||||
* Copyright 2014 Matthew Brush <matt(at)geany(dot)org>
|
||||
*
|
||||
* 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
|
||||
@ -19,217 +20,215 @@
|
||||
* with this program; if not, write to the Free Software Foundation, Inc.,
|
||||
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
||||
*
|
||||
* 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++.
|
||||
* 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, Frank Lanitz
|
||||
*
|
||||
* @section Intro
|
||||
* This is the Geany API documentation. It should be considered work in progress.
|
||||
* We will try to document as many functions and structs as possible.
|
||||
*
|
||||
* @warning Do not use any symbol not in the documentation - it may change.
|
||||
*
|
||||
* @section pluginsupport Plugin Support
|
||||
* - @link howto Plugin HowTo @endlink - get started
|
||||
* - @link pluginsymbols.c Plugin Symbols @endlink
|
||||
* - @link plugindata.h Plugin Datatypes and Macros @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
|
||||
*
|
||||
* @section common Common API files
|
||||
* - @link dialogs.h @endlink
|
||||
* - @link document.h @endlink
|
||||
* - @link editor.h @endlink
|
||||
* - @link filetypes.h @endlink
|
||||
* - @link keybindings.h @endlink
|
||||
* - @link msgwindow.h @endlink
|
||||
* - @link project.h @endlink
|
||||
* - @link sciwrappers.h Scintilla Wrapper Functions @endlink
|
||||
* - @link stash.h Stash Pref/Setting Functions @endlink
|
||||
* - @link utils.h General Utility Functions @endlink
|
||||
* - @link ui_utils.h Widget Utility Functions @endlink
|
||||
|
||||
* @section More
|
||||
* - All API functions and types - see <b>Files</b> link at the top
|
||||
* - Deprecated symbols - see <b>Related Pages</b> link at the top
|
||||
*
|
||||
* @note See the HACKING file for information about developing the plugin API and
|
||||
* other useful notes.
|
||||
*/
|
||||
@mainpage Geany Plugin API Documentation
|
||||
|
||||
/**
|
||||
* @page guidelines Plugin Writing Guidelines
|
||||
*
|
||||
* @section intro Introduction
|
||||
*
|
||||
* The following hints and guidelines are only recommendations. Nobody is forced to follow
|
||||
* them at all.
|
||||
*
|
||||
* @section general General notes
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* @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/
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* - 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
|
||||
*
|
||||
* @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++.
|
||||
*
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* [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"
|
||||
*
|
||||
* 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
|
||||
@author Enrico Tröger, Nick Treleaven, Frank Lanitz, Matthew Brush
|
||||
|
||||
@section Intro
|
||||
This is the Geany API documentation. It should be considered work in progress.
|
||||
We will try to document as many functions and structs as possible.
|
||||
|
||||
@warning Do not use any symbol not in the documentation - it may change.
|
||||
|
||||
@section pluginsupport Plugin Support
|
||||
- @link howto Plugin HowTo @endlink - get started
|
||||
- @link pluginsymbols.c Plugin Symbols @endlink
|
||||
- @link plugindata.h Plugin Datatypes and Macros @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
|
||||
|
||||
@section common Common API files
|
||||
- @link dialogs.h @endlink
|
||||
- @link document.h @endlink
|
||||
- @link editor.h @endlink
|
||||
- @link filetypes.h @endlink
|
||||
- @link keybindings.h @endlink
|
||||
- @link msgwindow.h @endlink
|
||||
- @link project.h @endlink
|
||||
- @link sciwrappers.h Scintilla Wrapper Functions @endlink
|
||||
- @link stash.h Stash Pref/Setting Functions @endlink
|
||||
- @link utils.h General Utility Functions @endlink
|
||||
- @link ui_utils.h Widget Utility Functions @endlink
|
||||
|
||||
@section More
|
||||
- All API functions and types - see <b>Files</b> link at the top
|
||||
- Deprecated symbols - see <b>Related Pages</b> link at the top
|
||||
|
||||
@note See the HACKING file for information about developing the plugin API and
|
||||
other useful notes.
|
||||
|
||||
@page guidelines Plugin Writing Guidelines
|
||||
|
||||
@section intro Introduction
|
||||
|
||||
The following hints and guidelines are only recommendations. Nobody is forced to follow
|
||||
them at all.
|
||||
|
||||
@section general General notes
|
||||
|
||||
@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.
|
||||
|
||||
@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/
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
- 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
|
||||
|
||||
@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++.
|
||||
|
||||
|
||||
@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.
|
||||
|
||||
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.
|
||||
|
||||
[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"
|
||||
|
||||
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
|
||||
#include <geanyplugin.h>
|
||||
* @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.
|
||||
*
|
||||
* @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
|
||||
@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.
|
||||
|
||||
@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
|
||||
GeanyPlugin *geany_plugin;
|
||||
GeanyData *geany_data;
|
||||
GeanyFunctions *geany_functions;
|
||||
* @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().
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
@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().
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world",
|
||||
"1.0", "John Doe <john.doe@example.org>");
|
||||
* @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
|
||||
@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
|
||||
PLUGIN_VERSION_CHECK(211)
|
||||
|
||||
PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world",
|
||||
@ -242,19 +241,19 @@ void plugin_init(GeanyData *data)
|
||||
void plugin_cleanup(void)
|
||||
{
|
||||
}
|
||||
* @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?
|
||||
*
|
||||
* @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:
|
||||
*
|
||||
* @code
|
||||
*
|
||||
@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?
|
||||
|
||||
@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:
|
||||
|
||||
@code
|
||||
|
||||
extern "C" void plugin_init(GeanyData *data)
|
||||
{
|
||||
}
|
||||
@ -262,34 +261,34 @@ extern "C" void plugin_init(GeanyData *data)
|
||||
extern "C" void plugin_cleanup(void)
|
||||
{
|
||||
}
|
||||
* @endcode
|
||||
*
|
||||
* @section building Building
|
||||
*
|
||||
* First make plugin.o:
|
||||
*
|
||||
* @code gcc -c plugin.c -fPIC `pkg-config --cflags geany` @endcode
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* 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
|
||||
@endcode
|
||||
|
||||
@section building Building
|
||||
|
||||
First make plugin.o:
|
||||
|
||||
@code gcc -c plugin.c -fPIC `pkg-config --cflags geany` @endcode
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
void plugin_init(GeanyData *data)
|
||||
{
|
||||
GtkWidget *main_menu_item;
|
||||
@ -307,36 +306,36 @@ void plugin_init(GeanyData *data)
|
||||
g_signal_connect(main_menu_item, "activate",
|
||||
G_CALLBACK(item_activate_cb), NULL);
|
||||
}
|
||||
* @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.
|
||||
*
|
||||
* Geany has a simple API for showing message dialogs. So our function contains
|
||||
* only a few lines:
|
||||
* @code
|
||||
@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.
|
||||
|
||||
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
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
@endcode
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
static GtkWidget *main_menu_item = NULL;
|
||||
|
||||
// ...
|
||||
@ -351,15 +350,15 @@ void plugin_cleanup(void)
|
||||
{
|
||||
gtk_widget_destroy(main_menu_item);
|
||||
}
|
||||
* @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!
|
||||
*
|
||||
* @section listing Complete listing (without comments)
|
||||
*
|
||||
* @code
|
||||
@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!
|
||||
|
||||
@section listing Complete listing (without comments)
|
||||
|
||||
@code
|
||||
#include <geanyplugin.h>
|
||||
|
||||
GeanyPlugin *geany_plugin;
|
||||
@ -393,70 +392,70 @@ void plugin_cleanup(void)
|
||||
{
|
||||
gtk_widget_destroy(main_menu_item);
|
||||
}
|
||||
* @endcode
|
||||
*
|
||||
*
|
||||
* Now you might like to look at Geany's source code for core plugins such as
|
||||
* @a plugins/demoplugin.c.
|
||||
*
|
||||
* @section furtherimprovements Furter Improvements and next steps
|
||||
* @subsection translatable_plugin_information Translatable plugin information
|
||||
*
|
||||
* After having written our first plugin, there is still room for improvement.
|
||||
*
|
||||
* By default, PLUGIN_SET_INFO() does not allow translation of the basic plugin
|
||||
* information for plugins which are not shipped with Geany's core distribution.
|
||||
* Since most plugins are not shipped with Geany's core, it makes sense to
|
||||
* enable translation when the plugin is loaded so that it gets translated
|
||||
* inside Geany's Plugin Manager. As of Geany 0.19, the plugin API contains
|
||||
* the PLUGIN_SET_TRANSLATABLE_INFO() macro which enables translation of the
|
||||
* basic plugin details passed to PLUGIN_SET_INFO() when the plugin is loaded.
|
||||
*
|
||||
* PLUGIN_SET_TRANSLATABLE_INFO() takes two more parameters than PLUGIN_SET_INFO(),
|
||||
* for a total of six parameters.
|
||||
*
|
||||
* - Localedir
|
||||
* - Gettextpackage
|
||||
* - Plugin name
|
||||
* - Short description
|
||||
* - Version
|
||||
* - Author
|
||||
*
|
||||
* The @a Localdir and the @a Gettextpackage parameters are usually set inside
|
||||
* the build system. If this has been done, the call for example HelloWorld
|
||||
* plugin could look like:
|
||||
*
|
||||
* @code
|
||||
@endcode
|
||||
|
||||
|
||||
Now you might like to look at Geany's source code for core plugins such as
|
||||
@a plugins/demoplugin.c.
|
||||
|
||||
@section furtherimprovements Furter Improvements and next steps
|
||||
@subsection translatable_plugin_information Translatable plugin information
|
||||
|
||||
After having written our first plugin, there is still room for improvement.
|
||||
|
||||
By default, PLUGIN_SET_INFO() does not allow translation of the basic plugin
|
||||
information for plugins which are not shipped with Geany's core distribution.
|
||||
Since most plugins are not shipped with Geany's core, it makes sense to
|
||||
enable translation when the plugin is loaded so that it gets translated
|
||||
inside Geany's Plugin Manager. As of Geany 0.19, the plugin API contains
|
||||
the PLUGIN_SET_TRANSLATABLE_INFO() macro which enables translation of the
|
||||
basic plugin details passed to PLUGIN_SET_INFO() when the plugin is loaded.
|
||||
|
||||
PLUGIN_SET_TRANSLATABLE_INFO() takes two more parameters than PLUGIN_SET_INFO(),
|
||||
for a total of six parameters.
|
||||
|
||||
- Localedir
|
||||
- Gettextpackage
|
||||
- Plugin name
|
||||
- Short description
|
||||
- Version
|
||||
- Author
|
||||
|
||||
The @a Localdir and the @a Gettextpackage parameters are usually set inside
|
||||
the build system. If this has been done, the call for example HelloWorld
|
||||
plugin could look like:
|
||||
|
||||
@code
|
||||
PLUGIN_SET_TRANSLATABLE_INFO(
|
||||
LOCALEDIR, GETTEXT_PACKAGE, _("Hello World"),
|
||||
_("Just another tool to say hello world"),
|
||||
"1.0", "John Doe <john.doe@example.org>");
|
||||
* @endcode
|
||||
*
|
||||
* When using this macro, you should use the gettext macro @a _() to mark
|
||||
* the strings like name and the short description as translatable as well. You
|
||||
* can see how this is done in the above example.
|
||||
*
|
||||
* As you can see the author's information is not marked as translatable in
|
||||
* this example. The community has agreed that the best practice here is to
|
||||
* use, if possible, the latin version of the author's name followed by the
|
||||
* native spelling inside parenthesis, where applicable.
|
||||
*
|
||||
* @subsection plugin_i18n Using i18n/l10n inside Plugin
|
||||
*
|
||||
@endcode
|
||||
|
||||
* You can (and should) also mark other strings beside the plugin's meta
|
||||
* information as translatable. Strings used in menu entries, information
|
||||
* boxes or configuration dialogs should also be translatable as well. Geany
|
||||
* offers a way to enable this in the plugin's code using the main_locale_init()
|
||||
* function provided by the plugin API. This function takes the same two
|
||||
* parameters discussed in the previous section; @a GETTEXT_PACKAGE and
|
||||
* @a LOCALEDIR.
|
||||
*
|
||||
* The main_locale_init() function is best called during initialization in the
|
||||
* plugin's plugin_init() function. Adding this to the HelloWorld example could
|
||||
* look like:
|
||||
* @code
|
||||
When using this macro, you should use the gettext macro @a _() to mark
|
||||
the strings like name and the short description as translatable as well. You
|
||||
can see how this is done in the above example.
|
||||
|
||||
As you can see the author's information is not marked as translatable in
|
||||
this example. The community has agreed that the best practice here is to
|
||||
use, if possible, the latin version of the author's name followed by the
|
||||
native spelling inside parenthesis, where applicable.
|
||||
|
||||
@subsection plugin_i18n Using i18n/l10n inside Plugin
|
||||
|
||||
|
||||
You can (and should) also mark other strings beside the plugin's meta
|
||||
information as translatable. Strings used in menu entries, information
|
||||
boxes or configuration dialogs should also be translatable as well. Geany
|
||||
offers a way to enable this in the plugin's code using the main_locale_init()
|
||||
function provided by the plugin API. This function takes the same two
|
||||
parameters discussed in the previous section; @a GETTEXT_PACKAGE and
|
||||
@a LOCALEDIR.
|
||||
|
||||
The main_locale_init() function is best called during initialization in the
|
||||
plugin's plugin_init() function. Adding this to the HelloWorld example could
|
||||
look like:
|
||||
@code
|
||||
void plugin_init(GeanyData *data)
|
||||
{
|
||||
main_locale_init(LOCALEDIR, GETTEXT_PACKAGE);
|
||||
@ -467,9 +466,10 @@ void plugin_init(GeanyData *data)
|
||||
g_signal_connect(main_menu_item, "activate",
|
||||
G_CALLBACK(item_activate_cb), NULL);
|
||||
}
|
||||
* @endcode
|
||||
*
|
||||
* @note If you've previously called the PLUGIN_SET_TRANSLATABLE_INFO() you do not
|
||||
* need to call main_locale_init() yourself, as this has been already been
|
||||
* done for you.
|
||||
**/
|
||||
@endcode
|
||||
|
||||
@note If you've previously called the PLUGIN_SET_TRANSLATABLE_INFO() you do not
|
||||
need to call main_locale_init() yourself, as this has been already been
|
||||
done for you.
|
||||
|
||||
*/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user