Sobre os Controles List-View

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 simples Caixas de Lista. Por exemplo, informações adicionais sobre cada item podem ser exibidas em colunas à direita do ícone e do rótulo.

• List-View estilos e vistas
  • Estilos de List-View estendidos
• Estilo List-View Virtual
  • Criando um List-View Controle virtual
  • problemas de compatibilidade
  • Manipulação de códigos de notificação de controle virtual List-View
  • Gestão de Cache
• List-View Áreas de Trabalho
• List-View Listas de imagens
• List-View Itens e Subitens
  • List-View Estados do Item
  • itens de callback e a máscara de callback
  • List-View Posição do Item
  • Organizar, classificar e localizar itens
• List-View Colunas
• List-View Posição de rolagem
• List-View Edição de Etiquetas
• List-View Cores
• Organizando itens de lista por grupo
• Marcas de inserção

List-View Estilos e Vistas

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 as visualizações.

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. As visualizações 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 ecrã a seguir mostra a vista de detalhes.

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

A imagem seguinte mostra a vista da lista.

A captura de ecrã seguinte mostra a vista de mosaico.

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.

Pode controlar a forma como os itens são organizados na vista de ícones ou ícones pequenos especificando o LVS_ALIGNTOP (predefinição) ou LVS_ALIGNLEFT estilo de 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 de cada vez. Para obter uma lista completa, consulte List-View Estilos de janela.

Estilos estendidos de List-View

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 Estendidos List-View. Você não acessa estilos de exibição de lista estendidos 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 estendido, LVM_SETEXTENDEDLISTVIEWSTYLE e LVM_GETEXTENDEDLISTVIEWSTYLE. Em vez de enviar as mensagens explicitamente, você pode usar as seguintes macros correspondentes: ListView_SetExtendedListViewStyle, ListView_SetExtendedListViewStyleExe ListView_GetExtendedListViewStyle.

Estilo List-View Virtual

Um modo de exibição em lista virtual é um controlo de exibição de lista que possui o estilo LVS_OWNERDATA. Esse estilo permite que o controle manipule milhões de itens porque o proprietário recebe a carga de gerenciar os dados do 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. Exceto para a seleção do item e informações de foco, o proprietário do controle deve gerenciar todas as informações do item. Outros processos solicitam informações de itens do proprietário usando códigos de notificação LVN_GETDISPINFO.

Como esse tipo de controle de lista se destina a grandes conjuntos de dados, é recomendável armazenar em cache os dados do item solicitado para melhorar o desempenho da recuperação. A exibição de lista fornece um mecanismo de sugestão 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 List-View virtual

Você cria controles de vista de lista virtual utilizando 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 visualização de lista virtuais 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.

As seguintes mensagens não são suportadas no estilo LVS_OWNERDATA: LVM_ENABLEGROUPVIEW, LVM_GETITEMTEXT, LVM_SETTILEINFOe 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 informações específicas 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 de exibição de lista 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 utiliza o estilo LVS_OWNERDATA. A tabela a seguir resume as mensagens afetadas.

Manipulando códigos de notificação de controle de List-View 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.

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 para incluir 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 finais inclusivos de um intervalo de itens que serão provavelmente 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 controlo de lista geralmente precisa de informações de item para o primeiro elemento (deslocamento 0). O código de notificação LVN_ODCACHEHINT nem sempre pode 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 em relação ao cache final para torná-lo disponível automaticamente em vez de recarregar o mesmo intervalo final a cada vez.

List-View Áreas de Trabalho

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 de exibição de lista 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 é movido para uma área de trabalho, o item se torna um membro dessa área de trabalho. Se um item não estiver dentro de qualquer área de trabalho, ele se torna automaticamente um membro da primeira área de trabalho (índice 0). Para colocar um novo item dentro de 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.

Várias áreas de trabalho podem ser usadas para criar diferentes áreas dentro de uma visualização. Você pode criar áreas em uma única 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 um array de estruturas de RECT como o lParam e o número de estruturas de RECT como o 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 nas coordenadas do cliente da exibição de lista. O número máximo de áreas de trabalho permitido é definido pelo valor LV_MAX_WORKAREAS.

A alteração da área de trabalho não tem efeito nos controles de exibição de lista que têm a exibição LVS_LIST ou LVS_REPORT, mas as áreas de trabalho serão mantidas quando o tipo de exibição for alterado. Com as vistas LVS_ICON e LVS_SMALLICON, a área de trabalho pode ser modificada para alterar a forma como os itens são apresentados. 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 envolvidos dentro da área de trabalho e não na área do cliente. Definir o membro esquerdo ou o membro superior para um valor positivo faz com que os itens sejam exibidos a partir da área de trabalho útil, criando um espaço vazio entre a borda do controlo 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.

List-View Listas de imagens

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 em tamanho real exibidos quando o controle está na visualizaçã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, apresentadas à esquerda de um ícone em tamanho normal ou reduzido. 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, modo de exibição de ícone pequeno, modo de exibição de lista e modo de exibição de relatório.

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

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 de tamanho real e pequenos. 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 quando chama a macro ListView_InsertItem ou ListView_SetItem. Use a macro INDEXTOOVERLAYMASK para especificar um índice de imagem de sobreposição no membro de 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, utilize 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.

List-View Itens e Subitens

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 de exibição de lista. 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 do iSubItem é o índice baseado em um de 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. de dados do item é 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 deLVITEM. 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ê adiciona 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 desativando 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 . A máscara do membro desta estrutura especifica os atributos do item que pretende 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 desta estrutura especifica os atributos de item a recuperar. 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.

List-View Estados do Item

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 Listas de imagens.

