Sobre controles de exibição de árvore

Um controle de exibição em árvore é uma janela que exibe uma lista hierárquica de itens, como os títulos em um documento, as entradas em um índice ou os arquivos e diretórios em um disco. Cada item consiste em um rótulo e uma imagem em bitmap opcional, e cada item pode ter uma lista de subitens associados a ele. Ao clicar em um item, o usuário pode expandir ou recolher a lista de subitens associada.

A ilustração a seguir mostra um controle de exibição em árvore simples com um nó raiz, um nó expandido e um nó recolhido. O controle usa um bitmap para o item selecionado e outro bitmap para outros itens.

Depois de criar um controle de exibição em árvore, você adiciona, remove, organiza ou manipula itens enviando mensagens para o controle. Cada mensagem tem uma ou mais macros correspondentes que você pode usar em vez de enviá-la explicitamente.

Os tópicos a seguir são discutidos nesta seção.

• Estilos de exibição em árvore
• Itens pai e filho
• Etiquetas de Item
• Edição de rótulos de exibição em árvore
• Posição do item de exibição em árvore
• Visão geral dos estados de item de exibição em árvore
• Seleção de Itens
• Informações do item
• Listas de imagens de exibição em árvore
• Operações de arrastar e soltar
• Mensagens de notificação de controle de exibição em árvore
• Processamento de mensagens de controle de exibição em árvore padrão
• Tópicos relacionados

Estilos de exibição em árvore

Os estilos de exibição em árvore governam aspectos da aparência de um controle de exibição em árvore. Você define os estilos iniciais ao criar o controle de exibição em árvore. Você pode recuperar e alterar os estilos depois de criar o controle de exibição em árvore usando as funções GetWindowLong e SetWindowLong.

O estilo TVS_HASLINES aprimora a representação gráfica da hierarquia de um controle de exibição em árvore desenhando linhas que vinculam itens filho ao item pai, conforme mostrado na ilustração a seguir.

Por si só, esse estilo não traça linhas na raiz da hierarquia. Para fazer isso, você precisa combinar os estilos TVS_HASLINES e TVS_LINESATROOT . O resultado é mostrado na ilustração a seguir.

O usuário pode expandir ou recolher uma lista de itens filho de um item pai clicando duas vezes no item pai. Um controle de exibição em árvore que tem o estilo TVS_HASBUTTONS adiciona um botão ao lado esquerdo de cada item pai. O usuário pode clicar no botão uma vez em vez de clicar duas vezes no item pai para expandir ou recolher o filho. TVS_HASBUTTONS não adiciona botões a itens na raiz da hierarquia. Para fazer isso, você deve combinar TVS_HASLINES, TVS_LINESATROOT e TVS_HASBUTTONS. Essa combinação de estilos é mostrada na ilustração a seguir.

O estilo TVS_CHECKBOXES cria caixas de seleção ao lado de cada item. Se você quiser usar o estilo de caixa de seleção, você deve definir o estilo TVS_CHECKBOXES (com SetWindowLong) depois de criar o controle de exibição de árvore e antes de preencher a árvore. Caso contrário, as caixas de seleção podem aparecer desmarcadas, dependendo de problemas de tempo. A ilustração a seguir mostra o estilo da caixa de seleção.

O estilo TVS_FULLROWSELECT faz com que o realce de seleção se estenda por toda a largura do controle, não apenas sobre o item em si. A ilustração a seguir mostra esse estilo.

O estilo TVS_EDITLABELS possibilita que o usuário edite os rótulos dos itens de exibição em árvore. Para obter mais informações sobre como editar rótulos, consulte Edição de rótulos de exibição em árvore.

Para obter mais informações sobre esses e outros estilos, consulte Estilos de janela de controle de exibição em árvore.

Itens pai e filho

Qualquer item em um controle de exibição em árvore pode ter uma lista de subitens — chamados itens filho — associados a ele. Um item que tem um ou mais itens filho é chamado de item pai. Um item filho é exibido abaixo de seu item pai e é recuado para indicar que ele está subordinado ao pai. Um item que não tem pai aparece no topo da hierarquia e é chamado de item raiz.

