Compartilhar via


Estrutura TVITEMW (commctrl.h)

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

Sintaxe

typedef struct tagTVITEMW {
  UINT      mask;
  HTREEITEM hItem;
  UINT      state;
  UINT      stateMask;
  LPWSTR    pszText;
  int       cchTextMax;
  int       iImage;
  int       iSelectedImage;
  int       cChildren;
  LPARAM    lParam;
} TVITEMW, *LPTVITEMW;

Membros

mask

Tipo: UINT

Matriz de sinalizadores que indicam quais dos outros membros da estrutura contêm dados válidos. Quando essa estrutura é usada com a mensagem TVM_GETITEM, a máscara membro indica os atributos de item a serem recuperados. Se usado com a mensagem TVM_SETITEM, a máscara indicará 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 manterá 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 do iImage é válido.
TVIF_PARAM
O membro lParam é válido.
TVIF_SELECTEDIMAGE
O membro iSelectedImage é válido.
TVIF_STATE
Os membros state state e são válidos.
TVIF_TEXT
Os membros do 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 stateMask membro 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 stateMask membro.

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 Tree-View estados de item de controle.

 

A imagem de sobreposição é sobreposta sobre a imagem de ícone do item. Os bits 8 a 11 deste membro especificam o índice de imagem de sobreposição baseada 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 TVM_SETIMAGELIST. Para definir a imagem de estado de um item, inclua o valor de TVIS_STATEIMAGEMASK no stateMask membro da estrutura TVITEM. Os bits 12 a 15 do estado da estrutura membro 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 de estado , use a máscara de TVIS_STATEIMAGEMASK.

stateMask

Tipo: UINT

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

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 exibição, classificação ou edição e um código de notificação TVN_SETDISPINFO quando o texto do item é 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 ele precisa 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 ele precisa exibir a imagem.

cChildren

Tipo: int

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

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 recomendado para uso em aplicativos. O controle de exibição de árvore determina automaticamente se o item tem itens filho.

Observação 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.

Observações

Nota

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