Clase `CTreeCtrl`

Artículo
06/16/2023

Proporciona la funcionalidad del control de vista de árbol común de Windows.

Sintaxis

class CTreeCtrl : public CWnd

Miembros

Constructores públicos

Nombre	Descripción
`CTreeCtrl::CTreeCtrl`	Construye un objeto `CTreeCtrl`.

Métodos públicos

Nombre	Descripción
`CTreeCtrl::Create`	Crea un control de vista de árbol y lo adjunta a un objeto `CTreeCtrl`.
`CTreeCtrl::CreateDragImage`	Crea un mapa de bits de arrastre para el elemento de vista de árbol especificado.
`CTreeCtrl::CreateEx`	Crea un control de lista con los estilos extendidos de Windows especificados y lo asocia a un objeto `CTreeCtrl`.
`CTreeCtrl::DeleteAllItems`	Elimina todos los elementos de un control de vista de árbol.
`CTreeCtrl::DeleteItem`	Elimina un nuevo elemento en un control de vista de árbol.
`CTreeCtrl::EditLabel`	Edita un elemento de vista de árbol especificado en contexto.
`CTreeCtrl::EndEditLabelNow`	Cancela la operación de edición en la etiqueta de un elemento de vista de árbol en el control de vista de árbol actual.
`CTreeCtrl::EnsureVisible`	Garantiza que un elemento de vista de árbol esté visible en su control de vista de árbol.
`CTreeCtrl::Expand`	Expande o contrae los elementos secundarios del elemento de vista de árbol especificado.
`CTreeCtrl::GetBkColor`	Esta función se usa para recuperar el color de fondo de la selección actual.
`CTreeCtrl::GetCheck`	Recupera el estado de comprobación de un elemento de control de árbol.
`CTreeCtrl::GetChildItem`	Recupera el elemento secundario de un elemento de vista de árbol especificado.
`CTreeCtrl::GetCount`	Recupera el número de elementos de árbol asociados a un control de vista de árbol.
`CTreeCtrl::GetDropHilightItem`	Recupera el destino de una operación de arrastrar y colocar.
`CTreeCtrl::GetEditControl`	Recupera el identificador del control de edición utilizado para editar el elemento de vista de árbol especificado.
`CTreeCtrl::GetExtendedStyle`	Recupera los estilos extendidos que usa el control de vista de árbol actual.
`CTreeCtrl::GetFirstVisibleItem`	Recupera el primer elemento visible del elemento de vista de árbol especificado.
`CTreeCtrl::GetImageList`	Recupera el identificador de la lista de imágenes asociada a un control de vista de árbol.
`CTreeCtrl::GetIndent`	Recupera el desplazamiento (en píxeles) de un elemento de vista de árbol de su elemento primario.
`CTreeCtrl::GetInsertMarkColor`	Recupera el color utilizado para dibujar la marca de inserción de la vista de árbol.
`CTreeCtrl::GetItem`	Recupera los atributos de un elemento de vista de árbol especificado.
`CTreeCtrl::GetItemData`	Devuelve el valor específico de la aplicación asociado a un elemento.
`CTreeCtrl::GetItemExpandedImageIndex`	Recupera el índice de la imagen que se va a mostrar cuando el elemento especificado del control de vista de árbol actual está en estado expandido.
`CTreeCtrl::GetItemHeight`	Recupera el alto actual de los elementos de vista de árbol.
`CTreeCtrl::GetItemImage`	Recupera las imágenes asociadas a un elemento.
`CTreeCtrl::GetItemPartRect`	Recupera el rectángulo delimitador de una parte especificada de un elemento especificado en el control de vista de árbol actual.
`CTreeCtrl::GetItemRect`	Recupera el rectángulo delimitador de un elemento de vista de árbol.
`CTreeCtrl::GetItemState`	Devuelve el estado de un elemento.
`CTreeCtrl::GetItemStateEx`	Recupera el estado extendido del elemento especificado en el control de vista de árbol actual.
`CTreeCtrl::GetItemText`	Devuelve el texto de un elemento.
`CTreeCtrl::GetLastVisibleItem`	Recupera el último elemento expandido en el control de vista de árbol actual.
`CTreeCtrl::GetLineColor`	Recupera el color de línea actual para el control de vista de árbol.
`CTreeCtrl::GetNextItem`	Recupera el siguiente elemento de vista de árbol que coincide con una relación especificada.
`CTreeCtrl::GetNextSiblingItem`	Recupera el siguiente elemento del mismo nivel del elemento de vista de árbol especificado.
`CTreeCtrl::GetNextVisibleItem`	Recupera el siguiente elemento visible del elemento de vista de árbol especificado.
`CTreeCtrl::GetParentItem`	Recupera el elemento primario del elemento de vista de árbol especificado.
`CTreeCtrl::GetPrevSiblingItem`	Recupera el elemento previo del mismo nivel del elemento de vista de árbol especificado.
`CTreeCtrl::GetPrevVisibleItem`	Recupera el elemento previo visible del elemento de vista de árbol especificado.
`CTreeCtrl::GetRootItem`	Recupera la raíz del elemento de vista de árbol especificado.
`CTreeCtrl::GetScrollTime`	Recupera el tiempo de desplazamiento máximo para el control de vista de árbol.
`CTreeCtrl::GetSelectedCount`	Recupera el número de elementos seleccionados en el control de vista de árbol actual.
`CTreeCtrl::GetSelectedItem`	Recupera el elemento de vista de árbol seleccionado actualmente.
`CTreeCtrl::GetTextColor`	Recupera el color de texto actual del control.
`CTreeCtrl::GetToolTips`	Recupera el identificador del control secundario `ToolTip` utilizado por un control de vista de árbol.
`CTreeCtrl::GetVisibleCount`	Recupera el número de elementos de árbol visibles asociados a un control de vista de árbol.
`CTreeCtrl::HitTest`	Devuelve la posición actual del cursor en relación con el objeto `CTreeCtrl`.
`CTreeCtrl::InsertItem`	Inserta un nuevo elemento en un control de vista de árbol.
`CTreeCtrl::ItemHasChildren`	Devuelve un valor distinto de cero si el elemento especificado tiene elementos secundarios.
`CTreeCtrl::MapAccIdToItem`	Asigna el identificador de accesibilidad especificado al identificador de un elemento de vista de árbol en el control de vista de árbol actual.
`CTreeCtrl::MapItemToAccID`	Asigna el identificador especificado a un elemento de vista de árbol en el control de vista de árbol actual a un identificador de accesibilidad.
`CTreeCtrl::Select`	Selecciona, se desplaza hacia la vista o vuelve a dibujar un elemento de vista de árbol especificado.
`CTreeCtrl::SelectDropTarget`	Vuelve a dibujar el elemento de árbol como destino de una operación de arrastrar y colocar.
`CTreeCtrl::SelectItem`	Selecciona un elemento de vista de árbol especificado.
`CTreeCtrl::SelectSetFirstVisible`	Selecciona un elemento de vista de árbol especificado como primer elemento visible.
`CTreeCtrl::SetAutoscrollInfo`	Establece la velocidad de inscripción automática del control de vista de árbol actual.
`CTreeCtrl::SetBkColor`	Establece el color de fondo del control.
`CTreeCtrl::SetCheck`	Establece el estado de comprobación de un elemento de control de árbol.
`CTreeCtrl::SetExtendedStyle`	Establece los estilos extendidos para el control de vista de árbol actual.
`CTreeCtrl::SetImageList`	Establece el identificador de la lista de imágenes asociada a un control de vista de árbol.
`CTreeCtrl::SetIndent`	Establece el desplazamiento (en píxeles) de un elemento de vista de árbol de su elemento primario.
`CTreeCtrl::SetInsertMark`	Establece la marca de inserción en un control de vista de árbol.
`CTreeCtrl::SetInsertMarkColor`	Establece el color utilizado para dibujar la marca de inserción de la vista de árbol.
`CTreeCtrl::SetItem`	Establece los atributos de un elemento de vista de árbol especificado.
`CTreeCtrl::SetItemData`	Establece el valor específico de la aplicación asociado a un elemento.
`CTreeCtrl::SetItemExpandedImageIndex`	Establece el índice de la imagen que se va a mostrar cuando el elemento especificado del control de vista de árbol actual está en estado expandido.
`CTreeCtrl::SetItemHeight`	Establece el alto de los elementos de la vista de árbol.
`CTreeCtrl::SetItemImage`	Asocia imágenes a un elemento.
`CTreeCtrl::SetItemState`	Establece el estado de un elemento.
`CTreeCtrl::SetItemStateEx`	Establece el estado extendido del elemento especificado en el control de vista de árbol actual.
`CTreeCtrl::SetItemText`	Establece el texto de un elemento.
`CTreeCtrl::SetLineColor`	Establece el color de línea actual para el control de vista de árbol.
`CTreeCtrl::SetScrollTime`	Establece el tiempo de desplazamiento máximo para el control de vista de árbol.
`CTreeCtrl::SetTextColor`	Establece el color de texto del control.
`CTreeCtrl::SetToolTips`	Establece el control secundario `ToolTip` de un control de vista de árbol.
`CTreeCtrl::ShowInfoTip`	Muestra la información sobre el elemento especificado en el control de vista de árbol actual.
`CTreeCtrl::SortChildren`	Ordena los elementos secundarios de un elemento primario determinado.
`CTreeCtrl::SortChildrenCB`	Ordena los elementos secundarios de un elemento primario determinado mediante una función de ordenación definida por la aplicación.

