inputCore module

Core framework for handling input from the user. Every piece of input from the user (e.g. a key press) is represented by an L{InputGesture}. The singleton L{InputManager} (L{manager}) manages functionality related to input from the user. For example, it is used to execute gestures and handle input help.

inputCore.InputGestureScriptT

The Python class and script name for each script; the script name may be C{None} indicating that the gesture should be unbound for this class.

alias of Tuple[InputGestureBindingClassT, Optional[str]]

exception inputCore.NoInputGestureAction

Bases: LookupError

Informs that there is no action to execute for a gesture.

class inputCore.InputGesture(*args, **kwargs)

Bases: AutoPropertyObject

A single gesture of input from the user. For example, this could be a key press on a keyboard or Braille display or a click of the mouse. At the very least, subclasses must implement L{_get_identifiers}.

cachePropertiesByDefault = True

Specifies whether properties are cached by default; can be overridden for individual properties by setting _cache_propertyName. @type: bool

wasInSayAll = False

indicates that sayAll was running before this gesture @type: bool

bypassInputHelp = False

Indicates that while in Input Help Mode, this gesture should be handled as if Input Help mode was currently off. @type: bool

reportInInputHelp = True

Indicates that this gesture should be reported in Input help mode. This would only be false for flooding Gestures like touch screen hovers. @type: bool

shouldPreventSystemIdle: bool = False

Indicates whether executing this gesture should explicitly prevent the system from being idle. For example, the system is unaware of C{BrailleDisplayGesture} execution, and might even get into sleep mode when reading a long portion of text in braille. In contrast, the system is aware of C{KeyboardInputGesture} execution itself.

identifiers: List[str] | Tuple[str, ...]
_abstract_identifiers = True
_get_identifiers()

The identifier(s) which will be used in input gesture maps to represent this gesture. These identifiers will be normalized and looked up in order until a match is found. A single identifier should take the form: C{source:id} where C{source} is a few characters representing the source of this gesture and C{id} is the specific gesture. An example identifier is: C{kb(desktop):NVDA+1}

This property should not perform normalization itself. However, please note the following regarding normalization. If C{id} contains multiple chunks separated by a + sign, they are considered to be ordered arbitrarily and may be reordered when normalized. Normalization also ensures that the entire identifier is lower case. For example, NVDA+control+f1 and control+nvda+f1 will match when normalized. See L{normalizeGestureIdentifier} for more details.

Subclasses must implement this method. @return: One or more identifiers which uniquely identify this gesture. @rtype: list or tuple of str

normalizedIdentifiers: List[str]
_get_normalizedIdentifiers()

The normalized identifier(s) for this gesture. This just normalizes the identifiers returned in L{identifiers} by calling L{normalizeGestureIdentifier} for each identifier. These normalized identifiers can be directly looked up in input gesture maps. Subclasses should not override this method. @return: One or more normalized identifiers which uniquely identify this gesture. @rtype: list of str

displayName: str
_get_displayName()

The name of this gesture as presented to the user. The base implementation calls L{getDisplayTextForIdentifier} for the first identifier. Subclasses need not override this unless they wish to provide a more optimal implementation. @return: The display name. @rtype: str

shouldReportAsCommand = True

Whether this gesture should be reported when reporting of command gestures is enabled. @type: bool

isCharacter = False

whether this gesture represents a character being typed (i.e. not a potential command) @type bool

SPEECHEFFECT_CANCEL = 'cancel'
SPEECHEFFECT_PAUSE = 'pause'
SPEECHEFFECT_RESUME = 'resume'
speechEffectWhenExecuted = 'cancel'

The effect on speech when this gesture is executed; one of the SPEECHEFFECT_* constants or C{None}.

isModifier = False

Whether this gesture is only a modifier, in which case it will not search for a script to execute. @type: bool

reportExtra()

Report any extra information about this gesture to the user. This is called just after command gestures are reported. For example, it could be used to report toggle states.

_get_script()

The script bound to this input gesture. @return: The script to be executed. @rtype: script function

send()

Send this gesture to the operating system. This is not possible for all sources. @raise NotImplementedError: If the source does not support sending of gestures.

scriptableObject: ScriptableObject | None

typing information for autoproperty _get_scriptableObject

_get_scriptableObject() ScriptableObject | None

An object which contains scripts specific to this gesture or type of gesture. This object will be searched for scripts before any other object when handling this gesture. @return: The gesture specific scriptable object or C{None} if there is none.

classmethod getDisplayTextForIdentifier(identifier)

