[pangomm/pangomm-2-46] Wrap pango_shape_with_flags()

[Kjell Ahlstedt <kjellahl src gnome org>]

commit d481ec16c5158f060b3419687d63d7e675f64533
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Sat Jan 16 11:26:33 2021 +0100

    Wrap pango_shape_with_flags()
    
    * pango/src/glyphstring.[ccg|hg]: Add constructor
    GlyphString(const Glib::ustring& item_text,
    const Glib::ustring& paragraph_text, const Analysis& analysis,
    ShapeFlags flags = SHAPE_NONE).
    * pango/src/item.[ccg|hg]: Add enum ShapeFlags and
    shape(const Glib::ustring& item_text, const Glib::ustring& paragraph_text,
    ShapeFlags flags = SHAPE_NONE).
    * tools/m4/convert_pango.m4: Add conversions for ShapeFlags.
    
    See #9

 pango/src/glyphstring.ccg | 15 ++++++++++-----
 pango/src/glyphstring.hg  | 41 +++++++++++++++++++++++++++++++++++------
 pango/src/item.ccg        |  8 +++++++-
 pango/src/item.hg         | 31 ++++++++++++++++++++++++++-----
 tools/m4/convert_pango.m4 |  4 +---
 5 files changed, 79 insertions(+), 20 deletions(-)
---
diff --git a/pango/src/glyphstring.ccg b/pango/src/glyphstring.ccg
index 7a17e86..2aaf0db 100644
--- a/pango/src/glyphstring.ccg
+++ b/pango/src/glyphstring.ccg
@@ -1,8 +1,4 @@
-// -*- c++ -*-
-/* $Id: glyphstring.ccg,v 1.2 2006/05/30 17:14:21 murrayc Exp $ */
-
 /*
- *
  * Copyright 1998-2002 The gtkmm Development Team
  *
  * This library is free software; you can redistribute it and/or
@@ -30,7 +26,16 @@ GlyphString::GlyphString(const Glib::ustring& text, const Analysis& analysis)
 :
   gobject_(pango_glyph_string_new())
 {
-  pango_shape(text.c_str(), text.bytes(), const_cast<PangoAnalysis*>(analysis.gobj()), gobj());
+  pango_shape(text.c_str(), text.bytes(), analysis.gobj(), gobj());
+}
+
+GlyphString::GlyphString(const Glib::ustring& item_text, const Glib::ustring& paragraph_text,
+  const Analysis& analysis, ShapeFlags flags)
+:
+  gobject_(pango_glyph_string_new())
+{
+  pango_shape_with_flags(item_text.c_str(), item_text.bytes(), paragraph_text.c_str(),
+   paragraph_text.bytes(), analysis.gobj(), gobj(), static_cast<PangoShapeFlags>(flags));
 }
 
 Rectangle GlyphString::get_ink_extents(const Glib::RefPtr<const Font>& font) const
diff --git a/pango/src/glyphstring.hg b/pango/src/glyphstring.hg
index 56cb961..2a8820f 100644
--- a/pango/src/glyphstring.hg
+++ b/pango/src/glyphstring.hg
@@ -19,7 +19,7 @@
 
 #include <pangomm/font.h>
 #include <pangomm/glyph.h>
-#include <pangomm/item.h>
+#include <pangomm/item.h> // for Analysis and ShapeFlags
 #include <cairomm/context.h>
 #include <pango/pango-glyph.h>
 #include <pango/pango-item.h> //For PangoAnalysis.
@@ -28,7 +28,6 @@ _DEFS(pangomm,pango)
 
 namespace Pango
 {
-
 /** A Pango::GlyphString is used to store strings of glyphs with geometry and visual attribute information.
  * It can be measured or drawn to the screen.
  */
@@ -39,15 +38,45 @@ class PANGOMM_API GlyphString
   _IGNORE(pango_glyph_string_index_to_x, pango_glyph_string_x_to_index, 
pango_glyph_string_get_logical_widths)
 
 public:
