Allow the review cursor to be bounded to onscreen text

developerGuide.t2t

@@ -403,7 +403,7 @@ For example:
 --- start ---
 	@script(
 		description=_("Speaks the date and time"),
-		category=inputCore.SCRCAT_MISC,
+		category=scriptCategories.SCRCAT_MISC,
 		gestures=["kb:NVDA+shift+t", "kb:NVDA+alt+r"]
 	)
 	def script_sayDateTime(self, gesture):
@@ -421,7 +421,7 @@ The following keyword arguments can be used when applying the script decorator:
 - category: The category of the script in order for it to be grouped with other similar scripts.
   For example, a script in a global plugin which adds browse mode quick navigation keys may be categorized under the "Browse mode" category.
   The category can be set for individual scripts, but you can also set the "scriptCategory" attribute on the plugin class, which will be used for scripts which do not specify a category.
-  There are constants for common categories prefixed with SCRCAT_ in the inputCore and globalCommands modules, which can also be specified.
+  There are constants for common categories prefixed with SCRCAT_ in the scriptCategories module, which can also be specified.
   The script will be listed under the specified category in the Input Gestures dialog.
   If no category is specified, the script will be categorized under "Miscellaneous".
 - gesture: A string containing a single gesture associated with this script, e.g. "kb:NVDA+shift+r".

source/NVDAObjects/IAccessible/__init__.py

@@ -637,6 +637,7 @@ def __init__(self,windowHandle=None,IAccessibleObject=None,IAccessibleChildID=No
 		self.event_objectID=event_objectID
 		self.event_childID=event_childID
 		super(IAccessible,self).__init__(windowHandle=windowHandle)
+		self.uniqueID = (self.windowHandle, self.IA2UniqueID)
 
 		try:
 			self.IAccessibleActionObject=IAccessibleObject.QueryInterface(IAccessibleHandler.IAccessibleAction)

source/NVDAObjects/UIA/__init__.py

@@ -297,6 +297,14 @@ def __init__(self,obj,position,_rangeObj=None):
 		elif position==textInfos.POSITION_LAST:
 			self._rangeObj=self.obj.UIATextPattern.documentRange
 			self.collapse(True)
+		elif position in (textInfos.POSITION_FIRSTVISIBLE, textInfos.POSITION_LASTVISIBLE):
+			try:
+				visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
+				element = 0 if position == textInfos.POSITION_FIRSTVISIBLE else visiRanges.length - 1
+				self._rangeObj = visiRanges.GetElement(element)
+			except COMError:
+				# Error: FIRST_VISIBLE/LAST_VISIBLE position not supported by the UIA text pattern.
+				raise NotImplementedError
 		elif position==textInfos.POSITION_ALL or position==self.obj:
 			self._rangeObj=self.obj.UIATextPattern.documentRange
 		elif isinstance(position,UIA) or isinstance(position,UIAHandler.IUIAutomationElement):
@@ -702,6 +710,25 @@ def compareEndPoints(self,other,which):
 			target=UIAHandler.TextPatternRangeEndpoint_End
 		return self._rangeObj.CompareEndpoints(src,other._rangeObj,target)
 
+	def _get_isOffscreen(self):
+		try:
+			visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
+		except COMError:
+			raise NotImplementedError
+		visiLength = visiRanges.length
+		if visiLength > 0:
+			firstVisiRange = visiRanges.GetElement(0)
+			lastVisiRange = visiRanges.GetElement(visiLength - 1)
+			return self._rangeObj.CompareEndPoints(
+				UIAHandler.TextPatternRangeEndpoint_Start, firstVisiRange,
+				UIAHandler.TextPatternRangeEndpoint_Start
+			) < 0 or self._rangeObj.CompareEndPoints(
+				UIAHandler.TextPatternRangeEndpoint_Start, lastVisiRange,
+				UIAHandler.TextPatternRangeEndpoint_End) >= 0
+		else:
+			# Review bounds not available.
+			return super(UIATextInfo, self).isOffscreen()
+
 	def setEndPoint(self,other,which):
 		if which.startswith('start'):
 			src=UIAHandler.TextPatternRangeEndpoint_Start
@@ -928,6 +955,7 @@ def __init__(self,windowHandle=None,UIAElement=None,initialUIACachedPropertyIDs=
 		if not windowHandle:
 			raise InvalidNVDAObject("no windowHandle")
 		super(UIA,self).__init__(windowHandle=windowHandle)
+		self.uniqueID =         self.UIAElement.getRuntimeId()
 
 		self.initialUIACachedPropertyIDs=initialUIACachedPropertyIDs
 		if initialUIACachedPropertyIDs:

source/NVDAObjects/UIA/winConsoleUIA.py

@@ -43,16 +43,6 @@ def collapse(self,end=False):
 			)
 
 	def move(self, unit, direction, endPoint=None):
-		oldRange = None
-		if self.basePosition != textInfos.POSITION_CARET:
-			# Insure we haven't gone beyond the visible text.
-			# UIA adds thousands of blank lines to the end of the console.
-			visiRanges = self.obj.UIATextPattern.GetVisibleRanges()
-			visiLength = visiRanges.length
-			if visiLength > 0:
-				firstVisiRange = visiRanges.GetElement(0)
-				lastVisiRange = visiRanges.GetElement(visiLength - 1)
-				oldRange = self._rangeObj.clone()
 		if unit == textInfos.UNIT_WORD and direction != 0:
 			# UIA doesn't implement word movement, so we need to do it manually.
 			# Relative to the current line, calculate our offset
@@ -106,18 +96,8 @@ def move(self, unit, direction, endPoint=None):
 						endPoint=endPoint
 					)
 		else:  # moving by a unit other than word
