[atk: 1/2] atktext: Add ScrollSubstringTo and ScrollSubstringToPoint text interfaces

[Samuel Thibault <sthibaul src gnome org>]

commit 1eab7ef4ed9d3d1a1e9a46b555a494ae10c52c22
Author: Samuel Thibault <samuel thibault ens-lyon org>
Date:   Wed Jun 27 15:53:15 2018 +0200

    atktext: Add ScrollSubstringTo and ScrollSubstringToPoint text interfaces

 NEWS                  |  8 ++++++
 atk/atktext.c         | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++
 atk/atktext.h         | 36 ++++++++++++++++++++++++++
 docs/atk-sections.txt |  2 ++
 4 files changed, 116 insertions(+)
---
diff --git a/NEWS b/NEWS
index e5641b3..ce519e3 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,11 @@
+Changes in version 2.31.1
+=========================
+
+* Add ScrollSubstringTo and ScrollSubstringToPoint methods to AtkText
+
+Contributors:
+   Samuel Thibault
+
 Changes in version 2.29.94
 ==========================
 
diff --git a/atk/atktext.c b/atk/atktext.c
index ca64c96..f10885d 100644
--- a/atk/atktext.c
+++ b/atk/atktext.c
@@ -1358,6 +1358,76 @@ atk_text_rectangle_contain (AtkTextRectangle *clip,
   
 }
 
+/**
+ * atk_text_scroll_substring_to (AtkText *accessible, AtkScrollType type)
+ * @text: an #AtkText
+ * @start_offset: start position
+ * @end_offset: end position, or -1 for the end of the string.
+ * @type: specify where the object should be made visible.
+ *
+ * Makes @text visible on the screen by scrolling all necessary parents.
+ *
+ * Contrary to atk_text_set_position, this does not actually move
+ * @text in its parent, this only makes the parents scroll so that the
+ * object shows up on the screen, given its current position within the parents.
+ *
+ * Since: 2.32
+ *
+ * Returns: whether scrolling was successful.
+ */
+gboolean
+atk_text_scroll_substring_to (AtkText       *text,
+                              gint          start_offset,
+                              gint          end_offset,
+                              AtkScrollType type)
+{
+  AtkTextIface *iface = NULL;
+  g_return_val_if_fail (ATK_IS_TEXT (text), FALSE);
+
+  iface = ATK_TEXT_GET_IFACE (text);
+
+  if (iface->scroll_substring_to)
+    return (iface->scroll_substring_to) (text, start_offset, end_offset, type);
+  else
+    return FALSE;
+}
+
+/**
+ * atk_text_scroll_substring_to_point (AtkText *accessible, AtkScrollType type, gint x, gint y)
+ * @text: an #AtkText
+ * @start_offset: start position
+ * @end_offset: end position, or -1 for the end of the string.
+ * @coords: specify whether coordinates are relative to the screen or to the
+ * parent object.
+ * @x: x-position where to scroll to
+ * @y: y-position where to scroll to
+ *
+ * Makes an object visible on the screen at a given position by scrolling all
+ * necessary parents.
+ *
+ * Since: 2.32
+ *
+ * Returns: whether scrolling was successful.
+ */
+gboolean
+atk_text_scroll_substring_to_point (AtkText      *text,
+                                    gint         start_offset,
+                                    gint         end_offset,
+                                    AtkCoordType coords,
+                                    gint         x,
+                                    gint         y)
+{
+  AtkTextIface *iface = NULL;
+  g_return_val_if_fail (ATK_IS_TEXT (text), FALSE);
+
+  iface = ATK_TEXT_GET_IFACE (text);
+
+  if (iface->scroll_substring_to_point)
+    return (iface->scroll_substring_to_point) (text, start_offset, end_offset, coords, x, y);
+  else
+    return FALSE;
+}
+
 static void 
 atk_text_real_get_range_extents (AtkText           *text,
                                  gint              start_offset,
diff --git a/atk/atktext.h b/atk/atktext.h
index d8852e4..32f0bf2 100644
--- a/atk/atktext.h
+++ b/atk/atktext.h
@@ -27,6 +27,7 @@
 #include <glib-object.h>
 #include <atk/atkobject.h>
 #include <atk/atkutil.h>
+#include <atk/atkcomponent.h>
 
 G_BEGIN_DECLS
 
@@ -333,6 +334,27 @@ struct _AtkTextIface
                                                    AtkTextGranularity granularity,
                                                    gint               *start_offset,
                                                    gint               *end_offset);
+  /*
+   * Scrolls this text range so it becomes visible on the screen.
+   *
+   * scroll_substring_to lets the implementation compute an appropriate target
+   * position on the screen, with type used as a positioning hint.
+   *
+   * scroll_substring_to_point lets the client specify a precise target position
+   * on the screen.
+   *
+   * Since ATK 2.32
+   */
+  gboolean       (* scroll_substring_to)          (AtkText          *text,
+                                                   gint             start_offset,
+                                                   gint             end_offset,
+                                                   AtkScrollType    type);
+  gboolean       (* scroll_substring_to_point)    (AtkText          *text,
+                                                   gint             start_offset,
+                                                   gint             end_offset,
+                                                   AtkCoordType     coords,
+                                                   gint             x,
+                                                   gint             y);
 };
 
 ATK_AVAILABLE_IN_ALL
@@ -448,6 +470,20 @@ ATK_AVAILABLE_IN_ALL
 const gchar*  atk_text_attribute_get_value                (AtkTextAttribute attr,
                                                            gint             index_);
 
+ATK_AVAILABLE_IN_ALL
+gboolean      atk_text_scroll_substring_to                (AtkText          *text,
+                                                           gint             start_offset,
+                                                           gint             end_offset,
+                                                           AtkScrollType    type);
+
+ATK_AVAILABLE_IN_ALL
+gboolean      atk_text_scroll_substring_to_point          (AtkText          *text,
+                                                           gint             start_offset,
+                                                           gint             end_offset,
+                                                           AtkCoordType     coords,
+                                                           gint             x,
+                                                           gint             y);
+
 G_END_DECLS
 
 #endif /* __ATK_TEXT_H__ */
diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt
index fb6a9ff..5200dbe 100644
--- a/docs/atk-sections.txt
+++ b/docs/atk-sections.txt
@@ -454,6 +454,8 @@ atk_text_attribute_register
 atk_text_attribute_get_name
 atk_text_attribute_for_name
 atk_text_attribute_get_value
+atk_text_scroll_substring_to
+atk_text_scroll_substring_to_point
 <SUBSECTION Standard>
 ATK_TEXT
 ATK_IS_TEXT