Patrón de control ItemContainer

Describe instrucciones y convenciones para implementar IItemContainerProvider, incluida la información sobre los métodos. El patrón de control ItemContainer se usa para admitir la virtualización de elementos.

Los controles que contienen un gran número de elementos secundarios pueden usar la virtualización para administrar de forma eficaz los elementos. Con la virtualización, el control mantiene información completa en la memoria solo para un subconjunto de elementos en un momento dado. Normalmente, el subconjunto incluye solo los elementos que están visibles actualmente para el usuario. La información completa sobre los elementos virtualizados restantes se mantiene en el almacenamiento y se carga en la memoria, o se realiza, ya que el control lo necesita, por ejemplo, a medida que los nuevos elementos sean visibles para el usuario.

Por ejemplo, en el diagrama siguiente se muestra un cuadro de lista que contiene miles de elementos virtualizados. Dado que el control mantiene información completa solo para los elementos secundarios que están visibles actualmente, el proveedor puede exponer los elementos de Microsoft Automatización de la interfaz de usuario solo para los elementos 100 a 127.

Los controles que usan la virtualización representan un desafío porque solo los elementos realizados (des virtualizados) están totalmente disponibles como elementos Automatización de la interfaz de usuario en el árbol de Automatización de la interfaz de usuario. Los elementos virtualizados no existen en el árbol, por lo que la información sobre ellos no está disponible.

Para proporcionar información sobre los elementos virtualizados, los proveedores implementan el patrón de control ItemContainer , que expone la interfaz IItemContainerProvider . El método FindItemByProperty busca elementos secundarios basados en el valor de una propiedad determinada, como Name, AutomationId o IsSelected. Si un elemento está virtualizado, FindItemByProperty recupera un elemento de marcador de posición Automatización de la interfaz de usuario para el elemento. Un elemento de marcador de posición es una implementación de la interfaz IRawElementProviderSimple que solo admite el patrón de control VirtualizedItem .

El método IVirtualizedItemProvider::Realize permite a un cliente solicitar que se realice un elemento virtualizado, exponiendo así un elemento de Automatización de la interfaz de usuario completo para el elemento para que estén disponibles todas las propiedades y patrones necesarios.

Aunque el propósito principal del patrón de control ItemContainer es admitir escenarios de contenedor virtualizados, puede implementarlo cualquier contenedor que recupere elementos secundarios por nombre, independientemente de si el contenedor usa la virtualización.

En este tema se incluyen las siguientes secciones.

• Directrices y convenciones de implementación
• Miembros necesarios para IItemContainerProvider
• Temas relacionados

Directrices y convenciones de implementación

Al implementar el patrón de control ItemContainer , tenga en cuenta las siguientes directrices y convenciones:

• Cualquier control que pueda contener elementos virtualizados debe admitir el patrón de control ItemContainer . Cualquier contenedor que admita la recuperación de elementos basados en un valor de propiedad puede admitir este patrón, independientemente de si el contenedor usa la virtualización.
• Cuando se virtualiza un contenedor, se pueden ver afectados otros patrones de controles, como Selección, Tabla y Cuadrícula . Por ejemplo, el método ISelectionProvider::GetSelection solo puede admitir elementos que están en la ventanilla o solo los elementos seleccionados que no están virtualizados actualmente.
• El patrón de control Scroll no debe verse afectado por la virtualización.
• No hay información de índice o recuento de elementos disponible para elementos virtualizados. Un control virtualizado puede usar la propiedad DescribedBy o ItemStatus para proporcionar esta información, si es necesario.
• Los desarrolladores de controles deben documentar y publicar detalles de todas las propiedades Automatización de la interfaz de usuario y los patrones de control afectados por el uso de la virtualización. Aunque los patrones de control ItemContainer y VirtualizedItem ofrecen compatibilidad básica, es posible que no admitan algunos comportamientos de virtualización.

Las siguientes directrices y requisitos se aplican al método IItemContainerProvider::FindItemByProperty .

• Aunque no es necesario, Microsoft recomienda encarecidamente que FindItemByProperty admita las propiedades Name, AutomationId e IsSelected .
• FindItemByProperty puede ser lento si necesita atravesar varios objetos para encontrar uno coincidente.
• Se puede llamar a FindItemByProperty repetidamente para buscar elementos en secuencia. Los elementos pueden estar en cualquier orden siempre que cada elemento se devuelva solo una vez.
• FindItemByProperty se puede implementar para buscar solo los elementos que aparecen en la vista de contenido o control del árbol de Automatización de la interfaz de usuario. Los elementos que solo aparecen en la vista sin procesar se pueden omitir para evitar recuperar varios elementos que representan solo una parte de un "elemento" al usuario.
• Cuando los criterios de búsqueda coinciden con un elemento virtualizado, el proveedor puede devolver un elemento de marcador de posición que admita el patrón de control VirtualizedItem . Las siguientes directrices se aplican a los elementos de marcador de posición:
  • La recuperación de un elemento de marcador de posición para un elemento virtualizado no debe provocar cambios en la interfaz de usuario.
  • El elemento de marcador de posición debe ser un elemento del mismo nivel de otros elementos secundarios (se requiere un evento modificado por la estructura).
  • Cuando sea posible, el proveedor puede crear un elemento de automatización completo en lugar de un marcador de posición.
• Cuando los criterios de búsqueda coinciden con un elemento no virtualizado, el proveedor debe devolver el elemento real, no un marcador de posición.
• Cuando no se encuentra ningún elemento, IItemContainerProvider::FindItemByProperty debe establecer el parámetro pFound en NULL y devolver S_OK.
• Cuando el parámetro propertyId es 0, el proveedor debe devolver el siguiente elemento después de pStartAfter.
• Si el parámetro pStartAfter es NULL y propertyId es 0, el proveedor debe devolver el primer elemento del contenedor.
• Cuando el parámetro propertyId es 0, se omite el parámetro value.

Las siguientes directrices y requisitos se aplican a los elementos de marcador de posición para los elementos virtualizados en el árbol de Automatización de la interfaz de usuario.

• Aunque se recomienda a los proveedores que admitan más propiedades y patrones de control para un elemento de marcador de posición, solo se requiere el patrón de control VirtualizedItem .
• El proveedor puede invalidar un elemento de marcador de posición anterior cuando se llama de nuevo a IItemContainerProvider::FindItemByProperty . (Si un cliente necesita realizar el elemento de marcador de posición, debe hacerlo inmediatamente; de lo contrario, el elemento se puede invalidar si se llama a FindItemByProperty de nuevo o si la ventanilla cambia por cualquier motivo).
• Las acciones de la interfaz de usuario, como el desplazamiento o el cambio de tamaño, pueden hacer que la ventanilla del contenedor cambie y un nuevo conjunto de elementos secundarios se vuelva visible. En este caso, es posible que los elementos de marcador de posición recuperados previamente no estén disponibles en el árbol de Automatización de la interfaz de usuario.
• El proveedor no debe virtualizar los elementos de la interfaz de usuario que están disponibles en pantalla en la ventanilla del objeto contenedor.

Miembros necesarios para IItemContainerProvider

El método siguiente es necesario para implementar la interfaz IItemContainerProvider .

Miembros requeridos	Tipo de miembro	Notas
FindItemByProperty	Método	None

 

El patrón de control ItemContainer no tiene propiedades ni eventos asociados.

Temas relacionados

Tipos de control y sus patrones de control admitidos

Información general acerca de los patrones de control de UI Automation

Información general sobre el árbol de la UI Automation

Patrón de control VirtualizedItem