Comentarios

Un "control de vista de árbol" es una ventana que muestra una lista jerárquica de elementos, como los encabezados de un documento, las entradas de un índice o los archivos y directorios de un disco. Cada elemento consta de una etiqueta y una imagen de mapa de bits opcional, y cada elemento puede tener una lista de subelementos asociados. Al hacer clic en un elemento, el usuario puede expandir y contraer la lista asociada de subelementos.

Este control (y, por tanto, la clase CTreeCtrl) solo está disponible con los programas que se ejecutan en Windows 98 y Windows NT 4 y versiones posteriores.

Para obtener más información sobre el uso de CTreeCtrl, vea:

Controles
Uso de CTreeCtrl
Referencia de control de vista de árbol en Windows SDK.

Jerarquía de herencia

CObject

CCmdTarget

CWnd

CTreeCtrl

Requisitos

Encabezado: afxcmn.h

`CTreeCtrl::Create`

Si especifica el control de árbol en una plantilla de cuadro de diálogo, o si usa CTreeView, el control de árbol se crea automáticamente cuando se crea el cuadro de diálogo o la vista.

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

Parámetros

dwStyle
Especifica el estilo del control de vista de árbol. Aplique estilos de ventana, descritos en CreateWindow y cualquier combinación de estilos de control de vista de árbol como se describe en Windows SDK.

rect
Especifica el tamaño y la posición del control de vista de árbol. Puede ser un objeto CRect o una estructura RECT.

pParentWnd
Especifica la ventana primaria del control de vista de árbol, normalmente CDialog. Este valor no debe ser NULL.

nID
Especifica el ID del control de vista de árbol.

Valor devuelto

Es distinto de cero si la inicialización se realiza correctamente; de lo contrario,es 0.

Comentarios

Si desea crear el control de árbol como una ventana secundaria de alguna otra ventana, use la función miembro Create. Si crea el control de árbol mediante Create, debe pasarlo WS_VISIBLE, además de otros estilos de vista de árbol.

El proceso de construcción de un elemento CTreeCtrl se divide en dos pasos. En primer lugar, llame al constructor, luego, a Create, lo que crea el control de vista de árbol y lo asocia al objeto CTreeCtrl.

Para crear un control de árbol con estilos de ventana extendidos, llame a CreateEx en lugar de a Create.

Ejemplo

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

Llame a esta función para crear un control (una ventana secundaria) y asociarlo al objeto CTreeCtrl.

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

Parámetros

dwExStyle
El valor de este parámetro se usa para especificar el estilo extendido del control que se va a crear. Para obtener una lista de estilos extendidos de Windows, consulte el parámetro dwExStyle de la función CreateWindowEx en Windows SDK.

rect
Una referencia a una estructura RECT describiendo el tamaño y la posición de la ventana a crear, en las coordenadas cliente de pParentWnd.

pParentWnd
Un puntero a la ventana que constituye el elemento primario del control.

nID
El identificador de ventana secundaria del control.

Valor devuelto

Distinto de cero si se realiza correctamente; de lo contrario, 0.

Comentarios

Usa la función CreateEx, en lugar de Create, para aplicar estilos extendidos de Windows. Estos se especifican en el prefacio de estilo extendido WS_EX_ de Windows.

`CTreeCtrl::CreateDragImage`

Llame a esta función para crear un mapa de bits de arrastre para el elemento especificado en un control de vista de árbol, cree una lista de imágenes para el mapa de bits y agregue el mapa de bits a la lista de imágenes.

CImageList* CreateDragImage(HTREEITEM hItem);

Parámetros

hItem
Identificador del elemento de árbol que se va a arrastrar.

Valor devuelto

Puntero a la lista de imágenes a la que se agregó el mapa de bits de arrastre, si se realiza correctamente; de lo contrario NULL.

Comentarios

Una aplicación usa las funciones image-list para mostrar la imagen cuando se arrastra el elemento.

El objeto CImageList es permanente y debe eliminarlo cuando termine. Por ejemplo:

HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();

CImageList *pImageList = m_TreeCtrl.CreateDragImage(hItem);

// Do something with the image list.

delete pImageList;

`CTreeCtrl::CTreeCtrl`

Construye un objeto CTreeCtrl.

CTreeCtrl();

`CTreeCtrl::DeleteAllItems`

Llame a esta función para eliminar todos los elementos del control de vista de árbol.

BOOL DeleteAllItems();

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Ejemplo

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

`CTreeCtrl::DeleteItem`

Llame a esta función para eliminar un elemento del control de vista de árbol.

BOOL DeleteItem(HTREEITEM hItem);

Parámetros

hItem
Identificador del elemento de árbol que se va a eliminar. Si hitem tiene el valor TVI_ROOT, todos los elementos se eliminan del control de vista de árbol.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Ejemplo

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

Llame a esta función para comenzar la edición local del texto del elemento especificado.

CEdit* EditLabel(HTREEITEM hItem);

Parámetros

hItem
Identificador del elemento de árbol que se va a editar.

Valor devuelto

Si se ejecuta correctamente, un puntero apunta al objeto CEdit que se usa para editar el texto del elemento, de lo contrario NULL.

Comentarios

La edición se realiza reemplazando el texto del elemento por un control de edición de una sola línea que contiene el texto.

Ejemplo

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

Concluye la operación de edición en la etiqueta de un elemento de vista de árbol en el control de vista de árbol actual.

BOOL EndEditLabelNow(BOOL fCancelWithoutSave);

Parámetros

fCancelWithoutSave
[in] TRUE para descartar los cambios en el elemento de vista de árbol antes de finalizar la operación de edición, o FALSE para guardar los cambios en el elemento de vista de árbol antes de finalizar la operación.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Al usar este método, se envía el mensaje TVM_ENDEDITLABELNOW, que se describe en Windows SDK.

`CTreeCtrl::EnsureVisible`

Llame a esta función para asegurarse de que un elemento de vista de árbol esté visible.

BOOL EnsureVisible(HTREEITEM hItem);

Parámetros

hItem
Identificador del elemento de árbol que se está haciendo visible.

Valor devuelto

Devuelve TRUE si el sistema ha desplazado los elementos del control de vista de árbol para asegurarse de que el elemento especificado está visible. De lo contrario, el valor devuelto es FALSE.

Comentarios

Si es necesario, la función expande el elemento primario o desplaza el control de vista de árbol para que el elemento esté visible.

