5_UI Automation (Part 1 of 5) Client Interfaces

7/27/2019 5_UI Automation (Part 1 of 5) Client Interfaces

1/254

Revision 1.0.0 (February 9, 2009)

UI Automation (part 1 of 5)

2009 Microsoft Corporation. All rights reserved. Permission to copy, display and distribute this document is available at

http://go.microsoft.com/fwlink/?LinkID=104273&clcid=0x409 .

UI Automation (Part 1 of 5)

Reference Specification for Unmanaged Client Interfaces


2/254





Legal Notice

Permission to copy, display, and distribute the contents of this document (the "Specification"), in any medium for

any purpose without fee or royalty is hereby granted, provided that you include the following notice on ALL copies

of the Specification, or portions thereof, that you make:

2009 Microsoft Corporation. All rights reserved. Permission to copy, display, and distribute this document isavailable atUI Automation Community Promise.

You may create derivative works of the Specification, provided that you include all required portions of the

Specification in your derivative work, and provide the notice above.

There is a separate patent promise available to parties interested in implementing software that conforms to the UI

Automation Specification. This patent license is available at this location:UI Automation Community Promise

The Specification is provided "as is" and Microsoft makes no representations or warranties, express or implied,

including, but not limited to, warranties of merchantability, fitness for a particular purpose, non-infringement, or

title; that the contents of the Specification are suitable for any purpose; nor that the implementation of such

contents will not infringe any third-party patents, copyrights, trademarks or other rights. Microsoft will not be liablefor any direct, indirect, special, incidental or consequential damages arising out of or relating to any use or

distribution of the Specification.

The name and trademarks of Microsoft may NOT be used in any manner, including advertising or publicity

pertaining to the Specification or its contents without specific, written prior permission. Title to copyright in the

Specification will at all times remain with Microsoft.

No other rights are granted by implication, estoppel or otherwise.
http://msdn.microsoft.com/en-us/accessibility/bb892136.aspxhttp://msdn.microsoft.com/en-us/accessibility/bb892136.aspxhttp://msdn.microsoft.com/en-us/accessibility/bb892136.aspxhttp://msdn.microsoft.com/en-us/accessibility/bb892136.aspxhttp://msdn.microsoft.com/en-us/accessibility/bb892136.aspxhttp://msdn.microsoft.com/en-us/accessibility/bb892136.aspxhttp://msdn.microsoft.com/en-us/accessibility/bb892136.aspxhttp://msdn.microsoft.com/en-us/accessibility/bb892136.aspx


3/254





Synopsis

This document is a reference specification for the UI Automation Unmanaged Client Interfaces. It is part

1 of the fifth section of the UI Automation Community Promise Specification, which consists of the

following parts:

1.

Overview of Accessibility Frameworks

2.

Microsoft Active Accessibility

3.

Common Infrastructure

4.

IAccessibleEx Interface

5.

UI Automation

Part 1: Client Interfaces (this document)

Part 2: Provider Interfaces

Part 3: Custom Properties, Control Patterns, and Events

Part 4: Common Interfaces and Definitions for Clients and Providers

Part 5: Control Types

6.

UI Automation in Managed APIs

Part 1: Managed Classes for the Clients

Part 2: Managed Classes for the Providers and Client-Side Providers

7.

Microsoft Active Accessibility to UI Automation Proxy

8.

UI Automation to Microsoft Active Accessibility Bridge

9.

UI Automation for W3C Accessible Rich Internet Applications Specifications


4/254





Contents

Baseline Interfaces............................................................................................................................................. 6

IUIAutomation Interface ................................................................................................................................. 6

IUIAutomationElement Interface .................................................................................................................. 47

IUIAutomationElementArray Interface ........................................................................................................ 103

IUIAutomationTreeWalker Interface ........................................................................................................... 104

IUIAutomationCacheRequest Interface ....................................................................................................... 116

IUIAutomationCondition Interface .............................................................................................................. 121

IUIAutomationAndCondition Interface ........................................................................................................ 121

IUIAutomationBoolCondition Interface ....................................................................................................... 123

IUIAutomationNotCondition Interface ........................................................................................................ 124

IUIAutomationOrCondition Interface .......................................................................................................... 125

IUIAutomationPropertyCondition Interface................................................................................................. 127

Control Pattern Interfaces for Clients ............................................................................................................ 129

IUIAutomationDockPattern Interface .......................................................................................................... 129

IUIAutomationExpandCollapsePattern Interface ......................................................................................... 131IUIAutomationGridPattern Interface ........................................................................................................... 134

IUIAutomationGridItemPattern Interface .................................................................................................... 138

IUIAutomationInvokePattern Interface ....................................................................................................... 144

IUIAutomationItemContainerPattern .......................................................................................................... 145

IUIAutomationLegacyIAccessiblePattern ..................................................................................................... 146

IUIAutomationMultipleViewPattern Interface ............................................................................................. 160

IUIAutomationRangeValuePattern Interface ............................................................................................... 164

IUIAutomationScrollPattern Interface ......................................................................................................... 171

IUIAutomationScrollItemPattern Interface .................................................................................................. 181

IUIAutomationSelectionPattern Interface ................................................................................................... 182

IUIAutomationSelectionItemPattern Interface ............................................................................................ 185

IUIAutomationSynchronizedInputPattern ................................................................................................... 189

IUIAutomationTablePattern Interface ......................................................................................................... 190

IUIAutomationTableItemPattern Interface .................................................................................................. 194

IUIAutomationTextPattern Interface ........................................................................................................... 196

IUIAutomationTextRange Interface ............................................................................................................. 201

