IItemContainerProvider::FindItemByProperty method

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

pStartAfter [in]

Type: IRawElementProviderSimple*

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

pFound [out]

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

Reference

IItemContainerProvider

Conceptual

Property Identifiers