CMFCCaptionBar Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CMFCCaptionBar Class on docs.microsoft.com. A CMFCCaptionBar object is a control bar that can display three elements: a button, a text label, and a bitmap. It can only display one element of each type at a time. You can align each element to the left or right edges of the control or to the center. You can also apply a flat or 3D style to the top and bottom borders of the caption bar.

class CMFCCaptionBar : public CPane  

Public Methods

NameDescription
CMFCCaptionBar::CreateCreates the caption bar control and attaches it to the CMFCCaptionBar object.
CMFCCaptionBar::DoesAllowDynInsertBeforeIndicates whether another pane can be dynamically inserted between the caption bar and its parent frame. (Overrides CBasePane::DoesAllowDynInsertBefore.)
CMFCCaptionBar::EnableButtonEnables or disables the button on the caption bar.
CMFCCaptionBar::GetAlignmentReturns the alignment of the specified element.
CMFCCaptionBar::GetBorderSizeReturns the border size of the caption bar.
CMFCCaptionBar::GetButtonRectRetrieves the bounding rectangle of the button on the caption bar.
CMFCCaptionBar::GetMarginReturns the distance between the edge of the caption bar elements and the edge of the caption bar control.
CMFCCaptionBar::IsMessageBarModeSpecifies whether the caption bar is in the message bar mode.
CMFCCaptionBar::RemoveBitmapRemoves the bitmap image from the caption bar.
CMFCCaptionBar::RemoveButtonRemoves the button from the caption bar.
CMFCCaptionBar::RemoveIconRemoves the icon from the caption bar.
CMFCCaptionBar::RemoveTextRemoves the text label from the caption bar.
CMFCCaptionBar::SetBitmapSets the bitmap image for the caption bar.
CMFCCaptionBar::SetBorderSizeSets the border size of the caption bar.
CMFCCaptionBar::SetButtonSets the button for the caption bar.
CMFCCaptionBar::SetButtonPressedSpecifies whether the button stays pressed.
CMFCCaptionBar::SetButtonToolTipSets the tooltip for the button.
CMFCCaptionBar::SetFlatBorderSets the border style of the caption bar.
CMFCCaptionBar::SetIconSets the icon for a caption bar.
CMFCCaptionBar::SetImageToolTipSets the tooltip for the image for the caption bar.
CMFCCaptionBar::SetMarginSets the distance between the edge of the caption bar element and the edge of the caption bar control.
CMFCCaptionBar::SetTextSets the text label for the caption bar.

Protected Methods

NameDescription
CMFCCaptionBar::OnDrawBackgroundCalled by the framework to fill the background of the caption bar.
CMFCCaptionBar::OnDrawBorderCalled by the framework to draw the border of the caption bar.
CMFCCaptionBar::OnDrawButtonCalled by the framework to draw the caption bar button.
CMFCCaptionBar::OnDrawImageCalled by the framework to draw the caption bar image.
CMFCCaptionBar::OnDrawTextCalled by the framework to draw the caption bar text.

Data Members

NameDescription
CMFCCaptionBar::m_clrBarBackgroundThe background color of the caption bar.
CMFCCaptionBar::m_clrBarBorderThe color of the border of the caption bar.
CMFCCaptionBar::m_clrBarTextThe color of the caption bar text.

To create a caption bar, follow these steps:

  1. Construct the CMFCCaptionBar object. Typically, you would add the caption bar to a frame window class.

  2. Call the CMFCCaptionBar::Create method to create the caption bar control and attach it to the CMFCCaptionBar object.

  3. Call CMFCCaptionBar::SetButton, CMFCCaptionBar::SetText, CMFCCaptionBar::SetIcon, and CMFCCaptionBar::SetBitmap to set the caption bar elements.

When you set the button element, you must assign a command ID to the button. When the user clicks the button, the caption bar routes the WM_COMMAND messages that have this ID to the parent frame window.

The caption bar can also work in message bar mode, which emulates the message bar that appears in Microsoft Office 2007 applications. In message bar mode, the caption bar displays a bitmap, a message, and a button (which typically opens a dialog box.) You can assign a tooltip to the bitmap.