O estado de um item é especificado pelo membro de estado da estrutura LVITEM. Quando se especifica ou altera o estado de um item, o membro stateMask especifica quais bits de estado precisam ser alterados. 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 stateMask membro da estrutura deLVITEMdeve incluir o valor LVIS_OVERLAYMASK e o estado membro 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 não especificar nenhuma imagem de sobreposição.

Para definir a imagem de estado de um item, o stateMask membro da estrutura deLVITEMdeve incluir o valor LVIS_STATEIMAGEMASK e o estado membro deve incluir o índice baseado em um da imagem de estado deslocado para a esquerda 12 bits usando a macroINDEXTOSTATEIMAGEMASK. O índice pode ser zero para especificar a ausência de uma imagem de estado.

Itens de retorno de chamada e a 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 queiras usar callbacks se a tua aplicação 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 callback ao enviar a mensagem LVM_INSERTITEM para adicionar um item ao controlo de vista de lista. Se a aplicação armazenar o texto para o item ou subitem, defina o membro pszText da estruturaLVITEM do itemcomo LPSTR_TEXTCALLBACK. Se a aplicação armazenar o índice do ícone 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 bit que especificam os estados do 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, ao contrário da designação de 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 controlo de visualização de lista armazena todas as informações sobre o estado dos itens. Depois de criar um controle de exibição de lista e inicializar os seus itens, você pode enviar a mensagem de 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. Esta mensagem especifica uma estrutura de NMLVDISPINFO que contém o tipo de informação necessária e identifica o item ou subitem a recuperar. A janela pai deve processar LVN_GETDISPINFO para fornecer os dados solicitados.

Se o controle de exibição de lista detetar 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 repintar 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 de cliente do controle de exibição de lista.

Usando efetivamente os itens de retorno de chamada e a máscara de retorno de chamada, pode-se garantir que cada atributo de item seja mantido em apenas um lugar. Fazer 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.

List-View Posicionamento do Item

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 do 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 todas as vistas, mas LVM_SETITEMPOSITION funciona apenas para vistas de ícones 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 para 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 modos de exibição de ícones e ícones pequenos, 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 esta mensagem, você especifica uma função de 'callback' definida pelo aplicativo que o controlo de vista de lista utiliza para comparar a ordem relativa entre 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 foi inserido na lista. Especificando os dados apropriados do item e fornecendo uma função de comparação apropriada, você pode classificar os 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 transportados 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 regenerar as colunas depois de classificar 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 pszText membro de sua estrutura deLVITEM.

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.

List-View Colunas

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.

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 principal ordena o controlo de visualização de lista pela coluna especificada quando ocorre esse clique. 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 estruturaLVCOLUMN.

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 estruturaLVCOLUMN. A ordem das colunas é baseada em zero e está na ordem da esquerda para a direita. Por exemplo, zero indica a coluna mais à esquerda.

List-View Posição de rolagem

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 cabe 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.

Na vista de ícones ou na vista de ícones pequenos, a posição de deslocamento atual é definida pela origem da vista . A origem da exibição é o conjunto de coordenadas, relativas à área visível do controle de exibição de lista, que correspondem às coordenadas de 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. Esta mensagem devolve um resultado válido apenas no modo de lista ou relatório; devolve zero no modo de ícone ou í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 de exibição de lista. Esta mensagem devolve um resultado válido apenas nas vistas de lista e relatório; Nas visualizações de ícones e ícones pequenos, ele retorna o número total de itens.

Para rolar um controle de exibição de lista por um valor específico, 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.

List-View Edição de etiquetas

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 local. O usuário começa a editar clicando no rótulo de um item que tem o foco. Como alternativa, um aplicativo pode começar a editar automaticamente usando a mensagem LVM_EDITLABEL. O controle de exibição de lista notifica a janela pai quando a edição começa e quando ela é cancelada ou concluída. Quando a edição é concluída, a janela principal é responsável por atualizar o rótulo do item, se apropriado.

Quando a edição de rótulos começa, um controle de edição é criado, posicionado e inicializado. Antes de ser exibido, o controlo de exibição de lista envia à janela pai um código de notificação LVN_BEGINLABELEDIT. Se você precisar modificar o processo de edição de rótulos, 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 evitar a edição de rótulos, retorne um valor diferente de zero. Para personalizar a edição de rótulos, peça ao manipulador de notificação que recupere um identificador para o controle de edição enviando uma mensagem 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 intercetar e descartar caracteres inválidos.

Quando a edição de rótulos é 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 item membro desta estrutura é uma estrutura deLVITEMcujo membro iItem identifica o item. Se a edição for cancelada, o pszText membro da estrutura LVITEM será NULL; caso contrário, pszText é o endereço do texto editado. A janela pai é responsável por atualizar a etiqueta do item se quiser manter a nova etiqueta.

List-View Cores

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

Para personalizar de forma mais significativa a aparência de um controle de visualização de lista, use NM_CUSTOMDRAW (controle de visualizaçã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 nas propriedades do 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.

Use a estrutura LVGROUP para armazenar informações sobre um grupo, como o texto do cabeçalho e do 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 List-View.

Marcas de inserção

As marcas de inserção mostram aos usuários onde os itens arrastados serão colocados. Atualmente, as marcas de inserção são exibidas quando o usuário arrasta um item para o menu Iniciar ou para a barra Início Rápido. A marca de inserção também funciona para listas definidas para organização automática. 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 ecrã a seguir mostra uma marca de inserção.

Os elementos da API da marca de inserção permitem posicionar as marcas de inserção, fornecendo mensagens e sinalizadores que realizam a deteção de colisões, especificando o local e o aspeto da marca de inserção por item, e consultando informações sobre o tamanho e o aspeto atuais da marca de inserção.

Ver também

• Exemplo de controlo de lista de visualização virtual