IItemContainerProvider::FindItemByProperty method (uiautomationcore.h)

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

Syntax

HRESULT FindItemByProperty(
  [in]  IRawElementProviderSimple *pStartAfter,
  [in]  PROPERTYID                propertyId,
  [in]  VARIANT                   value,
  [out] IRawElementProviderSimple **pFound
);

Parameters

[in] pStartAfter

Type: IRawElementProviderSimple*

The UI Automation provider of 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 value of the property.

[out] pFound

Type: IRawElementProviderSimple**

Receives a pointer to the UI Automation provider of the element.

Return value

Type: HRESULT

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

Remarks

For virtual lists, the element returned may be a placeholder. IVirtualizedItemProvider::Realize can then be used to make the item fully available.

The method returns E_INVALIDARG if searching by the specified property is not supported. Most containers should support UIA_NamePropertyId and, if appropriate, UIA_AutomationIdPropertyId and UIA_SelectionItemIsSelectedPropertyId.

If propertyId is 0, all items are a match. This value can be used with pStartAfter equalling NULL to get the first item, and then to get successive items. In this case, value should be VT_EMPTY.

Requirements

See also

Conceptual

IItemContainerProvider

Property Identifiers

Reference