CToolBarCtrl - 图1

CToolBarCtrl - 图2 返回

CToolBarCtrl CToolTipCtrl CTreeCtrl CTreeView CTypedPtrArray CTypedPtrList CTypedPtrMap CUIntArray CUserException C V iew

CWa itCursor C W inApp

C W indowDC C W inThread CWnd CwordArray

MFC 中的宏和全局函数、变量

宏、全局函数和全局变量

结构、风格、回调函数和消息映射

CToolBarCtrl

CToolBarCtrl 类提供了 W indows 工具条通用控件的性能。这个控件（也就是CToolBarCtrl 类）只对运行在 W indows 95 和 W indows NT 3.51 或更高版本下的程序来说才是可用的。

个 W indows 工具条通用控件是一个矩形子窗口，它包含
一个或多个按钮。这些按钮可以显示一个位图图像，一个字符串，或两者都有。当用户选择一个按

钮时，它向该工具条的属主窗口发送一条命令消息。通常，工具条中的按钮对应于应用程序的菜单中的项；这些按钮为用户访问一个应用程序的命令提供了更为直接的方法。

CToolBarCtrl 对象包含几个重要的内部数据结构：一个按钮图像列表或一个图像列表，一个按钮标签字符串列表和一个 TBBUTTON 结构的列表，该结构使一个图像和 / 或字符串与按钮的位置，风格，主题和命令 ID 相关联。这些数据结构的每一个都由一个从零开始的索引来引用。在你可以使用一个 CToolBarCtrl 对象之前，你必须设置这些数据结构。字符串列表只能被用作按钮标签；不能从按钮中检取字符串。

要使用一个 CToolBarCtrl 对象，通常你应该遵循下面的这些步骤：

构造该 CToolBarCtrl 对象。
调用 Create 来创建 W indows 工具条通用控件并将它与该

CToolBarCtrl 对象连接。通过使用风格来指定工具条的风格，如对一个透明的工具条使用TBSTYLE_ TRANSPARENT ，或对一个支持风格按钮的工具条使用TBSTYLE_DROPDOW N 。
指明你希望按钮在工具条上如何显示：
- 给按钮使用位图图像，通过调用 AddBitmap 将按钮位
  
  图添加到工具条中。
- 给按钮使用来自一个图像列表的图像，通过调用
  
  SetImageList ，

SetHotImageList ，或 SetDisabledImageList 来指定图像列表。

给按钮使用字符串标签，通过调用 AddString 和 /或
AddStrings 来将字符串添加到工具条中。

通过调用 AddButtons 将按钮结构添加到工具条中。
如果你希望在一个不是 CFrameWnd 的属主窗口中的工具

条具有工具提示，则你必须在工具条的属主窗口中处理 TTN_NEEDTEXT 消息，就像在CToolBarCtrl ：处理工具提示通知中描述的一样。如果工具条的父窗口是由 CFrameWnd 派生而来的，则你不用作任何额外的努力就可以显示工具提示，因为 CFrameWnd 提供了一个缺省的处理函数。
如果你希望能够让用户定制工具条，则在属主窗口中

处理定制通知消息，就像在 CToolBarCtrl：处理定制通知中描述的一样。

你可以使用 SaveState 来将一个工具条控件的当前状态保存在注册表中，用RestoreState 来根据注册表中先前保存的信息恢复工具条的状态。除了在应用程序的使用之间保存工具条的状态，通常在用户开始定制该工具条之前应用程序会保存工具条的状态，以防用户后来想将工具条恢复到它的最初的状态。

为 Internet Explorer 4.0 或更新版提供的支持

要支持在 Internet Explorer 4.0 或更新版之后引入的性能， MFC 提供了图像列表支持，为工具条提供了透明和平坦风格。

一个透明的工具条允许在工具条下的客户被透过工具条显示出来。要创建一个透明的工具条，要同时使用 TBSTYLE_FLAT 和 TBSTYLE_TRANSPARENT 风格。透明的工具条具有热点跟踪的特色；就是说，当鼠标指针移动到工具条的一个热点按钮上时，按钮的外观改变。只用 TBSTYLE_FLAT 风格创建的工具条将包含不透明的按钮。

图像列表支持使控件的缺省行为具有更大的灵活性，并支持热点图像和无效的图像。对透明的工具条使用 GetImageList ， GetHotImageList 和GetDisabledImageList 可以根据它的状态来操纵图像。

有关使用 CToolBarCtrl 的更多信息，参见 “ Visual C++ 程序员指南 ” 中的 “ 控件主题 ” 和 “ 使用 CToolBarCtrl” 。

#include <afxcmn.h>

请参阅 CToolBar

CToolBarCtrl 类成员

Construction

CToolBarCtrl 构造一个 CToolBarCtrl 对象

Create 创建一个工具条控件并将它与一个 CToolBarCtrl 对象连接

Attributes

IsButtonEnabled 指示一个工具条控件中的指定按钮是否是有效的IsButtonChecked 指示一个工具条控件中的指定按钮是否被核选了IsButtonPressed 指示一个工具条控件中的指定按钮是否被压住IsButtonHidden 指示一个工具条控件中的指定按钮是否被隐藏

续表

IsButtonIndeterminate 指示一个工具条控件中的指定按钮的状态是否是

不确定的（灰的）

SetState 设置一个工具条控件中的指定按钮的状态

GetState 获取关于一个工具条控件中的指定按钮的状态的信息，比如它是有效的、被压住的，或是被核选的

GetButton 获取一个工具条控件中的指定按钮的信息GetButtonCount 获取当前在该工具条控件中的按钮的数目GetItemRect 获取一个工具条控制中的按钮的边界矩形GetRect 获取一个特定工具条按钮的边界矩形SetButtonStructSize 指定 TBBUTTON 结构的大小

GetButtonSize 获取的像素表示的工具条按钮当前宽度和高度

SetButtonSize 设置要被添加到一个工具条控件中去的按钮的尺

寸

SetBitmapSize 设置要被添加到一个工具条控件中去的位图图像

的尺寸

GetToolTips 获取与此工具条控件相关联的工具提示控件（如

果有的话）的句柄

SetToolTips 将一个工具提示控件与该工具条控件关联

SetOwner 设置接收来自工具条控件的通知消息的窗口

SetRows 设置显示在工具条中的按钮的行数

续表

GetRows 获取当前显示在工具条中的按钮的行数

SetCmdID 设置当指定按钮被按下时，要发送到属主窗口的

命令标识符

GetBitmapFlags 获取与工具条位图相关联的标志

GetDisabledImageLis t

获取被一个工具条控件用来显示无效按钮的图像列表

GetHotImageList 获取被一个工具条控件用来显示 “ 热点 ” 按钮的

图像列表。当鼠标指针在一个热点控件上时，该控件被加亮显示

GetImageList 获取被一个工具条控件用来显示缺省状态按钮的

图像列表

GetStyle 获取一个工具条控件当前使用的风格

GetMaxTextRows 获取显示在一个工具条按钮上的文本行的最大行

数

IsButtonHighlighted 检验工具条控件的加亮状态

SetButtonWidth 设置工具条控件中的按钮宽度的最大和最小值

SetDisabledImageList 设置将要被工具条控件用来显示无效按钮的图像

列表

SetHotImageLise 设置将要被工具条控件用来显示 “ 热点 ” 按钮的

图像列表

续表

SetImageList 设置将要被工具条控件用来显示缺省状态按钮的

图像列表

GetDropTarget 获取一个工具条控件的 IDropTarget 接口SetIndent 设置一个工具条控件中的第一个按钮的缩排SetMaxTextRows 设置一个工具条按钮所显示的最大文本行数SetStyle 设置一个工具条控件的风格GetAnchorHighlight 获取一个工具条的固定的加亮设置SetAnchorHighlight 设置一个工具条的固定的加亮设置GetHotItem 获取一个工具条中的热点项的索引

SetHotItem 设置一个工具条中的热点项的索引

GetInsertMark 获取工具条的当前插入标记

SetInsertMark 设置工具条的当前插入标记

GetMaxSize 获取工具条中的所有可视按钮和分隔线的总的尺

寸

InsertMarkHitTest 获取一个工具条中的某个点的插入标记信息

GetExtendedStyle 获取一个工具条控件的扩展风格

SetExtendedStyle 设置一个工具条控件的扩展风格GetInsertMarkColor 获取用来绘制工具条的插入标记的颜色SetInsertMarkColor 设置用来绘制工具条的插入标记的颜色MapAccelerator 将一个加速键映射到一个工具条按钮MoveButton 将一个按钮从一个索引移动到另一个索引HitTest 确定一个点位于一个工具条控件的什么地方

Operation s

EnableButton 使一个工具条控件中的按钮有效或无效CheckButton 核选或清除一个工具条控件中的指定按钮PressButton 按下或释放一个工具条控件中的指定按钮GetButtonInfo 获取工具条中的一个按钮的信息SetButtonInfo 设置工具条中的一个按钮的信息

S etDrawTextFlags 设置 W in 32 中 DrawText 功能的标志，该功能通常

