Merge 1b56618 into 2fe9cb2

nvdaes · web-flow · commit f3ea2c38d22d · 2023-09-20T14:36:22.000+02:00
diff --git a/projectDocs/dev/developerGuide/developerGuide.t2t b/projectDocs/dev/developerGuide/developerGuide.t2t
@@ -1022,6 +1022,10 @@ For examples of how to define and use new extension points, please see the code
 || Type | Extension Point | Description |
 | ``Decider`` | ``decide_beep`` | Notifies when a beep is about to be generated and played, allowing a component to decide whether it should be. |
 
+++ treeInterceptorHandler ++[treeInterceptorHandlerExtPts]
+|| Type | Extension Point | Description |
+| ``Action`` | ``post_browseModeStateChange`` | Notifies when browse mode state changes. |
+
 ++ utils.security ++[utils_securityExtPts]
 || Type | Extension Point | Description |
 | ``Action`` | ``post_sessionLockStateChanged`` | Notifies when a session lock or unlock event occurs. |
diff --git a/source/api.py b/source/api.py
@@ -90,6 +90,9 @@ def setFocusObject(obj: NVDAObjects.NVDAObject) -> bool:  # noqa: C901
 		return False
 	if globalVars.focusObject:
 		eventHandler.executeEvent("loseFocus",globalVars.focusObject)
+		oldTreeInterceptor = globalVars.focusObject.treeInterceptor
+	else:
+		oldTreeInterceptor = None
 	oldFocusLine=globalVars.focusAncestors
 	#add the old focus to the old focus ancestors, but only if its not None (is none at NVDA initialization)
 	if globalVars.focusObject: 
@@ -164,6 +167,13 @@ def setFocusObject(obj: NVDAObjects.NVDAObject) -> bool:  # noqa: C901
 		obj.treeInterceptor=treeInterceptorObject
 	else:
 		obj.treeInterceptor=None
+	if oldTreeInterceptor is not obj.treeInterceptor:
+		if obj.treeInterceptor:
+			# obj.treeInterceptor has been assigned to treeInterceptorObject.
+			browseMode = not treeInterceptorObject._passThrough
+		else:
+			browseMode = False
+		treeInterceptorHandler.post_browseModeStateChange.notify(browseMode=browseMode)
 	# #3804: handleAppSwitch should be called as late as possible,
 	# as triggers must not be out of sync with global focus variables.
 	# setFocusObject shouldn't fail earlier anyway, but it's best to be safe.
diff --git a/source/browseMode.py b/source/browseMode.py
@@ -51,14 +51,16 @@
 from typing import Optional
 
 
-def reportPassThrough(treeInterceptor,onlyIfChanged=True):
+def reportPassThrough(treeInterceptor,onlyIfChanged=True, prevBrowseMode=False):
 	"""Reports the pass through mode if it has changed.
 	@param treeInterceptor: The current Browse Mode treeInterceptor.
 	@type treeInterceptor: L{BrowseModeTreeInterceptor}
 	@param onlyIfChanged: if true reporting will not happen if the last reportPassThrough reported the same thing.
 	@type onlyIfChanged: bool
+	@param prevBrowseMode: True if browse mode was active, False otherwise.
+	@type browseMode: bool
 	"""
-	if not onlyIfChanged or treeInterceptor.passThrough != reportPassThrough.last:
+	if not onlyIfChanged or treeInterceptor.passThrough != prevBrowseMode:
 		if config.conf["virtualBuffers"]["passThroughAudioIndication"]:
 			sound = "focusMode.wav" if treeInterceptor.passThrough else "browseMode.wav"
 			nvwave.playWaveFile(os.path.join(globalVars.appDir, "waves", sound))
@@ -70,8 +72,7 @@ def reportPassThrough(treeInterceptor,onlyIfChanged=True):
 				# Translators: The mode that presents text in a flat representation
 				# that can be navigated with the cursor keys like in a text document
 				ui.message(_("Browse mode"))
-		reportPassThrough.last = treeInterceptor.passThrough
-reportPassThrough.last = False
+
 
 def mergeQuickNavItemIterators(iterators,direction="next"):
 	"""
@@ -1995,3 +1996,5 @@ def _iterNotLinkBlock(self, direction="next", pos=None):
 	def script_toggleScreenLayout(self, gesture):
 		# Translators: The message reported for not supported toggling of screen layout
 		ui.message(_("Not supported in this document."))
+
+treeInterceptorHandler.post_browseModeStateChange.register(reportPassThrough)
diff --git a/source/treeInterceptorHandler.py b/source/treeInterceptorHandler.py
@@ -20,10 +20,20 @@
 import vision
 from speech.types import SpeechSequence
 from controlTypes import OutputReason
+import extensionPoints
 
 if TYPE_CHECKING:
 	import NVDAObjects
 
+post_browseModeStateChange = extensionPoints.Action()
+"""
+Notifies when browse mode state has changed.
+This allows components and add-ons to perform an action.
+For example, an add-on may activate a profile when browse mode has been activated,
+and deactivate that profile when browse mode becomes inactive.
+@param browseMode: The state of browse mode.
+@type browseMode: bool
+"""
 
 runningTable=set()
 
@@ -134,6 +144,8 @@ def _set_passThrough(self, state):
 		if self._passThrough == state:
 			return
 		self._passThrough = state
+		browseMode = not self._passThrough
+		post_browseModeStateChange.notify(browseMode=browseMode)
 		if state:
 			if config.conf['reviewCursor']['followFocus']:
 				focusObj=api.getFocusObject()
diff --git a/user_docs/en/changes.t2t b/user_docs/en/changes.t2t
@@ -130,6 +130,7 @@ They should also be thread safe, making it possible to call them from background
 - Added official support to register custom braille display drivers in the automatic braille display detection process.
 Consult the ``braille.BrailleDisplayDriver`` class documentation for more details.
 Most notably, the ``supportsAutomaticDetection`` attribute must be set to ``True`` and the ``registerAutomaticDetection`` ``classmethod`` must be implemented.  (#15196)
+- Added extension point: ``treeInterceptorHandler.post_browseModeStateChange``. (#14969)
 -
 
 === Deprecations ===

Original file line number	Diff line number	Diff line change
`@@ -130,6 +130,7 @@ They should also be thread safe, making it possible to call them from background`
`130`	`130`	`- Added official support to register custom braille display drivers in the automatic braille display detection process.`
`131`	`131`	Consult the ``braille.BrailleDisplayDriver`` class documentation for more details.
`132`	`132`	Most notably, the ``supportsAutomaticDetection`` attribute must be set to ``True`` and the ``registerAutomaticDetection`` ``classmethod`` must be implemented. (#15196)
	`133`	+- Added extension point: ``treeInterceptorHandler.post_browseModeStateChange``. (#14969)
`133`	`134`	`-`
`134`	`135`
`135`	`136`	`=== Deprecations ===`