`CToolBarCtrl` 类

项目
10/16/2023

提供 Windows 工具栏公共控件的功能。

语法

class CToolBarCtrl : public CWnd

成员

公共构造函数

名称	描述
`CToolBarCtrl::CToolBarCtrl`	构造 `CToolBarCtrl` 对象。

公共方法

名称	描述
`CToolBarCtrl::AddBitmap`	向可用于工具栏控件的按钮图像列表添加一个或多个位图按钮图像。
`CToolBarCtrl::AddButtons`	向工具栏控件添加一个或多个按钮。
`CToolBarCtrl::AddString`	将作为资源 ID 传递的新字符串添加到工具栏的内部字符串列表中。
`CToolBarCtrl::AddStrings`	将一个或多个新字符串（作为由 `NULL` 分隔的字符串的缓冲区的指针传递）添加到工具栏的内部字符串列表中。
`CToolBarCtrl::AutoSize`	调整工具栏控件的大小。
`CToolBarCtrl::ChangeBitmap`	更改当前工具栏控件中的按钮的位图。
`CToolBarCtrl::CheckButton`	选中或取消选中工具栏控件中的给定按钮。
`CToolBarCtrl::CommandToIndex`	检索与指定命令标识符关联的按钮的从零开始的索引。
`CToolBarCtrl::Create`	创建工具栏控件并将其附加到 `CToolBarCtrl` 对象。
`CToolBarCtrl::CreateEx`	创建具有指定 Windows 扩展样式的工具栏控件，并将其附加到 `CToolBarCtrl` 对象。
`CToolBarCtrl::Customize`	显示“自定义工具栏”对话框。
`CToolBarCtrl::DeleteButton`	从工具栏控件中删除按钮。
`CToolBarCtrl::EnableButton`	启用或禁用工具栏控件中的指定按钮。
`CToolBarCtrl::GetAnchorHighlight`	检索工具栏的定位点突出显示设置。
`CToolBarCtrl::GetBitmap`	检索与工具栏中的按钮关联的位图的索引。
`CToolBarCtrl::GetBitmapFlags`	获取与工具栏的位图关联的标志。
`CToolBarCtrl::GetButton`	检索有关工具栏控件中的指定按钮的信息。
`CToolBarCtrl::GetButtonCount`	检索当前位于工具栏控件中的按钮的计数。
`CToolBarCtrl::GetButtonInfo`	检索工具栏中的按钮的信息。
`CToolBarCtrl::GetButtonSize`	检索工具栏按钮当前的宽度和高度（以像素为单位）。
`CToolBarCtrl::GetColorScheme`	检索当前工具栏控件的配色方案。
`CToolBarCtrl::GetDisabledImageList`	检索工具栏控件用于显示禁用的按钮的图像列表。
`CToolBarCtrl::GetDropTarget`	检索工具栏控件的 `IDropTarget` 接口。
`CToolBarCtrl::GetExtendedStyle`	检索工具栏控件的扩展样式。
`CToolBarCtrl::GetHotImageList`	检索工具栏控件用于显示“热”按钮的图像列表。鼠标指针位于热按钮上方时，该按钮为突出显示状态。
`CToolBarCtrl::GetHotItem`	检索工具栏中的热项的索引。
`CToolBarCtrl::GetImageList`	检索工具栏控件用于显示处于默认状态的按钮的图像列表。
`CToolBarCtrl::GetInsertMark`	检索工具栏的当前插入标记。
`CToolBarCtrl::GetInsertMarkColor`	检索用于绘制工具栏的插入标记的颜色。
`CToolBarCtrl::GetItemRect`	检索工具栏控件中按钮的边框。
`CToolBarCtrl::GetMaxSize`	检索工具栏中所有可见的按钮和分隔符的总大小。
`CToolBarCtrl::GetMaxTextRows`	检索工具栏按钮上显示的文本行的最大数量。
`CToolBarCtrl::GetMetrics`	检索工具栏控件的指标。
`CToolBarCtrl::GetPadding`	检索当前工具栏控件的水平及垂直填充。
`CToolBarCtrl::GetPressedImageList`	检索当前工具栏控件用于表示处于按下状态的按钮的图像列表。
`CToolBarCtrl::GetRect`	检索指定工具栏按钮的边框。
`CToolBarCtrl::GetRows`	检索工具栏中当前显示的按钮的行数。
`CToolBarCtrl::GetState`	检索有关工具栏控件中指定按钮的状态的信息，例如按钮是处于启用、按下还是选中状态。
`CToolBarCtrl::GetString`	检索工具栏字符串。
`CToolBarCtrl::GetStyle`	检索当前用于工具栏控件的样式。
`CToolBarCtrl::GetToolTips`	检索与工具栏控件关联的工具提示控件的句柄（如果有）。
`CToolBarCtrl::HideButton`	隐藏或显示工具栏控件中的指定按钮。
`CToolBarCtrl::HitTest`	确定某个点在工具栏控件中的位置。
`CToolBarCtrl::Indeterminate`	设置或清除工具栏控件中指定按钮的不确定（灰色）状态。
`CToolBarCtrl::InsertButton`	在工具栏控件中插入按钮。
`CToolBarCtrl::InsertMarkHitTest`	检索工具栏中的点的插入标记信息。
`CToolBarCtrl::IsButtonChecked`	指示是否已选中工具栏控件中的指定按钮。
`CToolBarCtrl::IsButtonEnabled`	指示是否已启用工具栏控件中的指定按钮。
`CToolBarCtrl::IsButtonHidden`	指示是否已隐藏工具栏控件中的指定按钮。
`CToolBarCtrl::IsButtonHighlighted`	检查工具栏按钮的突出显示状态。
`CToolBarCtrl::IsButtonIndeterminate`	指示工具栏控件中指定按钮的状态是否为不确定（灰色）。
`CToolBarCtrl::IsButtonPressed`	指示是否已按下工具栏控件中的指定按钮。
`CToolBarCtrl::LoadImages`	将位图加载到工具栏控件的图像列表中。
`CToolBarCtrl::MapAccelerator`	将快捷键字符映射到工具栏按钮。
`CToolBarCtrl::MarkButton`	设置工具栏控件中给定按钮的突出显示状态。
`CToolBarCtrl::MoveButton`	将按钮从一个索引移到另一个索引。
`CToolBarCtrl::PressButton`	按下或释放工具栏控件中的指定按钮。
`CToolBarCtrl::ReplaceBitmap`	将当前工具栏控件中的现有位图替换为新的位图。
`CToolBarCtrl::RestoreState`	还原工具栏控件的状态。
`CToolBarCtrl::SaveState`	保存工具栏控件的状态。
`CToolBarCtrl::SetAnchorHighlight`	设置工具栏的定位点突出显示设置。
`CToolBarCtrl::SetBitmapSize`	设置要添加到工具栏控件的位图化图像的大小。
`CToolBarCtrl::SetButtonInfo`	设置工具栏中的现有按钮的信息。
`CToolBarCtrl::SetButtonSize`	设置要添加到工具栏控件的按钮的大小。
`CToolBarCtrl::SetButtonStructSize`	指定 `TBBUTTON` 结构的大小。
`CToolBarCtrl::SetButtonWidth`	设置工具栏控件中的最小和最大按钮宽度。
`CToolBarCtrl::SetCmdID`	设置按下指定按钮时要发送到所有者窗口的命令标识符。
`CToolBarCtrl::SetColorScheme`	设置当前工具栏控件的配色方案。
`CToolBarCtrl::SetDisabledImageList`	设置工具栏控件将用于显示禁用的按钮的图像列表。
`CToolBarCtrl::SetDrawTextFlags`	设置 Win32 函数 `DrawText` 中的标志，该函数用于在根据标志的设置方式设置格式的指定矩形中绘制文本。
`CToolBarCtrl::SetExtendedStyle`	设置工具栏控件的扩展样式。
`CToolBarCtrl::SetHotImageList`	设置工具栏控件将用于显示“热”按钮的图像列表。
`CToolBarCtrl::SetHotItem`	设置工具栏中的热项。
`CToolBarCtrl::SetImageList`	设置工具栏将用于显示处于默认状态的按钮的图像列表。
`CToolBarCtrl::SetIndent`	设置工具栏控件中第一个按钮的缩进。
`CToolBarCtrl::SetInsertMark`	设置工具栏的当前插入标记。
`CToolBarCtrl::SetInsertMarkColor`	设置用于绘制工具栏的插入标记的颜色。
`CToolBarCtrl::SetMaxTextRows`	设置工具栏按钮上显示的文本行的最大数量。
`CToolBarCtrl::SetMetrics`	设置工具栏控件的指标。
`CToolBarCtrl::SetOwner`	设置从工具栏控件接收通知消息的窗口。
`CToolBarCtrl::SetPadding`	设置当前工具栏控件的水平及垂直填充。
`CToolBarCtrl::SetPressedImageList`	设置当前工具栏控件用于表示处于按下状态的按钮的图像列表。
`CToolBarCtrl::SetRows`	设置工具栏中显示的按钮的行数。
`CToolBarCtrl::SetState`	设置工具栏控件中的指定按钮的状态。
`CToolBarCtrl::SetStyle`	设置工具栏控件的样式。
`CToolBarCtrl::SetToolTips`	将工具提示控件与工具栏控件关联起来。
`CToolBarCtrl::SetWindowTheme`	设置工具栏控件的视觉样式。