根据标志设置的指定矩形、格式设置文本 HideButton 隐藏或显示一个工具条控件中的指定按钮Indeterminate 设置或清除一个工具条控件中的指定按钮的不确定

（灰的）状态

AddBitmap 将一个或更多个位图按钮图像添加到一个工具条控

件可用的按钮图像列表中

AddButtons 将一个或多个按钮添加到一个工具条按钮中InsertButton 在一个工具条控件中插入一个按钮DeleteButton 从该工具条控件中删除一个按钮

CommandToIndex 获取与指定的命令标识符相关联的按钮的从零开始

的索引

RestoreState 恢复该工具条控件的状态

MarkButton 设置在一个工具条控件中给定的高亮状态LoadImages 将位图定位到工具条控件的图像列表中SaveState 保存该工具条控件的状态

Customize 显示 CustomizeToolbar 对话框

AddString 将作为一个资源 ID 传递的新字符串添加到工具条

的内部字符串列表中

AddStrings 将一个或多个新字符串添加到工具条的内部字符串

列表中，是通过传递指向这些用 .空字符分隔的字符串的缓冲区的指针来传递这些字符串的

AutoSize 调整一个工具条控件的尺寸

CToolBarCtrl ：处理工具提示通知

当你指定工具条具有 TBSTYLE_TOOLTIPS 风格时，该工具条创建并管理一个工具提示控件。一个工具提示是一个小的弹出窗口，该窗口包含了一行用于描述一个工具条按钮的文本。通常该工具提示是被隐藏的，只有当用户将光标放在一个工具条按钮上并停留大概半秒时间时它才显示出来。工具提示显示在光标的附近。

在工具提示被显示之前， TTN_NEEDTEXT 通知消息被发送给该工具条的属主窗口，以获取对应于该按钮的描述文本。如果该工具条的属主窗口是一个CFrameWnd 窗口，则不需要任何额外的工作就会显示工具提示，因为CFrameWnd 有一个缺省的 TTN_NEEDTEXT 通知处理函数。如果该工具条的属主窗口不是由 CFrameWnd 派生而来的，比如是一个对话框或格式视，则你必须在你的属主窗口的消息映射中添加一项，并在消息映射中提供一个通知处理函数。下面就是要被添加到你的属主窗口的消息映射：

ON_NOTIFY_EX( TTN_NEEDTEXT, 0, memberFxn )

memberFxn

当这个按钮的文本需要显示时将被调用的成员函数。注意，一个工具提示的 id 总是 0 。

除了 TTN_NEEDTEXT 通知，一个工具提示控件可以向一个工具条控件发送下列通知：

通知消息含义

TTN_NEEDTEXTA 需要 ASCII 文本的工具提示控件（只在 W in95

下）

TTN_NEEDTEXTW 需要 UNICODE 文本的工具提示控件（只在

W indows N T 下） TBN_HOTITEMCHANGE 表示热点（被加亮的）项已经改变了NM_RCLICK 表示用户用鼠标右键单击一个按钮

TBN_DRAGOUT 表示用户点击按钮并拖动指针离开了按钮。

它支持应用程序实现对一个工具条按钮的拖放。但接收到这个通知时，应用程序将开始拖放操作

TBN_DROPDOWN 表示用户已经点击了一个使用

TBSTYLE_DROPDOWN 风格的按钮

TBN_GETOBJECT 表示用户已经将指针移动到了一个使用

TBSTYLE_DROPDOWN 风格的按钮上

处理函数的例子和有关使能工具提示的更多信息，参见 “ V isual C++ 程序员指南 ” 中的 “ 工具提示 ” 。

CToolBarCtrl ：处理定制通知

个 W indows 工具条通用控件具有内在的定制特征，包括
一个系统定义的定制

对话框，用来让用户插入、删除，或重新安排工具条按钮。应用程序决定定制是否有效，并控制用户对该工具条定制的限度。

你可以通过给予工具条 CCS_ADJUSTABLE 风格来使这些定制特征对于用户来说是可用的。此定制特征允许用户将一个按钮拖动到一个新的位置，或通过拖动按钮离开工具条来删除这个按钮。另外，用户可以双击工具条来显示Customize Toolbar 对话框，让用户添加、删除，或重新安排工具条按钮。应用程序可以通过使用 Custoimize 成员函数来显示对话框。

在定制过程中的每一步，工具条控件都向父窗口发送通知消息。如果用户按住SHIFT 键并开始拖动一个按钮，则工具条自动处理这个拖动操作。工具条发送TBN_QUERYDELETE 通知消息给父窗口，以确定是否应该删除该按钮。如果父窗口返回 FALSE ，则这个拖动操作结束。否则，工具条捕捉鼠标输入并等待用户释放鼠标按钮。

当用户释放鼠标按钮时，工具条控件确定鼠标光标所在的位置。如果该光标的位置是在工具条之外，则按钮被删除。如果光标位于另一个工具条按钮上，则工具条向其父窗口发送 TBN_QUERYINSERT 通知消息，以确定是否要将一个按钮插入在给定按钮的左边。如果父窗口返回 TRUE ，则该按钮被插入；否则，不插入。工具条发送 TBN_TOOLBARCHANGE 通知来表示拖动操作结束。

如果用户在没有按下 SHIFT 键的情况下开始一次拖动操作，则工具条控件发送TBN_BEGINDRAG 通知消息给属主窗口。一个实现了自己的按钮拖动代码的应用程序可以使用这个消息作为开始一次拖动操作的信号。工具条发送TBN_ENDDRAG 通知消息来表示拖动操作结束。

当用户通过使用 Customize Toolbar 对话框来定制一个工具条时，该工具条控件发送通知消息。在用户双击工具条之后，但在对话框被创建之前，该工具条发送 TBN_BEGINADJUST 通知消息。然后，工具条开始发送一系列TBN_QUERYINSERT 消息，以确定该工具条是否允许插入按钮。当父窗口返回 TRUE 时，该工具条停止发送 TBN_QUERYINSERT 通知消息。如果父窗口没有对任何按钮返回 TRUE ，则工具条销毁该对话框。

接着，工具条控件通过为工具条中的每一个按钮发送一个 TBN_QUERYDELETE 通知消息来确定是否可以从工具条中删除某个按钮。父窗口返回 TRUE 则表示可以删除该按钮；否则，父窗口返回 FALSE 。工具条将所有的按钮都添加到对话框中，但是将那些不能删除的按钮变灰。

不管什么时候，当工具条控件需要有关 Customize Toolbar 对话框中的某个控件的信息时，它就发送 TBN_GETBUTTONINFO 通知信息，并指定它想获取其信息的按钮的索引，以及一个 TBNOTIFY 结构的地址。父窗口必须用相关的信息填充该结构。

Customize Toolbar 对话框还包括一个 Help 按钮和一个 Reset 按钮。当用户选择Help 按钮时，工具条控件发送 TBN_CUSTHELP 通知消息。父窗口应该通过显示帮助信息来作出响应。当用户选择 Reset 按钮时，对话框发送 TBN_RESET 消息。这个消息表示工具条要再次初始化这个对话框。

这些消息都是 WM_NOTIFY 消息，通过向你的属主窗口的消息映射中添加下列形式的消息映射项，你可以在你的属主窗口中处理它们。

ON_NOTIFY （ wNotifyCode , idContro l, memberFxn ）

wNotifyCode

通知消息标识符代码，比如 TBN_BEGINADJUST 。

idControl

发送通知的控件的标识符。

memberFxn

当这个通知被接收时要被调用的成员函数。

你的成员函数应该用下面的原形来声明：

afx_msg void memberFxn ( NMHDR * pNotifyStruct, LRESULT * result );

如果通知消息的处理函数返回一个值，则处理函数应该将这个值存放在由 result

指向的 LRESULT 中。

对每一个消息， pNotifyStruct 指向一个 N M H D R 结构或一个 TBNOTIFY 结构。这些结构被描述如下：

N M H D R 结构包含了下列成员：

typedef struct tagN M H D R {

H W N D hwndFrom; // 发送消息的控件的句柄UINT idFrom; // 发送消息的控件的标识符UINT code; // 通知代码，参见下面

} NMHDR;

hwndFrom

正发送通知的控件的窗口句柄。要将这个句柄转换为一个 CWnd 指针，可以使用 CWnd::FromHandle 。

idFrom

发送通知的控件的标识符。

code

通知代码。这个成员可以是一个特定于一个控件类型的值，比如TBN_BEGINADJUST 或 TTN_NEEDTEXT ，或者它可以是下面列出的普通通知值中的一个：

NM_CLICK 用户在控件中单击了鼠标的左按钮。
NM_DBLCLK 用户在控件中双击了鼠标的左按钮。
NM_KILLFOCUS 控件失去了输入焦点。
NM_OUTOFMEMORY 由于没有足够的可用内存，控件无法完

成一次操作。
NM_RCLICK 用户在控件中单击了鼠标的右按钮。
NM_RDBLCLK 用户在控件中双击了鼠标的右按钮。
NM_RETURN 控件拥有输入焦点，并且用户按下了 ENTER 键

