GimpProcedureConfig

GimpProcedureConfig — Config object for procedure arguments

Functions

Properties

GimpProcedure * procedure Read / Write / Construct Only

Object Hierarchy

    GObject
    ╰── GimpProcedureConfig

Description

GimpProcedureConfig is the base class for GimpProcedure specific config objects and the main interface to manage aspects of GimpProcedure's arguments such as persistency of the last used arguments across GIMP sessions.

A GimpProcedureConfig is created by a GimpProcedure using gimp_procedure_create_config() and its properties match the procedure's arguments and auxiliary arguments in number, order and type.

It implements the GimpConfig interface and therefore has all its serialization and deserialization features.

Functions

gimp_procedure_config_get_procedure ()

GimpProcedure *
gimp_procedure_config_get_procedure (GimpProcedureConfig *config);

This function returns the GimpProcedure which created config , see gimp_procedure_create_config().

Parameters

config

a GimpProcedureConfig

 

Returns

The GimpProcedure which created config .

[transfer none]

Since: 3.0


gimp_procedure_config_set_values ()

void
gimp_procedure_config_set_values (GimpProcedureConfig *config,
                                  const GimpValueArray *values);

Sets the values from values on config 's properties.

The number, order and types of values in values must match the number, order and types of config 's properties.

This function is meant to be used on values which are passed as arguments to the run() function of the GimpProcedure which created this config . See gimp_procedure_create_config().

Parameters

config

a GimpProcedureConfig

 

values

a GimpValueArray

 

Since: 3.0


gimp_procedure_config_get_values ()

void
gimp_procedure_config_get_values (GimpProcedureConfig *config,
                                  GimpValueArray *values);

Gets the values from config 's properties and stores them in values .

See gimp_procedure_config_set_values().

Parameters

config

a GimpProcedureConfig

 

values

a GimpValueArray

 

Since: 3.0


gimp_procedure_config_begin_run ()

void
gimp_procedure_config_begin_run (GimpProcedureConfig *config,
                                 GimpImage *image,
                                 GimpRunMode run_mode,
                                 const GimpValueArray *args);

Populates config with values for a GimpProcedure's run(), depending on run_mode .

If run_mode is GIMP_RUN_INTERACTIVE or GIMP_RUN_WITH_LAST_VALS, the saved values from the procedure's last run() are loaded and set on config . If image is not NULL, the last used values for this image are tried first, and if no image-specific values are found the globally saved last used values are used. If no saved last used values are found, the procedure's default argument values are used.

If run_mode is GIMP_RUN_NONINTERACTIVE, the contents of args are set on config using gimp_procedure_config_set_values().

After setting config 's properties like described above, arguments and auxiliary arguments are automatically synced from image parasites of the same name if they were set to GIMP_ARGUMENT_SYNC_PARASITE with gimp_procedure_set_argument_sync():

String properties are set to the value of the image parasite if run_mode is GIMP_RUN_INTERACTIVE or GIMP_RUN_WITH_LAST_VALS, or if the corresponding argument is an auxiliary argument. As a special case, a property named "gimp-comment" will default to gimp_get_default_comment() if there is no "gimp-comment" parasite.

After calling this function, the args passed to run() should be left alone and config be treated as the procedure's arguments.

It is possible to get config 's resulting values back into args by calling gimp_procedure_config_get_values(), as long as modified args are written back to config using gimp_procedure_config_set_values() before the call to gimp_procedure_config_end_run().

This function should be used at the beginning of a procedure's run() and be paired with a call to gimp_procedure_config_end_run() at the end of run().

Parameters

config

a GimpProcedureConfig

 

image

a GimpImage or NULL.

[nullable]

run_mode

the GimpRunMode passed to a GimpProcedure's run()

 

args

the GimpValueArray passed to a GimpProcedure's run()

 

Since: 3.0


gimp_procedure_config_end_run ()

void
gimp_procedure_config_end_run (GimpProcedureConfig *config,
                               GimpPDBStatusType status);

This function is the counterpart of gimp_procedure_config_begin_run() and must always be called in pairs in a procedure's run(), before returning return values.

If the run_mode passed to gimp_procedure_config_end_run() was GIMP_RUN_INTERACTIVE, config is saved as last used values to be used when the procedure runs again. Additionally, if the GimpImage passed to gimp_procedure_config_begin_run() was not NULL, config is attached to image as last used values for this image using a GimpParasite and gimp_image_attach_parasite().

