CToolBarCtrl基本内容控件
基本内容CToolBarCtrl
| CObject |
| └CCmdTarget |
| └CWnd |
| └CToolBarCtrl |
CToolBarCtrl类提供了Windows工具条通用控件的性能。这个控件（也就是CToolBarCtrl类）只对运行在Windows 95和Windows NT 3.51或更高版本下的程序来说才是可用的。
一个Windows工具条通用控件是一个矩形子窗口，它包含一个或多个按钮。这些按钮可以显示一个位图图像，一个字符串，或两者都有。当用户选择一个按钮时，它向该工具条的属主窗口发送一条命令消息。通常，工具条中的按钮对应于应用程序的菜单中的项；这些按钮为用户访问一个应用程序的命令提供了更为直接的方法。
CToolBarCtrl对象包含几个重要的内部数据结构：一个按钮图像列表或一个图像列表，一个按钮标签字符串列表和一个TBBUTTON结构的列表，该结构使一个图像和/或字符串与按钮的位置，风格，主题和命令ID相关联。这些数据结构的每一个都由一个从零开始的索引来引用。在你可以使用一个CToolBarCtrl对象之前，你必须设置这些数据结构。字符串列表只能被用作按钮标签；不能从按钮中检取字符串。
要使用一个CToolBarCtrl对象，通常你应该遵循下面的这些步骤：
| 1. | 构造该CToolBarCtrl对 象。 |
| 2. | 调用Create来创建Windows工具条通用控件并将它与该CToolBarCtrl对象连接。通过使用风格来指定工具条的风格，如对一个透明的工具条使用TBSTYLE_ TRANSPARENT，或对一个支持风格按钮的工具条使用TBSTYLE_DROPDOWN。 |
| 3. | 指明你希望按钮在工具条上如何显示： · 给按钮使用位图图像，通过调用AddBitmap将按钮位图添加到工具条中。 · 给按钮使用来自一个图像列表的图像，通过调用SetImageList，SetHotImageList，或SetDisabledImageList来指定图像列表。 · 给按钮使用字符串标签，通过调用AddString和/或AddStrings来将字符串添加到工具条中。 |
| 4. | 通过调用AddButtons将按钮结构添加到工具条中。 |
| 5. | 如果你希望在一个不是CFrameWnd的属主窗口中的工具条具有工具提示，则你必须在工具条的属主窗口中处理TTN_NEEDTEXT消息，就像在CToolBarCtrl：处理工具提示通知中描述的一样。如果工具条的父窗口是由CFrameWnd派生而来的，则你不用作任何额外的努力就可以显示工具提示，因为CFrameWnd提供了一个缺省的处理函数。 |
| 6. | 如果你希望能够让用户定制工具条，则在属主窗口中处理定制通知消息，就像在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类成员
构造
| CToolBarCtrl | 构造一个CToolBarCtrl对象 |
| Create | 创建一个工具条控件并将它与一个CToolBarCtrl对象连接 |
属性
| IsButtonEnabled | 指示一个工具条控件中的指定按钮是否是有效的 |
| IsButtonChecked | 指示一个工具条控件中的指定按钮是否被核选了 |
| IsButtonPressed | 指示一个工具条控件中的指定按钮是否被压住 |
| IsButtonHidden | 指示一个工具条控件中的指定按钮是否被隐藏 |
| IsButtonIndeterminate | 指示一个工具条控件中的指定按钮的状态是否是不确定的（灰的） |
| SetState | 设置一个工具条控件中的指定按钮的状态 |
| GetState | 获取关于一个工具条控件中的指定按钮的状态的信息，比如它是有效的、被压住的，或是被核选的 |
| GetButton | 获取一个工具条控件中的指定按钮的信息 |
| GetButtonCount | 获取当前在该工具条控件中的按钮的数目 |
| GetItemRect | 获取一个工具条控制中的按钮的边界矩形 |
| GetRect | 获取一个特定工具条按钮的边界矩形 |
| SetButtonStructSize | 指定TBBUTTON结构的大小 |
| GetButtonSize | 获取的像素表示的工具条按钮当前宽度和高度 |
| SetButtonSize | 设置要被添加到一个工具条控件中去的按钮的尺寸 |
| SetBitmapSize | 设置要被添加到一个工具条控件中去的位图图像的尺寸 |
| GetToolTips | 获取与此工具条控件相关联的工具提示控件（如果有的话）的句柄 |
| SetToolTips | 将一个工具提示控件与该工具条控件关联 |
| SetOwner | 设置接收来自工具条控件的通知消息的窗口 |
| GetRows | 获取当前显示在工具条中的按钮的行数 |
| SetRows | 设置显示在工具条中的按钮的行数 |
| SetCmdID | 设置当指定按钮被按下时，要发送到属主窗口的命令标识符 |
| GetBitmapFlags | 获取与工具条位图相关联的标志 |
| GetDisabledImageList | 获取被一个工具条控件用来显示无效按钮的图像列表 |
| GetHotImageList | 获取被一个工具条控件用来显示“热点”按钮的图像列表。当鼠标指针在一个热点控件上时，该控件被加亮显示 |
| GetImageList | 获取被一个工具条控件用来显示缺省状态按钮的图像列表 |
| GetStyle | 获取一个工具条控件当前使用的风格 |
| GetMaxTextRows | 获取显示在一个工具条按钮上的文本行的最大行数 |
| IsButtonHighlighted | 检验工具条控件的加亮状态 |
| SetButtonWidth | 设置工具条控件中的按钮宽度的最大和最小值 |
| SetDisabledImageList | 设置将要被工具条控件用来显示无效按钮的图像列表 |
| SetHotImageList | 设置将要被工具条控件用来显示“热点”按钮的图像列表 |
| SetImageList | 设置将要被工具条控件用来显示缺省状态按钮的图像列表 |
| GetDropTarget | 获取一个工具条控件的IDropTarget接口 |
| SetIndent | 设置一个工具条控件中的第一个按钮的缩排 |
| SetMaxTextRows | 设置一个工具条按钮所显示的最大文本行数 |
| SetStyle | 设置一个工具条控件的风格 |
| GetAnchorHighlight | 获取一个工具条的固定的加亮设置 |
| SetAnchorHighlight | 设置一个工具条的固定的加亮设置 |
| GetHotItem | 获取一个工具条中的热点项的索引 |
| SetHotItem | 设置一个工具条中的热点项的索引 |
| GetInsertMark | 获取工具条的当前插入标记 |
| SetInsertMark | 设置工具条的当前插入标记 |
| GetMaxSize | 获取工具条中的所有可视按钮和分隔线的总的尺寸 |
| InsertMarkHitTest | 获取一个工具条中的某个点的插入标记信息 |
| GetExtendedStyle | 获取一个工具条控件的扩展风格 |
| SetExtendedStyle | 设置一个工具条控件的扩展风格 |
| GetInsertMarkColor | 获取用来绘制工具条的插入标记的颜色 |
| SetInsertMarkColor | 设置用来绘制工具条的插入标记的颜色 |
| MapAccelerator | 将一个加速键映射到一个工具条按钮 |
| MoveButton | 将一个按钮从一个索引移动到另一个索引 |
| HitTest | 确定一个点位于一个工具条控件的什么地方 |
操作
| EnableButton | 使一个工具条控件中的按钮有效或无效 |
| CheckButton | 核选或清除一个工具条控件中的指定按钮 |
| PressButton | 按下或释放一个工具条控件中的指定按钮 |
| GetButtonInfo | 获取工具条中的一个按钮的信息 |
| SetButtonInfo | 设置工具条中的一个按钮的信息 |
| SetDrawTextFlags | 设置Win 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文本的工具提示控件（只在Win95下） |
| TTN_NEEDTEXTW | 需要UNICODE文本的工具提示控件（只在Windows NT下） |
| TBN_HOTITEMCHANGE | 表示热点（被加亮的）项已经改变了 |
| NM_RCLICK | 表示用户用鼠标右键单击一个按钮 |
| TBN_DRAGOUT | 表示用户点击按钮并拖动指针离开了按钮。它支持应用程序实现对一个工具条按钮的拖放。但接收到这个通知时，应用程序将开始拖放操作 |
| TBN_DROPDOWN | 表示用户已经点击了一个使用TBSTYLE_DROPDOWN风格的按钮 |
| TBN_GETOBJECT | 表示用户已经将指针移动到了一个使用TBSTYLE_DROPDOWN风格的按钮上 |
处理函数的例子和有关使能工具提示的更多信息，参见“Visual C++程序员指南”中的“工具提示”。
CToolBarCtrl：处理定制通知
一个Windows工具条通用控件具有内在的定制特征，包括一个系统定义的定制对话框，用来让用户插入、删除，或重新安排工具条按钮。应用程序决定定制是否有效，并控制用户对该工具条定制的限度。
你可以通过给予工具条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, idControl,memberFxn)
| wNotifyCode | 通知消息标识符代码，比如TBN_BEGINADJUST。 |
| idControl | 发送通知的控件的标识符。 |
| memberFxn | 当这个通知被接收时要被调用的成员函数。 |
你的成员函数应该用下面的原形来声明：
afx_msg void memberFxn( NMHDR* pNotifyStruct, LRESULT* result );
如果通知消息的处理函数返回一个值，则处理函数应该将这个值存放在由result指向的LRESULT中。
对每一个消息，pNotifyStruct指向一个NMHDR结构或一个TBNOTIFY结构。
这些结构被描述如下：NMHDR结构包含了下列成员：
typedef struct tagNMHDR
{
HWND 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 { NMHDR hdr; // 对所有WM_NOTIFY消息都通用的信息 int iItem; // 与通知相关联的控件的的索引 TBBUTTON tbButton; // 与通知相关联的控件的信息 int cchText; // 按钮文本中的字符数 LPSTR lpszText; // 按钮文本的地址 } TBNOTIFY, FAR* LPTBNOTIFY; |
| hdr | 对所有WM_NOTIFY消息都通用的信息。 |
| iItem | 与通知相关联的控件的的索引。 |
| tbButton | 包含与通知相关联的工具条控件信息的BBUTTON结构。 |
| cchText | 按钮文本中的字符数。 |
| lpszText | 指向按钮文本的指针。 |
工具条发送下列信息：
| · | TBN_BEGINADJUST | 当用户开始定制一个工具条控件时发送此通知。指针指向的NMHDR结构包含了有关这个通知的信息。处理程序不需要返回任何值。 |
| · | TBN_BEGINDRAG | 当用户开始拖动一个工具条控件中的按钮时发送此通知。指针指向一个TBNOTIFY结构。iItem成员包含了被拖动的按钮的从零开始的索引。处理程序不需要返回任何特定的值。 |
| · | TBN_CUSTHELP | 当用户在Customize Toolbar对话框中选择了Help按钮时发送此通知。没有返回值。指针指向一个NMHDR结构，该结构包含了有关这个通知消息的信息。处理程序不需要返回任何特定的值。 |
| · | TBN_ENDADJUST | 当用户停止定制有关工具条时发送此通知。指针指向一个NMHDR结构，该结构包含了有关此通知消息的信息。处理程序不需要返回任何特定的值。 |
| · | TBN_ENDDRAG | 当用户停止拖动一个工具条控件中的按钮时发送此通知。指针指向一个TBNOTIFY结构。iItem成员包含了被拖动的按钮的从零开始的索引。处理程序不需要返回任何特定的值。 |
| · | TBN_GETBUTTONINFO | 当用户正在定制一个工具条控件时发送此通知。工具条使用这个通知消息来获取Customize Toolbar对话框需要的信息。指针指向一个TBNOTIFY结构。iItem成员指定了一个按钮的从零开始的索引。lpszText和cchText成员指定当前按钮文本的地址和以字符数表示的长度。应用程序应该用有关这个按钮的信息来填充该结构。如果按钮的信息被拷贝到了结构中，则返回TRUE；否则就返回FALSE。 |
| · | TBN_QUERYDELETE | 当用户正在定制一个工具条时发送此消息，以确定一个按钮是否可以被从工具条控件中删除。指针指向一个TBNOTIFY结构。iItem成员包含了要被删除的按钮的从零开始的索引。如果允许该按钮被删除则返回TRUE；否则返回 FALSE来禁止该按钮被删除。 |
| · | TBN_QUERYINSERT | 当用户正在定制一个工具条控件时发送此通知，以确定一个按钮是否可以被插入到指定按钮的左边。指针指向一个TBNOTIFY结构。iItem成员包含了要被插入的按钮的从零开始的索引。如果允许一个按钮被插入到给定按钮的前面，则返回TRUE；否则返回FALSE来禁止该按钮被插入。 |
| · | TBN_RESET | 当用户重新设置Customize Toolbar对话框时发送此通知。指针指向一个NMHDR结构，该结构包含了有关这个通知消息的信息。处理程序不需要返回任何特定的值。 |
| · | TBN_TOOLBARCHANGE | 在用户定制完一个工具条控件之后发送此通知。指针指向一个NMHDR结构，该结构包含了有关这个通知消息的信息。处理程序不需要返回任何特定的值。 |
