Merge f6d69eb into 6d97c5a

rmcpantoja · web-flow · commit d49a6f54508c · 2024-02-02T16:09:46.000Z
diff --git a/source/globalCommands.py b/source/globalCommands.py
@@ -114,6 +114,10 @@
 # Translators: The name of a category of NVDA commands.
 SCRCAT_DOCUMENTFORMATTING = _("Document formatting")
 
+# Translators: Reported when there are no settings to configure in synth settings ring
+# (example: when there is no setting for language).
+NO_SETTINGS_MSG = _("No settings")
+
 class GlobalCommands(ScriptableObject):
 	"""Commands that are available at all times, regardless of the current focus.
 	"""
@@ -312,6 +316,32 @@ def script_dateTime(self,gesture):
 			text=winKernel.GetDateFormatEx(winKernel.LOCALE_NAME_USER_DEFAULT, winKernel.DATE_LONGDATE, None, None)
 		ui.message(text)
 
+	@script(
+		# Translators: Input help mode message for set the first value in the synth ring setting.
+		description=_("Set the first value of the current setting in the synth settings ring"),
+		category=SCRCAT_SPEECH
+	)
+	def script_firstValueSynthRing(self, gesture: inputCore.InputGesture):
+		settingName = globalVars.settingsRing.currentSettingName
+		if not settingName:
+			ui.message(NO_SETTINGS_MSG)
+			return
+		settingValue = globalVars.settingsRing.first()
+		ui.message("%s %s" % (settingName, settingValue))
+
+	@script(
+		# Translators: Input help mode message for set the last value in the synth ring settings.
+		description=_("Set the last value of the current setting in the synth settings ring"),
+		category=SCRCAT_SPEECH
+	)
+	def script_lastValueSynthRing(self, gesture: inputCore.InputGesture):
+		settingName = globalVars.settingsRing.currentSettingName
+		if not settingName:
+			ui.message(NO_SETTINGS_MSG)
+			return
+		settingValue = globalVars.settingsRing.last()
+		ui.message("%s %s" % (settingName, settingValue))
+
 	@script(
 		# Translators: Input help mode message for increase synth setting value command.
 		description=_("Increases the currently active setting in the synth settings ring"),
@@ -321,12 +351,25 @@ def script_dateTime(self,gesture):
 	def script_increaseSynthSetting(self,gesture):
 		settingName=globalVars.settingsRing.currentSettingName
 		if not settingName:
-			# Translators: Reported when there are no settings to configure in synth settings ring (example: when there is no setting for language).
-			ui.message(_("No settings"))
+			ui.message(NO_SETTINGS_MSG)
 			return
 		settingValue=globalVars.settingsRing.increase()
 		ui.message("%s %s" % (settingName,settingValue))
 
+	@script(
+		# Translators: Input help mode message for increasing synth setting value command in larger steps.
+		description=_("Increases the currently active setting in the synth settings ring in a larger step"),
+		category=SCRCAT_SPEECH,
+		gestures=("kb(desktop):NVDA+control+pageUp", "kb(laptop):NVDA+shift+control+pageUp")
+	)
+	def script_increaseLargeSynthSetting(self, gesture: inputCore.InputGesture):
+		settingName = globalVars.settingsRing.currentSettingName
+		if not settingName:
+			ui.message(NO_SETTINGS_MSG)
+			return
+		settingValue = globalVars.settingsRing.increaseLarge()
+		ui.message("%s %s" % (settingName, settingValue))
+
 	@script(
 		# Translators: Input help mode message for decrease synth setting value command.
 		description=_("Decreases the currently active setting in the synth settings ring"),
@@ -336,11 +379,25 @@ def script_increaseSynthSetting(self,gesture):
 	def script_decreaseSynthSetting(self,gesture):
 		settingName=globalVars.settingsRing.currentSettingName
 		if not settingName:
-			ui.message(_("No settings"))
+			ui.message(NO_SETTINGS_MSG)
 			return
 		settingValue=globalVars.settingsRing.decrease()
 		ui.message("%s %s" % (settingName,settingValue))
 
+	@script(
+		# Translators: Input help mode message for decreasing synth setting value command in larger steps.
+		description=_("Decreases the currently active setting in the synth settings ring in a larger step"),
+		category=SCRCAT_SPEECH,
+		gestures=("kb(desktop):NVDA+control+pageDown", "kb(laptop):NVDA+control+shift+pageDown")
+	)
+	def script_decreaseLargeSynthSetting(self, gesture: inputCore.InputGesture):
+		settingName = globalVars.settingsRing.currentSettingName
+		if not settingName:
+			ui.message(NO_SETTINGS_MSG)
+			return
+		settingValue = globalVars.settingsRing.decreaseLarge()
+		ui.message("%s %s" % (settingName, settingValue))
+
 	@script(
 		# Translators: Input help mode message for next synth setting command.
 		description=_("Moves to the next available setting in the synth settings ring"),
@@ -350,7 +407,7 @@ def script_decreaseSynthSetting(self,gesture):
 	def script_nextSynthSetting(self,gesture):
 		nextSettingName=globalVars.settingsRing.next()
 		if not nextSettingName:
-			ui.message(_("No settings"))
+			ui.message(NO_SETTINGS_MSG)
 			return
 		nextSettingValue=globalVars.settingsRing.currentSettingValue
 		ui.message("%s %s"%(nextSettingName,nextSettingValue))
@@ -364,7 +421,7 @@ def script_nextSynthSetting(self,gesture):
 	def script_previousSynthSetting(self,gesture):
 		previousSettingName=globalVars.settingsRing.previous()
 		if not previousSettingName:
-			ui.message(_("No settings"))
+			ui.message(NO_SETTINGS_MSG)
 			return
 		previousSettingValue=globalVars.settingsRing.currentSettingValue
 		ui.message("%s %s"%(previousSettingName,previousSettingValue))
diff --git a/source/synthSettingsRing.py b/source/synthSettingsRing.py
@@ -3,7 +3,7 @@
 import synthDriverHandler
 import queueHandler
 from autoSettingsUtils.driverSetting import BooleanDriverSetting, NumericDriverSetting
-
+from typing import Any
 
 class SynthSetting(baseObject.AutoPropertyObject):
 	"""a numeric synth setting. Has functions to set, get, increase and decrease its value """
@@ -13,17 +13,42 @@ def __init__(self,synth,setting,min=0,max=100):
 		self.min = setting.minVal if isinstance(setting, NumericDriverSetting) else min
 		self.max = setting.maxVal if isinstance(setting, NumericDriverSetting) else max
 		self.step = setting.normalStep if isinstance(setting, NumericDriverSetting) else 1
+		self.largeStep = self.setting.largeStep if isinstance(setting, NumericDriverSetting) else 10
+
+	def first(self) -> Any:
+		"""Sets the value of the current synth setting to the first value."""
+		val = self.min
+		self.value = val
+		return self._getReportValue(val)
+
+	def last(self) -> Any:
+		"""Sets the value of the current synth setting to the last value."""
+		val = self.max
+		self.value = val
+		return self._getReportValue(val)
 
 	def increase(self):
 		val = min(self.max,self.value+self.step)
 		self.value = val
 		return self._getReportValue(val)
 
+	def increaseLarge(self) -> Any:
+		"""Increases the value of the current synth setting by a larger step."""
+		val = min(self.max, self.value + self.largeStep * 2)
+		self.value = val
+		return self._getReportValue(val)
+
 	def decrease(self):
 		val = max(self.min,self.value-self.step)
 		self.value = val
 		return self._getReportValue(val)
 
+	def decreaseLarge(self) -> Any:
+		"""Decreases the value of the current synth setting by a larger step."""
+		val = max(self.min, self.value - self.largeStep * 2)
+		self.value = val
+		return self._getReportValue(val)
+
 	def _get_value(self):
 		return getattr(self.synth,self.setting.id)
 
@@ -124,18 +149,42 @@ def previous(self):
 			return self.currentSettingName
 		return None
 
+	def first(self) -> Any:
+		""" set the current setting to the first value """
+		if self._current is not None:
+			return self.settings[self._current].first()
+		return None
+
+	def last(self) -> Any:
+		""" set the current setting to the last value """
+		if self._current is not None:
+			return self.settings[self._current].last()
+		return None
+
 	def increase(self):
 		""" increases the currentSetting and returns its new value """
 		if self._current is not None:
 			return self.settings[self._current].increase()
 		return None
 
+	def increaseLarge(self) -> Any:
+		""" increases the currentSetting in a larger step, (20 items, 20%) and returns its new value """
+		if self._current is not None:
+			return self.settings[self._current].increaseLarge()
+		return None
+
 	def decrease(self):
 		""" decreases the currentSetting and returns its new value """
 		if self._current is not None:
 			return self.settings[self._current].decrease()
 		return None
 
+	def decreaseLarge(self) -> Any:
+		""" Decreases the currentSetting in a larger step, (20 items, 20%) and returns its new value """
+		if self._current is not None:
+			return self.settings[self._current].decreaseLarge()
+		return None
+
 	def updateSupportedSettings(self,synth):
 		import ui
 		from scriptHandler import _isScriptRunning
diff --git a/user_docs/en/changes.t2t b/user_docs/en/changes.t2t
@@ -7,6 +7,15 @@ What's New in NVDA
 
 == New Features ==
 - 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)
+    - Setting the first/last setting in the synth settings ring has no assigned gesture
+    - Decrease and increase the current setting of the synth settings ring in a larger step:
+      - Desktop: ``NVDA+control+pageUp`` or ``NVDA+control+pageDown``.
+      - Laptop: ``NVDA+control+shift+pageUp`` or ``NVDA+control+shift+pageDown``.
+      -
+    -
+  -
 - Added support for the BrailleEdgeS2 braille device. (#16033)
 -
 
diff --git a/user_docs/en/userGuide.t2t b/user_docs/en/userGuide.t2t
@@ -237,7 +237,14 @@ The actual commands will not execute while in input help mode.
 | Move to next synth setting | ``NVDA+control+rightArrow`` | ``NVDA+shift+control+rightArrow`` | Moves to the next available speech setting after the current, wrapping around to the first setting again after the last |
 | Move to previous synth setting | ``NVDA+control+leftArrow`` | ``NVDA+shift+control+leftArrow`` | Moves to the next available speech setting before the current, wrapping around to the last setting after the first |
 | Increment current synth setting | ``NVDA+control+upArrow`` | ``NVDA+shift+control+upArrow`` | increases the current speech setting you are on. E.g. increases the rate, chooses the next voice, increases the volume |
+| Increment the current synth setting in a larger step | ``NVDA+control+pageUp`` | ``NVDA+shift+control+pageUp`` | Increases the value of the current speech setting you're on in larger steps. e.g. when you're on a voice setting, it will jump forward every 20 voices; when you're on slider settings (rate, pitch, etc) it will jump forward the value up to 20% |
+
 | Decrement current synth setting | ``NVDA+control+downArrow`` | ``NVDA+shift+control+downArrow`` | decreases the current speech setting you are on. E.g. decreases the rate, chooses the previous voice, decreases the volume |
+| Decrement the current synth setting in a larger step | ``NVDA+control+pageDown`` | ``NVDA+shift+control+pageDown`` | Decreases the value of the current speech setting you're on in larger steps. e.g. when you're on a voice setting, it will jump backward every 20 voices; when you're on a slider setting, it will jump backward the value up to 20%. |
+
+It is also possible to set the first or last value of the current synth setting by assign custom gestures in [Input Gestures dialog #InputGestures], under the speech category.
+This means, for example, when you're on a rate setting, it will set the rate to 0 or 100.
+When you're on a voice setting, it will set the first or last voice.
 
 +++ Web navigation +++[WebNavigation]
 The full list of Single Letter Navigation keys is in the [Browse Mode #BrowseMode] section of the user guide.
@@ -1658,7 +1665,9 @@ If you wish to quickly change speech settings without going to the Speech catego
 | Move to next synth setting | NVDA+control+rightArrow | NVDA+shift+control+rightArrow | Moves to the next available speech setting after the current, wrapping around to the first setting again after the last |
 | Move to previous synth setting | NVDA+control+leftArrow | NVDA+shift+control+leftArrow | Moves to the next available speech setting before the current, wrapping around to the last setting after the first |
 | Increment current synth setting | NVDA+control+upArrow | NVDA+shift+control+upArrow | increases the current speech setting you are on. E.g. increases the rate, chooses the next voice, increases the volume |
+| Increment the current synth setting in a larger step | ``NVDA+control+pageUp`` | ``NVDA+shift+control+pageUp`` | Increases the value of the current speech setting you're on in larger steps. e.g. when you're on a voice setting, it will jump forward every 20 voices; when you're on slider settings (rate, pitch, etc) it will jump forward the value up to 20% |
 | Decrement current synth setting | NVDA+control+downArrow | NVDA+shift+control+downArrow | decreases the current speech setting you are on. E.g. decreases the rate, chooses the previous voice, decreases the volume |
+| Decrement the current synth setting in a larger step | ``NVDA+control+pageDown`` | ``NVDA+shift+control+pageDown`` | Decreases the value of the current speech setting you're on in larger steps. e.g. when you're on a voice setting, it will jump backward every 20 voices; when you're on a slider setting, it will jump backward the value up to 20% |
 %kc:endInclude
 
 +++ Braille +++[BrailleSettings]