。
NM_SETFOCUS 控件已经接收了输入焦点。

TBNOTIFY 结构包含下列成员：

typedef struct {

N M H D R hdr; // 对所有 WM_NOTIFY 消息都通用的信息

int iItem; // 与通知相关联的控件的的索引TBBUTTON tbButton; // 与通知相关联的控件的信息int cchText; // 按钮文本中的字符数

LPSTR lpszText; // 按钮文本的地址

} TBNOTIFY, FAR* LPTBNOTIFY;

hdr

iItem

对所有 WM_NOTIFY 消息都通用的信息。

与通知相关联的控件的的索引。

tbButton

包含与通知相关联的工具条控件信息的 BBUTTON 结构。

cchText

按钮文本中的字符数。

lpszText

指向按钮文本的指针。工具条发送下列信息：

TBN_BEGINADJUST 当用户开始定制一个工具条控件时发送
此通知。指

针指向的 N M H D R 结构包含了有关这个通知的信息。处理程序不需要返回任何值。

TBN_BEGINDRAG 当用户开始拖动一个工具条控件中的按钮
时发送此通

知。指针指向一个 TBNOTIFY 结构。 iItem 成员包含了被拖动的按钮的从零开始的索引。处理程序不需要返回任何特定的值。

TBN_CUSTHELP 当用户在 Customize Toolbar 对话框中选择了

Help 按钮时发送此通知。没有返回值。指针指向一个 N M H D R 结构，该结构包含了有关这个通知消息的信息。处理程序不需要返回任何特定的值。
TBN_ENDADJUST 当用户停止定制有关工具条时发送此通知

。指针指向一个 N M H D R 结构，该结构包含了有关此通知消息的信息。处理程序不需要返回任何特定的值。
TBN_ENDDRAG 当用户停止拖动一个工具条控件中的按钮

时发送此通知。指针指向一个 TBNOTIFY 结构。 iItem 成员包含了被拖动的按钮的从零开始的索引。处理程序不需要返回任何特定的值。
TBN_GETBUTTONINFO 当用户正在定制一个工具条控件时发

送此通知。工具条使用这个通知消息来获取 Customize Toolbar 对话框需要的信息。指针指向一个 TBNOTIFY 结构。 iItem 成员指定了一个按钮的从零开始的索引。 lpszText 和 cchText 成员指定当前按钮文本的地址和以字符数表示的长度。应用程序应该用有关这个按钮的信息来填充该结构。如果按钮的信息被拷贝到了结构中，则返回 TRUE ；否则就返回 FALSE 。
TBN_QUERYDELETE 当用户正在定制一个工具条时发送此消

息，以确

定一个按钮是否可以被从工具条控件中删除。指针指向一个 TBNOTIFY 结构。 iItem 成员包含了要被删除的按钮的从零开始的索引。如果允许该按钮被删除则返回 TRU E ；否则返回 FALSE 来禁止该按钮被删除。

TBN_QUERYINSERT 当用户正在定制一个工具条控件时发送
此通知，以

确定一个按钮是否可以被插入到指定按钮的左边。指针指向一个TBNOTIFY 结构。 iItem 成员包含了要被插入的按钮的从零开始的索引。如果允许一个按钮被插入到给定按钮的前面，则返回 TRUE ；否则返回FALSE 来禁止该按钮被插入。

TBN_RESET 当用户重新设置 Customize Toolbar 对话框时发送

此通知。指针指向一个 N M H D R 结构，该结构包含了有关这个通知消息的信息。处理程序不需要返回任何特定的值。
TBN_TOOLBARCHANGE 在用户定制完一个工具条控件之后发

送此通知。指针指向一个 N M H D R 结构，该结构包含了有关这个通知消息的信息。处理程序不需要返回任何特定的值。

成员函数

CToolBarCtrl::AddBitmap

int AddBitmap( int nNumButton s, UINT nBitmapID ); int AddBitmap( int nNumButton s, CBitmap* pBitmap );

返回值

如果成功则返回第一个新图像的从零开始的索引；否则返回 -1 。

参数

nNumButtons

位图中的按钮图像的数目。

nBitmapID

包含按钮图像或要增加图像的位图的资源标识符。

pBitmap

指向包含按钮图像或要增加图像的 CBitmap 对象的指针。

说明

此成员函数用来将一个或多个按钮图像添加到保存在该工具条控件中的按钮图像列表中。在向工具条添加位图之前，你可以使用 W indows API CreateMappedBitmap 来映射颜色。

如果你传递的是一个指向 CBitMap 对象的指针，则你必须确保直到工具条被销毁的时候该位图才会被销毁。

请参阅 CToolBarCtrl::AddButtons, CToolBarCtrl::InsertButton, CToolBarCtrl::AddString, CToolBarCtrl::AddStrings

CToolBarCtrl::AddButtons

BOOL AddButtons( int nNumButtons , LPTBBUTTON lpButtons );

返回值

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

参数

nNumButtons

要增加的按钮数。

lpButtons

一个 TBBUTTON 结构数组的地址，该结构包含关于要添加的按钮的信息。该数组的元素数目必须与 nNumButtons 指定的按钮数一样。

说明

此成员函数用来向一个工具条控件中添加一个或多个按钮。

lpButtons 指针指向一个 TBBUTTON 结构数组。每一个与被添加的按钮相关联的 TBBUTTON 结构包含了按钮的风格，图像和 /或字符串，命令 ID ，状态和用户定义的数据：

typedef struct _TBBUTTON {

int iBitmap; // zero-based index of button image

int idCommand; // command to be sent when button pressed BYTE fsState; // button state--see below

BYTE fsStyle; // button style--see below

D W O R D dwData; // application-defined value

int iString; // zero-based index of button label string

} TBBUTTON;

其成员描述如下：

iBitmap

按钮图像的从零开始的索引。如果这个按钮没有图像，则这个成员是

NULL 。

idCommand

与此按钮相关联的命令标识符。当按钮被选择时，这个标识符在一个W M _ C O M M A N D 消息中被发送。如果 fsStyle 成员的值为TBSTYLE_SEP ，则这个成员必须是零。

fsState

按钮的状态标志。它可以是下面列出的值的一个组合：

TBSTATE_CHECKED 该按钮具有 TBSTYLE_CHECKED 风格并且被按下

。
TBSTATE_ENABLED 按钮接收用户输入。一个不具有这个状

态的按

fsStyle

钮是不接收用户输入的，并且变灰。

TBSTATE_HIDDEN 按钮不可见，并且不能接收用户输入。
TBSTATE_INDETERMINATE 按钮是变灰的。
TBSTATE_PRESSED 按钮被按下。
TBSTATE_WRAP 按钮之后是一个分隔线。此按钮还必须具

有

TBSTATE_ ENABLED 状态。

按钮风格。它可以是下列值的一个组合：

TBSTYLE_BUTTON 创建一个标准的按钮。
TBSTYLE_CHECK 创建一个每次用户点击时可以在按下和弹

起状态间切换的按钮。该按钮则处于按下状态时有一种不同的背景颜色。
TBSTYLE_CHECKGROUP 创建一个核选按钮，它被选择后一直

处于按下状态，直到同组中的另一个按钮被按下时它才弹起。
TBSTYLE_GROUP 创建一个被选择后一直处于按下状态，直

到同组中的另一个按钮被按下时它才弹起的按钮。
TBSTYLE_SEP 创建一个分隔线，为按钮组之间提供一个

小的间距。具有这个风格的按钮是不接收用户输入的。

dwData

用户定义的数据。

iString

要用来作为按钮的标签的字符串的从零开始的索引。如果这个按钮没有

字符串则这个值为 NULL 。

你提供的图像和 /或字符串的索引必须是已经通过调用 AddBitmap ， AddString ，和 /或 AddStrings 被添加到工具条控件的列表中的值。

请参阅 CToolBarCtrl::InsertButton, CToolBarCtrl::DeleteButton, CToolBarCtrl::AddBitmap, CToolBarCtrl::AddString, CToolBarCtrl::AddStrings

CToolBarCtrl::AddString

int AddString( UINT nStringID );

返回值

如果成功则返回被添加的第一个新字符串的从零开始的索引；否则返回 -1 。

参数

nStringID

要添加到工具条控件的字符串列表中去的字符串资源的资源标识符。

说明

此成员函数用来将一个被作为资源 ID 传递的新字符串添加到工具条的内部字符串列表中。

请参阅 CToolBarCtrl::AddStrings, CToolBarCtrl::AddButtons, CToolBarCtrl::InsertButton, CToolBarCtrl::AddBitmap

CToolBarCtrl::AddStrings

int AddStrings( LPCTSTR lpszStrings );

返回值

如果成功则返回被添加的第一个新字符串的从零开始的索引；否则返回 -1 。

参数

lpszStrings

一个包含要添加到工具条的字符串列表中去的一个或多个以空字符结尾的字符串的缓冲区的地址。最后一个字符串必须以两个空字符结尾。

说明

