about: Add :license-type property

The :license-type property of GtkAboutDialog allows using a symbolic
enumeration value that will construct a placeholder license preamble
linking to a specific URL. This allows localization of the licensing
text without using a translation of the actual license, since it would
not be valid.
Bug 336225.

demos/gtk-demo/appwindow.c

@@ -109,22 +109,6 @@ about_cb (GtkAction *action,
     NULL
   };
 
-  const gchar *license =
-    "This library is free software; you can redistribute it and/or\n"
-    "modify it under the terms of the GNU Library General Public License as\n"
-    "published by the Free Software Foundation; either version 2 of the\n"
-    "License, or (at your option) any later version.\n"
-    "\n"
-    "This library is distributed in the hope that it will be useful,\n"
-    "but WITHOUT ANY WARRANTY; without even the implied warranty of\n"
-    "MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n"
-    "Library General Public License for more details.\n"
-    "\n"
-    "You should have received a copy of the GNU Library General Public\n"
-    "License along with the Gnome Library; see the file COPYING.LIB.  If not,\n"
-    "write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,\n"
-    "Boston, MA 02111-1307, USA.\n";
-
   pixbuf = NULL;
   transparent = NULL;
   filename = demo_find_file ("gtk-logo-rgb.gif", NULL);
@@ -142,7 +126,7 @@ about_cb (GtkAction *action,
 			 "program-name", "GTK+ Code Demos",
 			 "version", PACKAGE_VERSION,
 			 "copyright", "(C) 1997-2009 The GTK+ Team",
-			 "license", license,
+			 "license-type", GTK_LICENSE_LGPL_2_1,
 			 "website", "http://www.gtk.org",
 			 "comments", "Program to demonstrate GTK+ functions.",
 			 "authors", authors,

docs/reference/gtk/gtk3-sections.txt

@@ -18,6 +18,8 @@ gtk_about_dialog_get_license
 gtk_about_dialog_set_license
 gtk_about_dialog_get_wrap_license
 gtk_about_dialog_set_wrap_license
+gtk_about_dialog_get_license_type
+gtk_about_dialog_set_license_type
 gtk_about_dialog_get_website
 gtk_about_dialog_set_website
 gtk_about_dialog_get_website_label

gtk/gtk.symbols

@@ -31,6 +31,7 @@ gtk_about_dialog_get_comments
 gtk_about_dialog_get_copyright
 gtk_about_dialog_get_documenters
 gtk_about_dialog_get_license
+gtk_about_dialog_get_license_type
 gtk_about_dialog_get_logo
 gtk_about_dialog_get_logo_icon_name
 gtk_about_dialog_get_program_name
@@ -49,6 +50,7 @@ gtk_about_dialog_set_copyright
 gtk_about_dialog_set_documenters
 gtk_about_dialog_set_email_hook
 gtk_about_dialog_set_license
+gtk_about_dialog_set_license_type
 gtk_about_dialog_set_logo
 gtk_about_dialog_set_logo_icon_name
 gtk_about_dialog_set_translator_credits

gtk/gtkaboutdialog.c

@@ -115,10 +115,31 @@
  * #GtkWidget:name property.
  */
 
-
 static GdkColor default_link_color = { 0, 0, 0, 0xeeee };
 static GdkColor default_visited_link_color = { 0, 0x5555, 0x1a1a, 0x8b8b };
 
+/* Translators: this is the license preamble; the string at the end
+ * contains the URL of the license.
+ */
+static const gchar *gtk_license_preamble = N_("This program comes with ABSOLUTELY NO WARRANTY; for details, visit %s");
+
+/* URLs for each GtkLicense type; keep in the same order as the enumeration */
+static const gchar *gtk_license_urls[] = {
+  NULL,
+  NULL,
+
+  "http://www.gnu.org/licenses/old-licenses/gpl-2.0.html",
+  "http://www.gnu.org/licenses/gpl.html",
+
+  "http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html",
+  "http://www.gnu.org/licenses/lgpl.html",
+
+  "http://opensource.org/licenses/bsd-license.php",
+  "http://opensource.org/licenses/mit-license.php",
+
+  "http://opensource.org/licenses/artistic-license-2.0.php"
+};
+
 struct _GtkAboutDialogPrivate 
 {
   gchar *name;
@@ -150,6 +171,8 @@ struct _GtkAboutDialogPrivate
 
   GSList *visited_links;
 
+  GtkLicense license_type;
+
   guint hovering_over_link : 1;
   guint wrap_license : 1;
 };
@@ -173,7 +196,8 @@ enum
   PROP_ARTISTS,
   PROP_LOGO,
   PROP_LOGO_ICON_NAME,
-  PROP_WRAP_LICENSE
+  PROP_WRAP_LICENSE,
+  PROP_LICENSE_TYPE
 };
 
 static void                 gtk_about_dialog_finalize       (GObject            *object);
