Classe `CTreeCtrl`

Artigo
10/12/2023

Fornece a funcionalidade do controle de exibição de árvore comum do Windows.

Sintaxe

class CTreeCtrl : public CWnd

Membros

Construtores públicos

Nome	Descrição
`CTreeCtrl::CTreeCtrl`	Constrói um objeto `CTreeCtrl`.

Métodos públicos

Nome	Descrição
`CTreeCtrl::Create`	Cria um controle de exibição de árvore e o anexa a um objeto `CTreeCtrl`.
`CTreeCtrl::CreateDragImage`	Cria um bitmap de arrastar para o item de exibição de árvore especificado.
`CTreeCtrl::CreateEx`	Cria um controle de árvore com os estilos estendidos especificados do Windows e o anexa a um objeto `CTreeCtrl`.
`CTreeCtrl::DeleteAllItems`	Exclui todos os itens em um controle de exibição de árvore.
`CTreeCtrl::DeleteItem`	Exclui um novo item em um controle de exibição de árvore.
`CTreeCtrl::EditLabel`	Edita um item de exibição de árvore especificado no local.
`CTreeCtrl::EndEditLabelNow`	Cancela a operação de edição no rótulo de um item de exibição de árvore no controle de exibição de árvore atual.
`CTreeCtrl::EnsureVisible`	Garante que um item de exibição de árvore esteja visível em seu controle de exibição de árvore.
`CTreeCtrl::Expand`	Expande ou recolhe os itens filho do item de exibição de árvore especificado.
`CTreeCtrl::GetBkColor`	Recupera a cor da tela de fundo atual do controle.
`CTreeCtrl::GetCheck`	Recupera o estado de verificação de um item de controle de árvore.
`CTreeCtrl::GetChildItem`	Recupera o filho de um item de exibição de árvore especificado.
`CTreeCtrl::GetCount`	Recupera o número de itens de árvore associados a um controle de exibição de árvore.
`CTreeCtrl::GetDropHilightItem`	Recupera o destino de uma operação de arrastar e soltar.
`CTreeCtrl::GetEditControl`	Recupera o identificador do controle de edição usado para editar o item de exibição de árvore especificado.
`CTreeCtrl::GetExtendedStyle`	Recupera os estilos estendidos que o controle de exibição de árvore atual está usando.
`CTreeCtrl::GetFirstVisibleItem`	Recupera o primeiro item visível do item de exibição de árvore especificado.
`CTreeCtrl::GetImageList`	Recupera o identificador da lista de imagens associado a um controle de exibição de árvore.
`CTreeCtrl::GetIndent`	Recupera o deslocamento (em pixels) de um item de exibição de árvore a partir do item pai.
`CTreeCtrl::GetInsertMarkColor`	Recupera a cor usada para desenhar a marca de inserção para o modo de exibição de árvore.
`CTreeCtrl::GetItem`	Recupera os atributos de um item de exibição de árvore especificado.
`CTreeCtrl::GetItemData`	Retorna o valor específico do aplicativo associado a um item.
`CTreeCtrl::GetItemExpandedImageIndex`	Recupera o índice da imagem a ser exibido quando o item especificado do controle de exibição de árvore atual estiver no estado expandido.
`CTreeCtrl::GetItemHeight`	Recupera a altura atual dos itens de exibição de árvore.
`CTreeCtrl::GetItemImage`	Recupera as imagens associadas a um item.
`CTreeCtrl::GetItemPartRect`	Recupera o retângulo delimitador para uma parte especificada de um item especificado no controle de exibição de árvore atual.
`CTreeCtrl::GetItemRect`	Recupera o retângulo delimitador de um item de exibição de árvore.
`CTreeCtrl::GetItemState`	Retorna o estado de um item.
`CTreeCtrl::GetItemStateEx`	Recupera o estado estendido do item especificado no controle de exibição de árvore atual.
`CTreeCtrl::GetItemText`	Retorna o texto de um item.
`CTreeCtrl::GetLastVisibleItem`	Recupera o último item expandido no controle de exibição de árvore atual.
`CTreeCtrl::GetLineColor`	Recupera a cor da linha atual para o controle de exibição de árvore.
`CTreeCtrl::GetNextItem`	Recupera o próximo item de exibição de árvore que corresponde a uma relação especificada.
`CTreeCtrl::GetNextSiblingItem`	Recupera o próximo irmão do item de exibição de árvore especificado.
`CTreeCtrl::GetNextVisibleItem`	Recupera o próximo item visível do item de exibição de árvore especificado.
`CTreeCtrl::GetParentItem`	Recupera o pai do item de exibição de árvore especificado.
`CTreeCtrl::GetPrevSiblingItem`	Recupera o irmão anterior do item de exibição de árvore especificado.
`CTreeCtrl::GetPrevVisibleItem`	Recupera o item visível anterior do item de exibição de árvore especificado.
`CTreeCtrl::GetRootItem`	Recupera a raiz do item de exibição de árvore especificado.
`CTreeCtrl::GetScrollTime`	Recupera o tempo máximo de rolagem para o controle de exibição de árvore.
`CTreeCtrl::GetSelectedCount`	Recupera o número de itens selecionados no controle de exibição de árvore atual.
`CTreeCtrl::GetSelectedItem`	Recupera o item de exibição de árvore selecionado no momento.
`CTreeCtrl::GetTextColor`	Recupera a cor do texto atual do controle.
`CTreeCtrl::GetToolTips`	Recupera o identificador para o controle filho `ToolTip` usado por um controle de exibição de árvore.
`CTreeCtrl::GetVisibleCount`	Recupera o número de itens de árvore visíveis associados a um controle de exibição de árvore.
`CTreeCtrl::HitTest`	Retorna a posição atual do cursor relacionada ao objeto `CTreeCtrl`.
`CTreeCtrl::InsertItem`	Insere um novo item em um controle de exibição de árvore.
`CTreeCtrl::ItemHasChildren`	Retorna não zero se o item especificado tiver itens filho.
`CTreeCtrl::MapAccIdToItem`	Mapeia o identificador de acessibilidade especificado para o identificador para um item de exibição de árvore no controle de exibição de árvore atual.
`CTreeCtrl::MapItemToAccID`	Mapeia o identificador especificado para um item de exibição de árvore no controle de exibição de árvore atual para um identificador de acessibilidade.
`CTreeCtrl::Select`	Seleciona, rola para a exibição ou redesenha um item de exibição de árvore especificado.
`CTreeCtrl::SelectDropTarget`	Redesenhe o item de árvore como destino de uma operação de arrastar e soltar.
`CTreeCtrl::SelectItem`	Seleciona um item de exibição de árvore especificado.
`CTreeCtrl::SelectSetFirstVisible`	Seleciona um item de exibição de árvore especificado como o primeiro item visível.
`CTreeCtrl::SetAutoscrollInfo`	Define a taxa de registro automático do controle de exibição de árvore atual.
`CTreeCtrl::SetBkColor`	Define a cor da tela de fundo do controle.
`CTreeCtrl::SetCheck`	Define o estado de verificação de um item de controle de árvore.
`CTreeCtrl::SetExtendedStyle`	Define os estilos estendidos para o controle de exibição de árvore atual.
`CTreeCtrl::SetImageList`	Define o identificador da lista de imagens associado a um controle de exibição de árvore.
`CTreeCtrl::SetIndent`	Define o deslocamento (em pixels) de um item de exibição de árvore de seu pai.
`CTreeCtrl::SetInsertMark`	Define a marca de inserção em um controle de exibição de árvore.
`CTreeCtrl::SetInsertMarkColor`	Define a cor usada para desenhar a marca de inserção para o modo de exibição de árvore.
`CTreeCtrl::SetItem`	Define os atributos de um item de exibição de árvore especificado.
`CTreeCtrl::SetItemData`	Define o valor específico do aplicativo associado a um item.
`CTreeCtrl::SetItemExpandedImageIndex`	Define o índice da imagem a ser exibido quando o item especificado do controle de exibição de árvore atual estiver no estado expandido.
`CTreeCtrl::SetItemHeight`	Define a altura dos itens de exibição de árvore.
`CTreeCtrl::SetItemImage`	Associa imagens a um item.
`CTreeCtrl::SetItemState`	Define o estado de um item.
`CTreeCtrl::SetItemStateEx`	Define o estado estendido do item especificado no controle de exibição de árvore atual.
`CTreeCtrl::SetItemText`	Define o texto de um item.
`CTreeCtrl::SetLineColor`	Define a cor da linha atual para o controle de exibição de árvore.
`CTreeCtrl::SetScrollTime`	Define o tempo máximo de rolagem para o controle de exibição de árvore.
`CTreeCtrl::SetTextColor`	Define a cor do texto do controle.
`CTreeCtrl::SetToolTips`	Define o controle filho `ToolTip` de um controle de exibição de árvore.
`CTreeCtrl::ShowInfoTip`	Exibe a dica de informações do item especificado no controle de exibição de árvore atual.
`CTreeCtrl::SortChildren`	Classifica os filhos de um determinado item pai.
`CTreeCtrl::SortChildrenCB`	Classifica os filhos de um determinado item pai usando uma função de classificação definida pelo aplicativo.

Comentários

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 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 e recolher a lista associada de subitems.

Esse controle (e, portanto, a classe CTreeCtrl) está disponível somente para programas em execução no Windows 98 e no Windows NT versão 4 e posteriores.

Para obter mais informações sobre como usar CTreeCtrl, confira:

Controles
Usando CTreeCtrl
Referência de controle de exibição de árvore no SDK do Windows.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CTreeCtrl

Requisitos

Cabeçalhoafxcmn.h:

`CTreeCtrl::Create`

Se você especificar o controle de árvore em um modelo de caixa de diálogo ou se estiver usando CTreeView, o controle de árvore será criado automaticamente quando a caixa de diálogo ou exibição for criada.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parâmetros

dwStyle
Especifica o estilo do controle de exibição de árvore. Aplique estilos de janela, descritos em CreateWindow e qualquer combinação de estilos de controle de exibição de árvore, conforme descrito no SDK do Windows.

