通过

CMFCCaptionBar 类

  • 项目

CMFCCaptionBar 对象是一个可显示三个元素（按钮、文本标签和位图）的控制条。 它一次只能显示一种类型的一个元素。 你可以将每个元素与控件进行左对齐、右对齐或居中对齐。 你还可将平面或 3D 样式应用于标题栏的顶部和底部边界。

语法

class CMFCCaptionBar : public CPane

成员

公共方法

名称 描述
CMFCCaptionBar::Create 创建标题栏控件并将其附加到 CMFCCaptionBar 对象。
CMFCCaptionBar::DoesAllowDynInsertBefore 指示是否可在标题栏与其父框架之间动态插入另一个窗格。 （替代 CBasePane::DoesAllowDynInsertBefore。）
CMFCCaptionBar::EnableButton 启用或禁用标题栏上的按钮。
CMFCCaptionBar::GetAlignment 返回指定元素的对齐方式。
CMFCCaptionBar::GetBorderSize 返回标题栏的边框大小。
CMFCCaptionBar::GetButtonRect 检索标题栏上按钮的边框。
CMFCCaptionBar::GetMargin 返回标题栏元素边缘与标题栏控件边缘之间的距离。
CMFCCaptionBar::IsMessageBarMode 指定标题栏是否处于消息栏模式。
CMFCCaptionBar::RemoveBitmap 从标题栏中移除位图图像。
CMFCCaptionBar::RemoveButton 从标题栏中移除按钮。
CMFCCaptionBar::RemoveIcon 从标题栏中移除图标。
CMFCCaptionBar::RemoveText 从标题栏中移除文本标签。
CMFCCaptionBar::SetBitmap 设置标题栏的位图图像。
CMFCCaptionBar::SetBorderSize 设置标题栏的边框大小。
CMFCCaptionBar::SetButton 设置标题栏的按钮。
CMFCCaptionBar::SetButtonPressed 指定按钮是否保持在按下状态。
CMFCCaptionBar::SetButtonToolTip 设置按钮的工具提示。
CMFCCaptionBar::SetFlatBorder 设置标题栏的边框样式。
CMFCCaptionBar::SetIcon 设置标题栏的图标。
CMFCCaptionBar::SetImageToolTip 设置标题栏图像的工具提示。
CMFCCaptionBar::SetMargin 设置标题栏元素边缘与标题栏控件边缘之间的距离。
CMFCCaptionBar::SetText 设置标题栏的文本标签。

受保护方法

名称 描述
CMFCCaptionBar::OnDrawBackground 由框架调用来填充标题栏的背景。
CMFCCaptionBar::OnDrawBorder 由框架调用来绘制标题栏的边框。
CMFCCaptionBar::OnDrawButton 由框架调用来绘制标题栏按钮。
CMFCCaptionBar::OnDrawImage 由框架调用来绘制标题栏图像。
CMFCCaptionBar::OnDrawText 由框架调用来绘制标题栏文本。

数据成员

名称 描述
CMFCCaptionBar::m_clrBarBackground 标题栏的背景色。
CMFCCaptionBar::m_clrBarBorder 标题栏边框的颜色。
CMFCCaptionBar::m_clrBarText 标题栏文本的颜色。

注解

若要创建标题栏，请执行以下步骤：

  1. 构造 CMFCCaptionBar 对象。 通常，将标题栏添加到框架窗口类。

  2. 调用 CMFCCaptionBar::Create方法可创建标题栏控件并将其附加到 CMFCCaptionBar 对象。

  3. 调用 CMFCCaptionBar::SetButton、CMFCCaptionBar::SetText、CMFCCaptionBar::SetIcon 和 CMFCCaptionBar::SetBitmap 来设置标题栏元素。

设置按钮元素时，必须将命令 ID 分配给该按钮。 当用户单击该按钮时，标题栏会将具有此 ID 的 WM_COMMAND 消息路由到父框架窗口。

标题栏还可在消息栏模式下工作，该模式模拟 Microsoft Office 2007 应用程序中显示的消息栏。 在消息栏模式下，标题栏会显示位图、消息和按钮（该按钮通常会打开对话框）。你可以向位图分配工具提示。

若要启用消息栏模式，请调用 CMFCCaptionBar::Create 并将第 4 个参数 (bIsMessageBarMode) 设置为 TRUE。

示例

下面的示例演示了如何使用 CMFCCaptionBar 类中的各种方法。 该示例演示如何创建标题栏控件，设置标题栏的三维边框，设置标题栏元素边缘与标题栏控件边缘之间的距离（以像素为单位），设置标题栏的按钮，设置按钮的工具提示，设置标题栏的文本标签，设置标题栏的位图图像，以及为标题栏中的图像设置工具提示。 此代码片段是 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;
}

