## 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`