Para adicionar um item a um controle de exibição em árvore, envie a mensagem TVM_INSERTITEM para o controle. A mensagem retorna um identificador para o tipo HTREEITEM, que identifica exclusivamente o item. Ao adicionar um item, você deve especificar o identificador para o item pai do novo item. Se você especificar NULL ou o valor TVI_ROOT em vez de um identificador de item pai na estrutura TVINSERTSTRUCT, o item será adicionado como um item raiz.

A qualquer momento, o estado da lista de itens filho de um item pai pode ser expandido ou recolhido. Quando o estado é expandido, os itens filho são exibidos abaixo do item pai. Quando ele é recolhido, os itens filho não são exibidos. A lista alterna automaticamente entre os estados expandido e recolhido quando o usuário clica duas vezes no item pai ou, se o pai tiver o estilo TVS_HASBUTTONS, quando o usuário clicar no botão associado ao item pai. Um aplicativo pode expandir ou recolher os itens filho usando a mensagem TVM_EXPAND.

Um controle de exibição em árvore envia à janela pai uma mensagem de notificação TVN_ITEMEXPANDING quando a lista de itens filho de um item pai está prestes a ser expandida ou recolhida. A notificação dá a um aplicativo a oportunidade de impedir a alteração ou definir quaisquer atributos do item pai que dependam do estado da lista de itens filho. Depois de alterar o estado da lista, o controle de exibição em árvore envia à janela pai uma mensagem de notificação TVN_ITEMEXPANDED .

Quando uma lista de itens filho é expandida, ela é recuada em relação ao item pai. Você pode definir a quantidade de recuo usando a mensagem TVM_SETINDENT ou recuperar a quantidade atual usando a mensagem TVM_GETINDENT.

Um controle de exibição em árvore usa memória alocada do heap do processo que cria o controle de exibição em árvore. O número máximo de itens em um modo de exibição de árvore é baseado na quantidade de memória disponível no heap.

Etiquetas de Item

Normalmente, você especifica o texto do rótulo de um item ao adicionar o item ao controle de exibição em árvore. A mensagem TVM_INSERTITEM inclui uma estrutura TVITEM que define as propriedades do item, incluindo uma cadeia de caracteres que contém o texto do rótulo.

Um controle de exibição em árvore aloca memória para armazenar cada item; O texto dos rótulos dos itens ocupa uma parte significativa dessa memória. Se seu aplicativo mantém uma cópia das cadeias de caracteres no controle de exibição em árvore, você pode diminuir os requisitos de memória do controle especificando o valor de LPSTR_TEXTCALLBACK no membro pszText de TVITEM em vez de passar cadeias de caracteres reais para o modo de exibição de árvore. O uso LPSTR_TEXTCALLBACK faz com que o controle de exibição em árvore recupere o texto do rótulo de um item da janela pai sempre que o item precisar ser redesenhado. Para recuperar o texto, o controle de exibição em árvore envia uma mensagem de notificação TVN_GETDISPINFO, que inclui o endereço de uma estrutura NMTVDISPINFO. A janela pai deve preencher os membros apropriados da estrutura incluída.

Edição de rótulos de exibição em árvore

O usuário pode editar diretamente os rótulos de itens em um controle de exibição em árvore que tem o estilo TVS_EDITLABELS. O usuário começa a edição clicando no rótulo de um item com o foco. Um aplicativo começa a editar usando a mensagem TVM_EDITLABEL. O controle tree-view notifica a janela pai quando a edição começa e quando ela é cancelada ou concluída. Quando a edição for concluída, a janela pai será responsável por atualizar o rótulo do item, se apropriado.

Quando a edição de rótulo começa, um controle de exibição em árvore envia à janela pai uma mensagem de notificação TVN_BEGINLABELEDIT . Ao processar essa notificação, um aplicativo pode permitir a edição de alguns rótulos e impedir a edição de outros. Retornar zero permite a edição, e retornar diferente de zero impede isso.

Quando a edição de rótulo é cancelada ou concluída, um controle de exibição em árvore envia à janela pai uma mensagem de notificação TVN_ENDLABELEDIT . O parâmetro lParam é o endereço de uma estrutura NMTVDISPINFO . O parâmetro item é uma estrutura TVITEM que identifica o item e inclui o texto editado. A janela pai é responsável por atualizar o rótulo do item se desejar manter o novo rótulo. O membro pszText do TVITEM será zero se a edição for cancelada.

