Clase CHeaderCtrl

Artículo
06/16/2023

Proporciona la funcionalidad del control común de encabezado de Windows.

Sintaxis

class CHeaderCtrl : public CWnd

Miembros

Constructores públicos

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

Métodos públicos

Nombre	Descripción
CHeaderCtrl::ClearAllFilters	Borra todos los filtros de un control de encabezado.
CHeaderCtrl::ClearFilter	Borra el filtro de un control de encabezado.
CHeaderCtrl::Create	Crea un control de encabezado y lo asocia a un objeto `CHeaderCtrl`.
CHeaderCtrl::CreateDragImage	Crea una versión transparente de la imagen de un elemento dentro de un control de encabezado.
CHeaderCtrl::CreateEx	Crea un control de encabezado con los estilos extendidos de Windows especificados y lo adjunta a un objeto `CListCtrl`.
CHeaderCtrl::DeleteItem	Elimina un elemento de un control de encabezado.
CHeaderCtrl::DrawItem	Dibuja el elemento especificado de un control de encabezado.
CHeaderCtrl::EditFilter	Comienza a editar el filtro especificado de un control de encabezado.
CHeaderCtrl::GetBitmapMargin	Recupera el ancho del margen de un mapa de bits en un control de encabezado.
CHeaderCtrl::GetFocusedItem	Obtiene el identificador del elemento del control de encabezado actual que tiene el foco.
CHeaderCtrl::GetImageList	Recupera el identificador de una lista de imágenes usada para dibujar elementos de encabezado en un control de encabezado.
CHeaderCtrl::GetItem	Recupera información sobre un elemento de un control de encabezado.
CHeaderCtrl::GetItemCount	Recupera un recuento de los elementos de un control de encabezado.
CHeaderCtrl::GetItemDropDownRect	Obtiene la información de rectángulo delimitador del botón desplegable especificado en un control de encabezado.
CHeaderCtrl::GetItemRect	Recupera el rectángulo delimitador de una banda determinada en un control de encabezado.
CHeaderCtrl::GetOrderArray	Recupera el orden de izquierda a derecha de los elementos de un control de encabezado.
CHeaderCtrl::GetOverflowRect	Obtiene el rectángulo delimitador del botón de desbordamiento del control de encabezado actual.
CHeaderCtrl::HitTest	Determina qué elemento de encabezado, si existe, se encuentra en un punto especificado.
CHeaderCtrl::InsertItem	Inserta un nuevo elemento en un control de encabezado.
CHeaderCtrl::Layout	Recupera el tamaño y la posición de un control de encabezado dentro de un rectángulo determinado.
CHeaderCtrl::OrderToIndex	Recupera el valor de índice de un elemento en función de su orden en el control de encabezado.
CHeaderCtrl::SetBitmapMargin	Establece el ancho del margen de un mapa de bits en un control de encabezado.
CHeaderCtrl::SetFilterChangeTimeout	Establece el intervalo de tiempo de espera entre el momento en que se produce un cambio en los atributos de filtro y la publicación de una notificación `HDN_FILTERCHANGE`.
CHeaderCtrl::SetFocusedItem	Establece el foco en un elemento de encabezado especificado en el control de encabezado actual.
CHeaderCtrl::SetHotDivider	Cambia el divisor entre elementos de encabezado para indicar una arrastrar y colocar manualmente un elemento de encabezado.
CHeaderCtrl::SetImageList	Asigna una lista de imágenes a un control de encabezado.
CHeaderCtrl::SetItem	Establece los atributos del elemento especificado en un control de encabezado.
CHeaderCtrl::SetOrderArray	Establece el orden de izquierda a derecha de los elementos de un control de encabezado.

Comentarios

Un control de encabezado es una ventana que normalmente se coloca encima de un conjunto de columnas de texto o números. Contiene un título para cada columna y se puede dividir en partes. El usuario puede arrastrar los divisores que separan las partes para establecer el ancho de cada columna. Para obtener una ilustración de un control de encabezado, consulta Controles de encabezado.

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

La funcionalidad agregada para los controles comunes de Windows 95/Internet Explorer 4.0 incluye lo siguiente:

Ordenación personalizada del elemento de encabezado.
El elemento de encabezado arrastra y coloca, para reordenar los elementos de encabezado. Use el estilo HDS_DRAGDROP al crear el objeto CHeaderCtrl.
Texto de columna de encabezado visible constantemente durante el cambio de tamaño de columna. Use el estilo HDS_FULLDRAG al crear un objeto CHeaderCtrl.
Seguimiento activo del encabezado, que resalta el elemento de encabezado cuando el puntero mantiene el puntero sobre él. Use el estilo HDS_HOTTRACK al crear el objeto CHeaderCtrl.
Compatibilidad con listas de imágenes. Los elementos de encabezado pueden contener imágenes almacenadas en un CImageList objeto o texto.

Para obtener más información sobre cómo usar la clase CHeaderCtrl, consulta Controles y Uso de CHotKeyCtrl.

Jerarquía de herencia

CObject

CCmdTarget

CWnd

CHeaderCtrl

Requisitos

Encabezado: afxcmn.h

CHeaderCtrl::CHeaderCtrl

Construye un objeto CHeaderCtrl.

CHeaderCtrl();

Ejemplo

// Declare a local CHeaderCtrl object.
CHeaderCtrl myHeaderCtrl;

// Declare a dynamic CHeaderCtrl object.
CHeaderCtrl *pmyHeaderCtrl = new CHeaderCtrl;

CHeaderCtrl::ClearAllFilters

Borra todos los filtros de un control de encabezado.

BOOL ClearAllFilters();

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Este método implementa el comportamiento del mensaje Win32 HDM_CLEARFILTER con un valor de columna de -1, tal como se describe en Windows SDK.

Ejemplo

m_myHeaderCtrl.ClearAllFilters();

CHeaderCtrl::ClearFilter

Borra el filtro de un control de encabezado.

BOOL ClearFilter(int nColumn);

Parámetros

nColumn
Valor de columna que indica qué filtro se va a borrar.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Este método implementa el comportamiento del mensaje HDM_CLEARFILTER, de Win32, tal y como se describe en Windows SDK.

Ejemplo

int iFilt = m_myHeaderCtrl.ClearFilter(1);

CHeaderCtrl::Create

Crea un control de encabezado y lo asocia a un objeto CHeaderCtrl.

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

Parámetros

dwStyle
Especifica el estilo del control de encabezado. Para obtener una descripción de los estilos del control encabezado, consulta los estilos del control de encabezado en Windows SDK.

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

pParentWnd
Especifica la ventana primaria del control de encabezado, normalmente CDialog. No debe ser NULL.

Nid
Especifica el identificador del control de encabezado.

Valor devuelto

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

Comentarios

El objeto CHeaderCtrl se construye en dos pasos. En primer lugar, llama al constructor y, luego, a Create, lo que crea el control de tecla de acceso rápido y lo asocia al objeto CHeaderCtrl.

Además de los estilos de control de encabezado, puedes usar los siguientes estilos de control comunes para determinar cómo se coloca y cambia el tamaño del control de encabezado (consulta Estilos de control comunes para obtener más información):

CCS_BOTTOM Hace que el control se coloque en la parte inferior del área cliente de la ventana primaria y establece el ancho en el mismo que el ancho de la ventana primaria.
CCS_NODIVIDER Impide que se dibuje un resaltado de dos píxeles en la parte superior del control.
CCS_NOMOVEY Hace que el control cambie el tamaño y se mueva horizontalmente, pero no verticalmente, en respuesta a un mensaje de WM_SIZE. Si se usa el estilo CCS_NORESIZE, este estilo no se aplica. Los controles de encabezado tienen este estilo de forma predeterminada.
CCS_NOPARENTALIGN Impide que el control se mueva automáticamente a la parte superior o inferior de la ventana primaria. En su lugar, el control mantiene su posición dentro de la ventana primaria a pesar de los cambios en el tamaño de la ventana primaria. Si también se usa el estilo CCS_TOP o CCS_BOTTOM, el alto se ajusta al valor predeterminado, pero la posición y el ancho permanecen sin cambios.
CCS_NORESIZE Impide que el control use el ancho y alto predeterminados al establecer su tamaño inicial o un nuevo tamaño. En su lugar, el control usa el ancho y alto especificados en la solicitud de creación o ajuste de tamaño.
CCS_TOP Hace que el control se coloque en la parte superior del área cliente de la ventana primaria y establece el ancho en el mismo que el ancho de la ventana primaria.

También puede aplicar los siguientes estilos de ventana a un control de encabezado (consulte Estilos de ventana para obtener más información):