rect
Especifica o tamanho e a posição do controle de exibição de árvore. Pode ser um objeto CRect ou uma estrutura RECT.

pParentWnd
Especifica a janela pai do controle de exibição de árvore, geralmente um CDialog. Não deve ser NULL.

nID
Especifica a ID do controle de exibição de árvore.

Valor de Devolução

Um valor diferente de zero, se a inicialização tiver êxito. Caso contrário, 0.

Comentários

Se você quiser criar o controle de árvore como uma janela filho de alguma outra janela, use a função membro Create. Se você criar o controle de árvore usando Create, deverá passá-lo WS_VISIBLE, além de outros estilos de exibição de árvore.

O CTreeCtrl é construído em duas etapas. Primeiro chame o construtor e, em seguida, chame Create, que cria o controle de exibição de árvore e o anexa ao objeto CTreeCtrl.

Para criar um controle de árvore com estilos de janela estendidos, chame CreateEx em vez de Create.

Exemplo

// Assuming your window has a CTreeCtrl member named m_TreeCtrl,
// you can create the tree control window with a child ID of ID_MYTREE
// using a call like this:

m_TreeCtrl.Create(WS_VISIBLE | WS_TABSTOP | WS_CHILD | WS_BORDER |
                      TVS_HASBUTTONS | TVS_LINESATROOT | TVS_HASLINES |
                      TVS_DISABLEDRAGDROP | TVS_NOTOOLTIPS | TVS_EDITLABELS,
                  CRect(10, 10, 300, 100), this, ID_MYTREE);

// The control will have the appropriate window styles, and the tree
// control styles specified are those most commonly used.

`CTreeCtrl::CreateEx`

Chame essa função para criar um controle (uma janela filho) e associá-lo ao objeto CTreeCtrl.

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parâmetros

dwExStyle
Especifica o estilo estendido do controle que está sendo criado. Para obter uma lista de estilos estendidos do Windows, consulte o parâmetro dwExStyle para CreateWindowEx no SDK do Windows.

rect
Uma referência a uma estrutura RECT que descreve o tamanho e a posição da janela a ser criada, nas coordenadas de cliente de pParentWnd.

pParentWnd
Um ponteiro para a janela que é pai do controle.

nID
A ID da janela filho do controle.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Use CreateEx, em vez de Create, para aplicar estilos estendidos do Windows, especificados pelo prefácio WS_EX_ de estilos estendidos do Windows.

`CTreeCtrl::CreateDragImage`

Chame essa função para criar um bitmap de arrastar para o item especificado em um controle de exibição de árvore, criar uma lista de imagens para o bitmap e adicionar o bitmap à lista de imagens.

CImageList* CreateDragImage(HTREEITEM hItem);

Parâmetros

hItem
Identificador do item de árvore a ser arrastado.

Valor de Devolução

Ponteiro para a lista de imagens à qual o bitmap de arrastar foi adicionado, se bem-sucedido; caso contrário NULL.

Comentários

Um aplicativo usa as funções de lista de imagens para exibir a imagem quando o item está sendo arrastado.

O objeto CImageList é permanente e você deve excluí-lo quando terminar. Por exemplo:

HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();

CImageList *pImageList = m_TreeCtrl.CreateDragImage(hItem);

// Do something with the image list.

delete pImageList;

`CTreeCtrl::CTreeCtrl`

Constrói um objeto CTreeCtrl.

CTreeCtrl();

`CTreeCtrl::DeleteAllItems`

Chame essa função para excluir todos os itens do controle de exibição de árvore.

BOOL DeleteAllItems();

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

// The underlying Windows API always returns TRUE
VERIFY(m_TreeCtrl.DeleteAllItems());

`CTreeCtrl::DeleteItem`

Chame essa função para excluir um item do controle de exibição de árvore.

BOOL DeleteItem(HTREEITEM hItem);

Parâmetros

hItem
Identificador do item de árvore a ser excluído. Se hitem tiver o valor TVI_ROOT, todos os itens serão excluídos do controle de exibição de árvore.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

// Look at all of the root-level items
HTREEITEM hCurrent = m_TreeCtrl.GetChildItem(TVI_ROOT);
while (hCurrent != NULL)
{
   // Get the text for the item. Notice we use TVIF_TEXT because
   // we want to retrieve only the text, but also specify TVIF_HANDLE
   // because we're getting the item by its handle.
   TVITEM item;
   TCHAR szText[1024];
   item.hItem = hCurrent;
   item.mask = TVIF_TEXT | TVIF_HANDLE;
   item.pszText = szText;
   item.cchTextMax = 1024;

   BOOL bWorked = m_TreeCtrl.GetItem(&item);

   // Try to get the next item
   hCurrent = m_TreeCtrl.GetNextItem(hCurrent, TVGN_NEXT);

   // If we successfuly retrieved an item, and the item's text
   // contains a lowercase letter 'e', delete the item.
   if (bWorked && _tcschr(item.pszText, 'e'))
      m_TreeCtrl.DeleteItem(item.hItem);
}

`CTreeCtrl::EditLabel`

Chame essa função para iniciar a edição in-loco do texto do item especificado.

CEdit* EditLabel(HTREEITEM hItem);

Parâmetros

hItem
Identificador do item de árvore a ser editado.

Valor de Devolução

Se tiver êxito, um ponteiro para o objeto CEdit usado para editar o texto do item; caso contrário, NULL.

Comentários

A edição é realizada substituindo o texto do item por um controle de edição de linha única que contém o texto.

Exemplo

// Make sure the focus is set to the tree control.
m_TreeCtrl.SetFocus();

// Show the edit control on the label of the selected item.
// The tree control must have the TVS_EDITLABELS style set.
HTREEITEM hSel = m_TreeCtrl.GetSelectedItem();
CEdit *pmyEdit = m_TreeCtrl.EditLabel(hSel);
ASSERT(pmyEdit != NULL);

`CTreeCtrl::EndEditLabelNow`

Conclui a operação de edição no rótulo de um item de exibição de árvore no controle de exibição de árvore atual.

BOOL EndEditLabelNow(BOOL fCancelWithoutSave);

Parâmetros

fCancelWithoutSave
[in] TRUE para descartar alterações no item de exibição de árvore antes de concluir a operação de edição ou FALSE para salvar alterações no item de exibição de árvore antes de concluir a operação.

Valor de Devolução

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Esse método envia a mensagem TVM_ENDEDITLABELNOW, que é descrita no SDK do Windows.

`CTreeCtrl::EnsureVisible`

Chame essa função para garantir que um item de exibição de árvore esteja visível.

BOOL EnsureVisible(HTREEITEM hItem);

Parâmetros

hItem
Identificador do item de árvore que está sendo tornado visível.

Valor de Devolução

Retorna TRUE se o sistema tiver rolado os itens no controle de exibição de árvore para garantir que o item especificado esteja visível. Caso contrário, o valor retornado será FALSE.

Comentários

Se necessário, a função expande o item pai ou rola o controle de exibição de árvore para que o item fique visível.

Exemplo

HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();
// hmyItem is the item that I want to ensure is visible.
HTREEITEM hmyItem = m_TreeCtrl.GetChildItem(hItem);

// Expand the parent, if possible.
HTREEITEM hParent = m_TreeCtrl.GetParentItem(hmyItem);
if (hParent != NULL)
   m_TreeCtrl.Expand(hParent, TVE_EXPAND);

// Ensure the item is visible.
m_TreeCtrl.EnsureVisible(hmyItem);

`CTreeCtrl::Expand`

Chame essa função para expandir ou recolher a lista de itens filho, se houver, associados ao item pai especificado.

BOOL Expand(
    HTREEITEM hItem,
    UINT nCode);

Parâmetros

hItem
Identificador do item de árvore que está sendo expandido.

nCode
Um sinalizador que indica o tipo de ação a ser executada. Esse sinalizador pode ter um dos seguintes valores:

TVE_COLLAPSE Recolhe a lista.
TVE_COLLAPSERESETRecolhe a lista e remove os itens filho. O sinalizador de estado TVIS_EXPANDEDONCE é redefinido. Esse sinalizador deve ser usado com o sinalizador TVE_COLLAPSE.
TVE_EXPAND Expande a lista.
TVE_TOGGLE Recolherá a lista se ela for expandida ou expandi-la no momento se ela for recolhida no momento.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

Confira o exemplo de CTreeCtrl::EnsureVisible.

`CTreeCtrl::GetBkColor`

Essa função membro implementa o comportamento da mensagem TVM_GETBKCOLOR do Win32, conforme descrito no SDK do Windows.

COLORREF GetBkColor() const;

Valor de Devolução

Um valor COLORREF que representa a cor da tela de fundo da janela atual para o controle. Se esse valor for -1, o controle usará a cor da janela do sistema. Nesse caso, você pode usar ::GetSysColor(COLOR_WINDOW) para obter a cor atual do sistema que o controle está usando.

Exemplo

Confira o exemplo de CTreeCtrl::SetTextColor.

`CTreeCtrl::GetCheck`

Chame essa função de membro para recuperar o estado de verificação de um item.

BOOL GetCheck(HTREEITEM hItem) const;

Parâmetros

hItem
Sobre HTREEITEM, que recebe as informações de estado.

Valor de Devolução

Não zero se o item de controle de árvore estiver marcado; caso contrário, 0.

Exemplo

Confira o exemplo de CTreeCtrl::SetCheck.

`CTreeCtrl::GetChildItem`

Chame essa função para recuperar o item de exibição de árvore que é o filho do item especificado por hItem.

HTREEITEM GetChildItem(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

O identificador do item filho, se tiver êxito; caso contrário NULL.

Exemplo

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Delete all of the children of hmyItem.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hNextItem;
   HTREEITEM hChildItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hChildItem != NULL)
   {
      hNextItem = m_TreeCtrl.GetNextItem(hChildItem, TVGN_NEXT);
      m_TreeCtrl.DeleteItem(hChildItem);
      hChildItem = hNextItem;
   }
}

`CTreeCtrl::GetCount`

Chame essa função para recuperar uma contagem dos itens em um controle de exibição de árvore.

UINT GetCount() const;

Valor de Devolução

O número de itens no controle de exibição de árvore.