IUIAutomationTextRangeArray Interface..................................................................................................... 217

IUIAutomationTogglePattern Interface ....................................................................................................... 219

IUIAutomationTransformPattern Interface.................................................................................................. 221

IUIAutomationValuePattern Interface ......................................................................................................... 226

IUIAutomationVirtualizedItemPattern ......................................................................................................... 229

IUIAutomationWindowPattern Interface ..................................................................................................... 230

Event Handlers............................................................................................................................................... 238

IUIAutomationEventHandler Interface ........................................................................................................ 238

IUIAutomationFocusChangedEventHandler Interface ......................... .......................... .......................... ..... 240

IUIAutomationPropertyChangedEventHandler Interface ............................................................................. 240

IUIAutomationStructureChangedEventHandler Interface ............................................................................ 241

Proxy Factory Interfaces ................................................................................................................................ 242

IUIAutomationProxyFactory Interface ......................................................................................................... 242


5/254


6/254





Baseline Interfaces

IUIAutomation Interface

The IUIAutomationinterface is the basic interface that enables UI Automation client applications to

discover, access, and filter user interface (UI) elements. UI Automation exposes every element of the UI

as an object represented by the IUIAutomationinterface.

Members

Properties Methods

RawViewCondition CompareElements

ControlViewCondition CompareRuntimeIds

ContentViewCondition GetPropertyProgrammaticName

RawViewWalker GetPatternProgrammaticName

ControlViewWalker AddAutomationEventHandler

ContentViewWalker RemoveAutomationEventHandler

ProxyFactoryMapping AddPropertyChangedEventHandler

ReservedNotSupportedValue AddPropertyChangedEventHandlerNativeArray

ReservedMixedAttributeValue RemovePropertyChangedEventHandler

AddStructureChangedEventHandler

RemoveStructureChangedEventHandler

AddFocusChangedEventHandler

RemoveFocusChangedEventHandler

RemoveAllEventHandlers

GetRootElement

ElementFromHandle

ElementFromPoint

ElementFromIAccessible

GetFocusedElement

GetRootElementBuildCache

ElementFromHandleBuildCache

ElementFromPointBuildCache

ElementFromIAccessibleBuildCache

GetFocusedElementBuildCacheCreateTreeWalker

CreateCacheRequest

CreateTrueCondition

CreateFalseCondition

CreatePropertyCondition

CreatePropertyConditionEx


7/254


8/254





Type Description

HRESULT Returns S_OKif successful or an error value otherwise.

ControlViewCondition

The get_ControlViewConditionmethod retrieves an IUIAutomationConditioninterface for a

predefined condition that retrieves all control elements.

Language Syntax

C++ HRESULT get_ControlViewCondition(IUIAutomationCondition **condition);

Parameters

Parameter Description

condition The address of a variable that receives a pointer to an IUIAutomationCondition

interface.

Return Value

Type Description


ContentViewCondition

The get_ContentViewConditionmethod retrieves an IUIAutomationConditioninterface for a

predefined condition that retrieves all content elements.

Language Syntax

C++ HRESULT get_ContentViewCondition(IUIAutomationCondition **condition);

Parameters


condition The address of a variable that receives a pointer to the IUIAutomationCondition

interface.


9/254






10/254





Return Value

Type Description


RawViewWalker

The get_RawViewWalkermethod retrieves an IUIAutomationTreeWalkerinterface used to traverse an

unfiltered view of the UI Automation tree.

Language Syntax

C++ HRESULT get_RawViewWalker(IUIAutomationTreeWalker **walker);

Parameters


walker The address of a variable that receives a pointer to theIUIAutomationTreeWalker

interface.

Return Value

Type Description


ControlViewWalker

The get_ControlViewWalkermethod retrieves an IUIAutomationTreeWalkerinterface used to

discover control elements.

Language Syntax

C++ HRESULT get_ControlViewWalker(IUIAutomationTreeWalker **walker);

Parameters


walker The address of a variable that receives a pointer to the IUIAutomationTreeWalker

interface.


11/254





Return Value

Type Description


ContentViewWalker

The get_ContentViewWalkermethod retrieves an IUIAutomationTreeWalkerinterface used to

discover content elements.

Language Syntax

C++ HRESULT get_ContentViewWalker(IUIAutomationTreeWalker **walker);

Parameters


walker The address of a variable that receives a pointer to the IUIAutomationTreeWalker

interface.

Return Value

Type Description


ProxyFactoryMapping

The get_ProxyFactoryMappingmethod retrieves an IUIAutomationProxyFactoryMappinginterface

that represents the mapping of window class names and associated data to individual proxy factories.

Language Syntax

C++HRESULT get_ProxyFactoryMapping(IUIAutomationProxyFactoryMapping

**factoryMapping);


12/254





Parameters


factoryMapping The address of a variable that receives a pointer to the

IUIAutomationProxyFactoryMappinginterface.

Return Value

Type Description


ReservedNotSupportedValue

The get_ReservedNotSupportedValuemethod retrieves a static token object representing a property

that is not supported. This object can be used for comparison with results returned from

IUIAutomationElement::GetCurrentPropertyValue.

Language Syntax

C++ HRESULT get_ReservedNotSupportedValue(IUnknown **notSupportedValue);

Parameters


notSupportedValue The address of a variable that receives a pointer to theIUnknowninterface on the

static token object.

Return Value

Type Description


ReservedMixedAttributeValue

The get_ReservedMixedAttributeValuemethod retrieves a static token object representing a text

attribute that is a mixed attribute. This ReservedMixedAttributeValue object can be used for comparison

with results returned from ITextRangeProvider::GetAttributeValue.