WS_CHILD crea una ventana secundaria. No se puede usar con el estilo WS_POPUP.
WS_VISIBLE Crea una ventana que está visible inicialmente.
WS_DISABLED Crea una ventana que está deshabilitada inicialmente.
WS_GROUP Especifica el primer control de un grupo de controles en los que el usuario puede pasar de un control al siguiente con las teclas de dirección. Todos los controles definidos con el estilo WS_GROUP después del primer control pertenecen al mismo grupo. El siguiente control con el estilo WS_GROUP finaliza el grupo de estilo e inicia el siguiente grupo (es decir, un grupo finaliza donde comienza el siguiente).
WS_TABSTOP Especifica un control entre varios mediante los cuales el usuario se puede mover con la tecla TAB. La tecla TAB mueve al usuario al siguiente control especificado por el estilo WS_TABSTOP.

Si quiere usar estilos extendidos de Windows con el control, llame a CreateEx en lugar de a Create.

Ejemplo

// pParentWnd is a pointer to the parent window.
m_myHeaderCtrl.Create(WS_CHILD | WS_VISIBLE | HDS_HORZ,
                      CRect(10, 10, 600, 50), pParentWnd, 1);

CHeaderCtrl::CreateEx

Esta función puede usarse para crear un control (una ventana secundaria) y asociarlo con el objeto CHeaderCtrl.

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 ver una lista de estilos extendidos de Windows, consulte el parámetro dwExStyle para CreateWindowEx en Windows SDK.

dwStyle
El estilo del control de encabezado. Para obtener una descripción de los estilos del control encabezado, consulta los estilos del control de encabezado en Windows SDK. Consulta Crear para obtener una lista de estilos adicionales.

rect
Referencia a una estructura RECT que describe el tamaño y la posición de la ventana que se va a crear, en coordenadas de 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

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

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 de Windows WS_EX_.

CHeaderCtrl::CreateDragImage

Crea una versión transparente de la imagen de un elemento dentro de un control de encabezado.

CImageList* CreateDragImage(int nIndex);

Parámetros

nIndex
El índice de base cero del elemento del control de encabezado. La imagen asignada a este elemento es la base de la imagen transparente.

Valor devuelto

Un puntero a un objeto CImageList si se ejecutara correctamente; en caso contrario, será NULL. La lista devuelta contiene solo una imagen.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje HDM_CREATEDRAGIMAGE de Win32, tal y como se describe en Windows SDK. Se proporciona para admitir la arrastrar y colocar elementos de encabezado.

El objeto CImageList al que apunta el puntero devuelto es un objeto temporal y se elimina en el siguiente procesamiento en tiempo de inactividad.

CHeaderCtrl::DeleteItem

Elimina un elemento de un control de encabezado.

BOOL DeleteItem(int nPos);

Parámetros

nPos
Especifica el índice de base cero del elemento que se va a eliminar.

Valor devuelto

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

Ejemplo

int nCount = m_myHeaderCtrl.GetItemCount();

// Delete all of the items.
for (int i = 0; i < nCount; i++)
{
   m_myHeaderCtrl.DeleteItem(0);
}

CHeaderCtrl::DrawItem

Lo llama el marco de trabajo cuando cambia un aspecto visual de un control de encabezado dibujado por el propietario.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parámetros

lpDrawItemStruct
Un puntero a una estructura DRAWITEMSTRUCT que describe el elemento que se va a pintar.

Comentarios

El miembro itemAction de la estructura DRAWITEMSTRUCT define la acción de dibujo que se realizará.

De manera predeterminada, esta función miembro no hace nada. Invalida esta función miembro para implementar el dibujo de un objeto CHeaderCtrl dibujado por el propietario.

La aplicación debe restaurar todos los objetos de Interfaz de dispositivo gráfico (GDI) seleccionados para el contexto de presentación proporcionado en lpDrawItemStruct antes de que finalice esta función miembro.

Ejemplo

// NOTE: CMyHeaderCtrl is a class derived from CHeaderCtrl.
// The CMyHeaderCtrl object was created as follows:
//
//   CMyHeaderCtrl m_myHeader;
//   myHeader.Create(WS_CHILD | WS_VISIBLE | HDS_HORZ,
//      CRect(10, 10, 600, 50), pParentWnd, 1);

