Merge 1923005 into 41418d7

Emil-18 · web-flow · commit 4e4c4f5b8e2d · 2024-07-12T12:41:22.000+02:00
diff --git 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
@@ -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
 
