Classe CMFCCaptionBar

  • Artigo

Um objeto CMFCCaptionBar é uma barra de controle que pode exibir três elementos: um botão, um rótulo de texto e um bitmap. Ele só pode exibir um elemento de cada tipo por vez. Você pode alinhar cada elemento às bordas esquerda ou direita do controle ou ao centro. Você também pode aplicar um estilo plano ou em 3D às bordas superior e inferior da barra de legenda.

Sintaxe

class CMFCCaptionBar : public CPane

Membros

Métodos públicos

Nome Descrição
CMFCCaptionBar::Create Cria o controle de barra de legenda e o anexa ao objeto CMFCCaptionBar.
CMFCCaptionBar::DoesAllowDynInsertBefore Indica se outro painel pode ser inserido dinamicamente entre a barra de legenda e seu quadro pai. (Substitui CBasePane::DoesAllowDynInsertBefore.)
CMFCCaptionBar::EnableButton Habilita ou desabilita o botão na barra de legenda.
CMFCCaptionBar::GetAlignment Retorna o alinhamento do elemento especificado.
CMFCCaptionBar::GetBorderSize Retorna o tamanho da borda da barra de legenda.
CMFCCaptionBar::GetButtonRect Recupera o retângulo delimitador do botão na barra de legendas.
CMFCCaptionBar::GetMargin Retorna a distância entre a borda dos elementos da barra de legenda e a borda do controle de barra de legenda.
CMFCCaptionBar::IsMessageBarMode Especifica se a barra de legenda está no modo de barra de mensagens.
CMFCCaptionBar::RemoveBitmap Remove a imagem bitmap da barra de legenda.
CMFCCaptionBar::RemoveButton Remove o botão da barra de legenda.
CMFCCaptionBar::RemoveIcon Remove o ícone da barra de legenda.
CMFCCaptionBar::RemoveText Remove o rótulo de texto da barra de legenda.
CMFCCaptionBar::SetBitmap Define a imagem de bitmap para a barra de legenda.
CMFCCaptionBar::SetBorderSize Define o tamanho da borda da barra de legenda.
CMFCCaptionBar::SetButton Define o botão para a barra de legenda.
CMFCCaptionBar::SetButtonPressed Especifica se o botão permanece ou não pressionado.
CMFCCaptionBar::SetButtonToolTip Define a dica de ferramenta para o botão.
CMFCCaptionBar::SetFlatBorder Define o estilo da borda da barra de legenda.
CMFCCaptionBar::SetIcon Define o ícone de uma barra de legenda.
CMFCCaptionBar::SetImageToolTip Define a dica de ferramenta para a imagem da barra de legenda.
CMFCCaptionBar::SetMargin Define a distância entre a borda do elemento de barra de legenda e a borda do controle de barra de legenda.
CMFCCaptionBar::SetText Define o rótulo de texto para a barra de legenda.

Métodos protegidos

Nome Descrição
CMFCCaptionBar::OnDrawBackground Chamado pela estrutura para preencher o plano de fundo da barra de legenda.
CMFCCaptionBar::OnDrawBorder Chamado pela estrutura para desenhar a borda da barra de legenda.
CMFCCaptionBar::OnDrawButton Chamado pela estrutura para desenhar o botão da barra de legenda.
CMFCCaptionBar::OnDrawImage Chamado pela estrutura para desenhar a imagem da barra de legenda.
CMFCCaptionBar::OnDrawText Chamado pela estrutura para desenhar o texto da barra de legenda.

Membros de dados

Nome Descrição
CMFCCaptionBar::m_clrBarBackground A cor da tela de fundo da barra de legenda.
CMFCCaptionBar::m_clrBarBorder A cor da borda da barra de legenda.
CMFCCaptionBar::m_clrBarText A cor do texto da barra de legendas.

Comentários

