ThunarxProviderPlugin

3 THUNARX Library

ThunarxProviderPlugin

The interface to the plugin type registration

## Stability Level

Stable, unless otherwise indicated

# Synopsis

    #include <thunarx/thunarx.h>

                        ThunarxProviderPlugin;
                        ThunarxProviderPluginIface;
    gboolean            thunarx_provider_plugin_get_resident
                                                            (const ThunarxProviderPlugin *plugin);
    void                thunarx_provider_plugin_set_resident
                                                            (ThunarxProviderPlugin *plugin,
                                                             gboolean resident);
    GType               thunarx_provider_plugin_register_type
                                                            (ThunarxProviderPlugin *plugin,
                                                             GType type_parent,
                                                             const gchar *type_name,
                                                             const GTypeInfo *type_info,
                                                             GTypeFlags type_flags);
    void                thunarx_provider_plugin_add_interface
                                                            (ThunarxProviderPlugin *plugin,
                                                             GType instance_type,
                                                             GType interface_type,
                                                             const GInterfaceInfo *interface_info);
    GType               thunarx_provider_plugin_register_enum
                                                            (ThunarxProviderPlugin *plugin,
                                                             const gchar *name,
                                                             const GEnumValue *const _static_values);
    GType               thunarx_provider_plugin_register_flags
                                                            (ThunarxProviderPlugin *plugin,
                                                             const gchar *name,
                                                             const GFlagsValue *const _static_values);
    #define             THUNARX_DEFINE_TYPE                 (TN, t_n, T_P)
    #define             THUNARX_DEFINE_TYPE_WITH_CODE       (TN, t_n, T_P, _C_)
    #define             THUNARX_DEFINE_ABSTRACT_TYPE        (TN, t_n, T_P)
    #define             THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_)
    #define             THUNARX_DEFINE_TYPE_EXTENDED        (TypeName, type_name, TYPE_PARENT, flags, CODE)
    #define             THUNARX_IMPLEMENT_INTERFACE         (TYPE_IFACE, iface_init)

## Object Hierarchy

      GInterface
       +----ThunarxProviderPlugin

## Properties

      "resident"                 gboolean              : Read / Write

## Description

`ThunarxProviderPlugin` is the interface to the file manager's type plugin loader implementation. It provides methods to extensions - also called provider plugins - to register dynamic types and control certain aspects of the plugin (see `thunarx_provider_plugin_set_resident()`).

## Details

### ThunarxProviderPlugin

    typedef struct _ThunarxProviderPlugin ThunarxProviderPlugin;

The `ThunarxProviderPlugin` struct is just a typedef for the interface instance type.

### ThunarxProviderPluginIface

    typedef struct {
      gboolean (*get_resident)    (const ThunarxProviderPlugin *plugin);
      void     (*set_resident)    (ThunarxProviderPlugin       *plugin,
                                   gboolean                     resident);

      GType    (*register_type)   (ThunarxProviderPlugin       *plugin,
                                   GType                        type_parent,
                                   const gchar                 *type_name,
                                   const GTypeInfo             *type_info,
                                   GTypeFlags                   type_flags);
      void     (*add_interface)   (ThunarxProviderPlugin       *plugin,
                                   GType                        instance_type,
                                   GType                        interface_type,
                                   const GInterfaceInfo        *interface_info);
      GType    (*register_enum)   (ThunarxProviderPlugin       *plugin,
                                   const gchar                 *name,
                                   const GEnumValue            *const_static_values);
      GType    (*register_flags)  (ThunarxProviderPlugin       *plugin,
                                   const gchar                 *name,
                                   const GFlagsValue           *const_static_values);
    } ThunarxProviderPluginIface;

Interface with virtual methods implemented by the file manager and accessible from the extensions.

get_resident ()

- see `thunarx_provider_plugin_get_resident()`.

set_resident ()

- see `thunarx_provider_plugin_set_resident()`.

register_type ()

- see `thunarx_provider_plugin_register_type()`.

add_interface ()

- see `thunarx_provider_plugin_add_interface()`.

register_enum ()

- see `thunarx_provider_plugin_register_enum()`.

register_flags ()

- see `thunarx_provider_plugin_register_flags()`.

### thunarx_provider_plugin_get_resident ()

    gboolean            thunarx_provider_plugin_get_resident
                                                            (const ThunarxProviderPlugin *plugin);

Determines whether the application is allowed to unload `plugin` from memory when no longer needed and reload it on demand. If `FALSE` is returned, then the application may unload `plugin`, else if `TRUE` is returned the application will take care that `plugin` is never unloaded from memory during the lifetime of the application.

`plugin` :

- a `ThunarxProviderPlugin`.

Returns :

- `TRUE` if `plugin` will be kept in memory once loaded for the first time.

