GimpPlugIn

GimpPlugIn — The base class for plug-ins to derive from

Functions

Properties

GIOChannel * read-channel Read / Write / Construct Only
GIOChannel * write-channel Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── GimpPlugIn

Description

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 GList of their names from either GimpPlugInClass.query_procedures() or GimpPlugInClass.init_procedures().

Every GIMP plug-in has to implement a GimpPlugIn 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 three 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, GimpPlugInClass.query_procedures() is called and returns a GList 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 GimpPlugInClass.init_procedures() is called and returns a GList of procedure names this plug-in implements. This only happens if the plug-in actually implements GimpPlugInClass.init_procedures(). A plug-in only needs to implement GimpPlugInClass.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 GimpPlugInClass.create_procedure() on all procedure names in the exact order of the GList returned by GimpPlugInClass.query_procedures() or GimpPlugInClass.init_procedures() and then registers the returned GimpProcedure using GimpProcedureClass.register().

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 GimpPlugInClass.query_procedures() or GimpPlugInClass.init_procedures() is passed to GimpPlugInClass.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, GimpPlugInClass.quit() is called before the plug-in process exits, so the plug-in can perform whatever cleanup necessary.

Functions

gimp_plug_in_set_translation_domain ()

void
gimp_plug_in_set_translation_domain (GimpPlugIn *plug_in,
                                     const gchar *domain_name,
                                     GFile *domain_path);

Sets a textdomain for localisation for the plug_in .

This function adds a textdomain to the list of domains Gimp searches for strings when translating its menu entries. There is no need to call this function for plug-ins that have their strings included in the 'gimp-std-plugins' domain as that is used by default. If the compiled message catalog is not in the standard location, you may specify an absolute path to another location.

This function can only be called in the GimpPlugInClass.query_procedures() function of a plug-in.

Parameters

plug_in

A GimpPlugIn.

 

domain_name

The name of the textdomain (must be unique).

 

domain_path

A GFile pointing to the compiled message catalog (may be NULL).

[nullable]

Since: 3.0


gimp_plug_in_set_help_domain ()

void
gimp_plug_in_set_help_domain (GimpPlugIn *plug_in,
                              const gchar *domain_name,
                              GFile *domain_uri);

Set a help domain and path for the plug_in .

This function registers user documentation for the calling plug-in with the GIMP help system. The domain_uri parameter points to the root directory where the plug-in help is installed. For each supported language there should be a file called 'gimp-help.xml' that maps the help IDs to the actual help files.

This function can only be called in the GimpPlugInClass.query_procedures() function of a plug-in.

Parameters

plug_in

A GimpPlugIn.

 

domain_name

The XML namespace of the plug-in's help pages.

 

domain_uri

The root URI of the plug-in's help pages.

 

Since: 3.0


gimp_plug_in_add_menu_branch ()

void
gimp_plug_in_add_menu_branch (GimpPlugIn *plug_in,
                              const gchar *menu_path,
                              const gchar *menu_label);

Add a new sub-menu to the GIMP menus.

This function installs a sub-menu which does not belong to any procedure at the location menu_path .

For translations of menu_label to work properly, menu_label should only be marked for translation but passed to this function untranslated, for example using N_("Submenu"). GIMP will look up the translation in the textdomain registered for the plug-in.

See also: gimp_procedure_add_menu_path().

Parameters

plug_in

A GimpPlugIn

 

menu_path

The sub-menu's menu path.

 

menu_label

The menu label of the sub-menu.

 

Since: 3.0


gimp_plug_in_add_temp_procedure ()

void
gimp_plug_in_add_temp_procedure (GimpPlugIn *plug_in,
                                 GimpProcedure *procedure);

This function adds a temporary procedure to plug_in . It is usually called from a GIMP_PDB_PROC_TYPE_EXTENSION procedure's GimpProcedureClass.run().

A temporary procedure is a procedure which is only available while one of your plug-in's "real" procedures is running.

The procedure's type must be GIMP_PDB_PROC_TYPE_TEMPORARY or the function will fail.

NOTE: Normally, plug-in communication is triggered by the plug-in and the GIMP core only responds to the plug-in's requests. You must explicitly enable receiving of temporary procedure run requests using either gimp_plug_in_extension_enable() or gimp_plug_in_extension_process(). See this functions' documentation for details.

Parameters

plug_in

A GimpPlugIn

 

procedure

A GimpProcedure of type GIMP_PDB_PROC_TYPE_TEMPORARY.

 

Since: 3.0


gimp_plug_in_remove_temp_procedure ()

void
gimp_plug_in_remove_temp_procedure (GimpPlugIn *plug_in,
                                    const gchar *procedure_name);

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

Parameters

plug_in

A GimpPlugIn

 

procedure_name

The name of a GimpProcedure added to plug_in .

 

Since: 3.0


gimp_plug_in_get_temp_procedures ()

GList *
gimp_plug_in_get_temp_procedures (GimpPlugIn *plug_in);

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

Parameters

plug_in

A GimpPlugIn

 

Returns

The list of procedures.

[transfer none][element-type GimpProcedure]

Since: 3.0


gimp_plug_in_get_temp_procedure ()

GimpProcedure *
gimp_plug_in_get_temp_procedure (GimpPlugIn *plug_in,
                                 const gchar *procedure_name);

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

Parameters

plug_in

A GimpPlugIn

 

procedure_name

The name of a GimpProcedure added to plug_in .

 

Returns

The procedure if registered, or NULL.

[nullable][transfer none]

Since: 3.0


gimp_plug_in_extension_enable ()

void
gimp_plug_in_extension_enable (GimpPlugIn *plug_in);

Enables asynchronous processing of messages from the main GIMP application.