Get the text to be presented to the user describing a given gesture identifier. This should only be called with normalized gesture identifiers returned by the L{normalizedIdentifiers} property in the same subclass. For example, C{KeyboardInputGesture.getDisplayTextForIdentifier} should only be called for “kb:*” identifiers returned by C{KeyboardInputGesture.normalizedIdentifiers}. Most callers will want L{inputCore.getDisplayTextForIdentifier} instead. The display text consists of two strings: the gesture’s source (e.g. “laptop keyboard”) and the specific gesture (e.g. “alt+tab”). @param identifier: The normalized gesture identifier in question. @type identifier: str @return: A tuple of (source, specificGesture). @rtype: tuple of (str, str) @raise Exception: If no display text can be determined.

executeScript(script)

Executes the given script with this gesture, using scriptHandler.executeScript. This is only implemented so as to allow Gesture subclasses to perform an action directly before / after the script executes.

_abc_impl = <_abc._abc_data object>
script
class inputCore.GlobalGestureMap(entries: Dict[str, Dict[str | None, str | List[str] | None]] | None = None)

Bases: object

Maps gestures to scripts anywhere in NVDA. This is used to allow users and locales to bind gestures in addition to those bound by individual scriptable objects. Map entries will most often be loaded from a file using the L{load} method. See that method for details of the file format.

Constructor. @param entries: Initial entries to add; see L{update} for the format.

lastUpdateContainedError: bool

Indicates that the last load or update contained an error.

fileName: str | None

The file name for this gesture map, if any.

clear()

Clear this map.

add(gesture: str, module: str, className: str, script: str | None, replace: bool = False)

Add a gesture mapping. @param gesture: The gesture identifier. @param module: The name of the Python module containing the target script. @param className: The name of the class in L{module} containing the target script. @param script: The name of the target script

or C{None} to unbind the gesture for this class.

@param replace: if true replaces all existing bindings for this gesture with the given script,

otherwise only appends this binding.

load(filename: str)

Load map entries from a file. The file is an ini file. Each section contains entries for a particular scriptable object class. The section name must be the full Python module and class name. The key of each entry is the script name and the value is a comma separated list of one or more gestures. If the script name is “None”, the gesture will be unbound for this class. For example, the following binds the “a” key to move to the next heading in virtual buffers and removes the default “h” binding:

[virtualBuffers.VirtualBuffer]
nextHeading = kb:a
None = kb:h

@param filename: The name of the file to load.

update(entries: Dict[str, Dict[str | None, str | List[str] | None]])

Add multiple map entries. C{entries} must be a mapping of mappings. Each inner mapping contains entries for a particular scriptable object class. The key in the outer mapping must be the full Python module and class name. The key of each entry in the inner mappings is the script name and the value is one gesture string or a list of one or more gesture strings. If the script name is C{None}, the gesture will be unbound for this class. For example, the following binds the “a” key to move to the next heading in virtual buffers and removes the default “h” binding:

{
“virtualBuffers.VirtualBuffer”: {

“nextHeading”: “kb:a”, None: “kb:h”,

}

}

@param entries: The items to add.

getScriptsForGesture(gesture: str) Generator[Tuple[InputGestureBindingClassT, str | None], None, None]

Get the scripts associated with a particular gesture. @param gesture: The gesture identifier. @return: The Python class and script name for each script;

the script name may be C{None} indicating that the gesture should be unbound for this class.

getScriptsForAllGestures()

Get all of the scripts and their gestures. @return: The Python class, gesture and script name for each mapping;

the script name may be C{None} indicating that the gesture should be unbound for this class.

@rtype: generator of (class, str, str)

remove(gesture: str, module: str, className: str, script: str)

Remove a gesture mapping. @param gesture: The gesture identifier. @param module: The name of the Python module containing the target script. @param className: The name of the class in L{module} containing the target script. @param script: The name of the target script. @raise ValueError: If the requested mapping does not exist.

export() Dict[str, Dict[str | None, str | List[str] | None]]

Exports this gesture map to a dictionary that can be saved to disk or imported into another gesture map.

save()

Save this gesture map to disk. @precondition: L{load} must have been called.

inputCore.decide_executeGesture = <extensionPoints.Decider object>

Notifies when a gesture is about to be executed, and allows components or add-ons to decide whether or not to execute a gesture. For example, when controlling a remote system with a connected local braille display, braille display gestures should not be executed locally. Handlers are called with one argument: @param gesture: The gesture that is about to be executed. @type gesture: L{InputGesture}

class inputCore.InputManager(*args, **kwargs)

Bases: AutoPropertyObject

