Encapsulate IA2 relations constants (PR #13096)

* Relations constants

Compat breaking refactor:
- Removed IA2_RELATION_FLOWS_FROM
- Removed IA2_RELATION_FLOWS_TO
- Removed IA2_RELATION_CONTAINING_DOCUMENT
- Replaced with IAccessibleHandler.RelationType enum

* Breaks compatibility in 2022.1

source/IAccessibleHandler/__init__.py

@@ -3,6 +3,10 @@
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
+# F401 imported but unused. RelationType should be exposed from IAccessibleHandler, in future __all__
+# should be used to export it.
+from .types import RelationType  # noqa: F401
+
 import re
 import struct
 from typing import (
@@ -57,9 +61,6 @@
 NAVRELATION_NODE_CHILD_OF = 0x1005
 NAVRELATION_EMBEDS = 0x1009
 
-# IAccessible2 relations (not included in the typelib)
-IA2_RELATION_FLOWS_FROM = "flowsFrom"
-IA2_RELATION_FLOWS_TO = "flowsTo"
 
 # A place to store live IAccessible NVDAObjects, that can be looked up by their window,objectID,
 # childID event params.

source/IAccessibleHandler/types.py

@@ -7,11 +7,21 @@
 """Types used in IAccessibleHander.
 Kept here so they can be re-used without having to worry about circular imports.
 """
-
+import enum
 from typing import Tuple
 
 IAccessibleObjectIdentifierType = Tuple[
 	int,  # windowHandle
 	int,  # objectID
 	int,  # childID
 ]
+
+
+# IAccessible2 relations (not included in the typelib)
+@enum.unique
+class RelationType(enum.Enum):
+	FLOWS_FROM = "flowsFrom"
+	FLOWS_TO = "flowsTo"
+	CONTAINING_DOCUMENT = "containingDocument"
+	DETAILS = "details"
+	DETAILS_FOR = "detailsFor"

source/NVDAObjects/IAccessible/__init__.py

@@ -1486,11 +1486,17 @@ def _getIA2RelationFirstTarget(
 				pass
 		return None
 
-	def _get_flowsTo(self):
-		return self._getIA2RelationFirstTarget(IAccessibleHandler.IA2_RELATION_FLOWS_TO)
+	#: Type definition for auto prop '_get_flowsTo'
+	flowsTo: typing.Optional["IAccessible"]
 
-	def _get_flowsFrom(self):
-		return self._getIA2RelationFirstTarget(IAccessibleHandler.IA2_RELATION_FLOWS_FROM)
+	def _get_flowsTo(self) -> typing.Optional["IAccessible"]:
+		return self._getIA2RelationFirstTarget(IAccessibleHandler.RelationType.FLOWS_TO)
+
+	#: Type definition for auto prop '_get_flowsFrom'
+	flowsFrom: typing.Optional["IAccessible"]
+
+	def _get_flowsFrom(self) -> typing.Optional["IAccessible"]:
+		return self._getIA2RelationFirstTarget(IAccessibleHandler.RelationType.FLOWS_FROM)
 
 	def event_valueChange(self):
 		if isinstance(self, EditableTextWithAutoSelectDetection):

source/virtualBuffers/gecko_ia2.py

@@ -13,6 +13,7 @@
 import winUser
 import mouseHandler
 import IAccessibleHandler
+
 import oleacc
 from logHandler import log
 import textInfos
@@ -23,9 +24,6 @@
 import config
 from NVDAObjects.IAccessible import normalizeIA2TextFormatField, IA2TextTextInfo
 
-IA2_RELATION_CONTAINING_DOCUMENT = "containingDocument"
-
-
 def _getNormalizedCurrentAttrs(attrs: textInfos.ControlField) -> typing.Dict[str, typing.Any]:
 	valForCurrent = attrs.get("IAccessible2::attribute_current", "false")
 	try:
@@ -193,7 +191,10 @@ def _getEmbedderFrame(acc):
 				# IAccessible NVDAObjects currently fetch IA2, but we need IA2_2 for relationTargetsOfType.
 				# (Out-of-process, for a single relation, this is cheaper than IA2::relations.)
 				acc = acc.QueryInterface(IA2.IAccessible2_2)
-			targets, count = acc.relationTargetsOfType(IA2_RELATION_CONTAINING_DOCUMENT, 1)
+			targets, count = acc.relationTargetsOfType(
+				IAccessibleHandler.RelationType.CONTAINING_DOCUMENT,
+				1  # max relations to fetch
+			)
 			if count == 0:
 				return None
 			doc = targets[0].QueryInterface(IA2.IAccessible2_2)

user_docs/en/changes.t2t

@@ -78,6 +78,11 @@ This ensures code will honor the Windows user setting for swapping the primary m
   - ``_UIAConstants`` is now ``UIAHandler.constants``
   - ``_UIACustomProps`` is now ``UIAHandler.customProps``
   - ``_UIACustomAnnotations`` is now ``UIAHandler.customAnnotations``
+- The ``IAccessibleHandler`` ``IA2_RELATION_*`` constants have been replaced with the ``IAccessibleHandler.RelationType`` enum. (#13096)
+  - Removed ``IA2_RELATION_FLOWS_FROM``
+  - Removed ``IA2_RELATION_FLOWS_TO``
+  - Removed ``IA2_RELATION_CONTAINING_DOCUMENT``
+  -
 -