Partilhar via

Padrão de controle ItemContainer

  • Artigo

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

Os 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 para apenas um subconjunto de itens a qualquer momento. Normalmente, o subconjunto inclui apenas os itens que estão atualmente visíveis para o usuário. Informações completas sobre os itens virtualizados restantes são mantidas em armazenamento e carregadas na memória, ou realizadas, conforme o controle precisa, por exemplo, quando 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 apenas para os itens filho que estão visíveis no momento, o provedor pode expor elementos de Automação da Interface do Usuário da Microsoft somente para os itens 100—127.

diagrama mostrando itens em uma caixa de listagem que são virtualizados e não virtualizados

Os controles que usam virtualização representam um desafio porque apenas os itens realizados (desvirtualizados) estão totalmente disponíveis como elementos de Automação da Interface do Usuário na árvore de Automação da Interface do Usuário. Os 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 interfaceIItemContainerProvider. O métodoFindItemByProperty localiza itens filho com base no valor de uma propriedade específica, como Name, AutomationIdou IsSelected. Se um item for virtualizado, FindItemByProperty recuperará um elemento de espaço reservado para Automação da Interface do Usuário para o item. Um elemento de espaço reservado é uma implementação do interface IRawElementProviderSimple que suporta apenas o 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 completo de automação da interface do usuário para o item para que todas as propriedades e padrões necessários estejam disponíveis.

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

Este tópico contém as seguintes seções.

Orientações e convenções de aplicação

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

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

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

  • Embora não seja necessário, a Microsoft recomenda vivamente que FindItemByProperty suportem as propriedades Name, AutomationIde IsSelected.
  • FindItemByProperty pode ser lento se precisar atravessar 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 devolvido apenas uma vez.
  • FindItemByProperty pode ser implementada para localizar apenas os elementos que aparecem na exibição de controle ou conteúdo da árvore de automação da interface do usuário. Os elementos que aparecem apenas no modo de exibição bruto 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 ofereça suporte ao padrão de controle VirtualizedItem. As diretrizes a seguir 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 de estrutura é necessário).
    • Quando possível, o provedor pode criar um elemento de automação completa em vez de um espaço reservado.
  • Quando o critério de pesquisa corresponde a um elemento não virtualizado, o provedor deve retornar o elemento real, não um espaço reservado.
  • Quando nenhum item for 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 de Automação da Interface do Usuário.

  • Embora os provedores sejam incentivados a oferecer 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 é chamado novamente. (Se um cliente precisar realizar 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 a janela de visualização for alterada por qualquer motivo.)
  • Ações da interface do usuário, como rolagem ou redimensionamento, podem fazer com que a janela de visualização do contêiner seja alterada 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 de Automação da Interface do Usuário.
  • O provedor não deve virtualizar elementos da interface do usuário que estão disponíveis na tela no visor do objeto de contêiner.

Membros necessários para IItemContainerProvider

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

Membros obrigatórios Tipo de membro Observações
FindItemByProperty Método Nenhum

 

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

tipos de controle e seus padrões de controle suportados

Visão geral dos padrões de controle de automação da interface do do usuário

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

padrão de controle VirtualizedItem