appModuleHandler module

Manages appModules. @var runningTable: a dictionary of the currently running appModules, using their application’s main window handle as a key.

appModuleHandler.post_appSwitch = <extensionPoints.Action object>

Notifies when another application is taking foreground. This allows components to react upon application switches. For example, braille triggers bluetooth polling for braille displays if necessary. Handlers are called with no arguments.

appModuleHandler._executableNamesToAppModsAddons: Dict[str, str] = {}

AppModules registered with a given binary by add-ons are placed here. We cannot use l{appModules.EXECUTABLE_NAMES_TO_APP_MODS} for modules included in add-ons, since appModules in add-ons should take precedence over the one bundled in NVDA.

class appModuleHandler.processEntry32W

Bases: Structure

_fields_ = [('dwSize', <class 'ctypes.c_ulong'>), ('cntUsage', <class 'ctypes.c_ulong'>), ('th32ProcessID', <class 'ctypes.c_ulong'>), ('th32DefaultHeapID', <class 'ctypes.c_ulong'>), ('th32ModuleID', <class 'ctypes.c_ulong'>), ('cntThreads', <class 'ctypes.c_ulong'>), ('th32ParentProcessID', <class 'ctypes.c_ulong'>), ('pcPriClassBase', <class 'ctypes.c_long'>), ('dwFlags', <class 'ctypes.c_ulong'>), ('szExeFile', <class 'ctypes.wintypes.c_wchar_Array_260'>)]
cntThreads

Structure/Union member

cntUsage

Structure/Union member

dwFlags

Structure/Union member

dwSize

Structure/Union member

pcPriClassBase

Structure/Union member

szExeFile

Structure/Union member

th32DefaultHeapID

Structure/Union member

th32ModuleID

Structure/Union member

th32ParentProcessID

Structure/Union member

th32ProcessID

Structure/Union member

class appModuleHandler._PROCESS_MACHINE_INFORMATION

Bases: Structure

_fields_ = [('ProcessMachine', <class 'ctypes.c_ushort'>), ('Res0', <class 'ctypes.c_ushort'>), ('MachineAttributes', <class 'ctypes.c_ulong'>)]
MachineAttributes

Structure/Union member

ProcessMachine

Structure/Union member

Res0

Structure/Union member

appModuleHandler.registerExecutableWithAppModule(executableName: str, appModName: str) None

Registers appModule to be used for a given executable.

appModuleHandler.unregisterExecutable(executableName: str) None

Removes the executable of a given name from the mapping of applications to appModules.

appModuleHandler._getPossibleAppModuleNamesForExecutable(executableName: str) Tuple[str, ...]

Returns list of the appModule names for a given executable. The names in the tuple are placed in order in which import of these aliases should be attempted that is: - The alias registered by add-ons if any add-on registered an appModule for the executable - Just the name of the executable to cover a standard appModule named the same as the executable - The alias from appModules.EXECUTABLE_NAMES_TO_APP_MODS if it exists.

appModuleHandler.doesAppModuleExist(name: str) bool

Returns c{True} if App Module with a given name exists, c{False} otherwise.

appModuleHandler._importAppModuleForExecutable(executableName: str) module | None

Import and return appModule for a given executable or None if there is no module.

appModuleHandler.getAppNameFromProcessID(processID: int, includeExt: bool = False) str

Finds out the application name of the given process. @param processID: the ID of the process handle of the application you wish to get the name of. @param includeExt: C{True} to include the extension of the application’s executable filename, C{False} to exclude it. @returns: application name

appModuleHandler.getAppModuleForNVDAObject(obj: NVDAObject) AppModule
appModuleHandler.getAppModuleFromProcessID(processID: int) AppModule

Finds the appModule that is for the given process ID. The module is also cached for later retrievals. @param processID: The ID of the process for which you wish to find the appModule. @returns: the appModule

appModuleHandler.update(processID, helperLocalBindingHandle=None, inprocRegistrationHandle=None)

Tries to load a new appModule for the given process ID if need be. @param processID: the ID of the process. @type processID: int @param helperLocalBindingHandle: an optional RPC binding handle pointing to the RPC server for this process @param inprocRegistrationHandle: an optional rpc context handle representing successful registration with the rpc server for this process

