UIAHandler package

UIAHandler.shouldUseUIAInMSWord(appModule: AppModule) bool
class UIAHandler.UIAHandler(*args, **kw)

Bases: COMObject

_com_interfaces_ = [<class 'comtypes.gen._944DE083_8FB8_45CF_BCB7_C477ACB2F897_0_1_0.IUIAutomationEventHandler'>, <class 'comtypes.gen._944DE083_8FB8_45CF_BCB7_C477ACB2F897_0_1_0.IUIAutomationFocusChangedEventHandler'>, <class 'comtypes.gen._944DE083_8FB8_45CF_BCB7_C477ACB2F897_0_1_0.IUIAutomationPropertyChangedEventHandler'>, <class 'comtypes.gen._944DE083_8FB8_45CF_BCB7_C477ACB2F897_0_1_0.IUIAutomationNotificationEventHandler'>, <class 'comtypes.gen._944DE083_8FB8_45CF_BCB7_C477ACB2F897_0_1_0.IUIAutomationActiveTextPositionChangedEventHandler'>]
_rateLimitedEventHandler: IUnknown | None = None
_notificationKindsToNamesCache = {0: 'ItemAdded', 1: 'ItemRemoved', 2: 'ActionCompleted', 3: 'ActionAborted', 4: 'Other'}

A cache of UIA notification kinds to friendly names for logging

getUIANotificationKindDebugString(notificationKind: int) str

Generates a string representation of the given UIA notification kind, suitable for logging. This is the name part of the NotificationKind_* constant. If a matching constant can not be found, then a string representation of the NotificationKind value itself is used. E.g. “unknown notification kind 1234”.

_notificationProcessingValuesToNamesCache = {0: 'ImportantAll', 1: 'ImportantMostRecent', 2: 'All', 3: 'MostRecent', 4: 'CurrentThenMostRecent'}

A cache of UIA notification processing values to friendly names for logging

getUIANotificationProcessingValueDebugString(notificationProcessing: int) str

Generates a string representation of the given UIA notification processing value, suitable for logging. This is the name part of the NotificationProcessing_* constant. If a matching constant can not be found, then a string representation of the NotificationProcessing value itself is used. E.g. “unknown notification processing value 1234”.

getUIAPropertyIDDebugString(propertyID: int) str

Generates a string representation of the given property ID, suitable for logging. For constant or registered property IDs, the name is the programmatic name registered for the property in UIA. If no name can be found, then a string representation of the ID itself is used. E.g. “unknown property ID 1234”.

_eventIDsToNamesCache = {20000: 'ToolTipOpened', 20001: 'ToolTipClosed', 20002: 'StructureChanged', 20003: 'MenuOpened', 20004: 'AutomationPropertyChanged', 20005: 'AutomationFocusChanged', 20006: 'AsyncContentLoaded', 20007: 'MenuClosed', 20008: 'LayoutInvalidated', 20009: 'Invoke_Invoked', 20010: 'SelectionItem_ElementAddedToSelection', 20011: 'SelectionItem_ElementRemovedFromSelection', 20012: 'SelectionItem_ElementSelected', 20013: 'Selection_Invalidated', 20014: 'Text_TextSelectionChanged', 20015: 'Text_TextChanged', 20016: 'Window_WindowOpened', 20017: 'Window_WindowClosed', 20018: 'MenuModeStart', 20019: 'MenuModeEnd', 20020: 'InputReachedTarget', 20021: 'InputReachedOtherElement', 20022: 'InputDiscarded', 20023: 'SystemAlert', 20024: 'LiveRegionChanged', 20025: 'HostedFragmentRootsInvalidated', 20026: 'Drag_DragStart', 20027: 'Drag_DragCancel', 20028: 'Drag_DragComplete', 20029: 'DropTarget_DragEnter', 20030: 'DropTarget_DragLeave', 20031: 'DropTarget_Dropped', 20032: 'TextEdit_TextChanged', 20033: 'TextEdit_ConversionTargetChanged', 20034: 'Changes', 20035: 'Notification', 20036: 'ActiveTextPositionChanged'}

