PeasExtensionSet

## PeasExtensionSet PeasExtensionSet — Proxy for a set of extensions of the same type. |

## Synopsis

    struct              PeasExtensionSet;
    struct              PeasExtensionSetClass;
    void                (*PeasExtensionSetForeachFunc)      (PeasExtensionSet *set,
                                                             PeasPluginInfo *info,
                                                             PeasExtension *exten,
                                                             gpointer data);
    gboolean            peas_extension_set_call             (PeasExtensionSet *set,
                                                             const gchar *method_name,
                                                             ...);
    gboolean            peas_extension_set_call_valist      (PeasExtensionSet *set,
                                                             const gchar *method_name,
                                                             va_list va_args);
    gboolean            peas_extension_set_callv            (PeasExtensionSet *set,
                                                             const gchar *method_name,
                                                             GIArgument *args);
    void                peas_extension_set_foreach          (PeasExtensionSet *set,
                                                             PeasExtensionSetForeachFunc func,
                                                             gpointer data);
    PeasExtension *     peas_extension_set_get_extension    (PeasExtensionSet *set,
                                                             PeasPluginInfo *info);
    PeasExtensionSet *  peas_extension_set_new              (PeasEngine *engine,
                                                             GType exten_type,
                                                             const gchar *first_property,
                                                             ...);
    PeasExtensionSet *  peas_extension_set_newv             (PeasEngine *engine,
                                                             GType exten_type,
                                                             guint n_parameters,
                                                             GParameter *parameters);
    PeasExtensionSet *  peas_extension_set_new_valist       (PeasEngine *engine,
                                                             GType exten_type,
                                                             const gchar *first_property,
                                                             va_list var_args);

## Object Hierarchy

      GObject
       +----PeasExtensionSet

## Properties

      "construct-properties"     gpointer              : Write / Construct Only
      "engine"                   PeasEngine*           : Read / Write / Construct Only
      "extension-type"           GType*                : Read / Write / Construct Only

## Signals

      "extension-added"                                : Run Last
      "extension-removed"                              : Run Last

## Description

A PeasExtensionSet is an object which proxies method calls to a set of actual extensions. The application writer will use these objects in order to call methods on several instances of an actual extension exported by all the currently loaded plugins.

PeasExtensionSet will automatically track loading and unloading of the plugins, and signal appearance and disappearance of new extension instances. You should connect to those signals if you wish to call specific methods on loading or unloading time.

Here is the code for a typical setup of PeasExtensionSet with PeasActivatable as the watched extension point, and GtkWindow instances as the target objects:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    static void
    on_extension_added (PeasExtensionSet *set,
                        PeasPluginInfo   *info,
                        PeasActivatable  *activatable)
    {
      peas_activatable_activate (activatable);
    }

    static void
    on_extension_removed (PeasExtensionSet *set,
                          PeasPluginInfo   *info,
                          PeasActivatable  *activatable)
    {
      peas_activatable_deactivate (activatable);
    }

    PeasExtensionSet *
    setup_extension_set (PeasEngine *engine,
                         GtkWindow  *window)
    {
      PeasExtensionSet *set;

      set = peas_extension_set_new (engine, PEAS_TYPE_ACTIVATABLE,
                                    "object", window, NULL);
      peas_extension_set_foreach (set,
                                  (PeasExtensionSetForeachFunc) on_extension_added,
                                  NULL);
      g_signal_connect (set, "extension-added",
                        G_CALLBACK (on_extension_added), NULL);
      g_signal_connect (set, "extension-removed",
                        G_CALLBACK (on_extension_removed), NULL);
      return set;
    }

## Details

### struct PeasExtensionSet

    struct PeasExtensionSet;

The PeasExtensionSet structure contains only private data and should only be accessed using the provided API.