注解

此控件（以及 CToolBarCtrl 类）仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。

Windows 工具栏公共控件是包含一个或多个按钮的矩形子窗口。这些按钮可显示位图图像或字符串，或两者都显示。用户选择按钮时，该按钮会向工具栏的所有者窗口发送一条命令消息。通常，工具栏中的按钮对应于应用程序菜单中的项，它们为用户提供了一种更直接的方式来访问应用程序命令。

CToolBarCtrl 对象包含若干重要的内部数据结构：按钮图像位图列表或图像列表、按钮标签字符串列表和 TBBUTTON 结构列表，这些数据结构将图像和/或字符串与按钮的位置、样式、状态和命令 ID 相关联。这些数据结构的每个元素都由从零开始的索引引用。在使用 CToolBarCtrl 对象之前，必须设置这些数据结构。字符串列表只能用于按钮标签；不能从工具栏中检索字符串。

为了使用 CToolBarCtrl 对象，你通常将执行下列步骤：

构造 CToolBarCtrl 对象。
调用 Create 来创建 Windows 工具栏公共控件并将其附加到 CToolBarCtrl 对象。使用样式指示工具栏的样式，例如用 TBSTYLE_TRANSPARENT 指示透明工具栏，或者用 TBSTYLE_DROPDOWN 指示支持下拉式按钮的工具栏。
确定在工具栏上显示按钮的方式：
- 若要对按钮使用位图图像，请通过调用 AddBitmap 将按钮位图添加到工具栏。
- 若要对按钮使用图像列表中显示的图像，请通过调用 SetImageList、SetHotImageList 或 SetDisabledImageList 来指定图像列表。
- 若要对按钮使用字符串标签，请通过调用 AddString 和/或 AddStrings 将字符串添加到工具栏。
通过调用 AddButtons 将按钮结构添加到工具栏。
如果需要在不是 CFrameWnd 的所有者窗口中的工具栏按钮的工具提示，你需要按照处理工具提示通知中所述，处理工具栏所有者窗口中的 TTN_NEEDTEXT 消息。如果工具栏的父窗口派生自 CFrameWnd，则不需要你执行任何额外的工作，都会显示工具提示，因为 CFrameWnd 提供默认处理程序。
如果希望用户能够自定义工具栏，请按照处理自定义通知中所述，在所有者窗口中处理自定义通知消息。

你可以使用 SaveState 在注册表中保存工具栏控件的当前状态，使用 RestoreState 根据以前存储在注册表中的信息还原状态。除了在应用程序的两次使用之间保存工具栏状态外，应用程序通常还会存储用户开始自定义工具栏之前的状态，以备在用户稍后希望将工具栏还原为原始状态时用到。

支持 Internet Explorer 版本 4.0 及更高版本

为了支持 Internet Explorer 版本 4.0 及更高版本中引入的功能，MFC 为工具栏控件提供了图像列表支持以及透明和平面样式。

透明工具栏使工具栏下的客户端能显示出来。要创建透明工具栏，请使用 TBSTYLE_FLAT 显出 TBSTYLE_TRANSPARENT 样式。透明工具栏具有热跟踪功能，也就是说，当鼠标指针移到工具栏上的热按钮时，按钮外观发生变化。仅使用 TBSTYLE_FLAT 样式创建的工具栏将包含不透明的按钮。

图像列表支持使控件的默认行为、热图像和禁用的图像更灵活。将 GetImageListGetHotImageList 和 GetDisabledImageList 和工具栏结合使用可根据图像状态操作图像：

有关使用 CToolBarCtrl 的详细信息，请参阅控件和使用 CToolBarCtrl。

继承层次结构

CObject

CCmdTarget

CWnd

CToolBarCtrl

要求

标头afxcmn.h：

`CToolBarCtrl::AddBitmap`

向存储在工具栏控件中的按钮图像列表添加一个或多个按钮图像。

int AddBitmap(
    int nNumButtons,
    UINT nBitmapID);

int AddBitmap(
    int nNumButtons,
    CBitmap* pBitmap);

参数

nNumButtons
位图中按钮图像的数量。

nBitmapID
包含要添加的一个或多个按钮图像的位图的资源标识符。

pBitmap
指向包含要添加的一个或多个按钮图像的 CBitmap 对象的指针。

返回值

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

注解

在将位图添加到工具栏之前，你可以使用 Windows API CreateMappedBitmap 来映射颜色。如果传递 CBitMap 对象的指针，你必须确保在工具栏被销毁后才销毁位图。

