Estrutura LVITEMA (commctrl.h)
Especifica ou recebe os atributos de um item de exibição de lista. Essa estrutura foi atualizada para dar suporte a um novo valor de máscara (LVIF_INDENT) que permite o recuo do item. Essa estrutura substitui a estrutura LV_ITEM .
Sintaxe
typedef struct tagLVITEMA {
UINT mask;
int iItem;
int iSubItem;
UINT state;
UINT stateMask;
LPSTR pszText;
int cchTextMax;
int iImage;
LPARAM lParam;
int iIndent;
int iGroupId;
UINT cColumns;
PUINT puColumns;
int *piColFmt;
int iGroup;
} LVITEMA, *LPLVITEMA;
Membros
mask
Tipo: UINT
Conjunto de sinalizadores que especificam quais membros dessa estrutura contêm dados a serem definidos ou quais membros estão sendo solicitados. Esse membro pode ter um ou mais dos seguintes sinalizadores definidos:
| Valor | Significado |
|---|---|
|
Windows Vista e posterior. O membro piColFmt é válido ou deve ser definido. Se esse sinalizador for usado, o membro cColumns será válido ou deverá ser definido. |
|
O membro cColumns é válido ou deve ser definido. |
|
O sistema operacional deve armazenar as informações de item de lista solicitadas e não solicitá-la novamente. Esse sinalizador é usado apenas com o código de notificação LVN_GETDISPINFO . |
|
O membro iGroupId é válido ou deve ser definido. Se esse sinalizador não for definido quando uma mensagem de LVM_INSERTITEM for enviada, o valor de iGroupId será considerado I_GROUPIDCALLBACK. |
|
O membro iImage é válido ou deve ser definido. |
|
O membro iIndent é válido ou deve ser definido. |
|
O controle não gerará LVN_GETDISPINFO para recuperar informações de texto se receber uma mensagem de LVM_GETITEM . Em vez disso, o membro pszText conterá LPSTR_TEXTCALLBACK. |
|
O membro lParam é válido ou deve ser definido. |
|
O membro do estado é válido ou deve ser definido. |
|
O membro pszText é válido ou deve ser definido. |
iItem
Tipo: int
Índice baseado em zero do item ao qual essa estrutura se refere.
iSubItem
Tipo: int
Índice baseado em um do subitem ao qual essa estrutura se refere ou zero se essa estrutura se referir a um item em vez de um subitem.
state
Tipo: UINT
Indica o estado do item, a imagem de estado e a imagem de sobreposição. O membro stateMask indica os bits válidos desse membro.
Os bits 0 a 7 deste membro contêm os sinalizadores de estado do item. Pode ser um ou mais dos valores de estado do item .
Os bits 8 a 11 deste membro especificam o índice de imagem de sobreposição baseada em um. A lista de imagens de ícone de tamanho completo e a lista de imagens de ícone pequeno podem ter imagens de sobreposição. A imagem de sobreposição é sobreposta sobre a imagem de ícone do item. Se esses bits forem zero, o item não terá nenhuma imagem de sobreposição. Para isolar esses bits, use a máscara de LVIS_OVERLAYMASK . Para definir o índice de imagem de sobreposição neste membro, você deve usar a macro INDEXTOOVERLAYMASK . As imagens de sobreposição da lista de imagens são definidas com a função ImageList_SetOverlayImage .
Os bits 12 a 15 deste membro especificam o índice de imagem de estado. A imagem de estado é exibida ao lado do ícone de um item para indicar um estado definido pelo aplicativo. Se esses bits forem zero, o item não terá nenhuma imagem de estado. Para isolar esses bits, use a máscara LVIS_STATEIMAGEMASK . Para definir o índice de imagem de estado, use a macro INDEXTOSTATEIMAGEMASK . O índice de imagem de estado especifica o índice da imagem na lista de imagens de estado que deve ser desenhada. A lista de imagens de estado é especificada com a mensagem LVM_SETIMAGELIST .
stateMask
Tipo: UINT
Valor que especifica quais bits do membro de estado serão recuperados ou modificados. Por exemplo, definir esse membro como LVIS_SELECTED fará com que apenas o estado de seleção do item seja recuperado.
Esse membro permite que você modifique um ou mais estados de item sem precisar recuperar todos os estados de item primeiro. Por exemplo, definir esse membro como LVIS_SELECTED e o estado como zero fará com que o estado de seleção do item seja limpo, mas nenhum dos outros estados será afetado.
Para recuperar ou modificar todos os estados, defina esse membro como (UINT)-1.
Você pode usar a macro ListView_SetItemState para definir e limpar bits.
pszText
Tipo: LPTSTR
Se a estrutura especificar atributos de item, pszText será um ponteiro para uma cadeia de caracteres terminada em nulo que contém o texto do item. Ao responder a uma notificação de LVN_GETDISPINFO , certifique-se de que esse ponteiro permaneça válido até que a próxima notificação seja recebida.
Se a estrutura receber atributos de item, pszText será um ponteiro para um buffer que recebe o texto do item. Observe que, embora o controle de exibição de lista permita que qualquer cadeia de caracteres de comprimento seja armazenada como texto do item, somente os primeiros 259 TCHARs são exibidos.
Se o valor de pszText for LPSTR_TEXTCALLBACK, o item será um item de retorno de chamada. Se o texto de retorno de chamada for alterado, você deverá definir explicitamente pszText para LPSTR_TEXTCALLBACK e notificar o controle de exibição de lista da alteração enviando uma mensagem de LVM_SETITEM ou LVM_SETITEMTEXT .
Não defina pszText como LPSTR_TEXTCALLBACK se o controle de exibição de lista tiver o estilo LVS_SORTASCENDING ou LVS_SORTDESCENDING .
cchTextMax
Tipo: int
Número de TCHARs no buffer apontado por pszText, incluindo o NULL de terminação.
Esse membro só é usado quando a estrutura recebe atributos de item. Ele é ignorado quando a estrutura especifica atributos de item. Por exemplo, cchTextMax é ignorado durante LVM_SETITEM e LVM_INSERTITEM. Ele é somente leitura durante LVN_GETDISPINFO e outras notificações de LVN_.
iImage
Tipo: int
Índice do ícone do item na lista de imagens do controle. Isso se aplica à lista de imagens grandes e pequenas. Se esse membro for o valor I_IMAGECALLBACK, a janela pai será responsável por armazenar o índice. Nesse caso, o controle de exibição de lista envia ao pai um código de notificação LVN_GETDISPINFO para recuperar o índice quando precisar exibir a imagem.
lParam
Tipo: LPARAM
Valor específico para o item. Se você usar a mensagem LVM_SORTITEMS , o controle de exibição de lista passará esse valor para a função de comparação definida pelo aplicativo. Você também pode usar a mensagem LVM_FINDITEM para pesquisar um controle de exibição de lista para um item com um valor lParam especificado.
iIndent
Tipo: int
Versão 4.70. Número de larguras de imagem para recuar o item. Um único recuo é igual à largura de uma imagem de item. Portanto, o valor 1 recuará o item pela largura de uma imagem, o valor 2 recuará por duas imagens e assim por diante. Observe que esse campo tem suporte apenas para itens. A tentativa de definir o recuo de subitem fará com que a função de chamada falhe.
iGroupId
Tipo: int
Versão 6.0 Identificador do grupo ao qual o item pertence ou um dos valores a seguir.
| Valor | Significado |
|---|---|
|
O controle listview envia ao pai um código de notificação LVN_GETDISPINFO para recuperar o índice do grupo. |
|
O item não pertence a um grupo. |
cColumns
Tipo: UINT
Versão 6.0 Número de colunas de dados (subitems) a serem exibidas para este item no modo de exibição de bloco. O valor máximo é 20. Se esse valor for I_COLUMNSCALLBACK, o tamanho da matriz de colunas e a própria matriz (puColumns) serão obtidos enviando uma notificação de LVN_GETDISPINFO .
puColumns
Tipo: PUINT
Versão 6.0 Um ponteiro para uma matriz de índices de coluna, especificando quais colunas são exibidas para esse item e a ordem dessas colunas.
piColFmt
Tipo: int*
Windows Vista: Não implementado. Windows 7 e posterior: Um ponteiro para uma matriz dos sinalizadores a seguir (sozinho ou em combinação), especificando o formato de cada subitem no modo de exibição de bloco estendido.
iGroup
Tipo: int
Windows Vista: índice de grupo do item. Válido somente para dados/retorno de chamada do proprietário (item único em vários grupos).
Comentários
A estrutura LVITEM é usada com várias mensagens, incluindo LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM e LVM_DELETEITEM.
No modo de exibição de bloco, o nome do item é exibido à direita do ícone. Você pode especificar subitens adicionais (correspondentes a colunas na exibição de detalhes), a serem exibidos em linhas abaixo do nome do item. A matriz puColumns contém os índices de subitens a serem exibidos. Os índices devem ser maiores que 0, pois subitem 0, o nome do item, já está exibido. As informações da coluna também podem ser definidas na estrutura LVTILEINFO ao modificar o item de lista.
Por exemplo, código, consulte Usando controles de List-View.
Observação
O cabeçalho commctrl.h define LVITEM como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Cabeçalho | commctrl.h |
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de