CToolBar

类 CToolBar 的对象是带有一行位图按钮和可选分隔线的控件条。这些按钮可以像普通按钮、核选按钮或单选按钮那样动作。 CToolBar 对象通常是由

CFrameWnd 或 CMDIFrameWnd 派生的框架窗口对象的嵌入成员。

CToolBar ::GetToolBarCtrl 是 MFC4.0 后新增加的成员函数，它允许你利用W indows 通用控件对工具条的定制及其它性能的支持。 CToolBar 的成员函数为你提供了 Windows 通用控件的大多数性能；但是，当你调用 Get ToolBar Ctrl 时，你可以使你的工具条具有更多 W indows 95 工具条的特征。参见 CToolBar Ctrl 可以获得更多有关如何使用 W indows 通用控件来设计工具条的信息。更多有关通用控件的一般信息，参见“ W indows 95 SDK 程序员参考 ” 中的“ 通用控件 ”。

Visual C++ 提供了两种创建一个工具条的方法。要使用资源编辑器（ Resource Editor）创建一个工具条，应遵循下面的步骤：

创建一个工具条资源。
构造 CToolBar 对象。
调用 Creat e（或 CreateEx ）函数来创建 W indows 工具条并将

它与该 CToolBar

对象连接。

调用 LoadToolBar 来装入工具条资源。

另外，也可以依据下面的步骤：

构造 CToolBar 对象。
调用 Create （或 CreateE x）函数来创建 W indows 工具条并将

它与 CToolBar

对象连接。

调用 LoadBitmap 来装入包含工具条按钮图像的位图。
调用 SetButtons 来设置按钮风格并使每一个按钮与位图

中的一幅图像关联。

此工具条中的所有按钮图像都位于同一个位图，该位图必须为每一个按钮包含一个图像。所有的图像都必须是同样大小的。缺省的尺寸是 16 个像素宽和 15 个像素高。这些图像必须一幅接一幅的放在位图中。

SetButton 函数以指向一个控制 ID 数组的指针和一个指定数组中元素数目的整数作为参数。该函数将每个按钮的 ID 值设置为对应的数组元素的值，并赋予每个按钮一个图像索引值，每个索引值指定对应按钮图像在位图中的位置。如果某一数组元素的值为 ID_SEPARATOR ，则不为其赋图像索引值。

按钮图像在位图中的次序通常就是图像在屏幕上的绘制次序，但你也可以使用

SetButtonInfo 函数来修改图像次序和绘制次序的关系。

一个工具条中的所有按钮都具有相同的尺寸。按照 “ Windows 界面软件设计指南 ” 中所说，缺省尺寸为 24 × 22 个像素。图像和按钮之间的任何空白尺寸都可用来在图像周围形成一个边界。

每个按钮具有一幅图像。按钮的各种状态和风格（被压住，弹起，按下，无效，无效按下，以及不定）都可以由这幅图像产生。虽然位图可以是任何颜色，但是使用灰色加黑色文字及阴影可实现最好的效果。

缺省情况下，工具条按钮模拟普通按钮。但是，工具条按钮也可以模拟复选框按钮和单选按钮。复选框按钮具有三种状态：核选，清除和不定。单选按钮值具有两种状态：核选和清除。

要设置单个按钮或不指向一个数组的分隔线风格，可以调用 GetButtonStyle 来获取这个风格，然后调用 SetButtonStyle （而不是调用 SetButton ）。当你要在运行时改变按钮的风格时， 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_UPDAT_COMMAND_UI 处理程序。

有关使用 CToolBar 的更多信息，参见 “ V isual C++ 程序员指南 ” 中的文章 “工具条 ” 和 “ Visual C++ 联机文件 ” 中的技术注释 31 ，控制条。

＃ include <afxext.h>

请参阅 CToolBarCtrl, CControlBar, CToolBar::Create, CToolBar::LoadBitmap, CToolBar::SetButtons, CCmdUI::SetCheck, CCmdUI::SetRadio

CToolBar 类成员

Construction

CtoolBar 创建一个 CtoolBar 对象

Create 创建 Windows 工具条并将它与该 CToolBar 连接

CreateEx 为嵌入的 CtoolBarCtrl 对象创建一个具有附加风格

的 CToolBar 对象

SetSizes 设置按钮及其位图的尺寸

SetHeight 设置工具条的高度

LoadToolBar 装入一个用资源编辑器创建的工具条资源

LoadBitmap 装入包含位图 - 按钮图像的位图

SetBitmap 设置一个位图中的图像

SetButtons 设置按钮风格和按钮图像在位图中的索引

Attributes

