[gimp] libgimp, plug-ins: add a "format name" concept to GimpFileProcedure.

[Jehan <jehanp src gnome org>]

commit b13502088f988baab54ba46e7d85e067b4bd05b9
Author: Jehan <jehan girinstud io>
Date:   Thu Dec 17 02:02:14 2020 +0100

    libgimp, plug-ins: add a "format name" concept to GimpFileProcedure.
    
    This format name is a public facing name for a file format, such as
    "PNG", "JPEG", or "C-source". Since it is public facing, the function
    recommends to localize it too.
    This is an optional name, yet is made mandatory if you want to use
    GimpSaveProcedureDialog because it will be used for the dialog title
    (ensuring that all support format have a similar export dialog title).
    Following this change, gimp_save_procedure_dialog_new() does not ask for
    a title anymore (if anyone absolutely wants to set a custom title,
    setting the "title" property on the dialog is always possible anyway,
    but a generic and consistent title should be set as a default).
    
    Also updating the 3 plug-ins which were already using the now-changed
    API.

 libgimp/gimpfileprocedure.c         | 51 +++++++++++++++++++++++++++++++++++++
 libgimp/gimpfileprocedure.h         |  4 +++
 libgimp/gimpsaveproceduredialog.c   | 19 +++++++++++---
 libgimp/gimpsaveproceduredialog.h   |  3 +--
 plug-ins/common/file-png.c          |  5 ++--
 plug-ins/file-jpeg/jpeg-save.c      |  3 +--
 plug-ins/file-jpeg/jpeg.c           |  2 ++
 plug-ins/file-tiff/file-tiff-save.c |  3 +--
 plug-ins/file-tiff/file-tiff.c      |  2 ++
 9 files changed, 81 insertions(+), 11 deletions(-)
