[gimp] libgimp: new gimp_pdb_run_procedure_config() function.

[Jehan <jehanp src gnome org>]

commit 43f44288ef4c6890b6dd8aaf4fcd2f5b29f9f362
Author: Jehan <jehan girinstud io>
Date:   Fri Feb 11 17:44:26 2022 +0100

    libgimp: new gimp_pdb_run_procedure_config() function.
    
    While we do have quite a few gimp_pdb_run_procedure*() functions now, I
    always felt that one based on a config file was missing, even more as we
    are getting further and further into using config objects in plug-ins.
    
    In C, the gimp_pdb_run_procedure() function is without a doubt the
    easiest one. But such variable arg functions are not available on
    bindings, and having to deal with GValue and GimpValueArray is a real
    pain.
    
    Also using a config file has the very great advantage that we don't need
    to care about order. For instance, if I need to set the 10th argument of
    a PDB call (and leave the rest to default values), I don't have to set
    all 9 previous arguments. I can set only this one if I want. This
    advantage is useful also for C code by the way.
    
    For the record, here is how you could load then export an image with the
    "file-png-*" PDB procedures in Python:
    
    > c = Gimp.get_pdb().lookup_procedure('file-png-load').create_config()
    > c.set_property('file', Gio.file_new_for_path('/path/sample.png'))
    > r = Gimp.get_pdb().run_procedure_config('file-png-load', c)
    > d = Gimp.Display.new(r.index(1)) # Give it a display to work on it.
    
    Now exporting:
    
    > img = r.index(1)
    > c = Gimp.get_pdb().lookup_procedure('file-png-save').create_config()
    > c.set_property('image', img)
    > c.set_property('file', Gio.file_new_for_path('/path/exported.png'))
    > layers = img.get_layers()
    > c.set_property('drawables', Gimp.ObjectArray.new(Gimp.Drawable, layers, False))
    > c.set_property('num-drawables', len(layers))
    > r = Gimp.get_pdb().run_procedure_config('file-png-save', c)

 libgimp/gimp.def  |  1 +
 libgimp/gimppdb.c | 40 ++++++++++++++++++++++++++++++++++++++++
 libgimp/gimppdb.h |  3 +++
 3 files changed, 44 insertions(+)
---
diff --git a/libgimp/gimp.def b/libgimp/gimp.def
index b6e9f3287c..753248cd78 100644
--- a/libgimp/gimp.def
+++ b/libgimp/gimp.def
@@ -680,6 +680,7 @@ EXPORTS
        gimp_pdb_run_procedure
        gimp_pdb_run_procedure_argv
        gimp_pdb_run_procedure_array
+       gimp_pdb_run_procedure_config
        gimp_pdb_run_procedure_valist
        gimp_pdb_set_data
        gimp_pdb_temp_procedure_name
diff --git a/libgimp/gimppdb.c b/libgimp/gimppdb.c
index 2136b67c3f..53eb6f5f72 100644
--- a/libgimp/gimppdb.c
+++ b/libgimp/gimppdb.c
@@ -362,6 +362,46 @@ gimp_pdb_run_procedure_array (GimpPDB              *pdb,
   return return_values;
 }
 
+/**
+ * gimp_pdb_run_procedure_config:
+ * @pdb:            the #GimpPDB object.
+ * @procedure_name: the registered name to call.
+ * @config:         a config object obtained with gimp_procedure_create_config().
+ *
+ * Runs the procedure named @procedure_name with @config.
+ *
+ * Returns: (transfer full): the return values for the procedure call.
+ *
+ * Since: 3.0
+ */
+GimpValueArray *
+gimp_pdb_run_procedure_config (GimpPDB             *pdb,
+                               const gchar         *procedure_name,
+                               GimpProcedureConfig *config)
+{
+  GimpProcedure  *procedure;
+  GimpValueArray *args;
+  GimpValueArray *return_values;
+
+  g_return_val_if_fail (GIMP_IS_PDB (pdb), NULL);
+  g_return_val_if_fail (gimp_is_canonical_identifier (procedure_name), NULL);
+  g_return_val_if_fail (GIMP_IS_PROCEDURE_CONFIG (config), NULL);
+
+  procedure = gimp_pdb_lookup_procedure (pdb, procedure_name);
+
+  g_return_val_if_fail (gimp_procedure_config_get_procedure (config) == procedure,
+                        NULL);
+
+  args = gimp_procedure_new_arguments (procedure);
+
+  gimp_procedure_config_get_values (config, args);
+  return_values = gimp_pdb_run_procedure_array (pdb, procedure_name, args);
+
+  gimp_value_array_unref (args);
+
+  return return_values;
+}
+
 /**
  * gimp_pdb_temp_procedure_name:
  * @pdb: the #GimpPDB object.
diff --git a/libgimp/gimppdb.h b/libgimp/gimppdb.h
index af16d3249a..fbea62a7ed 100644
--- a/libgimp/gimppdb.h
+++ b/libgimp/gimppdb.h
@@ -88,6 +88,9 @@ GimpValueArray * gimp_pdb_run_procedure_argv   (GimpPDB              *pdb,
 GimpValueArray * gimp_pdb_run_procedure_array  (GimpPDB              *pdb,
                                                 const gchar          *procedure_name,
                                                 const GimpValueArray *arguments);
+GimpValueArray * gimp_pdb_run_procedure_config (GimpPDB              *pdb,
+                                                const gchar          *procedure_name,
+                                                GimpProcedureConfig  *config);
 
 gchar          * gimp_pdb_temp_procedure_name  (GimpPDB              *pdb);