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.