此成员函数用来将一个或多个新字符串添加到一个工具条控件的可用的字符串列表中。缓冲区中的字符串必须以空字符来分隔。

你必须确保最后一个字符串有两个空结尾符。为了准确地格式化一个常量字符串，你应该按如下的方式来写：

// 自动添加一个空字符。

lpszStrings = "Only one string to add\0";

或

// 一次调用添加三个字符串

lpszStrings = "String 1\0String 2\0String 3\0";

你不能给这个函数传递一个 CString 对象，因为在一个 CStrin 中不可能有多于一个的空字符。

请参阅 CToolBarCtrl::AddString, CToolBarCtrl::AddButtons, CToolBarCtrl::InsertButton, CToolBarCtrl::AddBitmap

CToolBarCtrl::AutoSize

void AutoSize( );

说明

此成员函数用来调整整个工具条控件的尺寸。当父窗口的尺寸改变或当工具条的尺寸改变（比如当你设置按钮或位图尺寸或添加字符串时）时，你应该调用这个函数。

请参阅 CToolBarCtrl::SetBitmapSize, CToolBarCtrl::SetButtonSize, CToolBarCtrl::AddString, CToolBarCtrl::AddStrings

CToolBarCtrl:: CheckButton

BOOL CheckButton( int nID , BOOL bCheck = TRUE );

返回值

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

参数

nID

要被核选或清除的按钮的命令标识符。

bCheck

如果是 TRUE 则核选该按钮，如果是 FALSE 则清除该按钮。

说明

此成员函数用来核选或清除工具条控件中的一个给定按钮。当一个按钮被核选时，它看起来就像被按下一样。如果你想改变多于一个的按钮状态，可以考虑调用 SetState 来代替。

请参阅 CToolBarCtrl::IsButtonChecked, CToolBarCtrl::EnableButton, CToolBarCtrl::PressButton, CToolBarCtrl::HideButton, CToolBarCtrl::Indeterminate,

CToolBarCtrl::GetState, CToolBarCtrl::SetState

CToolBarCtrl:: CommandToIndex

UINT CommandToIndex( UINT nID ) const;

返回值

返回与此命令 ID 相关联的按钮的从零开始的索引。

参数

nID

你想要查找其按钮索引的命令 ID 。

说明

此成员函数用来获取与指定的命令标识符相关联的按钮的从零开始的索引。

请参阅 CToolBarCtrl::SetCmdID, CToolBarCtrl::GetButton, CToolBarCtrl::AddButtons, CToolBarCtrl::InsertButton

CToolBarCtrl:: C reat

BOOL Create( DWORD dwStyle , const RECT& rect , CWnd* pParentWnd , UINT nID );

返回值

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

参数

dwStyle

指定工具条控件的风格。工具条必须总是具有 WS_CHILD 风格。另外，你可以为工具条指定在说明部分描述的工具条风格和窗口风格的任意组合。

rect

随意指定该工具条控件的尺寸和位置。它可以是一个 CRect 对象或一个

RECT 结构。

pParentWnd

指定工具条控件的父窗口。它不能是 NULL 。

nID

指定工具条控件的 ID 。

说明

构造一个 CToolBarCtrl 对象分两步。首先调用构造函数，然后调用 Create 来创建该工具条控件并将它与该 CToolBarCtrl 对象连接。

工具条控件自动设置工具条窗口的尺寸和位置。其高度依赖于工具条中的按钮的高度。其宽度与父窗口的客户区的宽度一样。 CCS_TOP 和 CCS_BOTTOM 风格决定了工具条是位于客户区的顶部还是底部。缺省的，一个工具条具有CCS_TOP 风格。

对一个工具条可以使用下面的窗口风格。

WS_CHILD 总是使用
WS_VISIBLE 经常使用
WS_DISABLED 很少使用

接着，你还可以使用一种或多种通用控件风格：

CCS_ADJUSTABLE 允许用户定制工具条。如果使用了这个

风格，则工具条的属主窗口必须处理由工具条发送的定制调整消息，就像在CToolBarCtrl：处理定制通知中描述的一样。
CCS_BOTTOM 使控件将自己定位在父窗口客户区的底部，

并将自己的宽度设置得与父窗口的宽度一样。
CCS_NODIVIDER 禁止在控件的顶部绘制两个像素的加亮。
CCS_NOHILITE 禁止在控件的顶部绘制一个像素的加亮。
CCS_NOMOVEY 使控件水平地，而不是垂直地调整自己的

尺寸和移动自

己，作为对一个 WM_SIZE 消息的响应。如果使用了 CCS_NORESIZE 风格，则这个风格就不适用了。

CCS_NOPARENTALIGN 禁止控件自动移动到父窗口的顶部或

底部。控件保持它在父窗口中的位置，不管父亲窗口的尺寸是怎么改变的。如果还使用了 CCS_TOP 或 CCS_BOTTOM 风格，则高度被调整为缺省值，但位置和宽度仍然保持不变。
CCS_NORESIZE 当设置控件的产生尺寸或新尺寸时，禁止

控件使用缺省的宽度和高度。控件使用在创建或改变大小时指定的宽度和高度。
CCS_TOP 使控件将自己定位在父窗口的客户区的顶部，

并将宽度设置为与父窗口的宽度一样。控件缺省的就具有这个风格。

最后，可以对控件或按钮本身使用工具条风格的一个组合。在 “ Platform SDK ” 中的 “ 工具条控件和按钮风格 ” 中描述了这些风格。

请参阅 CToolBarCtrl::CToolBarCtrl, CToolBarCtrl::SetButtonStructSize

CToolBarCtrl:: CToolBarCtrl

CToolBarCtrl( );

说明

此成员函数用来构造一个 CToolBarCtrl 对象。你必须调用 Create 来使工具条可用。

请参阅 CToolBarCtrl::Create

CToolBarCtrl:: Customize

void Customize( );

说明

此成员函数用来显示 Customize Toolbar 对话框。该对话框允许用户通过增加或删除按钮来定制工具条。

要支持定制，你的工具条的父窗口必须对定制通知消息作出处理，就象在CToolBarCtrl:: 处理定制通知中所描述的那样。你的工具条还必须使用CCS_ADJUSTABLE 风格创建，就象在 CToolBarCtrl::Create 中描述的那样。

请参阅 CToolBarCtrl::Handling Customization Notifications

CToolBarCtrl:: DeleteButton

BOOL DeleteButton( int nIndex );

返回值

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

参数

nIndex

要删除的按钮的从零开始的索引。

说明

此成员函数用来从工具条控件中删除一个按钮。

请参阅 CToolBarCtrl::AddButtons, CToolBarCtrl::AutoSize, CToolBarCtrl::InsertButton

CToolBarCtrl:: EnableButton

BOOL EnableButton( int nID , BOOL bEnable = TRUE );

返回值

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

参数

nID

要使其无效或有效的按钮的标识符。

bEnable

如果是 TRUE 则表示要使按钮有效；是 FALSE 表示要使按钮无效。

说明

此成员函数用来使一个工具条控件中的指定按钮有效或无效。当一个按钮已经是有效的时，它就可以被按下或核选。如果你想改变多于一个的按钮状态，可以考虑调用 SetState 。

请参阅 CToolBarCtrl::IsButtonEnabled, CToolBarCtrl::CheckButton, CToolBarCtrl::PressButton, CToolBarCtrl::HideButton, CToolBarCtrl::Indeterminate CToolBarCtrl::GetState, CToolBarCtrl::SetState

CToolBarCtrl:: GetAnchorHighlight

UINT GetBitmapFlags( ) const;

返回值

如果返回值是非零值，则可以进行定位加亮。如果返回的是零，则不能进行定位加亮。

说明

此成员函数用来实现 W in32 消息 TB_GETANCHORHIGHLIGHT ，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: SetAnchorHighlight

CToolBarCtrl:: GetBitmapFlags

UINT GetBitmapFlags( ) const;

返回值

如果显示可以支持大工具条位图，则返回具有 TBBF_LARGE 标志集的 UIN T ，否则就清除。

说明

此成员函数用来从工具条中获取位图标志。应该在创建工具条之后，但在向工具条添加位图之前调用这个函数。

返回值说明了显示是否支持大位图。如果显示支持大位图，并且你选择了使用它们，则在使用 AddBitmap 添加你的大位图之前，调用 SetBitmapSize 和SetButtonSize 。

CToolBarCtrl::SetButtonSize

CToolBarCtrl:: GetButton

BOOL GetButton( int nIndex , LPTBBUTTON lpButton ) const;

返回值

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

参数

nIndex

要获取其信息的按钮的从零开始的索引。

lpButton

用来接收按钮信息的拷贝的 TBBUTTON 结构的地址。参见

CToolBarCtrl::AddButtons 可以获得有关 TBBUTTON 结构的信息。

说明

此成员函数用来获取一个工具条控件中的指定按钮的信息。

请参阅 CToolBarCtrl::GetState, CToolBarCtrl::SetState,

dToIndex,CToolBarCtrl::AddButtons, CToolBarCtrl::InsertButton

CToolBarCtrl:: GetButtonCount