A cache of UIA event IDs to friendly names for logging

getUIAEventIDDebugString(eventID: int) str

Generates a string representation of the given UIA event ID, suitable for logging. This is the name part of the UIA_*EventId constant. If a matching constant can not be found, then a string representation of the ID itself is used. E.g. “unknown event ID 1234”.

getUIAElementPropertyDebugString(element: IUIAutomationElement, propertyId: int) str

Fetches a property from a UIA element, for the specific purpose of logging. NULL value and exceptions are also given a string representation.

getWindowHandleDebugString(windowHandle: int) str

Generates a string representation of the given window handle suitable for logging. Includes the handle value and the window’s class name.

getUIAElementDebugString(element: IUIAutomationElement) str

Generates a string representation of the given UIA element suitable for logging. Including info such as name, controlType and automation Id.

terminate()
MTAThreadFunc()
_registerGlobalEventHandlers(handler: UIAHandler)
_createLocalEventHandlerGroup(handler: UIAHandler)
addEventHandlerGroup(element, eventHandlerGroup)
removeEventHandlerGroup(element, eventHandlerGroup)
addLocalEventHandlerGroupToElement(element, isFocus=False)
removeLocalEventHandlerGroupFromElement(element)
IUIAutomationEventHandler_HandleAutomationEvent(sender, eventID)
lastFocusedUIAElement = None
IUIAutomationFocusChangedEventHandler_HandleFocusChangedEvent(sender)
IUIAutomationPropertyChangedEventHandler_HandlePropertyChangedEvent(sender, propertyId, newValue)
IUIAutomationNotificationEventHandler_HandleNotificationEvent(sender, NotificationKind, NotificationProcessing, displayString, activityId)
IUIAutomationActiveTextPositionChangedEventHandler_HandleActiveTextPositionChangedEvent(sender, textRange)
_isUIAWindowHelper(hwnd: int, isDebug=False) bool
isUIAWindow(hwnd: int, isDebug: bool = False) bool
getNearestWindowHandle(UIAElement)
_isNetUIEmbeddedInWordDoc(element: IUIAutomationElement) bool

Detects if the given UIA element represents a control in a NetUI container embedded within a MS Word document window. E.g. the Modern Comments side track pane. This method also caches the answer on the element itself to both speed up checking later and to allow checking on an already dead element E.g. a previous focus.

_emitMSAAFocusForWordDocIfNecessary(element: IUIAutomationElement) None

Fires an MSAA focus event on the given UIA element if the element is the root of a Word document, and the focus was previously in a NetUI container embedded in this Word document.

isNativeUIAElement(UIAElement)
UIAHandler.initialize()
UIAHandler.terminate()
UIAHandler._isDebug()

Subpackages

Submodules

UIAHandler.browseMode module

class UIAHandler.browseMode.UIADocumentWithTableNavigation(*args, **kwargs)

Bases: DocumentWithTableNavigation

_getTableCellAt(tableID, startPos, row, column)

Starting from the given start position, Locates the table cell with the given row and column coordinates and table ID. @param startPos: the position to start searching from. @type startPos: L{textInfos.TextInfo} @param tableID: the ID of the table. @param row: the row number of the cell @type row: int @param column: the column number of the table cell @type column: int @returns: the table cell’s position in the document @rtype: L{textInfos.TextInfo} @raises: LookupError if the cell does not exist

_abc_impl = <_abc._abc_data object>
class UIAHandler.browseMode.UIATextRangeQuickNavItem(itemType, document, UIAElementOrRange)

Bases: TextInfoQuickNavItem

See L{QuickNavItem.__init__} for itemType and document argument definitions. @param textInfo: the textInfo position this item represents. @type textInfo: L{textInfos.TextInfo}

property obj
property label
_abc_impl = <_abc._abc_data object>
class UIAHandler.browseMode.TextAttribUIATextInfoQuickNavItem(attribValues, itemType, document, textInfo)

