Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

IUIAutomationItemContainerPattern::FindItemByProperty method

Retrieves an element within a containing element, based on a specified property value.

Syntax


HRESULT FindItemByProperty(
  [in]           IUIAutomationElement *pstartAfter,
  [in]           PROPERTYID propertyId,
  [in]           VARIANT value,
  [out, retval]  IUIAutomationElement **pfound
);

Parameters

pstartAfter [in]

Type: IUIAutomationElement*

A pointer to the element after which the search begins, or NULL to search all elements.

propertyId [in]

Type: PROPERTYID

The property identifier. For a list of property IDs, see Property Identifiers.

value [in]

Type: VARIANT

The property value.

pfound [out, retval]

Type: IUIAutomationElement**

Receives a pointer to the matching element.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The provider may return an actual IUIAutomationElement interface or a placeholder if the matching element is virtualized.

This method returns E_INVALIDARG if the property requested is not one that the container supports searching over. It is expected that most containers will support Name property, and if appropriate for the container, AutomationId and IsSelected.

This method can be slow, because it may need to traverse multiple objects to find a matching one. When used in a loop to return multiple items, no specific order is defined so long as each item is returned only once (that is, the loop should terminate). This method is also item-centric, not UI-centric, so items with multiple UI representations need to be hit only once.

When the propertyId parameter is specified as 0 (zero), the provider is expected to return the next item after pStartAfter. If pStartAfter is specified as NULL with a propertyId of 0, the provider should return the first item in the container. When propertyId is specified as 0, the value parameter should be VT_EMPTY.

Requirements

Minimum supported client

Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista, Windows XP with SP3 and Platform Update for Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008, Windows Server 2003 with SP2 and Platform Update for Windows Server 2008 [desktop apps only]

Header

UIAutomationClient.h (include UIAutomation.h)

IDL

UIAutomationClient.idl

See also

Reference
IUIAutomationItemContainerPattern
Realize

 

 

Community Additions

Show:
© 2014 Microsoft