@@ -354,6 +378,9 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
    * a long multi-paragraph text. Note that the text is only wrapped
    * in the text view if the "wrap-license" property is set to %TRUE;
    * otherwise the text itself must contain the intended linebreaks.
+   * When setting this property to a non-%NULL value, the
+   * #GtkAboutDialog:license-type property is set to %GTK_LICENSE_CUSTOM
+   * as a side effect.
    *
    * Since: 2.6
    */
@@ -365,6 +392,36 @@ gtk_about_dialog_class_init (GtkAboutDialogClass *klass)
                                                         NULL,
                                                         GTK_PARAM_READWRITE));
 
+  /**
+   * GtkAboutDialog:license-type:
+   *
+   * The license of the program, as a value of the %GtkLicense enumeration.
+   *
+   * The #GtkAboutDialog will automatically fill out a standard disclaimer
+   * and link the user to the appropriate online resource for the license
+   * text.
+   *
+   * If %GTK_LICENSE_UNKNOWN is used, the link used will be the same
+   * specified in the #GtkAboutDialog:website property.
+   *
+   * If %GTK_LICENSE_CUSTOM is used, the current contents of the
+   * #GtkAboutDialog:license property are used.
+   *
+   * For any other #GtkLicense value, the contents of the
+   * #GtkAboutDialog:license property are also set by this property as
+   * a side effect.
+   *
+   * Since: 3.0
+   */
+  g_object_class_install_property (object_class,
+                                   PROP_LICENSE_TYPE,
+                                   g_param_spec_enum ("license-type",
+                                                      P_("License Type"),
+                                                      P_("The license type of the program"),
+                                                      GTK_TYPE_LICENSE,
+                                                      GTK_LICENSE_UNKNOWN,
+                                                      GTK_PARAM_READWRITE));
+
   /**
    * GtkAboutDialog:website:
    *
@@ -569,6 +626,8 @@ gtk_about_dialog_init (GtkAboutDialog *about)
   priv->hovering_over_link = FALSE;
   priv->wrap_license = FALSE;
 
+  priv->license_type = GTK_LICENSE_UNKNOWN;
+
   content_area = gtk_dialog_get_content_area (dialog);
   action_area = gtk_dialog_get_action_area (dialog);
 
@@ -718,6 +777,9 @@ gtk_about_dialog_set_property (GObject      *object,
     case PROP_LICENSE:
       gtk_about_dialog_set_license (about, g_value_get_string (value));
       break;
+    case PROP_LICENSE_TYPE:
+      gtk_about_dialog_set_license_type (about, g_value_get_enum (value));
+      break;
     case PROP_COPYRIGHT:
       gtk_about_dialog_set_copyright (about, g_value_get_string (value));
       break;
@@ -780,6 +842,9 @@ gtk_about_dialog_get_property (GObject    *object,
     case PROP_LICENSE:
       g_value_set_string (value, priv->license);
       break;
+    case PROP_LICENSE_TYPE:
+      g_value_set_enum (value, priv->license_type);
+      break;
     case PROP_TRANSLATOR_CREDITS:
       g_value_set_string (value, priv->translator_credits);
       break;
@@ -1153,16 +1218,19 @@ gtk_about_dialog_set_license (GtkAboutDialog *about,
   if (license)
     {
       priv->license = g_strdup (license);
+      priv->license_type = GTK_LICENSE_CUSTOM;
       gtk_widget_show (priv->license_button);
     }
   else
     {
       priv->license = NULL;
+      priv->license_type = GTK_LICENSE_UNKNOWN;
       gtk_widget_hide (priv->license_button);
     }
   g_free (tmp);
 
   g_object_notify (G_OBJECT (about), "license");
+  g_object_notify (G_OBJECT (about), "license-type");
 }
 
 /**
@@ -2439,3 +2507,90 @@ gtk_show_about_dialog (GtkWindow   *parent,
 
   gtk_window_present (GTK_WINDOW (dialog));
 }
+
+/**
+ * gtk_about_dialog_set_license_type:
+ * @about: a #GtkAboutDialog
+ * @license_type: the type of license
+ *
+ * Sets the license of the application showing the @about dialog from a
+ * list of known licenses.
+ *
+ * This function overrides the license set using
+ * gtk_about_dialog_set_license().
+ *
+ * Since: 3.0
+ */
+void
+gtk_about_dialog_set_license_type (GtkAboutDialog *about,
+                                   GtkLicense      license_type)
+{
+  GtkAboutDialogPrivate *priv;
+
+  g_return_if_fail (GTK_IS_ABOUT_DIALOG (about));
+  g_return_if_fail (license_type >= GTK_LICENSE_UNKNOWN &&
+                    license_type <= GTK_LICENSE_ARTISTIC);
+
+  priv = about->priv;
+
+  if (priv->license_type != license_type)
+    {
+      g_object_freeze_notify (G_OBJECT (about));
+
+      priv->license_type = license_type;
+
+      /* custom licenses use the contents of the :license property */
+      if (priv->license_type != GTK_LICENSE_CUSTOM)
+        {
+          const gchar *url;
+          GString *str;
+
+          url = gtk_license_urls[priv->license_type];
+          if (url == NULL)
+            url = priv->website_url;
+
+          /* compose the new license string as:
+           *
+           *   <program-name>  <copyright>\n
+           *   license preamble + URL
+           *
+           */
+          str = g_string_sized_new (256);
+          g_string_append (str, priv->name);
+          g_string_append (str, "  ");
+          g_string_append (str, priv->copyright);
+          g_string_append (str, "\n");
+          g_string_append_printf (str, gettext (gtk_license_preamble), url);
+
+          g_free (priv->license);
+          priv->license = g_string_free (str, FALSE);
+          priv->wrap_license = TRUE;
+          gtk_widget_show (priv->license_button);
+
+          g_object_notify (G_OBJECT (about), "wrap-license");
+          g_object_notify (G_OBJECT (about), "license");
+        }
+
+      g_object_notify (G_OBJECT (about), "license-type");
+
+      g_object_thaw_notify (G_OBJECT (about));
+    }
+}
+
+/**
+ * gtk_about_dialog_get_license_type:
+ * @about: a #GtkAboutDialog
+ *
+ * Retrieves the license set using gtk_about_dialog_set_license_type()
+ *
+ * Return value: a #GtkLicense value
+ *
+ * Since: 3.0
+ */
+GtkLicense
+gtk_about_dialog_get_license_type (GtkAboutDialog *about)
+{
+  g_return_val_if_fail (GTK_IS_ABOUT_DIALOG (about), GTK_LICENSE_UNKNOWN);
+
+  return about->priv->license_type;
+}