### struct PeasExtensionSetClass

    struct PeasExtensionSetClass {
      GObjectClass parent_class;

      /* Virtual public methods */
    #ifndef PEAS_DISABLE_DEPRECATED
      gboolean   (*call)                      (PeasExtensionSet *set,
                                               const gchar      *method_name,
                                               GIArgument       *args);
    #else
      /* Signals */
      void       (*extension_added)           (PeasExtensionSet *set,
                                               PeasPluginInfo   *info,
                                               PeasExtension    *exten);
      void       (*extension_removed)         (PeasExtensionSet *set,
                                               PeasPluginInfo   *info,
                                               PeasExtension    *exten);
    };

The class structure for PeasExtensionSet.

GObjectClass `parent_class`; | The parent class.
`call` () | The VFunc for `peas_extension_set_call()`.
`extension_added` () | Signal class handler for the "extension-added" signal.
`extension_removed` () | Signal class handler for the "extension-removed" signal.

### PeasExtensionSetForeachFunc ()

    void                (*PeasExtensionSetForeachFunc)      (PeasExtensionSet *set,
                                                             PeasPluginInfo *info,
                                                             PeasExtension *exten,
                                                             gpointer data);

This function is passed to `peas_extension_set_foreach()` and will be called for each extension in `set`.

`set` : | A PeasExtensionSet.
`info` : | A PeasPluginInfo.
`exten` : | A PeasExtension.
`data` : | Optional data passed to the function.

Since 1.2

### peas_extension_set_call ()

    gboolean            peas_extension_set_call             (PeasExtensionSet *set,
                                                             const gchar *method_name,
                                                             ...);

### Warning

`peas_extension_set_call` has been deprecated since version 1.2 and should not be used in newly-written code. Use `peas_extension_set_foreach()` instead.

Call a method on all the PeasExtension instances contained in `set`.

See `peas_extension_call()` for more information.

`set` : | A PeasExtensionSet.
`method_name` : | the name of the method that should be called.
`...` : | arguments for the method.
Returns : | `TRUE` on successful call.

### peas_extension_set_call_valist ()

    gboolean            peas_extension_set_call_valist      (PeasExtensionSet *set,
                                                             const gchar *method_name,
                                                             va_list va_args);

### Warning

`peas_extension_set_call_valist` has been deprecated since version 1.2 and should not be used in newly-written code. Use `peas_extension_set_foreach()` instead.

Call a method on all the PeasExtension instances contained in `set`.

See `peas_extension_call_valist()` for more information.

`set` : | A PeasExtensionSet.
`method_name` : | the name of the method that should be called.
`va_args` : | the arguments for the method.
Returns : | `TRUE` on successful call.

### peas_extension_set_callv ()

    gboolean            peas_extension_set_callv            (PeasExtensionSet *set,
                                                             const gchar *method_name,
                                                             GIArgument *args);

### Warning

`peas_extension_set_callv` has been deprecated since version 1.2 and should not be used in newly-written code. Use `peas_extension_set_foreach()` instead.

Call a method on all the PeasExtension instances contained in `set`.

See `peas_extension_callv()` for more information.

`set` : | A PeasExtensionSet.
`method_name` : | the name of the method that should be called.
`args` : | the arguments for the method.
Returns : | `TRUE` on successful call.

### peas_extension_set_foreach ()

    void                peas_extension_set_foreach          (PeasExtensionSet *set,
                                                             PeasExtensionSetForeachFunc func,
                                                             gpointer data);

Calls `func` for each PeasExtension.

`set` : | A PeasExtensionSet.
`func` : | A function call for each extension. [scope call]
`data` : | Optional data to be passed to the function or `NULL`.

Since 1.2

### peas_extension_set_get_extension ()

    PeasExtension *     peas_extension_set_get_extension    (PeasExtensionSet *set,
                                                             PeasPluginInfo *info);

Returns the PeasExtension object corresponding to `info`, or `NULL` if the plugin doesn't provide such an extension.

`set` : | A PeasExtensionSet
`info` : | a PeasPluginInfo
Returns : | a reference to a PeasExtension or `NULL`. [transfer none]

### peas_extension_set_new ()

    PeasExtensionSet *  peas_extension_set_new              (PeasEngine *engine,
                                                             GType exten_type,
                                                             const gchar *first_property,
                                                             ...);

Create a new PeasExtensionSet for the `exten_type` extension type.