Para criar uma barra de legendas, siga estas etapas:

  1. Construa o objeto CMFCCaptionBar. Normalmente, a barra de legenda é adicionada a uma classe de janela do quadro.

  2. Chame o método CMFCCaptionBar::Create para criar o controle de barra de legenda e anexá-lo ao objeto CMFCCaptionBar.

  3. Chame CMFCCaptionBar::SetButton, CMFCCaptionBar::SetText, CMFCCaptionBar::SetIcon e CMFCCaptionBar::SetBitmap para definir os elementos da barra de legenda.

Ao definir o elemento de botão, você deve atribuir uma ID de comando ao botão. Quando o usuário clica no botão, a barra de legenda roteia as mensagens WM_COMMAND que têm essa ID para a janela do quadro pai.

A barra de legendas também pode funcionar no modo de barra de mensagens, o que emula a barra de mensagens que aparece em aplicativos do Microsoft Office 2007. No modo de barra de mensagens, a barra de legendas exibe um bitmap, uma mensagem e um botão (que normalmente abre uma caixa de diálogo). Você pode atribuir uma dica de ferramenta ao bitmap.

Para habilitar o modo de barra de mensagens, chame CMFCCaptionBar::Create e defina o quarto parâmetro (bIsMessageBarMode) como TRUE.

Exemplo

O exemplo a seguir demonstra como usar vários métodos na classe CMFCCaptionBar. O exemplo mostra como criar o controle de barra de legenda, definir uma borda em 3D da barra de legenda, definir a distância, em pixels, entre a borda dos elementos da barra de legendas e a borda do controle da barra de legendas, definir o botão para a barra de legendas, definir a dica de ferramenta para o botão, definir o rótulo de texto para a barra de legenda, definir a imagem de bitmap para a barra de legendas e definir a dica de ferramenta para a imagem na barra de legendas. Este snippet de código faz parte do exemplo de Demonstração do MS Office 2007.

CMFCCaptionBar m_wndMessageBar;

BOOL CMainFrame::CreateMessageBar()
{
   // The this pointer points to a CMainFrame class which extends the CFrameWndEx class.
   if (!m_wndMessageBar.Create(WS_CHILD | WS_VISIBLE | WS_CLIPSIBLINGS, this, ID_VIEW_MESSAGEBAR, -1, TRUE))
   {
      TRACE0("Failed to create caption bar\n");
      return FALSE;
   }

   m_wndMessageBar.SetFlatBorder(FALSE);
   m_wndMessageBar.SetMargin(10);
   m_wndMessageBar.SetButton(_T("Options..."), ID_TOOLS_OPTIONS, CMFCCaptionBar::ALIGN_LEFT, FALSE);
   m_wndMessageBar.SetButtonToolTip(_T("Click here to see more options"));

   m_wndMessageBar.SetText(_T("Welcome to the MFC MSOffice2007 demonstration!"), CMFCCaptionBar::ALIGN_LEFT);

   m_wndMessageBar.SetBitmap(IDB_INFO, RGB(255, 255, 255), FALSE, CMFCCaptionBar::ALIGN_LEFT);
   m_wndMessageBar.SetImageToolTip(_T("Important"), _T("Please take a look at MSOffice2007Demo source code to learn how to create advanced user interface in minutes."));

   return TRUE;
}

Hierarquia de herança

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCCaptionBar

Requisitos

Cabeçalho: afxcaptionbar.h

CMFCCaptionBar::Create

Cria o controle de barra de legenda e o anexa ao objeto CMFCCaptionBar.

BOOL Create(
    DWORD dwStyle,
    CWnd* pParentWnd,
    UINT uID,
    int nHeight=-1,
    BOOL bIsMessageBarMode=FALSE);

Parâmetros

dwStyle
A combinação OR lógica dos estilos de barra de legenda.

pParentWnd
A janela pai do controle da barra de legenda.

uID
A ID do controle de barra de legenda.

nHeight
A altura, em pixels, do controle da barra de legenda. Se for -1, a altura será calculada de acordo com a altura do ícone, o texto e o botão exibidos pelo controle da barra de legenda.