gtk/gtkaboutdialog.h

@@ -44,6 +44,41 @@ typedef struct _GtkAboutDialog        GtkAboutDialog;
 typedef struct _GtkAboutDialogClass   GtkAboutDialogClass;
 typedef struct _GtkAboutDialogPrivate GtkAboutDialogPrivate;
 
+/**
+ * GtkLicense:
+ * @GTK_LICENSE_UNKNOWN: No license specified
+ * @GTK_LICENSE_CUSTOM: A license text is going to be specified by the
+ *   developer
+ * @GTK_LICENSE_GPL_2_0: The GNU General Public License, version 2.0
+ * @GTK_LICENSE_GPL_3_0: The GNU General Public License, version 3.0
+ * @GTK_LICENSE_LGPL_2_1: The GNU Lesser General Public License, version 2.1
+ * @GTK_LICENSE_LGPL_3_0: The GNU Lesser General Public License, version 3.0
+ * @GTK_LICENSE_BSD: The BSD standard license
+ * @GTK_LICENSE_MIT_X11: The MIT/X11 standard license
+ * @GTK_LICENSE_ARTISTIC: The Artistic License, version 2.0
+ *
+ * The type of license for an application.
+ *
+ * This enumeration can be expanded at later date.
+ *
+ * Since: 3.0
+ */
+typedef enum {
+  GTK_LICENSE_UNKNOWN,
+  GTK_LICENSE_CUSTOM,
+
+  GTK_LICENSE_GPL_2_0,
+  GTK_LICENSE_GPL_3_0,
+
+  GTK_LICENSE_LGPL_2_1,
+  GTK_LICENSE_LGPL_3_0,
+
+  GTK_LICENSE_BSD,
+  GTK_LICENSE_MIT_X11,
+
+  GTK_LICENSE_ARTISTIC
+} GtkLicense;
+
 /**
  * GtkAboutDialog:
  *
@@ -89,6 +124,9 @@ void                   gtk_about_dialog_set_comments           (GtkAboutDialog
 G_CONST_RETURN gchar  *gtk_about_dialog_get_license            (GtkAboutDialog  *about);
 void                   gtk_about_dialog_set_license            (GtkAboutDialog  *about,
 								const gchar     *license);
+void                   gtk_about_dialog_set_license_type       (GtkAboutDialog  *about,
+                                                                GtkLicense       license_type);
+GtkLicense             gtk_about_dialog_get_license_type       (GtkAboutDialog  *about);
 
 gboolean               gtk_about_dialog_get_wrap_license       (GtkAboutDialog  *about);
 void                   gtk_about_dialog_set_wrap_license       (GtkAboutDialog  *about,