CommandToIndex 返回具有给定的命令 ID 的按钮的索引GetItemID 返回具有给定索引值的按钮或分隔线的命令 ID GetItemRect 获取具有给定索引值的项的显示矩形GetButtonStyle 获取一个按钮的风格

SetButtonStyle 设置一个按钮的风格

GetButtonInfo 获取一个按钮的 ID ，风格和图像号

SetButtonInfo 设置一个按钮的 ID ，风格和图像号

GetButtonText 获取要显示在一个按钮上的文本SetButtonText 设置要显示在一个按钮上的文本GetToolBarCtrl 允许直接访问基本的通用控件

成员函数

CToolBar::CommandToIndex

int CommandToIndex( UINT nIDFind );

返回值

返回按钮的索引，如果没有按钮具有这个给定的命令 ID ，则返回 -1 。

参数

nIDFind

个工具条按钮的命令 ID 。

说明

此成员函数返回第一个工具条按钮的从位置 0 开始的索引，该按钮的命令 ID

与 nIDFind 匹配。

请参阅 CToolBar::GetItemId

CToolBar::Create

BOOL Create( CWnd* pParentWnd , DWORD dwStyle = WS_CHILD | WS_VISIBLE |

CBRS_TOP, UINT nID = AFX_IDW_TOOLBAR );

返回值

如果成功则返回非零值；否则返回 0 。

参数

pParentWnd

指向工具条的父窗口的指针。

dwStyle

工具条的风格。下面列出的是此参数支持的附加风格：

CBRS_TOP 控制条位于框架窗口的顶部。
CBRS_BOTTOM 控制条位于框架窗口的底部。
CBRS_NOALIGN 当父窗口调整尺寸时不重定位控制条。
CBRS_TOOLTIPS 控制条显示工具提示。
CBRS_SIZE_DYNAMIC 控制条是动态的。
CBRS_SIZE_FIXED 控制条是固定的。
CBRS_FLOATING 控制条是浮动的。
CBRS_FLYBY 状态条显示按钮的信息。
CBRS_HIDE_INPLACE 控件不显示给用户。

工具条子窗口的 ID 。

说明

此成员函数用来创建一个 W indows 工具条（一个子窗口），并将它与 CToolBan

对象连接。它还将工具条的高度设置为缺省值。

请参阅 CToolBar::CToolBar, CToolBar::LoadBitmap, CToolBar::SetButtons,

CToolBar::LoadToolBar,CControlBar::CalcDynamicLayout, CControlBar::CalcFixedLayout

CToolBar::CreateEx

BOOL CreateEx( CWnd* pParentWnd , D W O R D dwCtrlStyle = TBSTYLE_FLAT,

DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_ALIGN_TOP,

CRect rcBorders = CRect( 0, 0, 0 ), UINT nID = AFX_IDW_TOOLBAR );

返回值

如果成功则返回非零值；否则返回 0 。

参数

pParentWnd

指向工具条的父窗口的指针。

dwCtrlStyle

嵌入 CToolBarCtrl 对象的附加风格。缺省的，这个值被设置为

TBSTYLE_FLAT 。工具条风格的完整列表，参见 dwStyle 。dwStyle

工具条风格。参见 “ Platform SDK ” 的 “ 工具条控件和按钮风格 ” 可以

获得一个相关风格的列表。

rcBorders

一个定义工具条窗口边框的宽度的 CRect 对象。缺省的这些边框被设置为 0 ， 0 ， 0 ， 0 ，这样的工具条窗口是没有边界的。

nID

工具条的子窗口 ID 。

说明

此成员函数用来创建一个 W indows 工具条（一个子窗口）并将它与该 CToolBar

对象连接。它还将工具条的高度设置为一个缺省值。

当在嵌入工具条控件的创建期间需要指定某个特定的风格时，使用 CreateEx 来代替 Create 。例如，将 dwCtrlStyle 设置为 TBSTYLE_FLAT | TBSTYLE_TRANSPARENT 来创建一个类似于 Internet Explorer 4 工具条的工

具条。

CToolBar::CToolBar

CToolBar( );

说明

这个成员函数构造一个 CToolBar 对象并将它设置为缺省尺寸。

请参阅 CToolBar::Create

CToolBar::GetButtonInfo

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

参数

nIndex

要获取其信息的工具条按钮或分隔线的索引。

nID

对一个被设置为按钮的命令 ID 的 UINT 值的引用。

nStyle

对一个被设置为按钮的风格的 U IN T 值的引用。

iImage

对一个被设置为按钮的图像在位图中的索引值的整数的引用。

说明