-			res = super(consoleUIATextInfo, self).move(unit, direction,
+			return super(consoleUIATextInfo, self).move(unit, direction,
 														endPoint)
-		if oldRange and (
-			self._rangeObj.CompareEndPoints(
-				UIAHandler.TextPatternRangeEndpoint_Start, firstVisiRange,
-				UIAHandler.TextPatternRangeEndpoint_Start) < 0
-			or self._rangeObj.CompareEndPoints(
-				UIAHandler.TextPatternRangeEndpoint_Start, lastVisiRange,
-				UIAHandler.TextPatternRangeEndpoint_End) >= 0):
-			self._rangeObj = oldRange
-			return 0
-		return res
 
 	def expand(self, unit):
 		if unit == textInfos.UNIT_WORD:
@@ -236,6 +216,8 @@ class WinConsoleUIA(Terminal):
 	#: Whether the console got new text lines in its last update.
 	#: Used to determine if typed character/word buffers should be flushed.
 	_hasNewLines = False
+	#: Bound consoles by default to maintain feature parity with legacy.
+	_defaultReviewBounds = True
 	#: the caret in consoles can take a while to move on Windows 10 1903 and later.
 	_caretMovementTimeoutMultiplier = 1.5
 

source/NVDAObjects/__init__.py

@@ -12,6 +12,7 @@
 import re
 import weakref
 from logHandler import log
+from scriptHandler import script
 import review
 import eventHandler
 from displayModel import DisplayModelTextInfo
@@ -28,6 +29,7 @@
 import braille
 import globalPluginHandler
 import brailleInput
+import scriptCategories
 
 class NVDAObjectTextInfo(textInfos.offsets.OffsetsTextInfo):
 	"""A default TextInfo which is used to enable text review of information about widgets that don't support text content.
@@ -1267,3 +1269,33 @@ def getSelectedItemsCount(self,maxCount=2):
 		For performance, this method will only count up to the given maxCount number, and if there is one more above that, then sys.maxint is returned stating that many items are selected.
 		"""
 		return 0
+
+	@script(gesture="kb:NVDA+o",
+		category=scriptCategories.SCRCAT_TEXTREVIEW,
+		# Translators: A gesture description.
+		description=_(u"Toggles whether review is constrained to the currently visible text"))
+	def script_toggleReviewBounds(self, gesture):
+		rp = api.getReviewPosition()
+		try:
+			outOfBounds = rp.isOffscreen
+		except NotImplementedError:
+			ui.message(
+				# Translators: Reported when review bound configuration isn't supported for this object.
+				_(u"Not supported here"))
+		else:
+			self.reviewBounded = not self.reviewBounded
+			if self.reviewBounded:
+				ui.message(
+					# Translators: Reported when review is constrained to this
+					# object's visible text.
+					_(u"Bounded review")
+				)
+				if outOfBounds:
+					api.setReviewPosition(
+						self.makeTextInfo(textInfos.POSITION_CARET))
+			else:
+				ui.message(
+					# Translators: Reported when review is unconstrained, so all
+					# of this object's text can be read.
+					_(u"Unbounded review")
+				)

source/NVDAObjects/window/__init__.py

@@ -167,6 +167,7 @@ def __init__(self,windowHandle=None):
 			raise ValueError("invalid or not specified window handle")
 		self.windowHandle=windowHandle
 		super(Window,self).__init__()
+		self.uniqueID = self.windowHandle
 
 	def _isEqual(self,other):
 		return super(Window,self)._isEqual(other) and other.windowHandle==self.windowHandle

source/displayModel.py

@@ -590,3 +590,8 @@ def _setSelectionOffsets(self,start,end):
 		if start!=end:
 			raise NotImplementedError("Expanded selections not supported")
 		self._setCaretOffset(start)
+
+	def isOffscreen(self):
+		"""DisplayModelTextInfo instances only show screen contents, so
+		unbounding is impossible."""
+		raise NotImplementedError

source/documentBase.py

@@ -10,13 +10,17 @@
 import speech
 import ui
 import controlTypes
+import globalVars
 
-class TextContainerObject(AutoPropertyObject):
+class TextContainerObject(ScriptableObject):
 	"""
 	An object that contains text which can be accessed via a call to a makeTextInfo method.
 	E.g. NVDAObjects, BrowseModeDocument TreeInterceptors.
 	"""
 
+	#: A unique ID to represent this object.
+	uniqueID = None
+
 	def _get_TextInfo(self):
 		raise NotImplementedError
 
@@ -29,6 +33,17 @@ def _get_selection(self):
 	def _set_selection(self,info):
 		info.updateSelection()
 
+	#: The default state for an object's review bounds.
+	_defaultReviewBounds = False
+
+	def _get_reviewBounded(self):
+		return globalVars.reviewBoundsStates.get(self.uniqueID, self._defaultReviewBounds)
+
+	def _set_reviewBounded(self, state):
+		if not self.uniqueID:
+			raise NotImplementedError
+		globalVars.reviewBoundsStates[self.uniqueID] = state
+
 class DocumentWithTableNavigation(TextContainerObject,ScriptableObject):
 	"""
 	A document that supports standard table navigiation comments (E.g. control+alt+arrows to move between table cells).
@@ -205,5 +220,3 @@ def script_toggleIncludeLayoutTables(self,gesture):
 		"kb:control+alt+rightArrow": "nextColumn",
 		"kb:control+alt+leftArrow": "previousColumn",
 	}
-
-

source/globalCommands.py

@@ -32,7 +32,7 @@
 import treeInterceptorHandler
 import browseMode
 import scriptHandler
-from scriptHandler import script
+from scriptCategories import *
 import ui
 import braille
 import brailleInput
@@ -44,49 +44,6 @@
 import winVersion
 from base64 import b16encode
 
-#: Script category for text review commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_TEXTREVIEW = _("Text review")
-#: Script category for Object navigation commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_OBJECTNAVIGATION = _("Object navigation")
-#: Script category for system caret commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_SYSTEMCARET = _("System caret")
-#: Script category for mouse commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_MOUSE = _("Mouse")
-#: Script category for speech commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_SPEECH = _("Speech")
-#: Script category for configuration dialogs commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_CONFIG = _("Configuration")
-#: Script category for configuration profile activation and management commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_CONFIG_PROFILES = _("Configuration profiles")
-#: Script category for Braille commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_BRAILLE = _("Braille")
-#: Script category for tools commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_TOOLS = pgettext('script category', 'Tools')
-#: Script category for touch commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_TOUCH = _("Touch screen")
-#: Script category for focus commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_FOCUS = _("System focus")
-#: Script category for system status commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_SYSTEM = _("System status")
-#: Script category for input commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_INPUT = _("Input")
-#: Script category for document formatting commands.
-# Translators: The name of a category of NVDA commands.
-SCRCAT_DOCUMENTFORMATTING = _("Document formatting")
-
 class GlobalCommands(ScriptableObject):
 	"""Commands that are available at all times, regardless of the current focus.
 	"""
@@ -972,8 +929,21 @@ def script_review_activate(self,gesture):
 	script_review_activate.__doc__=_("Performs the default action on the current navigator object (example: presses it if it is a button).")
 	script_review_activate.category=SCRCAT_OBJECTNAVIGATION
 
+	def _moveWithBoundsChecking(self, info, unit, direction, endPoint=None):
+		"""
+		Nondestructively moves a textInfo and returns a (newInfo, res) tuple.
+		Res is 0 and the original C{textInfo} is returned if the move would be out of bounds.
+		"""
+		newInfo = info.copy()
+		res = newInfo.move(unit, direction, endPoint=endPoint)
+		if newInfo.obj.reviewBounded and newInfo.isOffscreen:
+			return (info, 0)
+		return (newInfo, res)
+
 	def script_review_top(self,gesture):
-		info=api.getReviewPosition().obj.makeTextInfo(textInfos.POSITION_FIRST)
+		obj = api.getReviewPosition().obj
+		pos = textInfos.POSITION_FIRSTVISIBLE if obj.reviewBounded else textInfos.POSITION_FIRST
+		info = obj.makeTextInfo(pos)
 		api.setReviewPosition(info)
 		info.expand(textInfos.UNIT_LINE)
 		ui.reviewMessage(_("Top"))
@@ -987,7 +957,7 @@ def script_review_previousLine(self,gesture):
 		if info._expandCollapseBeforeReview:
 			info.expand(textInfos.UNIT_LINE)
 			info.collapse()
-		res=info.move(textInfos.UNIT_LINE,-1)
+		info, res = self._moveWithBoundsChecking(info, textInfos.UNIT_LINE,-1)
 		if res==0:
 			# Translators: a message reported when review cursor is at the top line of the current navigator object.
 			ui.reviewMessage(_("Top"))
@@ -1019,7 +989,7 @@ def script_review_nextLine(self,gesture):
 		if info._expandCollapseBeforeReview:
 			info.expand(textInfos.UNIT_LINE)
 			info.collapse()
-		res=info.move(textInfos.UNIT_LINE,1)
+		info, res = self._moveWithBoundsChecking(info, textInfos.UNIT_LINE,1)
 		if res==0:
 			# Translators: a message reported when review cursor is at the bottom line of the current navigator object.
 			ui.reviewMessage(_("Bottom"))
@@ -1033,7 +1003,9 @@ def script_review_nextLine(self,gesture):
 	script_review_nextLine.category=SCRCAT_TEXTREVIEW
 
 	def script_review_bottom(self,gesture):
-		info=api.getReviewPosition().obj.makeTextInfo(textInfos.POSITION_LAST)
+		obj = api.getReviewPosition().obj
+		pos = textInfos.POSITION_LASTVISIBLE if obj.reviewBounded else textInfos.POSITION_LAST
+		info = obj.makeTextInfo(pos)
 		api.setReviewPosition(info)
 		info.expand(textInfos.UNIT_LINE)
 		ui.reviewMessage(_("Bottom"))
@@ -1047,7 +1019,7 @@ def script_review_previousWord(self,gesture):
 		if info._expandCollapseBeforeReview:
 			info.expand(textInfos.UNIT_WORD)
 			info.collapse()
-		res=info.move(textInfos.UNIT_WORD,-1)
+		info, res = self._moveWithBoundsChecking(info, textInfos.UNIT_WORD,-1)
 		if res==0:
 			# Translators: a message reported when review cursor is at the top line of the current navigator object.
 			ui.reviewMessage(_("Top"))
@@ -1078,7 +1050,7 @@ def script_review_nextWord(self,gesture):
 		if info._expandCollapseBeforeReview:
 			info.expand(textInfos.UNIT_WORD)
 			info.collapse()
-		res=info.move(textInfos.UNIT_WORD,1)
+		info, res = self._moveWithBoundsChecking(info, textInfos.UNIT_WORD,1)
 		if res==0:
 			# Translators: a message reported when review cursor is at the bottom line of the current navigator object.
 			ui.reviewMessage(_("Bottom"))
@@ -1206,7 +1178,7 @@ def _getCurrentLanguageForTextInfo(self, info):
 			curLanguage = speech.getCurrentLanguage()
 		return curLanguage
 
-	@script(
+	@scriptHandler.script(
 		# Translators: Input help mode message for Review Current Symbol command.
 		description=_("Reports the symbol where the review cursor is positioned. Pressed twice, shows the symbol and the text used to speak it in browse mode"),
 		category=SCRCAT_TEXTREVIEW,

source/globalVars.py

@@ -1,6 +1,6 @@
 #globalVars.py
 #A part of NonVisual Desktop Access (NVDA)
-#Copyright (C) 2006-2007 NVDA Contributors <http://www.nvda-project.org/>
+#Copyright (C) 2006-2019 NVDA Contributors, Bill Dengler <http://www.nvda-project.org/>
 #This file is covered by the GNU General Public License.
 #See the file COPYING for more details.
 """global variables module
@@ -18,6 +18,8 @@
 @type navigatorObject: L{NVDAObjects.NVDAObject}
 @var navigatorTracksFocus: if true, the navigator object will follow the focus as it changes
 @type navigatorTracksFocus: boolean
+@var reviewBoundsStates: maps object unique IDs to their review bounds states, needed for persistence when an object is regenerated.
+@type reviewBoundsStates: dict
 """
 
 startTime=0
@@ -32,6 +34,7 @@
 navigatorObject=None
 reviewPosition=None
 reviewPositionObj=None
+reviewBoundsStates = dict()
 lastProgressValue=0
 appArgs=None
 appArgsExtra=None