GimpModule

GimpModule — A GTypeModule subclass which implements module loading using GModule.

Synopsis

                    GimpModule;
                    GimpModuleInfo;
enum                GimpModuleState;
const GimpModuleInfo * (*GimpModuleQueryFunc)           (GTypeModule *module);
gboolean            (*GimpModuleRegisterFunc)           (GTypeModule *module);
#define             GIMP_MODULE_ERROR
enum                GimpModuleError;
#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);
GQuark              gimp_module_error_quark             (void);

Object Hierarchy

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

Implemented Interfaces

GimpModule implements GTypePlugin.

Signals

  "modified"                                       : Run First

Description

A GTypeModule subclass which implements module loading using GModule.

Details

GimpModule

typedef struct {
  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;

GimpModule is a generic mechanism to dynamically load modules into 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.


GimpModuleInfo

typedef struct {
  guint32  abi_version;
  gchar   *purpose;
  gchar   *author;
  gchar   *version;
  gchar   *copyright;
  gchar   *date;
} GimpModuleInfo;

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.

enum GimpModuleState

typedef enum {
  GIMP_MODULE_STATE_ERROR,
  GIMP_MODULE_STATE_LOADED,
  GIMP_MODULE_STATE_LOAD_FAILED,
  GIMP_MODULE_STATE_NOT_LOADED
} 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.

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.

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.

GIMP_MODULE_ERROR

#define GIMP_MODULE_ERROR (gimp_module_error_quark ())


enum GimpModuleError

typedef enum {
  GIMP_MODULE_FAILED             /* generic error condition */
} GimpModuleError;

GIMP_MODULE_FAILED


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 is incremented each time one of the following changes:

- the libgimpmodule implementation (if the change affects modules).

- one of the classes implemented by modules (currently GimpColorDisplay, GimpColorSelector and GimpController).


GIMP_MODULE_PARAM_SERIALIZE

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

Warning

GIMP_MODULE_PARAM_SERIALIZE is deprecated and should not be used in newly-written code.


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_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_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_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_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_register_enum ()

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

Warning

gimp_module_register_enum is deprecated and should not be used in newly-written code.

This function is deprecated! Use g_type_module_register_enum() instead.

module :

a module

name :

the name of the new enum type

const_static_values :

the enum values

Returns :

a new enum GType

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_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_free ()

void                gimp_module_info_free               (GimpModuleInfo *info);

Frees the passed GimpModuleInfo.

info :

The GimpModuleInfo struct to free

gimp_module_error_quark ()

GQuark              gimp_module_error_quark             (void);

This function is never called directly. Use GIMP_MODULE_ERROR() instead.

Returns :

the GQuark that defines the GIMP module error domain.

Since GIMP 2.8

Signal Details

The "modified" signal

void                user_function                      (GimpModule *gimpmodule,
                                                        gpointer    user_data)       : Run First

gimpmodule :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

See Also

GModule, GTypeModule