Add navigation helper functions for screen-reader and friends

[platform/upstream/at-spi2-core.git] / atspi / atspi-accessible.c

diff --git a/atspi/atspi-accessible.c b/atspi/atspi-accessible.c
index e112574..a579254 100644 (file)
--- a/atspi/atspi-accessible.c
+++ b/atspi/atspi-accessible.c
@@ -314,6 +314,47 @@ atspi_accessible_get_path(AtspiAccessible *obj, GError **error)
 }
 
 /**
+ * atspi_accessible_get_navigable_at_point:
+ * @root: a pointer to the #AtspiAccessible to start search from.
+ * @x: a #gint specifying the x coordinate of the point in question.
+ * @y: a #gint specifying the y coordinate of the point in question.
+ * @ctype: the coordinate system of the point (@x, @y)
+ *         (e.g. ATSPI_COORD_TYPE_WINDOW, ATSPI_COORD_TYPE_SCREEN).
+ *
+ * Finds the accessible element closest to user (highest in z-order), at a given coordinate within an #AtspiAccessible.
+ * This should be the element, that should be picked, when doing mouse click or finger tap at given coordinates.
+ *
+ * Returns: (nullable) (transfer full): a pointer to an
+ *          #AtspiAccessible descendant (of any depth) of the specified component which
+ *          contains the point (@x, @y), or NULL if no descendant contains
+ *          the point.
+ **/
+AtspiAccessible *
+atspi_accessible_get_navigable_at_point (AtspiAccessible *root,
+                                          gint x,
+                                          gint y,
+                                          AtspiCoordType ctype, GError **error)
+{
+  dbus_int32_t d_x = x, d_y = y;
+  dbus_uint32_t d_ctype = ctype;
+  DBusMessage *reply;
+  AtspiAccessible *return_value = NULL;
+  unsigned char recurse = 0;
+
+  g_return_val_if_fail (root != NULL, FALSE);
+  do {
+    reply = _atspi_dbus_call_partial (root, atspi_interface_accessible, "GetNavigableAtPoint", error, "iiu", d_x, d_y, d_ctype);
+
+    AtspiAccessible *tmp = _atspi_dbus_return_accessible_and_recurse_info_from_message (reply, &recurse);
+    if (!tmp) break;
+    if (return_value)
+      g_object_unref(return_value);
+    return_value = root = tmp;
+  } while(recurse);
+  return return_value;
+}
+
+/**
  * atspi_accessible_get_description:
  * @obj: a pointer to the #AtspiAccessible object on which to operate.
  *