Change PANGO_GLYPH_EMPTY to 0x0FFFFFFF, to not overlap with

2006-02-04  Behdad Esfahbod  <behdad@gnome.org>

        * pango/pango-types.h: Change PANGO_GLYPH_EMPTY to 0x0FFFFFFF, to
        not overlap with PANGO_GLYPH_UNKNOWN_FLAG (0x10000000).
        Define PANGO_GET_UNKNOWN_GLYPH(wc) that simply returns
        wc|PANGO_GLYPH_UNKNOWN_FLAG.

        * docs/pango-sections.txt, docs/tmpl/glyphs.sgml: Document new
        symbols.

        * modules/*/*.c: Use PANGO_GET_UNKNOWN_GLYPH instead of various
        backend-specific functions.

        * pango/pangofc-font.c, pango/pangoft.c, pango/pangoxft-font.c,
        * pango/pangowin32.c, pango/pangox.c: Suggest using
        PANGO_GET_UNKNOWN_GLYPH in docs.

        * pango/pangofc-font.h: Deprecate pango_fc_font_get_unknown_glyph().

        * pango/pangowin32.h: Deprecate pango_win32_get_unknown_glyph().

8 files changed, 27 insertions, 17 deletions

diff --git a/pango/pango-types.h b/pango/pango-types.h
index c93daf4d..7d12dac0 100644
--- a/pango/pango-types.h
+++ b/pango/pango-types.h
@@ -45,8 +45,9 @@ typedef struct _PangoLanguage PangoLanguage;
  */
 typedef guint32 PangoGlyph;
 