Exemplo

// Delete all of the items from the tree control.
m_TreeCtrl.DeleteAllItems();
ASSERT(m_TreeCtrl.GetCount() == 0);

`CTreeCtrl::GetDropHilightItem`

Chame essa função para recuperar o item que é o destino de uma operação de arrastar e soltar.

HTREEITEM GetDropHilightItem() const;

Valor de Devolução

O identificador do item removido se tiver êxito; caso contrário NULL.

Exemplo

// Set the item at the point myPoint as the drop target.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectDropTarget(hItem);
   ASSERT(m_TreeCtrl.GetDropHilightItem() == hItem);
}

`CTreeCtrl::GetEditControl`

Chame essa função para recuperar o identificador do controle de edição que está sendo usado para editar o texto de um item de exibição de árvore.

CEdit* GetEditControl() const;

Valor de Devolução

Um ponteiro para o controle de edição usado para editar o texto do item, se bem-sucedido; caso contrário NULL.

Exemplo

// The string replacing the text in the edit control.
LPCTSTR lpszmyString = _T("New text!");

// Replace the text in the label edit control, if possible.
CEdit *pEdit = m_TreeCtrl.GetEditControl();

if (pEdit != NULL)
{
   pEdit->SetWindowText(lpszmyString);
}

`CTreeCtrl::GetExtendedStyle`

Recupera os estilos estendidos que o controle de exibição de árvore atual está usando.

DWORD GetExtendedStyle() const;

Valor de Devolução

Um valor que contém uma combinação bit a bit (OR) dos estilos estendidos do controle de exibição de árvore atual. Para obter mais informações, consulte Estilos Estendidos de Controle de Exibição de Árvore.

Comentários

Esse método envia a mensagem TVM_GETEXTENDEDSTYLE, que é descrita no SDK do Windows.

`CTreeCtrl::GetFirstVisibleItem`

Chame essa função para recuperar o primeiro item visível do controle de exibição de árvore.

HTREEITEM GetFirstVisibleItem() const;

Valor de Devolução

O identificador do primeiro item visível; caso contrário NULL.

Exemplo

Confira o exemplo de CTreeCtrl::SetCheck.

`CTreeCtrl::GetImageList`

Chame essa função para recuperar o identificador da lista de imagens normal ou de estado associada ao controle de exibição de árvore.

CImageList* GetImageList(UINT nImageList) const;

Parâmetros

nImageList
Tipo de lista de imagens a recuperar. A lista de imagens pode ter um dos seguintes valores:

TVSIL_NORMAL Recupera a lista de imagens normal, que contém as imagens selecionadas e não selecionadas para o item de exibição de árvore.
TVSIL_STATE Recupera a lista de imagens de estado, que contém as imagens para itens de exibição de árvore que estão em um estado definido pelo usuário.

Valor de Devolução

Ponteiro para a lista de imagens do controle se tiver êxito; caso contrário NULL.

Comentários

Cada item em um controle de exibição de árvore pode ter um par de imagens bitmapped associadas a ele. Uma imagem é exibida quando o item é selecionado e a outra é exibida quando o item não está selecionado. Por exemplo, um item pode exibir uma pasta aberta quando estiver selecionada e uma pasta fechada quando não estiver selecionada.

Para obter mais informações sobre listas de imagens, consulte a classe CImageList.

Exemplo

ASSERT(m_TreeCtrl.GetImageList(TVSIL_NORMAL) == NULL);

m_TreeCtrl.SetImageList(&m_TreeImages, TVSIL_NORMAL);
ASSERT(m_TreeCtrl.GetImageList(TVSIL_NORMAL) == &m_TreeImages);

`CTreeCtrl::GetIndent`

Chame essa função para recuperar a quantidade, em pixels, de que os itens filho são recuados em relação aos itens pai.

UINT GetIndent() const;

Valor de Devolução

A quantidade de recuo medida em pixels.

Exemplo

// Double the indent.
UINT uIndent = m_TreeCtrl.GetIndent();
m_TreeCtrl.SetIndent(2 * uIndent);

`CTreeCtrl::GetInsertMarkColor`

Essa função membro implementa o comportamento da mensagem TVM_GETINSERTMARKCOLOR do Win32, conforme descrito no SDK do Windows.

COLORREF GetInsertMarkColor() const;

Valor de Devolução

Um valor COLORREF que contém a cor da marca de inserção atual.

Exemplo

// Use the highliight color for the insert mark color.
COLORREF crColor = ::GetSysColor(COLOR_HIGHLIGHT);
m_TreeCtrl.SetInsertMarkColor(crColor);
ASSERT(m_TreeCtrl.GetInsertMarkColor() == crColor);

`CTreeCtrl::GetItem`

Chame essa função para recuperar os atributos do item de exibição de árvore especificado.

BOOL GetItem(TVITEM* pItem) const;

Parâmetros

pItem
Um ponteiro para uma estrutura TVITEM, conforme descrito no SDK do Windows.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

Confira o exemplo de CTreeCtrl::DeleteItem.

`CTreeCtrl::GetItemData`

Chame essa função para recuperar o valor específico do aplicativo associado ao item especificado.

DWORD_PTR GetItemData(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador do item de lista cujos dados devem ser recuperados.

Valor de Devolução

Um valor específico do aplicativo do tamanho do ponteiro associado ao item especificado por hItem.

Exemplo

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Delete all of the children of hmyItem whose item data is
// not equal to zero.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hNextItem;
   HTREEITEM hChildItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hChildItem != NULL)
   {
      hNextItem = m_TreeCtrl.GetNextItem(hChildItem, TVGN_NEXT);

      if (m_TreeCtrl.GetItemData(hChildItem) != 0)
      {
         m_TreeCtrl.DeleteItem(hChildItem);
      }

      hChildItem = hNextItem;
   }
}

`CTreeCtrl::GetItemExpandedImageIndex`

Recupera o índice da imagem a ser exibido quando o item especificado do controle de exibição de árvore atual estiver no estado expandido.

int GetItemExpandedImageIndex(HTREEITEM hItem)const;

Parâmetros

hItem
[in] Manipule para um item de controle de exibição de árvore.

Valor de Devolução

O índice da imagem a ser exibido quando o item especificado estiver no estado expandido.

Comentários

Esse método envia a mensagem TVM_GETITEM, que é descrita no SDK do Windows. Essa mensagem retorna a estrutura TVITEMEX que descreve o item de controle de exibição de árvore e, em seguida, esse método recupera o membro iExpandedImage dessa estrutura.

`CTreeCtrl::GetItemHeight`

Essa função membro implementa o comportamento da mensagem TVM_GETITEMHEIGHT do Win32, conforme descrito no SDK do Windows.

SHORT GetItemHeight() const;

Valor de Devolução

Obtém a altura do item, em pixels.

Exemplo

// Double the height of the items.
SHORT sHeight = m_TreeCtrl.GetItemHeight();
m_TreeCtrl.SetItemHeight(2 * sHeight);

`CTreeCtrl::GetItemImage`

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

BOOL GetItemImage(
    HTREEITEM hItem,
    int& nImage,
    int& nSelectedImage) const;

Parâmetros

hItem
O identificador do item cujos dados devem ser recuperados.

nImage
Um inteiro que recebe o índice da imagem do item na lista de imagens do controle de exibição de árvore.

nSelectedImage
Um inteiro que recebe o índice da imagem selecionada do item na lista de imagens do controle de exibição de árvore.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

As imagens aparecem no lado esquerdo do rótulo de um item. Uma imagem é exibida quando o item é selecionado e a outra é exibida quando o item não está selecionado. Por exemplo, um item pode exibir uma pasta aberta quando estiver selecionada e uma pasta fechada quando não estiver selecionada.

Chame essa função para recuperar o índice da imagem do item e sua imagem selecionada na lista de imagens do controle de exibição de árvore.

Exemplo

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// If the selected image is the same as the nonselected image
// then make the selected image one more than the nonselected image.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hItem = m_TreeCtrl.GetChildItem(hmyItem);
   int nImage, nSelectedImage;

   while (hItem != NULL)
   {
      m_TreeCtrl.GetItemImage(hItem, nImage, nSelectedImage);

      if (nImage == nSelectedImage)
      {
         m_TreeCtrl.SetItemImage(hItem, nImage, nImage + 1);
      }

      hItem = m_TreeCtrl.GetNextSiblingItem(hItem);
   }
}

`CTreeCtrl::GetItemPartRect`

Recupera o retângulo delimitador para uma parte especificada de um item especificado no controle de exibição de árvore atual.

BOOL GetItemPartRect(
    HTREEITEM hItem,
    int nPart,
    LPRECT lpRect)const;

Parâmetros

hItem
[in] Manipule para um item de controle de exibição de árvore.

nPart
[in] Identificador da parte. Deve ser definido como TVGIPR_BUTTON.

lpRect
[out] Ponteiro para uma estrutura RECT. Se esse método for bem-sucedido, a estrutura receberá as coordenadas do retângulo da parte especificada por hItem e nPart.

Valor de Devolução

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Cada item de controle de árvore é limitado por um retângulo gráfico. Sempre que um ponto nesse retângulo é clicado, diz-se que o item é atingido. Esse método retorna o maior retângulo de modo que, quando um ponto no retângulo é clicado, o item identificado pelo parâmetro hItem é atingido.

Esse método envia a mensagem TVM_GETITEMPARTRECT, que é descrita no SDK do Windows. Para obter mais informações, consulte a macro TreeView_GetItemPartRect.

Exemplo

O primeiro exemplo de código define uma variável m_treeCtrl, que é usada para acessar o controle de exibição de árvore atual. O exemplo de código também define um inteiro sem sinal e HTREEITEM variáveis. Essas variáveis são usadas no próximo exemplo.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

O próximo exemplo de código usa um identificador de acessibilidade e o método CTreeCtrl::MapAccIdToItem para recuperar um identificador para o item de exibição de árvore raiz. Em seguida, o exemplo usa o identificador e o método CTreeCtrl::GetItemPartRect para desenhar um retângulo 3D em torno desse item. Em uma seção anterior do exemplo de código, que não é mostrada, criamos uma exibição de árvore que consiste em um nó de país/região raiz para o Estados Unidos, subnós para os estados da Pensilvânia e Washington e itens de árvore para cidades nesses estados. Usamos o método CTreeCtrl::MapItemToAccID para associar o item de exibição de árvore raiz a um identificador de acessibilidade.

