GritsPlugin

GritsPlugin — Plugin support

Synopsis

GritsPlugin *       (*GritsPluginConstructor)           (GritsViewer *viewer,
                                                         GritsPrefs *prefs);
struct              GritsPluginInterface;
struct              GritsPlugins;
GtkWidget *         grits_plugin_get_config             (GritsPlugin *plugin);
const gchar *       grits_plugin_get_description        (GritsPlugin *plugin);
const gchar *       grits_plugin_get_name               (GritsPlugin *plugin);
GList *             grits_plugins_available             (GritsPlugins *plugins);
gboolean            grits_plugins_disable               (GritsPlugins *plugins,
                                                         const char *name);
GritsPlugin *       grits_plugins_enable                (GritsPlugins *plugins,
                                                         const char *name,
                                                         GritsViewer *viewer,
                                                         GritsPrefs *prefs);
void                grits_plugins_foreach               (GritsPlugins *plugins,
                                                         GCallback callback,
                                                         gpointer user_data);
void                grits_plugins_free                  ();
GritsPlugin *       grits_plugins_load                  (GritsPlugins *plugins,
                                                         const char *name,
                                                         GritsViewer *viewer,
                                                         GritsPrefs *prefs);
GList *             grits_plugins_load_enabled          (GritsPlugins *plugins,
                                                         GritsViewer *viewer,
                                                         GritsPrefs *prefs);
GritsPlugins *      grits_plugins_new                   (const gchar *dir,
                                                         GritsPrefs *prefs);
gboolean            grits_plugins_unload                (GritsPlugins *plugins,
                                                         const char *name);

Description

A plugin in grits is a GObject which implements the GritsPlugin interface. Additionally, each plugin is compiled to a separate shared object and loaded conditionally at runtime when the plugin is enabled. Each such shared object should define a GritsPluginConstructor() function named grits_plugin_NAME_new which will be called when loading the plugin.

Almost all grits functionality is provided by a set of plugins. Each plugin can how however much it likes. The interface between plugins and the rest of grits is intentionally very thin. Since grits is the library, plugins must manually do everything. For instance, to draw something in the world, the plugin must add an object to the viewer. Likewise, plugins need to register callbacks on the viewer in order to receive updates, very little happens automagically.

That being said, one thing that plugins do do automagically, is provide a configuration area. Since the plugin doesn't know what application is is being loaded form, it is better for the application to ask the plugin for it's confirmation area, not the other way around.

Details

GritsPluginConstructor ()

GritsPlugin *       (*GritsPluginConstructor)           (GritsViewer *viewer,
                                                         GritsPrefs *prefs);

Create a new instance of a plugin. Each plugin should supply a constructor named grits_plugin_NAME_new in it's shared object.

viewer :

the viewer the plugin is associated with

prefs :

preferences the plugin can use for storing informtion

Returns :

the new plugin

struct GritsPluginInterface

struct GritsPluginInterface {
	GTypeInterface parent_iface;

	/* Virtual data */
	const gchar *name;
	const gchar *description;

	/* Virtual functions */
	GtkWidget *(*get_config)(GritsPlugin *plugin);
};


struct GritsPlugins

struct GritsPlugins {
	gchar      *dir;
	GList      *plugins;
	GritsPrefs *prefs;
};


grits_plugin_get_config ()

GtkWidget *         grits_plugin_get_config             (GritsPlugin *plugin);

Each plugin can provide a configuration area. Applications using grits should display this configuration area to the user so they can modify the behavior of the plugin.

plugin :

the plugin

Returns :

a configuration widget for the plugin

grits_plugin_get_description ()

const gchar *       grits_plugin_get_description        (GritsPlugin *plugin);

Get a description of a plugin

plugin :

the plugin

Returns :

a description of the plugin

grits_plugin_get_name ()

const gchar *       grits_plugin_get_name               (GritsPlugin *plugin);

Get a short human readable name for a plugin, this is not necessarily the same as the name of the shared object.

plugin :

the plugin

Returns :

a short name for the plugin

grits_plugins_available ()

GList *             grits_plugins_available             (GritsPlugins *plugins);

Search the plugin directory for shared objects which can be loaded as plugins.

plugins :

the plugin source

Returns :

the list of available plugins

grits_plugins_disable ()

gboolean            grits_plugins_disable               (GritsPlugins *plugins,
                                                         const char *name);

Unload a plugin and save it's loaded/unloaded state in the GritsPrefs stored in plugins.

See also: grits_plugins_unload()

plugins :

the plugins source

name :

the name of the plugin to unload

Returns :

FALSE

grits_plugins_enable ()

GritsPlugin *       grits_plugins_enable                (GritsPlugins *plugins,
                                                         const char *name,
                                                         GritsViewer *viewer,
                                                         GritsPrefs *prefs);

Load a plugin and save it's loaded/unloaded state in the GritsPrefs stored in plugins.

See also: grits_plugins_load()

plugins :

the plugins source

name :

the name of the plugin to load

viewer :

a GritsViewer to pass to the plugins constructor

prefs :

a GritsPrefs to pass to the plugins constructor

Returns :

the new plugin

grits_plugins_foreach ()

void                grits_plugins_foreach               (GritsPlugins *plugins,
                                                         GCallback callback,
                                                         gpointer user_data);

Iterate over all plugins loaded by the plugins source

plugins :

the plugins source

callback :

a function to call on each plugin

user_data :

user data to pass to the function

grits_plugins_free ()

void                grits_plugins_free                  ();

Free data used by a plugin source

plugins :

the GritsPlugins to free

grits_plugins_load ()

GritsPlugin *       grits_plugins_load                  (GritsPlugins *plugins,
                                                         const char *name,
                                                         GritsViewer *viewer,
                                                         GritsPrefs *prefs);

name should be the name of the shared object without the file extension. This is the same as what is returned by grits_plugins_available().

When loading plugins, the prefs argument is used, not the GritsPrefs stored in plugins.

plugins :

the plugins source

name :

the name of the plugin to load

viewer :

a GritsViewer to pass to the plugins constructor

prefs :

a GritsPrefs to pass to the plugins constructor

Returns :

the new plugin

grits_plugins_load_enabled ()

GList *             grits_plugins_load_enabled          (GritsPlugins *plugins,
                                                         GritsViewer *viewer,
                                                         GritsPrefs *prefs);

Load all enabled which have previously been enabled.

See also: grits_plugins_load()

plugins :

the plugins source

viewer :

a GritsViewer to pass to the plugins constructor

prefs :

a GritsPrefs to pass to the plugins constructor

Returns :

a list of all loaded plugins

grits_plugins_new ()

GritsPlugins *      grits_plugins_new                   (const gchar *dir,
                                                         GritsPrefs *prefs);

Create a new plugin source. If prefs is not NULL, the state of the plugins will be saved when they are either enabled or disabled.

dir :

the directory to search for plugins in

prefs :

a GritsPrefs to save the state of plugins, or NULL

Returns :

the new plugin source

grits_plugins_unload ()

gboolean            grits_plugins_unload                (GritsPlugins *plugins,
                                                         const char *name);

Unload a plugin and free any associated data.

plugins :

the plugins source

name :

the name of the plugin to unload

Returns :

FALSE