Manages functionality related to input from the user. Input includes key presses on the keyboard, as well as key presses on Braille displays, etc.

lastModifierWasInSayAll = False

a modifier gesture was just executed while sayAll was running @type: bool

_captureFunc

The function to call when capturing gestures. If it returns C{False}, normal execution will be prevented. @type: callable

localeGestureMap

The gestures mapped for the NVDA locale. @type: L{GlobalGestureMap}

userGestureMap

The gestures mapped by the user. @type: L{GlobalGestureMap}

executeGesture(gesture)

Perform the action associated with a gesture. @param gesture: The gesture to execute. @type gesture: L{InputGesture} @raise NoInputGestureAction: If there is no action to perform.

_get_isInputHelpActive()

Whether input help is enabled, wherein the function of each key pressed by the user is reported but not executed. @rtype: bool

_set_isInputHelpActive(enable)
_inputHelpCaptor(gesture)
_handleInputHelp(gesture, onlyLog=False)
loadUserGestureMap()
loadLocaleGestureMap()
emulateGesture(gesture)

Convenience method to emulate a gesture. First, an attempt will be made to execute the gesture using L{executeGesture}. If that fails, the gesture will be sent to the operating system if possible using L{InputGesture.send}. @param gesture: The gesture to execute. @type gesture: L{InputGesture}

getAllGestureMappings(obj=None, ancestors=None)
_abc_impl = <_abc._abc_data object>
property isInputHelpActive

Whether input help is enabled, wherein the function of each key pressed by the user is reported but not executed. @rtype: bool

_propertyCache: Set[Callable[[AutoPropertyObject], Any]]
class inputCore._AllGestureMappingsRetriever(obj, ancestors)

Bases: object

results: Dict[str, Dict[str, Any]]
addResult(scriptInfo)

@type scriptInfo: AllGesturesScriptInfo

addGlobalMap(gmap)
classmethod makeKbEmuScriptInfo(scriptCls, kbGestureIdentifier)

@rtype AllGesturesScriptInfo

classmethod makeNormalScriptInfo(scriptCls, scriptName, script)
classmethod getScriptCategory(scriptCls, script)
addObj(obj, isAncestor=False)
class inputCore.AllGesturesScriptInfo(cls, scriptName)

Bases: object

cls
scriptName
gestures
property moduleName
property className
category
displayName
class inputCore.KbEmuScriptInfo(cls, scriptName)

Bases: AllGesturesScriptInfo

cls
scriptName
category
displayName
gestures
inputCore.normalizeGestureIdentifier(identifier)

Normalize a gesture identifier so that it matches other identifiers for the same gesture. First, the entire identifier is converted to lower case. Then, any items separated by a + sign after the source prefix are considered to be of indeterminate order and are sorted by character. This is done because, for example, “kb:shift+alt+downArrow” must be treated the same as “kb:alt+shift+downarrow”.

inputCore.gestureSources = <WeakValueDictionary at 0x7024110>

Maps registered source prefix strings to L{InputGesture} classes.

inputCore.registerGestureSource(source, gestureCls)

Register an input gesture class for a source prefix string. The specified gesture class will be used for queries regarding all gesture identifiers with the given source prefix. For example, if “kb” is registered with the C{KeyboardInputGesture} class, any queries for “kb:tab” or “kb(desktop):tab” will be directed to the C{KeyboardInputGesture} class. If there is no exact match for the source, any parenthesized portion is stripped. For example, for “br(baum):d1”, if “br(baum)” isn’t registered, “br” will be used if it is registered. This registration is used, for example, to get the display text for a gesture identifier. @param source: The source prefix for associated gesture identifiers. @type source: str @param gestureCls: The input gesture class. @type gestureCls: L{InputGesture}

inputCore._getGestureClsForIdentifier(identifier)

Get the registered gesture class for an identifier.

inputCore.getDisplayTextForGestureIdentifier(identifier)

Get the text to be presented to the user describing a given gesture identifier. The display text consists of two strings: the gesture’s source (e.g. “laptop keyboard”) and the specific gesture (e.g. “alt+tab”). @param identifier: The normalized gesture identifier in question. @type identifier: str @return: A tuple of (source, specificGesture). @rtype: tuple of (str, str) @raise LookupError: If no display text can be determined.

inputCore.manager: InputManager | None = None

The singleton input manager instance.

inputCore.initialize()

Initializes input core, creating a global L{InputManager} singleton.

inputCore.terminate()

Terminates input core.

inputCore.logTimeSinceInput()

Log the time since the last input was received. This does nothing if time since input logging is disabled.