CToolBar

具有一行位图化按钮和可选分隔符的控件条。

语法

class CToolBar : public CControlBar

成员

公共构造函数

名称 描述
CToolBar::CToolBar 构造 CToolBar 对象。

公共方法

名称 描述
CToolBar::CommandToIndex 返回具有给定命令 ID 的按钮的索引。
CToolBar::Create 创建 Windows 工具栏并将其附加到 CToolBar 对象。
CToolBar::CreateEx 为嵌入式 CToolBarCtrl 对象创建具有其他样式的 CToolBar 对象。
CToolBar::GetButtonInfo 检索按钮的 ID、样式和图像编号。
CToolBar::GetButtonStyle 检索按钮的样式。
CToolBar::GetButtonText 检索将在按钮上显示的文本。
CToolBar::GetItemID 返回给定索引处的按钮或分隔符的命令 ID。
CToolBar::GetItemRect 检索给定索引处的项的显示矩形。
CToolBar::GetToolBarCtrl 允许直接访问基础公共控件。
CToolBar::LoadBitmap 加载包含位图按钮图像的位图。
CToolBar::LoadToolBar 加载使用资源编辑器创建的工具栏资源。
CToolBar::SetBitmap 设置位图图像。
CToolBar::SetButtonInfo 设置按钮的 ID、样式和图像编号。
CToolBar::SetButtons 设置按钮样式和位图中按钮图像的索引。
CToolBar::SetButtonStyle 设置按钮的样式。
CToolBar::SetButtonText 设置将在按钮上显示的文本。
CToolBar::SetHeight 设置工具栏的高度。
CToolBar::SetSizes 设置按钮的大小及其位图。

备注

这些按钮可以像按钮、复选框按钮或单选按钮一样操作。 CToolBar 对象通常是从 CFrameWndCMDIFrameWnd 类派生的框架窗口对象的嵌入成员。

CToolBar::GetToolBarCtrl 是 MFC 4.0 新增的成员函数,允许利用 Windows 通用控件支持实现工具栏自定义和其他功能。 CToolBar 成员函数提供 Windows 常用控件的大部分功能;但是,当你调用 GetToolBarCtrl 时,可以为工具栏赋予更多 Windows 95/98 工具栏的特征。 调用 GetToolBarCtrl时,它将返回对 CToolBarCtrl 对象的引用。 有关使用 Windows 常用控件设计工具栏的详细信息,请参阅 CToolBarCtrl。 如需详细了解常用控件的一般信息,请参阅 Windows SDK 中的常用控件

Visual C++ 提供了两种方法来创建工具栏。 若要使用资源编辑器创建工具栏资源,请执行以下步骤:

  1. 创建工具栏资源。

  2. 构造 CToolBar 对象。

  3. 调用 Create(或 CreateEx)函数来创建 Windows 工具栏并将其附加到 CToolBar 对象。

  4. 调用 LoadToolBar 以加载工具栏资源。

否则,请执行以下步骤:

  1. 构造 CToolBar 对象。

  2. 调用 Create(或 CreateEx)函数来创建 Windows 工具栏并将其附加到 CToolBar 对象。

  3. 调用 LoadBitmap 以加载包含工具栏按钮图像的位图。

  4. 调用 SetButtons 以设置按钮样式并将每个按钮与位图中的图像相关联。

工具栏中的所有按钮图像都取自一个位图,该位图必须包含每个按钮的一个图像。 所有图像的大小必须相同;默认值为 16 像素宽,15 像素高。 图像必须并排在位图中。

SetButtons 函数获取一个指向控件 ID 数组的指针和一个指定数组中的元素数量的整数。 该函数将每个按钮的 ID 设置为数组相应元素的值,并为每个按钮分配一个图像索引,以指定按钮图像在位图中的位置。 如果数组元素具有值 ID_SEPARATOR,则不分配图像索引。

图像在位图中的顺序通常是在屏幕上绘制图像的顺序,但你可以使用 SetButtonInfo 函数更改图像顺序与绘制顺序之间的关系。

工具栏中的所有按钮大小均相同。 默认值为 24 x 22 像素,符合《Windows 软件设计界面准则》。 图像和按钮尺寸之间的任何其他空间用于在图像周围形成边框。