`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
    DWORD dwData;   // application-defined value
    int iString;    // zero-based index of button label string
} TBBUTTON;

成员如下：

iBitmap

按钮图像从零开始的索引，如果没有此按钮的图像，则为 -1。
idCommand

与按钮关联的命令标识符。此标识符是在选定按钮时，在 WM_COMMAND 消息中发送的。如果 fsStyle 成员有 TBSTYLE_SEP 值，则此成员必须为零。
fsState

按钮状态标志。可以是下面列出的值的组合：
- TBSTATE_CHECKED 按钮具有 TBSTYLE_CHECKED 样式并正处于按下状态。
- TBSTATE_ENABLED 按钮接受用户输入。没有此状态的按钮不接受用户输入，并且是灰显的。
- TBSTATE_HIDDEN 按钮不可见，无法接收用户输入。
- TBSTATE_INDETERMINATE 按钮是灰显的。
- TBSTATE_PRESSED 按钮正处于按下状态。
- TBSTATE_WRAP 按钮后有一个换行符。该按钮还必须具有 TBSTATE_ENABLED 状态。
fsStyle

按钮样式。可以是下面列出的值的组合：
- TBSTYLE_BUTTON 创建标准推送按钮。
- TBSTYLE_CHECK 创建一个按钮，每次用户单击时，该按钮会在按下和未按下状态之间切换。按钮处于按下状态时具有不同的背景色。
- TBSTYLE_CHECKGROUP 创建一个选中按钮，该按钮在按下组中的另一个按钮之前一直保持按下状态。
- TBSTYLE_GROUP 创建一个按钮，该按钮在按下组中的另一个按钮之前一直保持按下状态。
- TBSTYLE_SEP 创建一个分隔符，在按钮组之间提供小间隔。具有此样式的按钮不接收用户输入。
dwData

用户定义的数据。
iString

要用作按钮标签的字符串的从零开始的索引；如果没有用于此按钮的字符串，则为 -1。

之前必须已使用 AddBitmap、AddString 和/或 AddStrings 将你必须提供其索引的图像和/或字符串添加到工具栏控件列表。

`CToolBarCtrl::AddString`

将作为资源 ID 传递的新字符串添加到工具栏的内部字符串列表中。

int AddString(UINT nStringID);

参数

nStringID
要添加到工具栏控件的字符串列表的字符串资源的资源标识符。

返回值

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

`CToolBarCtrl::AddStrings`

向可用于工具栏控件的字符串列表添加一个或多个新字符串。

int AddStrings(LPCTSTR lpszStrings);

参数

lpszStrings
包含一个或多个以 NULL 结尾的字符串（这些字符串要添加到工具栏字符串列表）的缓冲区的地址。最后一个字符串必须以两个 NULL 字符结尾。

返回值

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

备注

缓冲区中的字符串必须用 NULL 字符分隔开。你必须确保最后一个字符串有两个 NULL 终止符。若要正确设置常数字符串的格式，你可以将它编写为：

// one null added automatically
lpszStrings = _T("Only one string to add\0");

或：

// adds three strings with one call
lpszStrings = _T("String 1\0String 2\0String 3\0");

不应向此函数传递 CString 对象，因为一个 CString 中不可能有多个 NULL 字符。

`CToolBarCtrl::AutoSize`

重设整个工具栏控件的大小。

void AutoSize();

注解

父窗口大小或工具栏大小更改时（例如设置按钮或位图大小或添加字符串时）时，你应调用此函数。

`CToolBarCtrl::ChangeBitmap`

更改当前工具栏控件中的按钮的位图。

BOOL ChangeBitmap(
    int idButton,
    int iBitmap);

参数

idButton
[in] 要接收新位图的按钮的命令标识符。

iBitmap
[in] 当前工具栏控件图像列表中的图像的从零开始的索引。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

如果此方法成功，系统在指定按钮中显示指定图像。

此方法将发送 TB_CHANGEBITMAP 消息，如 Windows SDK 中所述。

示例

下面的代码示例将“文件保存”按钮的位图更改为“关于”按钮的位图。

{
   // Change the bitmap for the File Save button, whose
   // command ID is ID_FILE_SAVE, to the bitmap for the
   // About button, whose index is 7.
   CToolBarCtrl &m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
   BOOL bRet = m_toolBarCtrl.ChangeBitmap(ID_FILE_SAVE, 7);
}

`CToolBarCtrl::CheckButton`

选中或取消选中工具栏控件中的给定按钮。

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

参数

nID
要选中或取消选中的按钮的命令标识符。

bCheck
要选中按钮，为 TRUE要取消选中，为 FALSE。

返回值

如果成功，则不为零，否则为零。

注解

选中按钮后，它似乎处于已按下状态。如果要更改多个按钮状态，请考虑改为调用 SetState。

`CToolBarCtrl::CommandToIndex`

检索与指定命令标识符关联的按钮的从零开始的索引。

UINT CommandToIndex(UINT nID) const;

参数

nID
希望查找其按钮索引的命令 ID。

返回值

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

注解

`CToolBarCtrl::Create`

创建工具栏控件并将其附加到 CToolBarCtrl 对象。

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

参数

dwStyle
指定工具栏控件的样式。工具栏必须始终具有 WS_CHILD 样式。此外，你可以指定工具栏样式和窗口样式的任意组合，如注解下所述。

rect
可选择指定工具栏控件的大小和位置。它可以是 CRect 对象或 RECT 结构。

pParentWnd
指定工具栏控件的父窗口。不得为 NULL。

nID
指定工具栏控件的 ID。

返回值

如果成功，则不为零，否则为零。

备注

分两步构建 CToolBarCtrl。首先，调用构造函数，然后调用 Create，这将创建工具栏控件并将其附加到 CToolBarCtrl 对象。将以下窗口样式应用于工具栏控件。

WS_CHILD：始终
WS_VISIBLE：通常
WS_DISABLED 很少

有关窗口样式的说明，请参阅 Windows SDK 中的 CreateWindow。

视情况应用常见控件样式的组合，如 Windows SDK 中所述。

将工具栏样式组合应用于控件或按钮本身。 Windows SDK 中的工具栏控件和按钮样式主题中介绍了这些样式。

若要使用扩展的工具栏样式，请在调用 Create 后调用 SetExtendedStyle。若要创建具有扩展窗口样式的工具栏，请调用 CToolBarCtrl::CreateEx 而不是 Create。

工具栏控件自动设置工具栏窗口的大小和位置。高度基于工具栏中按钮的高度。宽度与父窗口工作区的宽度一样。 CCS_TOP 和 CCS_BOTTOM 样式确定是沿工作区的顶部还是底部放置工具栏。默认工具栏具有 CCS_TOP 样式。

`CToolBarCtrl::CreateEx`

创建一个控件（子窗口）并将其与 CToolBarCtrl 对象相关联。

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

参数

dwExStyle
指定要创建的控件的扩展样式。有关扩展 Windows 样式的列表，请参阅 Windows SDK 中 CreateWindowEx 的 dwExStyle 参数。

dwStyle
指定工具栏控件的样式。工具栏必须始终具有 WS_CHILD 样式。此外，你可以指定工具栏样式和窗口样式的任意组合，如 Create 的注解部分所述。

rect
对 RECT 结构的引用，该结构描述了要在客户端坐标 pParentWnd 中创建的窗口的大小和位置。

pParentWnd
指向作为控件父级的窗口的指针。

nID
控件的子窗口 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

使用 CreateEx（而不是 Create）应用由 Windows 扩展样式前缀 WS_EX_ 指定的扩展 Windows 样式。 CreateEx 使用 dwExStyle 指定的扩展 Windows 样式创建控件。使用 SetExtendedStyle 设置特定于控件的扩展样式。例如，使用 CreateEx 将此类样式设置为 WS_EX_CONTEXTHELP，但使用 SetExtendedStyle 将此类样式设置为 TBSTYLE_EX_DRAWDDARROWS。有关详细信息，请参阅 Windows SDK 的工具栏扩展样式中所述的样式。

`CToolBarCtrl::CToolBarCtrl`

构造 CToolBarCtrl 对象。

CToolBarCtrl();

注解

你必须调用 Create 来使工具栏可用。

`CToolBarCtrl::Customize`

显示“自定义工具栏”对话框。

void Customize();

备注

借助此对话框，用户能通过添加和删除按钮来自定义工具栏。若要支持自定义，工具栏的父窗口必须按照处理自定义通知中所述来处理自定义通知消息。工具栏也必须是使用 CCS_ADJUSTABLE 样式创建的，如 CToolBarCtrl::Create 中所述。

`CToolBarCtrl::DeleteButton`

从工具栏控件中删除按钮。

BOOL DeleteButton(int nIndex);

参数

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

返回值

如果成功，则不为零，否则为零。

备注

`CToolBarCtrl::EnableButton`

启用或禁用工具栏控件中的指定按钮。

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

参数

nID
要启用或禁用的按钮的命令标识符。

bEnable
如果启用该按钮，则为 TRUE；如果禁用该按钮，则为 FALSE。

返回值

如果成功，则不为零，否则为零。

备注

启用按钮后，可按下并选中它。如果要更改多个按钮状态，请考虑改为调用 SetState。

`CToolBarCtrl::GetAnchorHighlight`

检索工具栏的定位点突出显示设置。

BOOL GetAnchorHighlight() const;

返回值

如果不为零，定位点突出显示为启用状态。如果为零，禁用定位点突出显示为禁用状态。

注解

此成员函数实现 Win32 消息 TB_GETANCHORHIGHLIGHT 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetBitmap`