appModuleHandler.cleanup()

Removes any appModules from the cache whose process has died.

appModuleHandler.fetchAppModule(processID: int, appName: str) AppModule

Returns an appModule found in the appModules directory, for the given application name. @param processID: process ID for it to be associated with @param appName: the application name for which an appModule should be found. @returns: the appModule.

appModuleHandler.reloadAppModules()

Reloads running appModules. especially, it clears the cache of running appModules and deletes them from sys.modules. Each appModule will then be reloaded immediately.

appModuleHandler.initialize()

Initializes the appModule subsystem.

appModuleHandler.terminate()
appModuleHandler.handleAppSwitch(oldMods, newMods)
class appModuleHandler.AppModule(*args, **kwargs)

Bases: ScriptableObject

Base app module. App modules provide specific support for a single application. Each app module should be a Python module or a package in the appModules package named according to the executable it supports; e.g. explorer.py for the explorer.exe application or firefox/__init__.py for firefox.exe. If the name of the executable is not compatible with the Python’s import system i.e. contains some special characters such as “.” or “+” you can name the module however you like and then map the executable name to the module name by adding an entry to appModules.EXECUTABLE_NAMES_TO_APP_MODS dictionary. It should contain a C{AppModule} class which inherits from this base class. App modules can implement and bind gestures to scripts. These bindings will only take effect while an object in the associated application has focus. See L{ScriptableObject} for details. App modules can also receive NVDAObject events for objects within the associated application. This is done by implementing methods called C{event_eventName}, where C{eventName} is the name of the event; e.g. C{event_gainFocus}. These event methods take two arguments: the NVDAObject on which the event was fired and a callable taking no arguments which calls the next event handler.

Some executables host many different applications; e.g. javaw.exe. In this case, it is desirable that a specific app module be loaded for each actual application, rather than the one for the hosting executable. To support this, the module for the hosting executable (not the C{AppModule} class within it) can implement the function C{getAppNameFromHost(processId)}, where C{processId} is the id of the host process. It should return a unicode string specifying the name that should be used. Alternatively, it can raise C{LookupError} if a name couldn’t be determined.

sleepMode = False

Whether NVDA should sleep while in this application (e.g. the application is self-voicing). If C{True}, all events and script requests inside this application are silently dropped. @type: bool

processID: int

The ID of the process this appModule is for

appName: str

The application name

helperLocalBindingHandle: ctypes.c_long | None

RPC binding handle pointing to the RPC server for this process

_getExecutableFileInfo()
_getImmersivePackageInfo()
_setProductInfo()

Set productName and productVersion attributes. There are at least two ways of obtaining product info for an app: * Package info for hosted apps * File version info for other apps and for some hosted apps

_get_productName()
_get_productVersion()
_get_appModuleName()
isAlive: bool
_get_isAlive()
terminate()

Terminate this app module. This is called to perform any clean up when this app module is being destroyed. Subclasses should call the superclass method first.

chooseNVDAObjectOverlayClasses(obj, clsList)

Choose NVDAObject overlay classes for a given NVDAObject. This is called when an NVDAObject is being instantiated after L{NVDAObjects.NVDAObject.findOverlayClasses} has been called on the API-level class. This allows an AppModule to add or remove overlay classes. See L{NVDAObjects.NVDAObject.findOverlayClasses} for details about overlay classes. @param obj: The object being created. @type obj: L{NVDAObjects.NVDAObject} @param clsList: The list of classes, which will be modified by this method if appropriate. @type clsList: list of L{NVDAObjects.NVDAObject}

_get_appPath()

Returns the full path for the executable e.g. ‘C:Windowsexplorer.exe’ for Explorer. @rtype: str

_get_is64BitProcess() bool

Whether the underlying process is a 64 bit process. @rtype: bool

_get_isWindowsStoreApp()

Whether this process is a Windows Store (immersive) process. An immersive process is a Windows app that runs inside a Windows Runtime (WinRT) container. These include Windows store apps on Windows 8.1, and Universal Windows Platform (UWP) apps on Windows 10 and later. A special case is a converted desktop app distributed on Microsoft Store. Not all immersive apps are packaged as a true Store app with a package info e.g. File Explorer reports itself as immersive when it is not. @rtype: bool

