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

@@ -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():

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