int GetButtonCount( ) const;

返回值

返回按钮的数目。

说明

此成员函数用来获取工具条控件中的当前按钮的数目。

请参阅 CToolBarCtrl::GetButton, CToolBarCtrl::GetState, CToolBarCtrl::GetItemRect, CToolBarCtrl::AddButtons, CToolBarCtrl::InsertButton , CToolBarCtrl::DeleteButton

CToolBarCtrl:: GetButtonInfo

BOOL GetButtonInfo( int nID , TBBUTTONINFO* ptbbi ) const;

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

参数

nID pbbi

说明

按钮的标识符。

一个指向 TBBUTTONINFO 结构的指针，该结构用来接收按钮的信息。

此成员函数用来实现 W in32 消息 TB_GETBUTTONINFO ，就像在 “ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl::SetButtonInfo CToolBarCtrl:: GetButtonSize DWORD GetButtonSize( ) const;

返回一个 DWORD 值，其 LOWORD 和 HIWORD 中分别包含了宽度和高度值。

说明

此成员函数用来获取一个工具条按钮的尺寸。

请参阅 CToolBarCtrl::GetButtonInfo

CToolBarCtrl:: GetDisabledImageList

CImageList* GetDisabledImageList( ) const;

返回值

返回一个指向 CImageList 对象的指针。如果没有被设置为无效的图像列表则返回 NULL 。

说明

此成员函数用来实现 W in32 消息 TB_GETDISABLEDIMAGELIST ，就像在“ Platform SDK ” 中描述的一样。

GetDisabledImageList 的 MFC 实现使用包含了工具条控件的按钮图像的

CImageList 对象，而不是使用一个图像列表的句柄。

请参阅 CToolBarCtrl::SetDisabledImageList, CToolBarCtrl::GetHotImageList, CToolBarCtrl::GetImageList

CToolBarCtrl:: GetDropTarget

HRESULT GetDropTarget( IDropTarget** ppDropTarget ) const;

返回值

返回一个 HRESULT 值，指明操作的成功或失败。

参数

ppDropTarget

一个指向 IDropTarget 接口指针的指针。如果发生了一个错误，则一个

NULL 指针将被放置在这个地址中。

说明

此成员函数用来实现 W in32 消息 TB_GETOBJECT ，就像在 “ Platform SDK ” 中描述的一样。

CToolBarCtrl:: GetExtendedStyle

DWORD GetExtendedStyle ( ) const;

返回值

返回一个代表此工具条控件中当前使用的扩展风格的结构。参见 “ Platform SDK ” 中的 “ 工具条扩展风格 ” 可以获得风格的列表。

说明

此成员函数用来实现 W in32 消息 TB_GETEXTENDEDSTYLE ，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl::SetExtendedStyle

CToolBarCtrl:: GetHotImageList

CImageList* GetHotImageList( ) const;

返回值

返回一个指向 CImageList 对象的指针，如果没有被设置为无效的图像列表则返回 NULL 。

说明

此成员函数用来实现 W in32 消息 TB_GETHOTIMAGELIST ，就像在 “ Platform SDK ” 中描述的一样。

当鼠标指针位于一个热点按钮上时，该按钮被加亮显示。

请参阅 CToolBarCtrl::GetDisabledImageList, CToolBarCtrl::GetImageList

CToolBarCtrl:: GetHotItem

int GetHotItem( ) const;

返回值

返回一个工具条中的热点项的从零开始的索引。

说明

此成员函数用来实现 W in32 消息 TB_GETHOTITEM ，就像在 “ Platform SDK ” 中描述的一样。

CToolBarCtrl:: GetImageList

CImageList* GetImageList ( ) const;

返回值

返回一个指向 CImageList 对象的指针，如果没有被设置为无效的图像列表则返回 NULL 。

说明

此成员函数用来实现 W in32 消息 TB_GETIMAGELIST ，就像在“ Platform SDK ” 中描述的一样。

CToolBarCtrl:: GetInsertMark

void GetInserMark ( TBINSERTMARK* ptbim ) const;

参数

ptbim

一个指向 TBINSERTMARK 结构的指针，该结构用来接收插入标记。

说明

此成员函数用来实现 W in32 消息 TB_GETINSERTMARK ，就像在 “ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl::SetInsertMark

CToolBarCtrl:: GetInsertMarkColor

COLORREF GetInsertMarkColor( ) const;

返回值

返回一个包含当前插入标记的颜色的 COLORREF 值。

说明

此成员函数用来实现 W in32 消息 TB_GETINSERTMARKCOLOR ，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl::SetInsertMarkColor

BOOL GetItemRect( int nIndex , LPRECT lpRect ) const;

返回值

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

参数

nIndex

要获取其信息的按钮的从零开始的索引。

lpRect

一个用来接收边界矩形的坐标的 RECT 结构或 CRect 对象的地址。

说明

此成员函数用来接收工具条控件中的一个按钮的边界矩形。此函数不接收状态被设置为 TBSTATE_HIDDEN 的按钮的边界矩形。

请参阅 CToolBarCtrl::GetButton, CToolBarCtrl::GetButtonCount, CToolBarCtrl::GetState, CToolBarCtrl::SetButtonSize, CToolBarCtrl::SetBitmapSize

BOOL GetMaxSize ( LPSIZE pSize ) const;

返回值

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

参数

pSize

一个指向用来接收项的尺寸的 SIZE 结构的指针。

说明

此成员函数用来实现 W in32 消息 TB_GETMAXSIZE ，就像在 “ Platform SDK ” 中描述的一样。

CToolBarCtrl:: GetMaxTextRows

int GetMaxTextRows ( ) const;

返回一个工具条按钮上显示的文本的最大行数。

说明

此成员函数用来获取一个工具条按钮上显示的文本的最大行数。

请参阅 CToolBarCtrl:: SetMaxTextRows

CToolBarCtrl:: GetRect

BOOL GetRect( int nID , LPRECT lpRect ) const;

返回值

如果成功则返回 TRU E ；否则返回 FALSE 。

参数

nID

按钮标识符。

lpRect

一个指向用来接收边界矩形信息的 RECT 结构的指针。

此成员函数用来实现 W in32 消息 TB_GETRECT ，就像在 “ Platform SDK ” 中描述的一样。

CToolBarCtrl:: GetRows

int GetRows( ) const;

返回值

返回工具条中当前显示的按钮的行数。

说明

此成员函数用来获取工具条控件中当前显示的按钮的行数。注意，除非工具条是用 TBSTYLE_WRAPABLE 风格创建的，否则行数总是 1 。

请参阅 TBSTYLE_WRAPABLE in CToolBarCtrl::Create, CToolBarCtrl::SetRows

CToolBarCtrl:: GetState

int GetState( int nID ) const;

返回值

如果成功则返回按钮的状态信息；否则返回 -1 。按钮的状态信息可以是在

CToolBarCtrl::AddButtons 中所列出的值的一个组合。

参数

nID

要获取其信息的按钮的命令标识符。

说明

此成员函数用来获取有关一个工具条控件中的指定按钮的状态的信息，比如它是否是有效，被按下，或被核选。

如果你要处理多于一个的按钮状态，则这个函数是特别方便的。如果只需要获取一个状态，则可以使用下列成员函数： IsButtonEnabled ， IsButtonChecked ， IsButtonPressed ， IsButtonHidden ，或 IsButtonIndeterminate 。但是， GetState 成员函数是检测 TBSTATE_WRAP 按钮状态的唯一方法。

请参阅 CToolBarCtrl::SetState, CToolBarCtrl::GetItemRect, CToolBarCtrl::IsButtonEnabled, CToolBarCtrl::IsButtonChecked,

CToolBarCtrl::IsButtonPressed, CToolBarCtrl::IsButtonHidden, CToolBarCtrl::IsButtonIndeterminate

CToolBarCtrl:: GetStyle

DWORD GetStyle( ) const;

返回值

返回一个包含了工具条控件风格的一个组合的 DWORD ，就像 “ Platform SDK ” 中描述的一样。

说明

此成员函数用来获取一个工具条控件当前使用的风格。

请参阅 CToolBarCtrl::SetStyle

CToolBarCtrl:: GetToolTips

CToolTipCtrl* GetToolTips( ) const;

返回值

返回指向一个与工具条相关联的 CToolTipCtrl 对象的指针。如果该工具条没有关联的工具提示控件，则返回 NULL 。

说明

此成员函数用来获取与工具条控件相关联的工具提示控件（如果有的话）的句柄。由于工具条控件通常会创建并维护它自己的工具提示控件，所以大多数程序不需要调用这个函数。

请参阅 CToolBarCtrl::SetToolTips, CToolBarCtrl: Handling Tool Tip Notifications, CToolTipCtrl

CToolBarCtrl:: H itTest

int HitTest( LPPOINT ppt ) const;

返回值

返回一个指明了工具条上的一个点的位置的整数值。如果这个值是零或正值，则这个返回值表示的是该点所在的非分隔线项的从零开始的索引。