每个按钮都有一个图像。 各种按钮状态和样式(按下、向下、向上、禁用、向下禁用和不确定)都是从该图形生成的。 尽管位图可以是任何颜色,但可以使用黑色和各种灰度的图像获得最佳结果。

警告

CToolBar 最多支持 16 色位图。 将图像加载到工具栏编辑器中时,Visual Studio 会根据需要自动将图像转换为 16 色位图,并在图像转换时显示警告消息。 如果使用的图像超过 16 色(使用外部编辑器来编辑图像),则应用程序可能会出现意外行为。

默认情况下,工具栏按钮会模仿推送按钮。 但是,工具栏按钮还可以模仿复选框按钮或单选按钮。 复选框按钮有三种状态:已选中、已清除和不确定。 单选按钮只有两种状态:已选中和已清除。

若要设置单个按钮或分隔符样式而不指向数组,请调用 GetButtonStyle 以检索样式,然后调用 SetButtonStyle 而不是调用 SetButtons。 如果要在运行时更改按钮的样式,则 SetButtonStyle 最有用。

若要指定按钮上显示的文本,请调用 GetButtonText 以检索要在按钮上显示的文本,然后调用 SetButtonText 以设置该文本。

若要创建复选框按钮,请为其分配 TBBS_CHECKBOX 样式或在 ON_UPDATE_COMMAND_UI 处理程序中使用 CCmdUI 对象的 SetCheck 成员函数。 调用 SetCheck 会将推送按钮转换为复选框按钮。 向 SetCheck 传递参数 0、1、2,分别表示未选中、已选中和不确定。

若要创建单选按钮,请从 ON_UPDATE_COMMAND_UI 处理程序调用 CCmdUI 对象的 SetRadio 成员函数。 向 SetRadio 传递参数 0 表示未选中,传递非零参数表示已选中。 为了提供单选组的互斥行为,必须为该组中的所有按钮提供 ON_UPDATE_COMMAND_UI 处理程序。

有关使用 CToolBar 的详细信息,请参阅文章 MFC 工具栏实现技术说明 31:控制栏

继承层次结构

CObject

CCmdTarget

CWnd

CControlBar

CToolBar

要求

标头afxext.h

CToolBar::CommandToIndex

此成员函数返回第一个工具栏按钮的索引,从位置 0 开始,其命令 ID 匹配 nIDFind

int CommandToIndex(UINT nIDFind) const;

参数

nIDFind
工具栏按钮的命令 ID。

返回值

按钮的索引;如果没有按钮具有给定命令 ID,则为 -1。

CToolBar::Create

此成员函数创建一个 Windows 工具栏(子窗口),并将其与 CToolBar 对象关联。

virtual BOOL Create(
    CWnd* pParentWnd,
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_TOP,
    UINT nID = AFX_IDW_TOOLBAR);

参数

pParentWnd
指向作为工具栏父级的窗口的指针。

dwStyle
工具栏样式。 支持的其他工具栏样式包括:

  • CBRS_TOP 控制栏位于框架窗口顶部。

  • CBRS_BOTTOM 控制栏位于框架窗口底部。

  • CBRS_NOALIGN 控件栏在调整父级大小时不会重新定位。

  • CBRS_TOOLTIPS 控件栏显示工具提示。

  • CBRS_SIZE_DYNAMIC 控件栏是动态的。

  • CBRS_SIZE_FIXED 控件栏是固定的。

  • CBRS_FLOATING 控件栏是浮动的。

  • CBRS_FLYBY 状态栏显示有关按钮的信息。

  • CBRS_HIDE_INPLACE 控件栏不向用户显示。

nID
工具栏的子窗口 ID。

返回值

如果成功,则不为 0;否则为 0。

备注

它还将工具栏高度设置为默认值。

示例

// This code fragment is taken from CMainFrame::OnCreate
// CMainFrame is derived from CMDIFrameWnd.

//This example creates a dockable toolbar.
if (!m_wndToolBar.Create(this) ||
   !m_wndToolBar.LoadToolBar(IDR_MAINFRAME))
{
   TRACE0("Failed to create toolbar\n");
   return -1;      // fail to create
}