CRect rect;
HTREEITEM hUS = m_treeCtrl.MapAccIdToItem(accIdUS);
m_treeCtrl.GetItemPartRect(hUS, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

`CTreeCtrl::GetItemRect`

Chame essa função para recuperar o retângulo delimitador para hItem e determinar se ele está visível ou não.

BOOL GetItemRect(
    HTREEITEM hItem,
    LPRECT lpRect,
    BOOL bTextOnly) const;

Parâmetros

hItem
O identificador de um item de controle de exibição de árvore.

lpRect
Ponteiro de uma estrutura RECT que recebe o retângulo delimitador. As coordenadas são relativas ao canto superior esquerdo do controle de exibição de árvore.

bTextOnly
Se esse parâmetro não for zero, o retângulo delimitador incluirá apenas o texto do item. Caso contrário, ele inclui a linha inteira que o item ocupa no controle de exibição de árvore.

Valor de Devolução

Não zero se o item estiver visível, com o retângulo delimitador contido em lpRect. Caso contrário, 0 com lpRect não inicializado.

Exemplo

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Dump the bounds of hmyItem.
if (hmyItem != NULL)
{
   RECT r;

   m_TreeCtrl.GetItemRect(hmyItem, &r, FALSE);

   TRACE(TEXT("left = %d, top = %d, right = %d, bottom = %d\r\n"),
         r.left,
         r.top,
         r.right,
         r.bottom);
}

`CTreeCtrl::GetItemState`

Retorna o estado do item especificado por hItem.

UINT GetItemState(
    HTREEITEM hItem,
    UINT nStateMask) const;

Parâmetros

hItem
Identificador do item cujo estado deve ser recuperado.

nStateMask
Máscara indicando um ou mais estados a serem recuperados. Para obter mais informações sobre valores possíveisnStateMask, consulte a discussão entre os membros e state os stateMask membros da estrutura TVITEM no SDK do Windows.

Valor de Devolução

Um UINT que contém o operador OR bit a bit C++ (|) dos valores especificados por nStateMask. Para obter informações sobre valores possíveis, consulte CTreeCtrl::GetItem. Para localizar o valor de um estado específico, execute um operador AND bit a bit C++ (&) f o valor de estado e o valor retornado, conforme mostrado no exemplo a seguir.

Exemplo

// Show all of the visible items in bold.
HTREEITEM hItem = m_TreeCtrl.GetFirstVisibleItem();

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   ASSERT(TVIS_BOLD & m_TreeCtrl.GetItemState(hItem, TVIS_BOLD));
   hItem = m_TreeCtrl.GetNextVisibleItem(hItem);
}

`CTreeCtrl::GetItemStateEx`

Recupera o estado estendido do item especificado no controle de exibição de árvore atual.

UINT GetItemStateEx(HTREEITEM hItem) const;

Parâmetros

hItem
[in] Manipule para um item de controle de exibição de árvore.

Valor de Devolução

O estado estendido do item. Para obter mais informações, consulte o membro uStateEx da estrutura TVITEMEX.

Comentários

Esse método envia a mensagem TVM_GETITEM, que é descrita no SDK do Windows. Essa mensagem retorna a estrutura TVITEMEX que descreve o item de controle de exibição de árvore e esse método recupera o membro uStateEx dessa estrutura.

`CTreeCtrl::GetItemText`

Retorna o texto do item especificado por hItem.