如果返回值是负值，则该点不在一个按钮中。该返回值的绝对值是一个分隔线或最近的非分隔线项的索引。

参数

ppt

一个指向 POINT 结构的指针，该结构的 x 成员包含了点击测试的 x 坐标，其 y 成员包含了点击测试的 y 坐标。这个坐标是相对于工具条的客户区的。

说明

此成员函数用来实现 W in32 消息 TB_HITTEST 的行为，就像在“ Platform SDK ” 中描述的一样。

CToolBarCtrl:: H ideButton

BOOL HideButton( int nID , BOOL bHide = TRUE );

返回值

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

参数

nID

要被显示或隐藏的按钮的命令标识符。

bHide

如果是 TRUE 则隐藏此按钮，是 FALSE 则显示此按钮。

此成员函数用来隐藏或显示一个工具条控件中的指定按钮。如果你想改变多于一个的按钮状态，则可以考虑调用 SetState 来代替。

请参阅 CToolBarCtrl::IsButtonHidden, CToolBarCtrl::EnableButton, CToolBarCtrl::CheckButton,CToolBarCtrl::PressButton,ToolBarCtrl::Ind eterminate, CToolBarCtrl::GetState, CToolBarCtrl::SetState

CToolBarCtrl:: Indeterminate

BOOL Indeterminate( int nID , BOOL bIndeterminate = TRUE );

返回值

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

参数

nID

要清除或设置其不确定状态的按钮的命令标识符。

bIndeterminate

如果是 TRUE 则设置指定按钮的不确定状态，是 FALSE 则清除它。

此成员函数用来设置或清除一个工具条控件中的指定按钮的不确定状态。不确定的按钮被显示为灰色，例如，当一个字处理器中被选择的文本同时包含加粗的或正常的字符时，该处理器中的工具条上的加粗按钮就显示为灰色。

如果你希望改变多于一个的按钮状态，可以考虑调用 SetState 来代替。请参阅 Button styles in CToolBarCtrl::AddButtons, CToolBarCtrl::IsButtonIndeterminate, CToolBarCtrl::EnableButton,CToolBarCtrl::CheckButton,

CToolBarCtrl::PressButton,CToolBarCtrl::HideButton, CToolBarCtrl::GetState, CToolBarCtrl::SetState

CToolBarCtrl:: InsertButton

BOOL InsertButton( int nIndex , LPTBBUTTON lpButton );

返回值

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

nIndex

一个按钮的从零开始的索引。此函数将一个新按钮插入到这个按钮的左

边。

lpButton

一个包含要被插入的按钮的信息的 TBBUTTON 结构的指针。参见

CToolBarCtrl:: AddButtons 可以获得有关 TBBUTTON 结构的描述。

说明

此成员函数用来在一个工具条控件中插入一个按钮。

你提供的图像和 / 或字符串的索引必须是先前通过调用 AddBitmap ， AddString

和 /或 AddStrings 已经添加到工具条控件的列表中去了的值。

请参阅 CToolBarCtrl::AddButtons, CToolBarCtrl::DeleteButton, CToolBarCtrl::AddBitmap, CToolBarCtrl::AddString, CToolBarCtrl::AddStrings

CToolBarCtrl:: InsertMarkHitest

BOOL InsertMarkHitTest( LPPOINT pp t, LPTBINSERTMARK ptbim ) const;

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

参数

ppt

区。

一个指向包含点击测试坐标的 POINT 结构，该坐标相对于工具条的客户

ptbim

一个指向用来接收插入标记信息的 TBINSERTMARK 结构的指针。

说明

此成员函数用来实现 W in32 消息 TB_INSERTMARKHITTEST 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: GetInsert M ark, CToolBarCtrl:: SetInsert M ark

CToolBarCtrl:: IsButtonChecked

BOOL IsButtonChecked( int nID ) const;

如果按钮被核选则返回非零值；否则返回零。

参数

nID

工具条中的按钮的命令标识符。

说明

此成员函数用来确定一个工具条控件中的指定按钮是否被核选。如果你要获取多于一个的按钮状态，考虑调用 GetState 。

请参阅 CToolBarCtrl::CheckButton, CToolBarCtrl::GetState, CToolBarCtrl::SetState, CToolBarCtrl::IsButtonEnabled,

CToolBarCtrl::IsButtonPressed, CToolBarCtrl::IsButtonHidden, CToolBarCtrl::IsButtonIndeterminate

CToolBarCtrl:: IsButtonEnabled

BOOL IsButtonEnabled( int nID ) const;

如果按钮是有效的则返回非零值；否则返回零。

参数

nID

工具条中的按钮的命令标识符。

说明

此成员函数用来确定一个工具条控件中的指定按钮是否是有效的。如果你要获取多于一个的按钮状态，考虑调用 GetState 。

请参阅 CToolBarCtrl::EnableButton, CToolBarCtrl::GetState, CToolBarCtrl::SetState, CToolBarCtrl::IsButtonChecked,

CToolBarCtrl::IsButtonPressed, CToolBarCtrl::IsButtonHidden,CToolBarCtrl::IsButtonIndeterminate ,CToolBarCtrl::

IsButtonHighlighted

CToolBarCtrl:: IsButtonHidden

BOOL IsButtonHidden( int nID ) const;

如果按钮被隐藏则返回非零值；否则返回零。

参数

nID

工具条中的按钮的命令标识符。

说明

此成员函数用来确定一个工具条控件中的指定按钮是否是隐藏的。如果你要获取多于一个的按钮状态，考虑调用 GetState 。

请参阅 CToolBarCtrl::HideButton, CToolBarCtrl::GetState, CToolBarCtrl::SetState, CToolBarCtrl::IsButtonEnabled,

CToolBarCtrl::IsButtonChecked, CToolBarCtrl::IsButtonPressed,CToolBarCtrl::IsButtonIndeterminate ,CToolBarCtrl::

IsButtonHighlighted

CToolBarCtrl:: IsButtonHighlighted

Bool IsButtonHighlighted( int nID ) const;

如果按钮被加亮则返回非零值；否则返回 0 。

参数

nID

工具条中的按钮的命令标识符。

说明

此成员函数用来检查一个工具条控件中的指定按钮是否处于加亮状态。

请参阅 CToolBarCtrl:: IsButtonChecked, CToolBarCtrl:: IsButtonIndeterminate, CToolBarCtrl:: IsButtonHidden, CToolBarCtrl:: IsButtonEnabled, CToolBarCtrl:: IsButtonPressed, CToolBarCtrl:: MarkButton

CToolBarCtrl:: IsButtonIndeterminate

BOOL IsButtonIndeterminate( int nID ) const;

返回值

如果按钮处于不确定状态则返回非零值；否则返回零。

nID

工具条中的按钮的命令标识符。

说明

此成员函数用来确定一个工具条控件中的指定按钮是否是不确定的。不确定按钮被显示成灰色，例如，当一个字处理器中被选择的文本同时包含加粗的或正常的字符时，该处理器中的工具条上的加粗按钮就显示为灰色。

如果你要获取多于一个的按钮状态，考虑调用 GetState 。

请参阅 CToolBarCtrl:: Indeterminate, CToolBarCtrl:: GetState, CToolBarCtrl:: SetState CToolBarCtrl:: IsButtonEnabled,

CToolBarCtrl:: IsButtonChecked, CToolBarCtrl:: IsButtonPressed, CToolBarCtrl:: IsButtonHidden, CToolBarCtrl:: IsButtonHighlighted

CToolBarCtrl:: IsButtonPressed

BOOL IsButtonPressed( int nID ) const;

如果按钮被按下则返回非零值，否则返回零。

参数

nID

工具条中的按钮的命令标识符。

说明

此成员函数用来确定一个工具条控件中的指定按钮是否被按下。如果你要获取多于一个的按钮状态，考虑调用 GetState 。

请参阅 CToolBarCtrl::PressButton, CToolBarCtrl::GetState, CToolBarCtrl::SetState, CToolBarCtrl::IsButtonEnabled,

CToolBarCtrl::IsButtonChecked, CToolBarCtrl::IsButtonHidden,CToolBarCtrl::IsButtonIndeterminate ,CToolBarCtrl::

IsButtonHighlighted

CToolBarCtrl:: LoadImages

void LoadImages( int iBitmapID , HINSTANCE hinst );

iBitmapID

包含要装入的图像的位图的 ID 。要指定你自己的位图资源，可以将这个参数设置为一个位图资源的 ID ，并将 hInst 设置为 NULL 。你的位图资源将被添加到图像列表作为一个单一的图像。你可以通过将 hinst 设置为HINST_COMMCTRL ，将这个参数设置为下列 ID 值之一，来添加标准的，系统定义的位图：

位图 ID 描述

IDB_HIST_LARGE_COLOR 大尺寸的探测位图IDB_HIST_SMALL_COLOR 小尺寸的探测位图IDB_STD_LARGE_COLOR 大尺寸的标准位图IDB_STD_SMALL _ COLOR 小尺寸的标准位图IDB_VIEW_LARGE_COLOR 大尺寸的视位图IDB_VIEW_SMALL_COLOR 小尺寸的视位图

