GNOME.org
 

pango r2693 - in trunk: . docs docs/tmpl pango

Author: behdad
Date: Wed Aug 20 03:07:28 2008
New Revision: 2693
URL: http://svn.gnome.org/viewvc/pango?rev=2693&view=rev

Log:
2008-08-18  Behdad Esfahbod  <behdad gnome org>

        Bug 473805 â Add API enumerating scripts for a language

        * docs/Makefile.am:
        * docs/pango-sections.txt:
        * docs/tmpl/scripts.sgml:
        * docs/tmpl/text-attributes.sgml:
        * docs/tmpl/utils.sgml:
        * pango/pango-language.c (pango_language_get_scripts),
        (pango_language_includes_script),
        (pango_script_get_sample_language):
        * pango/pango-language.h:
        * pango/pango-script.c:
        * pango/pango.def:
        Add a minor new public API:

                pango_language_get_scripts()

        This is what pango_language_includes_script() has been using
        internally.  Previously one had to call that function over all
        possible script values to determine which scripts a language
        uses.  The new API makes that much easier.

Modified:
   trunk/ChangeLog
   trunk/docs/Makefile.am
   trunk/docs/pango-sections.txt
   trunk/docs/tmpl/scripts.sgml
   trunk/docs/tmpl/text-attributes.sgml
   trunk/docs/tmpl/utils.sgml
   trunk/pango/pango-language.c
   trunk/pango/pango-language.h
   trunk/pango/pango-script.c
   trunk/pango/pango.def

Modified: trunk/docs/Makefile.am
==============================================================================
--- trunk/docs/Makefile.am	(original)
+++ trunk/docs/Makefile.am	Wed Aug 20 03:07:28 2008
@@ -40,7 +40,8 @@
 	pangoatsui-private.h	\
 	pangox-private.h	\
 	pangoxft-private.h	\
-	pango-ot-private.h
+	pango-ot-private.h	\
+	pango-script-lang-table.h
 
 # CFLAGS and LDFLAGS for compiling scan program. Only needed
 # if $(DOC_MODULE).types is non-empty.

Modified: trunk/docs/pango-sections.txt
==============================================================================
--- trunk/docs/pango-sections.txt	(original)
+++ trunk/docs/pango-sections.txt	Wed Aug 20 03:07:28 2008
@@ -374,11 +374,6 @@
 pango_color_copy
 pango_color_free
 pango_color_to_string
-PangoLanguage
-PANGO_TYPE_LANGUAGE
-pango_language_from_string
-pango_language_to_string
-pango_language_matches
 <SUBSECTION>
 PangoAttrList
 PANGO_TYPE_ATTR_LIST
@@ -406,7 +401,6 @@
 pango_attr_list_get_type
 pango_underline_get_type
 pango_color_get_type
-pango_language_get_type
 </SECTION>
 
 <SECTION>
@@ -557,21 +551,29 @@
 </SECTION>
 
 <SECTION>
-<TITLE>Scripts</TITLE>
+<TITLE>Scripts and Languages</TITLE>
 <FILE>scripts</FILE>
-PangoScriptIter
 PangoScript
 PANGO_TYPE_SCRIPT
+PangoScriptIter
 pango_script_for_unichar
 pango_script_get_sample_language
-pango_language_includes_script
 pango_script_iter_new
 pango_script_iter_get_range
 pango_script_iter_next
 pango_script_iter_free
+PangoLanguage
+PANGO_TYPE_LANGUAGE
+pango_language_from_string
+pango_language_to_string
+pango_language_matches
+pango_language_includes_script
+pango_language_get_scripts
+pango_language_get_default
+pango_language_get_sample_string
 <SUBSECTION Private>
 pango_script_get_type
-PangoScriptForLang
+pango_language_get_type
 </SECTION>
 
 <SECTION>
@@ -1057,8 +1059,6 @@
 pango_get_sysconf_subdirectory
 pango_get_lib_subdirectory
 pango_log2vis_get_embedding_levels
-pango_language_get_default
-pango_language_get_sample_string
 pango_is_zero_width
 pango_quantize_line_geometry
 </SECTION>

Modified: trunk/docs/tmpl/scripts.sgml
==============================================================================
--- trunk/docs/tmpl/scripts.sgml	(original)
+++ trunk/docs/tmpl/scripts.sgml	Wed Aug 20 03:07:28 2008
@@ -19,12 +19,6 @@
 <!-- ##### SECTION Stability_Level ##### -->
 
 
