Coding plugins

Quick intro

The cssed plugin's API is divided in three layers that let you code using a higer or lower level.

The higer level API are the cssed_plugin_* functions that let you make actions on the currently selected document. Those functions are defined in plugin.h

In a middle level you can get access to some cssed internall objects as the CssedDoc and CssedWindow object. Those functions are defined on cssedwindow.h and document.h.

On the lower level you can get access to the Scintilla widget, that's the cssed's editor component. Throught a message based API you can change the tokenization ( Lexer ), highlighting and all the scintilla's settings.

You can learn more on scintilla at http://scintilla.org. You must use the scintilla provided headers SciLexer.h Scintilla.h and ScintillaWidget.h.

All you need to manage the scintilla editor control is the function scintilla_send_message() defined at Scintilla.h. Check the cssed's document.c source for some examples on using scintilla. All functions called sci_* are just wrappers to scintilla messages.

How it works

To build a cssed plugin you'll need to build a shared library exporting one function that will retrieve a pointer to the CssedPlugin object that implements the plugin.

It's loaded using the g_module interface from GLib.

See http://developer.gnome.org/doc/API/2.0/glib/glib-Dynamic-Loading-of-Modules.html , for more information on g_module.

The only function that should be exported is CssedPlugin *init_plugin(), when called by cssed this function should return a pointer to a CssedPlugin object and will take care to load and unload it via the CssedPlugin object functions.

You must flag it as a visible function to the outside world with G_MODULE_EXPORT.

The CssedPlugin structure

The CssedPlugin structure implements the plugin itself. It must be returned by the exported function CssedPlugin *init_plugin().

This structure is defined in plugin.h;

        typedef struct _CssedPlugin CssedPlugin;

        struct _CssedPlugin
        {
                gchar *name;            
                gchar *description;                                             
                gboolean (*load_plugin) (CssedPlugin*); 
                void (*clean_plugin) (CssedPlugin*);    
                gpointer user_data;     
                CssedPluginPriv* priv;
        };

The quick explanation for those fields is:

• gchar *name - a descriptive name for this plugin
• gchar *description - a brief description for this plugin
• gboolean (*load_plugin) (CssedPlugin*) - the address of a function that will be called by cssed to initiallize the plugin. Bild your UI and put all construction code here.
• void (*clean_plugin) (CssedPlugin*) - the address of a function that will be called by cssed before unload the plugin.Destroy the UI and free all memory here.
• gpointer user_data - a pointer to data to be used by developers (not by cssed, you can store whatever you need here).
• CssedPluginPriv* priv - private data to be used by cssed. This is opaque and should be ignored.

Let's write some code ...

Hello World

This is the samallest cssed plugin that writes "Hello World" to the current document when loaded, and print "Bye World" to stdout when unloaded. Read Compiling for instructions on how to compile this plugin.

        #include <gtk/gtk.h>
        #include <gmodule.h>
        #include <plugin.h>

        // This function should be visible to the outside world
        G_MODULE_EXPORT CssedPlugin* init_plugin();
        
        // Those are prototypes of the CssedPlugin functions
        gboolean load_plugin(CssedPlugin* p);
        void clean_plugin (CssedPlugin* p);
        
        // Let's create a plugin object
        static CssedPlugin plugin =
        {
                "test",          // the plugin's name
                "test plugin",   // a short description
                &load_plugin,    // the load function, will be called by cssed
                &clean_plugin,   // the unload function, will be called by cssed
                NULL,            // user data
                NULL             // this is private, just don't touch it.
        };
        
        // this will send a plugin's structure pointer to the caller.
        G_MODULE_EXPORT CssedPlugin* init_plugin()
        {
                        return &plugin;
        }
        
        // load function called by cssed to load the plugin
        // you should build your UI - if any - here.
        gboolean load_plugin(CssedPlugin* p)
        {
                cssed_plugin_add_text_to_document( &plugin, "Hello World" );
                return TRUE; // tell cssed all gone right
        }
        // unload function called by cssed to unload the plugin
        // you should destroy your UI - if any - here.  
        void clean_plugin( CssedPlugin* p )
        {
                g_print( "Bye World" );
        }       

[ Previous | Main Page | Next ]

---

Back to Index

This documentation is © Iago Rubio Sanfiz, 2004