Compartilhar via

Sobre controles de exibição de lista

  • Artigo

Consulte o exemplo de controle Listview virtual.

Um controle de exibição de lista é uma janela que exibe uma coleção de itens. Os controles de exibição de lista fornecem várias maneiras de organizar e exibir itens e são muito mais flexíveis do que caixas de listagem simples. Por exemplo, informações adicionais sobre cada item podem ser exibidas em colunas à direita do ícone e do rótulo.

Estilos e modos de exibição de lista

Os controles de exibição de lista podem exibir itens em cinco modos de exibição diferentes. O estilo de janela do controle especifica o modo de exibição padrão. Estilos de janela adicionais especificam o alinhamento de itens e recursos específicos do controle. A tabela a seguir descreve os modos de exibição.

Exibir Nome Descrição
Exibição do ícone Especificado pelo estilo de janela LVS_ICON ou passando LV_VIEW_ICON com a mensagem LVM_SETVIEW. Cada item é exibido como um ícone em tamanho normal com um rótulo abaixo dele. O usuário pode arrastar os itens para qualquer local na janela de exibição de lista.
Exibição do ícone pequeno Especificado pelo estilo de janela LVS_SMALLICON ou passando LV_VIEW_SMALLICON com LVM_SETVIEW. Cada item aparece como um pequeno ícone com o rótulo à direita dele. O usuário pode arrastar os itens para qualquer local.
Modo de exibição de lista Especificado pelo estilo de janela LVS_LIST ou passando LV_VIEW_LIST com LVM_SETVIEW. Cada item é exibido como um pequeno ícone com um rótulo à sua direita. Os itens são organizados em colunas e o usuário não pode arrastá-los para um local arbitrário.
Exibição de relatório (detalhes) Especificado pelo estilo de janela LVS_REPORT ou passando LV_VIEW_DETAILS com LVM_SETVIEW. Cada item aparece em sua própria linha, com informações organizadas em colunas. A coluna mais à esquerda é sempre justificada à esquerda e contém o pequeno ícone e rótulo. As colunas subsequentes contêm subitens conforme especificado pelo aplicativo. Cada coluna tem um cabeçalho, a menos que você também especifique o estilo de janela LVS_NOCOLUMNHEADER.
Exibição Lado a Lado Versão 6 e posterior. Especificado passando LV_VIEW_TILE com LVM_SETVIEW. Cada item aparece como um ícone de tamanho completo com um rótulo de uma ou mais linhas ao lado.

 

As capturas de tela a seguir usam modos de exibição para mostrar diferentes quantidades de informações sobre cada um dos sete animais de estimação. Os modos de exibição demonstram como as informações podem aparecer no Windows Vista. Os estilos visuais para o controle foram definidos para o tema "Explorer" usando SetWindowTheme.

A captura de tela a seguir mostra a exibição de detalhes.

screen shot that shows information in five columns and seven rows

A captura de tela a seguir mostra a exibição de ícone.

screen shot that shows only the name of each pet and an icon indicating the species

A captura de tela a seguir mostra o modo de exibição de lista.

screen shot that shows, for each pet, a large icon next the text of the pet's name, breed, and price

A captura de tela a seguir mostra o modo de exibição de bloco.

tile view.

Você pode alterar o tipo de exibição depois de criar um controle de exibição de lista. Para recuperar e alterar o estilo da janela, use as funções GetWindowLong e SetWindowLong. Para determinar os estilos de janela do modo de exibição atual, use o valor LVS_TYPEMASK.

Você pode controlar a maneira como os itens são organizados na exibição de ícone ou ícone pequeno especificando o estilo de LVS_ALIGNTOP (padrão) ou LVS_ALIGNLEFT janela.

Você pode alterar o alinhamento depois de criar um controle de exibição de lista. Para determinar o alinhamento atual, use o valor LVS_ALIGNMASK.

Estilos de janela adicionais fornecem outras opções, como se um usuário pode editar rótulos ou selecionar mais de um item por vez. Para obter uma lista completa, consulte List-View Window Styles.

Estilos de exibição de lista estendidos

Os estilos de controle de exibição de lista estendida fornecem opções como caixas de seleção, barras de rolagem planas, linhas de grade e rastreamento a quente. Para obter uma lista completa, consulte Estilos de exibição de lista estendidos. Você não acessa estilos de exibição de lista estendida da mesma maneira que os estilos de janela padrão. Você não usa as funções GetWindowLong e SetWindowLong para fazer alterações de estilo estendidas.

Há duas mensagens que definem e recuperam informações de estilo estendidas, LVM_SETEXTENDEDLISTVIEWSTYLE e LVM_GETEXTENDEDLISTVIEWSTYLE. Em vez de enviar as mensagens explicitamente, você pode usar as seguintes macros correspondentes: ListView_SetExtendedListViewStyle, ListView_SetExtendedListViewStyleEx e ListView_GetExtendedListViewStyle.

Estilo de exibição de lista virtual