Bases: TextInfoQuickNavItem

See L{QuickNavItem.__init__} for itemType and document argument definitions. @param textInfo: the textInfo position this item represents. @type textInfo: L{textInfos.TextInfo}

attribID = None

a UIA text attribute to search for

wantedAttribValues = {}

A set of attribute values acceptable to match the search.

_abc_impl = <_abc._abc_data object>
class UIAHandler.browseMode.ErrorUIATextInfoQuickNavItem(attribValues, itemType, document, textInfo)

Bases: TextAttribUIATextInfoQuickNavItem

See L{QuickNavItem.__init__} for itemType and document argument definitions. @param textInfo: the textInfo position this item represents. @type textInfo: L{textInfos.TextInfo}

attribID = 40031

a UIA text attribute to search for

wantedAttribValues = {60001, 60002}

A set of attribute values acceptable to match the search.

property label
_abc_impl = <_abc._abc_data object>
UIAHandler.browseMode.UIATextAttributeQuicknavIterator(ItemClass, itemType, document, position, direction='next')
class UIAHandler.browseMode.HeadingUIATextInfoQuickNavItem(itemType: str, document: UIA, position: UIATextInfo, label: str | None = None, level: int = 0)

Bases: TextInfoQuickNavItem

See L{QuickNavItem.__init__} for itemType and document argument definitions. @param textInfo: the textInfo position this item represents. @type textInfo: L{textInfos.TextInfo}

property label
isChild(parent)

Is this item a child of the given parent? This is used when representing items in a hierarchical tree structure, such as the Elements List. @param parent: the item of whom this item may be a child of. @type parent: L{QuickNavItem} @return: True if this item is a child, false otherwise. @rtype: bool

_abc_impl = <_abc._abc_data object>
UIAHandler.browseMode.UIAHeadingQuicknavIterator(itemType: str, document: UIABrowseModeDocument, position: UIABrowseModeDocumentTextInfo | None, direction: str = 'next')
UIAHandler.browseMode.UIAControlQuicknavIterator(itemType, document, position, UIACondition, direction='next', itemClass=<class 'UIAHandler.browseMode.UIATextRangeQuickNavItem'>)
class UIAHandler.browseMode.UIABrowseModeDocumentTextInfo(*args, **kwargs)

Bases: BrowseModeDocumentTextInfo, RootProxyTextInfo

Constructor. Subclasses must extend this, calling the superclass method first. @param position: The initial position of this range; one of the POSITION_* constants or a position object supported by the implementation. @param obj: The object containing the range of text being represented.

_get_UIAElementAtStart()
UIAElementAtStart
_abc_impl = <_abc._abc_data object>
class UIAHandler.browseMode.UIABrowseModeDocument(*args, **kwargs)

Bases: UIADocumentWithTableNavigation, BrowseModeDocumentTreeInterceptor

TextInfo

alias of UIABrowseModeDocumentTextInfo

shouldRememberCaretPositionAcrossLoads = False
_nativeAppSelectionMode: bool = True

Whether native selection mode is turned on or off

event_UIA_activeTextPositionChanged(obj, nextHandler, textRange=None)
_iterNodesByType(nodeType, direction='next', pos=None)

Yields L{QuickNavItem} objects representing the ordered positions in this document according to the type being searched for (e.g. link, heading, table etc). @param itemType: the type being searched for (e.g. link, heading, table etc) @type itemType: string @param direction: the direction in which to search (next, previous, up) @type direction: string @param pos: the position in the document from where to start the search. @type pos: Usually an L{textInfos.TextInfo} @raise NotImplementedError: This type is not supported by this BrowseMode implementation

_get_isAlive()

Whether this interceptor is alive. If it is not alive, it will be removed.

_abc_impl = <_abc._abc_data object>
isAlive
_propertyCache: Set[GetterMethodT]

UIAHandler.constants module

class UIAHandler.constants.FillType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

