GimpProcedure

GimpProcedure

Functions

GimpValueArray * (*GimpRunFunc) ()
GimpProcedure * gimp_procedure_new ()
GimpPlugIn * gimp_procedure_get_plug_in ()
const gchar * gimp_procedure_get_name ()
GimpPDBProcType gimp_procedure_get_proc_type ()
void gimp_procedure_set_image_types ()
const gchar * gimp_procedure_get_image_types ()
void gimp_procedure_set_menu_label ()
const gchar * gimp_procedure_get_menu_label ()
void gimp_procedure_add_menu_path ()
GList * gimp_procedure_get_menu_paths ()
void gimp_procedure_set_icon_name ()
void gimp_procedure_set_icon_file ()
void gimp_procedure_set_icon_pixbuf ()
GimpIconType gimp_procedure_get_icon_type ()
const gchar * gimp_procedure_get_icon_name ()
GFile * gimp_procedure_get_icon_file ()
GdkPixbuf * gimp_procedure_get_icon_pixbuf ()
void gimp_procedure_set_documentation ()
const gchar * gimp_procedure_get_blurb ()
const gchar * gimp_procedure_get_help ()
const gchar * gimp_procedure_get_help_id ()
void gimp_procedure_set_attribution ()
const gchar * gimp_procedure_get_authors ()
const gchar * gimp_procedure_get_copyright ()
const gchar * gimp_procedure_get_date ()
GParamSpec * gimp_procedure_add_argument ()
GParamSpec * gimp_procedure_add_aux_argument ()
GParamSpec * gimp_procedure_add_return_value ()
GParamSpec * gimp_procedure_find_argument ()
GParamSpec * gimp_procedure_find_aux_argument ()
GParamSpec * gimp_procedure_find_return_value ()
GParamSpec ** gimp_procedure_get_arguments ()
GParamSpec ** gimp_procedure_get_aux_arguments ()
GParamSpec ** gimp_procedure_get_return_values ()
GimpValueArray * gimp_procedure_new_arguments ()
GimpValueArray * gimp_procedure_new_return_values ()
GimpValueArray * gimp_procedure_run ()
void gimp_procedure_extension_ready ()
GimpProcedureConfig * gimp_procedure_create_config ()

Properties

char * name Read / Write / Construct Only
GimpPlugIn * plug-in Read / Write / Construct Only
GimpPDBProcType procedure-type Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── GimpProcedure
        ├── GimpFileProcedure
        ├── GimpImageProcedure
        ╰── GimpThumbnailProcedure

Description

Functions

GimpRunFunc ()

GimpValueArray *
(*GimpRunFunc) (GimpProcedure *procedure,
                const GimpValueArray *args,
                gpointer run_data);

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

Parameters

procedure

the GimpProcedure that runs.

 

args

the procedure 's arguments.

 

run_data

the run_data given in gimp_procedure_new().

[closure]

Returns

the procedure 's return values.

[transfer full]

Since: 3.0


gimp_procedure_new ()

GimpProcedure *
gimp_procedure_new (GimpPlugIn *plug_in,
                    const gchar *name,
                    GimpPDBProcType proc_type,
                    GimpRunFunc run_func,
                    gpointer run_data,
                    GDestroyNotify run_data_destroy);

Creates a new procedure named name which will call run_func when invoked.