Ejemplo

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`

Llame a esta función para expandir o contraer la lista de elementos secundarios, si existe, asociada al elemento primario especificado.

BOOL Expand(
    HTREEITEM hItem,
    UINT nCode);

Parámetros

hItem
Identificador del elemento de árbol que se va a expandir.

nCode
Marca que indica el tipo de acción que se va a realizar. Esta marca puede tener uno de los siguientes valores:

TVE_COLLAPSE Contrae la lista.
TVE_COLLAPSERESET Contrae la lista y quita los elementos secundarios. Se restablece la marca de estado TVIS_EXPANDEDONCE. Esta marca debe usarse con la marca TVE_COLLAPSE.
TVE_EXPAND Expande la lista.
TVE_TOGGLE Contrae la lista si está expandida actualmente o la expande si está contraída actualmente.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Ejemplo

Vea el ejemplo de CTreeCtrl::EnsureVisible.

`CTreeCtrl::GetBkColor`

En esta función miembro, se implementa el comportamiento del mensaje TVM_GETBKCOLOR de Win32, tal y como se describe en Windows SDK.

COLORREF GetBkColor() const;

Valor devuelto

Valor COLORREF que representa el color de fondo de la ventana actual para el control. Si este valor es -1, el control usa el color de la ventana del sistema. En este caso, puede usar ::GetSysColor(COLOR_WINDOW) para obtener el color actual del sistema que usa el control.

Ejemplo

Vea el ejemplo de CTreeCtrl::SetTextColor.

`CTreeCtrl::GetCheck`

Llame a esta función miembro para recuperar el estado de comprobación de un elemento.

BOOL GetCheck(HTREEITEM hItem) const;

Parámetros

hItem
La HTREEITEM sobre la que se va a recibir la información de estado.

Valor devuelto

Distinto de cero si se comprueba el elemento de control de árbol; de lo contrario, 0.

Ejemplo

Vea el ejemplo de CTreeCtrl::SetCheck.

`CTreeCtrl::GetChildItem`

Llame a esta función para recuperar el elemento de vista de árbol que es el elemento secundario del elemento especificado por hItem.

HTREEITEM GetChildItem(HTREEITEM hItem) const;

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

Identificador del elemento secundario si se realiza correctamente; de lo contrario NULL.

Ejemplo

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`

Llame a esta función para recuperar un recuento de los elementos de un control de vista de árbol.

UINT GetCount() const;

Valor devuelto

Número de elementos del control de vista de árbol.

Ejemplo

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

`CTreeCtrl::GetDropHilightItem`

Llame a esta función para recuperar el elemento que es el destino de una operación de arrastrar y colocar.

HTREEITEM GetDropHilightItem() const;

Valor devuelto

Identificador del elemento quitado si se ejecuta correctamente; de lo contrario NULL.

Ejemplo

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

Llame a esta función para recuperar el identificador del control de edición que se usa para editar el texto de un elemento de vista de árbol.

CEdit* GetEditControl() const;

Valor devuelto

Puntero al control de edición utilizado para editar el texto del elemento, si se ejecuta correctamente; de lo contrario NULL.

Ejemplo

// 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 los estilos extendidos que usa el control de vista de árbol actual.

DWORD GetExtendedStyle() const;

Valor devuelto

Valor que contiene una combinación bit a bit (OR) de los estilos extendidos del control de vista de árbol actual. Para obtener más información, vea Estilos extendidos de control de vista de árbol.

Comentarios

Al usar este método, se envía el mensaje TVM_GETEXTENDEDSTYLE, que se describe en Windows SDK.

`CTreeCtrl::GetFirstVisibleItem`

Llame a esta función para recuperar el primer elemento visible del control de vista de árbol.

HTREEITEM GetFirstVisibleItem() const;

Valor devuelto

Identificador del primer elemento visible; de lo contrario NULL.

Ejemplo

Vea el ejemplo de CTreeCtrl::SetCheck.

`CTreeCtrl::GetImageList`

Llame a esta función para recuperar el identificador de la lista de imágenes de estado o normal asociada al control de vista de árbol.

CImageList* GetImageList(UINT nImageList) const;

Parámetros

nImageList
Tipo de lista de imágenes que se va a recuperar. La lista de imágenes puede ser uno de los siguientes valores:

TVSIL_NORMAL Recupera la lista de imágenes normales, que contiene las imágenes seleccionadas y no seleccionadas para el elemento de vista de árbol.
TVSIL_STATE Recupera la lista de imágenes de estado, que contiene las imágenes para los elementos de vista de árbol que están en un estado definido por el usuario.

Valor devuelto

Puntero a la lista de imágenes del control si se ejecuta correctamente; de lo contrario NULL.

Comentarios

Cada elemento de un control de vista de árbol puede tener un par de imágenes con mapa de bits asociadas. Se muestra una imagen cuando se selecciona el elemento y la otra se muestra cuando el elemento no está seleccionado. Por ejemplo, un elemento podría mostrar una carpeta abierta cuando está seleccionada y una carpeta cerrada cuando no está seleccionada.

Para obtener más información sobre las listas de imágenes, vea la clase CImageList.

Ejemplo

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

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

`CTreeCtrl::GetIndent`

Llame a esta función para recuperar la cantidad, en píxeles, que los elementos secundarios tienen sangría en relación con sus elementos primarios.

UINT GetIndent() const;

Valor devuelto

Cantidad de sangría medida en píxeles.

Ejemplo

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

`CTreeCtrl::GetInsertMarkColor`

En esta función miembro, se implementa el comportamiento del mensaje TVM_GETINSERTMARKCOLOR de Win32, tal y como se describe en Windows SDK.

COLORREF GetInsertMarkColor() const;

Valor devuelto

Un valor COLORREF que contiene el color de la marca de inserción actual.

Ejemplo

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

Llame a esta función para recuperar los atributos del elemento de vista de árbol especificado.

BOOL GetItem(TVITEM* pItem) const;

Parámetros

pItem
Puntero a una estructura TVITEM, como se describe en Windows SDK.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Ejemplo

Vea el ejemplo de CTreeCtrl::DeleteItem.

`CTreeCtrl::GetItemData`

Llame a esta función para recuperar el valor específico de la aplicación asociado al elemento especificado.

DWORD_PTR GetItemData(HTREEITEM hItem) const;

Parámetros

hItem
Identificador del elemento cuyos datos se van a recuperar.

Valor devuelto

Valor específico de la aplicación de tamaño de puntero asociado al elemento especificado por hItem.

Ejemplo

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 el índice de la imagen que se va a mostrar cuando el elemento especificado del control de vista de árbol actual está en estado expandido.

int GetItemExpandedImageIndex(HTREEITEM hItem)const;

Parámetros

hItem
[in] Identificador de un elemento de control de vista de árbol.

Valor devuelto

Índice de la imagen que se va a mostrar cuando el elemento especificado está en estado expandido.

Comentarios

Al usar este método, se envía el mensaje TVM_GETITEM, que se describe en Windows SDK. Ese mensaje devuelve la estructura TVITEMEX que describe el elemento de control de vista de árbol y, a continuación, este método recupera el miembro iExpandedImage de esa estructura.

`CTreeCtrl::GetItemHeight`

En esta función miembro, se implementa el comportamiento del mensaje TVM_GETITEMHEIGHT de Win32, tal y como se describe en Windows SDK.

SHORT GetItemHeight() const;

Valor devuelto

Alto del elemento, en píxeles.

Ejemplo

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

`CTreeCtrl::GetItemImage`

Cada elemento de un control de vista de árbol puede tener un par de imágenes con mapa de bits asociadas.

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

Parámetros

hItem
El identificador del elemento cuya imagen se va a recuperar.

nImage
Entero que recibe el índice de la imagen del elemento dentro de la lista de imágenes del control de vista de árbol.

nSelectedImage
Entero que recibe el índice de la imagen seleccionada del elemento dentro de la lista de imágenes del control de vista de árbol.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Las imágenes aparecen en el lado izquierdo de la etiqueta de un elemento. Se muestra una imagen cuando se selecciona el elemento y la otra se muestra cuando el elemento no está seleccionado. Por ejemplo, un elemento podría mostrar una carpeta abierta cuando está seleccionada y una carpeta cerrada cuando no está seleccionada.

Llame a esta función para recuperar el índice de la imagen del elemento y su imagen seleccionada dentro de la lista de imágenes del control de vista de árbol.

Ejemplo

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 el rectángulo delimitador de una parte especificada de un elemento especificado en el control de vista de árbol actual.

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