// This example implements the DrawItem method for a
// CHeaderCtrl-derived class that draws every item as a
// 3D button using the text color red.
void CMyHeaderCtrl::DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct)
{
   // This code only works with header controls.
   ASSERT(lpDrawItemStruct->CtlType == ODT_HEADER);

   HDITEM hdi;
   const int c_cchBuffer = 256;
   TCHAR lpBuffer[c_cchBuffer];

   hdi.mask = HDI_TEXT;
   hdi.pszText = lpBuffer;
   hdi.cchTextMax = c_cchBuffer;

   GetItem(lpDrawItemStruct->itemID, &hdi);

   // Draw the button frame.
   ::DrawFrameControl(lpDrawItemStruct->hDC,
                      &lpDrawItemStruct->rcItem, DFC_BUTTON, DFCS_BUTTONPUSH);

   // Draw the items text using the text color red.
   COLORREF crOldColor = ::SetTextColor(lpDrawItemStruct->hDC,
                                        RGB(255, 0, 0));
   ::DrawText(lpDrawItemStruct->hDC, lpBuffer,
              (int)_tcsnlen(lpBuffer, c_cchBuffer),
              &lpDrawItemStruct->rcItem, DT_SINGLELINE | DT_VCENTER | DT_CENTER);
   ::SetTextColor(lpDrawItemStruct->hDC, crOldColor);
}

CHeaderCtrl::EditFilter

Comienza a editar el filtro especificado de un control de encabezado.

BOOL EditFilter(
    int nColumn,
    BOOL bDiscardChanges);

Parámetros

nColumn
Columna que se va a editar.

bDiscardChanges
Valor que especifica cómo controlar los cambios de edición del usuario si el usuario está en proceso de edición del filtro cuando se envía el mensaje de HDM_EDITFILTER.

Especifica TRUE para descartar los cambios realizados por el usuario o FALSE para aceptar los cambios realizados por el usuario.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Este método implementa el comportamiento del mensaje HDM_EDITFILTER, de Win32, tal y como se describe en Windows SDK.

Ejemplo

int iFilter = m_myHeaderCtrl.EditFilter(1, TRUE);

CHeaderCtrl::GetBitmapMargin

Recupera el ancho del margen de un mapa de bits en un control de encabezado.

int GetBitmapMargin() const;

Valor devuelto

La anchura del mapa de bits, en píxeles.

Comentarios

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

Ejemplo

int iMargin = m_myHeaderCtrl.GetBitmapMargin();

CHeaderCtrl::GetFocusedItem

Obtiene el índice del elemento que tiene el foco en el control de encabezado actual.

int GetFocusedItem() const;

Valor devuelto

El índice de base cero del elemento del encabezado que tiene el foco.

Comentarios

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

Ejemplo

En el primer ejemplo de código se define la variable m_headerCtrl, que se usa para acceder al control de encabezado. Esta variable se utiliza en el siguiente ejemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

En el siguiente código de ejemplo se muestran los métodos SetFocusedItem y GetFocusedItem. En una sección anterior del código, creamos un control de encabezado con cinco columnas. Sin embargo, puedes arrastrar un separador de columnas para que la columna no esté visible. En el ejemplo siguiente se establece y, a continuación, se confirma el último encabezado de columna como elemento de enfoque.

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXSetfocuseditem()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }

   // Check that we get the value we set.
   int item = m_headerCtrl.GetItemCount() - 1;
   m_headerCtrl.SetFocusedItem(item);
   int itemGet = m_headerCtrl.GetFocusedItem();
   CString str = _T("Set: focused item = %d\nGet: focused item = %d");
   str.Format(str, item, itemGet);
   MessageBox(str, _T("Set/GetFocused Item"));
}

CHeaderCtrl::GetImageList

Recupera el identificador de una lista de imágenes usada para dibujar elementos de encabezado en un control de encabezado.

CImageList* GetImageList() const;

Valor devuelto

Puntero a un objeto CImageList.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje HDM_GETIMAGELIST de Win32, tal y como se describe en Windows SDK. El objeto CImageList al que apunta el puntero devuelto es un objeto temporal y se elimina en el siguiente procesamiento en tiempo de inactividad.

Ejemplo

// The new image list of the header control.
m_HeaderImages.Create(16, 16, ILC_COLOR, 2, 2);
m_HeaderImages.Add(AfxGetApp()->LoadIcon(IDI_ICON1));
m_HeaderImages.Add(AfxGetApp()->LoadIcon(IDI_ICON2));
m_HeaderImages.Add(AfxGetApp()->LoadIcon(IDI_ICON3));

ASSERT(m_myHeaderCtrl.GetImageList() == NULL);

m_myHeaderCtrl.SetImageList(&m_HeaderImages);
ASSERT(m_myHeaderCtrl.GetImageList() == &m_HeaderImages);

CHeaderCtrl::GetItem

Recupera información sobre un elemento de control de encabezado.

BOOL GetItem(
    int nPos,
    HDITEM* pHeaderItem) const;

