Edit

Working with Virtualized Items

  • Article

This topic describes how to use functionality provided by the ItemContainer and VirtualizedItem control patterns to find and retrieve information about virtualized items.

Overview of Virtualization

Controls that contain a large number of child items can use virtualization to efficiently manage the items. With virtualization, the control maintains full information in memory for only a subset of items at any given time. Typically, the subset includes only those items that are currently visible to the user. Full information about the remaining virtualized items is kept in storage and is loaded into memory, or realized, as the control needs it, for example, as new items become visible to the user.

Controls that use virtualization represent a challenge because only realized items are fully available as Microsoft UI Automation elements in the UI Automation tree. Virtualized items do not exist in the tree, so information about them is not available to clients. To retrieve information about virtualized items, clients need a way to force UI Automation to pass the request to realize the items to the control. After the items have been realized, UI Automation can create UI Automation elements for them. UI Automation includes two control patterns to enable clients to work with virtualized items: ItemContainer and VirtualizedItem.

How a Control Supports Virtualization

Any control that can contain virtualized items must support the ItemContainer control pattern. Further, any item that can be virtualized must support the VirtualizedItem control pattern. The functionality that is exposed by the ItemContainer and VirtualizedItem control patterns is accessible to clients through the IUIAutomationItemContainerPattern and IUIAutomationVirtualizedItemPattern interfaces.

How Clients Find and Realize Virtualized Items

Clients can use the IUIAutomationItemContainerPattern::FindItemByProperty method to search for child items in the container based on the value of a particular property. The method can also retrieve the first item in the container or the item that follows the specified item. If a matching child item is found, the FindItemByProperty retrieves an IUIAutomationElement interface for the item. However, if the child item is virtualized, the IUIAutomationElement interface is a placeholder. The UIA_E_ELEMENTNOTAVAILABLE error occurs when the client attempts to use the IUIAutomationElement interface to retrieve property values or call methods that are not yet available. Which properties or methods are available through a placeholder depends on the control implementation. The only requirement for a placeholder is to support the IUIAutomationVirtualizedItemPattern interface.

The UIA_E_ELEMENTNOTAVAILABLE error is an indication to the client that an item may be virtualized. The client should respond by retrieving the IUIAutomationVirtualizedItemPattern interface for the item, and then realizing the item by calling the IUIAutomationVirtualizedItemPattern::Realize method. If this succeeds, the IUIAutomationElement interface is fully functional with all appropriate properties available.

Depending on the control implementation, calling IUIAutomationVirtualizedItemPattern::Realize may cause the control to scroll the item into view. However, a client should not rely on the item scrolling into view or made visible. To ensure that the item is visible, the client can use the IUIAutomationScrollItemPattern::ScrollIntoView method.

Example

For example code that shows how to use the UI Automation support for virtualization, see How to Retrieve a Virtualized Item.

UI Automation Control Patterns Overview