Make figure reporting configureable, and figures quick navigable (#16176

)

fixes #10826
Fixes #14349

Summary of the issue:
It has hitherto not been possible to navigate by figure with quick navigation keys, or to disable the reporting of figures and captions.

Description of user facing changes
Added a script to jump to next/previous figure in browse mode. Added an option to disable the reporting of figures and captions, and a script to toggle this setting.

Description of development approach
Examined similar code and based new code on existing code.

source/browseMode.py

@@ -1006,6 +1006,17 @@ def _get_disableAutoPassThrough(self):
 	# Translators: Message presented when the browse mode element is not found.
 	prevError=_("no previous tab")
 )
+qn(
+	"figure", key=None,
+	# Translators: Input help message for a quick navigation command in browse mode.
+	nextDoc=_("moves to the next figure"),
+	# Translators: Message presented when the browse mode element is not found.
+	nextError=_("no next figure"),
+	# Translators: Input help message for a quick navigation command in browse mode.
+	prevDoc=_("moves to the previous figure"),
+	# Translators: Message presented when the browse mode element is not found.
+	prevError=_("no previous figure")
+)
 qn(
 	"textParagraph",
 	key="p",

source/config/configSpec.py

@@ -234,6 +234,7 @@
 	reportLandmarks = boolean(default=true)
 	reportArticles = boolean(default=false)
 	reportFrames = boolean(default=true)
+	reportFigures = boolean(default=true)
 	reportClickable = boolean(default=true)
 
 [documentNavigation]

source/globalCommands.py

@@ -986,6 +986,24 @@ def script_toggleReportClickable(self,gesture):
 			config.conf["documentFormatting"]["reportClickable"]=True
 		ui.message(state)
 
+	@script(
+		# Translators: Input help mode message for toggle report figures and captions command.
+		description=_("Toggles on and off the reporting of figures and captions"),
+		category=SCRCAT_DOCUMENTFORMATTING
+	)
+	def script_toggleReportFigures(self, gesture: inputCore.InputGesture):
+		if config.conf["documentFormatting"]["reportFigures"]:
+			# Translators: The message announced when toggling the report figures and captions document formatting
+			# setting.
+			state = _("report figures and captions off")
+			config.conf["documentFormatting"]["reportFigures"] = False
+		else:
+			# Translators: The message announced when toggling the report figures and captions document formatting
+			# setting.
+			state = _("report figures and captions on")
+			config.conf["documentFormatting"]["reportFigures"] = True
+		ui.message(state)
+
 	@script(
 		description=_(
 			# Translators: Input help mode message for cycle through automatic language switching mode command.

source/gui/settingsDialogs.py

@@ -2562,6 +2562,12 @@ def makeSettings(self, settingsSizer):
 		self.framesCheckBox = elementsGroup.addItem(wx.CheckBox(elementsGroupBox, label=_("Fra&mes")))
 		self.framesCheckBox.Value=config.conf["documentFormatting"]["reportFrames"]
 
+		self.figuresCheckBox = elementsGroup.addItem(
+			# Translators: This is the label for a checkbox in the
+			# document formatting settings panel.
+			wx.CheckBox(elementsGroupBox, label=_("&Figures and captions")))
+		self.figuresCheckBox.Value = config.conf["documentFormatting"]["reportFigures"]
+
 		# Translators: This is the label for a checkbox in the
 		# document formatting settings panel.
 		self.clickableCheckBox = elementsGroup.addItem(wx.CheckBox(elementsGroupBox, label=_("&Clickable")))
@@ -2617,6 +2623,7 @@ def onSave(self):
 		config.conf["documentFormatting"]["reportLandmarks"]=self.landmarksCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportArticles"] = self.articlesCheckBox.IsChecked()
 		config.conf["documentFormatting"]["reportFrames"]=self.framesCheckBox.Value
+		config.conf["documentFormatting"]["reportFigures"] = self.figuresCheckBox.Value
 		config.conf["documentFormatting"]["reportClickable"]=self.clickableCheckBox.Value
 
 

source/textInfos/__init__.py

@@ -108,6 +108,10 @@ def getPresentationCategory(
 				and not formatConfig["reportLandmarks"]
 			)
 			or (role == controlTypes.Role.REGION and (not name or not formatConfig["reportLandmarks"]))
+			or (
+				role in {controlTypes.Role.FIGURE, controlTypes.Role.CAPTION}
+				and not formatConfig["reportFigures"]
+			)
 		):
 			# This is just layout as far as the user is concerned.
 			return self.PRESCAT_LAYOUT

source/virtualBuffers/gecko_ia2.py

@@ -549,6 +549,11 @@ def _searchableAttribsForNodeType(self,nodeType):
 			attrs = [
 				{"IAccessible::role": [oleacc.ROLE_SYSTEM_PAGETAB]}
 			]
+		elif nodeType == "figure":
+			attrs = [
+				{"Iaccessible::role": [oleacc.ROLE_SYSTEM_GROUPING]},
+				{"IAccessible2::attribute_xml-roles": [VBufStorage_findMatch_word("figure")]}
+			]
 		else:
 			return None
 		return attrs

user_docs/en/changes.t2t

@@ -8,8 +8,10 @@ What's New in NVDA
 == New Features ==
 - New key commands:
   - New Quick Navigation command ``p`` for jumping to next/previous text paragraph in browse mode. (#15998, @mltony)
+  - New unassigned Quick Navigation command to jump to the next/previous figure. (#10826)
   -
 - Reporting row and column headers is now supported in contenteditable HTML elements. (#14113)
+- Added the option to disable the reporting of figures and captions in Document Formatting settings. (#10826, #14349)
 - In Windows 11, NVDA will announce alerts from voice typing and suggested actions including the top suggestion when copying data such as phone numbers to the clipboard (Windows 11 2022 Update and later). (#16009, @josephsl)
 - New input gestures:
   - Added commands to jump first, last, forward and backward through the synth settings ring. (#13768, #16095, @rmcpantoja)
@@ -19,6 +21,7 @@ What's New in NVDA
       - Laptop: ``NVDA+control+shift+pageUp`` or ``NVDA+control+shift+pageDown``.
       -
     -
+  - Added a new unassigned input gesture to toggle the reporting of figures and captions. (#10826, #14349)
   -
 - Added support for the BrailleEdgeS2 braille device. (#16033)
 - NVDA will keep the audio device awake after speech stops, in order to prevent the start of the next speech being clipped with some audio devices such as Bluetooth headphones. (#14386, @jcsteh, @mltony)

user_docs/en/userGuide.t2t

@@ -876,6 +876,7 @@ In addition to the quick navigation commands listed above, NVDA has commands tha
 To use these commands, you first need to assign gestures to them using the [Input Gestures dialog #InputGestures].
 Here is a list of available commands:
 - Article
+- Figure
 - Grouping
 - Tab
 -
@@ -2360,6 +2361,7 @@ You can configure reporting of:
   - Landmarks
   - Articles
   - Frames
+  - Figures and captions
   - Clickable
   -
 -