## TotemPlugin

TotemPlugin — base plugin class and loading/unloading functions

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <totem-plugin.h>

                        TotemPlugin;
                        TotemPluginClass;
    enum                TotemPluginError;
    gboolean            totem_plugin_activate               (TotemPlugin *plugin,
                                                             TotemObject *totem,
                                                             GError **error);
    void                totem_plugin_deactivate             (TotemPlugin *plugin,
                                                             TotemObject *totem);
    GtkWidget *         totem_plugin_create_configure_dialog
                                                            (TotemPlugin *plugin);
    gboolean            totem_plugin_is_configurable        (TotemPlugin *plugin);
    GtkBuilder *        totem_plugin_load_interface         (TotemPlugin *plugin,
                                                             const char *name,
                                                             gboolean fatal,
                                                             GtkWindow *parent,
                                                             gpointer user_data);
    char *              totem_plugin_find_file              (TotemPlugin *plugin,
                                                             const char *file);

## Object Hierarchy

      GObject
       +----TotemPlugin

## Properties

      "name"                     gchar*                : Read / Write

## Description

TotemPlugin is a general-purpose architecture for adding plugins to Totem, with derived support for different programming languages.

## Details

### TotemPlugin

    typedef struct _TotemPlugin TotemPlugin;

All the fields in the TotemPlugin structure are private and should never be accessed directly.

### TotemPluginClass

    typedef struct {
    	GObjectClass parent_class;

    	/* Virtual public methods */

    	TotemPluginActivationFunc activate;
    	TotemPluginDeactivationFunc deactivate;
    	TotemPluginWidgetFunc		create_configure_dialog;
    } TotemPluginClass;

The class structure for the TotemPlParser type.

GObjectClass `parent_class`; | the parent class
TotemPluginActivationFunc `activate`; | function called when activating a plugin using `totem_plugin_activate()`. It must be set by inheriting classes, and should return `TRUE` if it successfully created/got handles to the resources needed by the plugin. If it returns `FALSE`, loading the plugin is abandoned.
TotemPluginDeactivationFunc `deactivate`; | function called when deactivating a plugin using `totem_plugin_deactivate()`; It must be set by inheriting classes, and should free/unref any resources the plugin used.
TotemPluginWidgetFunc `create_configure_dialog`; | function called when configuring a plugin using `totem_plugin_create_configure_dialog()`. If non-`NULL`, it should create and return the plugin's configuration dialog. If `NULL`, the plugin is not configurable.

### enum TotemPluginError

    typedef enum {
    	TOTEM_PLUGIN_ERROR_ACTIVATION
    } TotemPluginError;

Error codes returned by TotemPlugin operations.

`TOTEM_PLUGIN_ERROR_ACTIVATION` | there was an error activating the plugin

### totem_plugin_activate ()

    gboolean            totem_plugin_activate               (TotemPlugin *plugin,
                                                             TotemObject *totem,
                                                             GError **error);

Activates the passed `plugin` by calling its activate method.

`plugin` : | a TotemPlugin
`totem` : | a TotemObject
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success

### totem_plugin_deactivate ()

    void                totem_plugin_deactivate             (TotemPlugin *plugin,
                                                             TotemObject *totem);

Deactivates `plugin` by calling its deactivate method.

`plugin` : | a TotemPlugin
`totem` : | a TotemObject

### totem_plugin_create_configure_dialog ()

    GtkWidget *         totem_plugin_create_configure_dialog
                                                            (TotemPlugin *plugin);

Returns the plugin's configuration dialog, as created by the plugin's create_configure_dialog method.

`plugin` : | a TotemPlugin
Returns : | the configuration dialog, or `NULL`

### totem_plugin_is_configurable ()

    gboolean            totem_plugin_is_configurable        (TotemPlugin *plugin);

Returns `TRUE` if the plugin is configurable and has a configuration dialog. It calls the plugin's is_configurable method.

`plugin` : | a TotemPlugin
Returns : | `TRUE` if the plugin is configurable

### totem_plugin_load_interface ()

    GtkBuilder *        totem_plugin_load_interface         (TotemPlugin *plugin,
                                                             const char *name,
                                                             gboolean fatal,
                                                             GtkWindow *parent,
                                                             gpointer user_data);

Loads an interface file (GtkBuilder UI file) for a plugin, given its filename and assuming it's installed in the plugin's data directory.

This should be used instead of attempting to load interfaces manually in plugins.

`plugin` : | a TotemPlugin
`name` : | interface filename
`fatal` : | `TRUE` if it's a fatal error if the interface can't be loaded
`parent` : | the interface's parent GtkWindow
`user_data` : | a pointer to be passed to each signal handler in the interface when they're called
Returns : | the GtkBuilder instance for the interface

### totem_plugin_find_file ()

    char *              totem_plugin_find_file              (TotemPlugin *plugin,
                                                             const char *file);

Finds the specified `file` by looking in the plugin paths listed by `totem_get_plugin_paths()` and then in the system Totem data directory.

This should be used by plugins to find plugin-specific resource files.

`plugin` : | a TotemPlugin
`file` : | the file to find
Returns : | a newly-allocated absolute path for the file, or `NULL`

## Property Details

### The `"name"` property

      "name"                     gchar*                : Read / Write

The plugin's name. It should be a construction property, but due to the Python plugin hack, it can't be: do not change the name after construction. Should be the same as used for naming plugin- specific resources.

Default value: NULL