This topic has not yet been rated - Rate this topic

# CMFCCaptionBar Class

Visual Studio 2008

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

Name

Description

CMFCCaptionBar::Create

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

CMFCCaptionBar::DoesAllowDynInsertBefore

Determines whether another pane can be dynamically inserted between this pane and the 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.

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 MSOffice2007Demo Sample: MFC Office Application.

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