hinst

指向调用应用程序的程序示例句柄。这个参数这个参数可以是

HINST_COMMCTRL ，用来加载一个标准的图像列表。

此成员函数用来实现 W in32 消息 TB_LOADIMAGES 的行为，就象在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: SetImageList, CToolBarCtrl:: GetImageList

CToolBarCtrl:: MapAccelerator

BOOL MapAccelerator ( TCHAR chAccel , UINT* pIDBtn );

返回值

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

参数

chAccel

要被映射的加速键字符。这个字符与按钮文本中的加下划线的字符是一样

的。

pIDBtn

一个指向用来接收某个按钮的命令标识符的 UINT 的指针。此按钮用来响应在 chAccel 中指定的加速键。

此成员函数用来实现 W in32 消息 TB_MAPACCELERATOR 的行为，就像在“ Platform SDK ” 中描述的一样。

CToolBarCtrl:: MarkButton

BOOL MardButton( int nID , BOOL fHighlight = TRUE );

返回值

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

参数

nID

按钮标识符。

fH ighlight

指定要设置的加亮状态。缺省的，这个值是 TRUE 。如果将其设置为

FALSE ，则此按钮被设置为它的缺省状态。

此成员函数用来实现 W in32 消息 TB_MARKBUTTON 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: IsButtonHighlighted

CToolBarCtrl:: MoveButton

BOOL MoveButton( UINT nOldPos , UINT nNewPos );

返回值

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

参数

nOldPos

要被移动的按钮的从零开始的索引。

nNewPos

按钮的终点的从零开始的索引。

此成员函数用来实现 W in32 消息 TB_MOVEBUTTON 的行为，就像在“ Platform SDK ” 中描述的一样。

CToolBarCtrl:: PressButton

BOOL PressButton( int nID , BOOL bPress = TRUE );

返回值

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

参数

nID

要被按下或释放的按钮的命令标识符。

bPress

如果是 TRUE 则按下指定的按钮；如果是 FLASE 则释放指定按钮。

说明

此成员函数用来按下或释放一个工具条控件中的指定按钮。如果你要改变多于

个的按钮状态，可以考虑调用 SetState 来代替。

请参阅 CToolBarCtrl::IsButtonPressed, CToolBarCtrl::EnableButton, C ToolBarCtrl::CheckButton,CToolBarCtrl::HideButton, CToolBarCtrl::Indeterminate,

CToolBarCtrl::GetState, CToolBarCtrl::SetState

CToolBarCtrl:: RestoreState

void RestoreState( HKEY hKeyRoot , LPCTSTR lpszSubKey , LPCTSTR

lpszValueNam e);

参数

hKeyRoot

表示注册表中的一个当前打开的主键，或是下列预定义的保留句柄值的任何一个：

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpszSubKey

指向一个以空字符结尾的字符串，该字符串包含了与某个值关联的子键

的名字。这个参数可以是空或是一个指向空字符串的指针。如果这个参数是 NULL ，则该值被添加到由 hKeyRoot 参数指定的主键中。

lpszValueName

指向一个包含要获取的值的名字的字符串。如果这个名字的值在主键中没有给出，则函数将它添加到该主键中。

说明

此成员函数从参数所指定的注册表中的位置恢复工具条控件的状态。

请参阅 CToolBarCtrl::SaveState

CToolBarCtrl:: SaveState

void SaveState( HKEY hKeyRoo t, LPCTSTR lpszSubKey , LPCTSTR

lpszValueName );

参数

hKeyRoot

表示注册表中的一个当前打开主键，或是下列预定义的保留句柄值的任何一个：

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpszSubKey

指向一个以空字符结尾的字符串，该字符串包含了与某个值关联的子键的名字。这个参数可以是空或是一个指向空字符串的指针。如果这个参数是 NULL ，则该值被添加到由 hKeyRoot 参数指定的主键中。

lpszValueName

指向一个包含要获取的值的名字的字符串。如果这个名字的值在主键中没有给出，则函数将它添加到该主键中。

说明

此成员函数用来将工具条控件的状态保存到由参数指定的注册表中的位置。

请参阅 CToolBarCtrl::RestoreState

CToolBarCtrl:: SetAnchorHighlight

BOOL SetAnchorHighlight( BOOL fAnchor = TRUE );

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

参数

fAnchor

指示定位加亮是否有效。如果这个值是非零值，则定位加亮将是有效的。如果这个值是零，则不允许定位加亮。

说明

此成员函数用来实现 W in32 消息 TB_SETANCHORHIGHLIGHT 的行为，就像在 “ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: GetAnchorHighlight

CToolBarCtrl:: SetBitmapSize

BOOL SetBitmapSize( CSize size );

返回值

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

size

位图图像的以像素表示的宽度和高度。

说明

此成员函数用来设置要被添加到一个工具条控件中的实际位图图像的尺寸。

只有在向工具条中添加位图之前才调用这个函数。如果应用程序不显式地设置位图的尺寸，则它的缺省值为 16 × 15 像素。

请参阅 CToolBarCtrl::SetButtonSize, CToolBarCtrl::GetItemRect

CToolBarCtrl:: SetButtonInfo

BOOL SetButtonInfo( int nID , TBBUTTONINFO* ptbbi );

返回值

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

参数

nID

按钮标识符。

ptbbi

一个指向用来接收按钮信息的 TBBU T T ONINFO 结构的指针。

说明

此成员函数用来实现 W in32 消息 TB_SETBUTTONINFO 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: GetButtonInfo

CToolBarCtrl:: SetButtonSize

BOOL SetButtonSize( CSize size );

返回值

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

参数

size

按钮的以像素表示的宽度和高度。

说明

此成员函数用来设置工具条控件中的按钮的尺寸。按钮的尺寸必须总是至少与它所装入的位图的尺寸一样。

只有在向工具条中添加位图之前才调用这个函数。如果应用程序不显式地设置按钮的尺寸，则它的缺省值为 24 × 22 像素。

请参阅 CToolBarCtrl::SetBitmapSize, CToolBarCtrl::GetItemRect

CToolBarCtrl:: SetButtonStructSize

void SetButton Struc tSize( int n size );

参数

n size

说明

TBBUTTON 结构的以字节数表示的尺寸。

此成员函数用来指定 TBBUTTON 结构的大小。如果你想在 TBBUTTON 结构中保存额外的数，你可以从 TBBUTTON 派生一个新的结构，增加你需要的成员，或者创建一个新的结构，该结构包含一个 TBBUTTON 结构作为它的第一

个成员。然后你可以调用这个函数来向工具条控件给出此新结构的大小。

参见 CToolBarCtrl::AddButtons 可以获得有关 TBBUTTON 结构的更多信息。

请参阅 CToolBarCtrl:: Create,CToolBarCtarl::AddButtons CToolBarCtrl::InsertButton,CToolBarCtrl::GetButton

CToolBarCtrl:: SetButtonWidth

BOOL SetButtonWidth( int cxMin , int cxMax );

返回值

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

参数

cxMin

以像素表示的最小按钮宽度。工具条按钮的宽度不能小于这个值。

cxMax

以像素表示的最大按钮宽度。如果按钮文本太宽，则控件用省略的点来显式它。

此成员函数用来实现 W in32 消息 TB_SETBUTTONWIDTH 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: SetButtonInfo

CToolBarCtrl:: SetCmdID

BOOL SetCmdID( int nIndex , UINT nID );

返回值

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

参数

nIndex

要设置其命令 ID 的按钮的从零开始的索引。

nID

要给选定的按钮设置的命令 ID 。

此成员函数用来设置指定按钮的命令标识符，当该按钮被按下时，此命令标识符将被发送给属主窗口。

请参阅 CToolBarCtrl::CommandToIndex, CToolBarCtrl::GetButton, CToolBarCtrl::AddButtons, CToolBarCtrl::InsertButton

CToolBarCtrl:: SetDisabledImageList

CImageList* SetDisabledImageList( CImageList* pImageList );

返回值

一个指向 CImageList 对象的指针，该对象先前被工具条控件用来显示无效按钮图像。

参数

pImageList

一个指向 CImageList 对象的指针，该对象包含了要被工具条控件用来显示无效按钮图像的图像。

此成员函数用来实现 W in32 消息 TB_SETDISABLEDIMAGELIST 的行为，就像在 “ Platform SDK ” 中描述的一样。

SetDisabledImageList 的 MFC 实现使用的是一个包含工具条控件的无效按钮图像的 CImageList 对象，而不是一个图像列表句柄。

请参阅 CToolBarCtrl:: GetDisabledImageList, CToolBarCtrl:: SetHotImageList, CToolBarCtrl:: SetimageList

CToolBarCtrl:: SetDrawTextFlages

DWORD SetDrawTextFlage( DWORD dwMask , D W O R D dwDTFlags );

返回值

返回一个包含先前的文本绘制标志的 DWORD 。

参数

dwMask

在 W in32 函数 D rawText 中指定的一个或多个 DT_ 标志的组合。该组合说明了在绘制文本时使用 dwDTFlags 中的哪些位。

