From 9b63cd50fef2007809a04a16f818f5f965c217c5 Mon Sep 17 00:00:00 2001
From: Emil-18 <135248352+Emil-18@users.noreply.github.com>
Date: Mon, 15 Jul 2024 01:31:12 +0200
Subject: [PATCH] Added a method on the NVDAObject class called
 objectFromPointRedirect (#16807)

fixes #16788

Summary of the issue:
It is impossible to redirect what object NVDA retrieves from on screen coordinates. This makes it dificult to implement mouse and touch support for objects that has a location that differs from the location provided by the API class.

Description of user facing changes
None

Description of development approach
A new method called objectFromPointRedirect has been added to the NVDAObject class. This method is called from objectFromPoint, and given the x and y parameters. If it returns an NVDAObject, that object will be returned by objectFromPoint
---
 source/NVDAObjects/__init__.py | 27 +++++++++++++++++++--------
 user_docs/en/changes.md        |  1 +
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/source/NVDAObjects/__init__.py b/source/NVDAObjects/__init__.py
index f87d107f83a..7d3ab166471 100644
--- a/source/NVDAObjects/__init__.py
+++ b/source/NVDAObjects/__init__.py
@@ -316,19 +316,30 @@ def findOverlayClasses(self, clsList: typing.List[typing.Type["NVDAObject"]]) ->
 
 	beTransparentToMouse = False  #:If true then NVDA will never consider the mouse to be on this object, rather it will be on an ancestor.
 
+	def objectFromPointRedirect(self, x: int, y: int) -> "NVDAObject | None":
+		"""Redirects NVDA to another object if this object is retrieved from on-screen coordinates.
+		:param x: the x coordinate.
+		:param y: the y coordinate.
+		:return: The object that NVDA should be redirected to.
+		"""
+		return
+
 	@staticmethod
-	def objectFromPoint(x, y):
+	def objectFromPoint(x: int, y: int) -> "NVDAObject":
 		"""Retrieves an NVDAObject instance representing a control in the Operating System at the given x and y coordinates.
-		@param x: the x coordinate.
-		@type x: int
-		@param y: the y coordinate.
-		@param y: int
-		@return: The object at the given x and y coordinates.
-		@rtype: L{NVDAObject}
+		:param x: the x coordinate.
+		:param y: the y coordinate.
+		:return: The object at the given x and y coordinates.
 		"""
 		kwargs = {}
 		APIClass = NVDAObject.findBestAPIClass(kwargs, relation=(x, y))
-		return APIClass(chooseBestAPI=False, **kwargs) if APIClass else None
+		obj = APIClass(chooseBestAPI=False, **kwargs) if APIClass else None
+		if not obj:
+			return
+		redirect = obj.objectFromPointRedirect(x, y)
+		if redirect:
+			obj = redirect
+		return obj
 
 	@staticmethod
 	def objectWithFocus():
diff --git a/user_docs/en/changes.md b/user_docs/en/changes.md
index c88a7f343a2..32e4ea495af 100644
--- a/user_docs/en/changes.md
+++ b/user_docs/en/changes.md
@@ -21,6 +21,7 @@
 Please refer to [the developer guide](https://www.nvaccess.org/files/nvda/documentation/developerGuide.html#API) for information on NVDA's API deprecation and removal process.
 
 * Added a `.editorconfig` file to NVDA's repository in order for several IDEs to pick up basic NVDA code style rules by default. (#16795, @LeonarddeR)
+* It is now possible to redirect objects retrieved from on-screen coordinates, by using the `NVDAObject.objectFromPointRedirect` method. (#16788, @Emil-18)
 
 #### Deprecations