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>
_propertyCache: Set[GetterMethodT]
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.getReviewRect() RectLTRB
vision.util.getCaretRect(obj: TextContainerObject | None = None) RectLTRB
vision.util.getMouseRect() 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.util.getRectFromTextInfo(textInfo: TextInfo) RectLTRB

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
handleReviewMove(context: Context = Context.REVIEW) 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.

initialNavigatorObject() None

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.