//Make the toolbar dockable
m_wndToolBar.EnableDocking(CBRS_ALIGN_ANY);
EnableDocking(CBRS_ALIGN_ANY);
DockControlBar(&m_wndToolBar);

CToolBar::CreateEx

调用此函数可创建 Windows 工具栏(子窗口)并将其与 CToolBar 对象相关联。

virtual BOOL CreateEx(
    CWnd* pParentWnd,
    DWORD dwCtrlStyle = TBSTYLE_FLAT,
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_ALIGN_TOP,
    CRect rcBorders = CRect(
    0,
    0,
    0,
    0),
    UINT nID = AFX_IDW_TOOLBAR);

参数

pParentWnd
指向作为工具栏父级的窗口的指针。

dwCtrlStyle
用于创建嵌入 CToolBarCtrl 对象的附加样式。 默认情况下,此值设置为 TBSTYLE_FLAT。 有关工具栏样式的完整列表,请参阅 dwStyle

dwStyle
工具栏样式。 有关合适的样式列表,请参阅 Windows SDK 中的工具栏控件和按钮样式

rcBorders
定义工具栏窗口边框的宽度的 CRect 对象。 默认情况下,这些边框设置为 0,0,0,0,因此会导致工具栏窗口没有边框。

nID
工具栏的子窗口 ID。

返回值

如果成功,则不为 0;否则为 0。

备注

它还将工具栏高度设置为默认值。

在创建嵌入式工具栏控件期间需要存在某些样式时,请使用 CreateEx,而不是 Create。 例如,将 dwCtrlStyle 设置为 TBSTYLE_FLAT | TBSTYLE_TRANSPARENT 可创建类似于 Internet Explorer 4 工具栏的工具栏。

示例

// This example demonstrates CToolBar::CreateEx by creating a 
// toolbar as part of a child frame window. It also calls the 
// LoadToolbar and EnableDocking functions
int CChildFrame::OnCreate(LPCREATESTRUCT lpCreateStruct)
{
   if (CMDIChildWnd::OnCreate(lpCreateStruct) == -1)
      return -1;

   if (!m_wndMyToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE | CBRS_TOP
      | CBRS_GRIPPER | CBRS_TOOLTIPS | CBRS_FLYBY | CBRS_SIZE_DYNAMIC) ||
      !m_wndMyToolBar.LoadToolBar(IDR_MYTOOLBAR))
   {
      TRACE0("Failed to create toolbar\n");
      return -1;      // fail to create
   }

   m_wndMyToolBar.EnableDocking(CBRS_ALIGN_ANY);
   EnableDocking(CBRS_ALIGN_ANY);
   DockControlBar(&m_wndMyToolBar);

   return 0;
}

CToolBar::CToolBar

此成员函数构造 CToolBar 对象并设置默认大小。

CToolBar();

注解

调用 Create 成员函数可创建工具栏窗口。

CToolBar::GetButtonInfo

此成员函数检索在 nIndex 指定位置的工具栏按钮或分隔符的控件 ID、样式和图像索引。

void GetButtonInfo(
    int nIndex,
    UINT& nID,
    UINT& nStyle,
    int& iImage) const;

参数

nIndex
要检索其信息的工具栏按钮或分隔符的索引。

nID
对设置为按钮命令 ID 的 UINT 的引用。

nStyle
对设置为按钮样式的 UINT 的引用。

iImage
对一个整数的引用,该整数设置为位图中按钮图像的索引。

备注

这些值分配给 nIDnStyleiImage 引用的变量。 图像索引是图像在位图中的位置,该位图包含所有工具栏按钮的图像。 第一个图像位于位置 0 处。

如果 nIndex 指定分隔符,iImage 设置为分隔符宽度(以像素为单位)。

CToolBar::GetButtonStyle

调用此成员函数以检索工具栏上的按钮或分隔符的样式。

UINT GetButtonStyle(int nIndex) const;

参数

nIndex
要检索的工具栏按钮或分隔符样式的索引。

返回值

nIndex 指定的按钮或分隔符的样式。

