IUIAutomationItemContainerPattern::FindItemByProperty method (uiautomationclient.h)

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

[in] pStartAfter

Type: IUIAutomationElement*

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

[in] propertyId

Type: PROPERTYID

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

[in] value

Type: VARIANT

The property value.

[out, retval] pFound

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

See also

IUIAutomationItemContainerPattern

Realize

Reference