IItemContainerProvider::FindItemByProperty method

12/05/2018
2 minutes to read

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

Syntax

HRESULT FindItemByProperty(
  IRawElementProviderSimple *pStartAfter,
  PROPERTYID                propertyId,
  VARIANT                   value,
  IRawElementProviderSimple **pFound
);

Parameters

pStartAfter

Type: IRawElementProviderSimple*

The UI Automation provider of the element after which the search begins, or NULL to search all elements.

propertyId

Type: PROPERTYID

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

value

Type: VARIANT

The value of the property.

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


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 \| UWP apps]
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 \| UWP apps]
Target Platform	Windows
Header	uiautomationcore.h (include UIAutomation.h)
DLL	Uiautomationcore.dll