Parámetros

hItem
[in] Identificador de un elemento de control de vista de árbol.

nPart
[in] Identificador del elemento. Se debe establecer en TVGIPR_BUTTON.

lpRect
[out] Puntero a una estructura RECT. Si este método se realiza correctamente, la estructura recibe las coordenadas del rectángulo de la parte especificada por hItem y nPart.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Cada elemento de control de árbol está limitado por un rectángulo de gráficos. Cada vez que se hace clic en un punto de ese rectángulo, se dice que se alcanza el elemento. Este método devuelve el rectángulo más grande de modo que, cuando se hace clic en un punto del rectángulo, se alcanza el elemento identificado por el parámetro hItem.

Al usar este método, se envía el mensaje TVM_GETITEMPARTRECT, que se describe en Windows SDK. Para más información, consulte la macro TreeView_GetItemPartRect.

Ejemplo

En el primer ejemplo de código se define una variable, m_treeCtrl, que se usa para acceder al control de vista de árbol actual. El ejemplo de código también define un entero sin signo y varias variables HTREEITEM. Estas variables se usan en el ejemplo siguiente.

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;

En el ejemplo de código siguiente se usa un identificador de accesibilidad y el método CTreeCtrl::MapAccIdToItem para recuperar un identificador para el elemento raíz de vista de árbol. A continuación, en el ejemplo se usa el identificador y el método CTreeCtrl::GetItemPartRect para dibujar un rectángulo 3D alrededor de ese elemento. En una sección anterior del ejemplo de código, que no se muestra, creamos una vista de árbol que consta de un nodo de país o región raíz para el Estados Unidos, subnodos para los estados de Pennsylvania y Washington, y elementos de árbol para ciudades de esos estados. Hemos usado el método CTreeCtrl::MapItemToAccID para asociar el elemento de vista de árbol raíz con un identificador de accesibilidad.

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`

Llame a esta función para recuperar el rectángulo delimitador de hItem y determinar si está visible o no.

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

Parámetros

hItem
Identificador de un elemento de control de vista de árbol.

lpRect
Puntero a una estructura RECT que recibe el rectángulo delimitador. Las coordenadas son relativas a la esquina superior izquierda del control de vista de árbol.

bTextOnly
Si este parámetro es distinto de cero, el rectángulo delimitador solo incluye el texto del elemento. De lo contrario, incluye toda la línea que ocupa el elemento en el control de vista de árbol.

Valor devuelto

Distinto de cero si el elemento es visible, con el rectángulo delimitador contenido en lpRect. De lo contrario, 0 con lpRect sin inicializar.

Ejemplo

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`

Devuelve el estado del elemento especificado por hItem.

UINT GetItemState(
    HTREEITEM hItem,
    UINT nStateMask) const;

Parámetros

hItem
Identificador del elemento cuyo estado se va a recuperar.

nStateMask
Máscara que indica uno o varios estados que se van a recuperar. Para obtener más información sobre los valores posibles para nStateMask, vea la explicación de los miembros state y stateMask de la estructura TVITEM en Windows SDK.

Valor devuelto

Un UINT contiene el operador OR bit a bit de C++ (|) de los valores especificados por nStateMask. Para obtener información sobre los valores posibles, consulte CTreeCtrl::GetItem. Para buscar el valor de un estado específico, realice un operador AND bit a bit de C++ (&) f el valor de estado y el valor devuelto, como se muestra en el ejemplo siguiente.

Ejemplo

// 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 el estado extendido del elemento especificado en el control de vista de árbol actual.

UINT GetItemStateEx(HTREEITEM hItem) const;

Parámetros

hItem
[in] Identificador de un elemento de control de vista de árbol.

Valor devuelto

Estado extendido del elemento. Para obtener más información, consulte el miembro uStateEx de la estructura TVITEMEX.

Comentarios

`CTreeCtrl::GetItemText`

Devuelve el texto del elemento especificado por hItem.

CString GetItemText(HTREEITEM hItem) const;

Parámetros

hItem
Identificador del elemento cuyo texto se va a recuperar.

Valor devuelto

Objeto CString que contiene el texto del elemento.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetNextItem.

`CTreeCtrl::GetLastVisibleItem`

Recupera el último elemento de nodo sin expandir en el control de vista de árbol actual.

HTREEITEM GetLastVisibleItem() const;

Valor devuelto

Identificador del último elemento de nodo sin expandir si el método es correcto; de lo contrario, NULL.

Comentarios

Al usar este método, se envía el mensaje TVM_GETNEXTITEM, que se describe en Windows SDK. Para obtener más información, vea la marca TVGN_LASTVISIBLE en el parámetro flag de ese mensaje.

Ejemplo

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;

En el siguiente ejemplo de código se recupera un identificador del último elemento de nodo de vista de árbol sin expandir y, a continuación, se dibuja un rectángulo 3D alrededor de ese elemento. En una sección anterior del ejemplo de código, que no se muestra, creamos una vista de árbol que consta de un nodo de país o región raíz para el Estados Unidos, subnodos para los estados de Pennsylvania y Washington, y elementos de árbol para ciudades de esos 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`

En esta función miembro, se implementa el comportamiento del mensaje TVM_GETLINECOLOR de Win32, tal y como se describe en Windows SDK.

COLORREF GetLineColor() const;

Valor devuelto

El color de línea actual.

Ejemplo

COLORREF cr = m_TreeCtrl.GetLineColor();

`CTreeCtrl::GetNextItem`

Llame a esta función para recuperar el elemento de vista de árbol que tiene la relación especificada, indicada por el parámetro nCode, en hItem.

HTREEITEM GetNextItem(
    HTREEITEM hItem,
    UINT nCode) const;

Parámetros

hItem
Identificador de un elemento de árbol.

nCode
Marca que indica el tipo de relación con hItem. Esta marca puede ser uno de los siguientes valores:

TVGN_CARET Recupera el elemento seleccionado actualmente.
TVGN_CHILD Recupera el primer elemento secundario del elemento especificado por el parámetro hItem.
TVGN_DROPHILITE Recupera el elemento que es el destino de una operación de arrastrar y colocar.
TVGN_FIRSTVISIBLE Recupera el primer elemento visible.
TVGN_LASTVISIBLE Recupera el último elemento expandido del árbol. Esto no recupera el último elemento visible en la ventana de vista de árbol.
TVGN_NEXT Recupera el siguiente elemento relacionado.
TVGN_NEXTVISIBLE Recupera el siguiente elemento visible que sigue al elemento especificado.
TVGN_PARENT Recupera el elemento primario del elemento de vista de árbol especificado.
TVGN_PREVIOUS Recupera el elemento relacionado anterior.
TVGN_PREVIOUSVISIBLE Recupera el primer elemento visible que precede al elemento especificado.
TVGN_ROOT Recupera el primer elemento secundario del elemento raíz del que forma parte el elemento especificado.

Valor devuelto

Identificador del siguiente elemento si se realiza correctamente; de lo contrario NULL.

Comentarios

Esta función devolverá NULL si el elemento que se va a recuperar es el nodo raíz del árbol. Por ejemplo, si usa este mensaje con la marca TVGN_PARENT en un elemento secundario de primer nivel del nodo raíz de la vista de árbol, el mensaje devolverá NULL.

Ejemplo

Para obtener un ejemplo de uso de GetNextItem en un bucle, 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`

Llame a esta función para recuperar el siguiente elemento del mismo nivel de hItem.

HTREEITEM GetNextSiblingItem(HTREEITEM hItem) const;

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

Identificador del siguiente elemento relacionado; de lo contrario, NULL.