Um modo de exibição de lista virtual é um controle de exibição de lista que tem o estilo LVS_OWNERDATA. Esse estilo permite que o controle manipule milhões de itens porque o proprietário recebe a carga de gerenciar dados de item. Isso permite que você use o controle de exibição de lista virtual com grandes bancos de dados de informações, onde métodos específicos de acesso a dados já estão em vigor.

Um controle de exibição de lista virtual mantém muito poucas informações de item em si. Com exceção das informações de seleção e foco do item, o proprietário do controle deve gerenciar todas as informações do item. Outros processos solicitam informações de item do proprietário usando códigos de notificação LVN_GETDISPINFO .

Como esse tipo de controle de lista destina-se a grandes conjuntos de dados, é recomendável armazenar em cache dados de item solicitados para melhorar o desempenho de recuperação. A exibição de lista fornece um mecanismo de dicas de cache para ajudar na otimização do cache. A dica é implementada na forma de um código de notificação LVN_ODCACHEHINT .

Criando um controle de exibição de lista virtual

Você cria controles de exibição de lista virtual usando a função CreateWindow ou CreateWindowEx, especificando o estilo de janela LVS_OWNERDATA como parte do parâmetro de função dwStyle. Não há suporte para alternar dinamicamente de e para o estilo LVS_OWNERDATA .

Você pode usar o estilo LVS_OWNERDATA em combinação com a maioria dos outros estilos de janela, exceto o estilo LVS_SORTASCENDING ou LVS_SORTDESCENDING. Todos os controles de exibição de lista virtual têm como padrão o estilo LVS_AUTOARRANGE.

Para permitir que os itens sejam exibidos na lista, você deve primeiro enviar a mensagem LVM_SETITEMCOUNT, explicitamente ou usando a macro ListView_SetItemCountEx.

Não há suporte para as seguintes mensagens no estilo LVS_OWNERDATA: LVM_ENABLEGROUPVIEW, LVM_GETITEMTEXT, LVM_SETTILEINFO e LVM_MAPIDTOINDEX.

Problemas de compatibilidade

Todos os quatro estilos de exibição de lista — ícone, ícone pequeno, lista e exibição de relatório — oferecem suporte ao estilo LVS_OWNERDATA. Os controles de exibição de lista que têm o estilo LVS_OWNERDATA não armazenam nenhuma informação específica do item. Portanto, os únicos sinalizadores de estado de item válidos que você pode aplicar a um item são LVIS_SELECTED e LVIS_FOCUSED. Nenhuma outra informação de estado é armazenada. Em particular, o controle list-view não mantém imagens de estado ou sobreposição para cada item. No entanto, você pode fazer com que o controle de exibição de lista consulte seu aplicativo para essas imagens enviando-lhe uma mensagem LVM_SETCALLBACKMASK.

A maioria das mensagens de controle de exibição de lista e as macros associadas são totalmente suportadas. No entanto, algumas mensagens têm limitações ou não são suportadas quando você usa o estilo LVS_OWNERDATA. A tabela a seguir resume as mensagens afetadas.

Mensagem Limitação
LVM_ARRANGE Não suporta o estilo LVA_SNAPTOGRID .
LVM_DELETEALLITEMS Define a contagem de itens como zero e limpa todas as variáveis de seleção internas, mas na verdade não exclui nenhum item. Ele faz um retorno de chamada de notificação.
LVM_DELETEITEM É suportado apenas para integridade de seleção e não exclui um item.
LVM_GETITEMSTATE Retorna apenas os estados de foco e seleção (ou seja, aqueles estados armazenados pelo controle list-view).
LVM_GETNEXTITEM Não oferece suporte aos critérios de pesquisa de exibição de lista LVNI_CUT, LVNI_HIDDEN ou LVNI_DROPHILITED. Todos os outros critérios são suportados.
LVM_GETWORKAREAS Não tem suporte.
LVM_INSERTITEM É suportado apenas para integridade de seleção.
LVM_SETITEM Não tem suporte. Para definir o estado do item, use a mensagem ListView_SetItemState.
LVM_SETITEMCOUNT Define o número de itens atualmente na lista. Se o controle list-view enviar uma notificação que solicita dados para qualquer item até o conjunto máximo, o proprietário deve estar preparado para fornecer esses dados. Os parâmetros de mensagem oferecem suporte a controles de exibição de lista virtual.
LVM_SETITEMPOSITION Não tem suporte.
LVM_SETITEMSTATE Permite que apenas os estados de seleção e foco sejam alterados para o item.
LVM_SETITEMTEXT Não tem suporte. É de responsabilidade do aplicativo a manutenção dos textos dos itens.
LVM_SETWORKAREAS Não tem suporte.
LVM_SORTITEMS Não tem suporte. É de responsabilidade do aplicativo apresentar os itens na ordem desejada.

 

Manipulando códigos de notificação de controle de exibição de lista virtual

Os controles de exibição de lista com o estilo LVS_OWNERDATA enviam os mesmos códigos de notificação que outros controles de exibição de lista e dois adicionais: LVN_ODCACHEHINT e LVN_ODFINDITEM. A seguir estão as notificações mais comuns que o controle de exibição de lista com o estilo LVS_OWNERDATA envia.