备注

按钮的样式决定了按钮的显示方式以及按钮对用户输入的响应方式。 有关按钮样式的示例,请参阅 SetButtonStyle

CToolBar::GetButtonText

调用此成员函数以检索按钮上显示的文本。

CString GetButtonText(int nIndex) const;

void GetButtonText(
    int nIndex,
    CString& rString) const;

参数

nIndex
要检索的文本的索引。

rString
对将包含要检索的文本的 CString 对象的引用。

返回值

包含按钮文本的 CString 对象。

备注

此成员函数的第二种形式用字符串文本填充 CString 对象。

CToolBar::GetItemID

此成员函数返回由 nIndex 指定的按钮或分隔符的命令 ID。

UINT GetItemID(int nIndex) const;

参数

nIndex
将检索其 ID 的项的索引。

返回值

nIndex 指定的按钮或分隔符的命令 ID。

注解

分隔符返回 ID_SEPARATOR

CToolBar::GetItemRect

此成员函数用 nIndex 指定的按钮或分隔符的坐标填充地址包含在 lpRect 中的 RECT 结构。

virtual void GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

参数

nIndex
将检索其矩形坐标的项(按钮或分隔符)的索引。

lpRect
将包含项坐标的 RECT 结构的地址。

备注

坐标相对于工具栏的左上角(以像素为单位)。

使用 GetItemRect 可获取要替换为组合框或其他控件的分隔符的坐标。

示例

请参阅 CToolBar::SetSizes 的示例。

CToolBar::GetToolBarCtrl

此成员函数允许直接访问基础常用控件。

CToolBarCtrl& GetToolBarCtrl() const;

返回值

CToolBarCtrl 对象的引用。

备注

使用 GetToolBarCtrl 可利用 Windows 工具栏常用控件的功能和 CToolBarCtrl 提供的支持进行工具栏自定义。

有关使用常用控件的详细信息,请参阅 Windows SDK 中的文章控件常用控件

示例

// This code fragment is taken from CMainFrame::OnCreate
// CMainFrame is derived from CMDIFrameWnd.

//This example shows how to add text to toolbar buttons.
if (!m_wndToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE
   | CBRS_TOP) || !m_wndToolBar.LoadToolBar(IDR_MAINFRAME))
{
   TRACE0("Failed to create toolbar\n");
   return -1;      // fail to create
}

//Show text on toolbar buttons.
VERIFY(m_wndToolBar.SetButtonText(0, _T("New")));
VERIFY(m_wndToolBar.SetButtonText(1, _T("Open")));
VERIFY(m_wndToolBar.SetButtonText(2, _T("Save")));
VERIFY(m_wndToolBar.SetButtonText(4, _T("Cut")));
VERIFY(m_wndToolBar.SetButtonText(5, _T("Copy")));
VERIFY(m_wndToolBar.SetButtonText(6, _T("Paste")));
VERIFY(m_wndToolBar.SetButtonText(8, _T("Print")));
VERIFY(m_wndToolBar.SetButtonText(9, _T("About")));

CRect temp;
m_wndToolBar.GetItemRect(0, &temp);
m_wndToolBar.GetToolBarCtrl().SetButtonSize(CSize(temp.Width(),
   temp.Height()));

CToolBar::LoadBitmap

调用此成员函数以加载由 lpszResourceNamenIDResource 指定的位图。

BOOL LoadBitmap(LPCTSTR lpszResourceName);
BOOL LoadBitmap(UINT nIDResource);

参数

lpszResourceName
指向要加载的位图的资源名称的指针。

nIDResource
要加载的位图的资源 ID。

返回值

如果成功,则不为 0;否则为 0。

备注

位图应针对每个工具栏按钮包含一个图像。 如果图像不是标准大小(16 像素宽和 15 像素高),则调用 SetSizes 以设置按钮大小及其图像。

警告

CToolBar 最多支持 16 色位图。 将图像加载到工具栏编辑器中时,Visual Studio 会根据需要自动将图像转换为 16 色位图,并在图像转换时显示警告消息。 如果使用的图像超过 16 色(使用外部编辑器来编辑图像),则应用程序可能会出现意外行为。