Parámetros

nPos
Especifica el índice de base cero del elemento que se va a recuperar.

pHeaderItem
Puntero a una estructura HDITEM que recibe el nuevo elemento. Esta estructura se usa con las funciones miembro InsertItem y SetItem. Todas las marcas establecidas en el mask elemento garantizan que los valores de los elementos correspondientes se rellenen correctamente al devolverse. Si el elemento mask se establece en cero, los valores de los demás elementos de estructura no tienen sentido.

Valor devuelto

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

Ejemplo

LPCTSTR lpszmyString = _T("column 2");
LPCTSTR lpszmyString2 = _T("vertical 2");

// Find the item whose text matches lpszmyString, and
// replace it with lpszmyString2.
int i, nCount = m_myHeaderCtrl.GetItemCount();
HDITEM hdi;
enum
{
   sizeOfBuffer = 256
};
TCHAR lpBuffer[sizeOfBuffer];
bool fFound = false;

hdi.mask = HDI_TEXT;
hdi.pszText = lpBuffer;
hdi.cchTextMax = sizeOfBuffer;

for (i = 0; !fFound && (i < nCount); i++)
{
   m_myHeaderCtrl.GetItem(i, &hdi);

   if (_tcsncmp(hdi.pszText, lpszmyString, sizeOfBuffer) == 0)
   {
      _tcscpy_s(hdi.pszText, sizeOfBuffer, lpszmyString2);
      m_myHeaderCtrl.SetItem(i, &hdi);
      fFound = true;
   }
}

CHeaderCtrl::GetItemCount

Recupera un recuento de los elementos de un control de encabezado.

int GetItemCount() const;

Valor devuelto

Número de elementos de control de encabezado si se ejecuta correctamente; de lo contrario: -1.

Ejemplo

Consulta el ejemplo de CHeaderCtrl::D eleteItem.

CHeaderCtrl::GetItemDropDownRect

Obtiene el rectángulo delimitador del botón desplegable de un elemento de encabezado en el control de encabezado actual.

BOOL GetItemDropDownRect(
    int iItem,
    LPRECT lpRect) const;

Parámetros

iItem
[in] Índice de base cero de un elemento de encabezado cuyo estilo es HDF_SPLITBUTTON. Para obtener más información, consulta el miembro fmt de la estructura HDITEM.

lpRect
[out] Puntero a una estructura RECT para recibir la información del rectángulo delimitador.

Valor devuelto

TRUE si esta función se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

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

Ejemplo

En el primer ejemplo de código se define la variable m_headerCtrl, que se usa para acceder al control de encabezado. Esta variable se utiliza en el siguiente ejemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

En el siguiente código de ejemplo se muestra el método GetItemDropDownRect. En una sección anterior del código, creamos un control de encabezado con cinco columnas. En el ejemplo de código siguiente se dibuja un rectángulo 3D alrededor de la ubicación de la primera columna reservada para el botón desplegable del encabezado.

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXGetitemdropdownrect()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }

   // Get the dropdown rect for the first column.
   CRect rect;
   BOOL bRetVal = m_headerCtrl.GetItemDropDownRect(0, &rect);
   if (bRetVal == TRUE)
   {
      // Draw around the dropdown rect a rectangle that has red
      // left and top sides, and blue right and bottom sides.
      CDC *pDC = m_headerCtrl.GetDC();
      pDC->Draw3dRect(rect, RGB(255, 0, 0), RGB(0, 0, 255));
   }
}

CHeaderCtrl::GetItemRect

Recupera el rectángulo delimitador de una banda determinada en un control de encabezado.

BOOL GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parámetros

nIndex
El índice de base cero del elemento de control de encabezado.

lpRect
Un puntero a la dirección de una estructura RECT que recibe la información del rectángulo delimitador.

Valor devuelto

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

Comentarios

Este método implementa el comportamiento del mensaje HDM_GETITEMRECT, de Win32, tal y como se describe en Windows SDK.

CHeaderCtrl::GetOrderArray

Recupera el orden de izquierda a derecha de los elementos de un control de encabezado.

BOOL GetOrderArray(
    LPINT piArray,
    int iCount);

Parámetros

piArray
Puntero a la dirección de un búfer que recibe los valores de índice de los elementos del control de encabezado, en el orden en que aparecen de izquierda a derecha.

iCount
Número de elementos de control de encabezado. No puede ser negativo.

Valor devuelto

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

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje HDM_GETORDERARRAY de Win32, tal y como se describe en Windows SDK. Se proporciona para permitir la ordenación de elementos de encabezado.

