Classe CHeaderCtrl

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

Sintaxe

class CHeaderCtrl : public CWnd

Membros

Construtores Públicos

Métodos Públicos

Observações

Um controlo de cabeçalho é uma janela que normalmente está posicionada acima de um conjunto de colunas de texto ou números. Contém um título para cada coluna e pode ser dividida em partes. O utilizador pode arrastar os divisores que separam as partes para definir a largura de cada coluna. Para uma ilustração de um controlo de cabeçalho, veja Controlos de Cabeçalho.

Este controlo (e, portanto, a CHeaderCtrl classe) está disponível apenas para programas que correm sob Windows 95/98 e Windows NT versão 3.51 e posteriores.

Funcionalidades adicionadas para controlos comuns do Windows 95/Internet Explorer 4.0 incluem o seguinte:

• Encomenda personalizada de itens de cabeçalho.

• Arrastar e largar itens de cabeçalho, para reordenar itens de cabeçalho. Usa o estilo HDS_DRAGDROP quando criares o CHeaderCtrl objeto.

• O texto da coluna do cabeçalho está constantemente visível durante o redimensionamento da coluna. Usa o estilo HDS_FULLDRAG quando criares um CHeaderCtrl objeto.

• Seguimento de cabeçalho quente, que destaca o item do cabeçalho quando o ponteiro está a pairar sobre ele. Use o estilo HDS_HOTTRACK quando criar o CHeaderCtrl objeto.

• Suporte para listas de imagens. Os itens de cabeçalho podem conter imagens armazenadas num CImageList objeto ou texto.

Para mais informações sobre a utilização CHeaderCtrlde , veja Controlos e Utilização do CHeaderCtrl.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CHeaderCtrl

Requerimentos

Cabeçalho: afxcmn.h

CHeaderCtrl::CHeaderCtrl

Constrói um CHeaderCtrl objeto.

CHeaderCtrl();

Example

// Declare a local CHeaderCtrl object.
CHeaderCtrl myHeaderCtrl;

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

CHeaderCtrl::ClearAllFilters

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

BOOL ClearAllFilters();

Valor de retorno

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

Observações

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

Example

m_myHeaderCtrl.ClearAllFilters();

CHeaderCtrl::ClearFilter

Limpa o filtro para um controlo de cabeçalho.

BOOL ClearFilter(int nColumn);

Parâmetros

nColumn
Valor de coluna a indicar qual filtro eliminar.

Valor de retorno

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

Observações

Este método implementa o comportamento da HDM_CLEARFILTER de mensagens Win32, conforme descrito no SDK do Windows.

Example

int iFilt = m_myHeaderCtrl.ClearFilter(1);

CHeaderCtrl::Create

Cria um controlo de cabeçalho e liga-o a um CHeaderCtrl objeto.

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

Parâmetros

dwStyle
Especifica o estilo do controlo do cabeçalho. Para uma descrição dos estilos de controlo de cabeçalhos, veja Estilos de Controlo de Cabeçalho no SDK do Windows.

retângulo
Especifica o tamanho e a posição do controlo do cabeçalho. Pode ser um objeto CRect ou uma estrutura RECT .

pParentWnd
Especifica a janela pai do controlo do cabeçalho, normalmente um CDialog. Não pode ser NULL.

nID
Especifica o ID do controlo do cabeçalho.

Valor de retorno

Não nula se a inicialização fosse bem-sucedida; caso contrário, zero.

Observações

Constroem um CHeaderCtrl objeto em dois passos. Primeiro, chama o construtor e depois chama Create, que cria o controlo do cabeçalho e o anexa ao CHeaderCtrl objeto.

Para além dos estilos de controlo do cabeçalho, pode usar os seguintes estilos de controlo comuns para determinar como o cabeçalho se posiciona e se redimensiona (ver Estilos de Controlo Comuns para mais informações):

• CCS_BOTTOM Faz com que o controlo se posicione na parte inferior da área cliente da janela pai e define a largura para ser igual à largura da janela principal.

• CCS_NODIVIDER Impede que um destaque de dois píxeis seja desenhado no topo do controlo.