13/254





Language Syntax

C++ HRESULT get_ReservedMixedAttributeValue(IUnknown

**mixedAttributeValue);

Parameters


mixedAttributeValue The address of a variable that receives a pointer to theIUnknowninterface on the

static token object.

Return Value

Type DescriptionHRESULT Returns S_OKif successful or an error value otherwise.

Methods

CompareElements

The CompareElementsmethod compares two UI Automation elements to determine whether they

represent the same underlying UI element.

Language Syntax

C++ HRESULT CompareElements(IUIAutomationElement *el1,

IUIAutomationElement *el2, BOOL *areSame);

Parameters


el1[in] The first element to compare.

el2 [in] The second element to compare.

areSame [out,

retval]

The address of a variable that receives TRUE if the run-time identifiers of the

elements are the same, or FALSE otherwise.

Return Value


14/254





Type Description


CompareRuntimeIds

The CompareRuntimeIdsmethod compares two integer arrays containing run-time identifiers (IDs) to

determine whether their content is the same and they belong to the same UI element.

Language Syntax

C++ HRESULT CompareRuntimeIds(SAFEARRAY *runtimeId1, SAFEARRAY

*runtimeId2, BOOL *areSame);

Parameters


runtimeId1 [in] The first ID to compare.

runtimeId2 [in] The second ID to compare

areSame [out, retval] The address of a variable that receives TRUE if the IDs are the same, or FALSE if

they are not.

Return Value

Type Description


Remarks

The run-time ID of a UI Automation element is an array of integers. This method makes comparison

easier.


15/254





GetPropertyProgrammaticName

The GetPropertyProgrammaticNamemethod retrieves the registered programmatic name of a

property.

Language Syntax

C++ HRESULT GetPropertyProgrammaticName(PROPERTYID property, BSTR *name);

Parameters


property [in] The property identifier.

name [out,

retval]

The address of a variable that receives a pointer to the name.

Return Value

Type Description


Remarks

The programmatic name is intended for debugging and diagnostic purposes only. The string is not

localized.

This property should not be used in string comparisons. To determine whether two properties are the

same, compare the property identifiers directly.

GetPatternProgrammaticName

The GetPatternProgrammaticNamemethod gets the registered programmatic name of a control

pattern.

Language Syntax

C++ HRESULT GetPatternProgrammaticName(PATTERNID pattern, BSTR *name);


16/254





Parameters


pattern [in] The control pattern identifier.

name [out,

retval]

The address of a variable that receives a pointer to the name.

Return Value

Type Description


Remarks

The programmatic name is intended for debugging and diagnostic purposes only. The string is not

localized.

This property should not be used in string comparisons. To determine whether two properties are the

same, compare the pattern identifiers directly.

AddAutomationEventHandlerThe AddAutomationEventHandlermethod registers a method that handles UI Automation events.

Language Syntax

C++ HRESULT AddAutomationEventHandler(EVENTID eventId, IUIAutomationElement

*element, TreeScope scope, IUIAutomationCacheRequest *cacheRequest,

IUIAutomationEventHandler *handler);


17/254





Parameters


eventId [in] The identifier for the event that the method handles.

element [in] The UI Automation element to associate with the event handler.

scope [in] The scope of events to be handled; that is, whether they are on the element itself, or

on its ancestors and descendants.

cacheRequest

[in]

The cache request, or NULL if no caching is wanted.

handler [in] The IUIAutomationEventHandlerinterface of the object that handles the event.

Return Value

Type Description


RemoveAutomationEventHandler

The RemoveAutomationEventHandlermethod removes the specified UI Automation event handler.

Language Syntax

C++ HRESULT RemoveAutomationEventHandler(EVENTID eventId,

IUIAutomationElement *element, IUIAutomationEventHandler *handler);

Parameters


eventId [in] The ID of the event being handled.

Element [in] The UI Automation element that is handling the event.

Handler [in] The handler method that was passed to

IUIAutomation::AddAutomationEventHandlerfor the specified event identifier and

UI Automation element.


18/254





Return Value

Type Description


AddPropertyChangedEventHandler

The AddPropertyChangedEventHandlermethod registers a method that handles property-changed

events.

Language Syntax

C++ HRESULT AddPropertyChangedEventHandler(IUIAutomationElement *element,

TreeScope scope, IUIAutomationCacheRequest *cacheRequest,

IPropertyChangedEventHandler *pHandler, SAFEARRAY(PROPERTYID)

*propertyArray);

Parameters


element [in] The UI Automation element with which to associate the event handler.


on its ancestors and children.

cacheRequest

[in]The cache request, or NULL if no caching is wanted.

handler [in] The IUIAutomationPropertyChangedEventHandlerinterface of the object that

handles the event.

propertyArray

[in]

The UI Automation properties of interest.

Return Value

Type Description



19/254





AddPropertyChangedEventHandlerNativeArray

The AddPropertyChangedEventHandlermethod creates a condition that selects elements based on

multiple conditions, all of which must be true.

Language Syntax

C++ HRESULT AddPropertyChangedEventHandler(IUIAutomationElement *element,


IPropertyChangedEventHandler *pHandler, PROPERTYID *propertyArray, int

propertyCount);

Parameters




on its ancestors and children.

cacheRequest

[in]

The cache request, or NULL if caching is not needed.

handler [in] The IUIAutomationPropertyChangedEventHandlerinterface of the object that

handles the event.

propertyArray

[in]

The UI Automation properties of interest.

propertyCount

[in]

The number of elements inpropertyArray.

Return Value

Type Description



20/254





RemovePropertyChangedEventHandler