### thunarx_provider_plugin_set_resident ()

    void                thunarx_provider_plugin_set_resident
                                                            (ThunarxProviderPlugin *plugin,
                                                             gboolean resident);

This method is used to instruct the application that `plugin` must be kept in memory during the lifetime of the application. The default is to allow the application to unload `plugin` from the memory when no longer needed. If this method is invoked with a `resident` value of `TRUE` then the application will never try to unload `plugin`.

This method has no effect unless called from the `thunar_extension_initialize` method of the `plugin`.

`plugin` :

- a `ThunarxProviderPlugin`.

`resident` :

- `TRUE` to make `plugin` resident in memory.

### thunarx_provider_plugin_register_type ()

    GType               thunarx_provider_plugin_register_type
                                                            (ThunarxProviderPlugin *plugin,
                                                             GType type_parent,
                                                             const gchar *type_name,
                                                             const GTypeInfo *type_info,
                                                             GTypeFlags type_flags);

Looks up or registers a type that is implemented with a particular type `plugin`. If a type with name `type_name` was previously registered, the `GType` identifier for the type is returned, otherwise the type is newly registered, and the resulting `GType` identifier returned.

When reregistering a type (typically because a module is unloaded then reloaded, and reinitialized), module and `type_parent` must be the same as they were previously.

`plugin` :

- a `ThunarxProviderPlugin`.

`type_parent` :

- the type for the parent class.

`type_name` :

- name for the type.

`type_info` :

- type information structure.

`type_flags` :

- flags field providing details about the type.

Returns :

- the new or existing type id.

### thunarx_provider_plugin_add_interface ()

    void                thunarx_provider_plugin_add_interface
                                                            (ThunarxProviderPlugin *plugin,
                                                             GType instance_type,
                                                             GType interface_type,
                                                             const GInterfaceInfo *interface_info);

Registers an additional interface for a type, whose interface lives in the given type `plugin`. If the interface was already registered for the type in this `plugin`, nothing will be done.

As long as any instances of the type exist, the type `plugin` will not be unloaded.

`plugin` :

- a `ThunarxProviderPlugin`.

`instance_type` :

- type to which to add the interface.

`interface_type` :

- interface type to add.

`interface_info` :

- type information structure.

### thunarx_provider_plugin_register_enum ()

    GType               thunarx_provider_plugin_register_enum
                                                            (ThunarxProviderPlugin *plugin,
                                                             const gchar *name,
                                                             const GEnumValue *const _static_values);

Looks up or registers an enumeration that is implemented with a particular type `plugin`. If a type with name `name` was previously registered, the `GType` identifier for the type is returned, otherwise the type is newly registered, and the resulting `GType` identifier returned.

As long as any instances of the type exist, the type `plugin` will not be unloaded.

`plugin` :

- a `ThunarxProviderPlugin`.

`name` :

- the name for the type.

`_static_values` :

Returns :

- the new or existing type id.

### thunarx_provider_plugin_register_flags ()

    GType               thunarx_provider_plugin_register_flags
                                                            (ThunarxProviderPlugin *plugin,
                                                             const gchar *name,
                                                             const GFlagsValue *const _static_values);

Looks up or registers a flags type that is implemented with a particular type `plugin`. If a type with name qname was previously registered, the `GType` identifier for the type is returned, otherwise the type is newly registered, and the resulting `GType` identifier returned.

As long as any instances of the type exist, the type `plugin` will not be unloaded.

`plugin` :

- a `ThunarxProviderPlugin`.

`name` :

- name for the type.

`_static_values` :

Returns :

- the new or existing type id.

### THUNARX_DEFINE_TYPE()

    #define THUNARX_DEFINE_TYPE(TN, t_n, T_P)                         THUNARX_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})

A convenience macro for plugin type implementations, which declares a class initialization function, a static variable named `t_n`_parent_class pointing to the parent and a static variable named `t_n`_type containing the `GType` of the type to define. Furthermore, it defines a `t_n``_get_type()` function and a `t_n``_register_type()` function. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

`TN` :

- the name of the new type, in Camel case.

`t_n` :

- the name of the new type, in lowercase, with words separated by '_'.

`T_P` :

- the `GType` of the parent type.

### THUNARX_DEFINE_TYPE_WITH_CODE()

    #define THUNARX_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_)          THUNARX_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, _C_)

A convenience macro for plugin type implementations. Similar to `THUNARX_DEFINE_TYPE()`, but allows to insert custom code into the `*`_get_type()`` function, e.g. interface implemenations via `THUNARX_IMPLEMENT_INTERFACE()`. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

`TN` :

- the name of the new type, in Camel case.

`t_n` :

- the name of the new type, in lowercase, with words separated by '_'.

`T_P` :

- the `GType` of the parent type.

`_C_` :

- custom code that gets inserted in the `*`_get_type()`` function.