-#define PANGO_GLYPH_UNKNOWN_FLAG ((PangoGlyph)0x10000000)
-#define PANGO_GLYPH_EMPTY        ((PangoGlyph)0xFFFFFFFF)
+#define PANGO_GLYPH_EMPTY           ((PangoGlyph)0x0FFFFFFF)
+#define PANGO_GLYPH_UNKNOWN_FLAG    ((PangoGlyph)0x10000000)
+#define PANGO_GET_UNKNOWN_GLYPH(wc) ((PangoGlyph)(wc)|PANGO_GLYPH_UNKNOWN_FLAG)
 
 /* A rectangle. Used to store logical and physical extents of glyphs,
  * runs, strings, etc.
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index a14dd43a..5bea0e81 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -632,6 +632,8 @@ pango_fc_font_get_glyph (PangoFcFont *font,
  * Returns the index of a glyph suitable for drawing @wc as an
  * unknown character.
  *
+ * Use PANGO_GET_UNKNOWN_GLYPH() instead.
+ *
  * Return value: a glyph index into @font.
  *
  * Since: 1.4
@@ -640,12 +642,10 @@ PangoGlyph
 pango_fc_font_get_unknown_glyph (PangoFcFont *font,
 				 gunichar     wc)
 {
-  g_return_val_if_fail (PANGO_IS_FC_FONT (font), 0);
-
-  if (PANGO_FC_FONT_GET_CLASS (font)->get_unknown_glyph)
+  if (font && PANGO_FC_FONT_GET_CLASS (font)->get_unknown_glyph)
     return PANGO_FC_FONT_GET_CLASS (font)->get_unknown_glyph (font, wc);
 
-  return PANGO_GLYPH_UNKNOWN_FLAG | (PangoGlyph)wc;
+  return PANGO_GET_UNKNOWN_GLYPH (wc);
 }
 
 void
diff --git a/pango/pangofc-font.h b/pango/pangofc-font.h
index 198fb7c6..7b5bc4a3 100644
--- a/pango/pangofc-font.h
+++ b/pango/pangofc-font.h
@@ -96,6 +96,7 @@ struct _PangoFcFont
  * @get_unknown_glyph: Gets the glyph that should be used to
  *   display an unknown-glyph indication for the specified
  *   Unicode character.
+ *   May be %NULL.
  * @shutdown: Performs any font-specific shutdown code that
  *   needs to be done when pango_fc_font_map_shutdown is called.
  *   May be %NULL.
@@ -132,8 +133,10 @@ gboolean   pango_fc_font_has_char          (PangoFcFont      *font,
 					    gunichar          wc);
 guint      pango_fc_font_get_glyph         (PangoFcFont      *font,
 					    gunichar          wc);
+#ifndef PANGO_DISABLE_DEPRECATED
 PangoGlyph pango_fc_font_get_unknown_glyph (PangoFcFont      *font,
 					    gunichar          wc);
+#endif /* PANGO_DISABLE_DEPRECATED */
 void       pango_fc_font_kern_glyphs       (PangoFcFont      *font,
 					    PangoGlyphString *glyphs);
 
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index 901cd99a..be53cac4 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -470,10 +470,12 @@ pango_ft2_font_get_coverage (PangoFont     *font,
  * pango_ft2_get_unknown_glyph:
  * @font: a #PangoFont
  * 
- * Return the index of a glyph suitable for drawing unknown characters,
- * or %PANGO_GLYPH_EMPTY if no suitable glyph found.
+ * Return the index of a glyph suitable for drawing unknown characters with
+ * @font, or %PANGO_GLYPH_EMPTY if no suitable glyph found.
  * 
- * For most uses, pango_fc_font_get_unknown_glyph() should be used instead.
+ * If you want to draw an unknown-box for a character that is not covered
+ * by the font,
+ * use PANGO_GET_UNKNOWN_GLYPH() instead.
  * 
  * Return value: a glyph index into @font, or %PANGO_GLYPH_EMPTY
  **/
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index e3af31c7..28e60718 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -860,6 +860,8 @@ pango_win32_font_find_shaper (PangoFont     *font,
  * 
  * Returns the index of a glyph suitable for drawing @wc as an
  * unknown character.
+ *
+ * Use PANGO_GET_UNKNOWN_GLYPH() instead.
  * 
  * Return value: a glyph index into @font
  **/
@@ -867,7 +869,7 @@ PangoGlyph
 pango_win32_get_unknown_glyph (PangoFont *font,
 			       gunichar   wc)
 {
-  return wc | PANGO_GLYPH_UNKNOWN_FLAG;
+  return PANGO_GET_UNKNOWN_GLYPH (wc);
 }
 
 /**
diff --git a/pango/pangowin32.h b/pango/pangowin32.h
index 5a08f002..6f025d7a 100644
--- a/pango/pangowin32.h
+++ b/pango/pangowin32.h
@@ -69,8 +69,10 @@ void           pango_win32_render_transformed (HDC         hdc,
 /* For shape engines
  */
 
+#ifndef PANGO_DISABLE_DEPRECATED
 PangoGlyph     pango_win32_get_unknown_glyph  (PangoFont        *font,
 					       gunichar          wc);
+#endif /* PANGO_DISABLE_DEPRECATED */
 gint	      pango_win32_font_get_glyph_index(PangoFont        *font,
 					       gunichar          wc);
 
diff --git a/pango/pangox.c b/pango/pangox.c
index 06694713..0070c28b 100644
--- a/pango/pangox.c
+++ b/pango/pangox.c
@@ -1396,7 +1396,7 @@ pango_x_find_glyph (PangoFont *font,
  * @font: a #PangoFont.
  * 
  * Returns the index of a glyph suitable for drawing unknown characters;
- * you should generally use pango_x_font_get_unknown_glyph_instead,
+ * you should generally use PANGO_GET_UNKNOWN_GLYPH() instead,
  * since that may return a glyph that provides a better representation
  * of a particular char. (E.g., by showing hex digits, or a glyph
  * representive of a certain Unicode range.)
@@ -1406,7 +1406,7 @@ pango_x_find_glyph (PangoFont *font,
 PangoGlyph
 pango_x_get_unknown_glyph (PangoFont *font)
 {
-  return PANGO_GLYPH_UNKNOWN_FLAG;
+  return PANGO_GET_UNKNOWN_GLYPH (0);
 }
 
 /**
@@ -1744,13 +1744,13 @@ pango_x_fallback_shape (PangoFont        *font,
  * Returns the index of a glyph suitable for drawing @wc as an
  * unknown character.
  *
+ * Use PANGO_GET_UNKNOWN_GLYPH() instead.
+ *
  * Return value: a glyph index into @font.
  */
 PangoGlyph
 pango_x_font_get_unknown_glyph (PangoFont *font,
                                 gunichar   wc)
 {
-  g_return_val_if_fail (PANGO_IS_FONT (font), 0);
-
-  return PANGO_GLYPH_UNKNOWN_FLAG | wc;
+  return PANGO_GET_UNKNOWN_GLYPH (wc);
 }
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index 2e96c1f4..3df873b6 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -511,7 +511,7 @@ pango_xft_font_get_display (PangoFont *font)
  * Returns the index of a glyph suitable for drawing @wc as an
  * unknown character.
  *
- * Use pango_fc_font_get_unknown_glyph() instead.
+ * Use PANGO_GET_UNKNOWN_GLYPH() instead.
  *
  * Return value: a glyph index into @font.
  **/
@@ -519,7 +519,7 @@ PangoGlyph
 pango_xft_font_get_unknown_glyph (PangoFont *font,
 				  gunichar   wc)
 {
-  g_return_val_if_fail (PANGO_XFT_IS_FONT (font), -1);
+  g_return_val_if_fail (PANGO_XFT_IS_FONT (font), PANGO_GLYPH_EMPTY);
 
   return pango_fc_font_get_unknown_glyph (PANGO_FC_FONT (font), wc);
 }