---
diff --git a/libgimp/gimpfileprocedure.c b/libgimp/gimpfileprocedure.c
index b27656ceeb..45798adf2e 100644
--- a/libgimp/gimpfileprocedure.c
+++ b/libgimp/gimpfileprocedure.c
@@ -26,6 +26,7 @@
 
 struct _GimpFileProcedurePrivate
 {
+  gchar    *format_name;
   gchar    *mime_types;
   gchar    *extensions;
   gchar    *prefixes;
@@ -80,6 +81,7 @@ gimp_file_procedure_finalize (GObject *object)
 {
   GimpFileProcedure *procedure = GIMP_FILE_PROCEDURE (object);
 
+  g_clear_pointer (&procedure->priv->format_name, g_free);
   g_clear_pointer (&procedure->priv->mime_types, g_free);
   g_clear_pointer (&procedure->priv->extensions, g_free);
   g_clear_pointer (&procedure->priv->prefixes,   g_free);
@@ -91,6 +93,55 @@ gimp_file_procedure_finalize (GObject *object)
 
 /*  public functions  */
 
+/**
+ * gimp_file_procedure_set_format_name:
+ * @procedure: A #GimpFileProcedure.
+ * @format_name: A public-facing name for the format, e.g. "PNG".
+ *
+ * Associates a format name with a file handler procedure.
+ *
+ * This name can be used for any public-facing strings, such as
+ * graphical interface labels. An example usage would be
+ * %GimpSaveProcedureDialog title looking like "Export Image as %s".
+ *
+ * Note that since the format name is public-facing, it is recommended
+ * to localize it at runtime, for instance through gettext, like:
+ * |[<!-- language="C" -->
+ * gimp_file_procedure_set_format_name (procedure, _("JPEG"));
+ * ]|
+ * Some language would indeed localize even some technical terms or
+ * acronyms, even if sometimes just to rewrite them with the local
+ * writing system.
+ *
+ * Since: 3.0
+ **/
+void
+gimp_file_procedure_set_format_name (GimpFileProcedure *procedure,
+                                     const gchar       *format_name)
+{
+  g_return_if_fail (GIMP_IS_FILE_PROCEDURE (procedure));
+
+  g_free (procedure->priv->format_name);
+  procedure->priv->format_name = g_strdup (format_name);
+}
+
+/**
+ * gimp_file_procedure_get_format_name:
+ * @procedure: A #GimpFileProcedure.
+ *
+ * Returns: The procedure's format name as set with
+ *          gimp_file_procedure_set_format_name().
+ *
+ * Since: 3.0
+ **/
+const gchar *
+gimp_file_procedure_get_format_name (GimpFileProcedure *procedure)
+{
+  g_return_val_if_fail (GIMP_IS_FILE_PROCEDURE (procedure), NULL);
+
+  return procedure->priv->format_name;
+}
+
 /**
  * gimp_file_procedure_set_mime_types:
  * @procedure: A #GimpFileProcedure.
diff --git a/libgimp/gimpfileprocedure.h b/libgimp/gimpfileprocedure.h
index efb8f96b75..78d1e3527b 100644
--- a/libgimp/gimpfileprocedure.h
+++ b/libgimp/gimpfileprocedure.h
@@ -56,6 +56,10 @@ struct _GimpFileProcedureClass
 
 GType           gimp_file_procedure_get_type        (void) G_GNUC_CONST;
 
+void            gimp_file_procedure_set_format_name (GimpFileProcedure *procedure,
+                                                     const gchar       *format_name);
+const gchar   * gimp_file_procedure_get_format_name (GimpFileProcedure *procedure);
+
 void            gimp_file_procedure_set_mime_types  (GimpFileProcedure *procedure,
                                                      const gchar       *mime_types);
 const gchar   * gimp_file_procedure_get_mime_types  (GimpFileProcedure *procedure);
diff --git a/libgimp/gimpsaveproceduredialog.c b/libgimp/gimpsaveproceduredialog.c
index efec13ef66..c4f46e2de6 100644
--- a/libgimp/gimpsaveproceduredialog.c
+++ b/libgimp/gimpsaveproceduredialog.c
@@ -255,10 +255,11 @@ gimp_save_procedure_dialog_fill_list (GimpProcedureDialog *dialog,
 
 GtkWidget *
 gimp_save_procedure_dialog_new (GimpSaveProcedure   *procedure,
-                                GimpProcedureConfig *config,
-                                const gchar         *title)
+                                GimpProcedureConfig *config)
 {
   GtkWidget   *dialog;
+  gchar       *title;
+  const gchar *format_name;
   const gchar *help_id;
   gboolean     use_header_bar;
 
@@ -266,7 +267,18 @@ gimp_save_procedure_dialog_new (GimpSaveProcedure   *procedure,
   g_return_val_if_fail (GIMP_IS_PROCEDURE_CONFIG (config), NULL);
   g_return_val_if_fail (gimp_procedure_config_get_procedure (config) ==
                         GIMP_PROCEDURE (procedure), NULL);
-  g_return_val_if_fail (title != NULL, NULL);
+
+  format_name = gimp_file_procedure_get_format_name (GIMP_FILE_PROCEDURE (procedure));
+  if (! format_name)
+    {
+      g_critical ("%s: no format name set on file procedure '%s'. "
+                  "Set one with gimp_file_procedure_set_format_name()",
+                  G_STRFUNC,
+                  gimp_procedure_get_name (GIMP_PROCEDURE (procedure)));
+      return NULL;
+    }
+  /* TRANSLATORS: %s will be a format name, e.g. "PNG" or "JPEG". */
+  title = g_strdup_printf (_("Export Image as %s"), format_name);
 
   help_id = gimp_procedure_get_help_id (GIMP_PROCEDURE (procedure));
 
@@ -282,6 +294,7 @@ gimp_save_procedure_dialog_new (GimpSaveProcedure   *procedure,
                          "help-id",        help_id,
                          "use-header-bar", use_header_bar,
                          NULL);
+  g_free (title);
 
   return dialog;
 }
diff --git a/libgimp/gimpsaveproceduredialog.h b/libgimp/gimpsaveproceduredialog.h
index e97b4111f3..77edd24ccb 100644
--- a/libgimp/gimpsaveproceduredialog.h
+++ b/libgimp/gimpsaveproceduredialog.h
@@ -67,8 +67,7 @@ struct _GimpSaveProcedureDialogClass
 GType       gimp_save_procedure_dialog_get_type          (void) G_GNUC_CONST;
 
 GtkWidget * gimp_save_procedure_dialog_new               (GimpSaveProcedure   *procedure,
-                                                          GimpProcedureConfig *config,
-                                                          const gchar         *title);
+                                                          GimpProcedureConfig *config);
 
 void        gimp_save_procedure_dialog_add_metadata      (GimpSaveProcedureDialog *dialog,
                                                           const gchar             *property);
diff --git a/plug-ins/common/file-png.c b/plug-ins/common/file-png.c
index 3b7ba75fcc..63e2c91110 100644
--- a/plug-ins/common/file-png.c
+++ b/plug-ins/common/file-png.c
@@ -218,6 +218,8 @@ png_create_procedure (GimpPlugIn  *plug_in,
                                       "Nick Lamb <njl195 zepler org uk>",
                                       PLUG_IN_VERSION);
 
