Add script to toggle mouse audio coordinates (#19026) (#19282)

Fixes #19026
Summary of the issue:

This PR adds a new global script script_toggleMouseAudioCoordinates in globalCommands.py.

The script:

    Appears in the Mouse category of the Input Gestures dialog.
    Toggles the existing mouse/audioCoordinatesOnMouseMove configuration value using toggleBooleanValue.
    Announces “Mouse audio coordinates on/off” when toggled.

No default gesture is assigned in code.
Users can bind any gesture they like from NVDA menu → Preferences → Input gestures… → Mouse.
Description of user facing changes:

Adds a new script in the Mouse category of the Input Gestures dialog that allows users to assign a gesture to toggle mouse audio coordinates (beeps that report mouse location).
There is no behavior change unless a user assigns a gesture.
Description of developer facing changes:

-Adds script_toggleMouseAudioCoordinates to GlobalCommands in globalCommands.py.

    Uses the existing toggleBooleanValue helper to toggle config.conf["mouse"]["audioCoordinatesOnMouseMove"].
    No changes to public APIs or configuration schema.

Description of development approach:

Reuse the existing toggleBooleanValue helper to avoid duplicating toggle logic and messages.
Only globalCommands.py is updated; no new settings or gesture defaults are added.
Testing strategy:

    Ran NVDA from source using runnvda.bat.
    Opened Preferences → Input gestures… → Mouse.
    Confirmed that a new script “Toggles beeps that report mouse coordinates as the mouse moves” is present.
    Assigned a temporary gesture (e.g. NVDA+Shift+M) and verified that:
        The gesture toggles the “Play audio coordinates when mouse moves” option.
        NVDA reports “Mouse audio coordinates on/off”.

Author: rlawnsrl123

source/globalCommands.py

@@ -3042,6 +3042,23 @@ def script_toggleMouseTracking(self, gesture):
 			config.conf["mouse"]["enableMouseTracking"] = True
 		ui.message(state)
 
+	@script(
+		# Translators: Input help mode message for toggle mouse audio coordinates command.
+		description=_("Toggles beeps that report mouse coordinates as the mouse moves"),
+		category=SCRCAT_MOUSE,
+	)
+	def script_toggleMouseAudioCoordinates(self, gesture: inputCore.InputGetsture):
+		# Translators: Reported when mouse audio coordinates are toggled on.
+		enabledMsg = _("Mouse audio coordinates on")
+		# Translators: Reported when mouse audio coordinates are toggled off.
+		disabledMsg = _("Mouse audio coordinates off")
+		toggleBooleanValue(
+			configSection="mouse",
+			configKey="audioCoordinatesOnMouseMove",
+			enabledMsg=enabledMsg,
+			disabledMsg=disabledMsg,
+		)
+
 	@script(
 		# Translators: Input help mode message for toggle mouse text unit resolution command.
 		description=_("Toggles how much text will be spoken when the mouse moves"),

user_docs/en/changes.md

@@ -333,6 +333,7 @@ Localisation data for emojis has been added for Belarusian and Bosnian.
   * Installation date will now be also shown in the details area for external add-ons. (#18560, @CyrilleB79)
 * A new unassigned command has been added to send `control+alt+delete` when controlling another computer via NVDA Remote Access. (#18105)
 * A new setting has been added to automatically mute Remote Access when controlling the local computer. (#18630)
+* A new unassigned global command has been added to toggle the "Play audio coordinates when mouse moves" option. (#19026, @rlawnsrl123)
 
 ### Changes
 

user_docs/en/userGuide.md

@@ -952,6 +952,7 @@ Although a physical mouse or trackpad should be used to navigate with the mouse,
 |Scroll right at the mouse position |none |none |none |Scrolls the mouse wheel right at the current mouse position|
 |Move mouse to current navigator object |NVDA+numpadDivide |NVDA+shift+m |none |Moves the mouse to the location of the current navigator object and review cursor|
 |Navigate to the object under the mouse |NVDA+numpadMultiply |NVDA+shift+n |none |Set the navigator object to the object located at the position of the mouse|
+|Toggle mouse audio coordinates |none |none |none |Toggles whether NVDA plays audio beeps that report the mouse position as it moves.|
 
 <!-- KC:endInclude -->
 
@@ -2811,6 +2812,7 @@ Note that the announcement of some object details might be dependent on how othe
 Checking this checkbox makes NVDA play beeps as the mouse moves, so that the user can work out where the mouse is in regards to the dimensions of the screen.
 The higher the mouse is on the screen, the higher the pitch of the beeps.
 The further left or right the mouse is located on the screen, the further left or right the sound will be played (assuming the user has stereo speakers or headphones).
+You can also assign a custom gesture in the Mouse category of the Input Gestures dialog to toggle this option.
 
 ##### Brightness controls audio coordinates volume {#MouseSettingsBrightness}