-<!-- ##### STRUCT PangoScriptIter ##### -->
-<para>
-
-</para>
-
-
 <!-- ##### ENUM PangoScript ##### -->
 <para>
 The #PangoScript enumeration identifies different writing
@@ -125,30 +119,26 @@
 
 
 
-<!-- ##### FUNCTION pango_script_for_unichar ##### -->
+<!-- ##### STRUCT PangoScriptIter ##### -->
 <para>
 
 </para>
 
- ch: 
- Returns: 
-
 
-<!-- ##### FUNCTION pango_script_get_sample_language ##### -->
+<!-- ##### FUNCTION pango_script_for_unichar ##### -->
 <para>
 
 </para>
 
- script: 
+ ch: 
 @Returns: 
 
 
-<!-- ##### FUNCTION pango_language_includes_script ##### -->
+<!-- ##### FUNCTION pango_script_get_sample_language ##### -->
 <para>
 
 </para>
 
- language: 
 @script: 
 @Returns: 
 
@@ -191,3 +181,86 @@
 @iter: 
 
 
+<!-- ##### STRUCT PangoLanguage ##### -->
+<para>
+The #PangoLanguage structure is used to
+represent a language.
+</para>
+<para>
+#PangoLanguage pointers can be efficiently 
+copied and compared with each other.
+</para>
+
+
+<!-- ##### MACRO PANGO_TYPE_LANGUAGE ##### -->
+<para>
+The #GObject type for #PangoLanguage. 
+</para>
+
+
+
+<!-- ##### FUNCTION pango_language_from_string ##### -->
+<para>
+
+</para>
+
+ language: 
+ Returns: 
+
+
+<!-- ##### FUNCTION pango_language_to_string ##### -->
+<para>
+
+</para>
+
+ language: 
+ Returns: 
+
+
+<!-- ##### FUNCTION pango_language_matches ##### -->
+<para>
+
+</para>
+
+ language: 
+ range_list: 
+ Returns: 
+
+
+<!-- ##### FUNCTION pango_language_includes_script ##### -->
+<para>
+
+</para>
+
+ language: 
+ script: 
+ Returns: 
+
+
+<!-- ##### FUNCTION pango_language_get_scripts ##### -->
+<para>
+
+</para>
+
+ language: 
+ num_scripts: 
+ Returns: 
+
+
+<!-- ##### FUNCTION pango_language_get_default ##### -->
+<para>
+
+</para>
+
+ Returns: 
+
+
+<!-- ##### FUNCTION pango_language_get_sample_string ##### -->
+<para>
+
+</para>
+
+ language: 
+ Returns: 
+
+

Modified: trunk/docs/tmpl/text-attributes.sgml
==============================================================================
--- trunk/docs/tmpl/text-attributes.sgml	(original)
+++ trunk/docs/tmpl/text-attributes.sgml	Wed Aug 20 03:07:28 2008
@@ -605,52 +605,6 @@
 @Returns: 
 
 
-<!-- ##### STRUCT PangoLanguage ##### -->
-<para>
-The #PangoLanguage structure is used to
-represent a language.
-</para>
-<para>
-#PangoLanguage pointers can be efficiently 
-copied and compared with each other.
-</para>
-
-
-<!-- ##### MACRO PANGO_TYPE_LANGUAGE ##### -->
-<para>
-The #GObject type for #PangoLanguage. 
-</para>
-
-
-
-<!-- ##### FUNCTION pango_language_from_string ##### -->
-<para>
-
-</para>
-
- language: 
- Returns: 
-
-
-<!-- ##### FUNCTION pango_language_to_string ##### -->
-<para>
-
-</para>
-
- language: 
- Returns: 
-
-
-<!-- ##### FUNCTION pango_language_matches ##### -->
-<para>
-
-</para>
-
- language: 
- range_list: 
- Returns: 
-
-
 <!-- ##### STRUCT PangoAttrList ##### -->
 <para>
 The #PangoAttrList structure represents a list of attributes

Modified: trunk/docs/tmpl/utils.sgml
==============================================================================
--- trunk/docs/tmpl/utils.sgml	(original)
+++ trunk/docs/tmpl/utils.sgml	Wed Aug 20 03:07:28 2008
@@ -188,23 +188,6 @@
 @Returns: 
 
 