_get_isRunningUnderDifferentLogonSession() bool

Returns whether the application for this appModule was started under a different logon session. This applies to applications started with the Windows runas command or when choosing “run as a different user” from an application’s (shortcut) context menu.

_get_appArchitecture() str

Returns the target architecture for the specified app. This is useful for detecting X86/X64 apps running on ARM64 releases of Windows 10. The following strings are returned: * x86: 32-bit x86 app on 32-bit or 64-bit Windows. * AMD64: x64 app on x64 or ARM64 Windows. * ARM: 32-bit ARM app on ARM64 Windows. * ARM64: 64-bit ARM app on ARM64 Windows. @rtype: str

isGoodUIAWindow(hwnd)

returns C{True} if the UIA implementation of the given window must be used, regardless whether native or not. This function is the counterpart of and takes precedence over L{isBadUIAWindow}. If both functions return C{False}, the decision of whether to use UIA for the window is left to core. Warning: this may be called outside of NVDA’s main thread, therefore do not try accessing NVDAObjects and such, rather just check window class names.

isBadUIAWindow(hwnd)

returns C{True} if the UIA implementation of the given window must be ignored due to it being broken in some way. This function is the counterpart of L{isGoodUIAWindow}. When both functions return C{True}, L{isGoodUIAWindow} takes precedence. If both functions return C{False}, the decision of whether to use UIA for the window is left to core. Warning: this may be called outside of NVDA’s main thread, therefore do not try accessing NVDAObjects and such, rather just check window class names.

shouldProcessUIAPropertyChangedEvent(sender, propertyId)

Determines whether NVDA should process a UIA property changed event. Returning False will cause the event to be dropped completely. This can be used to work around UIA implementations which flood events and cause poor performance. Returning True means that the event will be processed, but it might still be rejected later; e.g. because it isn’t native UIA, because shouldAcceptEvent returns False, etc.

dumpOnCrash()

Request that this process writes a minidump when it crashes for debugging. This should only be called if instructed by a developer.

_get_statusBar()

Retrieve the status bar object of the application. If C{NotImplementedError} is raised, L{api.getStatusBar} will resort to perform a lookup by position. If C{None} is returned, L{GlobalCommands.script_reportStatusLine} will in turn resort to reading the bottom line of text written to the display. @rtype: NVDAObject

getStatusBarText(obj: NVDAObject) str

Get the text from the given status bar. If C{NotImplementedError} is raised, L{api.getStatusBarText} will resort to retrieve the name of the status bar and the names and values of all of its children.

_get_statusBarTextInfo()

Retrieve a L{TextInfo} positioned at the status bar of the application. This is used by L{GlobalCommands.script_reportStatusLine} in cases where L{api.getStatusBar} could not locate a proper L{NVDAObject} for the status bar. For this method to get called, L{_get_statusBar} must return C{None}. @rtype: TextInfo

_abc_impl = <_abc._abc_data object>
appArchitecture
appModuleName
appPath
is64BitProcess
isRunningUnderDifferentLogonSession
isWindowsStoreApp
productName
productVersion
statusBar
statusBarTextInfo
devInfo: List[str]

Information about this appModule useful to developers.

_get_devInfo() List[str]

Information about this appModule useful to developers. For an NVDAObject, its appModule devInfo is appended to NVDAObject.devInfo. Subclasses may extend this, calling the superclass property first. @return: A list of text strings providing information about this appModule useful to developers.

class appModuleHandler.AppProfileTrigger(appName)

Bases: ProfileTrigger

A configuration profile trigger for when a particular application has focus.

appModuleHandler.getWmiProcessInfo(processId)

Retrieve the WMI Win32_Process class instance for a given process. For details about the available properties, see http://msdn.microsoft.com/en-us/library/aa394372%28v=vs.85%29.aspx @param processId: The id of the process in question. @type processId: int @return: The WMI Win32_Process class instance. @raise LookupError: If there was an error retrieving the instance.