Classe CTreeCtrl

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:

• Controls

• 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çalho: afxcmn.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 retorno

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.

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

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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

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. Uma ou mais dessas 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 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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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

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

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

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_MAPHTREEITEMTOACCID, que é descrita no SDK do Windows.

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

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 retorno

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 retorno

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 retorno

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 retorno

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

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

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 retorno

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 retorno

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

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

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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

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

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 retorno

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 retorno

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 retorno

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

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

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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