Notificação Descrição
LVN_GETDISPINFO Um controle de exibição de lista virtual mantém muito poucas informações de item por conta própria. Como resultado, ele geralmente envia o código de notificação LVN_GETDISPINFO para solicitar informações de item. Essa mensagem é tratada da mesma maneira que os itens de retorno de chamada em um controle de lista padrão. Como o número de itens suportados pelo controle pode ser muito grande, o armazenamento em cache dos dados do item melhora o desempenho. Ao manipular LVN_GETDISPINFO, o proprietário do controle primeiro tenta fornecer informações de item solicitadas do cache (para obter mais informações, consulte Gerenciamento de cache). Se o item solicitado não estiver armazenado em cache, o proprietário deve estar preparado para fornecer as informações por outros meios.
LVN_ODCACHEHINT Uma exibição de lista virtual envia o código de notificação LVN_ODCACHEHINT para ajudar na otimização do cache. O código de notificação fornece valores de índice inclusivos para um intervalo de itens que ele recomenda que sejam armazenados em cache. Ao receber o código de notificação, o proprietário deve estar preparado para carregar o cache com informações de item para o intervalo solicitado para que as informações estejam prontamente disponíveis quando uma mensagem LVN_GETDISPINFO for enviada.
LVN_ODFINDITEM O código de notificação LVN_ODFINDITEM é enviado por um controle de exibição de lista virtual quando o controle precisa que o proprietário localize um item de retorno de chamada específico. O código de notificação é enviado quando o controle de exibição de lista recebe acesso rápido por chave ou quando recebe uma mensagem de LVM_FINDITEM . As informações de pesquisa são enviadas na forma de uma estrutura LVFINDINFO, que é membro da estrutura NMLVFINDITEM. O proprietário deve estar preparado para procurar um item que corresponda às informações fornecidas pelo controle list-view. O proprietário retorna o índice do item se for bem-sucedido ou -1 se nenhum item correspondente for encontrado.

 

Gerenciamento de cache

Um controle de exibição de lista com o estilo LVS_OWNERDATA produz um grande número de códigos de notificação LVN_GETDISPINFO e, para ajudar na otimização do cache, uma mensagem LVN_ODCACHEHINT. LVN_ODCACHEHINT mensagens fornecem informações sobre os itens recomendados a serem incluídos no cache. Essas mensagens são enviadas como mensagens WM_NOTIFY, com o valor lParam atuando como o endereço de uma estrutura NMLVCACHEHINT.

A estrutura NMLVCACHEHINT inclui dois membros inteiros, iFrom e iTo, que representam os pontos de extremidade inclusivos de uma variedade de itens que provavelmente serão necessários. O proprietário deve estar preparado para carregar o cache com as informações do item para cada um dos itens dentro do intervalo recomendado.

O controle de lista geralmente precisa de informações de item para o primeiro item (deslocamento 0). O código de notificação LVN_ODCACHEHINT pode nem sempre incluir o item 0, mas sempre deve ser incluído no cache.

Os últimos itens da lista são acessados com frequência. Portanto, o proprietário pode querer manter um segundo cache que inclua os itens no final da lista. O intervalo solicitado de LVN_ODCACHEHINT pode ser verificado no cache final para disponibilizá-lo automaticamente em vez de recarregar o mesmo intervalo de término todas as vezes.

Áreas de trabalho com exibição de lista

Os controles de exibição de lista oferecem suporte a áreas de trabalho, que são áreas virtuais retangulares que o controle de exibição de lista usa para organizar seus itens. Uma área de trabalho não é uma janela e não pode ter uma borda visível. Por padrão, o controle list-view não tem áreas de trabalho. Ao criar uma área de trabalho, você pode criar uma borda vazia à esquerda, na parte superior ou à direita dos itens ou fazer com que uma barra de rolagem horizontal seja exibida quando normalmente não haveria uma.

Quando uma área de trabalho é criada, os itens que estão dentro da área de trabalho tornam-se membros da área de trabalho. Da mesma forma, se um item for movido para uma área de trabalho, o item se tornará um membro dessa área de trabalho. Se um item não estiver em nenhuma área de trabalho, ele se tornará automaticamente um membro da primeira área de trabalho (índice 0). Para colocar um novo item em uma área de trabalho específica, você deve primeiro criar o item e, em seguida, usar o LVM_SETITEMPOSITION ou a mensagem LVM_SETITEMPOSITION32 para movê-lo para a área de trabalho desejada.

A ilustração a seguir é um exemplo de um controle de exibição de lista que contém quatro áreas de trabalho, cada uma em um quadrante diferente da área do cliente.

screen shot of a list-view control with one working area in each quadrant of the client area

Várias áreas de trabalho podem ser usadas para criar áreas diferentes em uma exibição. Você pode criar áreas em um único modo de exibição que tenham significados diferentes. Por exemplo, uma exibição de um sistema de arquivos pode ter uma área para arquivos de leitura/gravação e outra área para arquivos somente leitura. O usuário pode categorizar itens colocando-os em diferentes áreas de trabalho. Se um arquivo for movido para a área somente leitura, ele se tornará automaticamente somente leitura.