Ejemplo

// Reverse the order of the items in the header control.
// (i.e. make the first item the last one, the last item
// the first one, and so on ...).
int nCount = m_myHeaderCtrl.GetItemCount();
LPINT pnOrder = (LPINT)malloc(nCount * sizeof(int));
ASSERT(pnOrder != NULL);
if (NULL != pnOrder)
{
   m_myHeaderCtrl.GetOrderArray(pnOrder, nCount);

   int i, j, nTemp;
   for (i = 0, j = nCount - 1; i < j; i++, j--)
   {
      nTemp = pnOrder[i];
      pnOrder[i] = pnOrder[j];
      pnOrder[j] = nTemp;
   }

   m_myHeaderCtrl.SetOrderArray(nCount, pnOrder);
   free(pnOrder);
}

CHeaderCtrl::GetOverflowRect

Obtiene el rectángulo delimitador del botón de desbordamiento del control de encabezado actual.

BOOL GetOverflowRect(LPRECT lpRect) const;

Parámetros

lpRect
[out] Puntero a una estructura RECT para recibir la información del rectángulo delimitador.

Valor devuelto

TRUE si esta función se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Si el control de encabezado contiene más elementos de los que se pueden mostrar simultáneamente, el control puede mostrar un botón de desbordamiento que se desplaza a los elementos que no están visibles. El control de encabezado debe tener los estilos HDS_OVERFLOW y HDF_SPLITBUTTON para mostrar el botón de desbordamiento. El rectángulo delimitador incluye el botón de desbordamiento y solo existe cuando se muestra el botón de desbordamiento. Para más información, consulta Estilos del control de encabezado.

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

Ejemplo

En el primer ejemplo de código se define la variable m_headerCtrl, que se usa para acceder al control de encabezado. Esta variable se utiliza en el siguiente ejemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

En el siguiente código de ejemplo se muestra el método GetOverflowRect. En una sección anterior del código, creamos un control de encabezado con cinco columnas. Sin embargo, puedes arrastrar un separador de columnas para que la columna no esté visible. Si algunas columnas no están visibles, el control de encabezado dibuja un botón de desbordamiento. En el ejemplo de código siguiente se dibuja un rectángulo 3D alrededor de la ubicación del botón de desbordamiento.

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXGetoverflowrect()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }
   CRect rect;
   // Get the overflow rectangle.
   BOOL bRetVal = m_headerCtrl.GetOverflowRect(&rect);
   // Get the device context.
   CDC *pDC = m_headerCtrl.GetDC();
   // Draw around the overflow rect a rectangle that has red
   // left and top sides, and green right and bottom sides.
   pDC->Draw3dRect(rect, RGB(255, 0, 0), RGB(0, 255, 0));
}

CHeaderCtrl::HitTest

Determina qué elemento de encabezado, si existe, se encuentra en un punto especificado.

int HitTest(LPHDHITTESTINFO* phdhti);

Parámetros

phdhti
[dentro, fuera] Puntero a una estructura HDHITTESTINFO que especifica el punto que se va a probar y recibe los resultados de la prueba.

Valor devuelto

Índice de base cero del elemento de encabezado, si existe, en la posición especificada; de lo contrario, -1.

Comentarios

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

Ejemplo

En el primer ejemplo de código se define la variable m_headerCtrl, que se usa para acceder al control de encabezado. Esta variable se utiliza en el siguiente ejemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

En el siguiente código de ejemplo se muestra el método HitTest. En una sección anterior del código de ejemplo, creamos un control de encabezado con cinco columnas. Sin embargo, puedes arrastrar un separador de columnas para que la columna no esté visible. En este ejemplo se notifica el índice de la columna si está visible y -1 si la columna no está visible.

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXHittest()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }
   // Initialize HDHITTESTINFO structure.
   HDHITTESTINFO hdHitIfo;
   memset(&hdHitIfo, 0, sizeof(HDHITTESTINFO));

   CString str;
   CRect rect;
   int iRetVal = -1;
   for (int i = 0; i < m_headerCtrl.GetItemCount(); i++)
   {
      m_headerCtrl.GetItemRect(i, &rect);
      hdHitIfo.pt = rect.CenterPoint();
      // The hit test depends on whether the header item is visible.
      iRetVal = m_headerCtrl.HitTest(&hdHitIfo);
      str.AppendFormat(_T("Item = %d, Hit item = %d\n"), i, iRetVal);
   }
   MessageBox(str, _T("Hit test results"));
}