Ejemplo

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`

Llame a esta función para recuperar el siguiente elemento del mismo nivel de hItem.

HTREEITEM GetNextVisibleItem(HTREEITEM hItem) const;

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

Identificador del primer elemento visible; de lo contrario NULL.

Ejemplo

Vea el ejemplo de CTreeCtrl::SetCheck.

`CTreeCtrl::GetParentItem`

Llame a esta función para recuperar el elemento primario de hItem.

HTREEITEM GetParentItem(HTREEITEM hItem) const;

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

Identificador del elemento primario; de lo contrario, NULL.

Comentarios

Esta función devolverá NULL si el elemento primario del elemento especificado es el nodo raíz del árbol.

Ejemplo

Vea el ejemplo de CTreeCtrl::EnsureVisible.

`CTreeCtrl::GetPrevSiblingItem`

Llame a esta función para recuperar el elemento del mismo nivel anterior de hItem.

HTREEITEM GetPrevSiblingItem(HTREEITEM hItem) const;

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

El identificador del hermano anterior; de lo contrario, NULL.

Ejemplo

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`

Llame a esta función para recuperar el elemento visible anterior de hItem.

HTREEITEM GetPrevVisibleItem(HTREEITEM hItem) const;

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

Identificador del elemento visible anterior; de lo contrario NULL.

Ejemplo

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`

Llame a esta función para recuperar el elemento raíz del control de vista de árbol.

HTREEITEM GetRootItem() const;

Valor devuelto

Identificador del elemento raíz; de lo contrario, NULL.

Ejemplo

Vea el ejemplo de CTreeCtrl::EditLabel.

`CTreeCtrl::GetScrollTime`

Llame a esta función miembro para recuperar el tiempo máximo de desplazamiento del control de vista de árbol.

UINT GetScrollTime() const;

Valor devuelto

El tiempo máximo de desplazamiento, en milisegundos.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje TVM_GETSCROLLTIME de Win32, tal y como se describe en Windows SDK.

`CTreeCtrl::GetSelectedCount`

Recupera el número de elementos seleccionados en el control de vista de árbol actual.

UINT GetSelectedCount();

Valor devuelto

Número de elementos del control seleccionados.

Comentarios

Al usar este método, se envía el mensaje TVM_GETSELECTEDCOUNT, que se describe en Windows SDK.

`CTreeCtrl::GetSelectedItem`

Llame a esta función para recuperar el elemento seleccionado actualmente del control de vista de árbol.

HTREEITEM GetSelectedItem() const;

Valor devuelto

Identificador del elemento seleccionado; de lo contrario, NULL.

Ejemplo

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

En esta función miembro, se implementa el comportamiento del mensaje TVM_GETTEXTCOLOR de Win32, tal y como se describe en Windows SDK.

COLORREF GetTextColor() const;

Valor devuelto

Un valor COLORREF que representa el color de texto actual. Si este valor es -1, el control usa el color del sistema para el color del texto.

Ejemplo

Vea el ejemplo de CTreeCtrl::SetTextColor.

`CTreeCtrl::GetToolTips`

En esta función miembro, se implementa el comportamiento del mensaje TVM_GETTOOLTIPS de Win32, tal y como se describe en Windows SDK.

CToolTipCtrl* GetToolTips() const;

Valor devuelto

Puntero que apunta a un objeto CToolTipCtrl que va a usar el control de árbol. Si la función miembro Create usa el estilo TVS_NOTOOLTIPS, no se usa ninguna información sobre herramientas y se devuelve NULL.

Comentarios

La implementación de MFC de GetToolTips devuelve un objeto CToolTipCtrl, que usa el control de árbol, en lugar de un manipulador para un control de información sobre herramientas.

Ejemplo

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

Llame a esta función para recuperar un recuento de los elementos visibles de un control de vista de árbol.

UINT GetVisibleCount() const;

Valor devuelto

Número de elementos visibles en el control de vista de árbol; de lo contrario - 1.

Ejemplo

Vea el ejemplo de CTreeCtrl::SetCheck.

`CTreeCtrl::HitTest`

Llame a esta función para determinar la ubicación del punto especificado en relación con el área cliente de un control de vista de árbol.

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

HTREEITEM HitTest(TVHITTESTINFO* pHitTestInfo) const;

Parámetros

pt
Coordenadas de cliente del punto que se va a probar.

pFlags
Puntero que apunta a un entero que recibe información sobre los resultados de la prueba de posicionamiento. Puede ser uno o varios de los valores enumerados en el miembro flags de la sección Comentarios.

pHitTestInfo
Dirección de una estructura TVHITTESTINFO que contiene la posición de la prueba de posicionamiento y que recibe información sobre los resultados de la prueba de posicionamiento.

Valor devuelto

Identificador del elemento de vista de árbol que ocupa el punto especificado o NULL si ningún elemento ocupa el punto.

Comentarios

Cuando se llama a esta función, el parámetro pt especifica las coordenadas del punto que se va a probar. La función devuelve el identificador del elemento en el punto especificado o NULL si ningún elemento ocupa el punto. Además, el parámetro pFlags contiene un valor que indica la ubicación del punto especificado. Los valores posibles son:

Valor	Descripción
`TVHT_ABOVE`	Encima del área de cliente.
`TVHT_BELOW`	Debajo del área de cliente.
`TVHT_NOWHERE`	En el área cliente, pero debajo del último elemento.
`TVHT_ONITEM`	En el mapa de bits o la etiqueta asociados a un elemento.
`TVHT_ONITEMBUTTON`	En el botón asociado a un elemento.
`TVHT_ONITEMICON`	En el mapa de bits asociado a un elemento.
`TVHT_ONITEMINDENT`	En la sangría asociada a un elemento.
`TVHT_ONITEMLABEL`	En la etiqueta (cadena) asociada a un elemento.
`TVHT_ONITEMRIGHT`	En el área situada a la derecha de un elemento.
`TVHT_ONITEMSTATEICON`	En el icono de estado de un elemento de vista de árbol que se encuentra en un estado definido por el usuario.
`TVHT_TOLEFT`	A la izquierda del área de cliente.
`TVHT_TORIGHT`	A la derecha del área de cliente.

Ejemplo

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

Llame a esta función para insertar un nuevo elemento en un control de vista de árbol.

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
Puntero a un objeto TVINSERTSTRUCT que especifica los atributos del elemento de vista de árbol que se va a insertar.

nMask
Entero que especifica qué atributos se van a establecer. Consulte la estructura TVITEM en Windows SDK.

lpszItem
Dirección de una cadena que contiene el texto del elemento.

nImage
Índice de la imagen del elemento en la lista de imágenes del control de vista de árbol.

nSelectedImage
Índice de la imagen seleccionada del elemento en la lista de imágenes del control de vista de árbol.

nState
Especifica valores para los estados del elemento. Consulte Estados de elementos de control de vista de árbol en Windows SDK para obtener una lista de los estados adecuados.

nStateMask
Especifica qué estados se van a establecer. Consulte la estructura TVITEM en Windows SDK.

lParam
Valor específico de la aplicación de tamaño de puntero asociado al elemento.

hParent
Identificador del elemento primario del elemento insertado.

hInsertAfter
Identificador del elemento después del cual se va a insertar el nuevo elemento.

Valor devuelto

Identificador del nuevo elemento si se realiza correctamente; de lo contrario, NULL.

Comentarios

En el ejemplo se muestran situaciones en las que es posible que desee usar cada versión de la función al insertar un elemento de control de árbol.

Ejemplo

// 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 esta función para determinar si el elemento de árbol especificado por hItem tiene elementos secundarios.

BOOL ItemHasChildren(HTREEITEM hItem) const;

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

Distinto de cero si el elemento de árbol especificado por hItem tiene elementos secundarios; 0 si no lo hace.

Comentarios

Si es así, puede usar CTreeCtrl::GetChildItem para recuperar esos elementos secundarios.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetSelectedItem.

`CTreeCtrl::MapAccIdToItem`

Asigna el identificador de accesibilidad especificado al identificador de un elemento de vista de árbol en el control de vista de árbol actual.

HTREEITEM MapAccIdToItem(UINT uAccId) const;

Parámetros

uAccId
[in] Identificador de accesibilidad de un elemento del elemento de vista de árbol.

Valor devuelto

Identificador de un elemento de vista de árbol (HTREEITEM) que corresponde al parámetro uAccId. Para obtener más información, consulte el miembro hItem de la estructura TVITEMEX.

Comentarios

Las ayuda de accesibilidad son aplicaciones que ayudan a las personas con discapacidades a usar equipos. La interfaz IAccessible usa un identificador de accesibilidad para especificar de forma única un elemento en una ventana. Para obtener más información sobre las API IAccessible, consulte Microsoft Active Accessibility.

Al usar este método, se envía el mensaje TVM_MAPACCIDTOHTREEITEM, que se describe en Windows SDK.

Ejemplo

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;

En el ejemplo de código siguiente se usa un identificador de accesibilidad y el método CTreeCtrl::MapAccIdToItem para recuperar un identificador para el elemento raíz de vista de árbol. El ejemplo se usa el identificador y el método CTreeCtrl::GetItemPartRect para dibujar un rectángulo 3D alrededor de ese elemento. En una sección anterior del ejemplo de código, que no se muestra, creamos una vista de árbol que consta de un nodo de país o región raíz para el Estados Unidos, subnodos para los estados de Pennsylvania y Washington, y elementos de árbol para ciudades de esos estados. Hemos usado el método CTreeCtrl::MapItemToAccID para asociar el elemento de vista de árbol raíz con un identificador de accesibilidad.

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`