检索与工具栏中的按钮关联的位图的索引。

int GetBitmap(int nID) const;

参数

nID
要检索其位图索引的按钮的命令标识符。

返回值

如果成功，返回位图的索引；否则返回零。

备注

实现 Windows SDK 中的 TB_GETBITMAP 的功能。

`CToolBarCtrl::GetBitmapFlags`

从工具栏检索位图标志。

UINT GetBitmapFlags() const;

返回值

如果显示器可支持大的工具栏位图，返回设置了 TBBF_LARGE 标志的 UINT；否则归零。

备注

应在创建工具栏之后，但在将位图添加到工具栏之前调用它。返回值指示显示器是否支持大位图。如果显示器支持大位图并且你选择使用大位图，请在使用 AddBitmap 添加大位图之前调用 SetBitmapSize 和 SetButtonSize。

`CToolBarCtrl::GetButton`

检索有关工具栏控件中的指定按钮的信息。

BOOL GetButton(
    int nIndex,
    LPTBBUTTON lpButton) const;

参数

nIndex
要为其检索信息的按钮的从零开始的索引。

lpButton
要接收按钮信息副本的 TBBUTTON 结构的地址。有关 TBBUTTON 结构的信息，请参阅 CToolBarCtrl::AddButtons。

返回值

如果成功，则不为零，否则为零。

`CToolBarCtrl::GetButtonCount`

检索当前位于工具栏控件中的按钮的计数。

int GetButtonCount() const;

返回值

按钮的计数。

`CToolBarCtrl::GetButtonInfo`

检索工具栏中的按钮的信息。

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

参数

nID
按钮标识符。

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

返回值

如果成功，返回按钮的从零开始的索引；否则返回 -1。

备注

此成员函数实现 Win32 消息 TB_GETBUTTONINFO 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetButtonSize`

获取工具栏按钮的大小。

DWORD GetButtonSize() const;

返回值

一个 DWORD 值，该值分别包含 LOWORD 和 HIWORD 中的宽度值和高度值。

`CToolBarCtrl::GetButtonText`

检索当前工具栏控件上指定按钮的显示文本。

CString GetButtonText(int idButton) const;

参数

idButton
[in] 检索了显示文本的按钮的标识符。

返回值

一个包含指定按钮的显示文本的 CString。

备注

此方法将发送 TB_GETBUTTONTEXT 消息，如 Windows SDK 中所述。

`CToolBarCtrl::GetColorScheme`

检索当前工具栏控件的配色方案。

BOOL GetColorScheme(COLORSCHEME* lpColorScheme) const;

参数

lpColorScheme
[out] 指向 COLORSCHEME 结构的指针，该结构接收配色方案信息。此方法返回时，该结构描述工具栏控件的突出显示颜色和阴影颜色。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

此方法将发送 TB_GETCOLORSCHEME 消息，如 Windows SDK 中所述。

`CToolBarCtrl::GetDisabledImageList`

检索工具栏控件用于显示禁用的按钮的图像列表。

CImageList* GetDisabledImageList() const;

返回值

指向 CImageList 对象的指针；如果未设置禁用的图像列表，则为 NULL。

备注

此成员函数实现 Win32 消息 TB_GETDISABLEDIMAGELIST 的行为，如 Windows SDK 中所述。 GetDisabledImageList 的 MFC 实现使用包含工具栏控件按钮图像的 CImageList 对象，而不是图像列表的句柄。

`CToolBarCtrl::GetDropTarget`

检索工具栏控件的 IDropTarget 接口。

HRESULT GetDropTarget(IDropTarget** ppDropTarget) const;

参数

ppDropTarget
指向 IDropTarget 接口指针的指针。如果发生错误，则将 NULL 指针放置在此地址中。

返回值

返回一个 HRESULT 值，该值指示操作是成功还是失败。

备注

此成员函数实现 Win32 消息 TB_GETOBJECT 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetExtendedStyle`

检索工具栏控件的扩展样式。

DWORD GetExtendedStyle() const;

返回值

一个 DWORD，它表示当前用于工具栏控件的扩展样式。有关样式列表，请参阅 Windows SDK 中的工具栏扩展样式。

备注

此成员函数实现 Win32 消息 TB_GETEXTENDEDSTYLE 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetHotImageList`

检索工具栏控件用于显示“热”按钮的图像列表。鼠标指针位于热按钮上方时，该按钮为突出显示状态。

CImageList* GetHotImageList() const;

返回值

指向 CImageList 对象的指针；如果未设置禁用的图像列表，则为 NULL。

备注

此成员函数实现 Win32 消息 TB_GETHOTIMAGELIST 的行为，如 Windows SDK 中所述。鼠标指针位于热按钮上方时，该按钮为突出显示状态。

`CToolBarCtrl::GetHotItem`

检索工具栏中的热项的索引。

int GetHotItem() const;

返回值

工具栏中的热项的从零开始的索引。

备注

此成员函数实现 Win32 消息 TB_GETHOTITEM 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetImageList`

检索工具栏控件用于显示处于默认状态的按钮的图像列表。

CImageList* GetImageList() const;

返回值

指向 CImageList 对象的指针；如果未设置图像列表，则为 NULL。

注解

此成员函数实现 Win32 消息 TB_GETIMAGELIST 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetInsertMark`

检索工具栏的当前插入标记。

void GetInsertMark(TBINSERTMARK* ptbim) const;

参数

ptbim
指向 TBINSERTMARK 结构的指针，该结构接收插入标记。

备注

此成员函数实现 Win32 消息 TB_GETINSERTMARK 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetInsertMarkColor`

检索用于绘制工具栏的插入标记的颜色。

COLORREF GetInsertMarkColor() const;

返回值

一个 COLORREF 值，该值包含当前插入标记颜色。

注解

此成员函数实现 Win32 消息 TB_GETINSERTMARKCOLOR 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetItemRect`

检索工具栏控件中按钮的边框。

BOOL GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

参数

nIndex
要为其检索信息的按钮的从零开始的索引。

lpRect
RECT 结构或 CRect 对象的地址，该结构或对象接收边框的坐标。

返回值

如果成功，则不为零，否则为零。

备注

此函数不检索状态设置为 TBSTATE_HIDDEN 的按钮的边框。

`CToolBarCtrl::GetMaxSize`

检索工具栏中所有可见的按钮和分隔符的总大小。

BOOL GetMaxSize(LPSIZE pSize) const;

参数

pSize
一个指向 SIZE 结构的指针，该结构接收项的大小。

返回值

如果成功，则不为 0；否则为 0。

备注

此成员函数实现 Win32 消息 TB_GETMAXSIZE 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetMaxTextRows`

检索工具栏按钮上显示的文本行的最大数量。

int GetMaxTextRows() const;

返回值

工具栏按钮上显示的文本行的最大数量。

`CToolBarCtrl::GetMetrics`

检索 CToolBarCtrl 对象的指标。

void GetMetrics(LPTBMETRICS ptbm) const;

参数

ptbm
指向 CToolBarCtrl 对象的 TBMETRICS 结构的指针。

备注

此成员函数模拟 TB_GETMETRICS 消息的功能，如 Windows SDK 中所述。

`CToolBarCtrl::GetPadding`

检索当前工具栏控件的水平及垂直填充。

BOOL GetPadding(
    int* pnHorzPadding,
    int* pnVertPadding) const;

参数

pnHorzPadding
[out] 一个接收工具栏控件的水平填充（以像素为单位）的整数。

pnVertPadding
[out] 一个接收工具栏控件的垂直填充（以像素为单位）的整数。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