CToolBar::LoadToolBar

调用此成员函数以加载由 lpszResourceNamenIDResource 指定的工具栏。

BOOL LoadToolBar(LPCTSTR lpszResourceName);
BOOL LoadToolBar(UINT nIDResource);

参数

lpszResourceName
指向要加载的工具栏的资源名称的指针。

nIDResource
要加载的工具栏的资源 ID。

返回值

如果成功,则不为 0;否则为 0。

注解

有关创建工具栏资源的详细信息,请参阅工具栏编辑器

示例

请参阅 CToolBar::CreateEx 的示例。

CToolBar::SetBitmap

调用此成员函数以设置工具栏的位图图像。

BOOL SetBitmap(HBITMAP hbmImageWell);

参数

hbmImageWell
与工具栏关联的位图图像的句柄。

返回值

如果成功,则不为 0;否则为 0。

备注

例如,当用户对文档执行操作以更改按钮操作后,调用 SetBitmap 更改位图图像。

CToolBar::SetButtonInfo

调用此成员函数以设置按钮的命令 ID、样式和图像编号。

void SetButtonInfo(
    int nIndex,
    UINT nID,
    UINT nStyle,
    int iImage);

参数

nIndex
要为其设置信息的按钮或分隔符的从零开始的索引。

nID
按钮命令 ID 设置为的值。

nStyle
新按钮样式。 支持以下按钮样式:

  • TBBS_BUTTON 标准按键(默认)

  • TBBS_SEPARATOR 分隔符

  • TBBS_CHECKBOX 自动复选框按钮

  • TBBS_GROUP 标记按钮组的开始

  • TBBS_CHECKGROUP 标记复选框按钮组的开始

  • TBBS_DROPDOWN 创建下拉列表按钮。

  • TBBS_AUTOSIZE 按钮的宽度将根据按钮的文本而不是图像的大小计算。

  • TBBS_NOPREFIX 按钮文本没有与之关联的快捷键前缀。

iImage
位图中按钮图像的新索引。

备注

对于具有样式 TBBS_SEPARATOR 的分隔符,此函数将分隔符的宽度(以像素为单位)设置为 iImage 中存储的值。

注意

还可以使用 nStyle 参数设置按钮状态;但是,由于按钮状态由 ON_UPDATE_COMMAND_UI 处理程序控制,因此在下次空闲处理期间,使用 SetButtonInfo 设置的任何状态都将丢失。 有关详细信息,请参阅如何更新用户界面对象TN031:控件栏

有关位图图像和按钮的信息,请参阅 CToolBar 概述和 CToolBar::LoadBitmap

CToolBar::SetButtons

此成员函数将每个工具栏按钮的命令 ID 设置为数组 lpIDArray 的相应元素指定的值。

BOOL SetButtons(
    const UINT* lpIDArray,
    int nIDCount);

参数

lpIDArray
指向命令 ID 数组的指针。 它可以为 NULL 以分配空按钮。

nIDCount
lpIDArray 指向的数组中的元素数目。

返回值

如果成功,则不为 0;否则为 0。

备注

如果数组的元素具有值 ID_SEPARATOR,则会在工具栏的相应位置创建分隔符。 此函数还将每个按钮的样式设置为 TBBS_BUTTON,将每个分隔符的样式设置为 TBBS_SEPARATOR,并将图像索引分配给每个按钮。 图像索引指定按钮图像在位图中的位置。

无需考虑位图中的分隔符,因为此函数不会为分隔符分配图像索引。 如果工具栏的按钮在位置 0、1 和 3,分隔符在位置 2,则位图中位于位置 0、1 和 2 处的图像分别分配给位于位置 0、1 和 3 的按钮。

如果 lpIDArray 为 NULL,此函数将为 nIDCount 指定的项数分配空间。 使用 SetButtonInfo 设置每个项的属性。

CToolBar::SetButtonStyle

调用此成员函数以设置按钮或分隔符的样式,或将按钮分组。

void SetButtonStyle(
    int nIndex,
    UINT nStyle);

参数

nIndex
要设置其信息的按钮或分隔符的索引。