-<!-- ##### FUNCTION pango_language_get_default ##### -->
-<para>
-
-</para>
-
- Returns: 
-
-
-<!-- ##### FUNCTION pango_language_get_sample_string ##### -->
-<para>
-
-</para>
-
- language: 
- Returns: 
-
-
 <!-- ##### FUNCTION pango_is_zero_width ##### -->
 <para>
 

Modified: trunk/pango/pango-language.c
==============================================================================
--- trunk/pango/pango-language.c	(original)
+++ trunk/pango/pango-language.c	Wed Aug 20 03:07:28 2008
@@ -421,6 +421,14 @@
   return result;
 }
 
+
+
+
+/*
+ * From language to script
+ */
+
+
 #include "pango-script-lang-table.h"
 
 static int
@@ -434,41 +442,47 @@
 }
 
 /**
- * pango_language_includes_script:
+ * pango_language_get_scripts:
  * @language: a #PangoLanguage, or %NULL
- * @script: a #PangoScript
+ * @num_scripts: location to return number of scripts, or %NULL
  *
- * Determines if @script is one of the scripts used to
- * write @language. The returned value is conservative;
- * if nothing is known about the language tag @language,
- * %TRUE will be returned, since, as far as Pango knows,
- * @script might be used to write @language.
+ * Determines the scripts used to to write @language.
+ * If nothing is known about the language tag @language,
+ * or if @language is %NULL, then %NULL is returned.
+ * The list of scripts returned starts with the script that the
+ * language uses most and continues to the one it uses least.
  *
- * This routine is used in Pango's itemization process when
- * determining if a supplied language tag is relevant to
- * a particular section of text. It probably is not useful for
- * applications in most circumstances.
+ * The value @num_script points at will be set to the number
+ * of scripts in the returned array (or zero if %NULL is returned).
  *
- * Return value: %TRUE if @script is one of the scripts used
- * to write @language or if nothing is known about @language
- * (including the case that @language is %NULL),
- * %FALSE otherwise.
+ * Most languages use only one script for writing, but there are
+ * some that use two (Latin and Cyrillic for example), and a few
+ * use three (Japanese for example).  Applications should not make
+ * any assumptions on the maximum number of scripts returned
+ * though, except that it is a small number.
+ *
+ * The pango_language_includes_script() uses this function
+ * internally.
+ *
+ * Return value: An array of #PangoScript values, with the
+ * number of entries in the array stored in @num_scripts, or
+ * %NULL if Pango does not have any information about this
+ * particular language tag (also the case if @language is %NULL).
+ * The returned array is owned by Pango and should not be modified
+ * or freed.
  
- * Since: 1.4
+ * Since: 1.22
  **/
-gboolean
-pango_language_includes_script (PangoLanguage *language,
-				PangoScript    script)
+G_CONST_RETURN PangoScript *
+pango_language_get_scripts (PangoLanguage *language,
+			    int           *num_scripts)
 {
   PangoScriptForLang *script_for_lang;
   unsigned int j;
   const char *lang_str;
 
-#define REAL_SCRIPT(script) \
-  ((script) > PANGO_SCRIPT_INHERITED)
-
-  if (language == NULL || !REAL_SCRIPT (script))
-    return TRUE;
+  if (language == NULL)
+    goto NOT_FOUND;
 
   lang_str = pango_language_to_string (language);
 
@@ -482,7 +496,7 @@
 			     sizeof (PangoScriptForLang),
 			     script_for_lang_compare);
   if (!script_for_lang)
-    return TRUE;
+    goto NOT_FOUND;
   else
     {
       gboolean found = FALSE;
@@ -508,16 +522,90 @@
 	}
 
       if (!found)
-        return TRUE;
+        goto NOT_FOUND;
+    }
+
+  if (num_scripts)
+    {
+      for (j = 0; j < G_N_ELEMENTS (script_for_lang->scripts); j++)
+	if (script_for_lang->scripts[j] == 0)
+	  break;
+
+      g_assert (j > 0);
+
+      *num_scripts = j;
     }
 