注解

此方法将发送 TB_GETPADDING 消息，如 Windows SDK 中所述。

`CToolBarCtrl::GetPressedImageList`

检索当前工具栏控件用于表示处于按下状态的按钮的图像列表。

CImageList* GetPressedImageList();

返回值

指向 CImageList（它包含当前控件的图像列表）的指针；如果未设置此类图像列表，则为 NULL。

备注

此方法将发送 TB_GETPRESSEDIMAGELIST 消息，如 Windows SDK 中所述。

`CToolBarCtrl::GetRect`

检索指定工具栏按钮的边框。

BOOL GetRect(
    int nID,
    LPRECT lpRect) const;

参数

nID
按钮标识符。

lpRect
指向用于接收边框信息的 RECT 结构的指针。

返回值

如果成功，则返回 TRUE；否则返回 FALSE。

备注

此成员函数实现 Win32 消息 TB_GETRECT 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetRows`

检索工具栏控件当前显示的按钮的行数。

int GetRows() const;

返回值

工具栏当前显示的按钮的行数。

备注

请注意，除非是使用 TBSTYLE_WRAPABLE 样式创建的工具栏，否则行数将始终为一行。

`CToolBarCtrl::GetState`

检索有关工具栏控件中指定按钮的状态的信息，例如按钮是处于启用、按下还是选中状态。

int GetState(int nID) const;

参数

nID
要为其检索信息的按钮的从零开始的索引。

返回值

如果成功，为按钮状态信息；否则为 -1。按钮状态信息可以是 CToolBarCtrl::AddButtons 中列出的值的组合。

备注

如果希望检索多个按钮状态，此函数特别有用。如果只检索一种状态，请使用以下成员函数之一：IsButtonEnabled、IsButtonChecked、IsButtonPressed、IsButtonHidden 或 IsButtonIndeterminate。但是，GetState 成员函数是检测 TBSTATE_WRAP 按钮状态的唯一方式。

`CToolBarCtrl::GetString`

检索工具栏字符串。

int GetString(
    int nString,
    LPTSTR lpstrString,
    int cchMaxLen) const;

int GetString(
    int nString,
    CString& str) const;

参数

nString
字符串的索引。

lpstrString
指向用于返回字符串的缓冲区的指针。

cchMaxLen
缓冲区的长度（以字节为单位）。

str
字符串。

返回值

如果成功，返回字符串的长度；如果不成功，则返回 -1。

注解

此成员函数实现 Win32 消息 TB_GETSTRING 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::GetStyle`

获取当前应用于工具栏控件的样式。

DWORD GetStyle() const;

返回值

包含工具栏控件样式组合的 DWORD，如 Windows SDK 中所述。

`CToolBarCtrl::GetToolTips`

检索与工具栏控件关联的工具提示控件的句柄（如果有）。

CToolTipCtrl* GetToolTips() const;

返回值

指向与此工具栏关联的 CToolTipCtrl 对象的指针；如果工具栏没有关联的工具提示控件，则为 NULL。

备注

工具栏控件通常创建并维护它自己的工具提示控件，因此大多数程序不需要调用此函数。

`CToolBarCtrl::HitTest`

确定某个点在工具栏控件中的位置。

int HitTest(LPPOINT ppt) const;

参数

ppt
指向 POINT 结构的指针，该结构包含 x 成员中的命中测试的 X 坐标，还包含 y 成员中的命中测试的 Y 坐标。这些坐标是相对于工具栏的工作区而言的。

返回值

一个整数值，指示点在工具栏上的位置。如果该值为零或正值，则该返回值为点所在的非分隔符项的从零开始的索引。

如果返回值为负值，则点不在按钮内。返回值的绝对值是分隔符项或最近的非分隔符项的索引。

备注

此成员函数实现 Win32 消息 TB_HITTEST 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::HideButton`

隐藏或显示工具栏控件中的指定按钮。

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

参数

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

bHide
如果为 TRUE，隐藏按钮；如果为 FALSE，显示按钮。

返回值

如果成功，则不为零，否则为零。

备注

如果要更改多个按钮状态，请考虑改为调用 SetState。

`CToolBarCtrl::Indeterminate`

设置或清除工具栏控件中指定按钮的不确定状态。

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

参数

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

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

返回值

如果成功，则不为零，否则为零。

注解

不确定的按钮显示为灰色，例如选定文本包含粗体和常规两种字符时，粗体按钮在字处理器的工具栏上的外观。如果要更改多个按钮状态，请考虑改为调用 SetState。

`CToolBarCtrl::InsertButton`

在工具栏控件中插入按钮。

BOOL InsertButton(
    int nIndex,
    LPTBBUTTON lpButton);

参数

nIndex
按钮的从零开始的索引。此函数在此按钮的左侧插入新按钮。

lpButton
TBBUTTON 结构的地址，该结构包含要插入的按钮的信息。请参阅 CToolBarCtrl::AddButtons 查看有关 TBBUTTON 结构的说明。

返回值

如果成功，则不为零，否则为零。

注解

之前必须已使用 AddBitmap、AddString 和/或 AddStrings 将你必须提供其索引的图像和/或字符串添加到工具栏控件列表。

`CToolBarCtrl::InsertMarkHitTest`

检索工具栏中的点的插入标记信息。

BOOL InsertMarkHitTest(
    LPPOINT ppt,
    LPTBINSERTMARK ptbim) const;

参数

ppt
指向 POINT 结构的指针，该结构包含相对于工具栏工作区的命中测试坐标。

ptbim
指向 TBINSERTMARK 结构的指针，该结构接收插入标记信息。

返回值

如果成功，则不为零，否则为零。

注解

此成员函数实现 Win32 消息 TB_INSERTMARKHITTEST 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::IsButtonChecked`

确定是否已选中工具栏控件中的指定按钮。

BOOL IsButtonChecked(int nID) const;

参数

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

返回值

如果选中此按钮，不为零；否则为零。

备注

如果要检索多个按钮状态，请考虑调用 GetState。

`CToolBarCtrl::IsButtonEnabled`

确定是否已启用工具栏控件中的指定按钮。

BOOL IsButtonEnabled(int nID) const;

参数

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

返回值

如果启用了此按钮，不为零；否则为零。

备注

如果要检索多个按钮状态，请考虑调用 GetState。

`CToolBarCtrl::IsButtonHidden`

确定是否已隐藏工具栏控件中的指定按钮。

BOOL IsButtonHidden(int nID) const;

参数

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

返回值

如果已隐藏此按钮，不为零；否则为零。

备注

如果要检索多个按钮状态，请考虑调用 GetState。

`CToolBarCtrl::IsButtonHighlighted`

检查工具栏按钮的突出显示状态。

BOOL IsButtonHighlighted(int nID) const;

参数

nID
[in] 工具栏按钮的命令 ID。

返回值

如果按钮突出显示，为正整数；如果按钮未突出显示，为 0；如果发生错误，则为 -1。

`CToolBarCtrl::IsButtonIndeterminate`

确定工具栏控件中的指定按钮是否是不确定的。

BOOL IsButtonIndeterminate(int nID) const;

参数

nID
[in] 工具栏中的按钮的命令标识符。

返回值

如果按钮是不确定的，该值为正整数；如果按钮不是不确定的，为零；如果发生错误，则为 -1。

注解

不确定的按钮显示为暗灰色，例如选定文本包含粗体和常规两种字符时，粗体按钮在字处理器的工具栏上的外观。如果要检索多个按钮状态，请考虑调用 GetState。

`CToolBarCtrl::IsButtonPressed`

确定是否已按下工具栏控件中的指定按钮。

BOOL IsButtonPressed(int nID) const;

参数

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

返回值

如果按下了此按钮，不为零；否则为零。