• CCS_NOMOVEY Faz com que o controlo se redimensione e se mova horizontalmente, mas não verticalmente, em resposta a uma mensagem WM_SIZE. Se for usado o estilo CCS_NORESIZE, este estilo não se aplica. Os controlos de cabeçalho têm este estilo por defeito.

• CCS_NOPARENTALIGN Impede que o controlo se mova automaticamente para o topo ou para a parte inferior da janela principal. Em vez disso, o controlo mantém a sua posição dentro da janela pai apesar das alterações no tamanho da janela pai. Se também for usado o estilo CCS_TOP ou CCS_BOTTOM, a altura é ajustada para o padrão, mas a posição e a largura mantêm-se inalteradas.

• CCS_NORESIZE Impede que o controlo use a largura e altura padrão ao definir o seu tamanho inicial ou um novo tamanho. Em vez disso, o controlo utiliza a largura e altura especificadas no pedido de criação ou dimensionamento.

• CCS_TOP Faz com que o controlo se posicione no topo da área cliente da janela pai e define a largura para ser igual à largura da janela pai.

Também pode aplicar os seguintes estilos de janela a um controlo de cabeçalho (veja Estilos de Janelas para mais informações):

• WS_CHILD Cria uma janela criança. Não pode ser usado com o estilo WS_POPUP.

• WS_VISIBLE Cria uma janela que é inicialmente visível.

• WS_DISABLED Cria uma janela que está inicialmente desativada.

• WS_GROUP Especifica o primeiro controlo de um grupo de controlos em que o utilizador pode mover-se de um controlo para outro com as setas. Todos os controlos definidos com o estilo WS_GROUP após o primeiro controlo pertencem ao mesmo grupo. O controlo seguinte com o estilo WS_GROUP termina o grupo de estilos e inicia o grupo seguinte (ou seja, um grupo termina onde começa o seguinte).

• WS_TABSTOP Especifica um dos inúmeros controlos através dos quais o utilizador pode mover-se usando a tecla TAB. A tecla TAB move o utilizador para o controlo seguinte especificado pelo estilo WS_TABSTOP.

Se quiseres usar estilos de janelas estendidas com o teu controlo, chama CreateEx em vez de Create.

Example

// 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 controlo (uma janela filha) e associa-o ao CHeaderCtrl objeto.

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

Parâmetros

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

dwStyle
O estilo do controlo do cabeçalho. Para uma descrição dos estilos de controlo de cabeçalhos, veja Estilos de Controlo de Cabeçalho no SDK do Windows. Consulte Criar para uma lista de estilos adicionais.

retângulo
Uma referência a uma estrutura RECT que descreve o tamanho e a posição da janela a criar, em coordenadas cliente de pParentWnd.

pParentWnd
Um apontador para a janela que é o pai do controlo.

nID
O ID da janela criança do controlo.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

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

CHeaderCtrl::CreateDragImage

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

CImageList* CreateDragImage(int nIndex);

Parâmetros

nIndex
O índice baseado em zero do item dentro do controlo do cabeçalho. A imagem atribuída a este item é a base para a imagem transparente.

Valor de retorno

Um apontador para um objeto CImageList se for bem-sucedido; caso contrário, NULL. A lista devolvida contém apenas uma imagem.

Observações

Esta função membro implementa o comportamento da HDM_CREATEDRAGIMAGE de mensagens Win32, conforme descrito no SDK do Windows. É fornecido para suportar arrastar e largar itens de cabeçalho.

O CImageList objeto para o qual o ponteiro retornado aponta é um objeto temporário e é eliminado no próximo processamento em tempo ocioso.

CHeaderCtrl::D eleteItem

Apaga um item de um controlo de cabeçalho.

BOOL DeleteItem(int nPos);

Parâmetros

nPos
Especifica o índice base zero do item a eliminar.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Example

int nCount = m_myHeaderCtrl.GetItemCount();

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

CHeaderCtrl::D rawItem

Chamado pela framework quando um aspeto visual do controlo de cabeçalho proprietário-draw muda.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

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

Observações

O itemAction elemento da DRAWITEMSTRUCT estrutura define a ação de desenho que deve ser realizada.

Por defeito, esta função membro não faz nada. Substitua esta função de membro para implementar desenho para um objeto proprietário-desenho CHeaderCtrl .