To enable message bar mode, call CMFCCaptionBar::Create and set the fourth parameter (bIsMessageBarMode) to TRUE.

The following example demonstrates how to use various methods in the CMFCCaptionBar class. The example shows how to create the caption bar control, set a 3D border of the caption bar, set the distance, in pixels, between the edge of the caption bar elements and the edge of the caption bar control, set the button for the caption bar, set the tooltip for the button, set the text label for the caption bar, set the bitmap image for the caption bar, and set the tooltip for the image in the caption bar. This code snippet is part of the MS Office 2007 Demo sample.

	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;
}

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCCaptionBar

Header: afxcaptionbar.h

Creates the caption bar control and attaches it to the CMFCCaptionBar object.

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

Parameters

dwStyle
The logical OR combination of the caption bar styles.

pParentWnd
The parent window of the caption bar control.

uID
The ID of caption bar control.

nHeight
The height, in pixels, of the caption bar control. If it is -1, the height is calculated according to the height of the icon, the text and the button that the caption bar control displays.

bIsMessageBarMode
TRUE if the caption bar is in the message bar mode; FALSE otherwise.

Return Value

TRUE if the caption bar control is created successfully; FALSE otherwise.

Remarks

You construct a CMFCCaptionBar object in two steps. First you call the constructor, and then you call the Create method, which creates the Windows control and attaches it to the CMFCCaptionBar object.

Indicates whether another pane can be dynamically inserted between the caption bar and its parent frame.

virtual BOOL DoesAllowDynInsertBefore() const;  

Return Value

Returns FALSE unless overridden.

Remarks

Enables or disables the button on the caption bar.

void EnableButton(BOOL bEnable=TRUE);

Parameters

[in] bEnable
TRUE to enable the button, FALSE to disable the button.

Returns the alignment of the specified element.

BarElementAlignment GetAlignment(BarElement elem);

Parameters

[in] elem
A caption bar element for which to retrieve alignment.

Return Value

The alignment of an element, such as a button, a bitmap, text, or an icon.

Remarks

The alignment of the element can be one of the following values:

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

Returns the border size of the caption bar.

int GetBorderSize() const;  

Return Value

The size, in pixels, of the border.

Retrieves the bounding rectangle of the button on the caption bar.

CRect GetButtonRect() const;  

Return Value

A CRect object that contains the coordinates of the bounding rectangle of the button on the caption bar.

Returns the distance between the edge of the caption bar elements and the edge of the caption bar control.

int GetMargin() const;  

Return Value

The distance, in pixels, between the edge of the caption bar elements and the edge of the caption bar control.

Specifies whether the caption bar is in the message bar mode.

BOOL IsMessageBarMode() const;  

Return Value

TRUE if the caption bar is in the message bar mode; FALSE otherwise.

Remarks

In the message bar mode, the caption bar displays an image with a tooltip, a message text, and a button.

The background color of the caption bar.

COLORREF m_clrBarBackground  

The color of the border of the caption bar.

COLORREF m_clrBarBorder  

The color of the caption bar text.

COLORREF m_clrBarText  

Called by the framework to fill the background of the caption bar.

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

Parameters

[in] pDC
A pointer to the device context of the caption bar.

[in] rect
The bounding rectangle to fill.

Remarks

The OnDrawBackground method is called when the background of the caption bar is about to be filled. The default implementation fills the background by using the CMFCCaptionBar::m_clrBarBackground color.

Override this method in a CMFCCaptionBar derived class to customize the appearance of the caption bar.

Called by the framework to draw the border of the caption bar.

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

Parameters

[in] pDC
A device context that is used to display the borders.

[in] rect
The bounding rectangle.

Remarks

By default, the borders have the flat style.

Override this method in a CMFCCaptionBar derived class to customize the appearance of the caption bar's borders.

Called by the framework to draw the caption bar button.

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

Parameters

[in] pDC
A pointer to a device context that is used to display the button.

[in] rect
The bounding rectangle of the button.

[in] strButton
The button's text label.

[in] bEnabled
TRUE if the button is enabled; FALSE otherwise.