备注

如果要检索多个按钮状态，请考虑调用 GetState。

`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。

备注

此成员函数实现 Win32 消息 TB_LOADIMAGES 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::MapAccelerator`

将快捷键字符映射到工具栏按钮。

BOOL MapAccelerator(
    TCHAR chAccel,
    UINT* pIDBtn);

参数

chAccel
要映射的快捷键字符。此字符就是按钮文本中带下划线的字符。

pIDBtn
指向 UINT（它接收与 chAccel 中指定的快捷键对应的按钮的命令标识符）的指针。

返回值

如果成功，则不为零，否则为零。

备注

此成员函数实现 Win32 消息 TB_MAPACCELERATOR 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::MarkButton`

设置工具栏控件中给定按钮的突出显示状态。

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

参数

nID
按钮标识符。

fHighlight
指定要设置的突出显示状态。默认情况下，为 TRUE。如果设置为 FALSE，则按钮设置为其默认状态。

返回值

如果成功，则不为 0；否则为 0。

注解

此成员函数实现 Win32 消息 TB_MARKBUTTON 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::MoveButton`

将按钮从一个索引移到另一个索引。

BOOL MoveButton(
    UINT nOldPos,
    UINT nNewPos);

参数

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

nNewPos
按钮的目标的从零开始的索引。

返回值

如果成功，则不为 0；否则为 0。

注解

此成员函数实现 Win32 消息 TB_MOVEBUTTON 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::PressButton`

按下或释放工具栏控件中的指定按钮。

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

参数

nID
[in] 要按下或释放的按钮的命令标识符。

bPress
[in] 如果为 TRUE，按下指定按钮；如果为 FALSE，释放指定的按钮。默认值为 TRUE。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

注解

如果要更改多个按钮状态，请考虑改为调用 SetState。

此方法将发送 TB_PRESSBUTTON 消息，如 Windows SDK 中所述。

`CToolBarCtrl::ReplaceBitmap`

将当前工具栏控件中的现有位图替换为新的位图。

BOOL ReplaceBitmap(LPTBREPLACEBITMAP pReplaceBitmap);

参数

pReplaceBitmap
[in] 指向 TBREPLACEBITMAP 结构的指针，该结构描述替换的位图和新位图。

返回值

如果此方法成功，则为 TRUE；否则为 FALSE。

备注

此方法将发送 TB_REPLACEBITMAP 消息，如 Windows SDK 中所述。

示例

以下代码示例将标准工具栏的位图替换为其他位图。

{
   // Replace one toolbar bitmap with another.
   TBREPLACEBITMAP tbrb;
   tbrb.hInstOld = ::AfxGetInstanceHandle();
   tbrb.nIDOld = IDR_MAINFRAME;
   tbrb.hInstNew = ::AfxGetInstanceHandle();
   tbrb.nIDNew = IDR_MAINFRAME1;
   tbrb.nButtons = 8;
   CToolBarCtrl &m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
   BOOL bRet = m_toolBarCtrl.ReplaceBitmap(&tbrb);
}

`CToolBarCtrl::RestoreState`

从参数指定的注册表中的位置还原工具栏控件的状态。

void RestoreState(
    HKEY hKeyRoot,
    LPCTSTR lpszSubKey,
    LPCTSTR lpszValueName);

参数

hKeyRoot
标识注册表中当前打开的项或以下任何一个预定义的保留句柄值：

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpszSubKey
指向以 NULL 结尾的字符串的指针，该字符串包含与值关联的子项的名称。此参数可以为 NULL 或空字符串的指针。如果参数为 NULL，则值将被添加到由 hKeyRoot 参数标识的项中。

lpszValueName
指向包含要检索的值的名称的字符串。如果项中尚不存在具有此名称的值，该函数会将该值添加到项。

`CToolBarCtrl::SaveState`

保存位于参数指定的注册表中的位置的工具栏控件的状态。

void SaveState(
    HKEY hKeyRoot,
    LPCTSTR lpszSubKey,
    LPCTSTR lpszValueName);

参数

hKeyRoot
标识注册表中当前打开的项或以下任何一个预定义的保留句柄值：

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpszValueName
指向字符串，该字符串包含要设置的值的名称。如果项中尚不存在具有此名称的值，该函数会将该值添加到项。

`CToolBarCtrl::SetAnchorHighlight`

设置工具栏的定位点突出显示设置。

BOOL SetAnchorHighlight(BOOL fAnchor = TRUE);

参数

fAnchor
[in] 指定是启用还是禁用定位点突出显示。如果此值不为零，将启用定位点突出显示。如果此值为零，将禁用定位点突出显示

返回值

上一个定位点设置。如果已启用突出显示，则此值不为零。如果未启用突出显示，则此值为零。

注解

此方法实现 Win32 消息 TB_SETANCHORHIGHLIGHT 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::SetBitmapSize`

设置要添加到工具栏控件的实际位图化图像的大小。

BOOL SetBitmapSize(CSize size);

参数

size
位图化图像的宽度和高度（以像素为单位）。

返回值

如果成功，则不为零，否则为零。

注解

只能在向工具栏添加任何位图之前调用此函数。如果应用程序未显式设置位图大小，则默认为 16 乘 15 像素。

`CToolBarCtrl::SetButtonInfo`

设置工具栏中的现有按钮的信息。

BOOL SetButtonInfo(
    int nID,
    TBBUTTONINFO* ptbbi);

参数

nID
按钮标识符。

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

返回值

如果成功，则不为 0；否则为 0。

备注

此成员函数实现 Win32 消息 TB_SETBUTTONINFO 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::SetButtonSize`

设置工具栏控件中的按钮的大小。

BOOL SetButtonSize(CSize size);

参数

size
按钮的宽度和高度（以像素为单位）。

返回值

如果成功，则不为零，否则为零。

备注

按钮大小必须始终至少与它随附的位图的大小一样。只能在向工具栏添加任何位图之前调用此函数。如果应用程序未显式设置按钮大小，则默认为 24 乘 22 像素。

示例

请参阅 CToolBar::GetToolBarCtrl 的示例。

`CToolBarCtrl::SetButtonStructSize`

指定 TBBUTTON 结构的大小。

void SetButtonStructSize(int nSize);

参数

nSize
TBBUTTON 结构的大小（以字节为单位）。

备注

如果要在 TBBUTTON 结构中存储额外的数据，可以通过添加所需成员的方式从 TBBUTTON 派生一个新结构，或者创建一个将 TBBUTTON 结构作为第一个成员的新结构。然后，调用此函数将新结构的大小告诉工具栏控件。

有关 TBBUTTON 结构的详细信息，请参阅 CToolBarCtrl::AddButtons。

`CToolBarCtrl::SetButtonWidth`

设置工具栏控件中的最小和最大按钮宽度。

BOOL SetButtonWidth(
    int cxMin,
    int cxMax);

参数

cxMin
最小按钮宽度（以像素为单位）。工具栏按钮永远不会比此值更窄。

cxMax
最大按钮宽度（以像素为单位）。如果按钮文本过宽，控件会为其显示省略号点。

返回值

如果成功，则不为 0；否则为 0。

备注

此成员函数实现 Win32 消息 TB_SETBUTTONWIDTH 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::SetCmdID`

设置按下指定按钮时将发送到所有者窗口的命令标识符。

BOOL SetCmdID(
    int nIndex,
    UINT nID);

参数

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

nID
要将选定的按钮设置为的命令 ID。

返回值

如果成功，返回不为零的值；否则返回零。

`CToolBarCtrl::SetColorScheme`

设置当前工具栏控件的配色方案。

void SetColorScheme(const COLORSCHEME* lpColorScheme);

参数

lpColorScheme
[in] 指向 COLORSCHEME 结构的指针，该结构描述工具栏控件的突出显示颜色和阴影颜色。

