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
对象通常是从 CFrameWnd
或 CMDIFrameWnd
类派生的框架窗口对象的嵌入成员。
CToolBar::GetToolBarCtrl
是 MFC 4.0 新增的成员函数,允许利用 Windows 通用控件支持实现工具栏自定义和其他功能。 CToolBar
成员函数提供 Windows 常用控件的大部分功能;但是,当你调用 GetToolBarCtrl
时,可以为工具栏赋予更多 Windows 95/98 工具栏的特征。 调用 GetToolBarCtrl
时,它将返回对 CToolBarCtrl
对象的引用。 有关使用 Windows 常用控件设计工具栏的详细信息,请参阅 CToolBarCtrl
。 如需详细了解常用控件的一般信息,请参阅 Windows SDK 中的常用控件。
Visual C++ 提供了两种方法来创建工具栏。 若要使用资源编辑器创建工具栏资源,请执行以下步骤:
创建工具栏资源。
构造
CToolBar
对象。调用
LoadToolBar
以加载工具栏资源。
否则,请执行以下步骤:
构造
CToolBar
对象。调用
LoadBitmap
以加载包含工具栏按钮图像的位图。调用
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:控制栏。
继承层次结构
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
对一个整数的引用,该整数设置为位图中按钮图像的索引。
备注
这些值分配给 nID
、nStyle
和 iImage
引用的变量。 图像索引是图像在位图中的位置,该位图包含所有工具栏按钮的图像。 第一个图像位于位置 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
调用此成员函数以加载由 lpszResourceName
或 nIDResource
指定的位图。
BOOL LoadBitmap(LPCTSTR lpszResourceName);
BOOL LoadBitmap(UINT nIDResource);
参数
lpszResourceName
指向要加载的位图的资源名称的指针。
nIDResource
要加载的位图的资源 ID。
返回值
如果成功,则不为 0;否则为 0。
备注
位图应针对每个工具栏按钮包含一个图像。 如果图像不是标准大小(16 像素宽和 15 像素高),则调用 SetSizes
以设置按钮大小及其图像。
警告
CToolBar
最多支持 16 色位图。 将图像加载到工具栏编辑器中时,Visual Studio 会根据需要自动将图像转换为 16 色位图,并在图像转换时显示警告消息。 如果使用的图像超过 16 色(使用外部编辑器来编辑图像),则应用程序可能会出现意外行为。
CToolBar::LoadToolBar
调用此成员函数以加载由 lpszResourceName
或 nIDResource
指定的工具栏。
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
类