CHeaderCtrl::InsertItem

Inserta un nuevo elemento en un control de encabezado en el índice especificado.

int InsertItem(
    int nPos,
    HDITEM* phdi);

Parámetros

nPos
Índice de base cero del elemento que se va a insertar. Si el valor es cero, el elemento se inserta al principio del control de encabezado. Si el valor es mayor que el valor máximo, el elemento se inserta al final del control de encabezado.

phdi
Puntero a una estructura HDITEM que contiene información sobre el elemento que se va a insertar.

Valor devuelto

Índice del nuevo elemento si se realiza correctamente; de lo contrario, -1.

Ejemplo

CString str;
HDITEM hdi;

hdi.mask = HDI_TEXT | HDI_WIDTH | HDI_FORMAT | HDI_IMAGE;
hdi.cxy = 100; // Make all columns 100 pixels wide.
hdi.fmt = HDF_STRING | HDF_CENTER;

// Insert 6 columns in the header control.
for (int i = 0; i < 6; i++)
{
   str.Format(TEXT("column %d"), i);
   hdi.pszText = str.GetBuffer(0);
   hdi.iImage = i % 3;

   m_myHeaderCtrl.InsertItem(i, &hdi);
}

CHeaderCtrl::Layout

Recupera el tamaño y la posición de un control de encabezado dentro de un rectángulo determinado.

BOOL Layout(HDLAYOUT* pHeaderLayout);

Parámetros

pHeaderLayout
Puntero a una estructura HDLAYOUT, que contiene información utilizada para establecer el tamaño y la posición de un control de encabezado.

Valor devuelto

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

Comentarios

Esta función se usa para determinar las dimensiones adecuadas para un nuevo control de encabezado que va a ocupar el rectángulo especificado.

Ejemplo

HDLAYOUT hdl;
WINDOWPOS wpos;
RECT rc;

// Reposition the header control so that it is placed at
// the top of its parent window's client area.
m_myHeaderCtrl.GetParent()->GetClientRect(&rc);

hdl.prc = &rc;
hdl.pwpos = &wpos;
if (m_myHeaderCtrl.Layout(&hdl))
{
   m_myHeaderCtrl.SetWindowPos(
       CWnd::FromHandle(wpos.hwndInsertAfter),
       wpos.x,
       wpos.y,
       wpos.cx,
       wpos.cy,
       wpos.flags | SWP_SHOWWINDOW);
}

CHeaderCtrl::OrderToIndex

Recupera el valor de índice de un elemento en función de su orden en el control de encabezado.

int OrderToIndex(int nOrder) const;

Parámetros

nOrder
El orden de base cero que el elemento aparece en el control de encabezado, de izquierda a derecha.

Valor devuelto

Índice del elemento, según su orden en el control de encabezado. El índice cuenta de izquierda a derecha, empezando por 0.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, HDM_ORDERTOINDEX, tal y como se describe en Windows SDK. Se proporciona para permitir la ordenación de elementos de encabezado.

CHeaderCtrl::SetBitmapMargin

Establece el ancho del margen de un mapa de bits en un control de encabezado.

int SetBitmapMargin(int nWidth);

Parámetros

nWidth
Anchura, especificada en píxeles, del margen que rodea un mapa de bits dentro de un control de encabezado existente.

Valor devuelto

La anchura del mapa de bits, en píxeles.

Comentarios

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

Ejemplo

int iOldMargin = m_myHeaderCtrl.SetBitmapMargin(15);

CHeaderCtrl::SetFilterChangeTimeout

Establece el intervalo de tiempo de espera entre el momento en que se produce un cambio en los atributos de filtro y la publicación de una notificación HDN_FILTERCHANGE.

int SetFilterChangeTimeout(DWORD dwTimeOut);

Parámetros

dwTimeOut
Valor del tiempo de espera, en milisegundos.

Valor devuelto

Índice del control de filtro que se va a modificar.

Comentarios

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

Ejemplo

int iFltr = m_myHeaderCtrl.SetFilterChangeTimeout(15);

CHeaderCtrl::SetFocusedItem

Establece el foco en un elemento de encabezado especificado en el control de encabezado actual.

BOOL SetFocusedItem(int iItem);

Parámetros

iItem
[in] Índice de base cero de un elemento de encabezado.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

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

Ejemplo