注解

如果设置了 Windows Vista 视觉主题，此方法不起作用。

此方法将发送 TB_SETCOLORSCHEME 消息，如 Windows SDK 中所述。

示例

以下代码示例设置当前工具栏控件的配色方案。该代码示例使每个工具按钮的左边缘和上边缘为红色，右边缘和下边缘为蓝色。用户按下按钮时，该按钮的红色边缘变为蓝色，蓝色边缘变为红色。

//Set color scheme for the current toolbar control.
//Make the left and top edges of the tool button red,
//and the right and bottom edges blue. The colors
//reverse when a button is pressed.
//This method has no effect if the Vista visual theme
//is set.
{
   COLORSCHEME cs;
   cs.dwSize = sizeof(COLORSCHEME);
   cs.clrBtnHighlight = RGB(255, 0, 0);
   cs.clrBtnShadow = RGB(0, 0, 255);
   CToolBarCtrl &m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
   m_toolBarCtrl.SetColorScheme(&cs);
}

`CToolBarCtrl::SetDisabledImageList`

设置工具栏控件将用于显示禁用的按钮的图像列表。

CImageList* SetDisabledImageList(CImageList* pImageList);

参数

pImageList
指向 CImageList 对象的指针该对象包含工具栏控件为了显示禁用的按钮图像而将使用的图像。

返回值

指向 CImageList 对象的指针，该对象之前被工具栏控件用来显示禁用的按钮图像。

备注

此成员函数实现 Win32 消息 TB_SETDISABLEDIMAGELIST 的行为，如 Windows SDK 中所述。 SetDisabledImageList 的 MFC 实现使用包含工具栏控件的禁用的按钮图像的 CImageList 对象，而不是图像列表的句柄。

`CToolBarCtrl::SetDrawTextFlags`

设置 Win32 函数 DrawText 中的标志，该函数用于在根据标志的设置方式设置格式的指定矩形中绘制文本。

DWORD SetDrawTextFlags(
    DWORD dwMask,
    DWORD dwDTFlags);

参数

dwMask
Win32 函数 DrawText 中指定的一个或多个 DT_ 标志的组合，指示绘制文本时将使用 dwDTFlags 中的哪些位。

dwDTFlags
Win32 函数 DrawText 中指定的一个或多个 DT_ 标志的组合，指示如何绘制按钮文本。绘制按钮文本时，系统将此值传递到 DrawText。

返回值

包含上一个文本绘制标志的 DWORD。

注解

此成员函数实现 Win32 消息 TB_SETDRAWTEXTFLAGS 的行为，如 Windows SDK 中所述。此成员函数设置 Win32 函数 DrawText 中的标志，该函数根据标志的设置方式设置格式的指定矩形中绘制文本。

`CToolBarCtrl::SetExtendedStyle`

设置工具栏控件的扩展样式。

DWORD SetExtendedStyle(DWORD dwExStyle);

参数

dwExStyle
指定新的扩展样式的值。此参数可以是工具栏扩展样式的组合。

返回值

表示上一个扩展样式的 DWORD。有关样式列表，请参阅 Windows SDK 中的工具栏扩展样式。

备注

此成员函数实现 Win32 消息 TB_SETEXTENDEDSTYLE 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::SetHotImageList`

设置工具栏控件将用于显示“热”按钮的图像列表。

CImageList* SetHotImageList(CImageList* pImageList);

参数

pImageList
指向 CImageList 对象的指针，该对象包含工具栏控件为了显示热按钮图像而将使用的图像。

返回值

指向 CImageList 对象的指针，该对象之前被工具栏控件用来显示热按钮图像。

备注

此成员函数实现 Win32 消息 TB_SETHOTIMAGELIST 的行为，如 Windows SDK 中所述。

SetHotImageList 的 MFC 实现使用包含工具栏控件的热按钮图像的 CImageList 对象，而不是图像列表的句柄。指针位于热按钮上方时，该按钮为突出显示状态。

`CToolBarCtrl::SetHotItem`

设置工具栏中的热项。

int SetHotItem(int nHot);

参数

nHot
要设为热项的项的从零开始的索引号。如果此值为 -1，所有项都不会成为热项。

返回值

上一个热项的索引；如果没有热项，则为 -1。

注解

此成员函数实现 Win32 消息 TB_SETHOTITEM 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::SetImageList`

设置工具栏将用于显示处于默认状态的按钮的图像列表。

CImageList* SetImageList(CImageList* pImageList);

参数

pImageList
指向 CImageList 对象的指针，该对象包含工具栏控件为了显示处于默认状态的按钮图像而将使用的图像。

返回值

指向 CImageList 对象的指针，该对象之前被工具栏控件用来显示处于默认状态的按钮图像。

注解

此成员函数实现 Win32 消息 TB_SETIMAGELIST 的行为，如 Windows SDK 中所述。

SetImageList 的 MFC 实现使用包含工具栏控件按钮图像的 CImageList 对象，而不是图像列表的句柄。

`CToolBarCtrl::SetIndent`

设置工具栏控件中第一个按钮的缩进。

BOOL SetIndent(int iIndent);

参数

iIndent
指定缩进的值，以像素为单位。

返回值

如果成功，则不为零，否则为零。

`CToolBarCtrl::SetInsertMark`

设置工具栏的当前插入标记。

void SetInsertMark(TBINSERTMARK* ptbim);

参数

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

备注

此成员函数实现 Win32 消息 TB_SETINSERTMARK 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::SetInsertMarkColor`

设置用于绘制工具栏的插入标记的颜色。

COLORREF SetInsertMarkColor(COLORREF clrNew);

参数

clrNew
一个 COLORREF 值，该值包含新插入标记颜色。

返回值

一个 COLORREF 值，该值包含上一个插入标记颜色。

备注

此成员函数实现 Win32 消息 TB_SETINSERTMARKCOLOR 的行为，如 Windows SDK 中所述。

`CToolBarCtrl::SetMaxTextRows`

设置工具栏按钮上显示的文本行的最大数量。

BOOL SetMaxTextRows(int iMaxRows);

参数

iMaxRows
要设置的最大行数。

返回值

如果成功，则不为零，否则为零。

`CToolBarCtrl::SetMetrics`

设置 CToolBarCtrl 对象的指标。

void SetMetrics(LPTBMETRICS ptbm);

参数

ptbm
指向 CToolBarCtrl 对象的 TBMETRICS 结构的指针。

备注

此成员函数模拟 TB_SETMETRICS 消息的功能，如 Windows SDK 中所述。

`CToolBarCtrl::SetOwner`

设置工具栏控件的所有者窗口。

void SetOwner(CWnd* pWnd);

参数

pWnd
指向 CWnd 或 CWnd 派生对象（这二者将成为工具栏控件的新所有者窗口）的指针。

备注

所有者窗口是从工具栏接收通知的窗口。

`CToolBarCtrl::SetPadding`

设置当前工具栏控件的水平及垂直填充。

DWORD SetPadding(
    int nHorzPadding,
    int nVertPadding);

参数

nHorzPadding
[in] 指定工具栏控件的水平填充（以像素为单位）。

nVertPadding
[in] 指定工具栏控件的垂直填充（以像素为单位）。

返回值

一个 DWORD，其低位字包含上一个水平填充值，高位字包含上一个垂直填充值。填充值用像素来衡量。

注解

此方法将发送 TB_SETPADDING 消息，如 Windows SDK 中所述。

示例

以下代码示例将当前工具栏控件的水平及垂直填充设置为 20 像素。

{
   // Set the horizontal and vertical padding of the current
   // toolbar control.
   CToolBarCtrl &m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
   m_toolBarCtrl.SetPadding(50, 50);
}

`CToolBarCtrl::SetPressedImageList`

设置当前工具栏控件用于表示处于按下状态的按钮的图像列表。

CImagelist* SetPressedImageList(
    int iImageID,
    CImageList* pImageList);

参数

iImageID
[in] 图像列表的从零开始的索引。如果你只使用一个图像列表，请将此参数设置为零。

pImageList
[in] 指向包含新图像列表的 CImageList 的指针。

返回值

指向 CImageList（它包含当前控件的上一个图像列表）的指针；如果未设置此类图像列表，则为 NULL。

备注

此方法将发送 TB_SETPRESSEDIMAGELIST 消息，如 Windows SDK 中所述。

示例

以下代码示例将按下的图像列表设置成与默认图像列表相同。

{
   // SetPressedImageList
   // Set the pressed image list to be the same as the
   // normal image list.
   CToolBarCtrl &m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
   CImageList *pNormalCil = m_toolBarCtrl.GetImageList();
   CImageList *pPressedCil = m_toolBarCtrl.GetPressedImageList();
   m_toolBarCtrl.SetPressedImageList(0, pNormalCil);
}

`CToolBarCtrl::SetRows`

要求工具栏控件将其自身的大小调整为请求的行数。

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

参数

nRows
请求的行数。

bLarger
如果无法将工具栏调整为请求的行数，则指示是使用更多行还是更少行。

lpRect
指向 CRect 对象或 RECT 结构，该对象或结构将接收工具栏的新边框。

备注

如果工具栏无法将自己调整为请求的行数，则它将根据 bLarger 的值，将自己调整为下一个较大或较小的有效大小。如果 bLarger 为 TRUE，则新行数将大于请求的行数。如果 bLarger 为 FALSE，则新行数将小于请求的行数。

如果可将按钮排列为使所有行具有相同的按钮数（最后一行可能除外），则给定行数对于工具栏有效。例如，包含四个按钮的工具栏不能调整为三行，因为最后两行必须更短。如果试图将它调整为三行，则当 bLarger 为 TRUE 时，你将得到四行；当 bLarger 为 FALSE 时，你将得到两行。

如果工具栏中有分隔符，关于给定行数在何时有效的规则会更加复杂。布局的计算使按钮组（按钮在组中的第一个和最后一个按钮前有分隔符）永远不会分为数行，除非一行中容不下组。

如果一个组放不进一行中，则下一个组将在下一行上开始，即使它能放进大组结束的行中也是如此。此规则的目的是使大组之间的分隔更明显。所得的垂直分隔符被看作行。

另请注意，SetRows 成员函数将始终选择得到最小工具栏大小的布局。如果已知控件宽度，则在创建具有 TBSTYLE_WRAPABLE 样式的工具栏后调整控件大小的这种做法将只应用上面列出的方法。

只能为创建的具有 TBSTYLE_WRAPABLE 样式的工具栏调用此函数。

`CToolBarCtrl::SetState`

设置工具栏控件中的指定按钮的状态。

BOOL SetState(
    int nID,
    UINT nState);

参数

nID
按钮的命令标识符。

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

返回值

如果成功，则不为零，否则为零。

备注

如果希望设置多个按钮状态，此函数特别有用。如果只设置一种状态，请使用以下成员函数之一：EnableButton、CheckButton、HideButton、Indeterminate 或 PressButton。

`CToolBarCtrl::SetStyle`

设置工具栏控件的样式。

void SetStyle(DWORD dwStyle);

参数

dwStyle
包含工具栏控件样式组合的 DWORD，如 Windows SDK 中所述。

`CToolBarCtrl::SetToolTips`

将工具提示控件与工具栏控件关联起来。

void SetToolTips(CToolTipCtrl* pTip);

参数

pTip
指向 CToolTipCtrl 对象的指针。

`CToolBarCtrl::SetWindowTheme`

设置 CToolBarCtrl 对象的视觉样式。

HRESULT SetWindowTheme(LPCWSTR pszSubAppName);

参数

pszSubAppName
指向 Unicode 字符串的指针，该字符串包含要设置的工具栏视觉样式。

返回值

不使用返回值。

备注

此成员函数模拟 TB_SETWINDOWTHEME 消息的功能，如 Windows SDK 中所述。

另请参阅

MFC 示例 CMNCTRL1
MFC 示例 MFCIE
CWnd 类
 层次结构图
 CToolBar 类

通过

CToolBarCtrl 类

语法

成员

公共构造函数

公共方法

注解

支持 Internet Explorer 版本 4.0 及更高版本

继承层次结构

要求

CToolBarCtrl::AddBitmap

参数

返回值

注解

CToolBarCtrl::AddButtons

参数

返回值

备注

CToolBarCtrl::AddString

参数

返回值

CToolBarCtrl::AddStrings

参数

返回值

备注

CToolBarCtrl::AutoSize

注解

CToolBarCtrl::ChangeBitmap

参数

返回值

备注

示例

CToolBarCtrl::CheckButton

参数

返回值

注解

CToolBarCtrl::CommandToIndex

参数

返回值

注解

CToolBarCtrl::Create

参数

返回值

备注

CToolBarCtrl::CreateEx

参数

返回值

备注

CToolBarCtrl::CToolBarCtrl

注解

CToolBarCtrl::Customize

备注

CToolBarCtrl::DeleteButton

参数

返回值

备注

CToolBarCtrl::EnableButton

参数

返回值

备注

CToolBarCtrl::GetAnchorHighlight

返回值

注解

CToolBarCtrl::GetBitmap

参数

返回值

备注

CToolBarCtrl::GetBitmapFlags

返回值

备注

CToolBarCtrl::GetButton

参数

返回值

CToolBarCtrl::GetButtonCount

返回值

CToolBarCtrl::GetButtonInfo

参数

返回值

备注

CToolBarCtrl::GetButtonSize

`CToolBarCtrl` 类

`CToolBarCtrl::AddBitmap`

`CToolBarCtrl::AddButtons`

`CToolBarCtrl::AddString`

`CToolBarCtrl::AddStrings`

`CToolBarCtrl::AutoSize`

`CToolBarCtrl::ChangeBitmap`

`CToolBarCtrl::CheckButton`

`CToolBarCtrl::CommandToIndex`

`CToolBarCtrl::Create`

`CToolBarCtrl::CreateEx`

`CToolBarCtrl::CToolBarCtrl`

`CToolBarCtrl::Customize`

`CToolBarCtrl::DeleteButton`

`CToolBarCtrl::EnableButton`

`CToolBarCtrl::GetAnchorHighlight`

`CToolBarCtrl::GetBitmap`

`CToolBarCtrl::GetBitmapFlags`

`CToolBarCtrl::GetButton`

`CToolBarCtrl::GetButtonCount`

`CToolBarCtrl::GetButtonInfo`

`CToolBarCtrl::GetButtonSize`

`CToolBarCtrl::GetButtonText`

`CToolBarCtrl::GetColorScheme`

`CToolBarCtrl::GetDisabledImageList`

`CToolBarCtrl::GetDropTarget`

`CToolBarCtrl::GetExtendedStyle`

`CToolBarCtrl::GetHotImageList`

`CToolBarCtrl::GetHotItem`

`CToolBarCtrl::GetImageList`

`CToolBarCtrl::GetInsertMark`

`CToolBarCtrl::GetInsertMarkColor`

`CToolBarCtrl::GetItemRect`

`CToolBarCtrl::GetMaxSize`

`CToolBarCtrl::GetMaxTextRows`

`CToolBarCtrl::GetMetrics`

`CToolBarCtrl::GetPadding`

`CToolBarCtrl::GetPressedImageList`

`CToolBarCtrl::GetRect`

`CToolBarCtrl::GetRows`

`CToolBarCtrl::GetState`

`CToolBarCtrl::GetString`