Várias áreas de trabalho podem se cruzar, mas quaisquer itens que estejam dentro da interseção tornam-se membros da área com o índice mais baixo; Portanto, é melhor evitar essa situação. Ao classificar várias áreas de trabalho, os itens são classificados em comparação com os outros itens na mesma área de trabalho.

O número de áreas de trabalho pode ser recuperado com a mensagem LVM_GETNUMBEROFWORKAREAS. As áreas de trabalho são alteradas com a mensagem LVM_SETWORKAREAS e podem ser recuperadas com a mensagem LVM_GETWORKAREAS. Ambas as mensagens tomam o endereço de uma matriz de estruturas RECT como lParam e o número de estruturas RECT como wParam. Os membros esquerdo e superior dessas estruturas especificam as coordenadas do canto superior esquerdo (a origem) da área de trabalho, e os membros direito e inferior especificam o canto inferior direito da área de trabalho. Todas as coordenadas estão em coordenadas de cliente da exibição de lista. O número máximo de áreas de trabalho permitidas é definido pelo valor LV_MAX_WORKAREAS.

A alteração da área de trabalho não tem efeito sobre os controles de exibição de lista que têm o modo de exibição LVS_LIST ou LVS_REPORT, mas as áreas de trabalho serão mantidas quando o tipo de exibição for alterado. Com os modos de exibição LVS_ICON e LVS_SMALLICON, a área de trabalho pode ser modificada para alterar a maneira como os itens são exibidos. Tornar a largura da área de trabalho (direita - esquerda) maior do que a largura do cliente do controle faz com que os itens sejam encapsulados nessa largura e a barra de rolagem horizontal seja exibida. Tornar a largura da área de trabalho mais estreita do que a largura da área do cliente do controle faz com que os itens sejam encapsulados na área de trabalho e não na área do cliente. Definir o membro esquerdo ou superior como um valor positivo faz com que os itens sejam exibidos a partir da área de trabalho, criando um espaço vazio entre a borda do controle e os itens. Um espaço vazio também pode ser criado entre a borda direita do controle e os itens, tornando a largura da área de trabalho menor do que a largura do cliente do controle.

Listas de imagens de exibição de lista

Por padrão, um controle de exibição de lista não exibe imagens de item. Para exibir imagens de item, você deve criar listas de imagens e associá-las ao controle. Um controle de exibição de lista pode ter três listas de imagens:

  • Uma lista de imagens que contém ícones de tamanho completo exibidos quando o controle está no modo de exibição de ícones.
  • Uma lista de imagens que contém ícones pequenos exibidos quando o controle está no modo de exibição de ícone pequeno, modo de exibição de lista ou modo de exibição de relatório.
  • Uma lista de imagens que contém imagens de estado, que são exibidas à esquerda do ícone de tamanho completo ou pequeno. Você pode usar imagens de estado, como caixas de seleção marcadas e desmarcadas, para indicar estados de item definidos pelo aplicativo. As imagens de estado são exibidas no modo de exibição de ícone, no modo de exibição de ícone pequeno, no modo de exibição de lista e no modo de exibição de relatório.

As listas de imagens de ícones pequenos e de tamanho normal também podem conter imagens de sobreposição, que são projetadas para serem desenhadas de forma transparente sobre os ícones de item.

Para usar imagens de sobreposição em um controle de exibição de lista:

  1. Chame a função ImageList_SetOverlayImage para atribuir um índice de imagem de sobreposição a uma imagem nas listas de imagens de ícones pequenos e de tamanho completo. Uma imagem de sobreposição é identificada por um índice baseado em um.
  2. Você pode associar um índice de imagem de sobreposição a um item ao chamar a macro ListView_InsertItem ou ListView_SetItem. Use a macro INDEXTOOVERLAYMASK para especificar um índice de imagem de sobreposição no membro do estado da estrutura LVITEM do item. Você também deve definir os bits LVIS_OVERLAYMASK no membro stateMask .

Se uma lista de imagens de estado for especificada, um controle de exibição de lista reservará espaço à esquerda do ícone de cada item para uma imagem de estado.

Para associar uma imagem de estado a um item, use a macro INDEXTOSTATEIMAGEMASK para especificar um índice de imagem de estado no membro de estado da estrutura LVITEM. O índice identifica uma imagem na lista de imagens de estado do controle. Embora os índices de lista de imagens sejam baseados em zero, o controle usa índices baseados em um para identificar imagens de estado. Um índice de imagem de estado de zero indica que um item não tem imagem de estado.

Por padrão, quando um controle de exibição de lista é destruído, ele destrói as listas de imagens atribuídas a ele. No entanto, se um controle de exibição de lista tiver o estilo de janela LVS_SHAREIMAGELISTS, o aplicativo será responsável por destruir as listas de imagens quando elas não estiverem mais em uso. Você deve especificar esse estilo se atribuir as mesmas listas de imagens a vários controles de exibição de lista; caso contrário, mais de um controle pode tentar destruir a mesma lista de imagens.

Itens e subitens de exibição de lista

Cada item em um controle de exibição de lista tem um ícone, um rótulo, um estado atual e um valor definido pelo aplicativo. Usando mensagens de exibição de lista, você pode adicionar, modificar e excluir itens, bem como recuperar informações sobre itens.