+      gimp_file_procedure_set_format_name (GIMP_FILE_PROCEDURE (procedure),
+                                           _("PNG"));
       gimp_file_procedure_set_mime_types (GIMP_FILE_PROCEDURE (procedure),
                                           "image/png");
       gimp_file_procedure_set_extensions (GIMP_FILE_PROCEDURE (procedure),
@@ -2165,8 +2167,7 @@ save_dialog (GimpImage     *image,
   gboolean      run;
 
   dialog = gimp_save_procedure_dialog_new (GIMP_SAVE_PROCEDURE (procedure),
-                                           GIMP_PROCEDURE_CONFIG (config),
-                                           _("Export Image as PNG"));
+                                           GIMP_PROCEDURE_CONFIG (config));
 
   gimp_procedure_dialog_get_widget (GIMP_PROCEDURE_DIALOG (dialog),
                                     "compression", GIMP_TYPE_SCALE_ENTRY);
diff --git a/plug-ins/file-jpeg/jpeg-save.c b/plug-ins/file-jpeg/jpeg-save.c
index 83a8e13162..8fa030b32b 100644
--- a/plug-ins/file-jpeg/jpeg-save.c
+++ b/plug-ins/file-jpeg/jpeg-save.c
@@ -796,8 +796,7 @@ save_dialog (GimpProcedure       *procedure,
                 NULL);
 
   dialog = gimp_save_procedure_dialog_new (GIMP_SAVE_PROCEDURE (procedure),
-                                           GIMP_PROCEDURE_CONFIG (config),
-                                           _("Export Image as JPEG"));
+                                           GIMP_PROCEDURE_CONFIG (config));
 
   /* custom quantization tables - now used also for original quality */
   widget = gimp_procedure_dialog_get_widget (GIMP_PROCEDURE_DIALOG (dialog),
diff --git a/plug-ins/file-jpeg/jpeg.c b/plug-ins/file-jpeg/jpeg.c
index a3c1cab131..e612984f56 100644
--- a/plug-ins/file-jpeg/jpeg.c
+++ b/plug-ins/file-jpeg/jpeg.c
@@ -186,6 +186,8 @@ jpeg_create_procedure (GimpPlugIn  *plug_in,
                                       "Spencer Kimball & Peter Mattis",
                                       "1995-2007");
 
+      gimp_file_procedure_set_format_name (GIMP_FILE_PROCEDURE (procedure),
+                                           _("JPEG"));
       gimp_file_procedure_set_mime_types (GIMP_FILE_PROCEDURE (procedure),
                                           "image/jpeg");
       gimp_file_procedure_set_extensions (GIMP_FILE_PROCEDURE (procedure),
diff --git a/plug-ins/file-tiff/file-tiff-save.c b/plug-ins/file-tiff/file-tiff-save.c
index 386c065469..45ce1c5336 100644
--- a/plug-ins/file-tiff/file-tiff-save.c
+++ b/plug-ins/file-tiff/file-tiff-save.c
@@ -1283,8 +1283,7 @@ save_dialog (GimpImage     *image,
   gboolean         run;
 
   dialog = gimp_save_procedure_dialog_new (GIMP_SAVE_PROCEDURE (procedure),
-                                           GIMP_PROCEDURE_CONFIG (config),
-                                           _("Export Image as TIFF"));
+                                           GIMP_PROCEDURE_CONFIG (config));
 
   store =
     gimp_int_store_new (_("None"),              GIMP_COMPRESSION_NONE,
diff --git a/plug-ins/file-tiff/file-tiff.c b/plug-ins/file-tiff/file-tiff.c
index c5b6cc9be5..ff2812e7ca 100644
--- a/plug-ins/file-tiff/file-tiff.c
+++ b/plug-ins/file-tiff/file-tiff.c
@@ -188,6 +188,8 @@ tiff_create_procedure (GimpPlugIn  *plug_in,
 
       gimp_file_procedure_set_handles_remote (GIMP_FILE_PROCEDURE (procedure),
                                               TRUE);
+      gimp_file_procedure_set_format_name (GIMP_FILE_PROCEDURE (procedure),
+                                           _("TIFF"));
       gimp_file_procedure_set_mime_types (GIMP_FILE_PROCEDURE (procedure),
                                           "image/tiff");
       gimp_file_procedure_set_extensions (GIMP_FILE_PROCEDURE (procedure),