Durante a edição de rótulo, normalmente em resposta à mensagem de notificação TVN_BEGINLABELEDIT, você pode recuperar o identificador para o controle de edição usado para edição de rótulo usando a mensagem TVM_GETEDITCONTROL. Você pode enviar ao controle de edição uma mensagem EM_SETLIMITTEXT para limitar a quantidade de texto que um usuário pode inserir ou subclassificar o controle de edição para interceptar e descartar caracteres inválidos. Note, no entanto, que o controle de edição é exibido somente depois que TVN_BEGINLABELEDIT é enviado.

Posição do item de exibição em árvore

A posição inicial de um item é definida quando o item é adicionado ao controle de exibição em árvore usando a mensagem TVM_INSERTITEM. A mensagem inclui uma estrutura TVINSERTSTRUCT que especifica o identificador para o item pai e o identificador para o item após o qual o novo item deve ser inserido. O segundo identificador deve identificar um item filho do pai determinado ou um destes valores: TVI_FIRST, TVI_LAST ou TVI_SORT.

Quando TVI_FIRST ou TVI_LAST é especificado, o controle de exibição em árvore coloca o novo item no início ou no final da lista de itens filho do item pai determinado. Quando TVI_SORT é especificado, o controle de exibição em árvore insere o novo item na lista de itens filho em ordem alfabética com base no texto dos rótulos de item.

Você pode colocar a lista de itens filho de um item pai em ordem alfabética usando a mensagem TVM_SORTCHILDREN . A mensagem inclui um parâmetro que especifica se todos os níveis de itens filho descendentes do item pai específico também são classificados em ordem alfabética.

A mensagem TVM_SORTCHILDRENCB permite classificar itens filho com base em critérios definidos. Ao usar essa mensagem, você especifica uma função de retorno de chamada definida pelo aplicativo que o controle de exibição em árvore pode chamar sempre que a ordem relativa de dois itens filho precisar ser decidida. A função de retorno de chamada recebe dois valores definidos pelo aplicativo de 32 bits para os itens que estão sendo comparados e um terceiro valor de 32 bits que você especifica ao enviar TVM_SORTCHILDRENCB.

Visão geral dos estados de item de exibição em árvore

Cada item em um controle de exibição de árvore tem um estado atual. As informações de estado para cada item incluem um conjunto de sinalizadores de bits, bem como índices de lista de imagens que indicam a imagem de estado e a imagem de sobreposição do item. Os sinalizadores de bits indicam se o item está selecionado, desabilitado, expandido e assim por diante. Na maioria das vezes, um controle de exibição em árvore define automaticamente o estado de um item para refletir as ações do usuário, como a seleção de um item. No entanto, você também pode definir o estado de um item usando a mensagem TVM_SETITEM e pode recuperar o estado atual de um item usando a mensagem TVM_GETITEM. Para obter uma lista completa de estados de item, consulte Estados de item de controle de exibição em árvore.

O estado atual de um item é especificado pelo membro do estado da estrutura TVITEM . Um controle de exibição em árvore pode alterar o estado de um item para refletir uma ação do usuário, como selecionar o item ou definir o foco para o item. Além disso, um aplicativo pode alterar o estado de um item para desabilitar ou ocultar o item ou para especificar uma imagem de sobreposição ou uma imagem de estado.

Quando você especifica ou altera o estado de um item, o membro statemask de TVITEM especifica quais bits de estado devem ser definidos e o membro state contém os novos valores para esses bits.

Para definir a imagem de sobreposição de um item, statemask deve incluir o valor TVIS_OVERLAYMASK e state 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 especificar nenhuma imagem de sobreposição.

Uma imagem de estado é exibida ao lado do ícone de um item para indicar um estado definido pelo aplicativo. As imagens de estado estão contidas em uma lista de imagens de estado especificada pelo envio de uma mensagem 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 do 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 pega um índice e define os bits de 12 a 15 apropriadamente. Para indicar que o item não tem 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 12 a 15 do estado , use a máscara TVIS_STATEIMAGEMASK . Para obter mais informações sobre imagens de sobreposição e estado, consulte Listas de imagens de exibição em árvore.

Seleção de Itens