Asigna el identificador especificado de un elemento de vista de árbol en el control de vista de árbol actual a un identificador de accesibilidad.

UINT MapItemToAccID(HTREEITEM hItem) const;

Parámetros

hItem
[in] Identificador de un elemento de vista de árbol en el control. Para obtener más información, consulte el miembro hItem de la estructura TVITEMEX.

Valor devuelto

Identificador de accesibilidad que corresponde al parámetro hItem.

Comentarios

Al usar este método, se envía el mensaje TVM_MAPHTREEITEMTOACCID, que se describe en Windows SDK.

Ejemplo

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;

En el ejemplo de código siguiente se obtiene un número de identificación para un elemento de control de vista de árbol. En una sección anterior del ejemplo de código, que no se muestra, creamos una vista de árbol que consta de un nodo de país o región raíz para el Estados Unidos, subnodos para los estados de Pennsylvania y Washington, y elementos de árbol para ciudades de esos estados. En este ejemplo de código se obtiene un número de identificación único para el nodo de país o región raíz.

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

`CTreeCtrl::Select`

Llame a esta función para seleccionar el elemento de vista de árbol determinado, desplazar el elemento a la vista o volver a dibujar el elemento en el estilo usado para indicar el destino de una operación de arrastrar y colocar.

BOOL Select(
    HTREEITEM hItem,
    UINT nCode);

Parámetros

hItem
Identificador de un elemento de árbol.

nCode
Tipo de acción que se va a realizar. Este parámetro puede establecerse con uno de los siguientes valores:

TVGN_CARET Establece la selección en el elemento especificado.
TVGN_DROPHILITE Vuelve a dibujar el elemento especificado en el estilo usado para indicar el destino de una operación de arrastrar y colocar.
TVGN_FIRSTVISIBLE Desplaza la vista de árbol verticalmente para que el elemento especificado sea el primer elemento visible.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Si nCode contiene el valor TVGN_CARET, la ventana primaria recibe los mensajes de notificación TVN_SELCHANGING y TVN_SELCHANGED. Además, si el elemento especificado es el elemento secundario de un elemento primario contraído, la lista de elementos secundarios del elemento primario se expande para mostrar el elemento especificado. En este caso, la ventana primaria recibe los mensajes de notificación TVN_ITEMEXPANDING y TVN_ITEMEXPANDED.

Ejemplo

Vea el ejemplo de CTreeCtrl::HitTest.

`CTreeCtrl::SelectDropTarget`

Llame a esta función para volver a dibujar el elemento en el estilo usado para indicar el destino de una operación de arrastrar y colocar.

BOOL SelectDropTarget(HTREEITEM hItem);

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Ejemplo

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

Llame a esta función para seleccionar el elemento de vista de árbol especificado.

BOOL SelectItem(HTREEITEM hItem);

Parámetros

hItem
Identificador de un elemento de árbol.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Si hItem es NULL, esta función no selecciona ningún elemento.

Ejemplo

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

Llame a esta función para desplazar la vista de árbol verticalmente para que el elemento especificado sea el primer elemento visible.

BOOL SelectSetFirstVisible(HTREEITEM hItem);

Parámetros

hItem
Identificador del elemento de árbol que se va a establecer como primer elemento visible.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

La función envía un mensaje a la ventana con los parámetros de mensaje TVM_SELECTITEM y TVGN_FIRSTVISIBLE.

Ejemplo

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

Establece la velocidad de inscripción automática del control de vista de árbol actual.

BOOL SetAutoscrollInfo(
    UINT uPixelsPerSec,
    UINT uUpdateTime);

Parámetros

uPixelsPerSec
[in] Número de píxeles por segundo que se va a desplazar.

uUpdateTime
[in] Intervalo de tiempo entre las actualizaciones del control.

Valor devuelto

Siempre devuelve TRUE.

Comentarios

Los parámetros de inscripción automática se usan para desplazarse hacia la vista de un elemento que no está visible actualmente. El control de vista de árbol debe tener el estilo extendido TVS_EX_AUTOHSCROLL, que se describe en Estilos extendidos del control de vista de árbol.

Al usar este método, se envía el mensaje TVM_SETAUTOSCROLLINFO, que se describe en Windows SDK.

Ejemplo

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;

En el siguiente ejemplo de código se establece el comportamiento de la inscripción automática del control de vista de árbol actual. En una sección anterior del ejemplo de código, que no se muestra, creamos una vista de árbol que consta de un nodo de país o región raíz para el Estados Unidos, subnodos para los estados de Pennsylvania y Washington, y elementos de árbol para ciudades de esos estados. Hemos reducido intencionadamente el control de vista de árbol para que se desplace automáticamente para mostrar el elemento de árbol que tiene el foco. En el ejemplo de código se establece que el control de vista de árbol se desplace automáticamente 30 píxeles por segundo cada 5 segundos hasta que el elemento de árbol esté en vista.

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

`CTreeCtrl::SetBkColor`

En esta función miembro, se implementa el comportamiento del mensaje TVM_SETBKCOLOR de Win32, tal y como se describe en Windows SDK.

COLORREF SetBkColor(COLORREF clr);

Parámetros

clr
Un valor COLORREF que especifica el nuevo color de fondo. Si este valor es -1, el control volverá al uso del color del sistema para el color de fondo.

Valor devuelto

Un valor COLORREF que representa el color de texto actual. Si este valor es -1, el control usa el color del sistema para el color del texto.

Ejemplo

Vea el ejemplo de CTreeCtrl::SetTextColor.

`CTreeCtrl::SetCheck`

Llame a esta función miembro para establecer el estado de comprobación de un elemento de control de árbol.

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

Parámetros

hItem
HTREEITEM que se va a recibir el cambio de estado de comprobación.

fCheck
Indica si el elemento de control de árbol se va a comprobar o desactivar. De forma predeterminada, SetCheck establece el elemento que se va a comprobar.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Cuando se activa el elemento de control de árbol (fCheck se establece en TRUE), el elemento aparece con una marca de verificación adyacente.

Ejemplo

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 casillas, establezca TVS_CHECKBOXES antes de rellenar el control de árbol.

m_TreeCtrl.ModifyStyle(0, TVS_CHECKBOXES);

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

`CTreeCtrl::SetExtendedStyle`

Establece los estilos extendidos para el control de vista de árbol actual.

DWORD SetExtendedStyle(
    DWORD dwExMask,
    DWORD dwExStyles);

Parámetros

dwExMask
[in] Máscara de bits que especifica qué estilos del control de vista de árbol actual se ven afectados por este método. Si este parámetro es cero, se omite y el valor del parámetro dwExStyles se asigna al control de vista de árbol. Especifique cero o una combinación bit a bit (OR) de estilos descritos en Estilos extendidos del control de vista de árbol.

dwExStyles
[in] Máscara de bits que especifica qué estilos del control de vista de árbol actual se va a establecer o borrar. Para establecer una combinación de estilos, especifique una combinación bit a bit (OR) de estilos descritos en Estilos extendidos de control de vista de árbol. Para borrar un conjunto de estilos, especifique cero.

Valor devuelto

Valor que contiene los estilos de control extendidos anteriores.