A aplicação deve restaurar todos os objetos da interface do dispositivo gráfico (GDI) selecionados para o contexto de visualização fornecido em lpDrawItemStruct antes de esta função membro terminar.

Example

// 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 controlo de cabeçalho.

BOOL EditFilter(
    int nColumn,
    BOOL bDiscardChanges);

Parâmetros

nColumn
A coluna a editar.

bDiscardsAlterações
Um valor que especifica como lidar com as alterações de edição do utilizador caso este esteja a editar o filtro quando a mensagem HDM_EDITFILTER é enviada.

Especifique TRUE para descartar as alterações feitas pelo utilizador, ou FALSE para aceitar as alterações feitas pelo utilizador.

Valor de retorno

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

Observações

Este método implementa o comportamento da HDM_EDITFILTER de mensagens Win32, conforme descrito no SDK do Windows.

Example

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

CHeaderCtrl::GetBitmapMargin

Recupera a largura da margem de um bitmap num controlo de cabeçalho.

int GetBitmapMargin() const;

Valor de retorno

A largura da margem do bitmap em pixels.

Observações

Esta função membro implementa o comportamento da HDM_GETBITMAPMARGIN de mensagens Win32, conforme descrito no SDK do Windows.

Example

int iMargin = m_myHeaderCtrl.GetBitmapMargin();

CHeaderCtrl::GetFocusedItem

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

int GetFocusedItem() const;

Valor de retorno

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

Observações

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

Example

O primeiro exemplo de código define a variável, m_headerCtrl, que é usada para aceder ao controlo atual do cabeçalho. Esta variável é usada no exemplo seguinte.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra os SetFocusedItem métodos e GetFocusedItem . Numa secção anterior do código, criámos um controlo de cabeçalho com cinco colunas. No entanto, pode arrastar um separador de coluna para que a coluna não fique visível. O exemplo seguinte define e depois confirma o último cabeçalho da coluna como o elemento 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 handle de uma lista de imagens usada para desenhar itens de cabeçalho num controlo de cabeçalho.

CImageList* GetImageList() const;

Valor de retorno

Um apontador para um objeto CImageList .

Observações

Esta função membro implementa o comportamento da HDM_GETIMAGELIST de mensagens Win32, conforme descrito no SDK do Windows. O CImageList objeto para o qual o ponteiro retornado aponta é um objeto temporário e é eliminado no próximo processamento em tempo ocioso.

Example

// 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ção sobre um item de controlo de cabeçalho.

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

Parâmetros

nPos
Especifica o índice zero do item a recuperar.

pHeaderItem
Apontar para uma estrutura HDITEM que recebe o novo item. Esta estrutura é usada com as InsertItem funções dos membros e SetItem (). Quaisquer flags definidos no mask elemento garantem que os valores nos elementos correspondentes são devidamente preenchidos quando retornados. Se o mask elemento for definido para zero, os valores nos outros elementos da estrutura são sem sentido.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Example

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 a contagem dos itens num controlo de cabeçalho.

int GetItemCount() const;

Valor de retorno

Número de itens de controlo de cabeçalho se bem-sucedido; caso contrário - 1.

Example

Veja o exemplo de CHeaderCtrl::D eleteItem.

CHeaderCtrl::GetItemDropDownRect

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

BOOL GetItemDropDownRect(
    int iItem,
    LPRECT lpRect) const;

Parâmetros

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

lpRect
[fora] Apontar para uma estrutura RECT para receber a informação do retângulo delimitador.

Valor de retorno

TRUE se esta função for bem-sucedida; caso contrário, FALSO.

Observações

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

Example

O primeiro exemplo de código define a variável, m_headerCtrl, que é usada para aceder ao controlo atual do cabeçalho. Esta variável é usada no exemplo seguinte.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra o GetItemDropDownRect método. Numa secção anterior do código, criámos um controlo de cabeçalho com cinco colunas. O exemplo de código seguinte desenha um retângulo 3D à volta da localização na primeira coluna que está reservada para o botão suspenso do 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 de um dado item num controlo de cabeçalho.

BOOL GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parâmetros

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

lpRect
Um ponteiro para o endereço de uma estrutura RECT que recebe a informação do retângulo delimitador.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

Este método implementa o comportamento da HDM_GETITEMRECT de mensagens Win32, conforme descrito no SDK do Windows.