Um controle de exibição em árvore notifica a janela pai quando a seleção muda de um item para outro enviando as mensagens de notificação TVN_SELCHANGING e TVN_SELCHANGED . Ambas as notificações incluem um valor que especifica se a alteração é o resultado de um clique do mouse ou de uma tecla pressionada. As notificações também incluem informações sobre o item que está ganhando a seleção e o item que está perdendo a seleção. Você pode usar essas informações para definir atributos de item que dependem do estado de seleção do item. Retornar TRUE em resposta a TVN_SELCHANGING impede que a seleção seja alterada, e retornar FALSE permite a alteração.

Um aplicativo pode alterar a seleção enviando a mensagem TVM_SELECTITEM.

Informações do item

Os controles de exibição em árvore oferecem suporte a várias mensagens que recuperam informações sobre itens no controle.

A mensagem TVM_GETITEM pode recuperar o identificador e os atributos de um item. Os atributos de um item incluem seu estado atual, os índices na lista de imagens do controle das imagens bitmap selecionadas e não selecionadas do item, um sinalizador que indica se o item tem itens filho, o endereço da cadeia de caracteres de rótulo do item e o valor de 32 bits definido pelo aplicativo do item.

A mensagem TVM_GETNEXTITEM recupera o item de exibição em árvore que tem a relação especificada com o item atual. A mensagem pode recuperar o pai de um item, o item visível próximo ou anterior, o primeiro item filho e assim por diante.

A mensagem TVM_GETITEMRECT recupera o retângulo delimitador de um item de exibição em árvore. As mensagens TVM_GETCOUNT e TVM_GETVISIBLECOUNT recuperam uma contagem dos itens em um controle de exibição de árvore e uma contagem dos itens que podem ser totalmente visíveis na janela do controle de exibição de árvore, respectivamente. Você pode garantir que um item específico esteja visível usando a mensagem TVM_ENSUREVISIBLE.

Listas de imagens de exibição em árvore

Cada item em um controle de exibição em árvore pode ter quatro imagens bitmap associadas a ele.

• Uma imagem, como uma pasta aberta, é exibida quando o item é selecionado.
• Uma imagem, como uma pasta fechada, é exibida quando o item não está selecionado.
• Uma imagem de sobreposição desenhada de forma transparente sobre a imagem selecionada ou não selecionada.
• Uma imagem de estado, que é uma imagem adicional exibida à esquerda da imagem selecionada ou não selecionada. Você pode usar imagens de estado, como caixas de seleção marcadas e desmarcadas, para indicar estados de item definidos pelo aplicativo.

Por padrão, um controle de exibição em árvore não exibe imagens de item. Para exibir imagens de item, você deve criar listas de imagens e associá-las ao controle. Para obter mais informações sobre listas de imagens, consulte Listas de imagens.

Um controle de exibição em árvore pode ter duas listas de imagens: uma lista de imagens normais e uma lista de imagens de estado. Uma lista de imagens normal armazena as imagens selecionadas, não selecionadas e de sobreposição. Uma lista de imagens de estado armazena imagens de estado. Use a função ImageList_Create para criar uma lista de imagens e use outras funções de lista de imagens para adicionar bitmaps à lista de imagens. Em seguida, para associar a lista de imagens ao controle de exibição em árvore, use a mensagem TVM_SETIMAGELIST. A mensagem TVM_GETIMAGELIST recupera um identificador para uma das listas de imagens de um controle de exibição em árvore. Essa mensagem é útil se você precisar adicionar mais imagens à lista.

Além das imagens selecionadas e não selecionadas, a lista de imagens normais de um controle de exibição em árvore pode conter até quatro imagens de sobreposição. As imagens de sobreposição são identificadas por um índice baseado em um único e são projetadas para serem desenhadas de forma transparente sobre as imagens selecionadas e não selecionadas. Para atribuir um índice de máscara de sobreposição a uma imagem na lista de imagens normais, chame a função ImageList_SetOverlayImage.

Por padrão, todos os itens exibem a primeira imagem na lista de imagens normais para os estados selecionados e não selecionados. Além disso, por padrão, os itens não exibem imagens de sobreposição ou imagens de estado. Você pode alterar esses comportamentos padrão para um item enviando a mensagem TVM_INSERTITEM ou TVM_SETITEM. Essas mensagens usam a estrutura TVITEM para especificar índices de lista de imagens para um item.