The RemovePropertyChangedEventHandlermethod removes a method that handles property-changed

events.

Language Syntax

C++ HRESULT RemovePropertyChangedEventHandler(IUIAutomationElement

*element, IPropertyChangedEventHandler *handler);

Parameters


element [in] The UI Automation element from which to remove the handler.

handler [in] The interface that was passed to

IUIAutomation::AddPropertyChangedEventHandler.

Return Value

Type Description


AddStructureChangedEventHandlerThe AddStructureChangedEventHandlermethod registers a method that handles structure-changed

events.

Language Syntax

C++ HRESULT AddStructureChangedEventHandler(IUIAutomationElement *element,


IStructureChangedEventHandler *handler);


21/254





Parameters




on its ancestors and descendants.

cacheRequest

[in]

The cache request, or NULL if caching is not wanted.

handler [in] The IUIAutomationStructureChangedEventHandlerinterface of the object that

handles the structure-changed event.

Return Value

Type Description


RemoveStructureChangedEventHandler

The RemoveStructureChangedEventHandlermethod removes a structure-changed event handler.

Language Syntax

C++ HRESULT RemoveStructureChangedEventHandler(IUIAutomationElement

*element, IStructureChangedEventHandler *handler);

Parameters


element [in] The UI Automation element from which to remove the handler.

handler [in] The interface that was passed to

IUIAutomation::AddStructureChangedEventHandler.

Return Value

Type Description



22/254





AddFocusChangedEventHandler

The AddFocusChangedEventHandlermethod registers a method that handles focus-changed events.

Language Syntax

C++ HRESULT AddFocusChangedEventHandler(IUIAutomationCacheRequest*cacheRequest, IFocusChangedEventHandler *handler);

Parameters


cacheRequest

[in]

The cache request, or NULL if no caching is wanted.

handler [in] The IUIAutomationFocusChangedEventHandlerof the object that handles the event.

Return Value

Type Description


RemoveFocusChangedEventHandler

The RemoveFocusChangedEventHandlermethod removes a focus-changed event handler.

Language Syntax

C++ HRESULT RemoveFocusChangedEventHandler(IFocusChangedEventHandler

*pHandler);

Parameters


handler [in] The event handler that was passed to

IUIAutomation::AddFocusChangedEventHandler.


23/254





Return Value

Type Description


RemoveAllEventHandlers

The RemoveAllEventHandlersmethod removes all registered UI Automation event handlers.

Language Syntax

C++ HRESULT RemoveAllEventHandlers();

Return Value

Type Description


GetRootElement

The GetRootElementmethod retrieves the UI Automation element that represents the desktop.

Language Syntax

C++ HRESULT GetRootElement(IUIAutomationElement **root);

Parameters


root [out,

retval]

The address of a variable that receives the IUIAutomationElementinterface pointer.

Return Value

Type Description



24/254





Remarks

You can use the root element as a starting point for finding other elements, usingthe

IUIAutomationElement::FindAlland IUIAutomationElement::FindFirstmethods.

When searching from the root element, be sure to specify TreeScope_Children in the scope of the

search, not TreeScope_Descendants. A search through the entire subtree of the desktop could iterate

through thousands of items and lead to a stack overflow.

ElementFromHandle

The ElementFromHandlemethod retrieves a UI Automation element for the specified window.

Language Syntax

C++ HRESULT ElementFromHandle(HWND hwnd, IUIAutomationElement **element);

Parameters


hwnd [in] The window handle.

element [out,

retval]

The address of a variable that receives a pointer to theIUIAutomationElement

interface.

Return Value

Type Description


ElementFromPoint

The ElementFromPointmethod retrieves the UI Automation element for the UI item at the specified

point on the desktop.

Language Syntax

C++ HRESULT ElementFromPoint(POINT pt, IUIAutomationElement **element);


25/254





Parameters


pt [in] The desktop coordinates.

element [out,

retval]


interface.

Return Value

Type Description


Remark

The ElementFromPoint method returns the UIA_E_ELEMENTNOTAVAILABLE error code if the element

under the point is already removed by the time the method returns. Clients should handle errors from

this method gracefully; for example, by trying the call again.

ElementFromIAccessible

The ElementFromIAccessiblemethod retrieves the UI Automation element for the specified Microsoft

Active Accessible object.

Language Syntax

C++ HRESULT ElementFromIAccessible ( IAccessible * accessible, int childId,

IUIAutomationElement ** element );

Parameters


accessible [in] The address of IAccessible interface for the accessible object specified


26/254


27/254





Remark

The GetFocusedElement method returns the UIA_E_ELEMENTNOTAVAILABLE error code if the focused

element is already removed by the time the method returns. Clients should handle errors from thismethod gracefully; for example, by trying the call again.

GetRootElementBuildCache

The GetRootElementBuildCachemethod retrieves the UI Automation element that represents the

desktop, and the framework pre-fetches the items that are specified by the cache request.

Language Syntax

C++ HRESULT GetRootElementBuildCache(IUIAutomationCacheRequest

*cacheRequest, IUIAutomationElement **root);

Parameters


cacheRequest

[in]

The cache request, which specifies the properties and control patterns to store in the

cache.

root [out,

retval]


interface.

Return Value

Type Description



28/254





Remarks

You can use the root element as a starting point for finding other elements, by using the

IUIAutomationElement::FindAlland IUIAutomationElement::FindFirstmethods.

When searching from the root element, be sure to specify TreeScope_Children in the scope of the

search, not TreeScope_Descendants. A search through the entire subtree of the desktop could iterate

through thousands of items and lead to a stack overflow.

GetElementFromHandleBuildCache

