Script decorator: add ability to specify that given script should be …

…active in sleep mode. (#11979)

* Script decorator: Allow to set `allowInSleepMode` for a decorated script.

* Also take this oportunity to use type hints for script decorator parameters

* Unit test for allowInSleepMode

* Mention `allowInSleepMode` in script decorator's docstring

* Lint fixes

* Update developer guide

* Update what's new

Co-authored-by: Michael Curran <[email protected]>

devDocs/developerGuide.t2t

@@ -478,6 +478,8 @@ The following keyword arguments can be used when applying the script decorator:
   This option defaults to False.
 - bypassInputHelp: A boolean indicating whether this script should run when input help is active.
   This option defaults to False.
+- allowInSleepMode: A boolean indicating whether this script should run when sleep mode is active.
+  This option defaults to False.
 - resumeSayAllMode: The say all mode that should be resumed when active before executing this script.
   The constants for say all mode are prefixed with CURSOR_ and specified in the sayAllHandler modules.
   If resumeSayAllMode is not specified, say all does not resume after this script.

source/scriptHandler.py

@@ -1,9 +1,9 @@
-# scriptHandler.py
 # A part of NonVisual Desktop Access (NVDA)
 # Copyright (C) 2007-2020 NV Access Limited, Babbage B.V., Julien Cochuyt
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
+from typing import List, Optional
 import time
 import weakref
 import inspect
@@ -241,32 +241,27 @@ def isScriptWaiting():
 	return bool(_numScriptsQueued)
 
 def script(
-	description="",
-	category=None,
-	gesture=None,
-	gestures=None,
-	canPropagate=False,
-	bypassInputHelp=False,
-	resumeSayAllMode=None
+		description: str = "",
+		category: Optional[str] = None,
+		gesture: Optional[str] = None,
+		gestures: Optional[List[str]] = None,
+		canPropagate: bool = False,
+		bypassInputHelp: bool = False,
+		allowInSleepMode: bool = False,
+		resumeSayAllMode: Optional[int] = None
 ):
 	"""Define metadata for a script.
 	This function is to be used as a decorator to set metadata used by the scripting system and gesture editor.
 	It can only decorate methods which name start swith "script_"
 	@param description: A short translatable description of the script to be used in the gesture editor, etc.
-	@type description: string 
 	@param category: The category of the script displayed in the gesture editor.
-	@type category: string
 	@param gesture: A gesture associated with this script.
-	@type gesture: string
 	@param gestures: A list of gestures associated with this script
-	@type gestures: list(string)
 	@param canPropagate: Whether this script should also apply when it belongs to a  focus ancestor object.
-	@type canPropagate: bool
 	@param bypassInputHelp: Whether this script should run when input help is active.
-	@type bypassInputHelp: bool
+	@param allowInSleepMode: Whether this script should run when NVDA is in sleep mode.
 	@param resumeSayAllMode: The say all mode that should be resumed when active before executing this script.
-		One of the C{sayAllHandler.CURSOR_*} constants.
-	@type resumeSayAllMode: int
+	One of the C{sayAllHandler.CURSOR_*} constants.
 	"""
 	if gestures is None:
 		gestures = []
@@ -295,5 +290,6 @@ def script_decorator(decoratedScript):
 		decoratedScript.bypassInputHelp = bypassInputHelp
 		if resumeSayAllMode is not None:
 			decoratedScript.resumeSayAllMode = resumeSayAllMode
+		decoratedScript.allowInSleepMode = allowInSleepMode
 		return decoratedScript
 	return script_decorator

tests/unit/test_scriptHandler.py

@@ -1,13 +1,12 @@
-#tests/unit/test_scriptHandler.py
-#A part of NonVisual Desktop Access (NVDA)
-#This file is covered by the GNU General Public License.
-#See the file COPYING for more details.
-#Copyright (C) 2018-2019 NV Access Limited, Babbage B.V.
+# A part of NonVisual Desktop Access (NVDA)
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
+# Copyright (C) 2018-2021 NV Access Limited, Babbage B.V., Łukasz Golonka
 
 """Unit tests for the scriptHandler module."""
 
 import unittest
-from scriptHandler import *
+from scriptHandler import script
 from inputCore import SCRCAT_MISC
 from sayAllHandler import CURSOR_CARET
 
@@ -22,6 +21,7 @@ def test_scriptdecoration(self):
 			gestures=["kb:b", "kb:c"],
 			canPropagate=True,
 			bypassInputHelp=True,
+			allowInSleepMode=True,
 			resumeSayAllMode=CURSOR_CARET
 		)
 		def script_test(self, gesture):
@@ -32,4 +32,5 @@ def script_test(self, gesture):
 		self.assertCountEqual(script_test.gestures, ["kb:a", "kb:b", "kb:c"])
 		self.assertTrue(script_test.canPropagate)
 		self.assertTrue(script_test.bypassInputHelp)
+		self.assertTrue(script_test.allowInSleepMode)
 		self.assertEqual(script_test.resumeSayAllMode, CURSOR_CARET)

user_docs/en/changes.t2t

@@ -22,6 +22,7 @@ What's New in NVDA
   - Instead, override `_getText` which returns a string of all text in the object.
 - `LiveText` objects can now calculate diffs by character. (#11639)
   - To alter the diff behaviour for some object, override the `diffAlgo` property (see the docstring for details).
+- When defining a script with the script decorator, the 'allowInSleepMode' boolean argument can be specified to control  if a script is available in sleep mode or not. (#11979)
 
 
 = 2020.4 =