Cada item pode ter um ou mais subitens. Um subitem é uma cadeia de caracteres que, no modo de exibição de relatório, é exibida em uma coluna separada do ícone e do rótulo do item. Para especificar o texto de um subitem, use a mensagem LVM_SETITEMTEXT ou LVM_SETITEM. Todos os itens em um controle de exibição de lista têm o mesmo número de subitens. O número de subitens é determinado pelo número de colunas no controle list-view. Ao adicionar uma coluna a um controle de exibição de lista, você especifica seu índice de subitem associado.

A estrutura LVITEM define um item ou subitem de exibição de lista. O membro iItem é o índice baseado em zero do item. O membro iSubItem é o índice baseado em um subitem ou zero se a estrutura contiver informações sobre um item. Membros adicionais especificam o texto, o ícone, o estado e os dados do item. Os dados do item são um valor definido pelo aplicativo associado a um item de exibição de lista.

Para adicionar um item a um controle de exibição de lista, use a mensagem LVM_INSERTITEM , especificando o endereço de uma estrutura LVITEM . Antes de adicionar vários itens, você pode enviar ao controle uma mensagem LVM_SETITEMCOUNT, especificando o número de itens que o controle conterá. Essa mensagem permite que o controle de exibição de lista realoque suas estruturas de dados internas apenas uma vez, em vez de toda vez que você adicionar um item. Você pode determinar o número de itens em um controle de exibição de lista usando a mensagem LVM_GETITEMCOUNT. Se você estiver adicionando um grande número de itens a um controle de exibição de lista, poderá acelerar o processo desabilitando o redesenho antes de adicionar os itens e, em seguida, habilitar o redesenho depois que os itens forem adicionados. Use a mensagem WM_SETREDRAW para habilitar e desabilitar o redesenho.

Para alterar os atributos de um item de exibição de lista, use a mensagem LVM_SETITEM , especificando o endereço de uma estrutura LVITEM . O membro da máscara dessa estrutura especifica os atributos de item que você deseja alterar. Por exemplo, para alterar apenas o texto de um item ou subitem, use a mensagem LVM_SETITEMTEXT.

Para recuperar informações sobre um item de exibição de lista, use a mensagem LVM_GETITEM, especificando o endereço da estrutura LVITEM a ser preenchida. O membro da máscara dessa estrutura especifica os atributos de item a serem recuperados. Para recuperar apenas o texto de um item ou subitem, use a mensagem LVM_GETITEMTEXT.

Para excluir um item de exibição de lista, use a mensagem LVM_DELETEITEM. Você pode excluir todos os itens em um controle de exibição de lista usando a mensagem LVM_DELETEALLITEMS.

Estados de item de exibição de lista

O estado de um item é um valor que especifica a disponibilidade do item, indica ações do usuário ou reflete o status do item. Um controle de exibição de lista altera alguns bits de estado, como quando o usuário seleciona um item. Um aplicativo pode alterar outros bits de estado para desabilitar ou ocultar o item ou para especificar uma imagem de sobreposição ou imagem de estado. Para obter mais informações sobre imagens de sobreposição e imagens de estado, consulte List-View Image Lists.

O estado de um item é especificado pelo estado membro da estrutura LVITEM. Quando você especifica ou altera o estado de um item, o membro stateMask especifica quais bits de estado você precisa alterar. Você pode alterar o estado de um item usando a mensagem LVM_SETITEMSTATE. Você pode especificar o estado de um item ao criá-lo ou ao alterar seus atributos usando a mensagem LVM_SETITEM. Para determinar o estado atual de um item, use a mensagem LVM_GETITEMSTATE ou LVM_GETITEM.

Para definir a imagem de sobreposição de um item, o membro stateMask da estrutura LVITEM deve incluir o valor LVIS_OVERLAYMASK e o membro state deve incluir o índice baseado em um da imagem de sobreposição deslocada para a esquerda 8 bits usando a macro INDEXTOOVERLAYMASK. O índice pode ser zero para especificar nenhuma imagem de sobreposição.

Para definir a imagem de estado de um item, o membro stateMask da estrutura LVITEM deve incluir o valor LVIS_STATEIMAGEMASK e o membro state deve incluir o índice baseado em um da imagem de estado deslocada para a esquerda 12 bits usando a macro INDEXTOSTATEIMAGEMASK. O índice pode ser zero para especificar nenhuma imagem de estado.

Itens e máscara de retorno de chamada

Para cada um de seus itens, um controle de exibição de lista normalmente armazena o texto do rótulo, o índice da lista de imagens dos ícones do item e um conjunto de sinalizadores de bits para o estado do item. Você pode definir itens de retorno de chamada ou alterar a máscara de retorno de chamada do controle para indicar que o aplicativo, em vez do controle, armazena algumas ou todas essas informações. Talvez você queira usar retornos de chamada se seu aplicativo armazenar algumas dessas informações.