The name parameter is mandatory and should be unique, or it will overwrite an already existing procedure (overwrite procedures only if you know what you're doing).

proc_type should be GIMP_PDB_PROC_TYPE_PLUGIN for "normal" plug-ins.

Using GIMP_PDB_PROC_TYPE_EXTENSION means that the plug-in will add temporary procedures. Therefore, the GIMP core will wait until the GIMP_PDB_PROC_TYPE_EXTENSION procedure has called gimp_procedure_extension_ready(), which means that the procedure has done its initialization, installed its temporary procedures and is ready to run.

Not calling gimp_procedure_extension_ready() from a GIMP_PDB_PROC_TYPE_EXTENSION procedure will cause the GIMP core to lock up.

Additionally, a GIMP_PDB_PROC_TYPE_EXTENSION procedure with no arguments added is an "automatic" extension that will be automatically started on each GIMP startup.

GIMP_PDB_PROC_TYPE_TEMPORARY must be used for temporary procedures that are created during a plug-ins lifetime. They must be added to the GimpPlugIn using gimp_plug_in_add_temp_procedure().

run_func is called via gimp_procedure_run().

For GIMP_PDB_PROC_TYPE_PLUGIN and GIMP_PDB_PROC_TYPE_EXTENSION procedures the call of run_func is basically the lifetime of the plug-in.

Parameters

plug_in

a GimpPlugIn.

 

name

the new procedure's name.

 

proc_type

the new procedure's GimpPDBProcType.

 

run_func

the run function for the new procedure.

 

run_data

user data passed to run_func .

 

run_data_destroy

free function for run_data , or NULL.

[nullable]

Returns

a new GimpProcedure.

Since: 3.0


gimp_procedure_get_plug_in ()

GimpPlugIn *
gimp_procedure_get_plug_in (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The GimpPlugIn given in gimp_procedure_new().

[transfer none]

Since: 3.0


gimp_procedure_get_name ()

const gchar *
gimp_procedure_get_name (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's name given in gimp_procedure_new().

Since: 3.0


gimp_procedure_get_proc_type ()

GimpPDBProcType
gimp_procedure_get_proc_type (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's type given in gimp_procedure_new().

Since: 3.0


gimp_procedure_set_image_types ()

void
gimp_procedure_set_image_types (GimpProcedure *procedure,
                                const gchar *image_types);

This is a comma separated list of image types, or actually drawable types, that this procedure can deal with. Wildcards are possible here, so you could say "RGB*" instead of "RGB, RGBA" or "*" for all image types.

Supported types are "RGB", "GRAY", "INDEXED" and their variants with alpha.

Parameters

procedure

A GimpProcedure.

 

image_types

The image types this procedure can operate on.

 

Since: 3.0


gimp_procedure_get_image_types ()

const gchar *
gimp_procedure_get_image_types (GimpProcedure *procedure);

This function retrieves the list of image types the procedure can operate on. See gimp_procedure_set_image_types().

Parameters

procedure

A GimpProcedure.

 

Returns

The image types.

Since: 3.0


gimp_procedure_set_menu_label ()

void
gimp_procedure_set_menu_label (GimpProcedure *procedure,
                               const gchar *menu_label);

Sets the label to use for the procedure 's menu entry, The location(s) where to register in the menu hierarchy is chosen using gimp_procedure_add_menu_path().

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

Parameters

procedure

A GimpProcedure.

 

menu_label

The procedure 's menu label.

 

Since: 3.0


gimp_procedure_get_menu_label ()

const gchar *
gimp_procedure_get_menu_label (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's menu label given in gimp_procedure_set_menu_label().

Since: 3.0


gimp_procedure_add_menu_path ()

void
gimp_procedure_add_menu_path (GimpProcedure *procedure,
                              const gchar *menu_path);

Adds a menu path to the procedure. Only procedures which have a menu label can add a menu path.

Menu paths are untranslated paths to menus and submenus with the syntax:

<Prefix>/Path/To/Submenu

for instance:

<Image>/Layer/Transform

See also: gimp_plug_in_add_menu_branch().

Parameters

procedure

A GimpProcedure.

 

menu_path

The procedure 's additional menu path.

 

Since: 3.0


gimp_procedure_get_menu_paths ()

GList *
gimp_procedure_get_menu_paths (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

the procedure 's menu paths as added with gimp_procedure_add_menu_path().

[transfer none][element-type gchar*]

Since: 3.0


gimp_procedure_set_icon_name ()

void
gimp_procedure_set_icon_name (GimpProcedure *procedure,
                              const gchar *icon_name);

Sets the icon for procedure to the icon referenced by icon_name .

Parameters

procedure

a GimpProcedure.

 

icon_name

an icon name.

[nullable]

Since: 3.0


gimp_procedure_set_icon_file ()

void
gimp_procedure_set_icon_file (GimpProcedure *procedure,
                              GFile *file);

Sets the icon for procedure to the contents of an image file.

Parameters

procedure

a GimpProcedure.

 

file

a GFile pointing to an image file.

[nullable]

Since: 3.0


gimp_procedure_set_icon_pixbuf ()

void
gimp_procedure_set_icon_pixbuf (GimpProcedure *procedure,
                                GdkPixbuf *pixbuf);

Sets the icon for procedure to pixbuf .

Parameters

procedure

a GimpProcedure.

 

pixbuf

a GdkPixbuf.

[nullable]

Since: 3.0


gimp_procedure_get_icon_type ()

GimpIconType
gimp_procedure_get_icon_type (GimpProcedure *procedure);

Gets the type of data set as procedure 's icon. Depending on the result, you can call the relevant specific function, such as gimp_procedure_get_icon_name().

Parameters

procedure

a GimpProcedure.

 

Returns

the GimpIconType of procedure 's icon.

Since: 3.0


gimp_procedure_get_icon_name ()

const gchar *
gimp_procedure_get_icon_name (GimpProcedure *procedure);

Gets the name of the icon if one was set for procedure .

Parameters

procedure

a GimpProcedure.

 

Returns

the icon name or NULL if no icon name was set.

[nullable]

Since: 3.0


gimp_procedure_get_icon_file ()

GFile *
gimp_procedure_get_icon_file (GimpProcedure *procedure);

Gets the file of the icon if one was set for procedure .

Parameters

procedure

a GimpProcedure.

 

Returns

the icon GFile or NULL if no file was set.

[nullable][transfer none]

Since: 3.0


gimp_procedure_get_icon_pixbuf ()

GdkPixbuf *
gimp_procedure_get_icon_pixbuf (GimpProcedure *procedure);

Gets the GdkPixbuf of the icon if an icon was set this way for procedure .

Parameters

procedure

a GimpProcedure.

 

Returns

the icon pixbuf or NULL if no icon name was set.

[nullable][transfer none]

Since: 3.0


gimp_procedure_set_documentation ()

void
gimp_procedure_set_documentation (GimpProcedure *procedure,
                                  const gchar *blurb,
                                  const gchar *help,
                                  const gchar *help_id);

blurb is used as the procedure 's tooltip when represented in the UI, for example as a menu entry.

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

help is a free-form text that's meant as documentation for developers of scripts and plug-ins.

Sets various documentation strings on procedure .

Parameters

procedure

A GimpProcedure.

 

blurb

The procedure 's blurb.

 

help

The procedure 's help text.

 

help_id

The procedure 's help ID.

 

Since: 3.0


gimp_procedure_get_blurb ()

const gchar *
gimp_procedure_get_blurb (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's blurb given in gimp_procedure_set_documentation().

Since: 3.0


gimp_procedure_get_help ()

const gchar *
gimp_procedure_get_help (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's help text given in gimp_procedure_set_documentation().

Since: 3.0


gimp_procedure_get_help_id ()

const gchar *
gimp_procedure_get_help_id (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's help ID given in gimp_procedure_set_documentation().

Since: 3.0


gimp_procedure_set_attribution ()

void
gimp_procedure_set_attribution (GimpProcedure *procedure,
                                const gchar *authors,
                                const gchar *copyright,
                                const gchar *date);

Sets various attribution strings on procedure .

Parameters

procedure

A GimpProcedure.

 

authors

The procedure 's author(s).

 

copyright

The procedure 's copyright.

 

date

The procedure 's date (written or published).

 

Since: 3.0


gimp_procedure_get_authors ()

const gchar *
gimp_procedure_get_authors (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's authors given in gimp_procedure_set_attribution().

Since: 3.0


gimp_procedure_get_copyright ()

const gchar *
gimp_procedure_get_copyright (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's copyright given in gimp_procedure_set_attribution().

Since: 3.0


gimp_procedure_get_date ()

const gchar *
gimp_procedure_get_date (GimpProcedure *procedure);

Parameters

procedure

A GimpProcedure.

 

Returns

The procedure's date given in gimp_procedure_set_attribution().

Since: 3.0


gimp_procedure_add_argument ()

GParamSpec *
gimp_procedure_add_argument (GimpProcedure *procedure,
                             GParamSpec *pspec);

Add a new argument to procedure according to pspec specifications. The arguments will be ordered according to the call order to gimp_procedure_add_argument() and gimp_procedure_add_argument_from_property().

If pspec is floating, ownership will be taken over by procedure , allowing to pass directly g*_param_spec_*() calls as arguments.

Parameters

procedure

the GimpProcedure.

 

pspec

the argument specification.

[transfer floating]

Returns

the same pspec or NULL in case of error.

[transfer none]

Since: 3.0


gimp_procedure_add_aux_argument ()

GParamSpec *
gimp_procedure_add_aux_argument (GimpProcedure *procedure,
                                 GParamSpec *pspec);

Add a new auxiliary argument to procedure according to pspec specifications.

Auxiliary arguments are not passed to the procedure in run() and are not known to the PDB. They are however members of the GimpProcedureConfig created by gimp_procedure_create_config() and can be used to persistently store whatever last used values the procedure wants to remember across invocations

Parameters

procedure

the GimpProcedure.

 

pspec

the argument specification.

[transfer full]

Returns

the same pspec .

[transfer none]

Since: 3.0


gimp_procedure_add_return_value ()

GParamSpec *
gimp_procedure_add_return_value (GimpProcedure *procedure,
                                 GParamSpec *pspec);

Add a new return value to procedure according to pspec specifications.

The returned values will be ordered according to the call order to gimp_procedure_add_return_value() and gimp_procedure_add_return_value_from_property().

Parameters

procedure

the GimpProcedure.

 

pspec

the return value specification.

[transfer full]

Returns

the same pspec .

[transfer none]

Since: 3.0


gimp_procedure_find_argument ()

GParamSpec *
gimp_procedure_find_argument (GimpProcedure *procedure,
                              const gchar *name);

Searches the procedure 's arguments for a GParamSpec called name .

Parameters

procedure

A GimpProcedure

 

name

An argument name

 

Returns

The procedure 's argument with name if it exists, or NULL otherwise.

[transfer none]

Since: 3.0


gimp_procedure_find_aux_argument ()

GParamSpec *
gimp_procedure_find_aux_argument (GimpProcedure *procedure,
                                  const gchar *name);

Searches the procedure 's auxiliary arguments for a GParamSpec called name .

Parameters

procedure

A GimpProcedure

 

name

An auxiliary argument name

 

Returns

The procedure 's auxiliary argument with name if it exists, or NULL otherwise.

[transfer none]

Since: 3.0


gimp_procedure_find_return_value ()

GParamSpec *
gimp_procedure_find_return_value (GimpProcedure *procedure,
                                  const gchar *name);

Searches the procedure 's return values for a GParamSpec called name .

Parameters

procedure

A GimpProcedure

 

name

A return value name

 

Returns

The procedure 's return values with name if it exists, or NULL otherwise.

[transfer none]

Since: 3.0


gimp_procedure_get_arguments ()

GParamSpec **
gimp_procedure_get_arguments (GimpProcedure *procedure,
                              gint *n_arguments);

Parameters

procedure

A GimpProcedure.

 

n_arguments

Returns the number of arguments.

[out]

Returns

An array of GParamSpec in the order added with gimp_procedure_add_argument().

[transfer none][array length=n_arguments]

Since: 3.0


gimp_procedure_get_aux_arguments ()

GParamSpec **
gimp_procedure_get_aux_arguments (GimpProcedure *procedure,
                                  gint *n_arguments);

Parameters

procedure

A GimpProcedure.

 

n_arguments

Returns the number of auxiliary arguments.

[out]

Returns

An array of GParamSpec in the order added with gimp_procedure_add_aux_argument().

[transfer none][array length=n_arguments]

Since: 3.0


gimp_procedure_get_return_values ()

GParamSpec **
gimp_procedure_get_return_values (GimpProcedure *procedure,
                                  gint *n_return_values);

Parameters

procedure

A GimpProcedure.

 

n_return_values

Returns the number of return values.

[out]

Returns

An array of GParamSpec in the order added with gimp_procedure_add_return_value().

[transfer none][array length=n_return_values]

Since: 3.0


gimp_procedure_new_arguments ()

GimpValueArray *
gimp_procedure_new_arguments (GimpProcedure *procedure);

Format the expected argument values of procedures, in the order as added with gimp_procedure_add_argument().

Parameters

procedure

the GimpProcedure.

 

Returns

the expected GimpValueArray which could be given as arguments to run procedure , with all values set to defaults. Free with gimp_value_array_unref().

[transfer full]

Since: 3.0


gimp_procedure_new_return_values ()

GimpValueArray *
gimp_procedure_new_return_values (GimpProcedure *procedure,
                                  GimpPDBStatusType status,
                                  GError *error);

Format the expected return values from procedures, using the return values set with gimp_procedure_add_return_value().

Parameters

procedure

the GimpProcedure.

 

status

the success status of the procedure run.

 

error

an optional GError. This parameter should be set if status is either GIMP_PDB_EXECUTION_ERROR or GIMP_PDB_CALLING_ERROR.

[in][nullable][transfer full]

Returns

the expected GimpValueArray as could be returned by a GimpRunFunc.

[transfer full]

Since: 3.0


gimp_procedure_run ()

GimpValueArray *
gimp_procedure_run (GimpProcedure *procedure,
                    GimpValueArray *args);

Runs the procedure, calling the run_func given in gimp_procedure_new().

Parameters

procedure

a GimpProcedure .

 

args

the procedure 's arguments.

 

Returns

The procedure 's return values.

[transfer full]

Since: 3.0


gimp_procedure_extension_ready ()

void
gimp_procedure_extension_ready (GimpProcedure *procedure);

Notify the main GIMP application that the extension has been properly initialized and is ready to run.

This function must be called from every procedure's GimpRunFunc that was created as GIMP_PDB_PROC_TYPE_EXTENSION.

Subsequently, extensions can process temporary procedure run requests using either gimp_plug_in_extension_enable() or gimp_plug_in_extension_process().

See also: gimp_procedure_new().

Parameters

procedure

A GimpProcedure

 

Since: 3.0


gimp_procedure_create_config ()

GimpProcedureConfig *
gimp_procedure_create_config (GimpProcedure *procedure);

Create a GimpConfig with properties that match procedure 's arguments.

Parameters

procedure

A GimpProcedure

 

Returns

The new GimpConfig.

[transfer full]

Since: 3.0

Types and Values

GimpProcedure

typedef struct _GimpProcedure GimpProcedure;

struct GimpProcedureClass

struct GimpProcedureClass {
  GObjectClass parent_class;

  void                  (* install)         (GimpProcedure         *procedure);
  void                  (* uninstall)       (GimpProcedure         *procedure);

  GimpValueArray      * (* run)             (GimpProcedure         *procedure,
                                             const GimpValueArray  *args);

  GimpProcedureConfig * (* create_config)   (GimpProcedure         *procedure,
                                             GParamSpec           **args,
                                             gint                   n_args);

  gboolean              (* set_sensitivity) (GimpProcedure         *procedure,
                                             gint                   sensitivity_mask);

  /* Padding for future expansion */
};

Members

install ()

called to install the procedure with the main GIMP application. This is an implementation detail and must never be called by any plug-in code.

 

uninstall ()

called to uninstall the procedure from the main GIMP application. This is an implementation detail and must never be called by any plug-in code.

 

run ()

called when the procedure is executed via gimp_procedure_run(). the default implementation simply calls the procedure's GimpRunFunc, GimpProcedure subclasses are free to modify the passed args and call their own, subclass-specific run functions.

 

create_config ()

called when a GimpConfig object is created using gimp_procedure_create_config().

 

set_sensitivity ()

   

Since: 3.0

Property Details

The “name” property

  “name”                     char *

The procedure's name.

Owner: GimpProcedure

Flags: Read / Write / Construct Only

Default value: NULL


The “plug-in” property

  “plug-in”                  GimpPlugIn *

The GimpPlugIn of this plug-in process.

Owner: GimpProcedure

Flags: Read / Write / Construct Only


The “procedure-type” property

  “procedure-type”           GimpPDBProcType

The procedure's type.

Owner: GimpProcedure

Flags: Read / Write / Construct Only

Default value: GIMP_PDB_PROC_TYPE_PLUGIN