The ElementFromHandleBuildCachemethod retrieves a UI Automation element for the specified

window, and the framework pre-fetches the items that are specified by the cache request.

Language Syntax

C++ HRESULT ElementFromHandleBuildCache(HWND hwnd,

IUIAutomationCacheRequest *cacheRequest,

IUIAutomationElement **element);

Parameters


hwnd[in] The window handle.

cacheRequest[in]

The cache request, which specifies the properties and control patterns to store in thecache.

element[out,

retval]

The address of a variable that receives the IUIAutomationElementinterface pointer.

Return Value



29/254


30/254





Parameters


accessible [in] The address of the IAccessible interface of the accessible object.

childId [in] The ChildId of the accessible object.

cacheRequest

[in]


cache.

element [out,

retval]

The address of a variable that receives a pointer to the IUIAutomationElement

interface.

Return Value

Type Description


Remark

This method is supported where a Microsoft Active Accessibility Server is implemented. The result is notguaranteed when the server implements UI Automation Provider interfaces side by side with the

Microsoft Active Accessibility support. The function may return E_INVALIDARG, if a client passes an

OLEACC or UIA-to-MSAA Bridge object to the accessibleand childIdparameters.

GetFocusedElementBuildCache

The GetFocusedElementBuildCachemethod retrieves the UI Automation element that has the input

focus, and the framework pre-fetches the items that are specified by the cache request.

Language Syntax

C++ HRESULT GetFocusedElementBuildCache(IUIAutomationCacheRequest

*cacheRequest,

IUIAutomationElement **element);


31/254






32/254





Parameters


cacheRequest

[in]


cache.

element[out,

retval]


interface.

Return Value

Type Description


CreateTreeWalker

The CreateTreeWalkermethod retrieves an object that can be used to traverse the UI Automation

tree.

Language Syntax

C++ HRESULT CreateTreeWalker(IUIAutomationCondition *condition, ITreeWalker

**walker);

Parameters


condition[in] A condition that specifies the elements of interest.

walker[out,retval]

The address of a variable that receives a pointer to the IUIAutomationTreeWalkerinterface.


33/254


34/254


35/254





Language Syntax

C++ HRESULT CreatePropertyCondition(PROPERTYID propertyId, VARIANT value,

IUIAutomationCondition **newCondition);

Parameters


propertyId[in] The property identifier.

value[in] The property value.

newCondition

[out, retval]

The address of a variable that receives a pointer to the IUIAutomationCondition

interface representing the condition.

Return Value

Type Description


CreatePropertyConditionEx

The CreatePropertyConditionExmethod creates a condition that selects elements in which a

property has the specified value, and conditions indicated by optional flags are also met.

Language Syntax

C++ HRESULT CreatePropertyConditionEx(PROPERTYID propertyId, VARIANT value,

PropertyConditionFlags flags, IUIAutomationCondition **newCondition);

Parameters



value[in] The property value.


36/254





flags[in] Flags that affect the comparison.

newCondition

[out, retval]


interface representing the condition.

Return Value

Type Description


CreateAndCondition

The CreateAndConditionmethod creates a condition that selects elements that match both of two

conditions.

Language Syntax

C++ HRESULT CreateAndCondition(IUIAutomationCondition *condition1,

IUIAutomationCondition *condition2, IUIAutomationCondition

**newCondition);

Parameters


condition1[in] The first condition to match.

condition2[in] The second condition to match.

newCondition[out,

retval]


interface representing the combined condition.

Return Value

Type Description



37/254





CreateAndConditionFromArray

The CreateAndConditionFromArraymethod creates a condition that selects elements based on


Language Syntax

C++ HRESULT CreateAndConditionFromArray(SAFEARRAY(IUIAutomationCondition)

*conditions, IUIAutomationCondition **newCondition);

Parameters


conditions[in] A SAFEARRAY that contains the conditions to be combined.

newCondition

[out, retval]


interface representing the combined condition.

Return Value

Type Description


CreateAndConditionFromNativeArray

The CreateAndConditionFromNativeArraymethod creates a condition that selects elements based on


Language Syntax

C++ HRESULT CreateAndConditionFromNativeArray(IUIAutomationCondition

**conditions, int conditionCount, IUIAutomationCondition

**newCondition);


38/254


39/254


40/254


41/254


42/254





Parameters


intArray[in] The SAFEARRAY to convert.

array[out] The address of a variable that receives a pointer to the allocated array.

arrayCount

[out, retval]

The address of a variable that receives the number of elements in array.

Return Value

Type Description


RectToVariant

The RectToVariantmethod creates a VARIANT that contains the coordinates of a rectangle.

Language Syntax

C++ HRESULT RectToVariant(RECT *rc, VARIANT *var);

Parameters


rc[in] A RECT structure containing the coordinates.

var[out, retval] A VARIANT that receives the coordinates.

Return Value

Type Description



43/254


44/254





Parameters


rects[in] The SAFEARRAY containing the rectangle coordinates.

rectArray[out] The address of a variable that receives a pointer to an array of RECT coordinates.

rectArrayCount

[out, retval]

The address of a variable that receives the number of elements in rectArray.

Return Value

Type Description


CreateProxyFactoryEntry

The CreateProxyFactoryEntrymethod retrieves an object that is used to specify the mapping of UI

Automation events to WinEvents for the specified proxy factory.

Language Syntax

C++ HRESULT CreateProxyFactoryEntry(IUIAutomationProxyFactory *factory,

IUIAutomationProxyFactoryEntry **factoryEntry);

Parameters


factory [in] The proxy factory.

factoryEntry[out,

retval]

The address of a variable that receives a pointer to the