-  for (j = 0; j < G_N_ELEMENTS (script_for_lang->scripts); j++)
-    if (script_for_lang->scripts[j] == script)
+  return script_for_lang->scripts;
+
+ NOT_FOUND:
+
+  if (num_scripts)
+    *num_scripts = 0;
+
+  return NULL;
+}
+
+/**
+ * pango_language_includes_script:
+ * @language: a #PangoLanguage, or %NULL
+ * @script: a #PangoScript
+ *
+ * Determines if @script is one of the scripts used to
+ * write @language. The returned value is conservative;
+ * if nothing is known about the language tag @language,
+ * %TRUE will be returned, since, as far as Pango knows,
+ * @script might be used to write @language.
+ *
+ * This routine is used in Pango's itemization process when
+ * determining if a supplied language tag is relevant to
+ * a particular section of text. It probably is not useful for
+ * applications in most circumstances.
+ *
+ * This function uses pango_language_get_scripts() internally.
+ *
+ * Return value: %TRUE if @script is one of the scripts used
+ * to write @language or if nothing is known about @language
+ * (including the case that @language is %NULL),
+ * %FALSE otherwise.
+ 
+ * Since: 1.4
+ **/
+gboolean
+pango_language_includes_script (PangoLanguage *language,
+				PangoScript    script)
+{
+  const PangoScript *scripts;
+  int num_scripts, j;
+
+/* copied from the one in pango-script.c */
+#define REAL_SCRIPT(script) \
+  ((script) > PANGO_SCRIPT_INHERITED && (script) != PANGO_SCRIPT_UNKNOWN)
+
+  if (!REAL_SCRIPT (script))
+    return TRUE;
+
+#undef REAL_SCRIPT
+
+  scripts = pango_language_get_scripts (language, &num_scripts);
+  if (!scripts)
+    return TRUE;
+
+  for (j = 0; j < num_scripts; j++)
+    if (scripts[j] == script)
       return TRUE;
 
   return FALSE;
 }
 
+
+
+
+/*
+ * From script to language
+ */
+
+
 static PangoLanguage **
 parse_default_languages (void)
 {
@@ -645,6 +733,8 @@
    * to include the script, so alternate orthographies
    * (Shavian for English, Osmanya for Somali, etc), typically
    * have no sample language
+   *
+   * XXX Add a test to check the above invariant.
    */
   static const char sample_languages[][4] = {
     "",    /* PANGO_SCRIPT_COMMON */

Modified: trunk/pango/pango-language.h
==============================================================================
--- trunk/pango/pango-language.h	(original)
+++ trunk/pango/pango-language.h	Wed Aug 20 03:07:28 2008
@@ -35,6 +35,7 @@
 PangoLanguage *pango_language_from_string (const char *language);
 
 G_CONST_RETURN char *pango_language_to_string   (PangoLanguage *language) G_GNUC_CONST;
+/* For back compat.  Will have to keep indefinitely. */
 #define pango_language_to_string(language) ((const char *)language)
 
 G_CONST_RETURN char *pango_language_get_sample_string (PangoLanguage *language) G_GNUC_CONST;
@@ -45,8 +46,10 @@
 
 #include <pango/pango-script.h>
 
-gboolean       pango_language_includes_script   (PangoLanguage *language,
-						 PangoScript    script) G_GNUC_PURE;
+gboolean		    pango_language_includes_script (PangoLanguage *language,
+							    PangoScript    script) G_GNUC_PURE;
+G_CONST_RETURN PangoScript *pango_language_get_scripts	   (PangoLanguage *language,
+							    int           *num_scripts);
 
 G_END_DECLS
 

Modified: trunk/pango/pango-script.c
==============================================================================
--- trunk/pango/pango-script.c	(original)
+++ trunk/pango/pango-script.c	Wed Aug 20 03:07:28 2008
@@ -228,6 +228,7 @@
   return -1;
 }
 
+/* duplicated in pango-language.c */
 #define REAL_SCRIPT(script) \
   ((script) > PANGO_SCRIPT_INHERITED && (script) != PANGO_SCRIPT_UNKNOWN)
 

Modified: trunk/pango/pango.def
==============================================================================
--- trunk/pango/pango.def	(original)
+++ trunk/pango/pango.def	Wed Aug 20 03:07:28 2008
@@ -219,6 +219,7 @@
 	pango_language_from_string
 	pango_language_get_default
 	pango_language_get_sample_string
+	pango_language_get_scripts
 	pango_language_get_type
 	pango_language_includes_script
 	pango_language_matches
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]