Add the ability to automatically tether to focus or review

source/NVDAObjects/IAccessible/mscandui.py

@@ -160,7 +160,7 @@ def event_show(self):
 				reportSelectedCandidate(item)
 				return
 			elif config.conf["reviewCursor"]["followFocus"]:
-				api.setNavigatorObject(candidateList)
+				api.setNavigatorObject(candidateList, isFocus=True)
 		elif role==controlTypes.ROLE_MENUBUTTON:
 			item=candidateList.firstChild.next.next
 			item=MSCandUI21_candidateMenuItem(IAccessibleObject=item.IAccessibleObject,IAccessibleChildID=item.IAccessibleChildID)

source/NVDAObjects/UIA/__init__.py

@@ -1513,7 +1513,7 @@ def event_UIA_elementSelected(self):
 		focusControllerFor=api.getFocusObject().controllerFor
 		if len(focusControllerFor)>0 and focusControllerFor[0].appModule is self.appModule and self.name:
 			speech.cancelSpeech()
-			api.setNavigatorObject(self)
+			api.setNavigatorObject(self, isFocus=True)
 			self.reportFocus()
 			# Display results as flash messages.
 			braille.handler.message(braille.getBrailleTextForProperties(name=self.name, role=self.role, positionInfo=self.positionInfo))

source/NVDAObjects/__init__.py

@@ -961,7 +961,7 @@ def event_foreground(self):
 	def event_becomeNavigatorObject(self):
 		"""Called when this object becomes the navigator object.
 		"""
-		braille.handler.handleReviewMove()
+		braille.handler.handleReviewMove(shouldAutoTether=not eventHandler.lastReviewMoveDueToFollowing)
 
 	def event_valueChange(self):
 		if self is api.getFocusObject():

source/api.py

@@ -177,13 +177,14 @@ def getReviewPosition():
 		globalVars.reviewPosition,globalVars.reviewPositionObj=review.getPositionForCurrentMode(obj)
 		return globalVars.reviewPosition
 
-def setReviewPosition(reviewPosition,clearNavigatorObject=True):
+def setReviewPosition(reviewPosition,clearNavigatorObject=True, isCaret=False):
 	"""Sets a TextInfo instance as the review position. if clearNavigatorObject is true, It sets the current navigator object to None so that the next time the navigator object is asked for it fetches it from the review position.
 	"""
 	globalVars.reviewPosition=reviewPosition.copy()
 	globalVars.reviewPositionObj=reviewPosition.obj
 	if clearNavigatorObject: globalVars.navigatorObject=None
-	braille.handler.handleReviewMove()
+	eventHandler.lastReviewMoveDueToFollowing = isCaret
+	braille.handler.handleReviewMove(shouldAutoTether=not isCaret)
 
 def getNavigatorObject():
 	"""Gets the current navigator object. Navigator objects can be used to navigate around the operating system (with the number pad) with out moving the focus. If the navigator object is not set, it fetches it from the review position. 
@@ -227,6 +228,7 @@ def setNavigatorObject(obj,isFocus=False):
 		if isFocus:
 			globalVars.reviewPosition=obj.treeInterceptor.makeTextInfo(textInfos.POSITION_CARET)
 			globalVars.reviewPositionObj=globalVars.reviewPosition
+	eventHandler.lastReviewMoveDueToFollowing = isFocus
 	eventHandler.executeEvent("becomeNavigatorObject",obj)
 
 def isTypingProtected():

source/appModules/explorer.py

@@ -41,7 +41,7 @@ class SuggestionListItem(UIA):
 
 	def event_UIA_elementSelected(self):
 		speech.cancelSpeech()
-		api.setNavigatorObject(self)
+		api.setNavigatorObject(self, isFocus=True)
 		self.reportFocus()
 		super(SuggestionListItem,self).event_UIA_elementSelected()
 

source/appModules/lockapp.py

@@ -90,10 +90,10 @@ def event_appModule_gainFocus(self):
 			# Move the review cursor so others can't access its previous position.
 			self._oldReviewPos = api.getReviewPosition()
 			self._oldReviewObj = self._oldReviewPos.obj
-			api.setNavigatorObject(eventHandler.lastQueuedFocusObject)
+			api.setNavigatorObject(eventHandler.lastQueuedFocusObject, isFocus=True)
 
 	def event_appModule_loseFocus(self):
 		if not config.conf["reviewCursor"]["followFocus"]:
-			api.setReviewPosition(self._oldReviewPos)
+			api.setReviewPosition(self._oldReviewPos, isCaret=False)
 			del self._oldReviewPos, self._oldReviewObj
 		inputCore.manager._captureFunc = None

source/appModules/skype.py

@@ -160,7 +160,8 @@ def reviewRecentMessage(self, index):
 			ui.message(_("No message yet"))
 			return
 		message = self.getChild(count - index)
-		api.setNavigatorObject(message)
+		# Reviewing a message should not auto tether
+		api.setNavigatorObject(message, isFocus=True)
 		self.reportMessage(message.name)
 
 class Notification(NVDAObjects.behaviors.Notification):

source/braille.py

@@ -28,6 +28,7 @@
 from collections import namedtuple
 import re
 import scriptHandler
+import eventHandler
 
 roleLabels = {
 	# Translators: Displayed in braille for an object which is a
@@ -1450,6 +1451,7 @@ def __init__(self):
 		self._cells = []
 		self._cursorBlinkTimer = None
 		config.configProfileSwitched.register(self.handleConfigProfileSwitch)
+		self._tether = config.conf["braille"]["tetherTo"]
 
 	def terminate(self):
 		if self._messageCallLater:
@@ -1464,18 +1466,34 @@ def terminate(self):
 			self.display = None
 		_BgThread.stop()
 
+	def getTether(self):
+		return self._tether
+
 	def _get_tether(self):
-		return config.conf["braille"]["tetherTo"]
+		"""@deprecated: Use L{getTether instead."""
+		return self.getTether()
 
-	def _set_tether(self, tether):
-		if tether == config.conf["braille"]["tetherTo"]:
+	def setTether(self, tether, auto=False):
+		if auto and not self.shouldAutoTether:
+			return
+		if auto and tether == self.TETHER_REVIEW and eventHandler.lastReviewMoveDueToFollowing:
 			return
-		config.conf["braille"]["tetherTo"] = tether
+		if not auto:
+			config.conf["braille"]["tetherTo"] = tether
+		if tether == self._tether:
+			return
+		self._tether = tether
 		self.mainBuffer.clear()
-		if tether == self.TETHER_REVIEW:
-			self.handleReviewMove()
-		else:
-			self.handleGainFocus(api.getFocusObject())
+
+	def _set_tether(self, tether):
+		"""@deprecated: Use L{setTether instead."""
+		self.setTether(tether, auto=False)
+
+	def _get_isAutoTethered(self):
+		return self._tether is not config.conf["braille"]["tetherTo"]
+
+	def _get_shouldAutoTether(self):
+		return self.enabled and config.conf["braille"]["autoTether"]
 
 	def setDisplayByName(self, name, isFallback=False):
 		if not name:
@@ -1640,10 +1658,12 @@ def _dismissMessage(self):
 			self._messageCallLater = None
 		self.update()
 
-	def handleGainFocus(self, obj):
+	def handleGainFocus(self, obj, shouldAutoTether=True):
 		if not self.enabled:
 			return
-		if self.tether != self.TETHER_FOCUS:
+		if shouldAutoTether:
+			self.setTether(self.TETHER_FOCUS, auto=True)
+		elif self._tether != self.TETHER_FOCUS:
 			return
 		self._doNewObject(itertools.chain(getFocusContextRegions(obj, oldFocusRegions=self.mainBuffer.regions), getFocusRegions(obj)))
 
@@ -1672,12 +1692,12 @@ def _doNewObject(self, regions):
 		elif self.buffer is self.messageBuffer and keyboardHandler.keyCounter>self._keyCountForLastMessage:
 			self._dismissMessage()
 
-	def handleCaretMove(self, obj):
+	def handleCaretMove(self, obj, shouldAutoTether=True):
 		if not self.enabled:
 			return
-		if self.tether != self.TETHER_FOCUS:
-			return
-		if not self.mainBuffer.regions:
+		if shouldAutoTether:
+			self.setTether(self.TETHER_FOCUS, auto=True)
+		elif self._tether != self.TETHER_FOCUS or not self.mainBuffer.regions:
 			return
 		region = self.mainBuffer.regions[-1]
 		if region.obj is not obj:
@@ -1742,7 +1762,7 @@ def handleUpdate(self, obj):
 			# There are some objects that require special update behavior even if they have no region.
 			# This only applies when tethered to focus, because tethering to review shows only one object at a time,
 			# which always has a braille region associated with it.
-			if self.tether != self.TETHER_FOCUS:
+			if self._tether != self.TETHER_FOCUS:
 				return
 			# Late import to avoid circular import.
 			from NVDAObjects import NVDAObject
@@ -1758,12 +1778,16 @@ def handleUpdate(self, obj):
 		elif self.buffer is self.messageBuffer and keyboardHandler.keyCounter>self._keyCountForLastMessage:
 			self._dismissMessage()
 
-	def handleReviewMove(self):
+	def handleReviewMove(self, shouldAutoTether=True):
 		if not self.enabled:
 			return
-		if self.tether != self.TETHER_REVIEW:
+		if not shouldAutoTether and self._tether != self.TETHER_REVIEW:
 			return
 		reviewPos = api.getReviewPosition()
+		#if reviewPos.obj == api.getFocusObject() and config.conf["reviewCursor"]["followFocus"]:
+			#return
+		if shouldAutoTether:
+			self.setTether(self.TETHER_REVIEW, auto=True)
 		region = self.mainBuffer.regions[-1] if self.mainBuffer.regions else None
 		if region and region.obj == reviewPos.obj:
 			self._doCursorMove(region)
@@ -1851,9 +1875,9 @@ def initialize():
 		# Braille is disabled or focus/review hasn't yet been initialised.
 		return
 	if handler.tether == handler.TETHER_FOCUS:
-		handler.handleGainFocus(api.getFocusObject())
+		handler.handleGainFocus(api.getFocusObject(), shouldAutoTether=False)
 	else:
-		handler.handleReviewMove()
+		handler.handleReviewMove(shouldAutoTether=False)
 
 def pumpAll():
 	"""Runs tasks at the end of each core cycle. For now just caret updates."""

source/config/configSpec.py

@@ -61,6 +61,7 @@
 	noMessageTimeout = boolean(default=false)
 	messageTimeout = integer(default=4,min=0,max=20)
 	tetherTo = string(default="focus")
+	autoTether= boolean(default=false)
 	readByParagraph = boolean(default=false)
 	wordWrap = boolean(default=true)
 	focusContextPresentation = option("changedContext", "fill", "scroll", default="changedContext")

source/eventHandler.py

@@ -27,6 +27,9 @@
 #: the last object queued for a gainFocus event. Useful for code running outside NVDA's core queue 
 lastQueuedFocusObject=None
 
+#: Whether the last focus or caret event changed or is about to change the review cursor due to following
+lastReviewMoveDueToFollowing = False
+
 def queueEvent(eventName,obj,**kwargs):
 	"""Queues an NVDA event to be executed.
 	@param eventName: the name of the event type (e.g. 'gainFocus', 'nameChange')
@@ -170,7 +173,7 @@ def doPreGainFocus(obj,sleepMode=False):
 		if obj.treeInterceptor and obj.treeInterceptor.isReady and hasattr(obj.treeInterceptor,"event_treeInterceptor_gainFocus"):
 			obj.treeInterceptor.event_treeInterceptor_gainFocus()
 	return True
- 
+
 def doPreDocumentLoadComplete(obj):
 	focusObject=api.getFocusObject()
 	if (not obj.treeInterceptor or not obj.treeInterceptor.isAlive or obj.treeInterceptor.shouldPrepare) and (obj==focusObject or obj in api.getFocusAncestors()):