IUIAutomationProxyFactoryEntry interface.


45/254





Return Value

Type Description


PollForPotentialSupportedPatterns

The PollForPotentialSupportedPatternsmethod retrieves the control patterns that might be

supported on a UI Automation element.

Language Syntax

C++ HRESULT PollForPotentialSupportedPatterns( IUIAutomationElement *

pElement, SAFEARRAY(int) * patternIds, SAFEARRAY(BSTR) *

patternNames);

Parameters


pElement[in] The element to poll.

patternIds[out] The address of a variable that receives a pointer to an array of control pattern

identifiers.

patternNames[out] The address of a variable that receives a pointer to an array of control pattern

names.

Return Value

Type Description


Remarks

There is no guarantee that the element will support any particular control pattern when asked for it

later.


46/254





PollForPotentialSupportedProperties

The PollForPotentialSupportedPropertiesmethod retrieves the properties that might be

supported on a UI Automation element.

Language Syntax

C++ HRESULT PollForPotentialSupportedProperties( IUIAutomationElement *

pElement, SAFEARRAY(int) * propertyIds, SAFEARRAY(BSTR) *

propertyNames);

Parameters


pElement[in] The element to poll.

propertyIds[out] The address of a variable that receives a pointer to an array of property

identifiers.

propertyNames

[out]

The address of a variable that receives a pointer to an array of property names.

Return Value


Remarks

There is no guarantee that the element will support any particular property when asked for it later.

CheckNotSupported

The CheckNotSupportedmethod checks a provided VARIANT to see if it contains the Not Supported

identifier

Language Syntax

C++ HRESULT CheckNotSupported(VARIANT value, BOOL * isNotSupported);


47/254


48/254





Properties Methods

CurrentNativeWindowHandle GetCachedChildren

CurrentItemType GetClickablePoint

CurrentIsOffscreen

CurrentOrientationCurrentFrameworkId

CurrentIsRequiredForForm

CurrentItemStatus

CurrentBoundingRectangle

CurrentLabeledBy

CurrentAriaRole

CurrentAriaProperties

CurrentIsDataValidForForm

CurrentControllerFor

CurrentDescribedBy

CurrentFlowsTo

CurrentProviderDescription

CachedProcessId

CachedControlType

CachedLocalizedControlType

CachedName

CachedAcceleratorKey

CachedAccessKey

CachedHasKeyboardFocus

CachedIsKeyboardFocusable

CachedIsEnabled

CachedAutomationId

CachedClassName

CachedHelpText

CachedCulture

CachedIsControlElement

CachedIsContentElement

CachedIsPassword

CachedNativeWindowHandle

CachedItemType

CachedIsOffscreen

CachedOrientation

CachedFrameworkId

CachedIsRequiredForForm


49/254





Properties Methods

CachedItemStatus

CachedBoundingRectangle

CachedLabeledBy

CachedAriaRoleCachedAriaProperties

CachedIsDataValidForForm

CachedControllerFor

CachedDescribedBy

CachedFlowsTo

CachedProviderDescription

Properties

CurrentProcessId

The get_CurrentProcessIdmethod retrieves the ID of the process that hosts the element.

Language Syntax

C++ HRESULT get_CurrentProcessId(int *retVal);

Parameters


retVal The address of a variable that receives the value of the property.

Return Value

Type Description


CurrentControlType

The get_CurrentControlTypemethod retrieves the control type of the element.

Language Syntax

C++ HRESULT get_CurrentControlType(CONTROLTYPEID *retVal);


50/254


51/254


52/254


53/254





CurrentHasKeyboardFocus

The get_CurrentHasKeyboardFocusmethod retrieves the focus state of the element.

Language Syntax

C++ HRESULT get_CurrentHasKeyboardFocus(BOOL *retVal);

Parameters


retVal The address of a variable that receives the value of the property: TRUE if the element

has keyboard focus, otherwise FALSE.

Return Value

Type Description


CurrentIsKeyboardFocusable

The get_CurrentIsKeyboardFocusablemethod retrieves a value indicating whether the element can

take the keyboard focus.

Language Syntax

C++ HRESULT get_CurrentIsKeyboardFocusable(BOOL *retVal);

Parameters



can take keyboard focus, otherwise FALSE.


54/254





Return Value

Type Description


CurrentIsEnabled

The get_CurrentIsEnabledmethod retrieves the CurrentIsEnabled property, which indicates whether

the enabled state of the element.

Language Syntax

C++ HRESULT get_CurrentIsEnabled(BOOL *retVal);

Parameters



is enabled, otherwise FALSE.

Return Value

Type Description


CurrentAutomationId

The get_CurrentAutomationIdmethod retrieves the unique UI Automation identifier for the element.

Language Syntax

C++ HRESULT get_CurrentAutomationId(BSTR *retVal);


55/254





Parameters



Return Value

Type Description


Remarks

The identifier is unique among sibling elements in a container, and is the same in all instances of theapplication.

CurrentClassName

The get_CurrentClassNamemethod retrieves the class name that was assigned to the element by the

control developer.

Language Syntax

C++ HRESULT get_CurrentClassName(BSTR *retVal);

Parameters



Return Value

Type Description



56/254





CurrentHelpText

The get_CurrentHelpTextmethod retrieves the help text for the element.

Language Syntax

C++ HRESULT get_CurrentHelpText(BSTR *retVal);

Parameters



Return Value

Type Description


Remarks

This information is typically obtained from tooltips.

CurrentCulture

The get_CurrentCulturemethod retrieves the Culture property of the element.

Language Syntax

C++ HRESULT get_CurrentCulture(int *retVal);

