GimpModule 3 LIBGIMPMODULE Library
GimpModule A GTypeModule subclass which implements module loading using GModule.

## Synopsis

    struct      GimpModule;
    struct      GimpModuleInfo;
    enum        GimpModuleState;
    const GimpModuleInfo* (*GimpModuleQueryFunc)
                                                (GTypeModule *module);
    gboolean    (*GimpModuleRegisterFunc)       (GTypeModule *module);
    #define     GIMP_MODULE_ABI_VERSION
    #define     GIMP_MODULE_PARAM_SERIALIZE
    GimpModule* gimp_module_new                 (const gchar *filename,
                                                 gboolean load_inhibit,
                                                 gboolean verbose);
    void        gimp_module_modified            (GimpModule *module);
    gboolean    gimp_module_query_module        (GimpModule *module);
    void        gimp_module_set_load_inhibit    (GimpModule *module,
                                                 gboolean load_inhibit);
    const gchar* gimp_module_state_name         (GimpModuleState state);
    GType       gimp_module_register_enum       (GTypeModule *module,
                                                 const gchar *name,
                                                 const GEnumValue *const_static_values);
    GimpModuleInfo* gimp_module_info_new        (guint32 abi_version,
                                                 const gchar *purpose,
                                                 const gchar *author,
                                                 const gchar *version,
                                                 const gchar *copyright,
                                                 const gchar *date);
    GimpModuleInfo* gimp_module_info_copy       (const GimpModuleInfo *info);
    void        gimp_module_info_free           (GimpModuleInfo *info);

## Object Hierarchy

      GObject
       +----GTypeModule
             +----GimpModule

## Implemented Interfaces

GimpModule implements GTypePlugin.

## Signal Prototypes

    "modified"  void        user_function      (GimpModule *gimpmodule,
                                                gpointer user_data);

## Description

A GTypeModule subclass which implements module loading using GModule.

## Details

### struct GimpModule

    struct GimpModule {
      gchar           *filename;     /* path to the module                       */
      gboolean         verbose;      /* verbose error reporting                  */
      GimpModuleState  state;        /* what's happened to the module            */
      gboolean         on_disk;      /* TRUE if file still exists                */
      gboolean         load_inhibit; /* user requests not to load at boot time   */

      /* stuff from now on may be NULL depending on the state the module is in   */
      GimpModuleInfo  *info;         /* returned values from module_query        */
      gchar           *last_module_error;

    };

GimpModule is a generic mechanism to dynamically load modules into the GIMP. It is a GTypeModule subclass, implementing module loading using GModule. GimpModule does not know which functionality is implemented by the modules, it just provides a framework to get arbitrary GType implementations loaded from disk.

GimpModule

### struct GimpModuleInfo

    struct GimpModuleInfo {

      guint32  abi_version;
      gchar   *purpose;
      gchar   *author;
      gchar   *version;
      gchar   *copyright;
      gchar   *date;
    };

This structure contains information about a loadable module.

guint32 abi_version

  The GIMP_MODULE_ABI_VERSION the module was compiled against.

gchar *purpose

  The module's general purpose.

gchar *author

  The module's author.

gchar *version

  The module's version.

gchar *copyright

  The module's copyright.

gchar *date

  The module's release date.

GimpModuleInfo

### enum GimpModuleState

    typedef enum
    {
      GIMP_MODULE_STATE_ERROR,       /* missing gimp_module_register function
                                      * or other error
                                      */
      GIMP_MODULE_STATE_LOADED,      /* an instance of a type implemented by
                                      * this module is allocated
                                      */
      GIMP_MODULE_STATE_LOAD_FAILED, /* gimp_module_register returned FALSE
                                      */
      GIMP_MODULE_STATE_NOT_LOADED   /* there are no instances allocated of
                                      * types implemented by this module
                                      */
    } GimpModuleState;

The possible states a GimpModule can be in.

`GIMP_MODULE_STATE_ERROR`

  Missing `gimp_module_register()` function or other error.

`GIMP_MODULE_STATE_LOADED`

  An instance of a type implemented by this module is allocated.

`GIMP_MODULE_STATE_LOAD_FAILED`

  `gimp_module_register()` returned FALSE.

`GIMP_MODULE_STATE_NOT_LOADED`

  There are no instances allocated of types implemented by this module.

GimpModuleState

### GimpModuleQueryFunc ()

    const GimpModuleInfo* (*GimpModuleQueryFunc)
                                                (GTypeModule *module);

The signature of the query function a loadable GIMP module must implement. In the module, the function must be called `gimp_module_query()`.

GimpModule will copy the returned GimpModuleInfo struct, so the module doesn't need to keep these values around (however in most cases the module will just return a pointer to a constant structure).