nStyle
按钮样式。 支持以下按钮样式:

  • TBBS_BUTTON 标准按键(默认)

  • TBBS_SEPARATOR 分隔符

  • TBBS_CHECKBOX 自动复选框按钮

  • TBBS_GROUP 标记按钮组的开始

  • TBBS_CHECKGROUP 标记复选框按钮组的开始

  • TBBS_DROPDOWN 创建下拉列表按钮

  • TBBS_AUTOSIZE 按钮的宽度将根据按钮的文本进行计算,而不是根据图像的大小计算

  • TBBS_NOPREFIX 按钮文本没有与之关联的快捷键前缀

备注

按钮的样式决定了按钮的显示方式以及按钮对用户输入的响应方式。

在调用 SetButtonStyle 之前,调用 GetButtonStyle 成员函数以检索按钮或分隔符样式。

注意

还可以使用 nStyle 参数设置按钮状态;但是,由于按钮状态由 ON_UPDATE_COMMAND_UI 处理程序控制,因此在下次空闲处理期间,使用 SetButtonStyle 设置的任何状态都将丢失。 有关详细信息,请参阅如何更新用户界面对象TN031:控件栏

CToolBar::SetButtonText

调用此函数以设置按钮上的文本。

BOOL SetButtonText(
    int nIndex,
    LPCTSTR lpszText);

参数

nIndex
要设置其文本的按钮的索引。

lpszText
指向要在按钮上设置的文本。

返回值

如果成功,则不为 0;否则为 0。

示例

请参阅 CToolBar::GetToolBarCtrl 的示例。

CToolBar::SetHeight

此成员函数将工具栏的高度设置为 cyHeight 中指定的值(以像素为单位)。

void SetHeight(int cyHeight);

参数

cyHeight
工具栏的高度(以像素为单位)。

备注

调用 SetSizes 后,使用此成员函数替代标准工具栏高度。 如果高度太小,将在底部裁剪按钮。

如果未调用此函数,框架将使用按钮的大小来确定工具栏高度。

CToolBar::SetSizes

调用此成员函数以将工具栏的按钮设置 sizeButton 中指定的大小(以像素为单位)。

void SetSizes(
    SIZE sizeButton,
    SIZE sizeImage);

参数

sizeButton
每个按钮的大小(以像素为单位)。

sizeImage
每个图像的大小(以像素为单位)。

备注

sizeImage 参数必须包含工具栏位图中图像的大小(以像素为单位)。 sizeButton 中的尺寸必须足以容纳图像,并且宽度为 7 像素,高度为 6 像素。 此函数还设置工具栏高度以适应按钮。

仅针对不遵循《Windows 软件设计界面准则》中有关按钮和图形大小建议的工具栏调用此成员函数

示例

// This code fragment is taken from CMainFrame::OnCreate
// CMainFrame is derived from CMDIFrameWnd

// This example shows how to add text to toolbar buttons.
if (!m_wndToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE 
   | CBRS_TOP) || !m_wndToolBar.LoadToolBar(IDR_MAINFRAME))
{
   TRACE0("Failed to create toolbar\n");
   return -1;      // fail to create
}

//Show text on toolbar buttons.
VERIFY(m_wndToolBar.SetButtonText(0, _T("New")));
VERIFY(m_wndToolBar.SetButtonText(1, _T("Open")));
VERIFY(m_wndToolBar.SetButtonText(2, _T("Save")));
VERIFY(m_wndToolBar.SetButtonText(4, _T("Cut")));
VERIFY(m_wndToolBar.SetButtonText(5, _T("Copy")));
VERIFY(m_wndToolBar.SetButtonText(6, _T("Paste")));
VERIFY(m_wndToolBar.SetButtonText(8, _T("Print")));
VERIFY(m_wndToolBar.SetButtonText(9, _T("About")));

CRect temp;
m_wndToolBar.GetItemRect(0,&temp);
m_wndToolBar.SetSizes(CSize(temp.Width(),
   temp.Height()),CSize(16,15));

另请参阅

MFC 示例 CTRLBARS
MFC 示例 DLGCBR32
MFC 示例 DOCKTOOL
CControlBar
层次结构图
CToolBarCtrl