Comentarios

Este método borra los estilos especificados en el parámetro dwExMask y, a continuación, establece los estilos especificados en el parámetro dwExStyles. Solo los estilos extendidos que corresponden a los bits en cambio dwExMask.

Al usar este método, se envía el mensaje TVM_SETEXTENDEDSTYLE, que se describe en Windows SDK.

Ejemplo

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;

En el ejemplo de código siguiente se agrega el estilo extendido TVS_EX_AUTOHSCROLL al control de vista de árbol actual. En una sección anterior del ejemplo de código, que no se muestra, creamos una vista de árbol que consta de un nodo de país o región raíz para el Estados Unidos, subnodos para los estados de Pennsylvania y Washington, y elementos de árbol para ciudades de esos estados. Hemos reducido intencionadamente el control de vista de árbol para que se desplace automáticamente para mostrar el elemento de árbol que tiene el foco.

m_treeCtrl.SetExtendedStyle(TVS_EX_AUTOHSCROLL, TVS_EX_AUTOHSCROLL);

`CTreeCtrl::SetImageList`

Llame a esta función para establecer la lista de imágenes de estado o normal para un control de vista de árbol y volver a dibujar el control mediante las nuevas imágenes.

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

Parámetros

pImageList
Puntero que apunta a la lista de imágenes que se va a asignar. Si pImageList es NULL, todas las imágenes se quitan del control de vista de árbol.

nImageListType
Tipo de lista de imágenes que se va a establecer. La lista de imágenes puede ser uno de los siguientes valores:

TVSIL_NORMAL Establece la lista de imágenes normales, que contiene las imágenes seleccionadas y no seleccionadas para el elemento de vista de árbol. Debe usar este estado para las imágenes de superposición.
TVSIL_STATE Establece la lista de imágenes de estado, que contiene las imágenes para los elementos de vista de árbol que están en un estado definido por el usuario.

Valor devuelto

Puntero a la lista de imágenes anterior, si existe; de lo contrario, NULL.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetImageList.

`CTreeCtrl::SetIndent`

Llame a esta función para establecer el ancho de sangría de un control de vista de árbol y volver a dibujar el control para reflejar el nuevo ancho.

void SetIndent(UINT nIndent);

Parámetros

nIndent
Ancho, en píxeles, de la sangría. Si nIndent es menor que el ancho mínimo definido por el sistema, el nuevo ancho se establece en el mínimo definido por el sistema.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetIndent.

`CTreeCtrl::SetInsertMark`

En esta función miembro, se implementa el comportamiento del mensaje TVM_SETINSERTMARK de Win32, tal y como se describe en Windows SDK.

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

Parámetros

hItem
HTREEITEM que especifica en qué elemento se colocará la marca de inserción. Si este argumento es NULL, se quita la marca de inserción.

fAfter
Valor BOOL que especifica si la marca de inserción se coloca antes o después del elemento especificado. Si este argumento es distinto de cero, la marca de inserción se colocará después del elemento. Si este argumento es cero, la marca de inserción se colocará antes del elemento.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Ejemplo

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

En esta función miembro, se implementa el comportamiento del mensaje TVM_SETINSERTMARKCOLOR de Win32, tal y como se describe en Windows SDK.

COLORREF SetInsertMarkColor(COLORREF clrNew);

Parámetros

clrNew
Un valor COLORREF que contiene el nuevo color de la marca de inserción.

Valor devuelto

Un valor COLORREF que contiene el anterior color de la marca de inserción.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetInsertMarkColor.

`CTreeCtrl::SetItem`

Llame a esta función para establecer los atributos del elemento de vista de árbol 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
Puntero a una estructura TVITEM que contiene los nuevos atributos de elemento, como se describe en Windows SDK.

hItem
Identificador del elemento cuyos atributos se van a establecer. Consulte el miembro hItem de la estructura TVITEM en Windows SDK.

nMask
Entero que especifica qué atributos se van a establecer. Vea el mask miembro de la TVITEM estructura.

lpszItem
Dirección de una cadena que contiene el texto del elemento.

nImage
Índice de la imagen del elemento en la lista de imágenes del control de vista de árbol. Vea el iImage miembro de la TVITEM estructura.

nSelectedImage
Índice de la imagen seleccionada del elemento en la lista de imágenes del control de vista de árbol. Vea el iSelectedImage miembro de la TVITEM estructura.

nState
Especifica valores para los estados del elemento. Vea el State miembro de la TVITEM estructura.

nStateMask
Especifica qué estados se van a establecer. Vea el stateMask miembro de la TVITEM estructura.

lParam
Valor específico de la aplicación de tamaño de puntero asociado al elemento.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

En la estructura TVITEM, el miembro hItem identifica el elemento y el miembro mask especifica qué atributos se van a establecer.

Si el miembro mask o el parámetro nMask especifican el valor TVIF_TEXT, el miembro pszText o lpszItem es la dirección de una cadena terminada en null y se omite el miembro cchTextMax. Si mask (o nMask) especifica el valor TVIF_STATE, el miembro stateMask o el parámetro nStateMask especifica qué estados de elemento se van a cambiar y el miembro state o parámetro nState contiene los valores de esos estados.

Ejemplo

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

Llame a esta función para establecer el valor específico de la aplicación asociado al elemento especificado.

BOOL SetItemData(
    HTREEITEM hItem,
    DWORD_PTR dwData);

Parámetros

hItem
Identificador del elemento cuyos datos se van a recuperar.

dwData
Valor específico de la aplicación de tamaño de puntero asociado al elemento especificado por hItem.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Ejemplo

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`

Establece el índice de la imagen que se va a mostrar cuando el elemento especificado del control de vista de árbol actual está en estado expandido.

BOOL SetItemExpandedImageIndex(
    HTREEITEM hItem,
    int iExpandedImage);

Parámetros

hItem
[in] Identificador de un elemento de control de vista de árbol.

iExpandedImage
[in] Índice de la imagen que se va a mostrar cuando el elemento especificado está en estado expandido.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Al usar este método, se envía el mensaje TVM_SETITEM, que se describe en Windows SDK. Este método asigna el parámetro iExpandedImage al miembro iExpandedImage de una estructura TVITEMEX y, a continuación, usa esa estructura en el mensaje.

Ejemplo

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;

El siguiente ejemplo de código es una prueba trivial para determinar si el método CTreeCtrl::GetItemExpandedImageIndex devuelve el valor establecido por el método CTreeCtrl::SetItemExpandedImageIndex. En una sección anterior del ejemplo de código, que no se muestra, creamos una vista de árbol que consta de un nodo de país o región raíz para el Estados Unidos, subnodos para los estados de Pennsylvania y Washington, y elementos de árbol para ciudades de esos 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`

En esta función miembro, se implementa el comportamiento del mensaje TVM_SETITEMHEIGHT de Win32, tal y como se describe en Windows SDK.

SHORT SetItemHeight(SHORT cyHeight);

Parámetros

cyHeight
Especifica el nuevo alto de cada elemento de la vista de árbol, en píxeles. Si este argumento es menor que el alto de las imágenes, se establecerá en el alto de las imágenes. Si este argumento no es uniforme, se redondeará hacia abajo hasta el valor par más cercano. Si este argumento es -1, el control volverá a usar su alto de elemento predeterminado.

Valor devuelto

Alto anterior de los elementos, en píxeles.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetItemHeight.

`CTreeCtrl::SetItemImage`

Asocia imágenes a un elemento.

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

Parámetros

hItem
Identificador del elemento cuya imagen se va a establecer.

nImage
Índice de la imagen del elemento en la lista de imágenes del control de vista de árbol.

nSelectedImage
Índice de la imagen seleccionada del elemento en la lista de imágenes del control de vista de árbol.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Cada elemento de un control de vista de árbol puede tener un par de imágenes con mapa de bits asociadas. Las imágenes aparecen en el lado izquierdo de la etiqueta de un elemento. Se muestra una imagen cuando se selecciona el elemento y la otra se muestra cuando el elemento no está seleccionado. Por ejemplo, un elemento podría mostrar una carpeta abierta cuando está seleccionada y una carpeta cerrada cuando no está seleccionada.