CString GetItemText(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador do item cujo texto deve ser recuperado.

Valor de Devolução

Um objeto CString que contém o texto do item.

Exemplo

Confira o exemplo de CTreeCtrl::GetNextItem.

`CTreeCtrl::GetLastVisibleItem`

Recupera o último item de nó não verificado no controle de exibição de árvore atual.

HTREEITEM GetLastVisibleItem() const;

Valor de Devolução

O identificador para o último item de nó não compilado se o método for bem-sucedido; caso contrário, NULL.

Comentários

Esse método envia a mensagem TVM_GETNEXTITEM, que é descrita no SDK do Windows. Para obter mais informações, consulte o sinalizador TVGN_LASTVISIBLE no parâmetro flag dessa mensagem.

Exemplo

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

O próximo exemplo de código recupera um identificador para o último item de nó de exibição de árvore não verificado e desenha um retângulo 3D em torno desse item. Em uma seção anterior do exemplo de código, que não é mostrada, criamos uma exibição de árvore que consiste em um nó de país/região raiz para o Estados Unidos, subnós para os estados da Pensilvânia e Washington e itens de árvore para cidades nesses estados.

CRect rect;
HTREEITEM hLast = m_treeCtrl.GetLastVisibleItem();
m_treeCtrl.GetItemPartRect(hLast, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

`CTreeCtrl::GetLineColor`

Essa função membro implementa o comportamento da mensagem TVM_GETLINECOLOR do Win32, conforme descrito no SDK do Windows.

COLORREF GetLineColor() const;

Valor de Devolução

A cor da linha atual.

Exemplo

COLORREF cr = m_TreeCtrl.GetLineColor();

`CTreeCtrl::GetNextItem`

Chame essa função para recuperar o item de exibição de árvore que tem a relação especificada, indicada pelo parâmetro nCode, para hItem.

HTREEITEM GetNextItem(
    HTREEITEM hItem,
    UINT nCode) const;

Parâmetros

hItem
Identificador de um item de árvore.

nCode
Um sinalizador que indica o tipo de relação com hItem. Esse sinalizador pode ser um dos seguintes valores:

TVGN_CARET Recupera o item selecionado no momento.
TVGN_CHILD Recupera o primeiro item filho do item especificado pelo parâmetro hItem.
TVGN_DROPHILITE Recupera o item que é o destino de uma operação de arrastar e soltar.
TVGN_FIRSTVISIBLE Recupera o primeiro item visível.
TVGN_LASTVISIBLE Recupera o último item expandido na árvore. Isso não recupera o último item visível na janela de exibição de árvore.
TVGN_NEXT Recupera o próximo item irmão.
TVGN_NEXTVISIBLE Recupera o próximo item visível que segue o item especificado.
TVGN_PARENT Recupera o pai do item especificado.
TVGN_PREVIOUS Recupera o item irmão anterior.
TVGN_PREVIOUSVISIBLE Recupera o primeiro item visível que precede o item especificado.
TVGN_ROOT Recupera o primeiro item filho do item raiz do qual o item especificado faz parte.

Valor de Devolução

O identificador do próximo item, se tiver êxito; caso contrário NULL.

Comentários

Essa função retornará NULL se o item que está sendo recuperado for o nó raiz da árvore. Por exemplo, se você usar essa mensagem com o sinalizador TVGN_PARENT em um filho de primeiro nível do nó raiz do modo de exibição de árvore, a mensagem retornará NULL.

Exemplo

Para obter um exemplo de uso GetNextItem em um loop, consulte CTreeCtrl::DeleteItem.

// find the currently selected item
HTREEITEM hCurSel = m_TreeCtrl.GetNextItem(TVI_ROOT, TVGN_CARET);

// report it to the user
if (hCurSel == NULL)
{
   AfxMessageBox(_T("There is no selected item"));
}
else
{
   CString str;
   str.Format(_T("The currently selected item is \"%s\""),
              (LPCTSTR)m_TreeCtrl.GetItemText(hCurSel));
   AfxMessageBox((LPCTSTR)str);
}

`CTreeCtrl::GetNextSiblingItem`

Chame essa função para recuperar o próximo irmão de hItem.

HTREEITEM GetNextSiblingItem(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

O identificador do próximo item irmão; caso contrário NULL.

Exemplo

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the children of hmyItem in bold.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hItem != NULL)
   {
      m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
      hItem = m_TreeCtrl.GetNextSiblingItem(hItem);
   }
}

`CTreeCtrl::GetNextVisibleItem`

Chame essa função para recuperar o próximo item visível de hItem.

HTREEITEM GetNextVisibleItem(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

O identificador do próximo item visível; caso contrário NULL.

Exemplo

Confira o exemplo de CTreeCtrl::SetCheck.

`CTreeCtrl::GetParentItem`

Chame essa função para recuperar o pai de hItem.

HTREEITEM GetParentItem(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

O identificador do item pai; caso contrário NULL.

Comentários

Essa função retornará NULL se o pai do item especificado for o nó raiz da árvore.

Exemplo

Confira o exemplo de CTreeCtrl::EnsureVisible.

`CTreeCtrl::GetPrevSiblingItem`

Chame essa função para recuperar o irmão anterior de hItem.

HTREEITEM GetPrevSiblingItem(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

O identificador do irmão anterior; caso contrário NULL.

Exemplo

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the previous siblings of hmyItem in bold.
HTREEITEM hItem = hmyItem;

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   hItem = m_TreeCtrl.GetPrevSiblingItem(hItem);
}

`CTreeCtrl::GetPrevVisibleItem`

Chame essa função para recuperar o item visível anterior de hItem.

HTREEITEM GetPrevVisibleItem(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

O identificador do item visível anterior; caso contrário NULL.

Exemplo

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the previous visible items of hmyItem in bold.
HTREEITEM hItem = hmyItem;

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   hItem = m_TreeCtrl.GetPrevVisibleItem(hItem);
}

`CTreeCtrl::GetRootItem`

Chame essa função para recuperar o item raiz do controle de exibição de árvore.

HTREEITEM GetRootItem() const;

Valor de Devolução

O identificador do item raiz; caso contrário NULL.

Exemplo

Confira o exemplo de CTreeCtrl::EditLabel.

`CTreeCtrl::GetScrollTime`

Chame essa função de membro para recuperar o tempo máximo de rolagem para o controle de exibição de árvore.

UINT GetScrollTime() const;

Valor de Devolução

O tempo máximo de rolagem em milissegundos.

Comentários

Essa função membro implementa o comportamento da mensagem TVM_GETSCROLLTIME do Win32, conforme descrito no SDK do Windows.

`CTreeCtrl::GetSelectedCount`

Recupera o número de itens selecionados no controle de exibição de árvore atual.

UINT GetSelectedCount();

Valor de Devolução

O número de itens selecionados.

Comentários

Esse método envia a mensagem TVM_GETSELECTEDCOUNT, que é descrita no SDK do Windows.

`CTreeCtrl::GetSelectedItem`

Chame essa função para recuperar o item atualmente selecionado do controle de exibição de árvore.

HTREEITEM GetSelectedItem() const;

Valor de Devolução

O identificador do item selecionado; caso contrário NULL.

Exemplo

// Expand the selected item and make it visible, if possible.
HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();

if ((hItem != NULL) && m_TreeCtrl.ItemHasChildren(hItem))
{
   m_TreeCtrl.Expand(hItem, TVE_EXPAND);
   m_TreeCtrl.EnsureVisible(hItem);
}

`CTreeCtrl::GetTextColor`

Essa função membro implementa o comportamento da mensagem TVM_GETTEXTCOLOR do Win32, conforme descrito no SDK do Windows.

COLORREF GetTextColor() const;

Valor de Devolução

Um valor COLORREF que representa a cor do texto atual. Se esse valor for -1, o controle usará a cor do sistema para a cor do texto.

Exemplo

Confira o exemplo de CTreeCtrl::SetTextColor.

`CTreeCtrl::GetToolTips`

Essa função membro implementa o comportamento da mensagem TVM_GETTOOLTIPS do Win32, conforme descrito no SDK do Windows.

CToolTipCtrl* GetToolTips() const;

Valor de Devolução

Um ponteiro para um objeto CToolTipCtrl a ser usado pelo controle de árvore. Se a função membro Create usar o estilo TVS_NOTOOLTIPS, nenhuma dica de ferramenta será usada e NULL será retornada.

Comentários

A implementação MFC de GetToolTips retorna um objeto CToolTipCtrl, que é usado pelo controle de árvore, em vez de um identificador para um controle de dica de ferramenta.

Exemplo

// If the tree control does not have a tooltips control,
// then use m_ToolTips as the tooltips for the tree control.
if (m_TreeCtrl.GetToolTips() == NULL)
{
   m_TreeCtrl.SetToolTips(&m_ToolTips);
}

`CTreeCtrl::GetVisibleCount`

Chame essa função para recuperar uma contagem dos itens visíveis em um controle de exibição de árvore.

UINT GetVisibleCount() const;

Valor de Devolução

O número de itens visíveis no controle de exibição de árvore; caso contrário, 1.

Exemplo

Confira o exemplo de CTreeCtrl::SetCheck.

`CTreeCtrl::HitTest`

Chame essa função para determinar o local do ponto especificado em relação à área do cliente de um controle de exibição de árvore.

HTREEITEM HitTest(
    CPoint pt,
    UINT* pFlags = NULL) const;

HTREEITEM HitTest(TVHITTESTINFO* pHitTestInfo) const;

Parâmetros

pt
Coordenadas do cliente do ponto a ser testado.

pFlags
Ponteiro para um inteiro que recebe informações sobre os resultados do teste de ocorrência. Pode ser um ou mais dos valores listados no membro flags na seção Comentários.

pHitTestInfo
Endereço de uma estrutura TVHITTESTINFO que contém a posição a ser atingida no teste e que recebe informações sobre os resultados do teste de ocorrência.

Valor de Devolução

O identificador do item de exibição de árvore que ocupa o ponto especificado ou NULL se nenhum item ocupa o ponto.

Comentários

Quando essa função é chamada, o parâmetro pt especifica as coordenadas do ponto a ser testado. A função retorna o identificador do item no ponto especificado ou NULL se nenhum item ocupa o ponto. Além disso, o parâmetro pFlags contém um valor que indica o local do ponto especificado. Os valores possíveis são:

Valor	Descrição
`TVHT_ABOVE`	Acima da área do cliente.
`TVHT_BELOW`	Abaixo da área do cliente.
`TVHT_NOWHERE`	Na área do cliente, mas abaixo do último item.
`TVHT_ONITEM`	No bitmap ou rótulo associado a um item.
`TVHT_ONITEMBUTTON`	No botão associado a um item.
`TVHT_ONITEMICON`	No bitmap associado a um item.
`TVHT_ONITEMINDENT`	No recuo associado a um item.
`TVHT_ONITEMLABEL`	No rótulo (cadeia de caracteres) associado a um item.
`TVHT_ONITEMRIGHT`	Na área à direita de um item.
`TVHT_ONITEMSTATEICON`	No ícone de estado de um item de exibição de árvore que está em um estado definido pelo usuário.
`TVHT_TOLEFT`	À esquerda da área do cliente.
`TVHT_TORIGHT`	À direita da área do cliente.

Exemplo

// Select the item that is at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectItem(hItem);
}

`CTreeCtrl::InsertItem`

Chame essa função para inserir um novo item em um controle de exibição de árvore.

HTREEITEM InsertItem(LPTVINSERTSTRUCT lpInsertStruct);

HTREEITEM InsertItem(
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam,
    HTREEITEM hParent,
    HTREEITEM hInsertAfter);

HTREEITEM InsertItem(
    LPCTSTR lpszItem,
    HTREEITEM hParent = TVI_ROOT,
    HTREEITEM hInsertAfter = TVI_LAST);

HTREEITEM InsertItem(
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    HTREEITEM hParent = TVI_ROOT,
    HTREEITEM hInsertAfter = TVI_LAST);

Parâmetros

lpInsertStruct
Um ponteiro para um TVINSERTSTRUCT que especifica os atributos do item de exibição de árvore a ser inserido.

nMask
Inteiro especificando quais atributos definir. Consulte a estrutura TVITEM no SDK do Windows.

lpszItem
Endereço de uma cadeia de caracteres que contém o texto do item.

nImage
Índice da imagem do item na lista de imagens do controle de exibição de árvore.

nSelectedImage
Índice da imagem selecionada do item na lista de imagens do controle de exibição de árvore.

nState
Especifica valores para os estados do item. Consulte estados de item de controle de exibição de árvore no SDK do Windows para obter uma lista de estados apropriados.

nStateMask
Especifica quais estados devem ser definidos. Consulte a estrutura TVITEM no SDK do Windows.

lParam
Um valor específico do aplicativo do tamanho do ponteiro associado ao item.

hParent
Identificador do pai do item inserido.

hInsertAfter
Manipule o item após o qual o novo item deve ser inserido.

Valor de Devolução

Identificador do novo item se tiver êxito; caso contrário NULL.

Comentários

O exemplo mostra situações em que talvez você queira usar cada versão da função ao inserir um item de controle de árvore.

Exemplo

// Insert a root item using the structure. We must
// initialize a TVINSERTSTRUCT structure and pass its
// address to the call. 

TVINSERTSTRUCT tvInsert;
tvInsert.hParent = NULL;
tvInsert.hInsertAfter = NULL;
tvInsert.item.mask = TVIF_TEXT;
tvInsert.item.pszText = _T("United States");

HTREEITEM hCountry = m_TreeCtrl.InsertItem(&tvInsert);

// Insert subitems of that root. Pennsylvania is
// a state in the United States, so its item will be a child
// of the United States item. We won't set any image or states,
// so we supply only the TVIF_TEXT mask flag. This
// override provides nearly complete control over the
// insertion operation without the tedium of initializing
// a structure. If you're going to add lots of items
// to a tree, you might prefer the structure override
// as it affords you a performance win by allowing you
// to initialize some fields of the structure only once,
// outside of your insertion loop.

HTREEITEM hPA = m_TreeCtrl.InsertItem(TVIF_TEXT,
   _T("Pennsylvania"), 0, 0, 0, 0, 0, hCountry, NULL);

// Insert the "Washington" item and assure that it is
// inserted after the "Pennsylvania" item. This override is 
// more appropriate for conveniently inserting items with 
// images.

HTREEITEM hWA = m_TreeCtrl.InsertItem(_T("Washington"),
   0, 0, hCountry, hPA);

// We'll add some cities under each of the states.
// The override used here is most appropriate
// for inserting text-only items.

m_TreeCtrl.InsertItem(_T("Pittsburgh"), hPA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Harrisburg"), hPA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Altoona"), hPA, TVI_SORT);

m_TreeCtrl.InsertItem(_T("Seattle"), hWA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Kalaloch"), hWA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Yakima"), hWA, TVI_SORT);

`CTreeCtrl::ItemHasChildren`

Use essa função para determinar se o item de árvore especificado por hItem tem itens filho.

BOOL ItemHasChildren(HTREEITEM hItem) const;

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

Não zero se o item de árvore especificado por hItem tem itens filho; 0 se não tiver.

Comentários

Nesse caso, você pode usar CTreeCtrl::GetChildItem para recuperar esses itens filho.

Exemplo

Confira o exemplo de CTreeCtrl::GetSelectedItem.

`CTreeCtrl::MapAccIdToItem`

Mapeia o identificador de acessibilidade especificado para o identificador de um item de exibição de árvore no controle de exibição de árvore atual.

HTREEITEM MapAccIdToItem(UINT uAccId) const;

Parâmetros

uAccId
[in] Um identificador de acessibilidade para um elemento no item de exibição de árvore.

Valor de Devolução

O identificador de um item de exibição de árvore (HTREEITEM) que corresponde ao parâmetro uAccId. Para obter mais informações, consulte o membro hItem da estrutura TVITEMEX.

Comentários

Auxílios de acessibilidade são aplicativos que ajudam pessoas com deficiência a usar computadores. Um identificador de acessibilidade é usado pela interface IAccessible para especificar exclusivamente um elemento em uma janela. Para obter mais informações sobre as IAccessible APIs, consulte a Acessibilidade Ativa da Microsoft.

Esse método envia a mensagem TVM_MAPACCIDTOHTREEITEM, que é descrita no SDK do Windows.

Exemplo

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

