Class

GimpPlugIn

unstable since: 3.0

Description [src]

class Gimp.PlugIn : GObject.Object {
  parent_instance: GObject,
  priv: GimpPlugInPrivate*
}

The base class for plug-ins to derive from.

GimpPlugIn manages the plug-in’s GimpProcedure objects. The procedures a plug-in implements are registered with GIMP by returning a list of their names from either Gimp.PlugInClass.query_procedures or Gimp.PlugInClass.init_procedures.

Every GIMP plug-in has to be implemented as a subclass and make it known to the libgimp infrastructure and the main GIMP application by passing its GType to GIMP_MAIN().

GIMP_MAIN() passes the ‘argc’ and ‘argv’ of the platform’s main() function, along with the GType, to gimp_main(), which creates an instance of the plug-in’s GimpPlugIn subclass and calls its virtual functions, depending on how the plug-in was called by GIMP.

There are 3 different ways GIMP calls a plug-in: “query”, “init” and “run”.

The plug-in is called in “query” mode once after it was installed, or when the cached plug-in information in the config file “pluginrc” needs to be recreated. In “query” mode, Gimp.PlugInClass.query_procedures is called and returns a list of procedure names the plug-in implements. This is the “normal” place to register procedures, because the existence of most procedures doesn’t depend on things that change between GIMP sessions.

The plug-in is called in “init” mode at each GIMP startup, and Gimp.PlugInClass.init_procedures is called and returns a list of procedure names this plug-in implements. This only happens if the plug-in actually implements Gimp.PlugInClass.init_procedures. A plug-in only needs to implement init_procedures if the existence of its procedures can change between GIMP sessions, for example if they depend on the presence of external tools, or hardware like scanners, or online services, or whatever variable circumstances.

In order to register the plug-in’s procedures with the main GIMP application in the plug-in’s “query” and “init” modes, GimpPlugIn calls Gimp.PlugInClass.create_procedure on all procedure names in the exact order of the list returned by Gimp.PlugInClass.query_procedures or Gimp.PlugInClass.init_procedures and then registers the returned GimpProcedure.

The plug-in is called in “run” mode whenever one of the procedures it implements is called by either the main GIMP application or any other plug-in. In “run” mode, one of the procedure names returned by Gimp.PlugInClass.query_procedures or Gimp.PlugInClass.init_procedures is passed to Gimp.PlugInClass.create_procedure which must return a GimpProcedure for the passed name. The procedure is then executed by calling gimp_procedure_run().

In any of the three modes, Gimp.PlugInClass.quit is called before the plug-in process exits, so the plug-in can perform whatever cleanup necessary.

Available since: 3.0

Hierarchy

Ancestors

GObject

Functions

gimp_plug_in_directory

Returns the default top directory for GIMP plug-ins and modules. If the environment variable GIMP3_PLUGINDIR exists, that is used. It should be an absolute pathname. Otherwise, on Unix the compile-time defined directory is used. On Windows, the installation directory as deduced from the executable’s full filename is used.

gimp_plug_in_directory_file

Returns a GFile in the plug-in directory, or the plug-in directory itself if first_element is NULL.

since: 2.10

gimp_plug_in_error_quark

Generic GQuark error domain for plug-ins. Plug-ins are welcome to create their own domain when they want to handle advanced error handling. Often, you just want to pass an error message to the core. This domain can be used for such simple usage.

Instance methods

gimp_plug_in_add_menu_branch

Add a new sub-menu to the GIMP menus.

unstable since: 3.0

gimp_plug_in_add_temp_procedure

This function adds a temporary procedure to plug_in. It is usually called from a GIMP_PDB_PROC_TYPE_EXTENSION procedure’s Gimp.ProcedureClass.run.

unstable since: 3.0

gimp_plug_in_extension_enable

Enables asynchronous processing of messages from the main GIMP application.

unstable since: 3.0

gimp_plug_in_extension_process

Processes one message sent by GIMP and returns.

unstable since: 3.0

gimp_plug_in_get_pdb_error_handler

Retrieves the active error handler for procedure calls.

unstable since: 3.0

gimp_plug_in_get_temp_procedure

This function retrieves a temporary procedure from plug_in by the procedure’s procedure_name.