bIsMessageBarMode
TRUE se a barra de legenda estiver no modo de barra de mensagens; FALSE caso contrário.

Valor de retorno

TRUE se o controle de barra de legenda for criado com êxito; FALSE caso contrário.

Comentários

Um objeto CMFCCaptionBar é construído em duas etapas. Primeiro chame o construtor e, em seguida, chame o método Create, que cria o controle do Windows e o anexa ao objeto CMFCCaptionBar.

CMFCCaptionBar::DoesAllowDynInsertBefore

Indica se outro painel pode ser inserido dinamicamente entre a barra de legenda e seu quadro pai.

virtual BOOL DoesAllowDynInsertBefore() const;

Valor de retorno

Retorna FALSE, a menos que seja substituído.

Comentários

CMFCCaptionBar::EnableButton

Habilita ou desabilita o botão na barra de legenda.

void EnableButton(BOOL bEnable=TRUE);

Parâmetros

bEnable
[in] TRUE para habilitar o botão; FALSE para desabilitá-lo.

CMFCCaptionBar::GetAlignment

Retorna o alinhamento do elemento especificado.

BarElementAlignment GetAlignment(BarElement elem);

Parâmetros

elem
[in] Um elemento de barra de legenda para o qual recuperar o alinhamento.

Valor de retorno

O alinhamento de um elemento, como um botão, um bitmap, um texto ou um ícone.

Comentários

O alinhamento do elemento pode ser um dos valores a seguir:

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

CMFCCaptionBar::GetBorderSize

Retorna o tamanho da borda da barra de legenda.

int GetBorderSize() const;

Valor de retorno

O tamanho, em pixels, da borda.

CMFCCaptionBar::GetButtonRect

Recupera o retângulo delimitador do botão na barra de legendas.

CRect GetButtonRect() const;

Valor de retorno

Um objeto CRect que contém as coordenadas do retângulo delimitador do botão na barra de legendas.

CMFCCaptionBar::GetMargin

Retorna a distância entre a borda dos elementos da barra de legenda e a borda do controle de barra de legenda.

int GetMargin() const;

Valor de retorno

A distância, em pixels, entre a borda dos elementos da barra de legenda e a borda do controle de barra de legenda.

CMFCCaptionBar::IsMessageBarMode

Especifica se a barra de legenda está no modo de barra de mensagens.

BOOL IsMessageBarMode() const;

Valor de retorno

TRUE se a barra de legenda estiver no modo de barra de mensagens; FALSE caso contrário.

Comentários

No modo de barra de mensagens, a barra de legenda exibe uma imagem com uma dica de ferramenta, um texto da mensagem e um botão.

CMFCCaptionBar::m_clrBarBackground

A cor da tela de fundo da barra de legenda.

COLORREF m_clrBarBackground

CMFCCaptionBar::m_clrBarBorder

A cor da borda da barra de legenda.

COLORREF m_clrBarBorder

CMFCCaptionBar::m_clrBarText

A cor do texto da barra de legendas.

COLORREF m_clrBarText

CMFCCaptionBar::OnDrawBackground

Chamado pela estrutura para preencher o plano de fundo da barra de legenda.

virtual void OnDrawBackground(
    CDC* pDC,
    CRect rect);

Parâmetros

pDC
[in] Um ponteiro para o contexto do dispositivo da barra de legenda.

rect
[in] O retângulo delimitador a ser preenchido.

Comentários

O método OnDrawBackground é chamado quando o plano de fundo da barra de legendas está prestes a ser preenchido. A implementação padrão preenche a tela de fundo usando a cor CMFCCaptionBar::m_clrBarBackground.

Substitua esse método em uma classe CMFCCaptionBar derivada para personalizar a aparência da barra de legenda.

CMFCCaptionBar::OnDrawBorder

Chamado pela estrutura para desenhar a borda da barra de legenda.

virtual void OnDrawBorder(
    CDC* pDC,
    CRect rect);