O próximo exemplo de código usa um identificador de acessibilidade e o método CTreeCtrl::MapAccIdToItem para recuperar um identificador para o item de exibição de árvore raiz. O exemplo usa o identificador e o método CTreeCtrl::GetItemPartRect para desenhar um retângulo 3D em torno desse item. Em uma seção anterior do exemplo de código, que não é mostrada, criamos uma exibição de árvore que consiste em um nó de país/região raiz para o Estados Unidos, subnós para os estados da Pensilvânia e Washington e itens de árvore para cidades nesses estados. Usamos o método CTreeCtrl::MapItemToAccID para associar o item de exibição de árvore raiz a um identificador de acessibilidade.

CRect rect;
HTREEITEM hUS = m_treeCtrl.MapAccIdToItem(accIdUS);
m_treeCtrl.GetItemPartRect(hUS, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

`CTreeCtrl::MapItemToAccID`

Mapeia o identificador especificado de um item de exibição de árvore no controle de exibição de árvore atual para um identificador de acessibilidade.

UINT MapItemToAccID(HTREEITEM hItem) const;

Parâmetros

hItem
[in] Um identificador de um item de exibição de árvore no controle. Para obter mais informações, consulte o membro hItem da estrutura TVITEMEX.

Valor de Devolução

O identificador de acessibilidade que corresponde ao parâmetro hItem.

Comentários

Esse método envia a mensagem TVM_MAPHTREEITEMTOACCID, que é descrita no SDK do Windows.

Exemplo

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

O próximo exemplo de código obtém um número de identificação para um item de controle de exibição de árvore. Em uma seção anterior do exemplo de código, que não é mostrada, criamos uma exibição de árvore que consiste em um nó de país/região raiz para o Estados Unidos, subnós para os estados da Pensilvânia e Washington e itens de árvore para cidades nesses estados. Este exemplo de código obtém um número de identificação exclusivo para o nó de país/região raiz.

// Map an accessibility identifier to the Pennsylvania node.
accIdUS = m_treeCtrl.MapItemToAccId(hCountry);

`CTreeCtrl::Select`

Chame essa função para selecionar o item de exibição de árvore determinado, rolar o item para a exibição ou redesenhar o item no estilo usado para indicar o destino de uma operação de arrastar e soltar.

BOOL Select(
    HTREEITEM hItem,
    UINT nCode);

Parâmetros

hItem
Identificador de um item de árvore.

nCode
O tipo de ação a ser realizada. Esse parâmetro pode usar um dos valores a seguir:

TVGN_CARET Define a seleção como o item especificado.
TVGN_DROPHILITE Redesenha o item especificado no estilo usado para indicar o destino de uma operação de arrastar e soltar.
TVGN_FIRSTVISIBLE Rola a exibição da árvore verticalmente para que o item especificado seja o primeiro item visível.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Se nCode contiver o valor TVGN_CARET, a janela pai receberá as mensagens de notificação TVN_SELCHANGING e TVN_SELCHANGED. Além disso, se o item especificado for o filho de um item pai recolhido, a lista pai de itens filho será expandida para revelar o item especificado. Nesse caso, a janela pai recebe as mensagens de notificação TVN_ITEMEXPANDING e TVN_ITEMEXPANDED.

Exemplo

Confira o exemplo de CTreeCtrl::HitTest.

`CTreeCtrl::SelectDropTarget`

Chame essa função para redesenhar o item no estilo usado para indicar o destino de uma operação de arrastar e soltar.

BOOL SelectDropTarget(HTREEITEM hItem);

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

// Set the item at the point myPoint as the drop target.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectDropTarget(hItem);
   ASSERT(m_TreeCtrl.GetDropHilightItem() == hItem);
}

`CTreeCtrl::SelectItem`

Chame essa função para selecionar o item de exibição de árvore especificado.

BOOL SelectItem(HTREEITEM hItem);

Parâmetros

hItem
Identificador de um item de árvore.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Se hItem for NULL, essa função não selecionará nenhum item.

Exemplo

// Select the item that is at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectItem(hItem);
}

`CTreeCtrl::SelectSetFirstVisible`

Chame essa função para rolar a exibição da árvore verticalmente para que o item especificado seja o primeiro item visível.

BOOL SelectSetFirstVisible(HTREEITEM hItem);

Parâmetros

hItem
Manipule o item de árvore a ser definido como o primeiro item visível.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A função envia uma mensagem para a janela com os parâmetros de mensagem TVM_SELECTITEM e TVGN_FIRSTVISIBLE.

Exemplo

// Select the item at the point myPoint as the first visible item.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectSetFirstVisible(hItem);
}

`CTreeCtrl::SetAutoscrollInfo`

Define a taxa de registro automático do controle de exibição de árvore atual.

BOOL SetAutoscrollInfo(
    UINT uPixelsPerSec,
    UINT uUpdateTime);

Parâmetros

uPixelsPerSec
[in] O número de pixels por segundo a rolar.

uUpdateTime
[in] O intervalo de tempo entre as atualizações do controle.

Valor de Devolução

Sempre retorna TRUE.

Comentários

Os parâmetros de registro automático são usados para rolar para exibir um item que atualmente não está visível. O controle de exibição de árvore deve ter o estilo estendido TVS_EX_AUTOHSCROLL, que é descrito em Estilos Estendidos de Controle de Exibição de Árvore.

Esse método envia a mensagem TVM_SETAUTOSCROLLINFO, que é descrita no SDK do Windows.

Exemplo

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

O exemplo de código a seguir define o comportamento de registro automático do controle de exibição de árvore atual. Em uma seção anterior do exemplo de código, que não é mostrada, criamos uma exibição de árvore que consiste em um nó de país/região raiz para o Estados Unidos, subnós para os estados da Pensilvânia e Washington e itens de árvore para cidades nesses estados. Fizemos intencionalmente o controle de exibição de árvore estreita para que ele seja rolado automaticamente para exibir o item de árvore que tem o foco. O exemplo de código define o controle de exibição de árvore para rolar automaticamente 30 pixels por segundo a cada 5 segundos até que o item de árvore esteja em exibição.

// Scroll 30 pixels/sec and redraw every 5 seconds.
m_treeCtrl.SetAutoscrollInfo(30, 5);

`CTreeCtrl::SetBkColor`

Essa função membro implementa o comportamento da mensagem TVM_SETBKCOLOR do Win32, conforme descrito no SDK do Windows.

COLORREF SetBkColor(COLORREF clr);

Parâmetros

clr
Um valor COLORREF que especifica a nova cor do plano de fundo. Se esse valor for -1, o controle será revertido para usar a cor do sistema para a cor da tela de fundo.

Valor de Devolução

Um valor COLORREF que representa a cor do texto atual. Se esse valor for -1, o controle usará a cor do sistema para a cor do texto.

Exemplo

Confira o exemplo de CTreeCtrl::SetTextColor.

`CTreeCtrl::SetCheck`

Chame essa função de membro para definir o estado de verificação de um item de controle de árvore.

BOOL SetCheck(
    HTREEITEM hItem,
    BOOL fCheck = TRUE);

Parâmetros

hItem
A HTREEITEM para receber a alteração do estado de verificação.

fCheck
Indica se o item de controle de árvore deve ser verificado ou desmarcado. Por padrão, SetCheck define o item a ser verificado.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Quando o item de controle de árvore é verificado (fCheck definido como TRUE), o item aparece com uma marca de seleção adjacente.

Exemplo

UINT uCount = m_TreeCtrl.GetVisibleCount();
HTREEITEM hItem = m_TreeCtrl.GetFirstVisibleItem();

// Toggle the check state of all the visible items.
for (UINT i = 0; i < uCount; i++)
{
   ASSERT(hItem != NULL);
   m_TreeCtrl.SetCheck(hItem, !m_TreeCtrl.GetCheck(hItem));
   hItem = m_TreeCtrl.GetNextVisibleItem(hItem);
}

Para usar caixas de seleção, defina TVS_CHECKBOXES antes de preencher o controle de árvore.

m_TreeCtrl.ModifyStyle(0, TVS_CHECKBOXES);

HTREEITEM aItem = m_TreeCtrl.InsertItem(_T("AAA"));
m_TreeCtrl.SetCheck(aItem);

`CTreeCtrl::SetExtendedStyle`

Define os estilos estendidos para o controle de exibição de árvore atual.

DWORD SetExtendedStyle(
    DWORD dwExMask,
    DWORD dwExStyles);

Parâmetros

dwExMask
[in] Uma máscara de bits que especifica quais estilos no controle de exibição de árvore atual são afetados por esse método. Se esse parâmetro for zero, ele será ignorado e o valor do parâmetro dwExStyles será atribuído ao controle de exibição de árvore. Especifique zero ou uma combinação bit a bit (OR) de estilos descritos em Estilos Estendidos de Controle de Exibição de Árvore.

dwExStyles
[in] Uma máscara de bits que especifica quais estilos no controle de exibição de árvore atual devem ser definidos ou limpos. Para definir uma combinação de estilos, especifique uma combinação bit a bit (OR) de estilos descritos em Estilos Estendidos de Controle de Exibição de Árvore. Para limpar um conjunto de estilos, especifique zero.

Valor de Devolução

Um valor que contém os estilos de controle estendidos anteriores.

Comentários

Esse método limpa os estilos especificados no parâmetro dwExMask e define os estilos especificados no parâmetro dwExStyles. Somente os estilos estendidos que correspondem aos bits em dwExMask alteração.

Esse método envia a mensagem TVM_SETEXTENDEDSTYLE, que é descrita no SDK do Windows.

Exemplo

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

O próximo exemplo de código adiciona o estilo estendido TVS_EX_AUTOHSCROLL ao controle de exibição de árvore atual. Em uma seção anterior do exemplo de código, que não é mostrada, criamos uma exibição de árvore que consiste em um nó de país/região raiz para o Estados Unidos, subnós para os estados da Pensilvânia e Washington e itens de árvore para cidades nesses estados. Fizemos intencionalmente o controle de exibição de árvore estreita para que ele seja rolado automaticamente para exibir o item de árvore que tem o foco.

m_treeCtrl.SetExtendedStyle(TVS_EX_AUTOHSCROLL, TVS_EX_AUTOHSCROLL);

`CTreeCtrl::SetImageList`