Um item de retorno de chamada em um controle de exibição de lista é um item para o qual o aplicativo armazena o índice de texto ou ícone, ou ambos. Você pode definir itens de retorno de chamada ao enviar a mensagem LVM_INSERTITEM para adicionar um item ao controle list-view. Se o aplicativo armazenar o texto do item ou subitem, defina o membro pszText da estrutura LVITEM do item como LPSTR_TEXTCALLBACK. Se o aplicativo armazenar o índice de ícones de um item, defina o membro iImage da estrutura LVITEM do item como I_IMAGECALLBACK.

A máscara de retorno de chamada de um controle de exibição de lista é um conjunto de sinalizadores de bits que especificam os estados de item para os quais o aplicativo, em vez do controle, armazena os dados atuais. A máscara de retorno de chamada se aplica a todos os itens do controle, diferente da designação do item de retorno de chamada, que se aplica a um item específico. A máscara de retorno de chamada é zero por padrão, o que significa que o controle list-view armazena todas as informações de estado do item. Depois de criar um controle de exibição de lista e inicializar seus itens, você pode enviar a mensagem LVM_SETCALLBACKMASK para alterar a máscara de retorno de chamada. Para recuperar a máscara de retorno de chamada atual, envie a mensagem LVM_GETCALLBACKMASK.

Quando um controle de exibição de lista deve exibir ou classificar um item de exibição de lista para o qual o aplicativo armazena informações de retorno de chamada, o controle envia o código de notificação LVN_GETDISPINFO para a janela pai do controle. Essa mensagem especifica uma estrutura NMLVDISPINFO que contém o tipo de informação necessária e identifica o item ou subitem a ser recuperado. A janela pai deve processar LVN_GETDISPINFO para fornecer os dados solicitados.

Se o controle list-view detectar uma alteração nas informações de retorno de chamada de um item, como uma alteração nas informações de texto, ícone ou estado, o controle enviará um código de notificação LVN_SETDISPINFO para notificá-lo da alteração.

Se você alterar os atributos ou bits de estado de um item de retorno de chamada, use a mensagem LVM_UPDATE para forçar o controle a pintar novamente o item. Essa mensagem também faz com que o controle organize seus itens se ele tiver o estilo LVS_AUTOARRANGE. Você pode usar a mensagem LVM_REDRAWITEMS para redesenhar um intervalo de itens invalidando as partes correspondentes da área do cliente do controle de exibição de lista.

Usando efetivamente os itens de retorno de chamada e a máscara de retorno de chamada, você pode garantir que cada atributo de item seja mantido em apenas um lugar. Isso pode simplificar seu aplicativo, mas o único espaço salvo é a memória que, de outra forma, seria necessária para armazenar rótulos de item e texto de subitem.

Posição do item de exibição de lista

Cada item de exibição de lista tem uma posição e tamanho, que você pode recuperar e definir usando mensagens. Você também pode determinar qual item, se houver, está em uma posição especificada. A posição dos itens de exibição de lista é especificada em coordenadas de exibição, que são coordenadas de cliente deslocadas pela posição de rolagem.

Para recuperar e definir a posição de um item, use as mensagens LVM_GETITEMPOSITION e LVM_SETITEMPOSITION. LVM_GETITEMPOSITION funciona para todos os modos de exibição, mas LVM_SETITEMPOSITION funciona apenas para modos de exibição de ícone e ícones pequenos.

Você pode determinar qual item, se houver, está em um local específico usando a mensagem LVM_HITTEST.

Para recuperar o retângulo delimitador de um item de lista ou apenas de seu ícone ou rótulo, use a mensagem LVM_GETITEMRECT.

Organizando, classificando e localizando itens

Você pode usar mensagens de exibição de lista para organizar e classificar itens e localizar itens com base em seus atributos ou posições. Organizar reposiciona itens para alinhar em uma grade, mas os índices dos itens não mudam. A classificação altera a sequência de itens (e seus índices correspondentes) e, em seguida, os reposiciona de acordo. Você pode organizar itens somente em exibições de ícone e de ícone pequeno, mas pode classificar itens em qualquer modo de exibição. Para localizar itens, envie mensagens de exibição de lista que especificam um local ou propriedade de item.

Para organizar itens, use a mensagem LVM_ARRANGE. Você pode garantir que os itens estejam sempre organizados especificando o estilo de janela LVS_AUTOARRANGE.

Para classificar itens, use a mensagem LVM_SORTITEMS. Ao classificar usando essa mensagem, você especifica uma função de retorno de chamada definida pelo aplicativo que o controle list-view chama para comparar a ordem relativa de quaisquer dois itens. O controle passa para a função de comparação os dados do item associados a cada um dos dois itens. Os dados do item são o valor que foi especificado no membro lParam da estrutura LVITEM do item quando ele foi inserido na lista. Especificando os dados de item apropriados e fornecendo uma função de comparação apropriada, você pode classificar itens por seu rótulo, por qualquer subitem ou por qualquer outra propriedade. Observe que a classificação de itens não reordena os subitens correspondentes. Quando os itens são reordenados, seus subitens correspondentes são carregados com eles; ou seja, fileiras inteiras são mantidas juntas. Para ordenar as colunas separadamente umas das outras, separando os subitens de seus itens, você deve gerar novamente as colunas após a classificação usando LVM_SETITEM.