### THUNARX_DEFINE_ABSTRACT_TYPE()

    #define THUNARX_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P)                THUNARX_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})

A convenience macro for plugin type implementations. Similar to `THUNARX_DEFINE_TYPE()`, but defines an abstract type. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

`TN` :

- the name of the new type, in Camel case.

`t_n` :

- the name of the new type, in lowercase, with words separated by '_'.

`T_P` :

- the `GType` of the parent type.

### THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE()

    #define THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) THUNARX_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, _C_)

A convenience macro for plugin type implementations. Similar to `THUNARX_DEFINE_TYPE_WITH_CODE()`, but defines an abstract type and allows to insert custom code into the `*`_get_type()`` function, e.g. interface implementations via `THUNARX_IMPLEMENT_INTERFACE()`. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

`TN` :

- the name of the new type, in Camel case.

`t_n` :

- the name of the new type, in lowercase, with words separated by '_'.

`T_P` :

- the `GType` of the parent type.

`_C_` :

- custom code that gets inserted in the `*`_get_type()`` function.

### THUNARX_DEFINE_TYPE_EXTENDED()

    #define             THUNARX_DEFINE_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE)

The most general convenience macro for plugin type implementations, on which `THUNARX_DEFINE_TYPE()`, `THUNARX_DEFINE_TYPE_WITH_CODE()`, `THUNARX_DEFINE_ABSTRACT_TYPE()` and `THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE()` are based.

    THUNARX_DEFINE_TYPE_EXTENDED (FooExtension,
                                  foo_extension,
                                  G_TYPE_OBJECT,
                                  0,
                                  THUNARX_IMPLEMENT_INTERFACE (TYPE_BAR,
                                                               foo_extension_bar_init));

expands to

    static gpointer foo_extension_parent_class = NULL;
    static GType    foo_extension_type = G_TYPE_INVALID;

    static void     foo_extension_init              (FooExtension *self);
    static void     foo_extension_class_init        (FooExtensionClass *klass);
    static void     foo_extension_class_intern_init (FooExtensionClass *klass)
    {
      foo_extension_parent_class = g_type_class_peek_parent (klass);
      foo_extension_class_init (klass);
    }

    GType
    foo_extension_get_type (void)
    {
      return foo_extension_type;
    }

    void
    foo_extension_register_type (ThunarxProviderPlugin *plugin)
    {
      GType thunarx_define_type_id;
      static const thunarx_define_type_info =
      {
        sizeof (FooExtensionClass),
        NULL,
        NULL,
        (GClassInitFunc) foo_extension_class_intern_init,
        NULL,
        NULL,
        sizeof (FooExtension),
        0,
        (GInstanceInitFunc) foo_extension_init,
        NULL,
      };
      thunarx_define_type_id = thunarx_provider_plugin_register_type (thunarx_define_type_plugin, G_TYPE_OBJECT,
                                                                      "FooExtension", &thunarx_define_type_info, 0);
      {
        static const GInterfaceInfo thunarx_implement_interface_info =
        {
          (GInterfaceInitFunc) foo_extension_bar_init,
        };
        thunarx_provider_plugin_add_interface (thunarx_define_type_plugin, thunarx_define_type_id,
                                               TYPE_BAR, &thunarx_implement_interface_info);
      };
      foo_extension_type = thunarx_define_type_id;
    }

The only pieces which have to be manually provided are the definitions of the instance and class structure and the definitions of the instance and class init functions.

`TypeName` :

- The name of the new type, in Camel case.

`type_name` :

- The name of the new type, in lowercase, with words separated by '_'.

`TYPE_PARENT` :

- The `GType` of the parent type.

`flags` :

- `GTypeFlags` to pass to `thunarx_provider_plugin_register_type()`.

`CODE` :

- Custom code that gets inserted in the `*`_register_type()`` function.

### THUNARX_IMPLEMENT_INTERFACE()

    #define             THUNARX_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init)

A convenience macro to ease interface addition in the `_C_` section of `THUNARX_DEFINE_TYPE_WITH_CODE()` or `THUNARX_DEFINE_ABSTRACT_TYPE_WITH_CODE()`. See `THUNARX_DEFINE_TYPE_EXTENDED()` for an example.

Note that this macro can only be used together with the `THUNARX_DEFINE_*` macros, since it depends on variable names used by those macros.

`TYPE_IFACE` :

- the `GType` of the interface to add.

`iface_init` :

- the interface init function.

## Property Details

### The "`resident`" property

      "resident"                 gboolean              : Read / Write

Tells whether a plugin must reside in memory once loaded for the first time. See `thunarx_provider_plugin_get_resident()` and `thunarx_provider_plugin_set_resident()` for more details.

Default value: FALSE

## See Also

`ThunarxProviderFactory`