[atk] atkcomponent: Add ScrollTo and ScrollToPoint component interfaces

[Alejandro Piñeiro Iglesias <apinheiro src gnome org>]

commit e98b748461acfcfc261dc47290947b614417eef7
Author: Samuel Thibault <samuel thibault ens-lyon org>
Date:   Tue Feb 13 13:29:53 2018 +0100

    atkcomponent: Add ScrollTo and ScrollToPoint component interfaces

 atk/atkcomponent.c    |   66 ++++++++++++++++++++++++++++++++++++++++++++++--
 atk/atkcomponent.h    |   52 ++++++++++++++++++++++++++++++++++++++
 atk/atkutil.h         |    7 +++-
 atk/atkversion.h.in   |   14 ++++++++++
 docs/atk-sections.txt |    3 ++
 5 files changed, 137 insertions(+), 5 deletions(-)
---
diff --git a/atk/atkcomponent.c b/atk/atkcomponent.c
index f0beb10..dd3895d 100644
--- a/atk/atkcomponent.c
+++ b/atk/atkcomponent.c
@@ -507,10 +507,13 @@ atk_component_set_extents   (AtkComponent    *component,
  * @x: x coordinate
  * @y: y coordinate
  * @coord_type: specifies whether the coordinates are relative to the screen
- * or to the components top level window
+ * or to the component's top level window
+ *
+ * Sets the position of @component.
+ *
+ * Contrary to atk_component_scroll_to, this does not trigger any scrolling,
+ * this just moves @component in its parent.
  *
- * Sets the postition of @component.
- * 
  * Returns: %TRUE or %FALSE whether or not the position was set or not
  **/
 gboolean
@@ -556,6 +559,63 @@ atk_component_set_size       (AtkComponent    *component,
     return FALSE;
 }
 
+/**
+ * atk_component_scroll_to (AtkComponent *accessible, AtkScrollType type)
+ * @component: an #AtkComponent
+ * @type: specify where the object should be made visible.
+ *
+ * Makes @component visible on the screen by scrolling all necessary parents.
+ *
+ * Contrary to atk_component_set_position, this does not actually move
+ * @component 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.30
+ *
+ * Returns: whether scrolling was successful.
+ */
+gboolean
+atk_component_scroll_to (AtkComponent *component, AtkScrollType type)
+{
+  AtkComponentIface *iface = NULL;
+  g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
+
+  iface = ATK_COMPONENT_GET_IFACE (component);
+
+  if (iface->scroll_to)
+    return (iface->scroll_to) (component, type);
+  else
+    return FALSE;
+}
+
+/**
+ * atk_component_scroll_to_point (AtkComponent *accessible, AtkScrollType type, gint x, gint y)
+ * @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.30
+ *
+ * Returns: whether scrolling was successful.
+ */
+gboolean
+atk_component_scroll_to_point (AtkComponent *component, AtkCoordType coords, gint x, gint y)
+{
+  AtkComponentIface *iface = NULL;
+  g_return_val_if_fail (ATK_IS_COMPONENT (component), FALSE);
+
+  iface = ATK_COMPONENT_GET_IFACE (component);
+
+  if (iface->scroll_to_point)
+    return (iface->scroll_to_point) (component, coords, x, y);
+  else
+    return FALSE;
+}
+
 static gboolean
 atk_component_real_contains (AtkComponent *component,
                              gint         x,
diff --git a/atk/atkcomponent.h b/atk/atkcomponent.h
index d20fdc2..22155c1 100644
--- a/atk/atkcomponent.h
+++ b/atk/atkcomponent.h
@@ -29,6 +29,36 @@
 
 G_BEGIN_DECLS
 
+/**
+ *AtkScrollType:
+ *@ATK_SCROLL_TOP_LEFT: Scroll the object vertically and horizontally to the top
+ *left corner of the window.
+ *@ATK_SCROLL_BOTTOM_RIGHT: Scroll the object vertically and horizontally to the
+ *bottom right corner of the window.
+ *@ATK_SCROLL_TOP_EDGE: Scroll the object vertically to the top edge of the
+ window.
+ *@ATK_SCROLL_BOTTOM_EDGE: Scroll the object vertically to the bottom edge of
+ *the window.
+ *@ATK_SCROLL_LEFT_EDGE: Scroll the object vertically and horizontally to the
+ *left edge of the window.
+ *@ATK_SCROLL_RIGHT_EDGE: Scroll the object vertically and horizontally to the
+ *right edge of the window.
+ *@ATK_SCROLL_ANYWHERE: Scroll the object vertically and horizontally so that
+ *as much as possible of the object becomes visible. The exact placement is
+ *determined by the application.
+ *
+ * Specifies where an object should be placed on the screen when using scroll_to.
+ **/
+typedef enum {
+  ATK_SCROLL_TOP_LEFT,
+  ATK_SCROLL_BOTTOM_RIGHT,
+  ATK_SCROLL_TOP_EDGE,
+  ATK_SCROLL_BOTTOM_EDGE,
+  ATK_SCROLL_LEFT_EDGE,
+  ATK_SCROLL_RIGHT_EDGE,
+  ATK_SCROLL_ANYWHERE
+} AtkScrollType;
+
 /*
  * The AtkComponent interface should be supported by any object that is 
  * rendered on the screen. The interface provides the standard mechanism 
@@ -156,6 +186,18 @@ struct _AtkComponentIface
   void                     (* bounds_changed)   (AtkComponent   *component,
                                                  AtkRectangle   *bounds);
   gdouble                  (* get_alpha)        (AtkComponent   *component);
+
+  /*
+   * Scrolls this object so it becomes visible on the screen.
+   * Since ATK 2.30
+   */
+  gboolean                (*scroll_to)          (AtkComponent   *component,
+                                                 AtkScrollType   type);
+
+  gboolean                (*scroll_to_point)    (AtkComponent   *component,
+                                                 AtkCoordType    coords,
+                                                 gint            x,
+                                                 gint            y);
 };
 
 ATK_AVAILABLE_IN_ALL
@@ -219,6 +261,16 @@ gboolean              atk_component_set_size               (AtkComponent    *com
 ATK_AVAILABLE_IN_ALL
 gdouble               atk_component_get_alpha              (AtkComponent    *component);
 
+ATK_AVAILABLE_IN_2_30
+gboolean              atk_component_scroll_to              (AtkComponent    *component,
+                                                            AtkScrollType   type);
+
+ATK_AVAILABLE_IN_2_30
+gboolean              atk_component_scroll_to_point        (AtkComponent    *component,
+                                                            AtkCoordType    coords,
+                                                            gint            x,
+                                                            gint            y);
+
 G_END_DECLS
 
 #endif /* __ATK_COMPONENT_H__ */
diff --git a/atk/atkutil.h b/atk/atkutil.h
index d69df88..e3a6e4b 100644
--- a/atk/atkutil.h
+++ b/atk/atkutil.h
@@ -176,15 +176,18 @@ GType atk_util_get_type (void);
 /**
  *AtkCoordType:
  *@ATK_XY_SCREEN: specifies xy coordinates relative to the screen
- *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's 
+ *@ATK_XY_WINDOW: specifies xy coordinates relative to the widget's
  * top-level window
+ *@ATK_XY_PARENT: specifies xy coordinates relative to the widget's
+ * immediate parent.
  *
  *Specifies how xy coordinates are to be interpreted. Used by functions such
  *as atk_component_get_position() and atk_text_get_character_extents() 
  **/
 typedef enum {
   ATK_XY_SCREEN,
-  ATK_XY_WINDOW
+  ATK_XY_WINDOW,
+  ATK_XY_PARENT
 }AtkCoordType;
 
 ATK_DEPRECATED_IN_2_10
diff --git a/atk/atkversion.h.in b/atk/atkversion.h.in
index bba9f49..c5ec017 100644
--- a/atk/atkversion.h.in
+++ b/atk/atkversion.h.in
@@ -376,6 +376,20 @@
 # define ATK_AVAILABLE_IN_2_14                 _ATK_EXTERN
 #endif
 
+#if ATK_VERSION_MIN_REQUIRED >= ATK_VERSION_2_30
+# define ATK_DEPRECATED_IN_2_30                ATK_DEPRECATED
+# define ATK_DEPRECATED_IN_2_30_FOR(f)         ATK_DEPRECATED_FOR(f)
+#else
+# define ATK_DEPRECATED_IN_2_30                _ATK_EXTERN
+# define ATK_DEPRECATED_IN_2_30_FOR(f)         _ATK_EXTERN
+#endif
+
+#if ATK_VERSION_MAX_ALLOWED < ATK_VERSION_2_30
+# define ATK_AVAILABLE_IN_2_30                 ATK_UNAVAILABLE(2, 30)
+#else
+# define ATK_AVAILABLE_IN_2_30                 _ATK_EXTERN
+#endif
+
 ATK_AVAILABLE_IN_2_8
 guint atk_get_major_version (void) G_GNUC_CONST;
 ATK_AVAILABLE_IN_2_8
diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt
index 1224f31..816144e 100644
--- a/docs/atk-sections.txt
+++ b/docs/atk-sections.txt
@@ -39,6 +39,8 @@ atk_component_set_extents
 atk_component_set_position
 atk_component_set_size
 atk_component_get_alpha
+atk_component_scroll_to
+atk_component_scroll_to_point
 <SUBSECTION Standard>
 ATK_COMPONENT
 ATK_IS_COMPONENT
@@ -211,6 +213,7 @@ ATK_IS_IMPLEMENTOR
 ATK_IMPLEMENTOR
 ATK_TYPE_ROLE
 ATK_TYPE_LAYER
+ATK_TYPE_SCROLL_TYPE
 atk_implementor_get_type
 atk_object_get_type
 atk_role_get_type