Classe CHeaderCtrl

Artigo
10/12/2023

Fornece a funcionalidade do controle de cabeçalho comum do Windows.

Sintaxe

class CHeaderCtrl : public CWnd

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
CHeaderCtrl::ClearAllFilters	Limpa todos os filtros para um controle de cabeçalho.
CHeaderCtrl::ClearFilter	Limpa o filtro para um controle de cabeçalho.
CHeaderCtrl::Create	Cria um controle de cabeçalho e o anexa a um objeto `CHeaderCtrl`.
CHeaderCtrl::CreateDragImage	Cria uma versão transparente da imagem de um item dentro de um controle de cabeçalho.
CHeaderCtrl::CreateEx	Cria um controle de cabeçalho com os estilos estendidos especificados do Windows e o anexa a um objeto `CListCtrl`.
CHeaderCtrl::DeleteItem	Exclui um item de um controle de cabeçalho.
CHeaderCtrl::DrawItem	Desenha o item especificado de um controle de cabeçalho.
CHeaderCtrl::EditFilter	Inicia a edição do filtro especificado de um controle de cabeçalho.
CHeaderCtrl::GetBitmapMargin	Recupera a largura da margem de um bitmap em um controle de cabeçalho.
CHeaderCtrl::GetFocusedItem	Obtém o identificador do item no controle de cabeçalho atual que tem o foco.
CHeaderCtrl::GetImageList	Recupera o identificador de uma lista de imagens usada para desenhar itens de cabeçalho em um controle de cabeçalho.
CHeaderCtrl::GetItem	Recupera informações sobre um item em um controle de cabeçalho.
CHeaderCtrl::GetItemCount	Recupera uma contagem dos itens em um controle de cabeçalho.
CHeaderCtrl::GetItemDropDownRect	Obtém as informações de retângulo delimitador para o botão suspenso especificado em um controle de cabeçalho.
CHeaderCtrl::GetItemRect	Recupera o retângulo delimitador para uma determinada banda em um controle de cabeçalho.
CHeaderCtrl::GetOrderArray	Recupera a ordem da esquerda para a direita de itens em um controle de cabeçalho.
CHeaderCtrl::GetOverflowRect	Obtém o retângulo delimitador do botão de estouro para o controle de cabeçalho atual.
CHeaderCtrl::HitTest	Determina qual item de cabeçalho, se houver, está localizado em um ponto especificado.
CHeaderCtrl::InsertItem	Insere um novo item em um controle de cabeçalho.
CHeaderCtrl::Layout	Recupera o tamanho e a posição de um controle de cabeçalho em um determinado retângulo.
CHeaderCtrl::OrderToIndex	Recupera o valor do índice de um item com base em sua ordem no controle de cabeçalho.
CHeaderCtrl::SetBitmapMargin	Define a largura da margem de um bitmap em um controle de cabeçalho.
CHeaderCtrl::SetFilterChangeTimeout	Define o intervalo de tempo limite entre o tempo em que uma alteração ocorre nos atributos de filtro e a postagem de uma notificação `HDN_FILTERCHANGE`.
CHeaderCtrl::SetFocusedItem	Define o foco em um item de cabeçalho especificado no controle de cabeçalho atual.
CHeaderCtrl::SetHotDivider	Altera o divisor entre itens de cabeçalho para indicar um arrastar e soltar manual de um item de cabeçalho.
CHeaderCtrl::SetImageList	Atribui uma lista de imagens a um controle de cabeçalho.
CHeaderCtrl::SetItem	Define os atributos do item especificado em um controle de cabeçalho.
CHeaderCtrl::SetOrderArray	Define a ordem da esquerda para a direita de itens em um controle de cabeçalho.

Comentários

Um controle de cabeçalho é uma janela que geralmente é posicionada acima de um conjunto de colunas de texto ou números. Ele contém um título para cada coluna e pode ser dividido em partes. O usuário pode arrastar os divisores que separam as partes para definir a largura de cada coluna. Para obter uma ilustração de um controle de cabeçalho, consulte Controles de Cabeçalho.

Esse controle (e, portanto, a classe CHeaderCtrl) está disponível apenas para programas que são executados no Windows 95/98 e Windows NT versão 3.51 e posteriores.

A funcionalidade adicionada para controles comuns do Windows 95/Internet Explorer 4.0 inclui o seguinte:

Ordenação personalizada do item de cabeçalho.
Arraste e solte o item de cabeçalho para reordenar itens de cabeçalho. Use o estilo HDS_DRAGDROP ao criar o objeto CHeaderCtrl.
Texto da coluna de cabeçalho constantemente acessível durante o redimensionamento de coluna. Use o estilo HDS_FULLDRAG ao criar um objeto CHeaderCtrl.
Acompanhamento de cabeçalho frequente, que realça o item de cabeçalho quando o ponteiro está passando sobre ele. Use o estilo HDS_HOTTRACK ao criar o objeto CHeaderCtrl.
Suporte à lista de imagens. Os itens de cabeçalho podem conter imagens armazenadas em um objeto CImageList ou texto.

Para obter mais informações sobre como usar CHeaderCtrl, consulte Controles e Usar CHeaderCtrl.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CHeaderCtrl

Requisitos

Cabeçalho: afxcmn.h

CHeaderCtrl::CHeaderCtrl

Constrói um objeto CHeaderCtrl.

CHeaderCtrl();

Exemplo

// Declare a local CHeaderCtrl object.
CHeaderCtrl myHeaderCtrl;

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

CHeaderCtrl::ClearAllFilters

Limpa todos os filtros para um controle de cabeçalho.

BOOL ClearAllFilters();

Valor de retorno

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

Comentários

Esse método implementa o comportamento da mensagem Win32 HDM_CLEARFILTER com um valor de coluna de -1, conforme descrito no SDK do Windows.

Exemplo

m_myHeaderCtrl.ClearAllFilters();

CHeaderCtrl::ClearFilter

Limpa o filtro para um controle de cabeçalho.

BOOL ClearFilter(int nColumn);

Parâmetros

nColumn
Valor da coluna indicando qual filtro limpar.

Valor de retorno

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

Comentários

Esse método implementa o comportamento da mensagem Win32 HDM_CLEARFILTER, conforme descrito no SDK do Windows.

Exemplo

int iFilt = m_myHeaderCtrl.ClearFilter(1);

CHeaderCtrl::Create

Cria um controle de cabeçalho e o anexa a um objeto CHeaderCtrl.

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

Parâmetros

dwStyle
Especifica o estilo do controle de cabeçalho. Para obter uma descrição dos estilos de controle de cabeçalho, consulte Estilos de controle de cabeçalho no SDK do Windows.

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

pParentWnd
Especifica a janela pai do controle de cabeçalho, geralmente um CDialog. Não pode ser NULL.

Nid
Especifica a ID do controle de cabeçalho.

Valor de retorno

Diferente de zero se a inicialização for bem-sucedida. Caso contrário, zero.

Comentários

Um objeto CHeaderCtrl é construído em duas etapas. Primeiro, chame o construtor e, em seguida, chame Create, que cria o controle de cabeçalho e o anexa ao objeto CHeaderCtrl.

Além dos estilos de controle de cabeçalho, você pode usar os estilos de controle comuns a seguir para determinar como o controle de cabeçalho se posiciona e redimensiona (consulte Estilos de Controle Comuns para obter mais informações):

CCS_BOTTOM Faz com que o controle se posicione na parte inferior da área do cliente da janela pai e define a largura como igual à largura da janela pai.
CCS_NODIVIDER Impede que um realce de dois pixels seja desenhado na parte superior do controle.
CCS_NOMOVEY Faz com que o controle redimensione e mova a si próprio horizontalmente, mas não verticalmente, em resposta a uma mensagem WM_SIZE. Se o estilo CCS_NORESIZE for usado, esse estilo não será aplicável. Os controles de cabeçalho têm esse estilo por padrão.
CCS_NOPARENTALIGN Impede que o controle se mova automaticamente para a parte superior ou inferior da janela pai. Em vez disso, o controle mantém sua posição dentro da janela pai, apesar das alterações no tamanho da janela pai. Se o estilo CCS_TOP ou CCS_BOTTOM também for usado, a altura será ajustada para o padrão, mas a posição e a largura permanecerão inalteradas.
CCS_NORESIZE Impede que o controle use a largura e a altura padrão ao definir seu tamanho inicial ou um novo tamanho. Em vez disso, o controle usa a largura e a altura especificadas na solicitação de criação ou dimensionamento.
CCS_TOP Faz com que o controle se posicione na parte superior da área do cliente da janela pai e define a largura como igual à largura da janela pai.

Você também pode aplicar os seguintes estilos de janela a um controle de cabeçalho (consulte Estilos de Janela para obter mais informações):

WS_CHILD Cria uma janela filho. Não pode ser usado com o estilo WS_POPUP.
WS_VISIBLE Cria uma janela visível inicialmente.
WS_DISABLED Cria uma janela que desabilitada inicialmente.
WS_GROUP Especifica o primeiro controle de um grupo de controles no qual o usuário pode se mover de um controle para o outro com as teclas de direção. Todos os controles definidos com o estilo WS_GROUP após o primeiro controle pertencem ao mesmo grupo. O próximo controle com o estilo WS_GROUP encerra o grupo de estilos e inicia o próximo grupo (ou seja, um grupo termina onde o próximo começa).
WS_TABSTOP Especifica um controle dentre qualquer número de controles por meio do qual o usuário pode se mover usando a tecla TAB. A tecla TAB move o usuário para o próximo controle especificado pelo estilo WS_TABSTOP.

Se você quiser usar estilos de janela estendidos com seu controle, chame CreateEx em vez de Create.

Exemplo

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

Cria um controle (uma janela filho) e o associa ao objeto CHeaderCtrl.

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

Parâmetros

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

dwStyle
O estilo do controle de cabeçalho. Para obter uma descrição dos estilos de controle de cabeçalho, consulte Estilos de controle de cabeçalho no SDK do Windows. Consulte Criar para obter uma lista de estilos adicionais.

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

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

Nid
A ID da janela filho do controle.

Valor de retorno

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

Comentários

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

CHeaderCtrl::CreateDragImage

Cria uma versão transparente da imagem de um item dentro de um controle de cabeçalho.

CImageList* CreateDragImage(int nIndex);

Parâmetros

nIndex
O índice baseado em zero do item no controle de controle. A imagem atribuída a este item é a base para a imagem transparente.

Valor de retorno

Um ponteiro para um objeto CImageList se for bem-sucedido. Caso contrário, NULL. A lista retornada contém apenas uma imagem.

Comentários

Essa função membro implementa o comportamento da mensagem Win32 HDM_CREATEDRAGIMAGE, conforme descrito no SDK do Windows. Ela é fornecida para dar suporte ao arrastar e soltar de item de cabeçalho.

O objeto CImageList ao qual o ponteiro retornado aponta é um objeto temporário e é excluído no próximo processamento de tempo ocioso.

CHeaderCtrl::DeleteItem

Exclui um item de um controle de cabeçalho.

BOOL DeleteItem(int nPos);

Parâmetros

nPos
Especifica o índice de base zero do item a ser excluído.

Valor de retorno

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

Exemplo

int nCount = m_myHeaderCtrl.GetItemCount();

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

CHeaderCtrl::DrawItem

Chamado pela estrutura quando um aspecto visual de um controle do controle de cabeçalho desenhado pelo proprietário for alterado.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

lpDrawItemStruct
Um ponteiro para uma estrutura DRAWITEMSTRUCT descrevendo o item a ser pintado.

Comentários

O membro itemAction da estrutura DRAWITEMSTRUCT define a ação de desenho a ser executada.

Por padrão, essa função membro não faz nada. Substitua essa função de membro para implementar o desenho para um objeto CHeaderCtrl desenhado pelo proprietário.

O aplicativo deve restaurar todos os objetos GDI (Graphics Device Interface) selecionados para o contexto de exibição fornecido no lpDrawItemStruct antes que a função membro seja encerrada.

Exemplo

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

Começa a editar o filtro especificado de um controle de cabeçalho.

BOOL EditFilter(
    int nColumn,
    BOOL bDiscardChanges);

Parâmetros

nColumn
A coluna a ser editada.

bDiscardChanges
Um valor que especifica como lidar com as alterações de edição do usuário se o usuário estiver em processo de edição do filtro quando a mensagem HDM_EDITFILTER for enviada.

Especifique TRUE para descartar as alterações feitas pelo usuário ou FALSE para essas aceitar as alterações.

Valor de retorno

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

Comentários

Esse método implementa o comportamento da mensagem Win32 HDM_EDITFILTER, conforme descrito no SDK do Windows.

Exemplo

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

CHeaderCtrl::GetBitmapMargin

Recupera a largura da margem de um bitmap em um controle de cabeçalho.

int GetBitmapMargin() const;

Valor de retorno

A largura da margem do bitmap em pixels.

Comentários

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

Exemplo

int iMargin = m_myHeaderCtrl.GetBitmapMargin();

CHeaderCtrl::GetFocusedItem

Obtém o índice do item que tem o foco no controle de cabeçalho atual.

int GetFocusedItem() const;

Valor de retorno

O índice com base em zero do item de cabeçalho que tem o foco.

Comentários

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

Exemplo

O primeiro exemplo de código define a variável m_headerCtrl, que é usada para acessar o controle de cabeçalho atual. Essa variável será usada no próximo exemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra os métodos SetFocusedItem e GetFocusedItem. Em uma seção anterior do código, criamos um controle de cabeçalho com cinco colunas. No entanto, você pode arrastar um separador de coluna para que a coluna não fique visível. O exemplo a seguir define e confirma o último cabeçalho de coluna como o item de foco.

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 o identificador de uma lista de imagens usada para desenhar itens de cabeçalho em um controle de cabeçalho.

CImageList* GetImageList() const;

Valor de retorno

Um ponteiro para um objeto CImageList.

Comentários

Essa função membro implementa o comportamento da mensagem Win32 HDM_GETIMAGELIST, conforme descrito no SDK do Windows. O objeto CImageList ao qual o ponteiro retornado aponta é um objeto temporário e é excluído no próximo processamento de tempo ocioso.

Exemplo

// 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 informações sobre um item de controle de cabeçalho.

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

Parâmetros

nPos
Especifica o índice de base zero do item a ser recuperado.

pHeaderItem
Ponteiro para uma estrutura HDITEM que recebe o novo item. Essa estrutura é usada com as funções de membro InsertItem e SetItem. Todos os sinalizadores definidos no elemento mask garantem que os valores nos elementos correspondentes sejam preenchidos corretamente após o retorno. Se o elemento mask for definido como zero, os valores nos outros elementos de estrutura não têm sentido.

Valor de retorno

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

Exemplo

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 uma contagem dos itens em um controle de cabeçalho.

int GetItemCount() const;

Valor de retorno

Número de itens de controle de cabeçalho se for bem-sucedido. Caso contrário, - 1.

Exemplo

Consulte o exemplo de CHeaderCtrl::DeleteItem.

CHeaderCtrl::GetItemDropDownRect

Obtém o retângulo delimitador do botão suspenso para um item de cabeçalho no controle de cabeçalho atual.

BOOL GetItemDropDownRect(
    int iItem,
    LPRECT lpRect) const;

Parâmetros

iItem
[in] Índice baseado em zero de um item de cabeçalho cujo estilo é HDF_SPLITBUTTON. Para obter mais informações, consulte o membro fmt da estrutura HDITEM.

lpRect
[out] Ponteiro para uma estrutura RECT que recebe as informações do retângulo delimitador.

Valor de retorno

TRUE se a função for bem-sucedida. Caso contrário, FALSE.

Comentários

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

Exemplo

O primeiro exemplo de código define a variável m_headerCtrl, que é usada para acessar o controle de cabeçalho atual. Essa variável será usada no próximo exemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra o método GetItemDropDownRect. Em uma seção anterior do código, criamos um controle de cabeçalho com cinco colunas. O exemplo de código a seguir desenha um retângulo 3D ao redor do local na primeira coluna que está reservada para o botão suspenso de cabeçalho.

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 o retângulo delimitador para uma determinada banda em um controle de cabeçalho.

BOOL GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parâmetros

nIndex
O índice baseado em zero do item do controle de cabeçalho.

lpRect
Um ponteiro para o endereço de uma estrutura RECT que recebe as informações de retângulo delimitador.

Valor de retorno

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

Comentários

Esse método implementa o comportamento da mensagem Win32 HDM_GETITEMRECT, conforme descrito no SDK do Windows.

CHeaderCtrl::GetOrderArray

Recupera a ordem da esquerda para a direita de itens em um controle de cabeçalho.

BOOL GetOrderArray(
    LPINT piArray,
    int iCount);

Parâmetros

piArray
Um ponteiro para o endereço de um buffer que recebe os valores de índice dos itens no controle de cabeçalho, na ordem em que eles aparecem da esquerda para a direita.

iCount
O número de itens de controle de cabeçalho. Não deve ser negativo.

Valor de retorno

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

Comentários

Essa função membro implementa o comportamento da mensagem Win32 HDM_GETORDERARRAY, conforme descrito no SDK do Windows. Ela é fornecida para dar suporte à ordenação de item de cabeçalho.

Exemplo

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

Obtém o retângulo delimitador do botão de estouro do controle de cabeçalho atual.

BOOL GetOverflowRect(LPRECT lpRect) const;

Parâmetros

lpRect
[out] Ponteiro para uma estrutura RECT que recebe as informações do retângulo delimitador.

Valor de retorno

TRUE se a função for bem-sucedida. Caso contrário, FALSE.

Comentários

Se o controle de cabeçalho contém mais itens do que pode ser exibido simultaneamente, o controle pode exibir um botão de estouro que faz a rolagem até itens que não estão visíveis. O controle de cabeçalho deve ter os estilos HDS_OVERFLOW e HDF_SPLITBUTTON para exibir o botão de estouro. O retângulo delimitador inclui o botão de estouro e existe somente quando o botão de estouro é exibido. Para mais informações, confira Estilos de controle de cabeçalho.

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

Exemplo

O primeiro exemplo de código define a variável m_headerCtrl, que é usada para acessar o controle de cabeçalho atual. Essa variável será usada no próximo exemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra o método GetOverflowRect. Em uma seção anterior do código, criamos um controle de cabeçalho com cinco colunas. No entanto, você pode arrastar um separador de coluna para que a coluna não fique visível. Se algumas colunas não estiverem visíveis, o controle de cabeçalho desenhará um botão de estouro. O exemplo de código a seguir desenha um retângulo 3D ao redor do local do botão de estouro.

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 qual item de cabeçalho, se houver, está localizado em um ponto especificado.

int HitTest(LPHDHITTESTINFO* phdhti);

Parâmetros

phdhti
[in, out] Ponteiro para uma estrutura HDHITTESTINFO que especifica o ponto a ser testado e recebe os resultados do teste.

Valor de retorno

O índice baseado em zero do item de cabeçalho, se houver, na posição especificada. Caso contrário, -1.

Comentários

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

Exemplo

O primeiro exemplo de código define a variável m_headerCtrl, que é usada para acessar o controle de cabeçalho atual. Essa variável será usada no próximo exemplo.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra o método HitTest. Em uma seção anterior desse exemplo de código, criamos um controle de cabeçalho com cinco colunas. No entanto, você pode arrastar um separador de coluna para que a coluna não fique visível. Este exemplo relata o índice da coluna se ela estiver visível e -1 se a coluna não estiver visível.

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

Insere um novo item em um controle de cabeçalho no índice especificado.

int InsertItem(
    int nPos,
    HDITEM* phdi);

Parâmetros

nPos
O índice de base zero do item a ser inserido. Se o valor for zero, o item será inserido no início do controle de cabeçalho. Se o valor for maior que o valor máximo, o item será inserido no final do controle de cabeçalho.

phdi
Ponteiro para uma estrutura HDITEM que contém informações sobre o item a ser inserido.

Valor de retorno

Índice do novo item se for bem-sucedido. Caso contrário, -1.

Exemplo

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 o tamanho e a posição de um controle de cabeçalho em um determinado retângulo.

BOOL Layout(HDLAYOUT* pHeaderLayout);

Parâmetros

pHeaderLayout
Ponteiro para uma estrutura HDLAYOUT, que contém informações usadas para definir o tamanho e a posição de um controle de cabeçalho.

Valor de retorno

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

Comentários

Essa função é usada para determinar as dimensões apropriadas para um novo controle de cabeçalho que deve ocupar o retângulo especificado.

Exemplo

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 o valor do índice de um item com base em sua ordem no controle de cabeçalho.

int OrderToIndex(int nOrder) const;

Parâmetros

nOrder
A ordem baseada em zero na qual o item aparece no controle de cabeçalho, da esquerda para a direita.

Valor de retorno

O índice do item, com base em sua ordem no controle de cabeçalho. O índice conta da esquerda para a direita, começando com 0.

Comentários

Essa função membro implementa o comportamento da macro do Win32 HDM_ORDERTOINDEX, conforme descrito no SDK do Windows. Ela é fornecida para dar suporte à ordenação de item de cabeçalho.

CHeaderCtrl::SetBitmapMargin

Define a largura da margem de um bitmap em um controle de cabeçalho.

int SetBitmapMargin(int nWidth);

Parâmetros

nWidth
Largura, especificada em pixels, da margem que cerca um bitmap dentro de um controle de cabeçalho existente.

Valor de retorno

A largura da margem do bitmap em pixels.

Comentários

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

Exemplo

int iOldMargin = m_myHeaderCtrl.SetBitmapMargin(15);

CHeaderCtrl::SetFilterChangeTimeout

Define o intervalo de tempo limite entre o tempo em que uma alteração ocorre nos atributos de filtro e a postagem de uma notificação HDN_FILTERCHANGE.

int SetFilterChangeTimeout(DWORD dwTimeOut);

Parâmetros

dwTimeOut
Valor de tempo limite, em milissegundos.

Valor de retorno

O índice do controle de filtro modificado.

Comentários

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

Exemplo

int iFltr = m_myHeaderCtrl.SetFilterChangeTimeout(15);

CHeaderCtrl::SetFocusedItem

Define o foco em um item de cabeçalho especificado no controle de cabeçalho atual.

BOOL SetFocusedItem(int iItem);

Parâmetros

iItem
[in] Índice baseado em zero de um item de cabeçalho.

Valor de retorno

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

Comentários

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

Exemplo

O primeiro exemplo de código define a variável m_headerCtrl, que é usada para acessar o controle de cabeçalho atual. Essa variável será usada no próximo exemplo.

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

Altera o divisor entre itens de cabeçalho para indicar um arrastar e soltar manual de um item de cabeçalho.

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

Parâmetros

pt
A posição do ponteiro. O controle de cabeçalho realça o divisor apropriado com base na posição do ponteiro.

nIndex
O índice do divisor realçado.

Valor de retorno

O índice do divisor realçado.

Comentários

Essa função membro implementa o comportamento da mensagem Win32 HDM_SETHOTDIVIDER, conforme descrito no SDK do Windows. Ela é fornecida para dar suporte ao arrastar e soltar de item de cabeçalho.

Exemplo

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

   CHeaderCtrl::OnMouseMove(nFlags, point);
}

CHeaderCtrl::SetImageList

Atribui uma lista de imagens a um controle de cabeçalho.

CImageList* SetImageList(CImageList* pImageList);

Parâmetros

pImageList
Um ponteiro para um objeto CImageList que contém a lista de imagens a ser atribuída ao controle de cabeçalho.

Valor de retorno

Um ponteiro para o objeto CImageList atribuído anteriormente ao controle de cabeçalho.

Comentários

Essa função membro implementa o comportamento da mensagem Win32 HDM_SETIMAGELIST, conforme descrito no SDK do Windows. O objeto CImageList ao qual o ponteiro retornado aponta é um objeto temporário e é excluído no próximo processamento de tempo ocioso.

Exemplo

Consulte o exemplo de CHeaderCtrl::GetImageList.

CHeaderCtrl::SetItem

Define os atributos do item especificado em um controle de cabeçalho.

BOOL SetItem(
    int nPos,
    HDITEM* pHeaderItem);

Parâmetros

nPos
O índice de base zero do item a ser manipulado.

pHeaderItem
Ponteiro para uma estrutura HDITEM que contém informações sobre o item novo.

Valor de retorno

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

Exemplo

Consulte o exemplo de CHeaderCtrl::GetItem.

CHeaderCtrl::SetOrderArray

Define a ordem da esquerda para a direita de itens em um controle de cabeçalho.

BOOL SetOrderArray(
    int iCount,
    LPINT piArray);

Parâmetros

iCount
O número de itens de controle de cabeçalho.

piArray
Um ponteiro para o endereço de um buffer que recebe os valores de índice dos itens no controle de cabeçalho, na ordem em que eles aparecem da esquerda para a direita.

Valor de retorno

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

Comentários

Essa função membro implementa o comportamento da macro do Win32 HDM_SETORDERARRAY, conforme descrito no SDK do Windows. Ela é fornecida para dar suporte à ordenação de item de cabeçalho.

Exemplo

Consulte o exemplo de CHeaderCtrl::GetOrderArray.

Confira também

Classe CWnd
Gráfico da hierarquia
Classe CTabCtrl
Classe CListCtrl
Classe CImageList

Partilhar via

Classe CHeaderCtrl

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CHeaderCtrl::CHeaderCtrl

Exemplo

CHeaderCtrl::ClearAllFilters

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::ClearFilter

Parâmetros

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::CreateEx

Parâmetros

Valor de retorno

Comentários

CHeaderCtrl::CreateDragImage

Parâmetros

Valor de retorno

Comentários

CHeaderCtrl::DeleteItem

Parâmetros

Valor de retorno

Exemplo

CHeaderCtrl::DrawItem

Parâmetros

Comentários

Exemplo

CHeaderCtrl::EditFilter

Parâmetros

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::GetBitmapMargin

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::GetFocusedItem

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::GetImageList

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::GetItem

Parâmetros

Valor de retorno

Exemplo

CHeaderCtrl::GetItemCount

Valor de retorno

Exemplo

CHeaderCtrl::GetItemDropDownRect

Parâmetros

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::GetItemRect

Parâmetros

Valor de retorno

Comentários

CHeaderCtrl::GetOrderArray

Parâmetros

Valor de retorno

Comentários

Exemplo

CHeaderCtrl::GetOverflowRect