Padrão de controle ItemContainer

Descreve diretrizes e convenções para implementar IItemContainerProvider, incluindo informações sobre métodos. O padrão de controle ItemContainer é usado para dar suporte à virtualização de item.

Controles que contêm um grande número de itens filho podem usar a virtualização para gerenciar os itens com eficiência. Com a virtualização, o controle mantém informações completas na memória apenas para um subconjunto de itens a qualquer momento. Normalmente, o subconjunto inclui apenas os itens que estão visíveis no momento para o usuário. Informações completas sobre os itens virtualizados restantes são mantidas no armazenamento e são carregadas na memória ou realizadas, conforme o controle precisa dele, por exemplo, à medida que novos itens se tornam visíveis para o usuário.

Por exemplo, o diagrama a seguir mostra uma caixa de listagem que contém milhares de itens virtualizados. Como o controle mantém informações completas somente para os itens filho que estão visíveis no momento, o provedor pode expor elementos do Microsoft Automação da Interface do Usuário somente para itens 100 a 127.

Os controles que usam virtualização representam um desafio porque apenas itens realizados (des virtualizados) estão totalmente disponíveis como elementos Automação da Interface do Usuário na árvore Automação da Interface do Usuário. Itens virtualizados não existem na árvore, portanto, as informações sobre eles não estão disponíveis.

Para fornecer informações sobre itens virtualizados, os provedores implementam o padrão de controle ItemContainer , que expõe a interface IItemContainerProvider . O método FindItemByProperty localiza itens filho com base no valor de uma propriedade específica, como Name, AutomationId ou IsSelected. Se um item for virtualizado, FindItemByProperty recuperará um elemento de espaço reservado Automação da Interface do Usuário para o item. Um elemento de espaço reservado é uma implementação da interface IRawElementProviderSimple que dá suporte apenas ao padrão de controle VirtualizedItem .

O método IVirtualizedItemProvider::Realize permite que um cliente solicite que um item virtualizado seja realizado, expondo assim um elemento de Automação da Interface do Usuário completo para o item para que todas as propriedades e padrões necessários estejam disponíveis.

Embora a principal finalidade do padrão de controle ItemContainer seja dar suporte a cenários de contêiner virtualizado, ele pode ser implementado por qualquer contêiner que recupere itens filho por nome, independentemente de o contêiner usar virtualização.

Este tópico inclui as seções a seguir.

• Diretrizes e convenções de implementação
• Membros necessários para IItemContainerProvider
• Tópicos relacionados

Diretrizes e convenções de implementação

Ao implementar o padrão de controle ItemContainer , observe as seguintes diretrizes e convenções:

• Qualquer controle que possa conter itens virtualizados deve dar suporte ao padrão de controle ItemContainer . Qualquer contêiner que dê suporte à recuperação de itens com base em um valor de propriedade pode dar suporte a esse padrão, independentemente de o contêiner usar virtualização.
• Quando um contêiner é virtualizado, outros padrões de controle, como Seleção, Tabela e Grade , podem ser afetados. Por exemplo, o método ISelectionProvider::GetSelection pode dar suporte apenas a elementos que estão no visor ou apenas elementos selecionados que atualmente não estão virtualizados.
• O padrão de controle Scroll não deve ser afetado pela virtualização.
• Nenhuma contagem de itens ou informações de índice está disponível para itens virtualizados. Um controle virtualizado pode usar a propriedade DescribedBy ou ItemStatus para fornecer essas informações, se necessário.
• Os desenvolvedores de controle devem documentar e publicar detalhes de todas as propriedades Automação da Interface do Usuário e padrões de controle afetados pelo uso da virtualização. Embora os padrões de controle ItemContainer e VirtualizedItem ofereçam suporte básico, eles podem não dar suporte a alguns comportamentos de virtualização.

As diretrizes e requisitos a seguir se aplicam ao método IItemContainerProvider::FindItemByProperty .

• Embora não seja necessário, a Microsoft recomenda que FindItemByProperty dê suporte às propriedades Name, AutomationId e IsSelected .
• FindItemByProperty poderá ser lento se precisar percorrer vários objetos para encontrar um correspondente.
• FindItemByProperty pode ser chamado repetidamente para localizar itens em sequência. Os itens podem estar em qualquer ordem, desde que cada item seja retornado apenas uma vez.
• FindItemByProperty pode ser implementado para localizar apenas os elementos que aparecem no controle ou na exibição de conteúdo da árvore Automação da Interface do Usuário. Elementos que aparecem apenas na exibição bruta podem ser ignorados para evitar a recuperação de vários elementos que representam apenas uma parte de um "item" para o usuário.
• Quando os critérios de pesquisa correspondem a um item virtualizado, o provedor pode retornar um elemento de espaço reservado que dá suporte ao padrão de controle VirtualizedItem . As seguintes diretrizes se aplicam a elementos de espaço reservado:
  • A recuperação de um elemento de espaço reservado para um item virtualizado não deve causar alterações na interface do usuário.
  • O elemento de espaço reservado deve ser um par de outros elementos filho (um evento alterado por estrutura é necessário).
  • Quando possível, o provedor pode criar um elemento de automação completa em vez de um espaço reservado.
• Quando os critérios de pesquisa correspondem a um elemento não virtualizado, o provedor deve retornar o elemento real, não um espaço reservado.
• Quando nenhum item é encontrado, IItemContainerProvider::FindItemByProperty deve definir o parâmetro pFound como NULL e retornar S_OK.
• Quando o parâmetro propertyId for 0, o provedor deverá retornar o próximo item após pStartAfter.
• Se o parâmetro pStartAfter for NULL e propertyId for 0, o provedor deverá retornar o primeiro item no contêiner.
• Quando o parâmetro propertyId é 0, o parâmetro value é ignorado.

As diretrizes e requisitos a seguir se aplicam a elementos de espaço reservado para itens virtualizados na árvore Automação da Interface do Usuário.

• Embora os provedores sejam incentivados a dar suporte a mais propriedades e padrões de controle para um elemento de espaço reservado, somente o padrão de controle VirtualizedItem é necessário.
• O provedor pode invalidar um elemento de espaço reservado anterior quando IItemContainerProvider::FindItemByProperty for chamado novamente. (Se um cliente precisar perceber o elemento de espaço reservado, ele deverá fazê-lo imediatamente; caso contrário, o elemento poderá ser invalidado se FindItemByProperty for chamado novamente ou se o visor for alterado por qualquer motivo.)
• Ações de interface do usuário, como rolagem ou redimensionamento, podem fazer com que o visor do contêiner seja alterado e um novo conjunto de itens filho fique visível. Nesse caso, os elementos de espaço reservado recuperados anteriormente podem não estar disponíveis na árvore Automação da Interface do Usuário.
• O provedor não deve virtualizar elementos de interface do usuário que estão disponíveis na tela no visor do objeto contêiner.

Membros necessários para IItemContainerProvider

O método a seguir é necessário para implementar a interface IItemContainerProvider .

O padrão de controle ItemContainer não tem nenhuma propriedade ou eventos associados.

Tópicos relacionados

Tipos de controle e seus padrões de controle com suporte

Visão Geral de Padrões de Controle de Automação de Interface de Usuário

Visão geral da árvore de automação de interface do usuário

Padrão de controle VirtualizedItem