[pangomm/pangomm-2-46] Layout: Add get_const_line() and get_const_lines()

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 32c6a770d0947a70c413fadbdc18f7999efedab0
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Sun Jan 17 18:32:55 2021 +0100

    Layout: Add get_const_line() and get_const_lines()
    
    Fixes #10

 pango/src/layout.hg | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)
---
diff --git a/pango/src/layout.hg b/pango/src/layout.hg
index 7822fef..5d1b522 100644
--- a/pango/src/layout.hg
+++ b/pango/src/layout.hg
@@ -237,14 +237,81 @@ public:
   _WRAP_METHOD(int get_line_count() const, pango_layout_get_line_count)
   
   //Note that the const version uses a different (faster) C function:
+  /** Retrieves a particular line from a Pango::Layout.
+   *
+   * Use the faster get_const_line() if you do not plan
+   * to modify the contents of the line (glyphs, glyph widths, etc.).
+   *
+   * @param line The index of a line, which must be between 0 and
+   * <tt>get_line_count() - 1</tt>, inclusive.
+   * @return The requested Pango::LayoutLine, or an empty RefPtr if the index
+   * is out of range. This layout line will become invalid if changes are made
+   * to the Pango::Layout.
+   */
   _WRAP_METHOD(Glib::RefPtr<LayoutLine> get_line(int line), pango_layout_get_line, refreturn)
-  _WRAP_METHOD(Glib::RefPtr<const LayoutLine> get_line(int line) const, pango_layout_get_line_readonly, 
refreturn) 
+
+  /** Retrieves a particular line from a Pango::Layout.
+   *
+   * @param line The index of a line, which must be between 0 and
+   * <tt>get_line_count() - 1</tt>, inclusive.
+   * @return The requested Pango::LayoutLine, or an empty RefPtr if the index
+   * is out of range. This layout line will become invalid if changes are made
+   * to the Pango::Layout. No changes should be made to the line.
+   */
+  _WRAP_METHOD(Glib::RefPtr<const LayoutLine> get_line(int line) const, pango_layout_get_line_readonly, 
refreturn)
+
+  /** Retrieves a particular line from a Pango::Layout.
+   *
+   * This is a faster alternative to get_line(), but the user is not expected
+   * to modify the contents of the line (glyphs, glyph widths, etc.).
+   *
+   * @newin{2,46}
+   *
+   * @param line The index of a line, which must be between 0 and
+   * <tt>get_line_count() - 1</tt>, inclusive.
+   * @return The requested Pango::LayoutLine, or an empty RefPtr if the index
+   * is out of range. This layout line will become invalid if changes are made
+   * to the Pango::Layout. No changes should be made to the line.
+   */
+  _WRAP_METHOD(Glib::RefPtr<const LayoutLine> get_const_line(int line) const, 
pango_layout_get_line_readonly, refreturn)
 
 #m4 _CONVERSION(`GSList*',`SListHandle_LayoutLine',`$2($3, Glib::OWNERSHIP_NONE)')
 #m4 _CONVERSION(`GSList*',`SListHandle_ConstLayoutLine',`$2($3, Glib::OWNERSHIP_NONE)')
   //Note that the const version uses a different (faster) C function:
+  /** Returns the lines of the layout as a list.
+   *
+   * Use the faster get_const_lines() if you do not plan
+   * to modify the contents of the lines (glyphs, glyph widths, etc.).
+   *
+   * @return A Glib::SListHandle containing
+   * the lines in the layout. This points to internal data of the Pango::Layout
+   * and must be used with care. It will become invalid on any change to the layout's
+   * text or properties.
+   */
   _WRAP_METHOD(SListHandle_LayoutLine get_lines(), pango_layout_get_lines)
+
+  /** Returns the lines of the layout as a list.
+   *
+   * @return A Glib::SListHandle containing
+   * the lines in the layout. This points to internal data of the Pango::Layout and
+   * must be used with care. It will become invalid on any change to the layout's
+   * text or properties. No changes should be made to the lines.
+   */
   _WRAP_METHOD(SListHandle_ConstLayoutLine get_lines() const, pango_layout_get_lines_readonly)
+
+  /** Returns the lines of the layout as a list.
+   *
+   * This is a faster alternative to get_lines(), but the user is not expected
+   * to modify the contents of the lines (glyphs, glyph widths, etc.).
+   *
+   * @newin{2,46}
+   *
+   * @return A Glib::SListHandle containing
+   * the lines in the layout. This points to internal data of the Pango::Layout and
+   * must be used with care. It will become invalid on any change to the layout's
+   * text or properties. No changes should be made to the lines.
+   */
+  _WRAP_METHOD(SListHandle_ConstLayoutLine get_const_lines() const, pango_layout_get_lines_readonly)
   
 _DEPRECATE_IFDEF_START
   /** Gets an iterator to iterate over the visual extents of the layout.