Você pode garantir que um controle de exibição de lista seja sempre classificado especificando o estilo de janela LVS_SORTASCENDING ou LVS_SORTDESCENDING. Os controles com esses estilos usam o texto do rótulo dos itens para classificá-los em ordem crescente ou decrescente. Não é possível fornecer uma função de comparação ao usar esses estilos de janela. Se um controle de exibição de lista tiver um desses estilos, uma mensagem de LVM_INSERTITEM falhará se você tentar inserir um item que tenha LPSTR_TEXTCALLBACK como o membro pszText de sua estrutura LVITEM.

Você pode encontrar um item de exibição de lista com propriedades específicas usando a mensagem LVM_FINDITEM. Você pode encontrar um item de exibição de lista que está em um estado especificado e tem uma relação especificada com um determinado item usando a mensagem LVM_GETNEXTITEM. Por exemplo, você pode recuperar o próximo item selecionado à direita de um item especificado.

Colunas de exibição de lista

As colunas controlam a maneira como os itens e seus subitens são exibidos no modo de exibição de relatório. Cada coluna tem um título e largura e está associada a um subitem específico; O subitem zero é o ícone e o rótulo do item. Os atributos de uma coluna são definidos por uma estrutura LVCOLUMN.

Para adicionar uma coluna a um controle de exibição de lista, use a mensagem LVM_INSERTCOLUMN. Para excluir uma coluna, use a mensagem LVM_DELETECOLUMN.

Observação

A exclusão da coluna zero de um controle de exibição de lista é suportada somente no ComCtl32.dll versão 6 e posterior. A versão 5 também oferece suporte à exclusão da coluna zero, mas somente depois de usar CCM_SETVERSION para definir a versão como 5 ou posterior. As versões anteriores à versão 5 não oferecem suporte à exclusão da coluna zero.

 

Você pode recuperar e alterar as propriedades de uma coluna existente usando as mensagens LVM_GETCOLUMN e LVM_SETCOLUMN. Para recuperar ou alterar a largura de uma coluna, use as mensagens LVM_GETCOLUMNWIDTH e LVM_SETCOLUMNWIDTH.

A menos que o estilo de janela LVS_NOCOLUMNHEADER seja especificado, os cabeçalhos de coluna aparecem no modo de exibição de relatório. O usuário pode clicar em um cabeçalho de coluna, fazendo com que um código de notificação LVN_COLUMNCLICK seja enviado para a janela pai. Normalmente, a janela pai classifica o controle de exibição de lista pela coluna especificada quando esse clique ocorre. O usuário também pode arrastar as guias de coluna entre os cabeçalhos para dimensionar as colunas.

Os controles de exibição de lista podem exibir imagens ao lado de títulos de coluna. Para implementar esse recurso, especifique o valor LVCF_IMAGE e atribua o índice da imagem ao membro iImage na estrutura LVCOLUMN.

Os controles de exibição de lista podem definir a ordem em que as colunas são exibidas. Para implementar esse recurso, especifique o valor LVCF_ORDER e atribua a ordem das colunas ao membro iOrder na estrutura LVCOLUMN. A ordem das colunas é baseada em zero e está na ordem da esquerda para a direita. Por exemplo, zero indica a coluna mais à esquerda.

Posição de rolagem do modo de exibição de lista

A menos que o estilo de janela LVS_NOSCROLL seja especificado, um controle de exibição de lista pode ser rolado para mostrar mais itens do que pode caber na área do cliente do controle. Você pode recuperar a posição de rolagem de um controle de exibição de lista e informações relacionadas, rolar um controle de exibição de lista por uma quantidade especificada ou rolar um controle de exibição de lista para que um item de lista especificado fique visível.

No modo de exibição de ícone ou no modo de exibição de ícone pequeno, a posição de rolagem atual é definida pela origem do modo de exibição. A origem da exibição é o conjunto de coordenadas, em relação à área visível do controle list-view, que correspondem às coordenadas da exibição (0, 0). Para recuperar a origem do modo de exibição atual, use a mensagem LVM_GETORIGIN. Esta mensagem deve ser usada apenas na visualização de ícones ou ícones pequenos; ele retorna um erro no modo de exibição de lista ou relatório.

No modo de exibição de lista ou relatório, a posição de rolagem atual é definida pelo índice superior. O índice superior é o índice do primeiro item visível no controle de exibição de lista. Para recuperar o índice superior atual, use a mensagem LVM_GETTOPINDEX. Essa mensagem retorna um resultado válido somente no modo de exibição de lista ou relatório; ele retorna zero no ícone ou na exibição de ícone pequeno.

Você pode usar a mensagem LVM_GETVIEWRECT para recuperar o retângulo delimitador de todos os itens em um controle de exibição de lista, relativo à área visível do controle.

A mensagem LVM_GETCOUNTPERPAGE retorna o número de itens que cabem em uma página do controle list-view. Essa mensagem retorna um resultado válido somente em modos de exibição de lista e relatório; Nas exibições de ícone e ícone pequeno, ele retorna o número total de itens.

