Sobre controles de Tree-View

Um controle de exibição de á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 uma etiqueta e uma imagem bitmap opcional, podendo cada item ter uma lista de subitens associados a ele. Clicando em um item, o usuário pode expandir ou recolher a lista associada de subitems.

A ilustração a seguir mostra um controle de exibição de á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 de á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 enviar a mensagem explicitamente.

Estilos de Tree-View

Os estilos de exibição de árvore regem aspectos da aparência de um controle de exibição de árvore. Você define os estilos iniciais ao criar o controle de exibição de árvore. Você pode recuperar e alterar os estilos depois de criar o controle de exibição de á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 de árvore desenhando linhas que vinculam itens filho ao item pai, conforme mostrado na ilustração a seguir.

Por si só, esse estilo não desenha 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 de á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, deverá 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 poderão aparecer desmarcadas, dependendo dos 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 sobre a largura total 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 de itens de exibição de árvore. Para obter mais informações sobre a edição de rótulos, consulte Tree-View Edição de Rótulo.

Para obter mais informações sobre esses e outros estilos, consulte Tree-View estilos de janela de controle.

Itens pai e filho

Qualquer item em um controle de exibição de árvore pode ter uma lista de subitems, chamados de 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 é subordinado ao pai. Um item que não tem pai aparece na parte superior da hierarquia e é chamado de item raiz.

Para adicionar um item a um controle de exibição de á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 expandidos e recolhidos 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 de á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 de á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 de árvore usa a memória alocada do heap do processo que cria o controle de exibição de á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.

Rótulos de item

Normalmente, você especifica o texto do rótulo de um item ao adicionar o item ao controle de exibição de á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 de árvore aloca memória para armazenar cada item; o texto dos rótulos de item ocupa uma parte significativa dessa memória. Se o aplicativo mantiver uma cópia das cadeias de caracteres no controle de exibição de árvore, você poderá diminuir os requisitos de memória do controle especificando o valor LPSTR_TEXTCALLBACK no membro pszText do TVITEM em vez de passar cadeias de caracteres reais para o modo de exibição de árvore. Usar LPSTR_TEXTCALLBACK faz com que o controle de exibição de á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 de á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ótulo Tree-View

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

Quando a edição de rótulos começa, um controle de exibição de á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 sem zero o impede.

Quando a edição de rótulo é cancelada ou concluída, um controle de exibição de á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 de 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 quiser manter o novo rótulo. O membro pszText de 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 subclasse o controle de edição para interceptar e descartar caracteres inválidos. No entanto, observe que o controle de edição é exibido somente depois que TVN_BEGINLABELEDIT é enviado.

Posição do item Tree-View

A posição inicial de um item é definida quando o item é adicionado ao controle de exibição de á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 de árvore coloca o novo item no início ou no final da lista de itens filho do item pai especificado. Quando TVI_SORT é especificado, o controle de exibição de á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 decrescentes do item pai determinado também são classificados em ordem alfabética.

A mensagem TVM_SORTCHILDRENCB permite que você classifique itens filho com base nos 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 de á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 Tree-View

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 do item e a imagem de sobreposição. 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 de á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 recuperar o estado atual de um item usando a mensagem TVM_GETITEM . Para obter uma lista completa de estados de item, consulte Tree-View estados de item de controle.

O estado atual de um item é especificado pelo membro de estado da estrutura TVITEM . Um controle de exibição de á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 especificar uma imagem de sobreposição ou imagem de estado.

Quando você especifica ou altera o estado de um item, o membro de máscara de estado do TVITEM especifica quais bits de estado definir e o membro de estado contém os novos valores para esses bits.

Para definir a imagem de sobreposição de um item, a máscara de estado deve incluir o valor TVIS_OVERLAYMASK e o estado deve incluir o índice baseado em um da imagem de sobreposição deslocado para a esquerda de 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 enviando uma mensagem TVM_SETIMAGELIST . Para definir a imagem de estado de um item, inclua o valor TVIS_STATEIMAGEMASK no membro de máscara de estado 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 . Para obter mais informações sobre sobreposição e imagens de estado, consulte Tree-View Listas de Imagens.

Seleção de Item

Um controle de exibição de á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 um pressionamento de tecla. 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 de árvore dão 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 de bitmapped 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 de árvore que tem a relação especificada com o item atual. A mensagem pode recuperar o pai de um item, o item visível seguinte ou anterior, o primeiro item filho e assim por diante.

A mensagem TVM_GETITEMRECT recupera o retângulo delimitador para um item de exibição de á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 do Tree-View

Cada item em um controle de exibição de árvore pode ter quatro imagens bitmapped 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 que é 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 de á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 de árvore pode ter duas listas de imagens: uma lista de imagens normal e uma lista de imagens de estado. Uma lista de imagens normal armazena as imagens selecionadas, não selecionadas e sobrepostas. Uma lista de imagens de estado armazena imagens de estado. Use a função ImageList_Create para criar uma lista de imagens e usar 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 de á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 de árvore. Essa mensagem será ú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 de árvore pode conter até quatro imagens de sobreposição. As imagens de sobreposição são identificadas por um índice baseado em um e foram 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 normal, chame a função ImageList_SetOverlayImage .

Por padrão, todos os itens exibem a primeira imagem na lista de imagens normal 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 em busca de um índice de lista de imagens sempre que o item estiver 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 de 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 pelo índice. Para especificar a lista de imagens de estado, envie uma mensagem 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 do controle de exibição de á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 discussões sobre estados de item e imagens de estado, consulte Tree-View Visão geral dos Estados de Item.

Operações de arrastar e soltar

Um controle de exibição de á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 de árvore envie essas notificações fornecendo ao controle de exibição de árvore o estilo TVS_DISABLEDRAGDROP .

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

Você deve fornecer o código que realmente arrasta o item. Isso normalmente 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 de á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 . Especifique 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 que indica o local do ponteiro do mouse em relação ao controle de exibição de árvore. Se o ponteiro estiver sobre um item no controle de exibição de árvore, a estrutura também conterá o identificador do 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 como o valor TVIS_DROPHILITED . Um item que tem esse estado é desenhado no estilo usado para indicar um destino do tipo "arrastar e soltar".

Tree-View controlar mensagens de notificação

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

Processamento de mensagens de controle de Tree-View padrão

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