If run_mode was not GIMP_RUN_NONINTERACTIVE, this function also conveniently calls gimp_displays_flush(), which is what most procedures want and doesn't do any harm if called redundantly.

After a GIMP_RUN_INTERACTIVE run, GIMP_ARGUMENT_SYNC_PARASITE values that have been changed are written back to their corresponding image parasite.

See gimp_procedure_config_begin_run().

Parameters

config

a GimpProcedureConfig

 

status

the return status of the GimpProcedure's run()

 

Since: 3.0


gimp_procedure_config_begin_export ()

GimpMetadata *
gimp_procedure_config_begin_export (GimpProcedureConfig *config,
                                    GimpImage *original_image,
                                    GimpRunMode run_mode,
                                    const GimpValueArray *args,
                                    const gchar *mime_type);

This is a variant of gimp_procedure_config_begin_run() to be used by file export procedures using GimpSaveProcedure. It must be paired with a call to gimp_procedure_config_end_export() at the end of run().

It does everything gimp_procedure_config_begin_run() does but provides additional features to automate file export:

If mime_type is non-NULL, exporting metadata is handled automatically, by calling gimp_image_metadata_save_prepare() and syncing its returned GimpMetadataSaveFlags with config 's properties. (The corresponding gimp_image_metadata_save_finish() will be called by gimp_procedure_config_end_export()).

The following boolean arguments of the used GimpSaveProcedure are synced. The procedure can but must not provide these arguments.

"save-exif" for GIMP_METADATA_SAVE_EXIF.

"save-xmp" for GIMP_METADATA_SAVE_XMP.

"save-iptc" for GIMP_METADATA_SAVE_IPTC.

"save-thumbnail" for GIMP_METADATA_SAVE_THUMBNAIL.

"save-color-profile" for GIMP_METADATA_SAVE_COLOR_PROFILE.

"save-comment" for GIMP_METADATA_SAVE_COMMENT.

The values from the GimpMetadataSaveFlags will only ever be used to set these properties to FALSE, overriding the user's saved default values for the procedure, but NOT overriding the last used values from exporting original_image or the last used values from exporting any other image using this procedure.

If mime_type is NULL, GimpMetadata handling is skipped. The procedure can still have all of the above listed boolean arguments, but must take care of their default values itself. The easiest way to do this is by simply using gimp_export_comment(), gimp_export_exif() etc. as default values for these arguments when adding them using GIMP_PROC_ARG_BOOLEAN() or GIMP_PROC_AUX_ARG_BOOLEAN().

Parameters

config

a GimpProcedureConfig

 

original_image

the GimpImage passed to run()

 

run_mode

the GimpRunMode passed to a GimpProcedure's run()

 

args

the GimpValueArray passed to a GimpProcedure's run()

 

mime_type

exported file format's mime type, or NULL.

[nullable]

Returns

The GimpMetadata to be used for this export, or NULL if original_image doesn't have metadata.

[transfer none][nullable]

Since: 3.0


gimp_procedure_config_end_export ()

void
gimp_procedure_config_end_export (GimpProcedureConfig *config,
                                  GimpImage *exported_image,
                                  GFile *file,
                                  GimpPDBStatusType status);

This is a variant of gimp_procedure_config_end_run() to be used by file export procedures using GimpSaveProcedure. It must be paired with a call to gimp_procedure_config_begin_export() at the beginning of run().

It does everything gimp_procedure_config_begin_run() does but provides additional features to automate file export:

If status is GIMP_PDB_SUCCESS, and gimp_procedure_config_begin_export() returned a GimpMetadata, this function calls gimp_procedure_config_save_metadata(), which syncs back config 's export properties to the metadata's GimpMetadataSaveFlags and writes metadata to file using gimp_image_metadata_save_finish().

Parameters

config

a GimpProcedureConfig

 

exported_image

the GimpImage that was actually exported

 

file

the GFile exported_image was written to

 

status

the return status of the GimpProcedure's run()

 

Since: 3.0

Property Details

The “procedure” property

  “procedure”                GimpProcedure *

The procedure this config object is used for.

Owner: GimpProcedureConfig

Flags: Read / Write / Construct Only