At any moment, the PeasExtensionSet will contain an extension instance for each loaded plugin which implements the `exten_type` extension type. It does so by connecting to the relevant signals from PeasEngine.

The property values passed to `peas_extension_set_new()` will be used for the construction of new extension instances.

If `engine` is `NULL`, then the default engine will be used.

See `peas_engine_create_extension()` for more information.

`engine` : | A PeasEngine, or `NULL`.
`exten_type` : | the extension GType.
`first_property` : | the name of the first property.
`...` : | the value of the first property, followed optionally by more name/value pairs, followed by `NULL`.
Returns : | a new instance of PeasExtensionSet.

### peas_extension_set_newv ()

    PeasExtensionSet *  peas_extension_set_newv             (PeasEngine *engine,
                                                             GType exten_type,
                                                             guint n_parameters,
                                                             GParameter *parameters);

Create a new PeasExtensionSet for the `exten_type` extension type.

If `engine` is `NULL`, then the default engine will be used.

See `peas_extension_set_new()` for more information.

`engine` : | A PeasEngine, or `NULL`. [allow-none]
`exten_type` : | the extension GType.
`n_parameters` : | the length of the `parameters` array.
`parameters` : | an array of GParameter. [array length=n_parameters]
Returns : | a new instance of PeasExtensionSet. Rename to: peas_extension_set_new. [transfer full]

### peas_extension_set_new_valist ()

    PeasExtensionSet *  peas_extension_set_new_valist       (PeasEngine *engine,
                                                             GType exten_type,
                                                             const gchar *first_property,
                                                             va_list var_args);

Create a new PeasExtensionSet for the `exten_type` extension type.

If `engine` is `NULL`, then the default engine will be used.

See `peas_extension_set_new()` for more information.

`engine` : | A PeasEngine, or `NULL`.
`exten_type` : | the extension GType.
`first_property` : | the name of the first property.
`var_args` : | the value of the first property, followed optionally by more name/value pairs, followed by `NULL`.
Returns : | a new instance of PeasExtensionSet.

## Property Details

### The `"construct-properties"` property

      "construct-properties"     gpointer              : Write / Construct Only

The properties to pass the extensions when creating them.

### The `"engine"` property

      "engine"                   PeasEngine*           : Read / Write / Construct Only

The PeasEngine this set is attached to.

### The `"extension-type"` property

      "extension-type"           GType*                : Read / Write / Construct Only

The extension GType managed by this set.

Allowed values: void

## Signal Details

### The `"extension-added"` signal

    void                user_function                      (PeasExtensionSet *set,
                                                            PeasPluginInfo   *info,
                                                            GObject          *exten,
                                                            gpointer          user_data)      : Run Last

The extension-added signal is emitted when a new extension has been added to the PeasExtensionSet. It happens when a new plugin implementing the extension set's extension type is loaded.

You should connect to this signal in order to set up the extensions when they are loaded. Note that this signal is not fired for extensions coming from plugins that were already loaded when the PeasExtensionSet instance was created. You should set those up by yourself.

`set` : | A PeasExtensionSet.
`info` : | A PeasPluginInfo.
`exten` : | A PeasExtension.
`user_data` : | user data set when the signal handler was connected.

### The `"extension-removed"` signal

    void                user_function                      (PeasExtensionSet *set,
                                                            PeasPluginInfo   *info,
                                                            GObject          *exten,
                                                            gpointer          user_data)      : Run Last

The extension-removed signal is emitted when a new extension is about to be removed from the PeasExtensionSet. It happens when a plugin implementing the extension set's extension type is unloaded, or when the PeasExtensionSet itself is destroyed.

You should connect to this signal in order to clean up the extensions when their plugin is unload. Note that this signal is not fired for the PeasExtension instances still available when the PeasExtensionSet instance is destroyed. You should clean those up by yourself.

`set` : | A PeasExtensionSet.
`info` : | A PeasPluginInfo.
`exten` : | A PeasExtension.
`user_data` : | user data set when the signal handler was connected.

## See Also

PeasExtension