dwDTFlags

在 W in32 函数 D rawText 中指定的一个或多个 DT_ 标志的组合。该组合表明如何绘制按钮文本。当按钮文本被绘制时，这个值被传递给DrawTex t。

说明

此成员函数用来实现 W in32 消息 TB_SETDRAWTEXTFLAGS 的行为，就像在“ Platform SDK ” 中描述的一样。

此成员函数用来设置 W in32 函数 DrawText 中的标志。该函数用来绘制指定矩形中的文本，根据所设置的标志来格式化字符串。

CToolBarCtrl:: SetExtendedStyle

DWORD SetExtendedStyle( DWORD dwExStyle ) const;

返回值

返回一个代表先前的扩展风格的 DWORD 。参见 “ Platform SDK ” 中的 “ 工具条扩展风格 ” 可以获得风格的列表。

参数

dwExStyle

指定新的扩展风格的值。这个参数可以是工具条风格的一个组合。

说明

此成员函数用来实现 W in32 消息 TB_SETEXTENDEDSTYLE 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: GetExtendedStyle

CToolBarCtrl:: SetHotImageList

CImageList* SetHotImageList( CImageList* pImageList );

返回值

返回一个指向 CImageList 对象的指针，该对象先前被工具条控件用来显示热点按钮图像。

参数

pImageList

一个指向 CImageList 对象的指针，该对象包含的图像将被工具条控件用来显示热点按钮图像。

说明

此成员函数用来实现 W in32 消息 TB_SETHOTIMAGELIST 的行为，就像在“ Platform SDK ” 中描述的一样。

SetHotImageList 的 MFC 实现使用的是一个包含工具条控件的热点按钮图像的

CImageList 对象，而不是一个图像列表句柄。

当指针位于一个热点按钮上时，该按钮将被加亮显示。

请参阅 CToolBarCtrl:: GetHotImageList, CToolBarCtrl:: SetDisabledImageList, CToolBarCtrl:: SetImage L ist

CToolBarCtrl:: Set H otItem

int SetHotItem( int nHot );

返回值

返回先前的热点项的索引，如果没有热点项则返回 -1 。

nHot

将要被变成热点的项的从零开始的索引号。如果这个值是 -1 ，则没有一个项将被变成热点。

说明

此成员函数用来实现 W in32 消息 TB_SETHOTITEM 的行为，就像在 “ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: GetHotItem

CToolBarCtrl:: SetImageList

CImageList* Set ImageList( CImageList* pImageList );

返回值

返回一个指向 CImageList 对象的指针，该对象先前被工具条控件用来显示处于缺省状态的按钮图像。

pImageList

一个指向 CImageList 对象的指针，该对象包含的图像将被工具条控件用来显示缺省状态按钮图像。

说明

此成员函数用来实现 W in32 消息 TB_SETIMAGELIST 的行为，就像在“ Platform SDK ” 中描述的一样。

SetImageList 的 MFC 实现使用的是一个包含工具条控件的缺省状态按钮图像的

CImageList 对象，而不是一个图像列表句柄。

请参阅 CToolBarCtrl:: GetImageList, CToolBarCtrl:: SetDisabledImageList, CToolBarCtrl:: SetHotImageList

CToolBarCtrl:: SetIndent

BOOL Se t Indent( int iIndent );

返回值

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

iIndent

这个值指定了以像素表示的缩进。

说明

此处于函数用来设置一个工具条控件中的第一个按钮的缩进。

CToolBarCtrl:: SetInsertMark

void SetInsert M ark ( TBINSERTMARK* ptbim )

参数

ptbim

一个指向包含插入标记的 TBINSERTMARK 结构的指针。

说明

此成员函数用来实现 W in32 消息 TB_SETINSERTMARK 的行为，就像在“ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: GetInsert M ark

CToolBarCtrl:: SetInsertMarkColor

COLORREF SetInsertMarkColor( COLORREF clrNew );

返回值

返回一个包含先前的插入标记颜色的 COLORREF 值。

参数

clrNew

一个包含新的插入标记颜色的 COLORREF 值。

说明

此成员函数用来实现 W in32 消息 TB_SETINSERTMARKCOLOR 的行为，就像在 “ Platform SDK ” 中描述的一样。

请参阅 CToolBarCtrl:: Get Insert M arkColor

CToolBarCtrl:: SetMaxTextRows

BOOL SetMaxTextRows( int iMaxRows );

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

参数

iMaxRows

要设置的最大行数。

说明

此成员函数用来设置显示在一个工具条按钮中的文本的最大行数。

请参阅 CToolBarCtrl:: GetMaxTextRows

CToolBarCtrl:: SetOwner

void SetOwner( CWnd* pWnd );

参数

pWnd

指向将要成为工具条控件的新属主窗口的 CWnd 或 CWnd 派生对象的指

此成员函数用来为工具条控件设置属主窗口。属主窗口是接收来自该工具条的通知的窗口。

请参阅 CToolBarCtrl::Create

CToolBarCtrl:: SetRows

void SetRows( int nRows , BOOL bLarger , LPRECT lpRect );

参数

nRows

需要的行数。

bLarger

如果工具条不能调整到需要的行数，此参数指明是使用更多的行还是使用更少的行。

lpRect

指向 CRect 对象或 RECT 结构，该对象或结构用来接收工具条的新的边界矩形。

此成员函数用来请求工具条控件将它自己调整为需要的行数。

如果该工具条不能将自己调整为需要的行数，则它将根据 bLarger 的值把自己调整为下一个较大的或较小的尺寸。如果 bLarger 是 TRU E ，则新行数将大于请求的行数。如果 bLarger 是 FALSE ，则新行数将小于请求的行数。

如果按钮可以被安排为给定的行数，则该给定值是有效的，并且所有行都具有相同的按钮数（可能除了最后一行）。例如，一个包含四个按钮的工具条不能被调整为三行，因为这样的安排将使最后两行都较短。如果你尝试要将它调整为三行，则如果 bLarge 是 TRU E ，则得到的是四行，如果 bLarger 是 FALSE ，则得到的是两行。

如果工具条中有分隔线，则有关何时给定行数有效的规则就更复杂了。按钮的安排可以这样考虑：按钮组（组中的第一个按钮之前和最后一个按钮之后都有分隔线）不会被分行排列，除非它们不能在一行中安排。

如果一个组不能正好占据完一行，则下一个组将从下一个行开始，即使是这个组可以在上一个大组结束的行中完全安排。这个规则的目的就是使两个大组之间的分隔更加显而易见。这样导致的垂直分隔线被作为行计算。

还要注意， SetRows 成员函数将总是选择会获得最小的工具条尺寸的版面规划。创建一个具有 TBSTYLE_WRAPABLE 风格的工具条，然后调整这个控件将只是简单地根据给定的控件宽度应用这个方法来画出轮廓。

只有使用 TBSTYLE_WRAPABLE 风格创建的函数才可以调用这个函数。

请参阅 Toolbar styles in CToolBarCtrl::Create, CToolBarCtrl::GetRows

CToolBarCtrl:: SetState

BOOL SetState( int nID , UINT nState );

返回值

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

参数

nID

按钮的命令标识符。

nState

状态标志。它可以是 CToolBarCtrl::AddButtons 中列出的按钮状态值的一个组合。

说明

此成员函数用来设置一个工具条控件中的指定按钮的状态。

如果你想要设置多于一个的按钮状态，这个函数是特别方便的。如果只要设置一个状态，可以使用下列的成员函数： EnableButton ， CheckButton ， H ideButton ， Indeterminate ，或 PressButton 。

请参阅 CToolBarCtrl::GetState, CToolBarCtrl::AddButtons,

CToolBarCtrl::EnableButton, CToolBarCtrl::CheckButton,CToolBarCtrl::HideButton, CToolBarCtrl::Indeterminate,CToolBarCtrl::PressButton

CToolBarCtrl:: SetStyle

void SetStyle( DWORD dwStyle );

参数

dwStyle

一个包含工具条控件风格的组合的 DWORD ，就像在 “ Platform SDK ” 中描述的一样。

说明

此成员函数用来设置一个工具条控件的风格。

请参阅 CToolBarCtrl:: GetStyle

CToolBarCtrl:: SetToolTips

void SetToolTips( CToolTipCtrl* pTip );

参数

pTip

说明

指向一个 CToolTipCtrl 对象的指针。

此成员函数用来使一个工具提示控件与一个工具条控件相关联。

请参阅 CToolBarCtrl::GetToolTips, CToolBarCtrl: Handling Tool Tip Notifications, CtoolTipCtrl

CToolBarCtrl

CToolBarCtrl

CToolBarCtrl 类 成 员

Construction

Attributes

CToolBarCtrl ： 处 理 工 具 提 示 通 知

通 知 消 息 含义

CToolBarCtrl ： 处 理 定 制 通 知

成 员 函 数

位图 ID 描述

CToolBarCtrl 类成员

CToolBarCtrl ：处理工具提示通知

通知消息含义

CToolBarCtrl ：处理定制通知

成员函数