此成员函数用来获取位于由 nIndex 指定的位置的工具条按钮或分隔线的控制ID ，风格和图像索引。这些值被分别赋给由 nID ， nStyle 和 iImage 引用的变量。图像索引是图像在位图中的位置，该位图包含了所有工具条按钮的图像。第一个图像位于位置 0 。

如果 nIndex 指定的是一个分隔线，则 iImage 被设置为以像素表示的分隔线宽度。

请参阅 CToolBar::SetButtonInfo, CToolBar::GetItemID

CToolBar::GetButtonStyle

UINT GetButtonStyle( int nIndex ) const;

返回值

返回由 nIndex 指定的按钮或分隔线的风格。

参数

nIndex

要获取其风格的工具条按钮或分隔线的索引。

此成员函数用来获取工具条上的一个按钮或分隔线的风格。一个按钮的风格确定了按钮显示的样子，以及按钮对用户输入作出的反应。参见 SetButtonStyle 可以获得有关按钮风格的例子。

请参阅 CToolBar::SetButtonStyle

CToolBar::GetButtonText

CString GetButtonText( int nIndex ) const;

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

返回值

返回包含按钮的文本的 CString 对象。

nIndex

要获取的文本的索引。

rString

一个对 CSing 对象的引用，该对象将包含要被获取的文本。

说明

此成员函数用来获取显示在一个按钮上的文本。这个函数的第二种形式用字符串文本来填充一个 CString 对象。

请参阅 CToolBar::SetButtonText

CToolBar::GetItemID

UINT GetItemID( int nIndex ) const;

返回由 nIndex 指定的按钮或分隔线的命令 ID 。

参数

nIndex

要获取其 ID 的项的索引。

说明

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

ID_SEPARATO R 。

请参阅 CToolBar::CommandToIndex, CControlBar::GetCount

CToolBar::GetItemRect

virtual void GetItemRect( int nIndex , LPRECT lpRect );

参数

nIndex

要获取其矩形坐标的项（按钮或分隔线）的索引。

lpRect

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

说明

此成员函数用由 nIndex 指定的按钮或分隔线的坐标来填充由 lpRect 指定地址的

RECT 结构。坐标是以像素为单位的相对于工具条的左上角的值。

使用 GetItemRect 函数可以获取要用组合框或其它控件替换的分隔线的坐标。

CToolBar::GetToolBarCtrl CToolBarCtrl& GetToolBarCtrl( ) const; 返回值

返回一个对 CToolBarCtrl 对象的引用。

说明

此成员函数允许对基本通用控件的直接访问。

使用 GetToolBarCtrl 可以利用 Windows 工具条通用控件的性能，并且可以利用

CToolBarCtrl 为工具条定制提供的支持。

有关使用命令控件的更多信息，参见 “ V isual C++ 程序员指南 ” 中的文章 “控

请参阅 CToolBarCtrl

CToolBar::LoadBitmap

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

返回值

如果成功则返回非零值；否则返回 0 。

参数

lpszResourceName

指向要被装入的位图的资源名称的指针。

nIDResource

要装入的位图的资源 ID 。

说明

此成员函数用来装入由 lpszResourceName 或 nIDResource 指定的位图。该位图应该为每一个工具条按钮包含一个图像。如果该图像不具有标准尺寸（ 16 像素宽， 15 像素高），则定义 SetSizes 来设置按钮的尺寸和它们的图像。

请参阅 CToolBar::Create, CToolBar::SetButtons, CToolBar::SetSizes, CToolBar::LoadToolBar

CToolBar::LoadToolBar

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

返回值

如果成功则返回非零值；否则返回 0 。

参数

lpszResourceName

指向要被装入的工具条的资源名称的指针。

nIDResource

要装入的工具条的资源 ID 。

说明

此成员函数用来装入由 lpszResourceName 或 nIDResource 指定的工具条。

参见 “ Visual C++ 用户指南 ” 中的 “ 工具条编辑器 ” 可以获得有关创建一个工具条资源的更多信息。

CToolBar::SetBitmap

BOOL SetBitmap( HBITMAP hbmImageWell );

返回值

如果成功则返回非零值；否则返回 0 。

参数

hbmImageWell

个与工具条相关联的位图图像的句柄。

说明

此成员函数用来为工具条设置位图图像。例如，在用户对文档采取了可以改变

CToolBar::SetButtonInfo

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

参数

nIndex

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

nID

要给按钮的命令 ID 设置的值。

nStyle

新的按钮风格。下面的按钮风格是被支持的：

TBBS_BUTTON 标准按钮（缺省的）
TBBS_SEPARATOR 分隔线。
TBBS_CHECKBOX 自动复选框按钮。
TBBS_GROUP 标记一个按钮组的开始。
TBBS_CHECKGROUP 标记一个复选框按钮组的开始。

