CMFCCaptionBar Class

Article
01/08/2013

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

Members

Public Methods

Name	Description
CMFCCaptionBar::Create	Creates the caption bar control and attaches it to the CMFCCaptionBar object.
CMFCCaptionBar::DoesAllowDynInsertBefore	Indicates whether another pane can be dynamically inserted between the caption bar and its parent frame. (Overrides CBasePane::DoesAllowDynInsertBefore.)
CMFCCaptionBar::EnableButton	Enables or disables the button on the caption bar.
CMFCCaptionBar::GetAlignment	Returns the alignment of the specified element.
CMFCCaptionBar::GetBorderSize	Returns the border size of the caption bar.
CMFCCaptionBar::GetButtonRect	Retrieves the bounding rectangle of the button on the caption bar.
CMFCCaptionBar::GetMargin	Returns the distance between the edge of the caption bar elements and the edge of the caption bar control.
CMFCCaptionBar::IsMessageBarMode	Specifies whether the caption bar is in the message bar mode.
CMFCCaptionBar::RemoveBitmap	Removes the bitmap image from the caption bar.
CMFCCaptionBar::RemoveButton	Removes the button from the caption bar.
CMFCCaptionBar::RemoveIcon	Removes the icon from the caption bar.
CMFCCaptionBar::RemoveText	Removes the text label from the caption bar.
CMFCCaptionBar::SetBitmap	Sets the bitmap image for the caption bar.
CMFCCaptionBar::SetBorderSize	Sets the border size of the caption bar.
CMFCCaptionBar::SetButton	Sets the button for the caption bar.
CMFCCaptionBar::SetButtonPressed	Specifies whether the button stays pressed.
CMFCCaptionBar::SetButtonToolTip	Sets the tooltip for the button.
CMFCCaptionBar::SetFlatBorder	Sets the border style of the caption bar.
CMFCCaptionBar::SetIcon	Sets the icon for a caption bar.
CMFCCaptionBar::SetImageToolTip	Sets the tooltip for the image for the caption bar.
CMFCCaptionBar::SetMargin	Sets the distance between the edge of the caption bar element and the edge of the caption bar control.
CMFCCaptionBar::SetText	Sets the text label for the caption bar.

Protected Methods

Name	Description
CMFCCaptionBar::OnDrawBackground	Called by the framework to fill the background of the caption bar.
CMFCCaptionBar::OnDrawBorder	Called by the framework to draw the border of the caption bar.
CMFCCaptionBar::OnDrawButton	Called by the framework to draw the caption bar button.
CMFCCaptionBar::OnDrawImage	Called by the framework to draw the caption bar image.
CMFCCaptionBar::OnDrawText	Called by the framework to draw the caption bar text.

Data Members

Name	Description
CMFCCaptionBar::m_clrBarBackground	The background color of the caption bar.
CMFCCaptionBar::m_clrBarBorder	The color of the border of the caption bar.
CMFCCaptionBar::m_clrBarText	The color of the caption bar text.

Remarks

To create a caption bar, follow these steps:

Construct the CMFCCaptionBar object. Typically, you would add the caption bar to a frame window class.
Call the CMFCCaptionBar::Create method to create the caption bar control and attach it to the CMFCCaptionBar object.
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.

Example

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