CHeaderCtrl::GetOrderArray

Recupera a ordem da esquerda para a direita dos itens num controlo 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 controlo do cabeçalho, na ordem em que aparecem da esquerda para a direita.

iCount
O número de itens de controlo do cabeçalho. O valor deve ser não negativo.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

Esta função membro implementa o comportamento da HDM_GETORDERARRAY de mensagens Win32, conforme descrito no SDK do Windows. É fornecido para suportar a encomenda de itens de cabeçalho.

Example

// 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 overflow do controlo do cabeçalho atual.

BOOL GetOverflowRect(LPRECT lpRect) const;

Parâmetros

lpRect
[fora] Apontador para uma estrutura RECT que recebe a informação do retângulo delimitador.

Valor de retorno

TRUE se esta função for bem-sucedida; caso contrário, FALSO.

Observações

Se o controlo do cabeçalho contiver mais itens do que podem ser exibidos simultaneamente, o controlo pode mostrar um botão de overflow que desloca para itens que não são visíveis. O controlo do cabeçalho deve ter os estilos HDS_OVERFLOW e HDF_SPLITBUTTON para mostrar o botão de overflow. O retângulo delimitador envolve o botão de transbordo e existe apenas quando o botão de transbordamento é exibido. Para mais informações, consulte Estilos de Controlo de Cabeçalhos.

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

Example

O primeiro exemplo de código define a variável, m_headerCtrl, que é usada para aceder ao controlo atual do cabeçalho. Esta variável é usada no exemplo seguinte.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra o GetOverflowRect método. Numa secção anterior do código, criámos um controlo de cabeçalho com cinco colunas. No entanto, pode arrastar um separador de coluna para que a coluna não fique visível. Se algumas colunas não forem visíveis, o controlo do cabeçalho desenha um botão de transbordamento. O exemplo de código seguinte desenha um retângulo 3D em torno da localização do botão de transbordo.

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 o item do cabeçalho, se algum, está localizado num ponto especificado.

int HitTest(LPHDHITTESTINFO* phdhti);

Parâmetros

Phdhti
[inspira, expira] Apontar para uma estrutura HDHITTESTINFO que especifica o ponto a testar e recebe os resultados do teste.

Valor de retorno

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

Observações

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

Example

O primeiro exemplo de código define a variável, m_headerCtrl, que é usada para aceder ao controlo atual do cabeçalho. Esta variável é usada no exemplo seguinte.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra o HitTest método. Numa secção anterior deste exemplo de código, criámos um controlo de cabeçalho com cinco colunas. No entanto, pode arrastar um separador de coluna para que a coluna não fique visível. Este exemplo reporta o índice da coluna se esta for visível e -1 se a coluna não for 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 num controlo de cabeçalho no índice especificado.

int InsertItem(
    int nPos,
    HDITEM* phdi);

Parâmetros

nPos
O índice base zero do item a inserir. Se o valor for zero, o item é inserido no início do controlo do cabeçalho. Se o valor for superior ao valor máximo, o item é inserido no final do controlo do cabeçalho.

PHDI
Apontador para uma estrutura HDITEM que contém informação sobre o item a inserir.

Valor de retorno

Índice do novo item se bem-sucedido; caso contrário - 1.

Example

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 controlo de cabeçalho dentro de um dado retângulo.

BOOL Layout(HDLAYOUT* pHeaderLayout);

Parâmetros

pHeaderLayout
Apontador para uma estrutura HDLAYOUT , que contém informação usada para definir o tamanho e a posição de um controlo de cabeçalho.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

Esta função é usada para determinar as dimensões apropriadas para um novo controlo de cabeçalho que ocupará o retângulo dado.

Example

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 na sua ordem no controlo do cabeçalho.

int OrderToIndex(int nOrder) const;

Parâmetros

nOrder
A ordem zero em que o item aparece no controlo do cabeçalho, da esquerda para a direita.

Valor de retorno

O índice do item, baseado na sua ordem no controlo do cabeçalho. O índice conta da esquerda para a direita, começando com 0.

Observações

Esta função membro implementa o comportamento do HDM_ORDERTOINDEX de macros Win32, conforme descrito no SDK do Windows. É fornecido para suportar a encomenda de itens de cabeçalho.

CHeaderCtrl::SetBitmapMargin

Define a largura da margem de um bitmap num controlo de cabeçalho.

int SetBitmapMargin(int nWidth);

Parâmetros

nLargura
Largura, especificada em pixels, da margem que envolve um bitmap dentro de um controlo de cabeçalho existente.

Valor de retorno

A largura da margem do bitmap em pixels.

Observações

Esta função membro implementa o comportamento da HDM_SETBITMAPMARGIN de mensagens Win32, conforme descrito no SDK do Windows.

Example

int iOldMargin = m_myHeaderCtrl.SetBitmapMargin(15);

CHeaderCtrl::SetFilterChangeTimeout

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

int SetFilterChangeTimeout(DWORD dwTimeOut);

Parâmetros

dwTimeOut
Valor de timeout, em milissegundos.

Valor de retorno

O índice do controlo do filtro a ser modificado.

Observações

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

Example

int iFltr = m_myHeaderCtrl.SetFilterChangeTimeout(15);

CHeaderCtrl::SetFocusedItem

Define o foco para um elemento de cabeçalho especificado no controlo atual do cabeçalho.

BOOL SetFocusedItem(int iItem);

Parâmetros

iItem
[dentro] Índice em base zero de um item do cabeçalho.

Valor de retorno

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

Observações

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

Example

O primeiro exemplo de código define a variável, m_headerCtrl, que é usada para aceder ao controlo atual do cabeçalho. Esta variável é usada no exemplo seguinte.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

O próximo exemplo de código demonstra os SetFocusedItem métodos e GetFocusedItem . Numa secção anterior do código, criámos um controlo de cabeçalho com cinco colunas. No entanto, pode arrastar um separador de coluna para que a coluna não fique visível. O exemplo seguinte define e depois confirma o último cabeçalho da coluna como o elemento 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::SetHotDivider

Altera o divisor entre os itens do cabeçalho para indicar um arrastar e largar manualmente um item do cabeçalho.

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

Parâmetros

pt
A posição do apontador. O controlo do cabeçalho destaca o divisor apropriado com base na posição do ponteiro.

nIndex
O índice do divisor destacado.

Valor de retorno

O índice do divisor destacado.

Observações

Esta função membro implementa o comportamento da HDM_SETHOTDIVIDER de mensagens Win32, conforme descrito no SDK do Windows. É fornecido para suportar arrastar e largar itens de cabeçalho.

Example

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

   CHeaderCtrl::OnMouseMove(nFlags, point);
}

CHeaderCtrl::SetImageList

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

CImageList* SetImageList(CImageList* pImageList);

Parâmetros

pImageList
Um ponteiro para um CImageList objeto contendo a lista de imagens a ser atribuído ao controlo do cabeçalho.

Valor de retorno

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

Observações

Esta função membro implementa o comportamento do HDM_SETIMAGELIST de mensagens Win32, conforme descrito no SDK do Windows. O CImageList objeto para o qual o ponteiro retornado aponta é um objeto temporário e é eliminado no próximo processamento em tempo ocioso.

Example

Veja o exemplo para CHeaderCtrl::GetImageList.

CHeaderCtrl::SetItem

Define os atributos do item especificado num controlo de cabeçalho.

BOOL SetItem(
    int nPos,
    HDITEM* pHeaderItem);

Parâmetros

nPos
O índice de base zero do item a manipular.

pHeaderItem
Apontador para uma estrutura HDITEM que contém informação sobre o novo item.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Example

Veja o exemplo de CHeaderCtrl::GetItem.

CHeaderCtrl::SetOrderArray

Define a ordem da esquerda para a direita dos itens num controlo de cabeçalho.

BOOL SetOrderArray(
    int iCount,
    LPINT piArray);

Parâmetros

iCount
O número de itens de controlo do cabeçalho.

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

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

Esta função membro implementa o comportamento do HDM_SETORDERARRAY de macros Win32, conforme descrito no SDK do Windows. É fornecido para suportar a encomenda de itens de cabeçalho.

Example

Veja o exemplo de CHeaderCtrl::GetOrderArray.

Consulte também

Classe CWnd
Gráfico de Hierarquia
Classe CTabCtrl
Classe CListCtrl
Classe CImageList