Chame essa função para definir a lista de imagens normal ou de estado para um controle de exibição de árvore e redesenhe o controle usando as novas imagens.

CImageList* SetImageList(
    CImageList* pImageList,
    int nImageListType);

Parâmetros

pImageList
Ponteiro para a lista de imagens a ser atribuída. Se pImageList for NULL, todas as imagens são removidas do controle de exibição de árvore.

nImageListType
Tipo de lista de imagens a definir. A lista de imagens pode ter um dos seguintes valores:

TVSIL_NORMAL Define a lista de imagens normal, que contém as imagens selecionadas e não selecionadas para o item de exibição de árvore. Você deve usar esse estado para sobrepor imagens.
TVSIL_STATE Define a lista de imagens de estado, que contém as imagens para itens de exibição de árvore que estão em um estado definido pelo usuário.

Valor de Devolução

Ponteiro para a lista de imagens anterior, se houver; caso contrário NULL.

Exemplo

Confira o exemplo de CTreeCtrl::GetImageList.

`CTreeCtrl::SetIndent`

Chame essa função para definir a largura do recuo para um controle de exibição de árvore e redesenhe o controle para refletir a nova largura.

void SetIndent(UINT nIndent);

Parâmetros

nIndent
Largura, em pixels, do recuo. Se nIndent for menor que a largura mínima definida pelo sistema, a nova largura será definida como o mínimo definido pelo sistema.

Exemplo

Confira o exemplo de CTreeCtrl::GetIndent.

`CTreeCtrl::SetInsertMark`

Essa função membro implementa o comportamento da mensagem TVM_SETINSERTMARK do Win32, conforme descrito no SDK do Windows.

BOOL SetInsertMark(
    HTREEITEM hItem,
    BOOL fAfter = TRUE);

Parâmetros

hItem
HTREEITEM que especifica em qual item a marca de inserção será colocada. Se esse argumento for NULL, a marca de inserção será removida.

fAfter
Valor BOOL que especifica se a marca de inserção é colocada antes ou depois do item especificado. Se esse argumento não for zero, a marca de inserção será colocada após o item. Se esse argumento for zero, a marca de inserção será colocada antes do item.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

// Set the insert mark to be before the item at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetInsertMark(hItem, FALSE);
}

`CTreeCtrl::SetInsertMarkColor`

Essa função membro implementa o comportamento da mensagem TVM_SETINSERTMARKCOLOR do Win32, conforme descrito no SDK do Windows.

COLORREF SetInsertMarkColor(COLORREF clrNew);

Parâmetros

clrNew
Um valor COLORREF que contém a nova cor da marca de inserção.

Valor de Devolução

Um valor COLORREF que contém a cor da marca de inserção anterior.

Exemplo

Confira o exemplo de CTreeCtrl::GetInsertMarkColor.

`CTreeCtrl::SetItem`

Chame essa função para definir os atributos do item de exibição de árvore especificado.

BOOL SetItem(TVITEM* pItem);

BOOL SetItem(
    HTREEITEM hItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam);

Parâmetros

pItem
Ponteiro de uma estrutura TVITEM que contém os novos atributos de item, conforme descrito no SDK do Windows.

hItem
Indicador de item cujos atributos devem ser definidos. Confira o membro hItem da estrutura TVITEM no SDK do Windows.

nMask
Inteiro especificando quais atributos definir. Consulte o membro mask da estrutura TVITEM.

lpszItem
Endereço de uma cadeia de caracteres que contém o texto do item.

nImage
Índice da imagem do item na lista de imagens do controle de exibição de árvore. Consulte o membro iImage da estrutura TVITEM.

nSelectedImage
Índice da imagem selecionada do item na lista de imagens do controle de exibição de árvore. Consulte o membro iSelectedImage da estrutura TVITEM.

nState
Especifica valores para os estados do item. Consulte o membro State da estrutura TVITEM.

nStateMask
Especifica quais estados devem ser definidos. Consulte o membro stateMask da estrutura TVITEM.

lParam
Um valor específico do aplicativo do tamanho do ponteiro associado ao item.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Na estrutura TVITEM, o membro hItem identifica o item e o membro mask especifica quais atributos definir.

Se o membro mask ou o parâmetro nMask especificar o valor TVIF_TEXT, o membro pszText ou o endereço lpszItem de uma cadeia de caracteres terminada em nulo e o membro cchTextMax será ignorado. Se mask (ou nMask) especificar o TVIF_STATE valor, o membro stateMask ou o parâmetro nStateMask especificar quais estados de item serão alterados e o membro state ou parâmetro nState conterá os valores para esses estados.

Exemplo

// Show the item at the point myPoint in bold.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetItem(hItem, TVIF_STATE, NULL, 0, 0, TVIS_BOLD,
                      TVIS_BOLD, 0);
}

`CTreeCtrl::SetItemData`

Chame essa função para definir o valor específico do aplicativo associado ao item especificado.

BOOL SetItemData(
    HTREEITEM hItem,
    DWORD_PTR dwData);

Parâmetros

hItem
Identificador do item de lista cujos dados devem ser recuperados.

dwData
Um valor específico do aplicativo do tamanho do ponteiro associado ao item especificado por hItem.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

CString str;
HTREEITEM hItem;

// Insert 20 items into the tree control making every item's
// data be the handle of the item.
for (int i = 0; i < 20; i++)
{
   str.Format(TEXT("item %d"), i);
   hItem = m_TreeCtrl.InsertItem(str);

   if (hItem != NULL)
   {
      m_TreeCtrl.SetItemData(hItem, (DWORD_PTR)hItem);
   }
}

`CTreeCtrl::SetItemExpandedImageIndex`

Define o índice da imagem a ser exibido quando o item especificado do controle de exibição de árvore atual estiver no estado expandido.

BOOL SetItemExpandedImageIndex(
    HTREEITEM hItem,
    int iExpandedImage);

Parâmetros

hItem
[in] Manipule para um item de controle de exibição de árvore.

iExpandedImage
[in] O índice da imagem a ser exibido quando o item especificado estiver no estado expandido.

Valor de Devolução

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Esse método envia a mensagem TVM_SETITEM, que é descrita no SDK do Windows. Esse método atribui o parâmetro iExpandedImage ao membro iExpandedImage de uma estrutura TVITEMEX e usa essa estrutura na mensagem.

Exemplo

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

O próximo exemplo de código é um teste trivial para determinar se o método CTreeCtrl::GetItemExpandedImageIndex retorna o valor definido pelo método CTreeCtrl::SetItemExpandedImageIndex. Em uma seção anterior do exemplo de código, que não é mostrada, criamos uma exibição de árvore que consiste em um nó de país/região raiz para o Estados Unidos, subnós para os estados da Pensilvânia e Washington e itens de árvore para cidades nesses estados.

CString str;
CString msg = _T("The set and retrieved item expanded image ")
              _T("indexes are%s equal.");
int nSetItem = 0;
m_treeCtrl.SetItemExpandedImageIndex(hCountry, nSetItem);
int nItem = m_treeCtrl.GetItemExpandedImageIndex(hCountry);
if (nItem == nSetItem)
   str.Format(msg, _T(""));
else
   str.Format(msg, _T(" not"));
AfxMessageBox(str, MB_ICONINFORMATION);

`CTreeCtrl::SetItemHeight`

Essa função membro implementa o comportamento da mensagem TVM_SETITEMHEIGHT do Win32, conforme descrito no SDK do Windows.

SHORT SetItemHeight(SHORT cyHeight);

Parâmetros

cyHeight
Especifica a nova altura de cada item no modo de exibição de árvore, em pixels. Se esse argumento for menor que a altura das imagens, ele será definido como a altura das imagens. Se esse argumento não for mesmo, ele será arredondado para baixo até o valor par mais próximo. Se esse argumento for -1, o controle será revertido para usar a altura do item padrão.

Valor de Devolução

A altura anterior dos itens, em pixels.

Exemplo

Confira o exemplo de CTreeCtrl::GetItemHeight.

`CTreeCtrl::SetItemImage`

Associa imagens a um item.

BOOL SetItemImage(
    HTREEITEM hItem,
    int nImage,
    int nSelectedImage);

Parâmetros

hItem
Identificador do item cuja imagem deve ser definida.

nImage
Índice da imagem do item na lista de imagens do controle de exibição de árvore.

nSelectedImage
Índice da imagem selecionada do item na lista de imagens do controle de exibição de árvore.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Cada item em um controle de exibição de árvore pode ter um par de imagens bitmapped associadas a ele. As imagens aparecem no lado esquerdo do rótulo de um item. Uma imagem é exibida quando o item é selecionado e a outra é exibida quando o item não está selecionado. Por exemplo, um item pode exibir uma pasta aberta quando estiver selecionada e uma pasta fechada quando não estiver selecionada.

Chame essa função para definir o índice da imagem do item e sua imagem selecionada na lista de imagens do controle de exibição de árvore.

Para obter mais informações sobre imagens, consulte CImageList.

Exemplo

Confira o exemplo de CTreeCtrl::GetItemImage.

`CTreeCtrl::SetItemState`

Define o estado do item especificado por hItem.

BOOL SetItemState(
    HTREEITEM hItem,
    UINT nState,
    UINT nStateMask);

Parâmetros

hItem
Identificador do item cujo estado deve ser definido.

nState
Especifica novos estados para o item.

nStateMask
Especifica quais estados devem ser alterados.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Para obter informações sobre estados, consulte CTreeCtrl::GetItem.

Exemplo

Confira o exemplo de CTreeCtrl::GetItemState.

`CTreeCtrl::SetItemStateEx`

Define o estado estendido do item especificado no controle de exibição de árvore atual.

BOOL SetItemStateEx(
    HTREEITEM hItem,
    UINT uStateEx);

Parâmetros

hItem
[in] Manipule para um item de controle de exibição de árvore.

uStateEx
[in] O estado estendido do item. Para obter mais informações, consulte o membro uStateEx da estrutura TVITEMEX.

Valor de Devolução

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Esse método envia a mensagem TVM_SETITEM, que é descrita no SDK do Windows. Esse método atribui o parâmetro uStateEx ao membro uStateEx de uma estrutura TVITEMEX e usa essa estrutura na mensagem.