继承层次结构

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCCaptionBar

要求

标题：afxcaptionbar.h

CMFCCaptionBar::Create

创建标题栏控件并将其附加到 CMFCCaptionBar 对象。

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

参数

dwStyle
标题栏样式的逻辑 OR 组合。

pParentWnd
标题栏控件的父窗口。

uID
标题栏控件的 ID。

nHeight
标题栏控件的高度（以像素为单位）。 如果为 -1，则根据图标的高度、文本和标题栏控件显示的按钮计算高度。

bIsMessageBarMode
如果标题栏处于消息栏模式，则为 TRUE；否则为 FALSE。

返回值

如果已成功创建标题栏控件，则为 TRUE；否则为 FALSE。

备注

请分两步构造 CMFCCaptionBar 对象。 首先调用构造函数，然后调用 Create 方法，这会创建 Windows 控件并将其附加到 CMFCCaptionBar 对象。

CMFCCaptionBar::DoesAllowDynInsertBefore

指示是否可在标题栏与其父框架之间动态插入另一个窗格。

virtual BOOL DoesAllowDynInsertBefore() const;

返回值

除非替代，否则返回 FALSE。

注解

CMFCCaptionBar::EnableButton

启用或禁用标题栏上的按钮。

void EnableButton(BOOL bEnable=TRUE);

参数

bEnable
[in] 设置为 TRUE 可启用按钮；设置为 FALSE 可禁用按钮。

CMFCCaptionBar::GetAlignment

返回指定元素的对齐方式。

BarElementAlignment GetAlignment(BarElement elem);

参数

elem
[in] 要检索其对齐方式的标题栏元素。

返回值

元素的对齐方式，例如按钮、位图、文本或图标。

备注

元素的对齐方式可以为以下值之一：

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

CMFCCaptionBar::GetBorderSize

返回标题栏的边框大小。

int GetBorderSize() const;

返回值

边框的大小（以像素为单位）。

CMFCCaptionBar::GetButtonRect

检索标题栏上按钮的边框。

CRect GetButtonRect() const;

返回值

一个 CRect 对象，它包含标题栏上按钮边框的坐标。

CMFCCaptionBar::GetMargin

返回标题栏元素边缘与标题栏控件边缘之间的距离。

int GetMargin() const;

返回值

标题栏元素边缘与标题栏控件边缘之间的距离（以像素为单位）。

CMFCCaptionBar::IsMessageBarMode

指定标题栏是否处于消息栏模式。

BOOL IsMessageBarMode() const;

返回值

如果标题栏处于消息栏模式，则为 TRUE；否则为 FALSE。

注解

在消息栏模式下，标题栏显示带有工具提示、消息文本和按钮的图像。

CMFCCaptionBar::m_clrBarBackground

标题栏的背景色。

COLORREF m_clrBarBackground

CMFCCaptionBar::m_clrBarBorder

标题栏边框的颜色。

COLORREF m_clrBarBorder

CMFCCaptionBar::m_clrBarText

标题栏文本的颜色。

COLORREF m_clrBarText

CMFCCaptionBar::OnDrawBackground

由框架调用来填充标题栏的背景。

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

参数

pDC
[in] 指向标题栏的设备上下文的指针。

rect
[in] 要填充的边框。

备注

即将填充标题栏的背景时，将调用 OnDrawBackground 方法。 默认实现使用 CMFCCaptionBar::m_clrBarBackground 颜色填充背景。

若要自定义标题栏的外观，请在 CMFCCaptionBar 派生类中替代此方法。

CMFCCaptionBar::OnDrawBorder

由框架调用来绘制标题栏的边框。

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

参数

pDC
[in] 用于显示边框的设备上下文。

rect
[in] 边框。

备注

默认情况下，边框具有平面样式。

若要自定义标题栏边框的外观，请在 CMFCCaptionBar 派生类中替代此方法。

CMFCCaptionBar::OnDrawButton

由框架调用来绘制标题栏按钮。

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

参数

pDC
[in] 指向用于显示按钮的设备上下文的指针。

rect
[in] 按钮的范围框。

strButton
[in] 按钮的文本标签。

bEnabled
[in] 如果启用按钮，则为 TRUE；否则为 FALSE。

备注

若要自定义标题栏按钮的外观，请在 CMFCCaptionBar 派生类中替代此方法。

CMFCCaptionBar::OnDrawImage

由框架调用来绘制标题栏图像。

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

参数

pDC
[in] 指向用于显示图像的设备上下文的指针。

