vision package
Framework to facilitate changes in how content is displayed on screen.
One or more assistant functions can be implemented in vision enhancement providers. Add-ons can provide their own provider using modules in the visionEnhancementProviders package containing a L{VisionEnhancementProvider} class.
- vision.initialize() None
- vision.pumpAll() None
Runs tasks at the end of each core cycle.
- vision.terminate() None
- vision._isDebug() bool
Submodules
vision.constants module
Constants for the vision framework.
- class vision.constants.Context(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
str
,Enum
Context for events received by providers. Typically this informs of the cause of the event. For example, L{focus} is used when an event is triggered by the focus object or a focus change.
- FOCUS = 'focus'
- FOREGROUND = 'foreground'
- NAVIGATOR = 'navigator'
- FOCUS_NAVIGATOR = 'focusNavigator'
- CARET = 'caret'
- BROWSEMODE = 'browseMode'
- REVIEW = 'review'
- MOUSE = 'mouse'
- _generate_next_value_(start, count, last_values)
Generate the next value when not given.
name: the name of the member start: the initial start value or None count: the number of existing members last_values: the list of values assigned
- _new_member_(**kwargs)
Create and return a new object. See help(type) for accurate signature.
- _use_args_ = True
- _member_names_ = ['FOCUS', 'FOREGROUND', 'NAVIGATOR', 'FOCUS_NAVIGATOR', 'CARET', 'BROWSEMODE', 'REVIEW', 'MOUSE']
- _member_map_ = {'BROWSEMODE': Context.BROWSEMODE, 'CARET': Context.CARET, 'FOCUS': Context.FOCUS, 'FOCUS_NAVIGATOR': Context.FOCUS_NAVIGATOR, 'FOREGROUND': Context.FOREGROUND, 'MOUSE': Context.MOUSE, 'NAVIGATOR': Context.NAVIGATOR, 'REVIEW': Context.REVIEW}
- _value2member_map_ = {'browseMode': Context.BROWSEMODE, 'caret': Context.CARET, 'focus': Context.FOCUS, 'focusNavigator': Context.FOCUS_NAVIGATOR, 'foreground': Context.FOREGROUND, 'mouse': Context.MOUSE, 'navigator': Context.NAVIGATOR, 'review': Context.REVIEW}
- _unhashable_values_ = []
- _member_type_
alias of
str
- _value_repr_()
Return repr(self).
vision.exceptions module
Module containing exceptions for the vision framework.
- exception vision.exceptions.ProviderTerminateException
Bases:
RuntimeError
- exception vision.exceptions.ProviderInitException
Bases:
RuntimeError
vision.providerBase module
Module within the vision framework that contains the base vision enhancement provider class.
- class vision.providerBase.VisionEnhancementProviderSettings(*args, **kwargs)
Bases:
AutoSettings
Base class for settings for a vision enhancement provider. Ensure that the following are implemented: - AutoSettings.getId:
This is case sensitive. Used in the config file. Does not have to match the module name.
- AutoSettings.getDisplayName:
The string that should appear in the GUI as the name.
- AutoSettings._get_supportedSettings:
The settings for your provider, the returned list is permitted to change during start / termination of the provider. The implementation must handle how to modify the returned settings based on external (software, hardware) dependencies.
@note If the vision enhancement provider has settings, it will provide an implementation of this class. The provider will hold a reference to an instance of this class, this is accessed through the class method L{VisionEnhancementProvider.getSettings}. One way to handle settings that are strictly runtime: - During initialization, the vision enhancement provider can instruct the settings instance what it should expose using the L{utoSettings._get_supportedSettings} property. - “_exampleProvider_autoGui.py” provides an example of this.
Perform any initialisation @note: registers with the config save action extension point
- classmethod _getConfigSection() str
@return: The section of the config that these settings belong in.
- _abc_impl = <_abc._abc_data object>
- class vision.providerBase.VisionProviderStateControl
Bases:
object
Stub showing the interface for controlling the start/termination of a single provider. Implementors of this class should handle the outcome when things go wrong.
- abstract getProviderInfo()
@return: The provider info @rtype: providerInfo.ProviderInfo
- abstract getProviderInstance()
Gets an instance for the provider if it already exists @rtype: Optional[VisionEnhancementProvider]
- abstract startProvider(shouldPromptOnError: bool) bool
Initializes the provider, prompting user with the error if necessary. @param shouldPromptOnError: True if the user should be presented with any errors that may occur. @return: True on success
- abstract terminateProvider(shouldPromptOnError: bool) bool
Terminate the provider, prompting user with the error if necessary. @param shouldPromptOnError: True if the user should be presented with any errors that may occur. @return: True on success
- class vision.providerBase.VisionEnhancementProvider(*args, **kwargs)
Bases:
AutoPropertyObject
A class for vision enhancement providers. Derived classes should implement: - terminate:
How to shutdown the provider
- registerEventExtensionPoints:
Allows the provider to receive updates form NVDA
- canStart:
Checks startup dependencies are satisfied
- getSettings:
Returns your implementation of VisionEnhancementProviderSettings
Optional: To provide a custom GUI, return a SettingsPanel class type from: - getSettingsPanelClass
- cachePropertiesByDefault = True
Specifies whether properties are cached by default; can be overridden for individual properties by setting _cache_propertyName. @type: bool
- abstract classmethod getSettings() VisionEnhancementProviderSettings
- @remarks: The L{VisionEnhancementProviderSettings} class should be implemented to define the settings
for your provider
- classmethod getSettingsPanelClass() Any | None
Returns the class to be used in order to construct a settingsPanel instance for the provider. The returned class must have a constructor which accepts:
parent: wx.Window
providerControl: VisionProviderStateControl
EG: ``` python class mySettingsPanel(gui.settingsDialogs.SettingsPanel):
- def __init__(self, parent: wx.Window, providerControl: VisionProviderStateControl):
super().__init__(parent=parent)
``` @rtype: Optional[SettingsPanel] @remarks: When None is returned, L{gui.settingsDialogs.VisionProviderSubPanel_Wrapper} is used.
- reinitialize() None
Reinitialize a vision enhancement provider, reusing the same instance. This base implementation simply calls terminate and __init__ consecutively.
- abstract terminate() None
Terminate this provider. This should be used for any required clean up. @precondition: L{initialize} has been called. @postcondition: This provider can no longer be used.
- abstract registerEventExtensionPoints(extensionPoints: EventExtensionPoints) None
Called at provider initialization time, this method should register the provider to the several event extension points that it is interested in. This method should only register itself with the extension points, and should refrain from doing anything else, as it might be called again several times between initialization and termination. @param extensionPoints: An object containing available extension points as attributes.
- abstract classmethod canStart() bool
Returns whether this provider is able to start.
- classmethod enableInConfig(enable: bool) None
Enables or disables the provider in the current configuration. @param enable: Whether to enable (C{True}) or disable (C{False}) the provider in the configuration.
- classmethod isEnabledInConfig() bool
Returns whether the provider is enabled in the configuration.
- _abc_impl = <_abc._abc_data object>
- _propertyCache: Set[Callable[[AutoPropertyObject], Any]]
vision.providerInfo module
- class vision.providerInfo.ProviderInfo(providerId: str, moduleName: str, displayName: str, providerClass: Type[vision.providerBase.VisionEnhancementProvider])
Bases:
object
- providerId: str
- moduleName: str
- displayName: str
- providerClass: Type[VisionEnhancementProvider]
vision.util module
Utility functions for vision enhancement providers.
- vision.util.getCaretRect(obj: TextContainerObject | None = None) RectLTRB
- vision.util.getObjectRect(obj: NVDAObject) RectLTRB
- vision.util.getContextRect(context: Context, obj: TextContainerObject | None = None) RectLTRB | None
Gets a rectangle for the specified context.
vision.visionHandler module
Module containing the vision handler.
The vision handler is the core of the vision framework. See the documentation of L{VisionHandler} for more details about what it does.
- vision.visionHandler._getProviderClass(moduleName: str, caseSensitive: bool = True) Type[VisionEnhancementProvider]
Returns a registered provider class with the specified moduleName.
- vision.visionHandler._getProvidersFromFileSystem()
- class vision.visionHandler.VisionHandler(*args, **kwargs)
Bases:
AutoPropertyObject
The singleton vision handler is the core of the vision framework. It performs the following tasks:
It keeps track of active vision enhancement _providers in the L{_providers} dictionary.
It processes initialization and termination of providers.
- It receives certain events from the core of NVDA,
delegating them to the appropriate extension points.
- postGuiInit() None
Handles first initialization of the handler as a config profile switch. This is executed on the main thread by L{__init__} using the events queue. This ensures that the gui is fully initialized before providers are initialized that might rely on it.
- _allProviders: List[ProviderInfo] = []
- _getBuiltInProviderIds()
- _updateAllProvidersList()
- getProviderList(onlyStartable: bool = True, reloadFromSystem: bool = False) List[ProviderInfo]
Gets a list of available vision enhancement provider information @param onlyStartable: excludes all providers for which the check method returns C{False}. @param reloadFromSystem: ensure the list is fresh. Providers may have been added to the file system. @return: List of available providers
- getProviderInfo(providerId: str) ProviderInfo | None
- getActiveProviderInstances()
- getActiveProviderInfos() List[ProviderInfo]
- getConfiguredProviderInfos() List[ProviderInfo]
- getProviderInstance(provider: ProviderInfo) VisionEnhancementProvider | None
- terminateProvider(provider: ProviderInfo, saveSettings: bool = True) None
Terminates a currently active provider. When termination fails, an exception is raised. Yet, the provider will be removed from the providers dictionary, so its instance goes out of scope and wil lbe garbage collected. @param provider: The provider to terminate. @param saveSettings: Whether settings should be saved on termination.
- initializeProvider(provider: ProviderInfo, temporary: bool = False) None
Enables and activates the supplied provider. @param provider: The provider to initialize. @param temporary: Whether the selected provider is enabled temporarily (e.g. as a fallback).
This defaults to C{False}. If C{True}, no changes will be performed to the configuration.
@note: On error, an an Exception is raised.
- terminate() None
- handleUpdate(obj, property: str) None
- handleForeground(obj) None
- handleGainFocus(obj) None
- handleCaretMove(obj) None
- handleMouseMove(obj, x: int, y: int) None
- handleConfigProfileSwitch() None
- initialFocus() None
Handles the current focus when the provider is initialized. This function notifies one or more extension points; thus it can raise any type of exception.
Handles the current navigator object when the provider is initialized. This function notifies an extension point; thus it can raise any type of exception.
- _abc_impl = <_abc._abc_data object>
vision.visionHandlerExtensionPoints module
Module containing extension points for vision enhancement providers.
Consult the documentation of L{EventExtensionPoints} for more details.
- class vision.visionHandlerExtensionPoints.EventExtensionPoints
Bases:
object
Data class containing extension points that will be used to notify vision enhancement providers about occuring events, particularly for NVDA Objects. Though an instance of this class is created when initializing the vision handler, it should never be accessed from the vision handler directly. Instead, vision enhancement providers should implement a “registerEventExtensionPoints” method, taking an instance of this class as the only argument, performing registration to the extension points it is interested in. For an example, see the L{visionEnhancementProviders.NVDAHighlighter} module.
- post_objectUpdate: Action
Notifies a vision enhancement provider when an object property has changed. This allows a vision enhancement provider to take an action when one of the properties of an object has changed. For example, a magnifier can track the magnified area of the screen to this object, when the name of the object has changed. Handlers are called with two arguments. @param obj: The object that received a property change. @type obj: L{NVDAObjects.NVDAObject} @param property: The object’s property that changed, e.g. “name” or “description”. @type property: str
- post_focusChange: Action
Notifies a vision enhancement provider when the focused NVDAObject has changed. This allows a vision enhancement provider to take an action when the focus changed. For example, a magnifier can track the magnified area of the screen to this object. Handlers are called with one argument. @param obj: The object that received focus. @type obj: L{NVDAObjects.NVDAObject}
- post_foregroundChange: Action
Notifies a vision enhancement provider when the foreground NVDAObject has changed. This allows a vision enhancement provider to take an action when another window takes the foreground. For example, a magnifier can track the magnified area of the screen to this object. Handlers are called with one argument. @param obj: The object that became the foreground object. @type obj: L{NVDAObjects.NVDAObject}
- post_caretMove: Action
Notifies a vision enhancement provider when a physical caret has moved. This allows a vision enhancement provider to take an action when the caret moves in a window. For example, a magnifier can track the magnified area of the screen to the new caret position. Handlers are strongly encouraged to cache the new caret position, and handle the pending caret update at the end of every core cycle using L{post_coreCycle}, unless they delegate caret change handling to a separate thread. Handlers are called with one argument. @param obj: The object in which the caret position changed. @type obj: L{NVDAObjects.NVDAObject}
- post_browseModeMove: Action
Notifies a vision enhancement provider when a virtual caret has moved. This allows a vision enhancement provider to take an action when the virtual caret moves in a browse mode document. For example, a magnifier can track the magnified area of the screen to the new virtual caret position. Handlers are strongly encouraged to cache the new virtual caret position, and handle the pending update at the end of every core cycle using L{post_coreCycle}, unless they delegate virtual caret change handling to a separate thread. Handlers are called with one argument. @param obj: The cursor manager that changed it virtual caret position. @type obj: L{cursorManager.CursorManager}
- post_reviewMove: Action
Notifies a vision enhancement provider when the position of the review cursor has changed. This allows a vision enhancement provider to take an action when the review position has changed. For example, a magnifier can track the magnified area of the screen to the new navigator object, or the exact location of the review cursor within the object. Handlers are strongly encouraged to cache the last context that triggered the change, and handle the pending review position change at the end of every core cycle using L{post_coreCycle}, unless they delegate review position change handling to a separate thread. Handlers are called with one argument. @param context: The context that triggered the review position change. @type context: L{vision.constants.Context}
- post_mouseMove: Action
Notifies a vision enhancement provider when the mouse has moved. This allows a vision enhancement provider to take an action for mouse moves. For example, a magnifier can track the magnified area of the screen to the position of the mouse. Note that, by the nature of NVDA’s mouse tracking implementation, This extension point is only called once per core cycle. Handlers are called with one argument. @param obj: The object that received focus. @type obj: L{NVDAObjects.NVDAObject}
- post_coreCycle: Action
Notifies a vision enhancement provider at the end of every core cycle. This allows a vision enhancement provider to rate limit certain actions. For example, many caret updates could take place during one core cycle. Especially if handling a caret update takes some time, handling only one of them is enough. Handlers are called without arguments.