Parâmetros

pDC
[in] Um contexto de dispositivo usado para exibir as bordas.

rect
[in] O retângulo delimitador.

Comentários

Por padrão, as bordas têm o estilo plano.

Substitua esse método em uma classe CMFCCaptionBar derivada para personalizar a aparência das bordas da barra de legenda.

CMFCCaptionBar::OnDrawButton

Chamado pela estrutura para desenhar o botão da barra de legenda.

virtual void OnDrawButton(
    CDC* pDC,
    CRect rect,
    const CString& strButton,
    BOOL bEnabled);

Parâmetros

pDC
[in] Um ponteiro para um contexto de dispositivo usado para exibir o botão.

rect
[in] O retângulo delimitador do botão.

strButton
[in] O rótulo de texto do botão.

bEnabled
[in] TRUE se o botão estiver habilitado; FALSE caso contrário.

Comentários

Substitua esse método em uma classe CMFCCaptionBar derivada para personalizar a aparência do botão da barra de legenda.

CMFCCaptionBar::OnDrawImage

Chamado pela estrutura para desenhar a imagem da barra de legenda.

virtual void OnDrawImage(
    CDC* pDC,
    CRect rect);

Parâmetros

pDC
[in] Um ponteiro para um contexto de dispositivo usado para exibir a imagem.

rect
[in] Especifica o retângulo delimitador da imagem.

Comentários

Substitua esse método em uma classe CMFCCaptionBar derivada para personalizar a aparência da imagem.

CMFCCaptionBar::OnDrawText

Chamado pela estrutura para desenhar o texto da barra de legenda.

virtual void OnDrawText(
    CDC* pDC,
    CRect rect,
    const CString& strText);

Parâmetros

pDC
[in] Um ponteiro para um contexto de dispositivo usado para exibir o botão.

rect
[in] O retângulo delimitador do texto.

strText
[in] A cadeia de caracteres de texto a ser exibida.

Comentários

A implementação padrão exibe o texto usando CDC::DrawText e a cor CMFCCaptionBar::m_clrBarText.

Substitua esse método em uma classe CMFCCaptionBar derivada para personalizar a aparência do texto da barra de legenda.

CMFCCaptionBar::RemoveBitmap

Remove a imagem bitmap da barra de legenda.

void RemoveBitmap();

CMFCCaptionBar::RemoveButton

Remove o botão da barra de legenda.

void RemoveButton();

Comentários

O layout dos elementos da barra de legendas é ajustado automaticamente.

CMFCCaptionBar::RemoveIcon

Remove o ícone da barra de legenda.

void RemoveIcon();

CMFCCaptionBar::RemoveText

Remove o rótulo de texto da barra de legenda.

void RemoveText();

CMFCCaptionBar::SetBitmap

Define a imagem de bitmap para a barra de legenda.

void SetBitmap(
    HBITMAP hBitmap,
    COLORREF clrTransparent,
    BOOL bStretch=FALSE,
    BarElementAlignment bmpAlignment=ALIGN_RIGHT);

void SetBitmap(
    UINT uiBmpResID,
    COLORREF clrTransparent,
    BOOL bStretch=FALSE,
    BarElementAlignment bmpAlignment=ALIGN_RIGHT);

Parâmetros

hBitmap
[in] O identificador para o bitmap a ser definido.

clrTransparent
[in] Um valor RGB que especifica a cor transparente do bitmap.

bStretch
[in] Se TRUE, o bitmap será alongado caso não se ajuste ao retângulo delimitador de imagem. Caso contrário, o bitmap não será alongado.

bmpAlignment
[in] O alinhamento do bitmap.

Comentários

Use esse método para definir um bitmap em uma barra de legenda.

O bitmap anterior é destruído automaticamente. Se a barra de legenda exibir um ícone porque você chamou o método CMFCCaptionBar::SetIcon, o bitmap não será exibido, a menos que você remova o ícone chamando CMFCCaptionBar::RemoveIcon.

