hi there
i finally finished writing the plugins howto. After three
rewrites I hope this one is good. I kept the example as
short as possible, as I don't want to explain the whole API
in it (for that we have the documentation). I just wanted
to write how to write a plugin.
I also added the sample source code used and I think this
should be downloadable for the user to test.
Greets
Tobias
------------------------------------------------------------------------
/This short tutorial shall give you a short introduction in plugin
development for beaver. It does not contain the full API documentation
(for that see the documentation section)./
Introduction
The following small sample plugin will create a menu entry which will
report the selected text in a message box. We will go step by step
through the development progress and provide the full source code of
the example at the end.
The Code
the init function
In beaver a plugin can have a init function. This function gets called
when the user activates the plugin in the Plugin Manager (by enabling
the checkbox). So the first thing we do, is to write this init function.
/#include "beaver.h"/ /* including the beaver API */
*static* gint menu_id = 0;
*static void* init (*void*)
{
menu_id = beaver_ui_item_add (BEAVER_SECTION_MENU_TOOLS, "Sample", NULL,
"_Sample Entry", sample_clicked);
}
This will add a menu into the tools menu with the text "_S_ample
Entry". When this entry get's clicked the function /sample_clicked/
gets called. We also have to provide a unique name for every menu
entry we create. We called this entry "Sample". We need this name and
the returned /menu_id/ to cleanup afterwards.
the cleanup function
Similar to the init function, the cleanup function gets called when
the user deactivates the plugin. We use this function to free up
allocated space as well as to remove menu entries and such.
*static void* cleanup (*void*)
{
beaver_ui_item_remove (menu_id, "Sample");
}
This simply removes the menu entry we made before. As you can see
here, we need the /menu_id/ as well as the unique name
the menu handler
In the /init/ function we saw that we registered the function
/sample_clicked/ as handler when the menu gets clicked. We now write
this menu handler
*static void* sample_clicked (*void*)
{
gchar* selection = beaver_text_selection_get ();
if (selection != NULL) {
beaver_box_message (selection);
g_free (selection);
}
}
This will simply read out the selected text and print it out in a
message box (if any text was selected)
the preferences function
A plugin in beaver can have some preferences. For that in the Plugin
Manager the user can press a preferences button. We now write a
function for this button.
*static void* preferences (*void*)
{
beaver_box_error ("Hello World!");
}
This will simply output a message box with "Hello World!" written in
it, when the user presses the preferences button.
finishing touches
We now have written some functions, but now we have to tell beaver
which function to use for which task. We also want to tell beaver the
author, version and a short description of our plugin. For that we
have simple macros.
PLUGIN_NAME("Sample Plugin")
PLUGIN_DESCRIPTION("A small simple plugin.")
PLUGIN_AUTHOR("John Doe")
PLUGIN_VERSION("1.0")
PLUGIN_INIT(init)
PLUGIN_CLEANUP(cleanup)
PLUGIN_PREFERENCE(preferences)
Compiling the code
To compile our sourcecode we create a simple Makefile.
export OBJECTS = sample.o
export NAME = sample.so
BEAVER_INCLUDE_DIR = `beaver --include-dir`
all:
make -C ${BEAVER_INCLUDE_DIR} DIR=`pwd` module
clean:
make -C ${BEAVER_INCLUDE_DIR} DIR=`pwd` clean
install:
make -C ${BEAVER_INCLUDE_DIR} DIR=`pwd` install
install_local:
make -C ${BEAVER_INCLUDE_DIR} DIR=`pwd` install_local
The OBJECTS contains all files we want to include in our plugin (this
is simply all C files in our directory with the extension .o). The
NAME gives us the filename of our plugin. We do not have to write or
change anything else, as everything gets handled by beaver itself. All
dependencies and include files are automatically included. After you
compiled the project with /make/. You can install it. For that you
have two options: /make install/ or /make install_local/. The first
will install the plugin in the plugins directory of beaver, so that
every user can access it. For that you need superuser privileges. If
you don't have these or if you want only to test it yourself, you can
install it locally for your user. In this case, the plugin will be
installed in you home directory.
Final Words
The beaver API allows you to use all GTK and glib functions. So it is
possible to create complete Windows with widgets etc. There are no
limits for your imagination
Source
You can download the sourcecode of this sample plugin here
<sample.tar.gz>
------------------------------------------------------------------------
_______________________________________________
Beaver-devel mailing list
address@hidden
http://lists.nongnu.org/mailman/listinfo/beaver-devel