NONE = 0
COLOR = 1
GRADIENT = 2
PICTURE = 3
PATTERN = 4
class UIAHandler.constants.UIAutomationType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

INT = 1
BOOL = 2
STRING = 3
DOUBLE = 4
POINT = 5
RECT = 6
ELEMENT = 7
ARRAY = 8
OUT = 9
INT_ARRAY = 10
BOOL_ARRAY = 11
STRING_ARRAY = 12
DOUBLE_ARRAY = 13
POINT_ARRAY = 14
RECT_ARRAY = 15
ELEMENT_ARRAY = 16
OUT_INT = 17
OUT_BOOL = 18
OUT_STRING = 19
OUT_DOUBLE = 20
OUT_POINT = 21
OUT_RECT = 22
OUT_ELEMENT = 23
OUT_INT_ARRAY = 24
OUT_BOOL_ARRAY = 25
OUT_STRING_ARRAY = 26
OUT_DOUBLE_ARRAY = 27
OUT_POINT_ARRAY = 28
OUT_RECT_ARRAY = 29
OUT_ELEMENT_ARRAY = 30
class UIAHandler.constants.WinConsoleAPILevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Defines actively used Windows Console versions and the levels of custom code required for each.

END_INCLUSIVE = 0
IMPROVED = 1
FORMATTED = 2

UIAHandler.customAnnotations module

This module provides helpers and a common format to define UIA custom annotation types. The common custom annotation types are defined here. Custom annotation types specific to an application should be defined within a NVDAObjects/UIA submodule specific to that application, E.G. ‘NVDAObjects/UIA/excel.py’

UIA originally had hard coded ‘static’ ID’s for annotation types. For an example see ‘AnnotationType_SpellingError’ in source/comInterfaces/_944DE083_8FB8_45CF_BCB7_C477ACB2F897_0_1_0.py imported via UIAutomationClient.py. When a new annotation type was added the UIA spec had to be updated. Now a mechanism is in place to allow applications to register “custom annotation types”. This relies on both the UIA server application and the UIA client application sharing a known GUID for the annotation type.

class UIAHandler.customAnnotations.CustomAnnotationTypeInfo(guid: GUID)

Bases: object

Holds information about a CustomAnnotationType This makes it easy to define custom annotation types to be loaded.

guid: GUID
_registeredAnnotations: ClassVar[Dict[GUID, int]] = {}
_registerCustomAnnotation() int

Registers the annotation with a given GUID.

A GUID uniquely identifies a custom annotation, but the UIA system relies on integer IDs. Any application (clients or providers) can register a custom annotation type, subsequent applications will get the same id for a given GUID. Registering custom annotations is only supported on Windows 11 and above. For any lesser version, id will be 0.

property id: int

Return an ID for a given annotation registering it first if necessary.

Id’s of all registered annotations are cached when requested for the first time to prevent unnecessary work by repeatedly interacting with UIA .

class UIAHandler.customAnnotations.CustomAnnotationTypesCommon

Bases: object

UIA ‘custom annotation types’ common to all applications. Once registered, all subsequent registrations will return the same ID value.

UIAHandler.customProps module

This module provides helpers and a common format to define UIA custom properties. The common custom properties are defined here. Custom properties specific to an application should be defined within a NVDAObjects/UIA submodule specific to that application, E.G. ‘NVDAObjects/UIA/excel.py’

UIA originally had hard coded ‘static’ ID’s for properties. For an example see ‘UIA_SelectionPatternId’ in source/comInterfaces/_944DE083_8FB8_45CF_BCB7_C477ACB2F897_0_1_0.py imported via UIAutomationClient.py. When a new property was added the UIA spec had to be updated. Now a mechanism is in place to allow applications to register “custom properties”. This relies on both the UIA server application and the UIA client application sharing a known GUID for the property.

class UIAHandler.customProps.CustomPropertyInfo(guid: GUID, programmaticName: str, uiaType: UIAutomationType)

Bases: object

Holds information about a CustomProperty This makes it easy to define custom properties to be loaded.