iImage

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

说明

此成员函数用来设置按钮的命令 ID ，风格和图像号。对于具有TBBS_SEPARATOR 风格的分隔线，这个函数将分隔线的以像素为单位的宽度设置为保存在 iImage 中的值。

有关位图图像和按钮的更多信息，参见 CToolBar 概述和

CToolBar::LoadBitmap 。

请参阅 CToolBar::GetButtonInfo

CToolBar::SetButtons

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

返回值

如果成功则返回非零值；否则返回 0 。

参数

lpIDArray

指向一个命令 Ids 数组的指针。它可以是 NULL ，用于分配空的按钮。

nIDCount

由 lpIDArray 指向的数组的元素数目。

说明

此成员函数用来将每一个工具条按钮的命令 ID 设置为由数组 lpIDArray 的相应元素指定的值。如果该数组的某个元素的值是 ID_SEPARATOR ，则在工具条的相应位置创建一个分隔线。这个函数还将每个控件的风格设置为TBBS_BUTTON ，将每个分隔线的风格设置为 TBBS_SEPARATOR ，并为每一个按钮分配一个图像索引。图像索引指定了按钮的图像在位图中的位置。

你不用在位图中说明分隔线，因为这个函数不给分隔线分配图像索引。如果你的工具条有位于位置 0 ， 1 和 3 的按钮，有位于位置 2 的分隔线，则位于你的位图中的位置 0 ， 1 ，和 2 的图像将被分别分配给位置 0 ， 1 和 3 的位图。

如果 lpIDArray 是 NULL ，则此函数按 nIDCount 指定的项数分配空间。使用

SetButtonInfo 可以设置每一个项的属性。

请参阅 CToolBar::Create, CToolBar::SetButtonInfo, CToolBar::SetButtonStyle, CToolBar::LoadToolBar

CToolBar::SetButtonStyle

void SetButtonStyle( int nIndex , UINT nStyle );

参数

nIndex

要设置其风格的按钮或分隔线的索引。

nStyle

按钮风格。下面的按钮风格都是被支持的：

TBBS_BUTTON 标准按钮（缺省的）
TBBS_SEPARATOR 分隔线。
TBBS_CHECKBOX 自动复选框按钮。
TBBS_GROUP 标记一个按钮组的开始。
TBBS_CHECKGROUP 标记一个复选框按钮组的开始。

说明

此成员函数用来设置一个按钮或分隔线或按钮组的风格。一个按钮的风格决定了按钮是如何显示的，以及它对用户的输入是如何反应的。

在调用 SetButtonStyle 之前，调用 GetButtonStyle 成员函数来获取该按钮或分隔线的风格。

请参阅 CToolBar::GetButtonStyle

CToolBar::SetButtonText

BOOL SetButtonText( int nIndex , LPCTSTR lpszText );

返回值

如果成功则返回非零值；否则返回 0 。

参数

nIndex

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

lpszText

指向要被设置到一个按钮上的文本。

说明

此成员函数用来设置一个按钮上的文本。

请参阅 CToolBar::GetButtonText

CToolBar::SetHeight

void SetHeight( int cyHeight );

参数

cyHeight

是工具条的以像素表示的高度。

说明

此成员函数用来将工具条的高度设置为在 cyHeight 中指定的以像素表示的值。

在调用 SetSize 之后，可以使用这个成员函数来重新设置这个标准工具条的高度。如果这个高度太小，则按钮将被从底部剪切。

如果没有调用这个函数，则框架使用该按钮的尺寸来确定此工具条的高度。

请参阅 CToolBar::SetSizes, CToolBar::SetButtonInfo, CToolBar::SetButtons

CToolBar::SetSizes

void SetSizes( SIZE sizeButton , SIZE sizeImage );

参数

sizeButton

每个按钮的用像素表示的尺寸。

sizeImage

每个图像的以像素表示的尺寸。

说明

此成员函数用来将工具条的按钮的尺寸设置为在 sizeButton 中指定的以像素表示的尺寸。 sizeImage 参数必须包含在工具条位图中的图像的以像素表示的尺寸。 sizeButton 中的空间必须足够大以能存放在宽度上加 7 个像素，在高度上

加 6 个像素的按钮图像。此函数还用来设置工具条的高度以使它能与按钮相适合。

只有当工具条不采用 “ W indows 界面软件设计 ” 中推荐的按钮和图像尺寸时，才调用这个函数。

请参阅 CToolBar::LoadBitmap, CToolBar::SetButtonInfo, CToolBar::SetButtons,

CToolBar

CToolBar

CToolBar 类 成 员

成 员 函 数

CToolBar 类成员

成员函数