add unassigned command to report the status of screen curtain (#19767)

Summary of the issue:

users needs a way to know what the current status of screen curtain is
. Previously , Users had to check the NVDA settings or perform the shortcut NVDA+CTRL+ESC to know what is the current status of the screen curtain if it is activated or deactivated.
Description of user facing changes:

Now, users can assign a new custom shortcut that when it is performed will allow the users to get a notification with the current status of the screen curtain .
Description of developer facing changes:

None
Description of development approach:

Added a new intrys with an if check in /source/globalCommands.py, and added new entrys in the changes and the user docs files

Author: makhlwf

source/globalCommands.py

@@ -4967,6 +4967,36 @@ def _enableScreenCurtain(doEnable: bool = True):
 					return
 				_enableScreenCurtain()
 
+	@script(
+		description=_(
+			# Translators: Describes a command.
+			"Reports the state of the screen curtain.",
+		),
+		category=SCRCAT_VISION,
+	)
+	def script_reportScreenCurtainState(self, gesture: inputCore.InputGesture) -> None:
+		import screenCurtain
+
+		if screenCurtain.screenCurtain is None:
+			# Screen curtain has not been initialized.
+			# Translators: Reported when the screen curtain is not available.
+			ui.message(_("Screen curtain not available"), speechPriority=speech.priorities.Spri.NOW)
+			return
+
+		if screenCurtain.screenCurtain.enabled:
+			if not screenCurtain.screenCurtain.settings["enabled"]:
+				# Translators: Reported when the screen curtain is temporarily enabled.
+				ui.message(
+					_("Temporary Screen curtain, enabled until next restart"),
+					speechPriority=speech.priorities.Spri.NOW,
+				)
+			else:
+				# Translators: Reported when the screen curtain is enabled.
+				ui.message(_("Screen curtain enabled"), speechPriority=speech.priorities.Spri.NOW)
+		else:
+			# Translators: Reported when the screen curtain is disabled.
+			ui.message(_("Screen curtain disabled"), speechPriority=speech.priorities.Spri.NOW)
+
 	@script(
 		description=_(
 			# Translators: Describes a command.

user_docs/en/changes.md

@@ -24,6 +24,7 @@
 Consult the speech dictionaries section in the User Guide for more details. (#19506, @LeonarddeR)
 * When resetting the configuration to factory defaults from the NVDA menu, a dialog is now shown afterwards with an Undo button to restore the previous configuration.
 The triple-press keyboard shortcut (`NVDA+ctrl+r`) is not affected, as it is intended for recovery scenarios. (#19575, @bramd)
+* Added an unassigned command to report the current status of the Screen Curtain. (#19759)
 
 ### Changes
 

user_docs/en/userGuide.md

@@ -1511,6 +1511,7 @@ You can enable Screen Curtain in the [Privacy and Security category](#PrivacyAnd
 | Name |Key |Description|
 |---|---|---|
 |Toggles the state of the screen curtain |`NVDA+control+escape` |Enable to make the screen black or disable to show the contents of the screen. Pressed once, screen curtain is enabled until you restart NVDA. Pressed twice, screen curtain is enabled until you disable it.|
+| Reports the state of the screen curtain | `None` | Announces the current status of the screen curtain, whether it is disabled or enabled or in temporary mode. |
 
 <!-- KC:endInclude -->