guid: GUID
programmaticName: str
uiaType: UIAutomationType
_registeredProperties: ClassVar[Dict[GUID, int]] = {}
_registerCustomProperty() int

Registers a custom property with a given id.

UIA will return the id to use when given the GUID. Any application can be first to register a custom property, subsequent applications will be given the same id.

property id: int

Return the integer id of the given property registering it first if necessary.

Id’s of all registered properties are cached when requested for the first time to prevent unnecessary work by repeatedly interacting with UIA.

class UIAHandler.customProps.CustomPropertiesCommon

Bases: object

UIA ‘custom properties’ common to all applications. Once registered, all subsequent registrations will return the same ID value.

UIAHandler.remote module

UIAHandler.remote.isSupported() bool

Returns whether UIA remote operations are supported on this version of Windows.

UIAHandler.remote.initialize(doRemote: bool, UIAClient: IUIAutomation)

Initializes UI Automation remote operations. The following parameters are deprecated and ignored: @param doRemote: true if code should be executed remotely, or false for locally. @param UIAClient: the current instance of the UI Automation client library running in NVDA.

UIAHandler.remote.terminate()

Terminates UIA remote operations support.

UIAHandler.remote.msWord_getCustomAttributeValue(docElement: IUIAutomationElement, textRange: IUIAutomationTextRange, customAttribID: int) Any | None
UIAHandler.remote.collectAllHeadingsInTextRange(textRange: IUIAutomationTextRange) Generator[tuple[int, str, IUIAutomationElement], None, None]
UIAHandler.remote.findFirstHeadingInTextRange(textRange: IUIAutomationTextRange, wantedLevel: int | None = None, reverse: bool = False) tuple[int, str, IUIAutomationElement] | None

UIAHandler.types module

class UIAHandler.types._IUIAutomationTextRangeT(*args, **kwargs)

Bases: Protocol

clone() IUIAutomationTextRangeT
compare(other: IUIAutomationTextRangeT) bool
CompareEndpoints(source: int, rangeObject: IUIAutomationTextRangeT, target: int) int
ExpandToEnclosingUnit(unit: int) None
findText() IUIAutomationTextRangeT
GetBoundingRectangles() List
getText(index: int) str
Move(unit: int, direction: int) None
MoveEndpointByRange(source: int, rangeObject: IUIAutomationTextRangeT, target: int) None
MoveEndpointByUnit(endPoint: int, unit: int, direction: int) None
Select() None
_abc_impl = <_abc._abc_data object>
_is_protocol = True
class UIAHandler.types.IUIAutomationTextRangeT(name, bases, namespace)

Bases: _cominterface_meta, _IUIAutomationTextRangeT

_abc_impl = <_abc._abc_data object>
_is_protocol = False

UIAHandler.utils module

UIAHandler.utils.createUIAMultiPropertyCondition(*dicts)

A helper function that Creates a complex UI Automation Condition matching on various UI Automation properties with both ‘and’ and ‘or’. Arguments to this function are dicts whos keys are UI Automation property IDs, and whos values are a list of possible values for the property ID. The dicts are joined with ‘or’, the keys in each dict are joined with ‘and’, and the values for each key are joined with ‘or’. For example, to create a condition that matches on a controlType of button or edit and where isReadOnly is True, or, className is ‘ding’, you would provide arguments of: {UIA_ControlTypePropertyId:[UIA_ButtonControlTypeId,UIA_EditControlTypeId],UIA_Value_ValueIsReadOnly:[True]},{UIA_ClassNamePropertyId:[‘ding’]}

UIAHandler.utils.UIATextRangeFromElement(documentTextPattern, element)

Wraps IUIAutomationTextRange::getEnclosingElement, returning None on COMError.

UIAHandler.utils.isUIAElementInWalker(element, walker)

Checks if the given IUIAutomationElement exists in the given IUIAutomationTreeWalker by calling IUIAutomationTreeWalker::normalizeElement and comparing the fetched element with the given element.