En el primer ejemplo de código se define la variable m_headerCtrl, que se usa para acceder al control de encabezado. Esta variable se utiliza en el siguiente ejemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXSetfocuseditem()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }

   // Check that we get the value we set.
   int item = m_headerCtrl.GetItemCount() - 1;
   m_headerCtrl.SetFocusedItem(item);
   int itemGet = m_headerCtrl.GetFocusedItem();
   CString str = _T("Set: focused item = %d\nGet: focused item = %d");
   str.Format(str, item, itemGet);
   MessageBox(str, _T("Set/GetFocused Item"));
}

CHeaderCtrl::SetHotDivider

Cambia el divisor entre elementos de encabezado para indicar una arrastrar y colocar manualmente un elemento de encabezado.

int SetHotDivider(CPoint pt);
int SetHotDivider(int nIndex);

Parámetros

pt
Posición del puntero. El control de encabezado resalta el divisor adecuado en función de la posición del puntero.

nIndex
El índice del elemento resaltado.

Valor devuelto

El índice del elemento resaltado.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje HDM_SETHOTDIVIDER de Win32, tal y como se describe en Windows SDK. Se proporciona para admitir la arrastrar y colocar elementos de encabezado.

Ejemplo

void CMyHeaderCtrl::OnMouseMove(UINT nFlags, CPoint point)
{
   SetHotDivider(point);

   CHeaderCtrl::OnMouseMove(nFlags, point);
}

CHeaderCtrl::SetImageList

Asigna una lista de imágenes a un control de encabezado.

CImageList* SetImageList(CImageList* pImageList);

Parámetros

pImageList
Un puntero a un objeto CImageList que contiene la lista de imágenes que se va a asignar al control de encabezado.

Valor devuelto

Un puntero al objeto CImageList asignado previamente al control de encabezado.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje HDM_SETIMAGELIST de Win32, tal y como se describe en Windows SDK. El objeto CImageList al que apunta el puntero devuelto es un objeto temporal y se elimina en el siguiente procesamiento en tiempo de inactividad.

Ejemplo

Consulta el ejemplo de CHeaderCtrl::GetImageList.

CHeaderCtrl::SetItem

Establece los atributos del elemento especificado en un control de encabezado.

BOOL SetItem(
    int nPos,
    HDITEM* pHeaderItem);

Parámetros

nPos
El índice de base cero del elemento que se va a manipular.

pHeaderItem
Puntero a una estructura HDITEM que contiene información sobre el elemento nuevo.

Valor devuelto

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

Ejemplo

Consulta el ejemplo de CHeaderCtrl::GetItem.

CHeaderCtrl::SetOrderArray

Establece el orden de izquierda a derecha de los elementos de un control de encabezado.

BOOL SetOrderArray(
    int iCount,
    LPINT piArray);

Parámetros

iCount
Número de elementos de control de encabezado.

piArray
Puntero a la dirección de un búfer que recibe los valores de índice de los elementos del control de encabezado, en el orden en que aparecen de izquierda a derecha.

Valor devuelto

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

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, HDM_SETORDERARRAY, tal y como se describe en Windows SDK. Se proporciona para permitir la ordenación de elementos de encabezado.

Ejemplo

Consulta el ejemplo de CHeaderCtrl::GetOrderArray.

Consulte también

CWnd (clase)
Gráfico de jerarquías
CTabCtrl (clase)
CListCtrl (clase)
CImageList (clase)

Compartir vía

Clase CHeaderCtrl

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Comentarios

Jerarquía de herencia

Requisitos

CHeaderCtrl::CHeaderCtrl

Ejemplo

CHeaderCtrl::ClearAllFilters

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::ClearFilter

Parámetros

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::Create

Parámetros

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::CreateEx

Parámetros

Valor devuelto

Comentarios

CHeaderCtrl::CreateDragImage

Parámetros

Valor devuelto

Comentarios

CHeaderCtrl::DeleteItem

Parámetros

Valor devuelto

Ejemplo

CHeaderCtrl::DrawItem

Parámetros

Comentarios

Ejemplo

CHeaderCtrl::EditFilter

Parámetros

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::GetBitmapMargin

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::GetFocusedItem

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::GetImageList

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::GetItem

Parámetros

Valor devuelto

Ejemplo

CHeaderCtrl::GetItemCount

Valor devuelto

Ejemplo

CHeaderCtrl::GetItemDropDownRect

Parámetros

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::GetItemRect

Parámetros

Valor devuelto

Comentarios

CHeaderCtrl::GetOrderArray

Parámetros

Valor devuelto

Comentarios

Ejemplo

CHeaderCtrl::GetOverflowRect