Callbacks

BatchFunc (procedure, run_mode, command, config, *run_data)

ExportGetCapabilitiesFunc (procedure, config, options, *get_capabilities_data)

ExtractVectorFunc (procedure, run_mode, file, metadata, config, *extract_data)

ModuleQueryFunc (module)

ModuleRegisterFunc (module)

ProgressFunc (min, max, current, *data)

ProgressVtableEndFunc (*user_data)

ProgressVtableGetWindowFunc (*user_data)

ProgressVtablePulseFunc (*user_data)

ProgressVtableSetTextFunc (message, *user_data)

ProgressVtableSetValueFunc (percentage, *user_data)

ProgressVtableStartFunc (message, cancelable, *user_data)

PutPixelFunc (x, y, color, *data)

RenderFunc (x, y, *data)

RunExportFunc (procedure, run_mode, image, file, options, metadata, config, *run_data)

RunFunc (procedure, config, *run_data)

RunImageFunc (procedure, run_mode, image, drawables, config, *run_data)

RunLoadFunc (procedure, run_mode, file, metadata, flags, config, *run_data)

RunThumbnailFunc (procedure, file, size, config, *run_data)

RunVectorLoadFunc (procedure, run_mode, file, width, height, extracted_data, metadata, flags, config, data_from_extract, *run_data)

Details

Gimp.BatchFunc(procedure, run_mode, command, config, *run_data)
Parameters:
Returns:

the procedure's return values.

Return type:

Gimp.ValueArray

The batch function is run during the lifetime of the GIMP session, each time a plug-in batch procedure is called.

New in version 3.0.

Gimp.ExportGetCapabilitiesFunc(procedure, config, options, *get_capabilities_data)
Parameters:
Returns:

a bitfield of the capabilities you want when preparing the image for exporting.

Return type:

Gimp.ExportCapabilities

This function returns the capabilities requested by your export procedure, depending on config or options.

New in version 3.0.

Gimp.ExtractVectorFunc(procedure, run_mode, file, metadata, config, *extract_data)
Parameters:

  • procedure (Gimp.Procedure) – the [class`Gimp`.Procedure].

  • run_mode (Gimp.RunMode) – the [enum`RunMode`].

  • file (Gio.File) – the [iface`Gio`.File] to load from.

  • metadata (Gimp.Metadata) – the [class`Gimp`.Metadata] which will be added to the new image.

  • config (Gimp.ProcedureConfig or None) – the procedure's remaining arguments.

  • extract_data (object or None) – the extract_data given in [ctor`VectorLoadProcedure`.new].

Returns:

True if any information could be extracted from file.

extracted_data:

dimensions and pixel density extracted from file.

data_for_run:

will be passed as data_from_extract in [callback`RunVectorLoadFunc`].

data_for_run_destroy:

the free function for data_for_run.

Return type:

(bool, extracted_data: Gimp.VectorLoadData, data_for_run: object, data_for_run_destroy: GLib.DestroyNotify)

Loading a vector image happens in 2 steps:

this function is first run to determine which size should be actually requested.

[callback`RunVectorLoadFunc`] is called with the suggested width and height.

This function is run during the lifetime of the GIMP session, as the first step above. It should extract the maximum of information from the source document to help GIMP take appropriate decisions for default values and also for displaying relevant information in the load dialog (if necessary).

The best case scenario is to be able to extract proper dimensions (width and height) with valid units supported by GIMP. If not possible, returning already processed dimensions then setting exact_width and exact_height to False in extracted_data is also an option. If all you can get are no-unit dimensions, set them with Gimp.UnitID.PIXEL and %correct_ratio to True to at least give a valid ratio as a default.

If there is no way to extract any valid default dimensions, not even a ratio, then return False but leave %error as None. [callback`RunVectorLoadFunc`] will still be called but default values might be bogus. If the return value is False and %error is set, it means that the file is invalid and cannot even be loaded. Thus [callback`RunVectorLoadFunc`] won’t be run and %error is passed as the main run error.

Note: when procedure is run, the original arguments will be passed as config. Nevertheless it may happen that this function is called with a None config, in particular when [method`VectorLoadProcedure`.extract_dimensions] is called. In such a case, the callback is expected to return whatever can be considered “best judgement” defaults.

New in version 3.0.

Gimp.ModuleQueryFunc(module)
Parameters:

module (GObject.TypeModule) – The module responsible for this loadable module.

Returns:

The info struct describing the module.

Return type:

Gimp.ModuleInfo

The signature of the query function a loadable GIMP module must implement. In the module, the function must be called [func`Module`.query].

[class`Module`] will copy the returned [struct`ModuleInfo`], 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).

Gimp.ModuleRegisterFunc(module)
Parameters:

module (GObject.TypeModule) – The module responsible for this loadable module.

Returns:

Whether the registration was succesfull

Return type:

bool

The signature of the register function a loadable GIMP module must implement. In the module, the function must be called [func`Module`.register].

When this function is called, the module should register all the types it implements with the passed module.

Gimp.ProgressFunc(min, max, current, *data)
Parameters:
Gimp.ProgressVtableEndFunc(*user_data)
Parameters:

user_data (object or None) – User data

Ends the progress

Gimp.ProgressVtableGetWindowFunc(*user_data)
Parameters:

user_data (object or None) – User data

Returns:

the handle of the window where the progress is displayed.

Return type:

GLib.Bytes

Gimp.ProgressVtablePulseFunc(*user_data)
Parameters:

user_data (object or None) – User data

Makes the progress pulse

Gimp.ProgressVtableSetTextFunc(message, *user_data)
Parameters:

  • message (str) – The new text

  • user_data (object or None) – User data

Sets a new text on the progress.

