Gimp.PlugIn¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`directory` ()
class	`error_quark` ()
	`add_menu_branch` (menu_path, menu_label)
	`add_temp_procedure` (procedure)
	`get_pdb_error_handler` ()
	`get_temp_procedure` (procedure_name)
	`get_temp_procedures` ()
	`persistent_enable` ()
	`persistent_process` (timeout)
	`remove_temp_procedure` (procedure_name)
	`set_help_domain` (domain_name, domain_uri)
	`set_pdb_error_handler` (handler)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_create_procedure` (procedure_name)
	`do_init_procedures` ()
	`do_query_procedures` ()
	`do_quit` ()
	`do_set_i18n` (procedure_name)

Properties¶

Name	Type	Flags	Short Description
`program-name`	`str`	w/co	The executable name as usually found on argv[0]
`read-channel`	`GLib.IOChannel`	r/w/co	The GIOChanel to read from GIMP
`write-channel`	`GLib.IOChannel`	r/w/co	The GIOChanel to write to GIMP

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Gimp.PlugIn(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gimp.PlugInClass

The base class for plug-ins to derive from.

Gimp.PlugIn manages the plug-in’s [class`Procedure`] objects. The procedures a plug-in implements are registered with GIMP by returning a list of their names from either [vfunc`GimpPlugIn`.query_procedures] or [vfunc`GimpPlugIn`.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 [funcMAIN].

[funcMAIN] passes the ‘argc’ and ‘argv’ of the platform’s main() function, along with the GType, to [func`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, [vfunc`GimpPlugIn`.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 [vfunc`PlugIn`.init_procedures] is called and returns a list of procedure names this plug-in implements. This only happens if the plug-in actually implements [vfunc`GimpPlugIn`.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, [class`PlugIn`] calls [vfunc`PlugIn`.create_procedure] on all procedure names in the exact order of the list returned by [vfunc`PlugIn`.query_procedures] or [vfunc`PlugIn`.init_procedures] and then registers the returned [class`Procedure`].

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 [vfunc`PlugIn`.query_procedures] or [vfunc`PlugIn`.init_procedures] is passed to [vfunc`PlugIn`.create_procedure] which must return a [class`Procedure`] for the passed name. The procedure is then executed by calling [method`Procedure`.run].

In any of the three modes, [vfunc`PlugIn`.quit] is called before the plug-in process exits, so the plug-in can perform whatever cleanup necessary.

New in version 3.0.

classmethod directory()¶

Returns:: The top directory for GIMP plug_ins and modules.
Return type:: str

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.

Note that the actual directories used for GIMP plug-ins and modules can be overridden by the user in the preferences dialog.

In config files such as gimprc, the string ${gimp_plug_in_dir} expands to this directory.

The returned string is owned by GIMP and must not be modified or freed. The returned string is in the encoding used for filenames by GLib, which isn’t necessarily UTF-8. (On Windows it always is UTF-8.)

classmethod error_quark()¶

Return type:: int

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.

See GLib.Error for information on error domains.

add_menu_branch(menu_path, menu_label)¶

Parameters:

menu_path (str) – The sub-menu’s menu path.
menu_label (str) – The menu label of the sub-menu.

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().

New in version 3.0.

add_temp_procedure(procedure)¶

Parameters:: procedure (Gimp.Procedure) – A Gimp.Procedure of type Gimp.PDBProcType.TEMPORARY.

This function adds a temporary procedure to self. It is usually called from a Gimp.PDBProcType.PERSISTENT procedure’s [vfunc`Procedure`.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.PDBProcType.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 [method`PlugIn`.persistent_enable] or [method`PlugIn`.persistent_process]. See their respective documentation for details.

New in version 3.0.

get_pdb_error_handler()¶

Returns:: Who is responsible for handling procedure call errors.
Return type:: Gimp.PDBErrorHandler

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.

New in version 3.0.

get_temp_procedure(procedure_name)¶

Parameters:: procedure_name (str) – The name of a [class`Procedure`] added to self.
Returns:: The procedure if registered, or None.
Return type:: Gimp.Procedure or None

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

New in version 3.0.

get_temp_procedures()¶

Returns:: The list of procedures.
Return type:: [Gimp.Procedure]

This function retrieves the list of temporary procedure of self as added with [method`PlugIn`.add_temp_procedure].

New in version 3.0.

persistent_enable()¶

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 [method`PlugIn`.add_temp_procedure], it needs to be able to receive requests to execute them. Usually this will be done by running [method`PlugIn`.persistent_process] in an endless loop.

If the plug-in cannot use [method`PlugIn`.persistent_process], i.e. if it has a GUI and is hanging around in a [struct`GLib`.MainLoop], it must call [method`PlugIn`.persistent_enable].

Note that the plug-in does not need to be a [enum`Gimp`.PDBProcType.PERSISTENT] to register temporary procedures.

See also: [method`PlugIn`.add_temp_procedure].

New in version 3.0.

persistent_process(timeout)¶

Parameters:: timeout (int) – The timeout (in ms) to use for the select() call.

Processes one message sent by GIMP and returns.

Call this function in an endless loop after calling [method`Gimp`.Procedure.persistent_ready] to process requests for running temporary procedures.

See [method`PlugIn`.persistent_enable] for an asynchronous way of doing the same if running an endless loop is not an option.

See also: [method`PlugIn`.add_temp_procedure].

New in version 3.0.

remove_temp_procedure(procedure_name)¶

Parameters:: procedure_name (str) – The name of a [class`Procedure`] added to self.

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

New in version 3.0.

set_help_domain(domain_name, domain_uri)¶

Parameters:

domain_name (str) – The XML namespace of the plug-in’s help pages.
domain_uri (Gio.File) – The root URI of the plug-in’s help pages.

Set a help domain and path for the self.

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 [vfunc`PlugIn`.query_procedures] function of a plug-in.

New in version 3.0.

set_pdb_error_handler(handler)¶

Parameters:: handler (Gimp.PDBErrorHandler) – Who is responsible for handling procedure call errors.

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.PDBErrorHandler.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.

New in version 3.0.

do_create_procedure(procedure_name) virtual¶

Parameters:: procedure_name (str) – procedure name.
Returns:: the procedure to be registered or executed by plug_in.
Return type:: Gimp.Procedure

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

This method will be called for every name as returned by [vfunc`PlugIn`.query_procedures] and [vfunc`PlugIn`.init_procedures] so care must be taken to handle them all. Upon procedure registration, [vfunc`PlugIn`.create_procedure] will be called in the order of the lists returned by [vfunc`PlugIn`.query_procedures] and [vfunc`PlugIn`.init_procedures]

do_init_procedures() virtual¶

Returns:: the names of the procedures registered by plug_in.
Return type:: [str]

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 [vfunc`PlugIn`.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 [vfunc`PlugIn`.init_procedures] typically returns procedures dependent to runtime conditions (such as the presence of a third-party tool), whereas [vfunc`PlugIn`.query_procedures] would usually return procedures that are always available unconditionally.

Most of the time, you only want to override [vfunc`PlugIn`.query_procedures] and leave [vfunc`PlugIn`.init_procedures] untouched.

do_query_procedures() virtual¶

Returns:: the names of the procedures registered by plug_in.
Return type:: [str]

This method can be overridden by all plug-ins to return a newly allocated list of allocated strings naming the procedures registered by this plug-in. See documentation of [vfunc`PlugIn`.init_procedures] for differences.

do_quit() virtual¶: This method can be overridden by a plug-in which needs to perform some actions upon quitting.

do_set_i18n(procedure_name) virtual¶

Parameters:

procedure_name (str) – procedure name.

Returns:

True if this plug-in will use Gettext localization. You may return False if you wish to disable localization or set it up differently.

gettext_domain:: Gettext domain. If None, it defaults to the plug-in name as determined by the directory the binary is called from.
catalog_dir:: relative path to a subdirectory of the plug-in folder containing the compiled Gettext message catalogs. If None, it defaults to “locale/”.

Return type:

(bool, gettext_domain: str or None, catalog_dir: str or None)

This method can be overridden by all plug-ins to customize internationalization of the plug-in.

This method will be called before initializing, querying or running procedure_name (respectively with [vfunc`PlugIn`.init_procedures], [vfunc`PlugIn`.query_procedures] or with the run() function set in gimp_image_procedure_new()).

By default, GIMP plug-ins look up gettext compiled message catalogs in the subdirectory locale/ under the plug-in folder (same folder as gimp_get_progname()) with a text domain equal to the plug-in name (regardless procedure_name). It is unneeded to override this method if you follow this localization scheme.

If you wish to disable localization or localize with another system, simply set the method to None, or possibly implement this method to do something useful for your usage while returning False.

If you wish to tweak the gettext_domain or the catalog_dir, return True and allocate appropriate gettext_domain and/or catalog_dir (these use the default if set None).

Note that catalog_dir must be a relative path, encoded as UTF-8, subdirectory of the directory of gimp_get_progname(). The domain names “gimp30-std-plug-ins”, “gimp30-script-fu” and “gimp30-python” are reserved and can only be used with a None catalog_dir. These will use the translation catalogs installed for core plug-ins, so you are not expected to use these for your plug-ins, except if you are making a core plug-in. More domain names may become reserved so we discourage using a gettext domain starting with “gimp30-“.

When localizing your plug-in this way, GIMP also binds gettext_domain to the UTF-8 encoding.

New in version 3.0.

Property Details¶

Gimp.PlugIn.props.program_name¶

Name:: program-name
Type:: str
Default Value:: None
Flags:: WRITABLE, CONSTRUCT_ONLY

The program name as usually found on argv[0]

Gimp.PlugIn.props.read_channel¶

Name:: read-channel
Type:: GLib.IOChannel
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The [struct`GLib`.IOChannel] to read from GIMP

Gimp.PlugIn.props.write_channel¶

Name:: write-channel
Type:: GLib.IOChannel
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The [struct`GLib`.IOChannel] to write to GIMP