Windows apps
Collapse the table of content
Expand the table of content
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.


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


pstartAfter [in]

Type: IUIAutomationElement*

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

propertyId [in]


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

value [in]


The property value.

pfound [out, retval]

Type: IUIAutomationElement**

Receives a pointer to the matching element.

Return value


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


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.


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]


UIAutomationClient.h (include UIAutomation.h)



See also




© 2018 Microsoft