[Beaver-devel] [beaver] plugins howto

[t.heinzen]

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 "Sample 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
Description: application/gzip