Normally, a plug-in is not called by GIMP except for the call to the procedure it implements. All subsequent communication is triggered by the plug-in and all messages sent from GIMP to the plug-in are just answers to requests the plug-in made.

If the plug-in however registered temporary procedures using gimp_plug_in_add_temp_procedure(), it needs to be able to receive requests to execute them. Usually this will be done by running gimp_plug_in_extension_process() in an endless loop.

If the plug-in cannot use gimp_plug_in_extension_process(), i.e. if it has a GUI and is hanging around in a GMainLoop, it must call gimp_plug_in_extension_enable().

Note that the plug-in does not need to be a GIMP_PDB_PROC_TYPE_EXTENSION to register temporary procedures.

See also: gimp_plug_in_add_temp_procedure().

Parameters

plug_in

A GimpPlugIn

 

Since: 3.0


gimp_plug_in_extension_process ()

void
gimp_plug_in_extension_process (GimpPlugIn *plug_in,
                                guint timeout);

Processes one message sent by GIMP and returns.

Call this function in an endless loop after calling gimp_procedure_extension_ready() to process requests for running temporary procedures.

See gimp_plug_in_extension_enable() for an asynchronous way of doing the same if running an endless loop is not an option.

See also: gimp_plug_in_add_temp_procedure().

Parameters

plug_in

A GimpPlugIn.

 

timeout

The timeout (in ms) to use for the select() call.

 

Since: 3.0


gimp_plug_in_set_pdb_error_handler ()

void
gimp_plug_in_set_pdb_error_handler (GimpPlugIn *plug_in,
                                    GimpPDBErrorHandler handler);

Sets an error handler for procedure calls.

This procedure changes the way that errors in procedure calls are handled. By default GIMP will raise an error dialog if a procedure call made by a plug-in fails. Using this procedure the plug-in can change this behavior. If the error handler is set to GIMP_PDB_ERROR_HANDLER_PLUGIN, then the plug-in is responsible for calling gimp_pdb_get_last_error() and handling the error whenever one if its procedure calls fails. It can do this by displaying the error message or by forwarding it in its own return values.

Parameters

plug_in

A GimpPlugIn

 

handler

Who is responsible for handling procedure call errors.

 

Since: 3.0


gimp_plug_in_get_pdb_error_handler ()

GimpPDBErrorHandler
gimp_plug_in_get_pdb_error_handler (GimpPlugIn *plug_in);

Retrieves the active error handler for procedure calls.

This procedure retrieves the currently active error handler for procedure calls made by the calling plug-in. See gimp_plugin_set_pdb_error_handler() for details.

Parameters

plug_in

A GimpPlugIn

 

Returns

Who is responsible for handling procedure call errors.

Since: 3.0

Types and Values

GimpPlugIn

typedef struct _GimpPlugIn GimpPlugIn;

struct GimpPlugInClass

struct GimpPlugInClass {
  GObjectClass  parent_class;

  /**
   * GimpPlugInClass::query_procedures:
   * @plug_in: a #GimpPlugIn.
   *
   * Returns: (element-type gchar*) (transfer full):
   *          the names of the procedures registered by @plug_in.
   **/
  GList          * (* query_procedures) (GimpPlugIn  *plug_in);

  /**
   * GimpPlugInClass::init_procedures:
   * @plug_in: a #GimpPlugIn.
   *
   * Returns: (element-type gchar*) (transfer full):
   *          the names of the procedures registered by @plug_in.
   **/
  GList          * (* init_procedures)  (GimpPlugIn  *plug_in);

  /**
   * GimpPlugInClass::create_procedure:
   * @plug_in:        a #GimpPlugIn.
   * @procedure_name: procedure name.
   *
   * Returns: (transfer full):
   *          the procedure to be registered or executed by @plug_in.
   **/
  GimpProcedure  * (* create_procedure) (GimpPlugIn  *plug_in,
                                         const gchar *procedure_name);

  /**
   * GimpPlugInClass::quit:
   * @plug_in: a #GimpPlugIn.
   **/
  void             (* quit)             (GimpPlugIn  *plug_in);

  /* Padding for future expansion */
};

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

Members

query_procedures ()

This method can be overridden by all plug-ins to return a newly allocated GList of allocated strings naming the procedures registered by this plug-in. See documentation of GimpPlugInClass.init_procedures() for differences.

 

init_procedures ()

This method can be overridden by all plug-ins to return a newly allocated GList of allocated strings naming procedures registered by this plug-in. It is different from GimpPlugInClass.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 GimpPlugInClass.init_procedures() typically returns procedures dependent to runtime conditions (such as the presence of a third-party tool), whereas GimpPlugInClass.query_procedures() would usually return procedures that are always available unconditionally. Most of the time, you only want to override GimpPlugInClass.query_procedures() and leave GimpPlugInClass.init_procedures() untouched.

 

create_procedure ()

This method must be overridden by all plug-ins and return a newly allocated GimpProcedure named name . It will be called for every name as returned by GimpPlugInClass.query_procedures() and GimpPlugInClass.init_procedures() so care must be taken to handle them all. Upon procedure registration, GimpPlugInClass.create_procedure() will be called in the order of the lists returned by GimpPlugInClass.query_procedures() and GimpPlugInClass.init_procedures()

 

quit ()

This method can be overridden by a plug-in which needs to perform some actions upon quitting.

 

Since: 3.0

Property Details

The “read-channel” property

  “read-channel”             GIOChannel *

The GIOChanel to read from GIMP.

Flags: Read / Write / Construct Only


The “write-channel” property

  “write-channel”            GIOChannel *

The GIOChanel to write to GIMP.

Flags: Read / Write / Construct Only