Improve Paragraph Navigation - add single and multi line break style (#13798)

Closes #13797

Summary of the issue:
Not all applications support navigating by paragraph (control + up/down arrow) natively.
A specific example is web browsers.

Description of how this pull request fixes the issue:
Add "Document Navigation" settings panel allowing explicit choice of strategy for navigating by paragraph:

Handled by application (default): No change in behavior. The application is responsible for responding to the key press.
Single line break: Use a single end of line character to define a paragraph boundary.
Multi line break: Use two or more end of line characters (I.E. at least one blank line) to define a paragraph boundary.
Fallback to "Handled by application" when single line break or double line break fails.

Description of changes for the user:
Paragraph navigation is now supported in editors, such as Notepad and Notepad++, which do not support this feature natively. For editors which already support paragraph navigation, such as WordPad, block style paragraphs (those separated by one or more blank lines) may now be navigated in addition to single line break paragraphs.
When selecting the default option, Handled by application, paragraph navigation performs exactly as it did before this feature was added.

Author: rob-aph

source/config/configSpec.py

@@ -1,7 +1,7 @@
 # -*- coding: UTF-8 -*-
 # A part of NonVisual Desktop Access (NVDA)
 # Copyright (C) 2006-2022 NV Access Limited, Babbage B.V., Davy Kager, Bill Dengler, Julien Cochuyt,
-# Joseph Lee, Dawid Pieper, mltony, Bram Duvigneau, Cyrille Bougot
+# Joseph Lee, Dawid Pieper, mltony, Bram Duvigneau, Cyrille Bougot, Rob Meredith
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
@@ -225,6 +225,9 @@
 	reportFrames = boolean(default=true)
 	reportClickable = boolean(default=true)
 
+[documentNavigation]
+	paragraphStyle = featureFlag(optionsEnum="ParagraphNavigationFlag", behaviorOfDefault="application")
+
 [reviewCursor]
 	simpleReviewMode = boolean(default=True)
 	followFocus = boolean(default=True)

source/config/featureFlagEnums.py

@@ -1,5 +1,5 @@
 # A part of NonVisual Desktop Access (NVDA)
-# Copyright (C) 2022 NV Access Limited, Bill Dengler
+# Copyright (C) 2022 NV Access Limited, Bill Dengler, Rob Meredith
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
@@ -67,6 +67,24 @@ def __bool__(self):
 		return self == BoolFlag.ENABLED
 
 
+class ParagraphNavigationFlag(DisplayStringEnum):
+	@property
+	def _displayStringLabels(self):
+		return {
+			# Translators: Label for a paragraph style in NVDA settings.
+			self.APPLICATION: _("Handled by application"),
+			# Translators: Label for a paragraph style in NVDA settings.
+			self.SINGLE_LINE_BREAK: _("Single line break"),
+			# Translators: Label for a paragraph style in NVDA settings.
+			self.MULTI_LINE_BREAK: _("Multi line break")
+		}
+
+	DEFAULT = enum.auto()
+	APPLICATION = enum.auto()
+	SINGLE_LINE_BREAK = enum.auto()
+	MULTI_LINE_BREAK = enum.auto()
+
+
 class WindowsTerminalStrategyFlag(DisplayStringEnum):
 	"""
 	A feature flag for defining how new text is calculated in Windows Terminal

source/cursorManager.py

@@ -1,8 +1,7 @@
-#cursorManager.py
-#A part of NonVisual Desktop Access (NVDA)
-#Copyright (C) 2006-2018 NV Access Limited, Joseph Lee, Derek Riemer, Davy Kager
-#This file is covered by the GNU General Public License.
-#See the file COPYING for more details.
+# A part of NonVisual Desktop Access (NVDA)
+# Copyright (C) 2006-2022 NV Access Limited, Joseph Lee, Derek Riemer, Davy Kager, Rob Meredith
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
 
 """
 Implementation of cursor managers.
@@ -26,9 +25,13 @@
 import braille
 import vision
 import controlTypes
-from inputCore import SCRCAT_BROWSEMODE
+from inputCore import (
+	SCRCAT_BROWSEMODE,
+	InputGesture,
+)
 import ui
 from textInfos import DocumentWithPageTurns
+from logHandler import log
 
 
 class FindDialog(
@@ -264,12 +267,35 @@ def script_moveBySentence_forward(self,gesture):
 		self._caretMovementScriptHelper(gesture,textInfos.UNIT_SENTENCE,1)
 	script_moveBySentence_forward.resumeSayAllMode = sayAll.CURSOR.CARET
 
-	def script_moveByParagraph_back(self,gesture):
-		self._caretMovementScriptHelper(gesture,textInfos.UNIT_PARAGRAPH,-1)
+	def _handleParagraphNavigation(self, gesture: InputGesture, nextParagraph: bool) -> None:
+		from config.featureFlagEnums import ParagraphNavigationFlag
+		flag: config.featureFlag.FeatureFlag = config.conf["documentNavigation"]["paragraphStyle"]
+		if (
+			flag.calculated() == ParagraphNavigationFlag.APPLICATION
+			or flag.calculated() == ParagraphNavigationFlag.SINGLE_LINE_BREAK
+		):
+			self._caretMovementScriptHelper(gesture, textInfos.UNIT_PARAGRAPH, 1 if nextParagraph else -1)
+		elif flag.calculated() == ParagraphNavigationFlag.MULTI_LINE_BREAK:
+			from documentNavigation.paragraphHelper import moveToMultiLineBreakParagraph
+			ti = self.makeTextInfo(textInfos.POSITION_SELECTION)
+			passKey, moved = moveToMultiLineBreakParagraph(
+				nextParagraph=nextParagraph,
+				speakNew=not willSayAllResume(gesture),
+				ti=ti)
+			if moved:
+				self.selection = ti
+			elif passKey:
+				# fail over to default behavior
+				self._caretMovementScriptHelper(gesture, textInfos.UNIT_PARAGRAPH, 1 if nextParagraph else -1)
+		else:
+			log.error(f"Unexpected ParagraphNavigationFlag value {flag.value}")
+
+	def script_moveByParagraph_back(self, gesture: InputGesture):
+		self._handleParagraphNavigation(gesture, False)
 	script_moveByParagraph_back.resumeSayAllMode = sayAll.CURSOR.CARET
 
-	def script_moveByParagraph_forward(self,gesture):
-		self._caretMovementScriptHelper(gesture,textInfos.UNIT_PARAGRAPH,1)
+	def script_moveByParagraph_forward(self, gesture: InputGesture):
+		self._handleParagraphNavigation(gesture, True)
 	script_moveByParagraph_forward.resumeSayAllMode = sayAll.CURSOR.CARET
 
 	def script_startOfLine(self,gesture):