Gimp.ProgressVtableSetValueFunc(percentage, *user_data)
Parameters:

  • percentage (float) – The progress in percent

  • user_data (object or None) – User data

Sets a new percentage on the progress.

Gimp.ProgressVtableStartFunc(message, cancelable, *user_data)
Parameters:

  • message (str) – The message to show

  • cancelable (bool) – Whether the procedure is cancelable

  • user_data (object or None) – User data

Starts the progress

Gimp.PutPixelFunc(x, y, color, *data)
Parameters:
Gimp.RenderFunc(x, y, *data)
Parameters:
Returns:

The rendered pixel as RGB

Return type:

color: float

Gimp.RunExportFunc(procedure, run_mode, image, file, options, metadata, config, *run_data)
Parameters:
Returns:

the procedure's return values.

Return type:

Gimp.ValueArray

The export function is run during the lifetime of the GIMP session, each time a plug-in export procedure is called.

If a MimeType was passed in Gimp.ExportProcedure.new(), then metadata will be non-None and can be tweaked by the run() function if needed. Otherwise you can let it as-is and it will be stored back into the exported file according to rules on metadata export shared across formats.

New in version 3.0.

Gimp.RunFunc(procedure, config, *run_data)
Parameters:
Returns:

the procedure's return values.

Return type:

Gimp.ValueArray

The run function is run during the lifetime of the GIMP session, each time a plug-in procedure is called.

New in version 3.0.

Gimp.RunImageFunc(procedure, run_mode, image, drawables, config, *run_data)
Parameters:
Returns:

the procedure's return values.

Return type:

Gimp.ValueArray

The image function is run during the lifetime of the GIMP session, each time a plug-in image procedure is called.

New in version 3.0.

Gimp.RunLoadFunc(procedure, run_mode, file, metadata, flags, config, *run_data)
Parameters:
Returns:

the procedure's return values.

flags:

flags to filter which metadata will be added..

Return type:

(Gimp.ValueArray, flags: Gimp.MetadataLoadFlags)

The load function is run during the lifetime of the GIMP session, each time a plug-in load procedure is called.

You are expected to read file and create a [class`Gimp`.Image] out of its data. This image will be the first return value. metadata will be filled from metadata from file if our infrastructure supports this format. You may tweak this object, for instance adding metadata specific to the format. You can also edit flags if you need to filter out some specific common fields. For instance, it is customary to remove a colorspace field with [flags`MetadataLoadFlags`] when a profile was added.

New in version 3.0.

Gimp.RunThumbnailFunc(procedure, file, size, config, *run_data)
Parameters:
Returns:

the procedure's return values.

Return type:

Gimp.ValueArray

The thumbnail function is run during the lifetime of the GIMP session, each time a plug-in thumbnail procedure is called.

[class`ThumbnailProcedure`] are always run non-interactively.

On success, the returned array must contain:

a [class`Image`]: this is the only mandatory return value. It should ideally be a simple image whose dimensions are closest to size and meant to be displayed as a small static image.

(optional) the full image’s width (not the thumbnail’s image’s), or 0 if unknown.

(optional) the full image’s height, or 0 if unknown.

(optional) the [enum`ImageType`] of the full image.

(optional) the number of layers in the full image.

New in version 3.0.

Gimp.RunVectorLoadFunc(procedure, run_mode, file, width, height, extracted_data, metadata, flags, config, data_from_extract, *run_data)
Parameters:

  • procedure (Gimp.Procedure) – the [class`Gimp`.Procedure] that runs.

  • run_mode (Gimp.RunMode) – the [enum`RunMode`].

  • file (Gio.File) – the [iface`Gio`.File] to load from.

  • width (int) – the desired width in pixel for the created image.

  • height (int) – the desired height in pixel for the created image.

  • extracted_data (Gimp.VectorLoadData) – dimensions returned by [callback`ExtractVectorFunc`].

  • metadata (Gimp.Metadata) – the [class`Gimp`.Metadata] which will be added to the new image.

  • flags (Gimp.MetadataLoadFlags) – flags to filter which metadata will be added..

  • config (Gimp.ProcedureConfig) – the procedure's remaining arguments.

  • data_from_extract (object or None) – data_for_run returned by [callback`ExtractVectorFunc`].

  • run_data (object or None) – run_data given in Gimp.VectorLoadProcedure.new().

Returns:

the procedure's return values.

flags:

flags to filter which metadata will be added..

Return type:

(Gimp.ValueArray, flags: Gimp.MetadataLoadFlags)

The load function is run during the lifetime of the GIMP session, each time a plug-in load procedure is called.

You are expected to read file and create a [class`Gimp`.Image] out of its data. This image will be the first return value. metadata will be filled from metadata from file if our infrastructure supports this format. You may tweak this object, for instance adding metadata specific to the format. You can also edit flags if you need to filter out some specific common fields. For instance, it is customary to remove a colorspace field with [flags`MetadataLoadFlags`] when a profile was added.

Regarding returned image dimensions:

If width or height is 0 or negative, the actual value will be computed so that ratio is preserved. If prefer_native_dimension is False, at least one of the 2 dimensions should be strictly positive.

If preserve_ratio is True, then width and height are considered as a max size in their respective dimension. I.e. that the resulting image will be at most widthx height while preserving original ratio. preserve_ratio is implied when any of the dimension is 0 or negative.

If prefer_native_dimension is True, and if the image has some kind of native size (if the format has such metadata or it can be computed), it will be used rather than widthx height. Note that if both dimensions are 0 or negative, even if prefer_native_dimension is True yet the procedure cannot determine native dimensions, then maybe a dialog could be popped up (if implemented), unless the run_mode is [enum`Gimp`.RunMode.NONINTERACTIVE].

New in version 3.0.