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
LVIF_COLFMT	Windows Vista e posterior. O membro piColFmt é válido ou deve ser definido. Se esse sinalizador for usado, o cColumns membro será válido ou deverá ser definido.
LVIF_COLUMNS	O membro cColumns é válido ou deve ser definido.
LVIF_DI_SETITEM	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.
LVIF_GROUPID	O membro iGroupId é válido ou deve ser definido. Se esse sinalizador não estiver definido quando uma mensagem de LVM_INSERTITEM for enviada, o valor de iGroupId será considerado I_GROUPIDCALLBACK.
LVIF_IMAGE	O membro do iImage é válido ou deve ser definido.
LVIF_INDENT	O membro iIndent é válido ou deve ser definido.
LVIF_NORECOMPUTE	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.
LVIF_PARAM	O membro lParam é válido ou deve ser definido.
LVIF_STATE	O membro de estado é válido ou deve ser definido.
LVIF_TEXT	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

Um índice baseado no 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. Isso pode ser um ou mais dos valores de 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 pequena lista de imagens de ícone 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 de 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 de 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 estado membro 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 estado a 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é depois que a próxima notificação for 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ã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 LVM_SETITEM ou LVM_SETITEMTEXT.

Não defina pszText para LPSTR_TEXTCALLBACK se o controle de exibição de lista tiver o estilo LVS_SORTASCENDING ou LVS_SORTDESCENDING.

cchTextMax

Tipo: int

Número de deTCHAR no buffer apontado por pszText, incluindo o de terminação NULL.

Esse membro só é usado quando a estrutura recebe atributos de item. Ela é ignorada 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 LVN_.

Observação Nunca copie mais de cchTextMaxdeTCHAR — em que cchTextMax inclui aNULL de terminação — em pszText durante uma notificação LVN_, caso contrário, seu programa pode falhar.

 

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 ele precisa exibir a imagem.

lParam

Tipo: LPARAM

Valor específico para o item. Se você usar a mensagem LVM_SORTITEMS, o controle list-view 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 de 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
I_GROUPIDCALLBACK	O controle listview envia ao pai um código de notificação LVN_GETDISPINFO para recuperar o índice do grupo.
I_GROUPIDNONE	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 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 este item e a ordem dessas colunas.

piColFmt

Tipo: int*

Windows Vista: Não implementado. Windows 7 e posterior: um ponteiro para uma matriz dos seguintes sinalizadores (sozinho ou em combinação), especificando o formato de cada subitem no modo de exibição de bloco estendido.

Valor	Significado
LVCFMT_LINE_BREAK	Força a coluna a encapsular na parte superior da próxima lista de colunas.
LVCFMT_FILL	Preenche o restante da área do bloco. Pode ter um título.
LVCFMT_WRAP	Permite que a coluna encapsular dentro do espaço restante em sua lista de colunas.
LVCFMT_NO_TITLE	Remove o título do subitem.
LVCFMT_TILE_PLACEMENTMASK	Equivalente a uma combinação de LVCFMT_LINE_BREAK e LVCFMT_FILL.

iGroup

Tipo: int

Windows Vista: índice de grupo do item. Válido somente para dados de proprietário/retorno de chamada (item único em vários grupos).

Observações

A estrutura de LVITEM é usada com várias mensagens, incluindo LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEMe 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 subitem a serem exibidos. Os índices devem ser maiores que 0, pois o subitem 0, o nome do item, já está exibido. As informações da coluna também podem ser definidas na estrutura de LVTILEINFO ao modificar o item de lista.

Por exemplo, código, consulte Usando controles List-View.

Observação Comctl32.dll versão 6 não é redistribuível, mas está incluída no Windows ou posterior. Para usar Comctl32.dll versão 6, especifique-o em um manifesto. Para obter mais informações sobre manifestos, consulte Habilitando estilos visuais.

 

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
cabeçalho	commctrl.h