Remarks

Override this method in a CMFCCaptionBar derived class to customize the appearance of the caption bar's button.

Called by the framework to draw the caption bar image.

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

Parameters

[in] pDC
A pointer to a device context that is used to display the image.

[in] rect
Specifies the bounding rectangle of the image.

Remarks

Override this method in a CMFCCaptionBar derived class to customize the image appearance.

Called by the framework to draw the caption bar text.

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

Parameters

[in] pDC
A pointer to a device context that is used to display the button.

[in] rect
The bounding rectangle of the text.

[in] strText
The text string to display.

Remarks

The default implementation displays the text by using CDC::DrawText and CMFCCaptionBar::m_clrBarText color.

Override this method in a CMFCCaptionBar derived class to customize the appearance of the caption bar's text.

Removes the bitmap image from the caption bar.

void RemoveBitmap();

Removes the button from the caption bar.

void RemoveButton();

Remarks

The layout of caption bar elements are adjusted automatically.

Removes the icon from the caption bar.

void RemoveIcon();

Removes the text label from the caption bar.

void RemoveText();

Sets the bitmap image for the caption bar.

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

Parameters

[in] hBitmap
The handle to the bitmap to set.

[in] clrTransparent
An RGB value that specifies the transparent color of the bitmap.

[in] bStretch
If TRUE, the bitmap is stretched if it does not fit to the image bounding rectangle. Otherwise the bitmap is not stretched.

[in] bmpAlignment
The alignment of the bitmap.

Remarks

Use this method to set a bitmap on a caption bar.

The previous bitmap is destroyed automatically. If the caption bar displays an icon because you called the CMFCCaptionBar::SetIcon method, the bitmap will not be displayed unless you remove the icon by calling CMFCCaptionBar::RemoveIcon.

The bitmap is aligned as specified by the bmpAlignment parameter. This parameter can be one of the following BarElementAlignment values:

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

Sets the border size of the caption bar.

void SetBorderSize(int nSize);

Parameters

[in] nSize
The new size, in pixels, of the caption bar border.

Sets the button for the caption bar.

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

Parameters

lpszLabel
The button's command label.

uiCmdUI
The button's command ID.

btnAlignmnet
The button's alignment.

bHasDropDownArrow
TRUE if the button displays a drop down arrow, FALSE otherwise.

Specifies whether the button stays pressed.

void SetButtonPressed(BOOL bPresed=TRUE);

Parameters

bPresed
TRUE if the button keeps its pressed state, FALSE otherwise.

Sets the tooltip for the button.

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

Parameters

[in] lpszToolTip
The tooltip caption.

[in] lpszDescription
The tooltip description.

Sets the border style of the caption bar.

void SetFlatBorder(BOOL bFlat=TRUE);

Parameters

[in] bFlat
TRUE if the border of a caption bar is flat. FALSE if the border is 3D.

Sets the icon for a caption bar.

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

Parameters

[in] hIcon
The handle to the icon to set.

[in] iconAlignment
The alignment of the icon.

Remarks

Caption bars can display either icons or bitmaps. See CMFCCaptionBar::SetBitmap to find out how to display a bitmap. If you set both an icon and a bitmap, the icon is always displayed. Call CMFCCaptionBar::RemoveIcon to remove an icon from the caption bar.

The icon is aligned according to the iconAlignment parameter. It can be one of the following BarElementAlignment values:

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

Sets the tooltip for the image in the caption bar.

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

Parameters

[in] lpszToolTip
The text of the tooltip.

[in] lpszDescription
The tooltip description.

Sets the distance between the edge of the caption bar element and the edge of the caption bar control.

void SetMargin(int nMargin);

Parameters

[in] nMargin
The distance, in pixels, between the edge of the caption bar elements and the edge of the caption bar control.

Sets the text label for the caption bar.

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

Parameters

[in] strText
The text string to set.

[in] textAlignment
The text alignment.

Remarks

The text label is aligned as specified by the textAlignment parameter. It can be one of the following BarElementAlignment values:

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

Hierarchy Chart
Classes

Show: