Estrutura TVITEMA (commctrl.h)

Especifica ou recebe atributos de um item de exibição de árvore. Essa estrutura é idêntica à estrutura TV_ITEM , mas foi renomeada para seguir as convenções de nomenclatura atuais. Novos aplicativos devem usar essa estrutura.

Sintaxe

typedef struct tagTVITEMA {
  UINT      mask;
  HTREEITEM hItem;
  UINT      state;
  UINT      stateMask;
  LPSTR     pszText;
  int       cchTextMax;
  int       iImage;
  int       iSelectedImage;
  int       cChildren;
  LPARAM    lParam;
} TVITEMA, *LPTVITEMA;

Membros

mask

Tipo: UINT

Matriz de sinalizadores que indicam qual dos outros membros da estrutura contêm dados válidos. Quando essa estrutura é usada com a mensagem TVM_GETITEM , o membro da máscara indica os atributos de item a serem recuperados. Se usada com a mensagem TVM_SETITEM , a máscara indica os atributos a serem definidos. Esse membro pode ser um ou mais dos seguintes valores:

Valor	Significado
TVIF_CHILDREN	O membro cChildren é válido.
TVIF_DI_SETITEM	O controle de exibição de árvore reterá as informações fornecidas e não as solicitará novamente. Esse sinalizador só é válido ao processar a notificação de TVN_GETDISPINFO .
TVIF_HANDLE	O membro hItem é válido.
TVIF_IMAGE	O membro iImage é válido.
TVIF_PARAM	O membro lParam é válido.
TVIF_SELECTEDIMAGE	O membro iSelectedImage é válido.
TVIF_STATE	Os membros state e stateMask são válidos.
TVIF_TEXT	Os membros pszText e cchTextMax são válidos.

hItem

Tipo: HTREEITEM

Manipule para o item.

state

Tipo: UINT

Conjunto de sinalizadores de bits e índices de lista de imagens que indicam o estado do item. Ao definir o estado de um item, o membro stateMask indica os bits válidos desse membro. Ao recuperar o estado de um item, esse membro retorna o estado atual para os bits indicados no membro stateMask .

Os bits 0 a 7 deste membro contêm os sinalizadores de estado do item. Para obter uma lista de possíveis sinalizadores de estado de item, consulte Estados de item de controle de exibição de árvore.

 

A imagem de sobreposição é sobreposta à imagem de ícone do item. Os bits de 8 a 11 deste membro especificam o índice de imagem de sobreposição baseado em um. Se esses bits forem zero, o item não terá nenhuma imagem de sobreposição. Para isolar esses bits, use a máscara de TVIS_OVERLAYMASK . Para definir o índice de imagem de sobreposição neste membro, use a macro INDEXTOOVERLAYMASK . As imagens de sobreposição da lista de imagens são definidas com a função ImageList_SetOverlayImage .

 

Uma imagem de estado é exibida ao lado do ícone de um item para indicar um estado definido pelo aplicativo. Especifique a lista de imagens de estado enviando uma mensagem de TVM_SETIMAGELIST . Para definir a imagem de estado de um item, inclua o valor TVIS_STATEIMAGEMASK no membro stateMask da estrutura TVITEM . Os bits 12 a 15 do membro de estado da estrutura especificam o índice na lista de imagens de estado da imagem a ser desenhada.

 

Para definir o índice de imagem de estado, use INDEXTOSTATEIMAGEMASK. Essa macro usa um índice e define os bits de 12 a 15 adequadamente. Para indicar que o item não tem nenhuma imagem de estado, defina o índice como zero. Essa convenção significa que a imagem zero na lista de imagens de estado não pode ser usada como uma imagem de estado. Para isolar os bits de 12 a 15 do membro do estado , use a máscara de TVIS_STATEIMAGEMASK .

stateMask

Tipo: UINT

Bits do membro de estado que são válidos. Se você estiver recuperando o estado de um item, defina os bits do membro stateMask para indicar os bits a serem retornados no membro do estado . Se você estiver definindo o estado de um item, defina os bits do membro stateMask para indicar os bits do membro de estado que deseja definir. Para definir ou recuperar o índice de imagem de sobreposição de um item, defina os bits TVIS_OVERLAYMASK . Para definir ou recuperar o índice de imagem de estado de um item, defina o TVIS_STATEIMAGEMASK bits.

pszText

Tipo: LPTSTR

Ponteiro para uma cadeia de caracteres terminada em nulo que contém o texto do item se a estrutura especificar atributos de item. Se esse membro for o valor LPSTR_TEXTCALLBACK, a janela pai será responsável por armazenar o nome. Nesse caso, o controle de exibição de árvore envia à janela pai um código de notificação TVN_GETDISPINFO quando precisa do texto do item para exibir, classificar ou editar e um código de notificação TVN_SETDISPINFO quando o texto do item for alterado. Se a estrutura estiver recebendo atributos de item, esse membro será o endereço do buffer que recebe o texto do item. Observe que, embora o controle de exibição de árvore permita que qualquer cadeia de caracteres de comprimento seja armazenada como texto do item, somente os primeiros 260 caracteres são exibidos.

cchTextMax

Tipo: int

Tamanho do buffer apontado pelo membro pszText, em caracteres . Se essa estrutura estiver sendo usada para definir atributos de item, esse membro será ignorado.

iImage

Tipo: int

Indexe na lista de imagens do controle de exibição de árvore da imagem de ícone a ser usada quando o item estiver no estado não selecionado. 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 árvore envia ao pai um código de notificação TVN_GETDISPINFO para recuperar o índice quando precisar exibir a imagem.

iSelectedImage

Tipo: int

Indexe na lista de imagens do controle de exibição de árvore da imagem de ícone a ser usada quando o item estiver no estado selecionado. 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 árvore envia ao pai um código de notificação TVN_GETDISPINFO para recuperar o índice quando precisar exibir a imagem.

cChildren

Tipo: int

Sinalizador que indica se o item tem itens filho associados. Esse membro pode ser um dos valores a seguir.

Valor	Significado
zero	O item não tem itens filho.
Um	O item tem um ou mais itens filho.
I_CHILDRENCALLBACK	A janela pai controla se o item tem itens filho. Nesse caso, quando o controle de exibição de árvore precisa exibir o item, o controle envia ao pai um código de notificação TVN_GETDISPINFO para determinar se o item tem itens filho. Se o controle de exibição de árvore tiver o estilo TVS_HASBUTTONS , ele usará esse membro para determinar se o botão indica a presença de itens filho. Você pode usar esse membro para forçar o controle a exibir o botão, mesmo que o item não tenha nenhum item filho inserido. Isso permite que você exiba o botão minimizando o uso de memória do controle inserindo itens filho somente quando o item estiver visível ou expandido.
I_CHILDRENAUTO	Versão 6.0Destinada ao uso interno; não é recomendável para uso em aplicativos. O controle de exibição de árvore determina automaticamente se o item tem itens filho. Nota Esse sinalizador pode não ter suporte em versões futuras do Comctl32.dll. Além disso, esse sinalizador não é definido em commctrl.h. Adicione a seguinte definição aos arquivos de origem do aplicativo para usar o sinalizador: #define I_CHILDRENAUTO (-2)

lParam

Tipo: LPARAM

Um valor a ser associado ao item.

Comentários

Observação

O cabeçalho commctrl.h define TVITEM 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

Requisito	Valor
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