rect
[in] 指定图像的边框。

备注

若要自定义图像外观，请在 CMFCCaptionBar 派生类中替代此方法。

CMFCCaptionBar::OnDrawText

由框架调用来绘制标题栏文本。

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

参数

pDC
[in] 指向用于显示按钮的设备上下文的指针。

rect
[in] 文本的边框。

strText
[in] 要显示的文本字符串。

备注

默认实现使用CDC::DrawText 和 CMFCCaptionBar::m_clrBarText 颜色显示文本。

若要自定义标题栏文本的外观，请在 CMFCCaptionBar 派生类中替代此方法。

CMFCCaptionBar::RemoveBitmap

从标题栏中移除位图图像。

void RemoveBitmap();

CMFCCaptionBar::RemoveButton

从标题栏中移除按钮。

void RemoveButton();

备注

标题栏元素的布局会自动调整。

CMFCCaptionBar::RemoveIcon

从标题栏中移除图标。

void RemoveIcon();

CMFCCaptionBar::RemoveText

从标题栏中移除文本标签。

void RemoveText();

CMFCCaptionBar::SetBitmap

设置标题栏的位图图像。

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

参数

hBitmap
[in] 要设置的位图的句柄。

clrTransparent
[in] 指定位图透明色的 RGB 值。

bStretch
[in] 如果为 TRUE，则当位图不适应图像边框时，会拉伸位图。 否则，不会拉伸位图。

bmpAlignment
[in] 位图的对齐方式。

备注

使用此方法可在标题栏上设置位图。

上一位图会自动销毁。 如果由于调用了 CMFCCaptionBar::SetIcon 方法而使标题栏显示一个图标，则除非调用 CMFCCaptionBar::RemoveIcon 来移除该图标，否则不会显示位图。

位图按 bmpAlignment 参数指定的方式对齐。 此参数可能是以下 BarElementAlignment 值之一：

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

CMFCCaptionBar::SetBorderSize

设置标题栏的边框大小。

void SetBorderSize(int nSize);

参数

nSize
[in] 标题栏边框的新大小（以像素为单位）。

CMFCCaptionBar::SetButton

设置标题栏的按钮。

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

参数

lpszLabel
按钮的命令标签。

uiCmdUI
按钮的命令 ID。

btnAlignmnet
按钮的对齐方式。

bHasDropDownArrow
如果按钮显示下拉箭头，则为 TRUE；否则为 FALSE。

CMFCCaptionBar::SetButtonPressed

指定按钮是否保持在按下状态。

void SetButtonPressed(BOOL bPresed=TRUE);

参数

bPresed
如果按钮保持在按下状态，则为 TRUE；否则为 FALSE。

CMFCCaptionBar::SetButtonToolTip

设置按钮的工具提示。

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

参数

lpszToolTip
[in] 工具提示标题。

lpszDescription
[in] 工具提示说明。

CMFCCaptionBar::SetFlatBorder

设置标题栏的边框样式。

void SetFlatBorder(BOOL bFlat=TRUE);

参数

bFlat
[in] 如果标题栏的边框是平面的，则为 TRUE。 如果边框是三维的，则为 FALSE。

CMFCCaptionBar::SetIcon

设置标题栏的图标。

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

参数

hIcon
[in] 要设置的图标的句柄。

iconAlignment
[in] 图标的对齐方式。

备注

标题栏可以显示图标或位图。 请参阅 CMFCCaptionBar::SetBitmap，了解如何显示位图。 如果同时设置图标和位图，则始终显示该图标。 调用 CMFCCaptionBar::RemoveIcon 可从标题栏中移除图标。

图标根据 iconAlignment 参数进行对齐。 它可以为下列 BarElementAlignment 值之一：

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

CMFCCaptionBar::SetImageToolTip

设置标题栏中图像的工具提示。

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

参数

lpszToolTip
[in] 工具提示的文本。

lpszDescription
[in] 工具提示说明。

CMFCCaptionBar::SetMargin

设置标题栏元素边缘与标题栏控件边缘之间的距离。

void SetMargin(int nMargin);

参数

nMargin
[in] 标题栏元素边缘与标题栏控件边缘之间的距离（以像素为单位）。

CMFCCaptionBar::SetText

设置标题栏的文本标签。

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

参数

strText
[in] 要设置的文本字符串。

textAlignment
[in] 文本对齐方式。

注解

文本标签按 textAlignment 参数指定的方式对齐。 它可以为下列 BarElementAlignment 值之一：

  • ALIGN_INVALID

  • ALIGN_LEFT

  • ALIGN_RIGHT

  • ALIGN_CENTER

另请参阅

层次结构图
类