O bitmap é alinhado conforme especificado pelo parâmetro bmpAlignment. Esse parâmetro pode usar um dos valores de BarElementAlignment a seguir:

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

CMFCCaptionBar::SetBorderSize

Define o tamanho da borda da barra de legenda.

void SetBorderSize(int nSize);

Parâmetros

nSize
[in] O novo tamanho, em pixels, da borda da barra de legenda.

CMFCCaptionBar::SetButton

Define o botão para a barra de legenda.

void SetButton(
    LPCTSTR lpszLabel,
    UINT uiCmdUI,
    BarElementAlignment btnAlignmnet=ALIGN_LEFT,
    BOOL bHasDropDownArrow=TRUE);

Parâmetros

lpszLabel
O rótulo de comando do botão.

uiCmdUI
A ID de comando do botão.

btnAlignmnet
O alinhamento do botão.

bHasDropDownArrow
TRUE se o botão exibir uma seta suspensa, FALSE caso contrário.

CMFCCaptionBar::SetButtonPressed

Especifica se o botão permanece ou não pressionado.

void SetButtonPressed(BOOL bPresed=TRUE);

Parâmetros

bPresed
TRUE se o botão mantiver seu estado pressionado, caso contrário, FALSE.

CMFCCaptionBar::SetButtonToolTip

Define a dica de ferramenta para o botão.

void SetButtonToolTip(
    LPCTSTR lpszToolTip,
    LPCTSTR lpszDescription=NULL);

Parâmetros

lpszToolTip
[in] A legenda da dica de ferramenta.

lpszDescription
[in] A descrição da dica de ferramenta.

CMFCCaptionBar::SetFlatBorder

Define o estilo da borda da barra de legenda.

void SetFlatBorder(BOOL bFlat=TRUE);

Parâmetros

bFlat
[in] TRUE se a borda de uma barra de legenda for plana. FALSE se a borda for em 3D.

CMFCCaptionBar::SetIcon

Define o ícone de uma barra de legenda.

void SetIcon(
    HICON hIcon,
    BarElementAlignment iconAlignment=ALIGN_RIGHT);

Parâmetros

hIcon
[in] O identificador para o ícone a ser definido.

iconAlignment
[in] O alinhamento do ícone.

Comentários

As barras de legenda podem exibir ícones ou bitmaps. Consulte CMFCCaptionBar::SetBitmap para descobrir como exibir um bitmap. Se você definir um ícone e um bitmap, o ícone sempre será exibido. Chame CMFCCaptionBar::RemoveIcon para remover um ícone da barra de legenda.

O ícone é alinhado de acordo com o parâmetro iconAlignment. Pode ter um dos valores de BarElementAlignment a seguir:

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

CMFCCaptionBar::SetImageToolTip

Define a dica de ferramenta para a imagem na barra de legenda.

void SetImageToolTip(
    LPCTSTR lpszToolTip,
    LPCTSTR lpszDescription=NULL);

Parâmetros

lpszToolTip
[in] O texto da dica de ferramenta.

lpszDescription
[in] A descrição da dica de ferramenta.

CMFCCaptionBar::SetMargin

Define a distância entre a borda do elemento de barra de legenda e a borda do controle de barra de legenda.

void SetMargin(int nMargin);

Parâmetros

nMargin
[in] A distância, em pixels, entre a borda dos elementos da barra de legenda e a borda do controle de barra de legenda.

CMFCCaptionBar::SetText

Define o rótulo de texto para a barra de legenda.

void SetText(
    const CString& strText,
    BarElementAlignment textAlignment=ALIGN_RIGHT);

Parâmetros

strText
[in] A cadeia de caracteres de texto a ser definida.

textAlignment
[in] O alinhamento de texto.

Comentários

O rótulo de texto é alinhado conforme especificado pelo parâmetro textAlignment. Pode ter um dos valores de BarElementAlignment a seguir:

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

Confira também

Gráfico da hierarquia
Classes