[gspell/wip/lang-choosers] language-choosers: add language-code property

[Sébastien Wilmet <swilmet src gnome org>]

commit d4189851fb502388b2e481f54a7416940b4823c4
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Thu Jan 14 15:32:04 2016 +0100

    language-choosers: add language-code property
    
    https://bugzilla.gnome.org/show_bug.cgi?id=758421

 gspell/gspell-language-chooser.c |   70 +++++++++++++++++++++++++++++++++++++-
 gspell/gspell-language-chooser.h |   18 +++++++--
 2 files changed, 83 insertions(+), 5 deletions(-)
---
diff --git a/gspell/gspell-language-chooser.c b/gspell/gspell-language-chooser.c
index eeaf3ee..ea90a28 100644
--- a/gspell/gspell-language-chooser.c
+++ b/gspell/gspell-language-chooser.c
@@ -27,6 +27,28 @@
  *
  * #GspellLanguageChooser is an interface that is implemented by widgets for
  * choosing a #GspellLanguage.
+ *
+ * There are two properties: #GspellLanguageChooser:language and
+ * #GspellLanguageChooser:language-code. They are kept in sync. The former is
+ * useful to, for example, bind it to the #GspellChecker's language property
+ * with g_object_bind_property(). The latter is useful to bind it to a
+ * #GSettings key with g_settings_bind().
+ *
+ * When setting the language, %NULL or the empty string can be passed to pick
+ * the default language. In that case, the #GspellLanguageChooser:language-code
+ * property will contain the empty string, whereas the
+ * #GspellLanguageChooser:language property will contain the actual
+ * #GspellLanguage as returned by gspell_language_get_default(). If the user
+ * launches the #GspellLanguageChooser and chooses explicitly a language, then
+ * the #GspellLanguageChooser:language-code property will no longer be empty,
+ * even if it is the same language as the default language.
+ *
+ * Note that if an explicit language (non-%NULL or not the empty string) is set
+ * to the #GspellLanguageChooser, then the #GspellLanguageChooser:language-code
+ * property will not be empty, it will contain the language code of the passed
+ * language, even if the language is the same as the default language.
+ *
+ * Thus, a good default value for a #GSettings key is the empty string.
  */
 
 G_DEFINE_INTERFACE (GspellLanguageChooser, gspell_language_chooser, G_TYPE_OBJECT)
@@ -46,13 +68,29 @@ gspell_language_chooser_default_init (GspellLanguageChooserInterface *interface)
                                                                 GSPELL_TYPE_LANGUAGE,
                                                                 G_PARAM_READWRITE |
                                                                 G_PARAM_STATIC_STRINGS));
+
+       /**
+        * GspellLanguageChooser:language-code:
+        *
+        * The empty string if the default language was set and the selection
+        * hasn't changed. Or the language code if an explicit language was set
+        * or if the selection has changed.
+        */
+       g_object_interface_install_property (interface,
+                                            g_param_spec_string ("language-code",
+                                                                 "Language Code",
+                                                                 "",
+                                                                 "",
+                                                                 G_PARAM_READWRITE |
+                                                                 G_PARAM_STATIC_STRINGS));
 }
 
 /**
  * gspell_language_chooser_get_language:
  * @chooser: a #GspellLanguageChooser.
  *
- * Returns: (nullable): the selected #GspellLanguage.
+ * Returns: (nullable): the selected #GspellLanguage, or %NULL if no
+ * dictionaries are available.
  */
 const GspellLanguage *
 gspell_language_chooser_get_language (GspellLanguageChooser *chooser)
@@ -79,4 +117,34 @@ gspell_language_chooser_set_language (GspellLanguageChooser *chooser,
        GSPELL_LANGUAGE_CHOOSER_GET_IFACE (chooser)->set_language (chooser, language);
 }
 
+/**
+ * gspell_language_chooser_get_language_code:
+ * @chooser: a #GspellLanguageChooser.
+ *
+ * Returns: the #GspellLanguageChooser:language-code. It cannot be %NULL.
+ */
+const gchar *
+gspell_language_chooser_get_language_code (GspellLanguageChooser *chooser)
+{
+       g_return_val_if_fail (GSPELL_IS_LANGUAGE_CHOOSER (chooser), "");
+
+       return GSPELL_LANGUAGE_CHOOSER_GET_IFACE (chooser)->get_language_code (chooser);
+}
+
+/**
+ * gspell_language_chooser_set_language_code:
+ * @chooser: a #GspellLanguageChooser.
+ * @language_code: (nullable): a language code, or the empty string or %NULL to
+ *   pick the default language.
+ */
+void
+gspell_language_chooser_set_language_code (GspellLanguageChooser *chooser,
+                                          const gchar           *language_code)
+{
+       g_return_if_fail (GSPELL_IS_LANGUAGE_CHOOSER (chooser));
+
+       GSPELL_LANGUAGE_CHOOSER_GET_IFACE (chooser)->set_language_code (chooser,
+                                                                       language_code);
+}
+
 /* ex:set ts=8 noet: */
diff --git a/gspell/gspell-language-chooser.h b/gspell/gspell-language-chooser.h
index 8ce0565..682fb4c 100644
--- a/gspell/gspell-language-chooser.h
+++ b/gspell/gspell-language-chooser.h
@@ -43,13 +43,23 @@ struct _GspellLanguageChooserInterface
        void                    (* set_language)        (GspellLanguageChooser *chooser,
                                                         const GspellLanguage  *language);
 
-       gpointer padding[8];
+       const gchar *           (* get_language_code)   (GspellLanguageChooser *chooser);
+
+       void                    (* set_language_code)   (GspellLanguageChooser *chooser,
+                                                        const gchar           *language_code);
+
+       gpointer padding[12];
 };
 
-const GspellLanguage * gspell_language_chooser_get_language    (GspellLanguageChooser *chooser);
+const GspellLanguage * gspell_language_chooser_get_language            (GspellLanguageChooser *chooser);
+
+void                   gspell_language_chooser_set_language            (GspellLanguageChooser *chooser,
+                                                                        const GspellLanguage  *language);
+
+const gchar *          gspell_language_chooser_get_language_code       (GspellLanguageChooser *chooser);
 
-void                   gspell_language_chooser_set_language    (GspellLanguageChooser *chooser,
-                                                                const GspellLanguage  *language);
+void                   gspell_language_chooser_set_language_code       (GspellLanguageChooser *chooser,
+                                                                        const gchar           
*language_code);
 
 G_END_DECLS