IUIAutomationItemContainerPattern::FindItemByProperty Method

  • Article

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

Syntax

HRESULT FindItemByProperty(      
    IUIAutomationElement *pstartAfter,
    PROPERTYID propertyId,
    VARIANT value,
    IUIAutomationElement **pfound
);

Parameters

  • pstartAfter
    [in] The address of the IUIAutomationElement interface for 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] The address of a variable that receives a pointer to the IUIAutomationElement interface of the matching element.

Return Value

Returns S_OK if successful, or an error value otherwise.

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.

See Also

IUIAutomationItemContainerPattern, IUIAutomationVirtualizedItemPattern::Realize