Gimp.PlugIn
Description: Reference for Gimp.PlugIn

### Class

# GimpPlugIn

since: 3.0

#### Description [src]

    class Gimp.PlugIn : GObject.Object
    {
      /* No available fields */
    }

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.

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_PERSISTENT` procedure’s `Gimp.ProcedureClass.run`.

since: 3.0

###### gimp_plug_in_get_pdb_error_handler

Retrieves the active error handler for procedure calls.

since: 3.0

###### gimp_plug_in_get_temp_procedure

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

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

since: 3.0

###### gimp_plug_in_persistent_enable

Enables asynchronous processing of messages from the main GIMP application.

since: 3.0

###### gimp_plug_in_persistent_process

Processes one message sent by GIMP and returns.

since: 3.0

###### gimp_plug_in_remove_temp_procedure

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

since: 3.0

###### gimp_plug_in_set_help_domain

Set a help domain and path for the `plug_in`.

since: 3.0

###### gimp_plug_in_set_pdb_error_handler

Sets an error handler for procedure calls.

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_reserved0) (
    void
      );
      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
      );
      void (* _gimp_reserved9) (
    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_reserved0: void (* _gimp_reserved0) ( void )`

  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.

`_gimp_reserved9: void (* _gimp_reserved9) ( 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.

###### Gimp.PlugInClass.query_procedures

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 `Gimp.PlugInClass.init_procedures` for differences.

###### Gimp.PlugInClass.quit

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

###### Gimp.PlugInClass.set_i18n

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

since: 3.0