unstable since: 3.0

gimp_plug_in_get_temp_procedures

This function retrieves the list of temporary procedure of plug_in as added with gimp_plug_in_add_temp_procedure().

unstable since: 3.0

gimp_plug_in_remove_temp_procedure

This function removes a temporary procedure from plug_in by the procedure’s procedure_name.

unstable since: 3.0

gimp_plug_in_set_help_domain

Set a help domain and path for the plug_in.

unstable since: 3.0

gimp_plug_in_set_pdb_error_handler

Sets an error handler for procedure calls.

unstable since: 3.0

Methods inherited from GObject (43)

Please see GObject for a full list of methods.

Properties

Gimp.PlugIn:program-name

The program name as usually found on argv[0]

Gimp.PlugIn:read-channel

The GIOChannel to read from GIMP.

Gimp.PlugIn:write-channel

The GIOChannel to write to GIMP.

Signals

Signals inherited from GObject (1)

GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Class structure

struct GimpPlugInClass {
  GObjectClass parent_class;
  GList* (* query_procedures) (
    GimpPlugIn* plug_in
  );
  GList* (* init_procedures) (
    GimpPlugIn* plug_in
  );
  GimpProcedure* (* create_procedure) (
    GimpPlugIn* plug_in,
    const gchar* procedure_name
  );
  void (* quit) (
    GimpPlugIn* plug_in
  );
  gboolean (* set_i18n) (
    GimpPlugIn* plug_in,
    const gchar* procedure_name,
    gchar** gettext_domain,
    gchar** catalog_dir
  );
  void (* _gimp_reserved1) (
void
  );
  void (* _gimp_reserved2) (
void
  );
  void (* _gimp_reserved3) (
void
  );
  void (* _gimp_reserved4) (
void
  );
  void (* _gimp_reserved5) (
void
  );
  void (* _gimp_reserved6) (
void
  );
  void (* _gimp_reserved7) (
void
  );
  void (* _gimp_reserved8) (
void
  );
  
}

A class which every plug-in should subclass, while overriding Gimp.PlugInClass.query_procedures and/or Gimp.PlugInClass.init_procedures, as well as Gimp.PlugInClass.create_procedure.

Class members

parent_class: GObjectClass: No description available.
query_procedures: GList* (* query_procedures) ( GimpPlugIn* plug_in ): No description available.
init_procedures: GList* (* init_procedures) ( GimpPlugIn* plug_in ): No description available.
create_procedure: GimpProcedure* (* create_procedure) ( GimpPlugIn* plug_in, const gchar* procedure_name ): No description available.
quit: void (* quit) ( GimpPlugIn* plug_in ): No description available.
set_i18n: gboolean (* set_i18n) ( GimpPlugIn* plug_in, const gchar* procedure_name, gchar** gettext_domain, gchar** catalog_dir ): No description available.
_gimp_reserved1: void (* _gimp_reserved1) ( void ): No description available.
_gimp_reserved2: void (* _gimp_reserved2) ( void ): No description available.
_gimp_reserved3: void (* _gimp_reserved3) ( void ): No description available.
_gimp_reserved4: void (* _gimp_reserved4) ( void ): No description available.
_gimp_reserved5: void (* _gimp_reserved5) ( void ): No description available.
_gimp_reserved6: void (* _gimp_reserved6) ( void ): No description available.
_gimp_reserved7: void (* _gimp_reserved7) ( void ): No description available.
_gimp_reserved8: void (* _gimp_reserved8) ( void ): No description available.

Virtual methods

Gimp.PlugInClass.create_procedure

This method must be overridden by all plug-ins and return a newly allocated GimpProcedure named name.

Gimp.PlugInClass.init_procedures

This method can be overridden by all plug-ins to return a newly allocated list of allocated strings naming procedures registered by this plug-in. It is different from Gimp.PlugInClass.query_procedures in that init happens at every startup, whereas query happens only once in the life of a plug-in (right after installation or update). Hence Gimp.PlugInClass.init_procedures typically returns procedures dependent to runtime conditions (such as the presence of a third-party tool), whereas Gimp.PlugInClass.query_procedures would usually return procedures that are always available unconditionally.