Para rolar um controle de exibição de lista por uma quantidade específica, use a mensagem LVM_SCROLL. Usando a mensagem LVM_ENSUREVISIBLE, você pode rolar o controle de exibição de lista, se necessário, para garantir que um item especificado esteja visível.

Edição de rótulo de exibição de lista

Um controle de exibição de lista que tem o estilo de janela LVS_EDITLABELS permite que um usuário edite rótulos de item no lugar. O usuário começa a editar clicando no rótulo de um item com o foco. Como alternativa, um aplicativo pode começar a editar automaticamente usando a mensagem LVM_EDITLABEL. O controle list-view notifica a janela pai quando a edição começa e quando ela é cancelada ou concluída. Quando a edição for concluída, a janela pai será responsável por atualizar o rótulo do item, se apropriado.

Quando a edição de rótulo começa, um controle de edição é criado, posicionado e inicializado. Antes de ser exibido, o controle list-view envia à janela pai um código de notificação LVN_BEGINLABELEDIT . Se você precisar modificar o processo de edição de rótulo, poderá implementar um manipulador para essa notificação.

Um uso para um manipulador de notificação LVN_BEGINLABELEDIT é controlar quais rótulos o usuário pode editar. Para impedir a edição de rótulos, retorne um valor diferente de zero. Para personalizar a edição de rótulo, faça com que o manipulador de notificação recupere um identificador para o controle de edição enviando uma mensagem de LVM_GETEDITCONTROL para o controle de exibição de lista. Depois de ter esse identificador, você pode personalizar o controle de edição enviando as mensagens EM_XXX usuais. Por exemplo, para limitar a quantidade de texto que um usuário pode inserir, envie ao controle de edição uma mensagem EM_LIMITTEXT. Você pode alterar o texto padrão do controle de edição com SetWindowText. Você pode até mesmo subclassificar o controle de edição para interceptar e descartar caracteres inválidos.

Quando a edição de rótulo é cancelada ou concluída, um controle de exibição de lista envia à janela pai um código de notificação LVN_ENDLABELEDIT . O parâmetro lParam é o endereço de uma estrutura NMLVDISPINFO . O membro do item dessa estrutura é uma estrutura LVITEM cujo membro iItem identifica o item. Se a edição for cancelada, o membro pszText da estrutura LVITEM será NULL, caso contrário, pszText será o endereço do texto editado. A janela pai é responsável por atualizar o rótulo do item se quiser manter o novo rótulo.

Cores de exibição de lista

Um aplicativo pode recuperar e definir três cores para um controle de exibição de lista.

Color Mensagens usadas para recuperar e definir cores
Cor do texto LVM_GETTEXTCOLOR, LVM_SETTEXTCOLOR
Cor do plano de fundo do texto LVM_GETTEXTBKCOLOR, LVM_SETTEXTBKCOLOR
Cor de fundo da janela LVM_GETBKCOLOR, LVM_SETBKCOLOR

 

Para personalizar a aparência de um controle de exibição de lista de forma mais significativa, use NM_CUSTOMDRAW (modo de exibição de lista) ou use estilos visuais (consulte Estilos visuais e Habilitando estilos visuais).

Organizando itens de lista por grupo

Os recursos de agrupamento do controle de exibição de lista permitem que você agrupe visualmente conjuntos de itens logicamente relacionados. Os grupos podem ser criados com base em propriedades de item, atributos ou outras características. Esses grupos geralmente são separados na tela por um cabeçalho horizontal que contém o nome do grupo. A captura de tela a seguir mostra itens agrupados.

screen shot of a list-view control, with dogs in one group and cats in another group

Use a estrutura LVGROUP para armazenar informações sobre um grupo, como o texto do cabeçalho e rodapé, o estado atual do grupo e assim por diante. A API de agrupamento inclui mensagens que permitem gerenciar grupos e elementos de grupo adicionando itens a grupos, adicionando grupos a modos de exibição, classificando itens de grupo e consultando grupos para tamanho de item e outras informações. Por exemplo, você pode definir e recuperar parâmetros de exibição para cada grupo usando as macros ListView_SetGroupMetrics e ListView_GetGroupMetrics.

O agrupamento está disponível em todos os modos de exibição, exceto no modo de exibição de lista. Ele não está disponível em controles que têm o estilo LVS_OWNERDATA.

Para obter mais informações, consulte Usando controles de exibição de lista.

Marcas de inserção

As marcas de inserção mostram aos usuários onde os itens arrastados serão colocados. As marcas de inserção são exibidas atualmente quando o usuário arrasta um item para o menu Iniciar ou para a barra de Início Rápido. A marca de inserção também funciona para listas definidas como autoarranjo. Quando um usuário arrasta um item para um ponto entre dois outros itens, a marca de inserção mostra o novo local esperado do item. A captura de tela a seguir mostra uma marca de inserção.

screen shot that shows an insertion mark when dragging one file between two others in a list-view control

Os elementos da API de marca de inserção permitem o posicionamento de marcas de inserção fornecendo mensagens e sinalizadores que executam a detecção de ocorrências, que especificam o local e a aparência da marca de inserção por item e que consultam informações sobre o tamanho e a aparência atuais da marca de inserção.

Confira também