-  /** Construct a string of glyphs from a string of characters.
+
+  /** Constructs a string of glyphs from a string of characters.
+   *
    * Given a segment of text and the corresponding Pango::Analysis structure
    * returned from Pango::Context::itemize(), convert the characters into glyphs.
-   * You may also pass in only a sub-string of the item.
-   * @param text The text to process. You must pass the same string into those member functions expecting a 
const Glib::ustring&.
-   * @param analysis The analysis information return from Pango::Context::itemize().
+   * You may also pass in only a substring of the item.
+   *
+   * It is recommended that you use the constructor with @a item_text and
+   * @a paragraph_text parameters instead, since that API allows for shaping
+   * interaction happening across text item boundaries.
+   *
+   * @param text The text to process. You must pass the same string into those
+   *             member functions expecting a const Glib::ustring&.
+   * @param analysis The analysis information returned from Pango::Context::itemize().
    */
   GlyphString(const Glib::ustring& text, const Analysis& analysis);
 
+  /** Constructs a string of glyphs from a string of characters.
+   *
+   * Given a segment of text and the corresponding Pango::Analysis structure
+   * returned from Pango::Context::itemize(), convert the characters into glyphs.
+   * You may also pass in only a substring of the item.
+   *
+   * This is similar to the constructor with only one @a text parameter, except
+   * it also takes @a flags and the full paragraph text as input, which will then
+   * be used to perform certain cross-item shaping interactions. If you have
+   * access to the broader text of which @a item_text is a part, provide the
+   * broader text as @a paragraph_text.
+   *
+   * @newin{2,46}
+   *
+   * @param item_text Valid UTF-8 text to shape.
+   * @param paragraph_text Text of the paragraph (see details).
+   * @param analysis The analysis information returned from Pango::Context::itemize().
+   * @param flags Flags influencing the shaping process.
+   */
+  GlyphString(const Glib::ustring& item_text, const Glib::ustring& paragraph_text,
+    const Analysis& analysis, ShapeFlags flags = SHAPE_NONE);
+
   _WRAP_METHOD(void set_size (int new_len), pango_glyph_string_set_size)
 
   _WRAP_METHOD(void get_extents(const Glib::RefPtr<const Font>& font, Rectangle& ink_rect, Rectangle& 
logical_rect) const, pango_glyph_string_extents)
diff --git a/pango/src/item.ccg b/pango/src/item.ccg
index f948a56..b2bb88f 100644
--- a/pango/src/item.ccg
+++ b/pango/src/item.ccg
@@ -15,6 +15,7 @@
  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
+#include <pango/pango-enum-types.h> // for pango_shape_flags_get_type()
 #include <pangomm/font.h>
 #include <pangomm/attributes.h>
 #include <pangomm/glyphstring.h>
@@ -99,6 +100,12 @@ Pango::GlyphString Item::shape(const Glib::ustring& text) const
   return GlyphString(text, get_analysis());
 }
 
+Pango::GlyphString Item::shape(const Glib::ustring& item_text,
+  const Glib::ustring& paragraph_text, ShapeFlags flags) const
+{
+  return GlyphString(item_text, paragraph_text, get_analysis(), flags);
+}
+
 } /* namespace Pango */
 
 
@@ -121,4 +128,3 @@ Pango::Item wrap(PangoItem* object, bool take_copy)
 }
 
 } /* namespace Glib */