module :

  The GimpModule responsible for this loadable module.

Returns :

  The GimpModuleInfo struct describing the module.

GimpModuleQueryFunc

### GimpModuleRegisterFunc ()

    gboolean    (*GimpModuleRegisterFunc)       (GTypeModule *module);

The signature of the register function a loadable GIMP module must implement. In the module, the function must be called `gimp_module_register()`.

When this function is called, the module should register all the types it implements with the passed module.

module :

  The GimpModule responsible for this loadable module.

Returns :

  TRUE on success, FALSE otherwise.

GimpModuleRegisterFunc

### GIMP_MODULE_ABI_VERSION

    #define GIMP_MODULE_ABI_VERSION 0x0004

The version of the module system's ABI. Modules put this value into GimpModuleInfo's abi_version field so the code loading the modules can check if it was compiled against the same module ABI the modules are compiled against.

GIMP_MODULE_ABI_VERSION

### GIMP_MODULE_PARAM_SERIALIZE

    #define GIMP_MODULE_PARAM_SERIALIZE (1 << (0 + G_PARAM_USER_SHIFT))

GIMP_MODULE_PARAM_SERIALIZE

### gimp_module_new ()

    GimpModule* gimp_module_new                 (const gchar *filename,
                                                 gboolean load_inhibit,
                                                 gboolean verbose);

Creates a new GimpModule instance.

filename :

  The filename of a loadable module.

load_inhibit :

  Pass `TRUE` to exclude this module from auto-loading.

verbose :

  Pass `TRUE` to enable debugging output.

Returns :

  The new GimpModule object.

gimp_module_new

### gimp_module_modified ()

    void        gimp_module_modified            (GimpModule *module);

Emits the "modified" signal. Call it whenever you have modified the module manually (which you shouldn't do).

module :

  A GimpModule.

gimp_module_modified

### gimp_module_query_module ()

    gboolean    gimp_module_query_module        (GimpModule *module);

Queries the module without actually registering any of the types it may implement. After successful query, the info field of the GimpModule struct will be available for further inspection.

module :

  A GimpModule.

Returns :

  `TRUE` on success.

gimp_module_query_module

### gimp_module_set_load_inhibit ()

    void        gimp_module_set_load_inhibit    (GimpModule *module,
                                                 gboolean load_inhibit);

Sets the load_inhibit property if the module. Emits "modified".

module :

  A GimpModule.

load_inhibit :

  Pass `TRUE` to exclude this module from auto-loading.

gimp_module_set_load_inhibit

### gimp_module_state_name ()

    const gchar* gimp_module_state_name         (GimpModuleState state);

Returns the translated textual representation of a GimpModuleState. The returned string must not be freed.

state :

  A GimpModuleState.

Returns :

  The state's name.

gimp_module_state_name

### gimp_module_register_enum ()

    GType       gimp_module_register_enum       (GTypeModule *module,
                                                 const gchar *name,
                                                 const GEnumValue *const_static_values);

Registers an enum similar to `g_enum_register_static()` but for modules. This function should actually live in GLib but since there's no such API, it is provided here.

module :

name :

const_static_values :

Returns :

  a new enum GType

gimp_module_register_enum

### gimp_module_info_new ()

    GimpModuleInfo* gimp_module_info_new        (guint32 abi_version,
                                                 const gchar *purpose,
                                                 const gchar *author,
                                                 const gchar *version,
                                                 const gchar *copyright,
                                                 const gchar *date);

Creates a newly allocated GimpModuleInfo struct.

abi_version :

  The GIMP_MODULE_ABI_VERSION the module was compiled against.

purpose :

  The module's general purpose.

author :

  The module's author.

version :

  The module's version.

copyright :

  The module's copyright.

date :

  The module's release date.

Returns :

  The new GimpModuleInfo struct.

gimp_module_info_new

### gimp_module_info_copy ()

    GimpModuleInfo* gimp_module_info_copy       (const GimpModuleInfo *info);

Copies a GimpModuleInfo struct.

info :

  The GimpModuleInfo struct to copy.

Returns :

  The new copy.

gimp_module_info_copy

### gimp_module_info_free ()

    void        gimp_module_info_free           (GimpModuleInfo *info);

Frees the passed GimpModuleInfo.

info :

  The GimpModuleInfo struct to free

gimp_module_info_free

## Signals

### The "modified" signal

    void        user_function                  (GimpModule *gimpmodule,
                                                gpointer user_data);

gimpmodule :

  the object which received the signal.

user_data :

  user data set when the signal handler was connected.

## See Also

GModule

GTypeModule