Para especificar as imagens selecionadas e não selecionadas de um item, defina os bits TVIF_SELECTEDIMAGE e TVIF_IMAGE no membro da máscara da estrutura TVITEM e especifique índices da lista de imagens normais do controle nos membros iSelectImage e iImage. Como alternativa, você pode especificar o valor I_IMAGECALLBACK em iSelectImage e iImage em vez de especificar índices. Isso faz com que o controle consulte sua janela pai para um índice de lista de imagens sempre que o item está prestes a ser redesenhado. O controle envia a mensagem de notificação TVN_GETDISPINFO para recuperar o índice.

Para associar uma imagem de sobreposição a um item, use a macro INDEXTOOVERLAYMASK para especificar um índice de máscara de sobreposição no membro do estado da estrutura TVITEM do item. Você também deve definir os bits TVIS_OVERLAYMASK no membro stateMask . Os índices de máscara de sobreposição são baseados em um; Um índice de zero indica que nenhuma imagem de sobreposição foi especificada.

As imagens de estado são armazenadas em uma lista de imagens de estado separada e identificadas por seu índice. Para especificar a lista de imagens de estado, envie uma mensagem de TVM_SETIMAGELIST . Ao contrário do controle de exibição de lista, que usa um índice baseado em um para identificar imagens de estado, as imagens de estado de controle de exibição em árvore são identificadas por um índice baseado em zero. No entanto, um índice de zero indica que o item não tem uma imagem de estado. Consequentemente, a imagem zero não pode ser usada como uma imagem de estado. Para obter mais informações sobre estados de item e imagens de estado, consulte Visão geral de estados de item de exibição em árvore.

Operações de arrastar e soltar

Um controle de exibição em árvore notifica a janela pai quando o usuário começa a arrastar um item. A janela pai recebe uma mensagem de notificação TVN_BEGINDRAG quando o usuário começa a arrastar um item com o botão esquerdo do mouse e uma mensagem de notificação TVN_BEGINRDRAG quando o usuário começa a arrastar com o botão direito. Você pode impedir que um controle de exibição em árvore envie essas notificações dando ao controle de exibição em árvore o estilo TVS_DISABLEDRAGDROP.

Você obtém uma imagem para exibir durante uma operação de arrastar usando a mensagem TVM_CREATEDRAGIMAGE. O controle tree-view cria um bitmap de arrastar com base no rótulo do item que está sendo arrastado. Em seguida, o controle de exibição em árvore cria uma lista de imagens, adiciona o bitmap a ela e retorna o identificador para a lista de imagens.

Você deve fornecer o código que realmente arrasta o item. Isso geralmente envolve o uso dos recursos de arrastar das funções de lista de imagens e o processamento das mensagens WM_MOUSEMOVE e WM_LBUTTONUP (ou WM_RBUTTONUP) enviadas para a janela pai após o início da operação de arrastar.

Se os itens em um controle de exibição em árvore forem os destinos das operações de arrastar e soltar, você precisará saber quando o ponteiro do mouse está em um item de destino. Você pode descobrir usando a mensagem TVM_HITTEST. Você especifica o endereço de uma estrutura TVHITTESTINFO que contém as coordenadas atuais do ponteiro do mouse. Quando a função SendMessage retorna, a estrutura contém um sinalizador indicando o local do ponteiro do mouse em relação ao controle de exibição em árvore. Se o ponteiro estiver sobre um item no controle de exibição em árvore, a estrutura também conterá o identificador para o item.

Você pode indicar que um item é o destino de uma operação de arrastar e soltar usando a mensagem TVM_SETITEM para definir o estado para o valor TVIS_DROPHILITED. Um item que tem esse estado é desenhado no estilo usado para indicar um destino do tipo "arrastar e soltar".

Mensagens de notificação de controle de exibição em árvore

Um controle de exibição em árvore envia as seguintes mensagens de notificação para sua janela pai na forma de mensagens WM_NOTIFY.

Processamento de mensagens de controle de exibição em árvore padrão

Esta seção descreve o processamento de mensagens de janela executado por um controle de exibição em árvore. As mensagens específicas para controles de exibição em árvore são discutidas em outras seções deste documento, portanto, não estão incluídas aqui.

Tópicos relacionados

EXEMPLO: CustDTv ilustra o desenho personalizado em um TreeView (Q248496)