UIAHandler.utils.getDeepestLastChildUIAElementInWalker(element, walker)

Starting from the given IUIAutomationElement, walks to the deepest last child of the given IUIAutomationTreeWalker.

exception UIAHandler.utils.UIAMixedAttributeError

Bases: ValueError

Raised when a function would return a UIAutomation text attribute value that is mixed.

UIAHandler.utils.getUIATextAttributeValueFromRange(rangeObj, attrib, ignoreMixedValues=False)

Wraps IUIAutomationTextRange::getAttributeValue, returning UIAutomation’s reservedNotSupportedValue on COMError, and raising UIAMixedAttributeError if a mixed value would be returned and ignoreMixedValues is False.

UIAHandler.utils.iterUIARangeByUnit(rangeObj, unit, reverse=False)

Splits a given UI Automation text range into smaller text ranges the size of the given unit and yields them. @param rangeObj: the UI Automation text range to split. @type rangeObj: L{UIAHandler.IUIAutomationTextRange} @param unit: a UI Automation text unit. @param reverse: true if the range should be walked backwards (from end to start) @type reverse: bool @rtype: a generator that yields L{UIAHandler.IUIAutomationTextRange} objects.

UIAHandler.utils.getEnclosingElementWithCacheFromUIATextRange(textRange, cacheRequest)

A thin wrapper around IUIAutomationTextRange3::getEnclosingElementBuildCache if it exists, otherwise IUIAutomationTextRange::getEnclosingElement and then IUIAutomationElement::buildUpdatedCache.

class UIAHandler.utils.CacheableUIAElementArray(elementArray, cacheRequest=None)

Bases: object

property length
getElement(index)
UIAHandler.utils.getChildrenWithCacheFromUIATextRange(textRange, cacheRequest)

A thin wrapper around IUIAutomationTextRange3::getChildrenBuildCache if it exists, otherwise IUIAutomationTextRange::getChildren but wraps the result in an object that automatically calls IUIAutomationElement::buildUpdateCache on any element retreaved.

UIAHandler.utils.isTextRangeOffscreen(textRange, visiRanges)

Given a UIA text range and a visible textRanges array (returned from obj.UIATextPattern.GetVisibleRanges), determines if the given textRange is not within the visible textRanges.

class UIAHandler.utils.UIATextRangeAttributeValueFetcher(textRange)

Bases: object

getValue(ID, ignoreMixedValues=False)
class UIAHandler.utils.BulkUIATextRangeAttributeValueFetcher(textRange, IDs)

Bases: UIATextRangeAttributeValueFetcher

getValue(ID, ignoreMixedValues=False)
class UIAHandler.utils.FakeEventHandlerGroup(clientObject)

Bases: object

Mimics the behavior of UiAutomation 6+ Event Handler Groups for older versions.

property clientObject
AddAutomationEventHandler(eventId, scope, cacheRequest, handler)
AddNotificationEventHandler(scope, cacheRequest, handler)
AddPropertyChangedEventHandler(scope, cacheRequest, handler, propertyArray, propertyCount)
registerToClientObject(element)
unregisterFromClientObject(element)
UIAHandler.utils._shouldUseUIAConsole(hwnd: int) bool

Determines whether to use UIA in the Windows Console.

UIAHandler.utils._getConhostAPILevel(hwnd: int) WinConsoleAPILevel

This function determines which of several console UIA workarounds are needed in a given conhost instance. See the comments on the WinConsoleAPILevel enum for details.

UIAHandler.utils._shouldSelectivelyRegister() bool

Determines whether to register for UIA events selectively or globally.

UIAHandler.utils._shouldUseWindowsTerminalNotifications() bool

Determines whether to use notifications for new text reporting in Windows Terminal.

UIAHandler.utils._isFrameworkIdWinForm(hwnd: int) bool

Returns whether this window belongs to an element that originates from the Windows Forms framework (WinForm). This is used to determine whether a native UIA implementation should be used for SysListView32 controls.