Parameters




57/254





Return Value

Type Description


CurrentIsControlElement

The get_CurrentIsControlElementmethod retrieves a value indicting whether the element is a

control.

Language Syntax

C++ HRESULT get_CurrentIsControlElement(BOOL *retVal);

Parameters



is a control element, otherwise FALSE.

Return Value

Type Description


Remarks

Controls are elements in the UI that display information, or that can be manipulated by the user to

perform an action.

CurrentIsContentElement

The get_CurrentIsContentElementmethod retrieves a value indicting whether the element is a

content element.

Language Syntax

C++ HRESULT get_CurrentIsContentElement(BOOL *retVal);


58/254


59/254


60/254





Parameters



Return Value

Type Description


Remarks

This property is used to obtain information about items in a list, tree view, or data grid. For example, an

item in a file directory view might be a "Document File" or a "Folder".

CurrentIsOffscreen

The get_CurrentIsOffscreenmethod retrieves the off-screen property of the element.

Language Syntax

C++ HRESULT get_CurrentIsOffscreen(BOOL *retVal);

Parameters



is off screen, otherwise FALSE.

Return Value

Type Description



61/254





CurrentOrientation

The get_CurrentOrientationmethod retrieves the orientation of the element.

Language Syntax

C++ HRESULT get_CurrentOrientation(OrientationType *retVal);

Parameters


retVal The address of a variable that receives a value from theOrientationType enumeration

indicating the orientation of the element.

Return Value

Type Description


Remarks

This property is supported by controls such as scroll bars and sliders that can have either a vertical or ahorizontal orientation.

CurrentFrameworkId

The get_CurrentFrameworkIdmethod retrieves the UI framework identifier.

Language Syntax

C++ HRESULT get_CurrentFrameworkId(BSTR *retVal);


62/254


63/254





CurrentItemStatus

The get_CurrentItemStatusmethod retrieves the ItemStatusproperty of the element.

Language Syntax

C++ HRESULT get_CurrentItemStatus(BSTR *retVal);

Parameters



Return Value

Type Description


Remarks

This property enables a client to ascertain whether an element is conveying status about an item. For

example, an item associated with a contact in a messaging application might be "Busy" or "Connected".

CurrentBoundingRectangle

The get_CurrentBoundingRectanglemethod retrieves the bounding rectangle of the UI element.

Language Syntax

C++ HRESULT get_CurrentBoundingRectangle(RECT *retVal);

Parameters




64/254


65/254





Parameters



Return Value

Type Description


CurrentAriaProperties

The get_CurrentAriaPropertiesmethod retrieves the Accessible Rich Internet Applications (ARIA)

properties of the element.

Language Syntax

C++ HRESULT get_CurrentAriaProperties(BSTR *retVal);

Parameters



Return Value

Type Description



66/254





CurrentIsDataValidForForm

The get_CurrentIsDataValidForFormmethod retrieves a value that specifies whether the element

contains valid data for the form.

Language Syntax

C++ HRESULT get_CurrentIsDataValidForForm(BOOL *retVal);

Parameters


retVal The address of a variable that receives the value of the property: TRUE if the data is

valid, otherwise FALSE.

Return Value

Type Description


CurrentControllerFor

The get_CurrentControllerFormethod retrieves an array of UI Automation elements for which this

element serves as the controller.

Language Syntax

C++ HRESULT get_CurrentControllerFor(IUIAutomationElementArray *retVal);

Parameters


retVal The address of a variable that receives an array of elements for which this element is

the controller.


67/254


68/254





Parameters


retVal The address of a variable that receives anIUIAutomationElementArrayrepresenting

an array of elements.

Return Value

Type Description


CurrentProviderDescription

The get_CurrentProviderDescriptionmethod retrieves the ProviderDescriptionproperty of the

element.

Language Syntax

C++ HRESULT get_CurrentProviderDescription(BSTR *retVal);

Parameters


retVal The address of a variable that receives the description.

Return Value

Type Description



69/254


70/254


71/254


72/254


73/254


74/254





Parameters


retVal The address of a variable that receives the value of the cached property: TRUE if the

element is enabled, otherwise FALSE.

Return Value

Type Description


CachedAutomationId

The get_CachedAutomationIdmethod retrieves the element's UI Automation identifier from the cache.

Language Syntax

C++ HRESULT get_CachedAutomationId(BSTR *retVal);

Parameters


retVal The address of a variable that receives the value of the cached property.

Return Value

Type Description


Remarks

The identifier is unique among sibling elements in a container, and is the same in all instances of the

application.


75/254


76/254


77/254


78/254





Return Value

Type Description


Remarks

A content element contains data that is presented to the user. Examples of content elements are the

items in a list box or a button in a dialog box. Non-content elements, also called peripheral elements,

are typically used to manipulate the content in a composite control; for example, the button on a drop-

down control.

CachedIsPassword

The get_CachedIsPasswordmethod retrieves the value of the cached property that specifies whether

the element contains a disguised password.

Language Syntax

C++ HRESULT get_CachedIsPassword(BOOL *retVal);

Parameters


retVal The address of a variable that receives the value of the cached property: TRUE if the

element contains a password, otherwise FALSE.

Return Value

Type Description


Remarks

This property enables applications such as screen readers to determine whether the text content of a

control should be read aloud.


79/254





CachedNativeWindowHandle

The get_CachedNativeWindowHandlemethod retrieves the window handle (HWND) of the element

from the cache.

Language Syntax

C++ HRESULT get_CachedNativeWindowHandle(HWND *retVal);

Parameters


retVal The address of a variable that receives the value of the cached property. If the