-
diff --git a/pango/src/item.hg b/pango/src/item.hg
index eaa4186..1e2b300 100644
--- a/pango/src/item.hg
+++ b/pango/src/item.hg
@@ -24,12 +24,13 @@ _DEFS(pangomm,pango)
 
 namespace Pango
 {
+_WRAP_ENUM(ShapeFlags, PangoShapeFlags, newin "2,46", decl_prefix PANGOMM_API)
 
 class PANGOMM_API Font;
 class PANGOMM_API GlyphString;
 
-/** A Pango::Analysis stores information about the properties of a segment of text.
- * Pango::Analysis is used as an output type only so there is no public default constructor.
+/** A %Pango::Analysis stores information about the properties of a segment of text.
+ * %Pango::Analysis is used as an output type only so there is no public default constructor.
  * You can retrieve an object of this type from an object of type Pango::Item by
  * calling Pango::Item::get_analysis(). Objects of this class can be used for some
  * calculations in Pango::GlyphString.
@@ -135,12 +136,33 @@ public:
    */
   Glib::ustring get_segment(const Glib::ustring& text) const;
 
-  /** Convert a segment of text into a string of glyphs.
-   * @param text The text to process. This must either be the whole segment of text that corresponds to the 
item as returned by get_segment() or a sub-string of that segment. You need to pass the same text to the 
member functions of Pango::GlyphString for further calculations.
+  /** Converts a segment of text into a string of glyphs.
+   *
+   * @param text The text to process. This must either be the whole segment of text
+   *             that corresponds to the item as returned by get_segment() or a
+   *             substring of that segment. You need to pass the same text to
+   *             the member functions of Pango::GlyphString for further calculations.
    * @return A Pango::GlyphString object that can be measured or drawn.
    */
   GlyphString shape(const Glib::ustring& text) const;
 
+  /** Converts a segment of text into a string of glyphs.
+   *
+   * @newin{2,46}
+   *
+   * @param item_text The text to process. This must either be the whole segment of text
+   *             that corresponds to the item as returned by get_segment() or a
+   *             substring of that segment. You need to pass the same text to
+   *             the member functions of Pango::GlyphString for further calculations.
+   * @param paragraph_text Text of the paragraph. See GlyphString::GlyphString(
+   *        const Glib::ustring& item_text, const Glib::ustring& paragraph_text,
+   *        const Analysis& analysis, ShapeFlags flags).
+   * @param flags Flags influencing the shaping process.
+   * @return A Pango::GlyphString object that can be measured or drawn.
+   */
+  GlyphString shape(const Glib::ustring& item_text, const Glib::ustring& paragraph_text,
+    ShapeFlags flags = SHAPE_NONE) const;
+
   /// Provides access to the underlying C GObject.  
   PangoItem*       gobj()       { return gobject_; }
   /// Provides access to the underlying C GObject.
@@ -183,4 +205,3 @@ PANGOMM_API
 Pango::Item wrap(PangoItem* object, bool take_copy=true);
 
 } // namespace Glib
-
diff --git a/tools/m4/convert_pango.m4 b/tools/m4/convert_pango.m4
index 6a9e4a1..cc4d4da 100644
--- a/tools/m4/convert_pango.m4
+++ b/tools/m4/convert_pango.m4
@@ -19,13 +19,13 @@ _CONV_ENUM(Pango,EllipsizeMode)
 _CONV_ENUM(Pango,RenderPart)
 _CONV_ENUM(Pango,Gravity)
 _CONV_ENUM(Pango,GravityHint)
+_CONV_ENUM(Pango,ShapeFlags)
 
 # General conversions:
 _CONVERSION(`gchar*',`const char*',`($3)')
 _CONVERSION(`guchar*&',`guchar**',`&($3)')
 _CONVERSION(`int*&',`int**',`&($3)')
 
-
 # Wrapper type conversions:
 _CONVERSION(`PangoLanguage*',`Language',`Language($3)')
 _CONVERSION(`PangoLanguage*',`Pango::Language',`Pango::Language($3)')
@@ -175,5 +175,3 @@ _CONVERSION(`GSList*',`SListHandle_ConstLayoutLine',__FL2H_SHALLOW)
 _CONVERSION(`const Cairo::FontOptions&',`const cairo_font_options_t*',`($3).cobj()')
 
 _CONVERSION(`const LogAttr&',`PangoLogAttr*',&(const_cast<LogAttr&>($3)))
-
-