Merge 990c306 into 3f82ab6

nvdaes · web-flow · commit 754c78542630 · 2024-07-27T00:59:43.000Z
diff --git a/source/braille.py b/source/braille.py
@@ -330,6 +330,9 @@
 # used to separate chunks of text when programmatically joined
 TEXT_SEPARATOR = " "
 
+# Indicator at the start of paragraphs
+PARAGRAPH_START = " "
+
 #: Identifier for a focus context presentation setting that
 #: only shows as much as possible focus context information when the context has changed.
 CONTEXTPRES_CHANGEDCONTEXT = "changedContext"
@@ -1083,6 +1086,9 @@ def getFormatFieldBraille(field, fieldCache, isAtStart, formatConfig):
 	"""
 	textList = []
 	if isAtStart:
+		brailleConfig = config.conf["braille"]
+		if brailleConfig["readByParagraph"] and brailleConfig["showParagraphStart"]:
+			textList.append(PARAGRAPH_START)
 		if formatConfig["reportLineNumber"]:
 			lineNumber = field.get("line-number")
 			if lineNumber:
diff --git a/source/config/configSpec.py b/source/config/configSpec.py
@@ -83,6 +83,7 @@
 	reviewRoutingMovesSystemCaret = featureFlag(\
 		optionsEnum="ReviewRoutingMovesSystemCaretFlag", behaviorOfDefault="NEVER")
 	readByParagraph = boolean(default=false)
+	showParagraphStart = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="disabled")
 	wordWrap = boolean(default=true)
 	unicodeNormalization = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="disabled")
 	focusContextPresentation = option("changedContext", "fill", "scroll", default="changedContext")
diff --git a/source/gui/settingsDialogs.py b/source/gui/settingsDialogs.py
@@ -4363,8 +4363,22 @@ def makeSettings(self, settingsSizer):
 			wx.CheckBox(self.followCursorGroupBox, label=readByParagraphText),
 		)
 		self.bindHelpEvent("BrailleSettingsReadByParagraph", self.readByParagraphCheckBox)
+		self.readByParagraphCheckBox.Bind(wx.EVT_CHECKBOX, self.onReadByParagraphChange)
 		self.readByParagraphCheckBox.Value = config.conf["braille"]["readByParagraph"]
 
+		self.showParagraphStartCombo: nvdaControls.FeatureFlagCombo = followCursorGroupHelper.addLabeledControl(
+			labelText=_(
+				# Translators: This is a label for a combo-box in the Braille settings panel to select if start of paragraphs will be reported in braille.
+				"Show para&graph start",
+			),
+			wxCtrlClass=nvdaControls.FeatureFlagCombo,
+			keyPath=["braille", "showParagraphStart"],
+			conf=config.conf,
+		)
+		self.bindHelpEvent("BrailleShowParagraphStart", self.showParagraphStartCombo)
+		if not self.readByParagraphCheckBox.GetValue():
+			self.showParagraphStartCombo.Disable()
+
 		# Translators: The label for a setting in braille settings to select how the context for the focus object should be presented on a braille display.
 		focusContextPresentationLabelText = _("Focus context presentation:")
 		self.focusContextPresentationValues = [x[0] for x in braille.focusContextPresentations]
@@ -4459,6 +4473,7 @@ def onSave(self):
 			braille.handler.setTether(tetherChoice, auto=False)
 		self.brailleReviewRoutingMovesSystemCaretCombo.saveCurrentValueToConf()
 		config.conf["braille"]["readByParagraph"] = self.readByParagraphCheckBox.Value
+		self.showParagraphStartCombo.saveCurrentValueToConf()
 		config.conf["braille"]["wordWrap"] = self.wordWrapCheckBox.Value
 		self.unicodeNormalizationCombo.saveCurrentValueToConf()
 		config.conf["braille"]["focusContextPresentation"] = self.focusContextPresentationValues[
@@ -4484,6 +4499,9 @@ def onTetherToChange(self, evt: wx.CommandEvent) -> None:
 		tetherChoice = [x.value for x in TetherTo][evt.GetSelection()]
 		self.brailleReviewRoutingMovesSystemCaretCombo.Enable(tetherChoice != TetherTo.FOCUS.value)
 
+	def onReadByParagraphChange(self, evt):
+		self.showParagraphStartCombo.Enable(evt.IsChecked())
+
 	def _onModeChange(self, evt: wx.CommandEvent):
 		self.followCursorGroupBox.Enable(not evt.GetSelection())
 
diff --git a/user_docs/en/changes.md b/user_docs/en/changes.md
@@ -9,6 +9,7 @@
 * Enhanced Microsoft Word comment command: press twice to present comment content in browsable message. (#16800, @Cary-Rowen)
 * Enhanced Microsoft Excel notes command: press twice to present notes content in browsable message. (#16878, @Cary-Rowen)
 * NVDA can now be configured to report font attributes in speech and braille separately. (#16755)
+* When the "Read by paragraph" option is enabled, NVDA can now be configured to indicate the start of paragraphs in braille. (#16895,  @nvdaes)
 
 
 ### Bug Fixes
diff --git a/user_docs/en/userGuide.md b/user_docs/en/userGuide.md
@@ -2163,6 +2163,16 @@ This means that you do not have to scroll the display at the end of each line ev
 This may allow for more fluent reading of large amounts of text.
 It is disabled by default.
 
+##### Show paragraph start {#BrailleShowParagraphStart}
+| . {.hideHeaderRow} |.|
+|---|---|
+|Options |Default (Disabled), Enabled, Disabled|
+|Default |Disabled|
+
+If enabled and "Read by paragraph" is checked, two spaces will be displayed to indicate the start of a paragraph.
+This can be especially helpful in applications used to read large pieces of text, like structured documents or books.
+In such documents, knowing where paragraphs start maybe important to understand the structure of the content, or to set bookmarks or annotations based on paragraph position.
+
 ##### Avoid splitting words when possible {#BrailleSettingsWordWrap}
 
 If this is enabled, a word which is too large to fit at the end of the braille display will not be split.