Exemplo

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

O próximo exemplo de código define um item de exibição de árvore como estado desabilitado. Em uma seção anterior do exemplo de código, que não é mostrada, criamos uma exibição de árvore que consiste em um nó de país/região raiz para o Estados Unidos, subnós para os estados da Pensilvânia e Washington e itens de árvore para cidades nesses estados. Este exemplo de código define o nó da Pensilvânia como estado desabilitado.

// Disable the Pennsylvania node.
m_treeCtrl.SetItemStateEx(hPA, TVIS_EX_DISABLED);

`CTreeCtrl::SetItemText`

Define o texto do item especificado por hItem.

BOOL SetItemText(
    HTREEITEM hItem,
    LPCTSTR lpszItem);

Parâmetros

hItem
Identificador do item cujo texto deve ser definido.

lpszItem
Endereço de uma cadeia de caracteres que contém o novo texto do item

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

// Clear the text of the item at point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetItemText(hItem, NULL);
}

`CTreeCtrl::SetLineColor`

Chame essa função de membro para definir a cor da linha atual para o controle de exibição de árvore.

COLORREF SetLineColor(COLORREF clrNew = CLR_DEFAULT);

Parâmetros

clrNew
A nova cor da linha.

Valor de Devolução

A cor da linha anterior.

Comentários

Essa função membro implementa o comportamento da mensagem TVM_SETLINECOLOR do Win32, conforme descrito no SDK do Windows.

Exemplo

COLORREF clrPrev = m_TreeCtrl.SetLineColor(RGB(255, 0, 0));

`CTreeCtrl::SetScrollTime`

Chame essa função de membro para definir o tempo máximo de rolagem para o controle de exibição de árvore.

UINT SetScrollTime(UINT uScrollTime);

Parâmetros

uScrollTime
O novo tempo máximo de rolagem em milissegundos. Se esse valor for menor que 100, ele será arredondado até 100.

Valor de Devolução

O tempo máximo de rolagem anterior em milissegundos.

Comentários

Essa função membro implementa o comportamento da mensagem TVM_SETSCROLLTIME do Win32, conforme descrito no SDK do Windows.

`CTreeCtrl::SetTextColor`

Essa função membro implementa o comportamento da mensagem TVM_SETTEXTCOLOR do Win32, conforme descrito no SDK do Windows.

COLORREF SetTextColor(COLORREF clr);

Parâmetros

clr
Um valor COLORREF que contém a nova cor de texto. Se esse argumento for -1, o controle será revertido para usar a cor do sistema para a cor do texto.

Valor de Devolução

Um valor COLORREF que representa a cor do texto anterior. Se esse valor for -1, o controle estava usando a cor do sistema para a cor do texto.

Exemplo

// change text color to white and background to dark blue
m_TreeCtrl.SetTextColor(RGB(255, 255, 255));
ASSERT(m_TreeCtrl.GetTextColor() == RGB(255, 255, 255));
m_TreeCtrl.SetBkColor(RGB(0, 0, 128));
ASSERT(m_TreeCtrl.GetBkColor() == RGB(0, 0, 128));

// force repaint immediately
m_TreeCtrl.Invalidate();

`CTreeCtrl::SetToolTips`

Essa função membro implementa o comportamento da mensagem TVM_SETTOOLTIPS do Win32, conforme descrito no SDK do Windows.

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

Parâmetros

pWndTip
Um ponteiro para um objeto CToolTipCtrl que o controle de árvore usará.

Valor de Devolução

Um ponteiro para um objeto CToolTipCtrl que contém a dica de ferramenta usada anteriormente pelo controle ou NULL se nenhuma dica de ferramenta foi usada anteriormente.

Comentários

Para usar dicas de ferramenta, indique o estilo TVS_NOTOOLTIPS ao criar o objeto CTreeCtrl.

Exemplo

Confira o exemplo de CTreeCtrl::GetToolTips.

`CTreeCtrl::ShowInfoTip`

Exibe a dica de informações do item especificado no controle de exibição de árvore atual.

void ShowInfoTip(HTREEITEM hItem);

Parâmetros

hItem
[in] Um identificador para um item de exibição de árvore no controle. Para obter mais informações, consulte o membro hItem da estrutura TVITEMEX.

Comentários

Para obter mais informações sobre a diferença entre dicas de ferramentas e dicas de informações, consulte dicas de ferramentas e dicas de informações.

Esse método envia a mensagem TVM_SHOWINFOTIP, que é descrita no SDK do Windows.

`CTreeCtrl::SortChildren`

Chame essa função para classificar alfabeticamente os itens filho do item pai especificado em um controle de exibição de árvore.

BOOL SortChildren(HTREEITEM hItem);

Parâmetros

hItem
Manipular o item pai cujos itens filho devem ser classificados. Se hItem for NULL, a classificação prosseguirá da raiz da árvore.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

SortChildren não será recurso através da árvore; somente os filhos imediatos de hItem serão classificados.

Exemplo

// Sort all of the items in the tree control.
m_TreeCtrl.SortChildren(TVI_ROOT);

`CTreeCtrl::SortChildrenCB`

Chame essa função para classificar itens de exibição de árvore usando uma função de retorno de chamada definida pelo aplicativo que compara os itens.

BOOL SortChildrenCB(LPTVSORTCB pSort);

Parâmetros

pSort
Ponteiro para uma estrutura TVSORTCB.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A função de comparação da estrutura lpfnCompare deve retornar um valor negativo se o primeiro item deve preceder o segundo, um valor positivo se o primeiro item deve seguir o segundo ou zero se os dois itens forem equivalentes.

Os parâmetros lParam1 e lParam2 correspondem ao membro lParam da estrutura TVITEM para os dois itens que estão sendo comparados. O parâmetro lParamSort corresponde ao membro lParam da estrutura TV_SORTCB.

Exemplo

// Sort the item in reverse alphabetical order.
int CALLBACK MyCompareProc(LPARAM lParam1, LPARAM lParam2, LPARAM lParamSort)
{
   // lParamSort contains a pointer to the tree control.
   // The lParam of an item is just its handle, 
   // as specified with SetItemData
   CTreeCtrl* pmyTreeCtrl = (CTreeCtrl*)lParamSort;
   CString strItem1 = pmyTreeCtrl->GetItemText((HTREEITEM)lParam1);
   CString strItem2 = pmyTreeCtrl->GetItemText((HTREEITEM)lParam2);

   return strItem2.Compare(strItem1);
}

TVSORTCB tvs;

// Sort the tree control's items using my
// callback procedure.
tvs.hParent = TVI_ROOT;
tvs.lpfnCompare = MyCompareProc;
tvs.lParam = (LPARAM)&m_TreeCtrl;

m_TreeCtrl.SortChildrenCB(&tvs);

Confira também

Exemplo de MFC CMNCTRL1
Classe CWnd
Gráfico da hierarquia
Classe CImageList

Share via

Classe CTreeCtrl

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CTreeCtrl::Create

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTreeCtrl::CreateEx

Parâmetros

Valor de Devolução

Comentários

CTreeCtrl::CreateDragImage

Parâmetros

Valor de Devolução

Comentários

CTreeCtrl::CTreeCtrl

CTreeCtrl::DeleteAllItems

Valor de Devolução

Exemplo

CTreeCtrl::DeleteItem

Parâmetros

Valor de Devolução

Exemplo

CTreeCtrl::EditLabel

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTreeCtrl::EndEditLabelNow

Parâmetros

Valor de Devolução

Comentários

CTreeCtrl::EnsureVisible

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTreeCtrl::Expand

Parâmetros

Valor de Devolução

Exemplo

CTreeCtrl::GetBkColor

Valor de Devolução

Exemplo

CTreeCtrl::GetCheck

Parâmetros

Valor de Devolução

Exemplo

CTreeCtrl::GetChildItem

Parâmetros

Valor de Devolução

Exemplo

CTreeCtrl::GetCount

Valor de Devolução

Exemplo

CTreeCtrl::GetDropHilightItem

Valor de Devolução

Exemplo

CTreeCtrl::GetEditControl

Valor de Devolução

Exemplo

CTreeCtrl::GetExtendedStyle

Valor de Devolução

Comentários

CTreeCtrl::GetFirstVisibleItem

Valor de Devolução

Exemplo

CTreeCtrl::GetImageList

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTreeCtrl::GetIndent

Classe `CTreeCtrl`

`CTreeCtrl::Create`

`CTreeCtrl::CreateEx`

`CTreeCtrl::CreateDragImage`

`CTreeCtrl::CTreeCtrl`

`CTreeCtrl::DeleteAllItems`

`CTreeCtrl::DeleteItem`

`CTreeCtrl::EditLabel`

`CTreeCtrl::EndEditLabelNow`

`CTreeCtrl::EnsureVisible`

`CTreeCtrl::Expand`

`CTreeCtrl::GetBkColor`

`CTreeCtrl::GetCheck`

`CTreeCtrl::GetChildItem`

`CTreeCtrl::GetCount`

`CTreeCtrl::GetDropHilightItem`

`CTreeCtrl::GetEditControl`

`CTreeCtrl::GetExtendedStyle`

`CTreeCtrl::GetFirstVisibleItem`

`CTreeCtrl::GetImageList`

`CTreeCtrl::GetIndent`

`CTreeCtrl::GetInsertMarkColor`

`CTreeCtrl::GetItem`

`CTreeCtrl::GetItemData`

`CTreeCtrl::GetItemExpandedImageIndex`

`CTreeCtrl::GetItemHeight`

`CTreeCtrl::GetItemImage`

`CTreeCtrl::GetItemPartRect`

`CTreeCtrl::GetItemRect`

`CTreeCtrl::GetItemState`

`CTreeCtrl::GetItemStateEx`

`CTreeCtrl::GetItemText`

`CTreeCtrl::GetLastVisibleItem`

`CTreeCtrl::GetLineColor`

`CTreeCtrl::GetNextItem`

`CTreeCtrl::GetNextSiblingItem`

`CTreeCtrl::GetNextVisibleItem`

`CTreeCtrl::GetParentItem`