element does not have a window, the value is 0.

Return Value

Type Description


CachedItemType

The get_CachedItemTypemethod retrieves the item type from the cache.

Language Syntax

C++ HRESULT get_CachedItemType(BSTR *retVal);

Parameters




80/254


81/254


82/254





CachedIsRequiredForForm

The get_CachedIsRequiredForFormmethod retrieves the value of the cached property that specifies

whether the element is required to be filled out on a form.

Language Syntax

C++ HRESULT get_CachedIsRequiredForForm(BOOL *retVal);

Parameters



is required, otherwise FALSE.

Return Value

Type Description


CachedItemStatus

The get_CachedItemStatusmethod retrieves the item status property from the cache.

Language Syntax

C++ HRESULT get_CachedItemStatus(BSTR *retVal);

Parameters




83/254


84/254


85/254


86/254


87/254





Parameters


retVal The address of a variable that receives an array of elements.

Return Value

Type Description


CachedFlowsTo

The get_CurrentFlowsTomethod retrieves a cached FlowsToproperty of the element.

Language Syntax

C++ HRESULT get_CachedFlowsTo(IUIAutomationElementArray *retVal);

Parameters


retVal The address of a variable that receives an array of elements.

Return Value

Type Description


CachedProviderDescription

The get_CurrentProviderDescriptionmethod retrieves a cached ProviderDescriptionproperty of

the element.

Language Syntax

C++ HRESULT get_CachedProviderDescription(BSTR *retVal);


88/254





Parameters


retVal The address of a variable that receives the description.

Return Value

Type Description


Methods

SetFocusThe SetFocusmethod sets the keyboard focus on this UI Automation element.

Language Syntax

C++ HRESULT SetFocus();

Return Value


GetRuntimeId

The GetRuntimeIdmethod retrieves the unique identifier assigned to the user interface (UI) element.

Language Syntax

C++ HRESULT GetRuntimeId(SAFEARRAY **runtimeId);


89/254


90/254





Parameters


scope[in] A bitwise combination of values that specifies the scope of the search.

condition[in] The criteria to match.

found[out,

retval]

The address of a variable that receives the element. NULL is returned if no matching

element is found.

Return Value

Type Description


Remarks

The scope of the search is relative to the element on which the method is called. Elements are returned

in the order in which they were encountered in the tree.

When searching for top-level windows on the desktop, be sure to specify TreeScope_Children in the

scopeparameter, not TreeScope_Descendants. A search through the entire subtree of the desktop could

iterate through thousands of items and lead to a stack overflow.

If your client application might try to find elements in its own user interface, you must make all UI

Automation calls on a separate thread.

FindAll

The FindAllmethod returns all UI Automation elements that satisfy the specified condition.

Language Syntax

C++HRESULT FindAll(TreeScope scope, IUIAutomationCondition *condition,

IUIAutomationElementArray **found);


91/254


92/254





Parameters


scope[in] A bitwise combination of values that specifies the scope of the search.

condition[in] The criteria to match.

cacheRequest

[in]

The cache request that specifies the control patterns and properties to cache.

found[out,

retval]

The address of a variable that receives the element. NULL is returned if no matching

element is found.

Return Value

Type Description


Remarks

The scope of the search is relative to the element on which the method is called. Elements are returned

in the order in which they were encountered in the tree.

When searching for top-level windows on the desktop, be sure to specify TreeScope_Children in the

scopeparameter, not TreeScope_Descendants. A search through the entire subtree of the desktop could

iterate through thousands of items and lead to a stack overflow.




93/254


94/254







BuildUpdatedCache

The BuildUpdatedCachemethod retrieves a new UI Automation element that has an updated cache.

Language Syntax

C++ HRESULT BuildUpdatedCache(IUIAutomationCacheRequest *cacheRequest,

IUIAutomationElement **updatedElement);

Parameters


cacheRequest[in] The cache request.

updatedElement

[out, retval]

The address of a variable that receives the new UI Automation element.

Return Value

Type Description


Remarks

The original UI Automation element is unchanged. The new UI Automation element refers to the same

UI element and has the same runtime identifier.


95/254





GetCurrentPropertyValue

The GetCurrentPropertyValuemethod retrieves a current property value for this UI Automation

element.

Language Syntax

C++ HRESULT GetCurrentPropertyValue(PROPERTYID propertyId, VARIANT

*retVal);

Parameters



retVal[out,

retval]

The address of a variable that receives the value of the property.

Return Value

Type Description


GetCurrentPropertyValueEx

The GetCurrentPropertyValueExmethod retrieves a current property value for this UI Automation

element, optionally ignoring any default value.

Language Syntax

C++ HRESULT GetCurrentPropertyValueEx(PROPERTYID propertyId, BOOL

ignoreDefaultValue, VARIANT *retVal);


96/254


97/254


98/254


99/254


100/254


101/254


102/254


103/254


104/254


105/254


106/254


107/254


108/254


109/254


110/254


111/254





Parameters


element[in] A UI Automation element that specifies the element from which to start the

normalization.

normalized

[out, retval]

The address of the ancestor element nearest to the specified element in the tree view

used by this instance of TreeWalker.

Return Value

Type Description

HRESULTReturns S_OKif successful or an error value otherwise.

GetParentBuildCache

Language Syntax

C++ HRESULT GetParentBuildCache(IUIAutomationElement *element,

IUIAutomationCacheRequest *cacheRequest, IUIAutomationElement

**parent);

Parameters


element[in] The e

5_UI Automation (Part 1 of 5) Client Interfaces

Documents

Transcript of 5_UI Automation (Part 1 of 5) Client Interfaces