TotemPlugin

## 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            (*TotemPluginActivationFunc)        (TotemPlugin *plugin,
                                                             TotemObject *totem,
                                                             GError **error);
    void                (*TotemPluginDeactivationFunc)      (TotemPlugin *plugin,
                                                             TotemObject *totem);
    GtkWidget *         (*TotemPluginWidgetFunc)            (TotemPlugin *plugin);
    #define             TOTEM_PLUGIN_DEFINE_TYPE            (TypeName,
                                                             type_name,
                                                             TYPE_PARENT)
    #define             TOTEM_PLUGIN_REGISTER               (PluginName,
                                                             plugin_name)
    #define             TOTEM_PLUGIN_REGISTER_EXTENDED      (PluginName,
                                                             plugin_name,
                                                             _C_)
    #define             TOTEM_PLUGIN_REGISTER_TYPE          (type_name)
    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

### TotemPluginActivationFunc ()

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

Called when the user has requested `plugin` be activated, this function should be used to initialise any resources the plugin needs, and attach itself to the Totem UI.

If an error is encountered while setting up the plugin, `error` should be set, and the function should return `FALSE`. Totem will then not mark the plugin as activated, and will ensure it's not loaded again unless explicitly asked for by the user.

`plugin` : | the TotemPlugin
`totem` : | a TotemObject
`error` : | a GError
Returns : | `TRUE` on success, `FALSE` otherwise

### TotemPluginDeactivationFunc ()

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

Called when the user has requested `plugin` be deactivated, this function should destroy all resources created during the plugin's lifetime, especially those created in the activation function.

It should be possible to activate and deactivate the plugin multiple times sequentially in a single Totem session without memory or resource leaks, or errors.

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

### TotemPluginWidgetFunc ()

    GtkWidget *         (*TotemPluginWidgetFunc)            (TotemPlugin *plugin);

Called when the configuration dialogue for the plugin needs to be built, this function should return a complete window which will be shown by the Totem code. The widget needs to be capable of hiding itself when configuration is complete.

If your plugin is not configurable, do not define this function.

`plugin` : | the TotemPlugin
Returns : | a GtkWidget

### TOTEM_PLUGIN_DEFINE_TYPE()

    #define             TOTEM_PLUGIN_DEFINE_TYPE(TypeName, type_name, TYPE_PARENT)

Registers a type to be used inside a Totem plugin, but not the plugin's itself; use `TOTEM_PLUGIN_REGISTER()` for that.

`TypeName` : | the type name in camelcase
`type_name` : | the type name in lowercase, with underscores
`TYPE_PARENT` : | the type's parent name in uppercase, with underscores

### TOTEM_PLUGIN_REGISTER()

    #define             TOTEM_PLUGIN_REGISTER(PluginName, plugin_name)

Registers a new Totem plugin type. A plugin is, at its core, just a class which is instantiated and activated on the user's request. This macro registers that class.

`PluginName` : | the plugin's name in camelcase
`plugin_name` : | the plugin's name in lowercase, with underscores

### TOTEM_PLUGIN_REGISTER_EXTENDED()

    #define             TOTEM_PLUGIN_REGISTER_EXTENDED(PluginName, plugin_name, _C_)

Registers a new Totem plugin type with custom code in the module type registration function. See `TOTEM_PLUGIN_REGISTER()` for more information about the registration process.

A variable named `our_info` is available with the module's GTypeInfo information. `plugin_module_type` is the plugin's GTypeModule. @`plugin_name`_type is the plugin's newly-registered GType (where `plugin_name` is the plugin name passed to the `TOTEM_PLUGIN_REGISTER_EXTENDED()` macro).

`PluginName` : | the plugin's name in camelcase
`plugin_name` : | the plugin's name in lowercase, with underscores
`_C_` : | extra code to call in the module type registration function

### TOTEM_PLUGIN_REGISTER_TYPE()

    #define             TOTEM_PLUGIN_REGISTER_TYPE(type_name)

Calls the type registration function for a type inside a plugin module previously defined with `TOTEM_PLUGIN_DEFINE_TYPE()`.

`type_name` : | the type's name in lowercase, with underscores

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