Llame a esta función para establecer el índice de la imagen del elemento y su imagen seleccionada dentro de la lista de imágenes del control de vista de árbol.

Para obtener más información acerca de las imágenes, consulte CImageList.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetItemImage.

`CTreeCtrl::SetItemState`

Devuelve el estado del elemento especificado por hItem.

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

Parámetros

hItem
Identificador del elemento cuyo estado se va a establecer.

nState
Especifica nuevos estados para el elemento.

nStateMask
Especifica qué estados se van a modificar.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Para obtener información sobre los estados, consulte CTreeCtrl::GetItem.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetItemState.

`CTreeCtrl::SetItemStateEx`

Establece el estado extendido del elemento especificado en el control de vista de árbol actual.

BOOL SetItemStateEx(
    HTREEITEM hItem,
    UINT uStateEx);

Parámetros

hItem
[in] Identificador de un elemento de control de vista de árbol.

uStateEx
[in] Estado extendido del elemento. Para obtener más información, consulte el miembro uStateEx de la estructura TVITEMEX.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Al usar este método, se envía el mensaje TVM_SETITEM, que se describe en Windows SDK. Este método asigna el parámetro uStateEx al miembro uStateEx de una estructura TVITEMEX y, a continuación, usa esa estructura en el mensaje.

Ejemplo

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;

En el ejemplo de código siguiente se establece un elemento de vista de árbol en estado deshabilitado. En una sección anterior del ejemplo de código, que no se muestra, creamos una vista de árbol que consta de un nodo de país o región raíz para el Estados Unidos, subnodos para los estados de Pennsylvania y Washington, y elementos de árbol para ciudades de esos estados. En este ejemplo de código se establece el nodo Pennsylvania en estado deshabilitado.

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

`CTreeCtrl::SetItemText`

Devuelve el texto del elemento especificado por hItem.

BOOL SetItemText(
    HTREEITEM hItem,
    LPCTSTR lpszItem);

Parámetros

hItem
Identificador del elemento cuyo texto se va a establecer.

lpszItem
Dirección de una cadena que contiene el nuevo texto del elemento

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Ejemplo

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

Llame a esta función miembro para establecer el color de línea actual para el control de vista de árbol.

COLORREF SetLineColor(COLORREF clrNew = CLR_DEFAULT);

Parámetros

clrNew
Nuevo color de línea.

Valor devuelto

Color de línea anterior.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje TVM_SETLINECOLOR de Win32, tal y como se describe en Windows SDK.

Ejemplo

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

`CTreeCtrl::SetScrollTime`

Llame a esta función miembro para establecer el tiempo máximo de desplazamiento del control de vista de árbol.

UINT SetScrollTime(UINT uScrollTime);

Parámetros

uScrollTime
El tiempo máximo nuevo de desplazamiento, en milisegundos. Si este valor es menor que 100, se redondeará hasta 100.

Valor devuelto

El tiempo máximo anterior de desplazamiento, en milisegundos.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje TVM_SETSCROLLTIME de Win32, tal y como se describe en Windows SDK.

`CTreeCtrl::SetTextColor`

En esta función miembro, se implementa el comportamiento del mensaje TVM_SETTEXTCOLOR de Win32, tal y como se describe en Windows SDK.

COLORREF SetTextColor(COLORREF clr);

Parámetros

clr
Valor COLORREF que contiene el nuevo color de texto. Si este argumento es -1, el control volverá a usar el color del sistema para el color del texto.

Valor devuelto

El valor devuelto será un valor COLORREF que se usa para representar el color del texto previo. Si este valor es -1, el control usaba el color del sistema para el color del texto.

Ejemplo

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

En esta función miembro, se implementa el comportamiento del mensaje TVM_SETTOOLTIPS de Win32, tal y como se describe en Windows SDK.

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

Parámetros

pWndTip
Puntero que apunta a un objeto CToolTipCtrl que usará el control de árbol.

Valor devuelto

Puntero que apunta a un objeto CToolTipCtrl que contiene la información sobre herramientas usada anteriormente por el control o NULL si no se usó anteriormente ninguna información sobre herramientas.

Comentarios

Para usar información sobre herramientas, indique el estilo TVS_NOTOOLTIPS al crear el objeto CTreeCtrl.

Ejemplo

Vea el ejemplo de CTreeCtrl::GetToolTips.

`CTreeCtrl::ShowInfoTip`

Muestra la información sobre el elemento especificado en el control de vista de árbol actual.

void ShowInfoTip(HTREEITEM hItem);

Parámetros

hItem
[in] Identificador de un elemento de vista de árbol en el control. Para obtener más información, consulte el miembro hItem de la estructura TVITEMEX.

Comentarios

Para obtener más información sobre la diferencia entre la información sobre herramientas y la información, consulte Información sobre herramientas.

Al usar este método, se envía el mensaje TVM_SHOWINFOTIP, que se describe en Windows SDK.

`CTreeCtrl::SortChildren`

Llame a esta función para ordenar alfabéticamente los elementos secundarios del elemento primario especificado en un control de vista de árbol.

BOOL SortChildren(HTREEITEM hItem);

Parámetros

hItem
Identificador del elemento primario cuyos elementos secundarios se van a ordenar. Si hItem es NULL, la ordenación continuará desde la raíz del árbol.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

SortChildren no se recusará a través del árbol; solo se ordenarán los elementos secundarios inmediatos de hItem.

Ejemplo

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

`CTreeCtrl::SortChildrenCB`

Llame a esta función para ordenar los elementos de vista de árbol mediante una función de devolución de llamada definida por la aplicación que compara los elementos.

BOOL SortChildrenCB(LPTVSORTCB pSort);

Parámetros

pSort
Puntero a una estructura TVSORTCB.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

La función de comparación de la estructura, lpfnCompare, debe devolver un valor negativo si el primer elemento debe preceder al segundo, un valor positivo si el primer elemento debe seguir el segundo o cero si los dos elementos son equivalentes.

Los parámetros lParam1 y lParam2 corresponden al miembro lParam de la estructura TVITEM de los dos elementos que se comparan. El parámetro lParamSort corresponde al miembro lParam de la estructura TV_SORTCB.

Ejemplo

// 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);

Vea también

Ejemplo de MFCCMNCTRL1
CWnd (clase)
Gráfico de jerarquías
CImageList (clase)

Compartir a través de

Clase CTreeCtrl

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Comentarios

Jerarquía de herencia

Requisitos

CTreeCtrl::Create

Parámetros

Valor devuelto

Comentarios

Ejemplo

CTreeCtrl::CreateEx

Parámetros

Valor devuelto

Comentarios

CTreeCtrl::CreateDragImage

Parámetros

Valor devuelto

Comentarios

CTreeCtrl::CTreeCtrl

CTreeCtrl::DeleteAllItems

Valor devuelto

Ejemplo

CTreeCtrl::DeleteItem

Parámetros

Valor devuelto

Ejemplo

CTreeCtrl::EditLabel

Parámetros

Valor devuelto

Comentarios

Ejemplo

CTreeCtrl::EndEditLabelNow

Parámetros

Valor devuelto

Comentarios

CTreeCtrl::EnsureVisible

Parámetros

Valor devuelto

Comentarios

Ejemplo

CTreeCtrl::Expand

Parámetros

Valor devuelto

Ejemplo

CTreeCtrl::GetBkColor

Valor devuelto

Ejemplo

CTreeCtrl::GetCheck

Parámetros

Valor devuelto

Ejemplo

CTreeCtrl::GetChildItem

Parámetros

Valor devuelto

Ejemplo

CTreeCtrl::GetCount

Valor devuelto

Ejemplo

CTreeCtrl::GetDropHilightItem

Valor devuelto

Ejemplo

CTreeCtrl::GetEditControl

Valor devuelto

Ejemplo

CTreeCtrl::GetExtendedStyle

Valor devuelto

Comentarios

CTreeCtrl::GetFirstVisibleItem

Valor devuelto

Ejemplo

CTreeCtrl::GetImageList

Parámetros

Valor devuelto

Comentarios

Ejemplo

CTreeCtrl::GetIndent

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