![]() |
![]() |
![]() |
Grits Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
struct GritsPluginInterface; const gchar * grits_plugin_get_name (GritsPlugin *plugin
); const gchar * grits_plugin_get_description (GritsPlugin *plugin
); GtkWidget * grits_plugin_get_config (GritsPlugin *plugin
); GritsPlugin * (*GritsPluginConstructor) (GritsViewer *viewer
,GritsPrefs *prefs
); struct GritsPlugins; GritsPlugins * grits_plugins_new (const gchar *dir
,GritsPrefs *prefs
); void grits_plugins_free (); GList * grits_plugins_available (GritsPlugins *plugins
); GritsPlugin * grits_plugins_load (GritsPlugins *plugins
,const char *name
,GritsViewer *viewer
,GritsPrefs *prefs
); GritsPlugin * grits_plugins_enable (GritsPlugins *plugins
,const char *name
,GritsViewer *viewer
,GritsPrefs *prefs
); GList * grits_plugins_load_enabled (GritsPlugins *plugins
,GritsViewer *viewer
,GritsPrefs *prefs
); gboolean grits_plugins_disable (GritsPlugins *plugins
,const char *name
); gboolean grits_plugins_unload (GritsPlugins *plugins
,const char *name
); void grits_plugins_foreach (GritsPlugins *plugins
,GCallback callback
,gpointer user_data
);
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.
struct GritsPluginInterface { GTypeInterface parent_iface; /* Virtual data */ const gchar *name; const gchar *description; /* Virtual functions */ GtkWidget *(*get_config)(GritsPlugin *plugin); };
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.
|
the plugin |
Returns : |
a short name for the plugin |
const gchar * grits_plugin_get_description (GritsPlugin *plugin
);
Get a description of a plugin
|
the plugin |
Returns : |
a description of the plugin |
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.
|
the plugin |
Returns : |
a configuration widget for the plugin |
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.
|
the viewer the plugin is associated with |
|
preferences the plugin can use for storing informtion |
Returns : |
the new plugin |
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.
|
the directory to search for plugins in |
|
a GritsPrefs to save the state of plugins, or NULL |
Returns : |
the new plugin source |
void grits_plugins_free ();
Free data used by a plugin source
|
the GritsPlugins to free |
GList * grits_plugins_available (GritsPlugins *plugins
);
Search the plugin directory for shared objects which can be loaded as plugins.
|
the plugin source |
Returns : |
the list of available plugins |
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
.
|
the plugins source |
|
the name of the plugin to load |
|
a GritsViewer to pass to the plugins constructor |
|
a GritsPrefs to pass to the plugins constructor |
Returns : |
the new plugin |
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()
|
the plugins source |
|
the name of the plugin to load |
|
a GritsViewer to pass to the plugins constructor |
|
a GritsPrefs to pass to the plugins constructor |
Returns : |
the new plugin |
GList * grits_plugins_load_enabled (GritsPlugins *plugins
,GritsViewer *viewer
,GritsPrefs *prefs
);
Load all enabled which have previously been enabled.
See also: grits_plugins_load()
|
the plugins source |
|
a GritsViewer to pass to the plugins constructor |
|
a GritsPrefs to pass to the plugins constructor |
Returns : |
a list of all loaded plugins |
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()
|
the plugins source |
|
the name of the plugin to unload |
Returns : |
FALSE |
gboolean grits_plugins_unload (GritsPlugins *plugins
,const char *name
);
Unload a plugin and free any associated data.
|
the plugins source |
|
the name of the plugin to unload |
Returns : |
FALSE |
void grits_plugins_foreach (GritsPlugins *plugins
,GCallback callback
,gpointer user_data
);
Iterate over all plugins loaded by the plugins source
|
the plugins source |
|
a function to call on each plugin |
|
user data to pass to the function |