CMFCToolBarButton 类

为工具栏提供按钮功能。

语法

class CMFCToolBarButton : public CObject

成员

公共构造函数

名称	描述
CMFCToolBarButton::CMFCToolBarButton	构造并初始化一个 CMFCToolBarButton 对象。
CMFCToolBarButton::~CMFCToolBarButton	析构函数。

公共方法

名称	描述
CMFCToolBarButton::CanBeDropped	指定用户是否可以在自定义期间将按钮放置在工具栏或菜单上。
CMFCToolBarButton::CanBeStored	指定是否可以存储按钮。
CMFCToolBarButton::CanBeStretched	指定用户是否可以在自定义期间拉伸按钮。
CMFCToolBarButton::CompareWith	将此实例与提供的 CMFCToolBarButton 对象进行比较。
CMFCToolBarButton::CopyFrom	将另一个工具栏按钮的属性复制到当前按钮。
CMFCToolBarButton::CreateFromOleData	从提供的 COleDataObject 对象创建一个 CMFCToolBarButton 对象。
CMFCToolBarButton::CreateObject	由框架用于创建此类类型的动态实例。
CMFCToolBarButton::EnableWindow	启用或禁用鼠标和键盘输入。
CMFCToolBarButton::ExportToMenuButton	将文本从工具栏按钮复制到菜单。
CMFCToolBarButton::GetClipboardFormat	检索应用程序的全局剪贴板格式。
CMFCToolBarButton::GetHwnd	检索与工具栏按钮关联的窗口句柄。
CMFCToolBarButton::GetImage	检索按钮的图像索引。
CMFCToolBarButton::GetInvalidateRect	检索必须重新绘制的按钮的工作区的区域。
CMFCToolBarButton::GetParentWnd	检索按钮的父窗口。
CMFCToolBarButton::GetProtectedCommands	检索用户无法自定义的命令列表。
CMFCToolBarButton::GetTextSize	检索按钮文本的大小。
CMFCToolBarButton::HasFocus	确定按钮是否具有当前输入焦点。
CMFCToolBarButton::HaveHotBorder	确定当用户选择按钮时是否显示按钮的边框。
CMFCToolBarButton::IsDrawImage	确定按钮上是否显示图像。
CMFCToolBarButton::IsDrawText	确定按钮上是否显示文本标签。
CMFCToolBarButton::IsDroppedDown	确定按钮是否显示子菜单。
CMFCToolBarButton::IsEditable	确定是否可以自定义按钮。
CMFCToolBarButton::IsExtraSize	确定是否可以使用扩展边框显示按钮。
CMFCToolBarButton::IsFirstInGroup	确定按钮是否位于其按钮组的第一个位置。
CMFCToolBarButton::IsHidden	确定按钮是否隐藏。
CMFCToolBarButton::IsHorizontal	确定按钮是否位于水平工具栏上。
CMFCToolBarButton::IsLastInGroup	指定按钮是否位于其按钮组的最后一个位置。
CMFCToolBarButton::IsLocked	确定按钮是否位于锁定（不可自定义）的工具栏上。
CMFCToolBarButton::IsOwnerOf	确定按钮是否是提供的窗口句柄的所有者。
CMFCToolBarButton::IsVisible	确定工具栏按钮是否可见。
CMFCToolBarButton::IsWindowVisible	确定按钮的基础窗口句柄是否可见。
CMFCToolBarButton::NotifyCommand	指定按钮是否处理 WM_COMMAND 消息。
CMFCToolBarButton::OnAddToCustomizePage	当将按钮添加到“自定义”对话框时，由框架调用。
CMFCToolBarButton::OnBeforeDrag	指定是否可以拖动按钮。
CMFCToolBarButton::OnBeforeDrop	指定用户是否可以将按钮放置到目标工具栏上。
CMFCToolBarButton::OnCalculateSize	由框架调用，以计算指定设备上下文和停靠状态的按钮大小。
CMFCToolBarButton::OnCancelMode	由框架调用，用于处理 WM_CANCELMODE 消息。
CMFCToolBarButton::OnChangeParentWnd	当按钮插入新工具栏时由框架调用。
CMFCToolBarButton::OnClick	当用户单击鼠标按钮时由框架调用。
CMFCToolBarButton::OnClickUp	当用户释放鼠标按钮时由框架调用。
CMFCToolBarButton::OnContextHelp	当父工具栏处理 WM_HELPHITTEST 消息时由框架调用。
CMFCToolBarButton::OnCtlColor	当父工具栏处理 WM_CTLCOLOR 消息时，由框架调用。
CMFCToolBarButton::OnCustomizeMenu	当应用程序在父工具栏上显示快捷菜单时，允许该按钮修改所提供的菜单。
CMFCToolBarButton::OnDblClk	当父工具栏处理 WM_LBUTTONDBLCLK 消息时由框架调用。
CMFCToolBarButton::OnDraw	由框架调用，用于使用指定的样式和选项绘制按钮。
CMFCToolBarButton::OnDrawOnCustomizeList	由框架调用，用于在“自定义”对话框的“命令”窗格中绘制按钮。
CMFCToolBarButton::OnGetCustomToolTipText	由框架调用以检索按钮的自定义工具提示文本。
CMFCToolBarButton::OnGlobalFontsChanged	当更改全局字体时，由框架调用。
CMFCToolBarButton::OnMove	当父工具栏移动时，由框架调用。
CMFCToolBarButton::OnShow	当按钮变为可见或不可见时，由框架调用。
CMFCToolBarButton::OnSize	当父工具栏更改其大小或位置，并且此更改需要按钮改变大小时，由框架调用。
CMFCToolBarButton::OnToolHitTest	当父工具栏必须确定某个点是否位于按钮的边框中时，由框架调用。
CMFCToolBarButton::OnUpdateToolTip	当父工具栏更新其工具提示文本时，由框架调用。
CMFCToolBarButton::PrepareDrag	当按钮即将执行拖放操作时，由框架调用。
CMFCToolBarButton::Rect	检索按钮的边框。
CMFCToolBarButton::ResetImageToDefault	将与按钮关联的图像设置为默认值。
CMFCToolBarButton::SaveBarState	保存工具栏按钮的状态。
CMFCToolBarButton::Serialize	从存档中读取此对象或将其写入存档。 （重写 CObject::Serialize。）
CMFCToolBarButton::SetACCData	使用工具栏按钮中的辅助功能数据填充所提供的 CAccessibilityData 对象。
CMFCToolBarButton::SetClipboardFormatName	重命名全局剪贴板格式。
CMFCToolBarButton::SetImage	设置按钮的图像索引。
CMFCToolBarButton::SetProtectedCommands	设置用户无法自定义的命令列表。
CMFCToolBarButton::SetRadio	当按钮更改其选中状态时，由框架调用。
CMFCToolBarButton::SetRect	设置按钮的边框。
CMFCToolBarButton::SetStyle	设置按钮的样式。
CMFCToolBarButton::SetVisible	指定按钮是否可见。
CMFCToolBarButton::Show	显示或隐藏按钮。

数据成员

名称	描述
CMFCToolBarButton::m_bImage	指定是否在按钮上显示图像。
CMFCToolBarButton::m_bText	指定是否在按钮上显示文本标签。
CMFCToolBarButton::m_bTextBelow	指定文本标签是否显示在按钮的图像下方。
CMFCToolBarButton::m_bUserButton	指定按钮是否具有用户定义的图像。
CMFCToolBarButton::m_bWholeText	指定按钮是否显示其全文标签，即使它不在边框内。
CMFCToolBarButton::m_bWrap	指定是否将分隔符旁边的按钮置于下一行。
CMFCToolBarButton::m_bWrapText	指定是否启用多行文本标签。
CMFCToolBarButton::m_nID	按钮的命令 ID。
CMFCToolBarButton::m_nStyle	按钮的样式。
CMFCToolBarButton::m_strText	按钮的文本标签。

备注

CMFCToolbarButton 对象是驻留在工具栏上的控件。 其行为类似于普通按钮。 可以将图像和文本标签分配给此对象。 工具栏按钮还可以具有命令 ID。 当用户单击工具栏按钮时，框架将执行此 ID 指定的命令。

通常，可以自定义工具栏按钮：用户可以将按钮从一个工具栏拖动到另一个工具栏，并复制、粘贴、删除和编辑文本标签和图像。 若要防止用户自定义工具栏，可以通过以下两种方式之一锁定工具栏。 在调用 CMFCToolBar::LoadToolBar 时将 bLocked 标志设置为 TRUE，或是使用 CMFCToolBarButton::SetProtectedCommands 方法将单个按钮的命令 ID 添加到受保护命令的全局列表中。

CMFCToolBarButton 对象显示应用程序中工具栏图像的全局集合中的图像。 这些集合由父工具栏 CMFCToolBar 类维护。 有关详细信息，请参阅 CMFCToolBarImages 类。

当用户单击工具栏按钮时，其父工具栏会处理鼠标消息并将适当的操作传达给按钮。 如果按钮具有有效的命令 ID，则父工具栏会将 WM_COMMAND 消息发送到父框架。

CMFCToolBarButton 类是其他工具栏按钮类的基类，例如 CMFCToolBarMenuButton 类、CMFCToolBarEditBoxButton 类和 CMFCToolBarComboBoxButton 类。

示例

以下示例演示如何使用 CMFCToolBarButton 类中的各种方法配置 CMFCToolBarButton 对象。 该示例演示如何启用鼠标和键盘输入、设置按钮的图像索引、设置按钮的边框以及使按钮可见。 此代码段是选项卡控件示例的一部分。

CMFCToolBarButton *pOffice2007 = NULL;
int nIndex = -1;

for (UINT uiCmd = ID_VIEW_APPLOOK_2007_1; uiCmd <= ID_VIEW_APPLOOK_2007_4; uiCmd++)
{
   // CMFCToolBar m_wndToolBarTheme
   nIndex = m_wndToolBarTheme.CommandToIndex(uiCmd);

   CMFCToolBarButton *pButton = m_wndToolBarTheme.GetButton(nIndex);

   if (pButton != NULL)
   {
      pOffice2007 = pButton;
      break;
   }
}

pOffice2007->EnableWindow();
pOffice2007->SetImage(1);
pOffice2007->SetRect(CRect(1, 1, 1, 1));
pOffice2007->SetVisible();
pOffice2007->Show(true);

继承层次结构

CObject

CMFCToolBarButton

要求

标头：afxtoolbarbutton.h

CMFCToolBarButton::CanBeDropped

指定用户是否可以在自定义期间将按钮放置在工具栏或菜单上。

virtual BOOL CanBeDropped(CMFCToolBar* pToolbar);

参数

pToolBar
[in] 未使用。

返回值

该方法返回 TRUE。

备注

默认情况下，可以在每个可自定义（即非锁定）工具栏上放置一个工具栏按钮。

此方法的默认实现返回 TRUE。 如果要阻止用户重新定位按钮，请重写此方法并返回 FALSE。

CMFCToolBarButton::CanBeStored

确定是否可以存储按钮。

virtual BOOL CanBeStored() const;

返回值

该方法返回 TRUE。

备注

框架使用此方法来确定按钮是否可以参与拖放操作。

默认实现返回 TRUE。 如果按钮无法作为拖放操作的一部分存储，请重写此方法。 有关拖放操作的详细信息，请参阅 OLE 拖放。

CMFCToolBarButton::CanBeStretched

指定用户是否可以在自定义期间拉伸按钮。

virtual BOOL CanBeStretched() const;

返回值

此方法返回 FALSE。

备注

框架使用此方法来确定按钮是否可以在自定义模式下拉伸。

此方法的默认实现返回 FALSE。 重写此方法以对可变宽度控件（例如组合框或滑块）返回 TRUE。

有关自定义模式的详细信息，请参阅 CMFCToolBar::SetCustomizeMode。

CMFCToolBarButton::CMFCToolBarButton

构造并初始化一个 CMFCToolBarButton 对象。

CMFCToolBarButton(
    UINT uiID,
    int iImage,
    LPCTSTR lpszText=NULL,
    BOOL bUserButton=FALSE,
    BOOL bLocked=FALSE);

参数

uiID
[in] 按钮的命令 ID。

iImage
[in] 图像集合中按钮的图像索引。

lpszText
[in] 元素的文本标签。 可以为 NULL。

bUserButton
[in] 一个布尔值，用于确定按钮是否为用户定义的。 如果此参数为 TRUE，则按钮是用户定义的。 否则，按钮图像将从资源加载。

bLocked
[in] 一个布尔值，用于确定是否可以自定义按钮。 如果此参数为 TRUE，则无法自定义该按钮。 否则，可以自定义该按钮。

CMFCToolBarButton::CompareWith

将此实例与提供的 CMFCToolBarButton 对象进行比较。

virtual BOOL CompareWith(const CMFCToolBarButton& other) const;

参数

其他
[in] 对要与此实例进行比较的对象的引用。

返回值

如果提供的对象等于此实例的值，则为非零；否则为 0。

注解

默认实现确定所提供对象的命令 ID 是否等于该实例的命令 ID。 如果必须执行附加处理以确定两个 CMFCToolBarButton 对象是否相等，请重写此方法。

CMFCToolBarButton::CopyFrom

将另一个工具栏按钮的属性复制到当前按钮。

virtual void CopyFrom(const CMFCToolBarButton& src);

参数

src
[in] 对要从中复制的源按钮的引用。

注解

调用此方法，将另一个工具栏按钮复制到此工具栏按钮。

CMFCToolBarButton::CreateFromOleData

从提供的 COleDataObject 对象创建一个 CMFCToolBarButton 对象。

static CMFCToolBarButton* __stdcall CreateFromOleData(COleDataObject* pDataObject);

参数

pDataObject
[in] 源 OLE 数据对象。

返回值

创建的 CMFCToolBarButton 对象。

备注

框架使用此方法来执行各种格式的数据传输。 例如，CMFCOutlookBarPane::OnDragOver 方法使用此方法执行拖放操作。

CMFCToolBarButton::EnableWindow

启用或禁用鼠标和键盘输入。

virtual void EnableWindow(BOOL bEnable = TRUE);

参数

bEnable
[in] 将此参数设置为 TRUE 以启用输入，或设置为 FALSE 以禁用输入。

注解

此方法调用 EnableWindow 函数来启用或禁用输入。 有关详细信息，请参阅 Windows SDK 中的 EnableWindow。

CMFCToolBarButton::ExportToMenuButton

将文本从工具栏按钮复制到菜单。

virtual BOOL ExportToMenuButton(CMFCToolBarMenuButton& menuButton) const;

参数

menuButton
[in] 对目标菜单按钮的引用。

返回值

该方法返回 TRUE。

注解

框架调用此方法，将文本从工具栏按钮复制到菜单按钮。 默认实现复制按钮的文本标签。 如果文本标签为空，此方法将复制按钮的工具提示文本。

此方法的默认实现返回 TRUE。 如果想在框架将派生自 CMFCToolbarButton 的对象转换为菜单按钮时执行其他操作，请重写此方法。

CMFCToolBarButton::GetClipboardFormat

检索应用程序的全局剪贴板格式。

static CLIPFORMAT __stdcall GetClipboardFormat();

返回值

应用程序的全局 CLIPFORMAT 值。

注解

框架调用此方法以检索 OLE 数据传输操作的剪贴板格式。 例如，CMFCToolBarButton::CreateFromOleData 方法使用此方法从源 OLE 数据对象复制数据。

该方法在首次调用此方法时设置全局 CLIPFORMAT 值。 对此方法的所有后续调用均返回该值。

若要允许在应用程序之间进行拖放操作，请调用 CMFCToolBarButton::SetClipboardFormatName 方法。

有关 MFC 中剪贴板的详细信息，请参阅剪贴板。

CMFCToolBarButton::GetHwnd

检索与工具栏按钮关联的窗口句柄。

virtual HWND GetHwnd();

返回值

与工具栏按钮关联的窗口句柄；如果工具栏按钮没有关联的窗口句柄，则为 NULL。

备注

此方法的默认实现返回 NULL。 重写此方法以返回特定控件的窗口句柄。

CMFCToolBarButton::GetImage

检索按钮的图像索引。

int GetImage() const;

返回值

与此按钮关联的图像的索引。

备注

如果按钮具有用户定义的图像（即，如果 bUserButton 在构造函数中为 TRUE），则返回的索引指定用户定义图像集合中的图像（请参阅 CMFCToolBar::GetUserImages）。 否则，索引会指定从资源文件加载的图像集合中的图像（请参阅 CMFCToolBar::GetImages）。 有关资源文件的详细信息，请参阅使用资源文件。

CMFCToolBarButton::GetInvalidateRect

检索必须重新绘制的按钮的工作区的区域。

virtual const CRect GetInvalidateRect() const;

返回值

一个 CRect 对象，它指定必须重新绘制的区域。

备注

此方法的默认实现返回整个工作区。 如果希望重新绘制其他区域，请重写此方法。

CMFCToolBarButton::GetParentWnd

检索按钮的父窗口。

CWnd* GetParentWnd() const;

返回值

按钮的父窗口。

CMFCToolBarButton::GetProtectedCommands

检索用户无法自定义的命令列表。

static const CList<UINT,UINT>& GetProtectedCommands();

返回值

受保护命令的列表。

备注

在自定义模式下，框架会禁用受保护的工具栏按钮命令。 用户无法在禁用的工具栏按钮上执行拖放和编辑操作。

使用 CMFCToolBarButton::SetProtectedCommands 方法定义受保护命令的列表。

CMFCToolBarButton::GetTextSize

检索按钮文本的大小。

SIZE GetTextSize() const;

返回值

一个 SIZE 对象，包含按钮文本的大小（以像素为单位）。

CMFCToolBarButton::HasFocus

确定按钮是否具有当前输入焦点。

virtual BOOL HasFocus() const;

返回值

如果按钮具有输入焦点，则为非零；否则为 0。

备注

如果按钮具有输入焦点或者是具有输入焦点的窗口的子窗口或后代窗口，则此方法的默认实现返回非零。 可以重写此函数以自定义此行为。

CMFCToolBarButton::HaveHotBorder

确定当用户选择按钮时是否显示按钮的边框。

virtual BOOL HaveHotBorder() const;

返回值

该方法返回 TRUE。

备注

框架调用此方法以确定当用户选择工具栏按钮时是否应显示其边框。

默认实现返回 TRUE。 可以重写此方法来自定义此行为。

CMFCToolBarButton::IsDrawImage

确定按钮上是否显示图像。

BOOL IsDrawImage() const;

返回值

如果按钮上显示图像，则为非零；否则为 0。

备注

如果工具栏按钮没有关联的图像（CMFCToolBarButton::GetImage 返回 -1）或者如果 CMFCToolBarButton::m_bImage 设置为 FALSE，则此方法返回 FALSE。

CMFCToolBarButton::IsDrawText

确定按钮上是否显示文本标签。

BOOL IsDrawText() const;

返回值

如果显示文本标签，则为非零；否则为 0。

备注

如果工具栏按钮没有关联的文本标签（CMFCToolBarButton::m_strText 为空）或 CMFCToolBarButton::m_bText 设置为 FALSE，则此方法返回 FALSE。

CMFCToolBarButton::IsDroppedDown

确定按钮是否显示子菜单。

virtual BOOL IsDroppedDown() const;

返回值

此方法返回 FALSE。

注解

此方法的默认实现返回 FALSE。 如果控件显示子菜单，请重写此方法以返回 TRUE。

CMFCToolBarButton::IsEditable

确定是否可以自定义按钮。

virtual BOOL IsEditable() const;

返回值

如果用户可以自定义按钮，则为非零；否则为 0。

注解

框架调用此方法以确定用户是否可以使用拖放或编辑操作自定义工具栏按钮。

如果按钮的命令 ID 是标准命令（可以通过调用 IsStandardCommand 函数来确定）或命令 ID 位于受保护命令列表中，则默认实现返回 FALSE。 有关受保护命令的详细信息，请参阅 CMFCToolBarButton::GetProtectedCommands 和 CMFCToolBarButton::SetProtectedCommands。

重写此方法以自定义其行为。

CMFCToolBarButton::IsExtraSize

确定是否可以使用扩展边框显示按钮。

virtual BOOL IsExtraSize() const;

返回值

如果工具栏按钮可以用扩展边框显示，返回值为非零；否则返回值为 0。

备注

有些外观对工具栏按钮的边框使用了额外的尺寸（例如，圆形按钮）。

如果用户将此按钮从一个工具栏移动到另一个工具栏，框架会调用 CMFCToolBarButton::OnChangeParentWnd 方法。 CMFCToolBarButton::OnChangeParentWnd 方法将额外大小标志设置为新父工具栏的标志（有关详细信息，请参阅 CMFCToolBar::IsButtonExtraSizeAvailable）。

CMFCToolBarButton::IsFirstInGroup

确定按钮是否位于其按钮组的第一个位置。

virtual BOOL IsFirstInGroup() const;

返回值

如果按钮是其按钮组中的第一个按钮，则为 TRUE；否则为 FALSE。

备注

此方法将“按钮组”定义为一组相邻的按钮，这些按钮位于同一行并以分隔符或工具栏的边框为界。 如果工具栏按钮引用“自定义”按钮，则此方法返回 FALSE。 有关“自定义”按钮的详细信息，请参阅 CMFCToolBar::GetCustomizeButton。

调用 CMFCToolBarButton::IsLastInGroup 方法来确定按钮是否位于其按钮组中的最后一个位置。

CMFCToolBarButton::IsHidden

确定按钮是否隐藏。

BOOL IsHidden() const;

返回值

如果按钮已隐藏（不可见），则为非零；否则为 0。

备注

当拉伸父工具栏以确定工具栏按钮是否可见时，框架会调用此方法。

如果使用 CMFCToolBarButton::SetVisible 方法将按钮设置为不可见，请使用 CMFCToolBarButton::IsVisible 确定工具栏按钮是否可见。

默认情况下，所有工具栏按钮都可见。 使用 CMFCToolBarButton::Show 方法隐藏或显示工具栏按钮。

CMFCToolBarButton::IsHorizontal

确定按钮是否位于水平工具栏上。

BOOL IsHorizontal() const;

返回值

如果工具栏按钮位于水平工具栏上，则为非零；否则为 0。

备注

框架调用此方法来确定工具栏按钮的布局。

此方法返回 m_bHorz 数据成员。 m_bHorz 数据成员的默认值为 TRUE；它会在每次调用 CMFCToolBarButton::OnDraw 方法时重置。

CMFCToolBarButton::IsLastInGroup

指定按钮是否位于其按钮组的最后一个位置。

virtual BOOL IsLastInGroup() const;

返回值

如果按钮是其按钮组中的最后一个按钮，则为 TRUE；否则为 FALSE。

注解

此方法将“按钮组”定义为一组相邻的按钮，这些按钮位于同一行并以分隔符或工具栏的边框为界。如果工具栏按钮没有父工具栏或工具栏按钮引用“自定义”按钮，则此方法返回 FALSE。 有关“自定义”按钮的详细信息，请参阅 CMFCToolBar::GetCustomizeButton。

调用 CMFCToolBarButton::IsFirstInGroup 方法来确定按钮是否位于其按钮组中的第一个位置。

CMFCToolBarButton::IsLocked

确定按钮是否位于锁定（不可自定义）的工具栏上。

BOOL IsLocked() const;

返回值

如果按钮位于锁定工具栏上，则为非零；否则为 0。

备注

框架调用此方法以确定用户是否可以使用拖放或编辑操作自定义工具栏按钮。 使用 CMFCToolBar::LoadToolBar 方法设置父工具栏上的锁定属性。 框架将此属性的值传递给它插入父工具栏的每个工具栏按钮 (CMFCToolbarButton) 的构造函数。

CMFCToolBarButton::IsOwnerOf

确定按钮是否是提供的窗口句柄的所有者。

virtual BOOL IsOwnerOf(HWND hwnd);

参数

hwnd
[in] 窗口句柄。

返回值

如果按钮是提供的窗口句柄的所有者，则为非零；否则为 0。

备注

如果 hwnd 引用直接窗口句柄或者是与按钮关联的窗口句柄的子句柄，则此方法返回非零值。 如果 hwnd 为 NULL，此方法返回 0。

CMFCToolBarButton::IsVisible

确定工具栏按钮是否可见。

BOOL IsVisible() const;

返回值

如果工具栏按钮可见，则非零；否则为 0。

备注

可以使用 CMFCToolBarButton::SetVisible 方法显示或隐藏工具栏按钮。 在调用 CMFCToolBarButton::SetVisible 以重新计算父工具栏的布局后，请调用在父工具栏上调用 CPane::AdjustSizeImmediate 方法。

CMFCToolBarButton::IsWindowVisible

确定按钮的基础窗口句柄是否可见。

virtual BOOL IsWindowVisible();

返回值

如果按钮的基础窗口句柄可见，则为非零；否则为 0。

备注

如果基础窗口句柄的样式属性包含 WS_VISIBLE 样式，则此方法返回非零值。 如果按钮的基础窗口句柄为 NULL，则此方法返回 FALSE。

CMFCToolBarButton::m_bImage

指定是否在按钮上显示图像。

BOOL m_bImage;

备注

如果此数据成员设置为 TRUE，则框架显示与工具栏按钮关联的图像；否则框架不显示图像。 此成员会影响 CMFCToolBarButton::m_bImage 方法的返回值。

CMFCToolBarButton::m_bText

指定是否在按钮上显示文本标签。

BOOL m_bText;

备注

如果此数据成员设置为 TRUE，则框架显示工具栏按钮的文本标签；否则框架不显示文本标签。 此成员会影响 CMFCToolBarButton::m_bText 方法的返回值。

CMFCToolBarButton::m_bTextBelow

指定文本标签是否显示在按钮的图像下方。

BOOL m_bTextBelow;

备注

如果此成员变量设置为 TRUE，则框架会在图像下方显示按钮的文本。 此成员的默认值为 FALSE。

CMFCToolBarButton::m_bUserButton

指定按钮是否具有用户定义的图像

BOOL m_bUserButton;

备注

当按钮具有与之关联的用户定义图像时，此数据成员设置为 TRUE。

CMFCToolBarButton::m_bWholeText

指定按钮是否显示其全文标签，即使它不在边框内。

BOOL m_bWholeText;

注解

如果此数据成员设置为 TRUE，则框架通过放大按钮显示全文标签。 否则，框架会截断并将省略号 (...) 追加到文本标签。

CMFCToolBarButton::m_bWrap

指定是否将分隔符旁边的按钮置于下一行。

BOOL m_bWrap;

注解

当工具栏按钮不适合当前行或你指定了布局（例如，每行特定数量的工具栏按钮）时，框架会将此数据成员设置为 TRUE。

如果此数据成员设置为 TRUE 并且工具栏水平停靠或浮动，则框架会将此按钮置于下一行。

此数据成员的默认值为 FALSE。

CMFCToolBarButton::m_bWrapText

指定是否启用多行文本标签。

AFX_IMPORT_DATA static BOOL m_bWrapText;

注解

如果此静态成员变量为 TRUE，则框架允许所有工具栏在工具栏按钮上显示多行文本标签。

此数据成员的默认值为 FALSE。

CMFCToolBarButton::m_nID

按钮的命令 ID。

UINT m_nID;

注解

命令 ID 为 -1 表示该按钮是分隔符。 所有按钮分隔符都具有 TBBS_SEPARATOR 样式。 有关按钮样式的详细信息，请参阅 CMFCToolBarButton::m_nStyle。

CMFCToolBarButton::m_nStyle

按钮的样式。

UINT m_nStyle;

备注

有关可用工具栏按钮样式的列表，请参阅工具栏控件样式。

CMFCToolBarButton::m_strText

按钮的文本标签。

CString m_strText;

备注

此数据成员包含按钮的文本标签。 文本标签可以为空。

CMFCToolBarButton::NotifyCommand

指定按钮是否处理 WM_COMMAND 消息。

virtual BOOL NotifyCommand(int iNotifyCode);

参数

iNotifyCode
[in] 与命令关联的通知消息。

返回值

此方法返回 FALSE。

备注

当即将向父窗口发送 WM_COMMAND 消息时，框架会调用此方法。

默认情况下，此方法返回 FALSE。 如果你要处理 WM_COMMAND 消息，则重写此方法以返回 TRUE，或者返回 FALSE 以指示父工具栏应处理此消息。

CMFCToolBarButton::OnAddToCustomizePage

当将按钮添加到“自定义”对话框时，由框架调用。

virtual void OnAddToCustomizePage();

备注

此方法的默认实现不执行任何操作。 如果要在将按钮添加到“自定义”对话框时执行某些操作，请重写此方法。

CMFCToolBarButton::OnBeforeDrag

指定是否可以拖动按钮。

virtual BOOL OnBeforeDrag() const;

返回值

如果可以拖动按钮，则为 TRUE；否则为 FALSE。

注解

框架在用户开始拖动按钮之前调用此方法。

此方法的默认实现返回 TRUE。 重写此方法返回 FALSE 以禁用按钮拖动。

CMFCToolBarButton::OnBeforeDrop

指定用户是否可以将按钮放置到目标工具栏上。

virtual BOOL OnBeforeDrop(CMFCToolBar* pTarget);

参数

pTarget
[in] 拖放操作的目标。

返回值

如果可以将按钮放置到提供的目标工具栏上，则为 TRUE；否则为 FALSE。

备注

在将按钮放置到工具栏上之前，框架会调用此方法。

此方法的默认实现返回 TRUE。 重写此方法返回 FALSE 以禁用对指定目标的放置操作。

CMFCToolBarButton::OnCalculateSize

由框架调用，以计算指定设备上下文和停靠状态的按钮大小。

virtual SIZE OnCalculateSize(
    CDC* pDC,
    const CSize& sizeDefault,
    BOOL bHorz);

参数

pDC
[in] 显示按钮的设备上下文。

sizeDefault
[in] 按钮的默认大小。

bHorz
[in] 父工具栏的停靠状态。 如果工具栏水平停靠或浮动，此参数为 TRUE；如果工具栏垂直停靠，则为 FALSE。

返回值

包含按钮维度的 SIZE 结构（以像素为单位）。

注解

框架调用此方法以确定指定设备上下文和停靠状态的工具栏按钮的大小。

默认实现会考虑文本和图像大小（如果显示）、文本和图像位置（文本位于图像下方或右侧）以及工具栏停靠状态。

如果要提供非标准按钮（例如，编辑框按钮）的大小，请重写此方法。

CMFCToolBarButton::OnCancelMode

由框架调用，用于处理 WM_CANCELMODE 消息。

virtual void OnCancelMode();

注解

此方法的默认实现不执行任何操作。 如果要处理 WM_CANCELMODE 消息，请重写此方法。

CMFCToolBarButton::OnChangeParentWnd

当按钮插入新工具栏时由框架调用。

virtual void OnChangeParentWnd(CWnd* pWndParent);

参数

pWndParent
[in] 新的父窗口。

备注

例如，当用户将按钮从一个工具栏拖动到另一个工具栏时，该按钮将插入工具栏中。

此方法的默认实现不执行任何操作。

CMFCToolBarButton::OnClick

当用户单击鼠标按钮时由框架调用。

virtual BOOL OnClick(
    CWnd* pWnd,
    BOOL bDelay=TRUE);

参数

pWnd
[in] 工具栏按钮的父窗口。

bDelay
[in] 如果消息应以延迟处理，则为 TRUE。

返回值

此方法返回 FALSE。

备注

当用户单击工具栏按钮时，框架将调用此方法。

默认实现不执行任何操作并返回 FALSE。 如果按钮处理单击消息，请重写此方法以返回非零值。

CMFCToolBarButton::OnClickUp

当用户释放鼠标按钮时由框架调用。

virtual BOOL OnClickUp();

返回值

此方法返回 FALSE。

注解

当用户释放工具栏按钮时，框架将调用此方法。

默认实现不执行任何操作并返回 FALSE。 如果按钮处理单击消息，请重写此方法以返回非零值。

CMFCToolBarButton::OnContextHelp

当父工具栏处理 WM_HELPHITTEST 消息时由框架调用。

virtual BOOL OnContextHelp(CWnd* pWnd);

参数

pWnd
[in] 工具栏按钮的父窗口。

返回值

此方法返回 FALSE。

注解

此方法的默认实现不执行任何操作并返回 FALSE。 如果按钮处理帮助消息，请重写此方法以返回非零值。

有关 WM_HELPHITTEST 消息的详细信息，请参阅 TN028：上下文关联帮助支持。

CMFCToolBarButton::OnCtlColor

当父工具栏处理 WM_CTLCOLOR 消息时，由框架调用。

virtual HBRUSH OnCtlColor(
    CDC* pDC,
    UINT nCtlColor);

参数

pDC
[in] 显示按钮的设备上下文。

nCtlColor
[in] 特定颜色通知。

返回值

框架用于绘制按钮背景的画笔对象的句柄。

备注

当父工具栏处理包含 Windows 控件的工具栏按钮的 WM_CTLCOLOR 消息时，框架将调用此方法。 如果工具栏按钮无窗口，框架不会调用此方法。

当工具栏框架处于自定义模式且工具栏按钮处于解锁状态时，框架将调用此方法。 有关自定义模式的详细信息，请参阅 CMFCToolBar::SetCustomizeMode。 有关锁定工具栏按钮的详细信息，请参阅 CMFCToolBarButton::IsLocked。

默认实现不执行任何操作并返回 NULL。

CMFCToolBarButton::OnCustomizeMenu

当应用程序在父工具栏上显示快捷菜单时，允许该按钮修改所提供的菜单。

virtual BOOL OnCustomizeMenu(CMenu* pMenu);

参数

pMenu
[in] 要自定义的菜单。

返回值

此方法返回 FALSE。

备注

默认实现不执行任何操作并返回 FALSE。 如果要修改所提供的菜单的内容，请重写此方法并返回非零值。

CMFCToolBarButton::OnDblClk

当父工具栏处理 WM_LBUTTONDBLCLK 消息时由框架调用。

virtual void OnDblClk(CWnd* pWnd);

参数

pWnd
[in] - 按钮的父窗口。

备注

当父工具栏处理 WM_LBUTTONDBLCLK 消息时，此方法由 CMFCToolBar::OnLButtonDblClk 方法调用。

此方法的默认实现不执行任何操作。

CMFCToolBarButton::OnDraw

由框架调用，用于使用指定的样式和选项绘制按钮。

virtual void OnDraw(
    CDC* pDC,
    const CRect& rect,
    CMFCToolBarImages* pImages,
    BOOL bHorz=TRUE,
    BOOL bCustomizeMode=FALSE,
    BOOL bHighlight=FALSE,
    BOOL bDrawBorder=TRUE,
    BOOL bGrayDisabledButtons=TRUE);

参数

pDC
[in] 显示按钮的设备上下文。

rect
[in] 按钮的范围框。

pImages
[in] 关联按钮的工具栏图像集合。

bHorz
[in] 父工具栏的停靠状态。 当按钮水平停靠时，此参数为 TRUE，当按钮垂直停靠时，此参数为 FALSE。

bCustomizeMode
[in] 指定工具栏是否处于自定义模式。 当工具栏处于自定义模式时，此参数为 TRUE，当工具栏未处于自定义模式时，此参数为 FALSE。

bHighlight
[in] 指定是否突出显示按钮。 当按钮突出显示时，此参数为 TRUE，当按钮未突出显示时，此参数为 FALSE。

bDrawBorder
[in] 指定按钮是否应显示其边框。 当按钮应显示其边框时，此参数为 TRUE，当按钮不应显示其边框时，此参数为 FALSE。

bGrayDisabledButtons
[in] 指定是对禁用的按钮进行阴影处理还是使用禁用的图像集合。 如果应对禁用的按钮进行阴影处理，则此参数为 TRUE，如果此方法应使用禁用的图像集合，则为 FALSE。

注解

替代此方法来自定义工具栏按钮绘图。

CMFCToolBarButton::OnDrawOnCustomizeList

由框架调用，用于在“自定义”对话框的“命令”窗格中绘制按钮。

virtual int OnDrawOnCustomizeList(
    CDC* pDC,
    const CRect& rect,
    BOOL bSelected);

参数

pDC
[in] 显示按钮的设备上下文。

rect
[in] 按钮的范围框。

bSelected
[in] 指定是否选择该按钮。 如果此参数为 TRUE，则选择该按钮。 如果此参数为 FALSE，则不选择该按钮。

返回值

指定设备上下文上按钮的宽度（以像素为单位）。

备注

当按钮即将在所有者绘制列表框中显示自身时，“自定义”对话框（“命令”选项卡）调用此方法。

此方法的默认实现显示按钮的图像和文本标签（如果可用）。 如果按钮的文本标签不可用，该方法将显示工具提示文本。

重写此方法以执行自定义绘制。

CMFCToolBarButton::OnGetCustomToolTipText

由框架调用以检索按钮的自定义工具提示文本。

virtual BOOL OnGetCustomToolTipText(CString& strToolTip);

参数

strToolTip
[out] 接收自定义工具提示文本的 CString 对象。

返回值

此方法返回 FALSE。

注解

框架在显示工具栏按钮的工具提示时调用此方法。 如果此方法返回 FALSE，框架将使用默认工具提示。

默认实现不执行任何操作并返回 FALSE。 重写此方法并返回非零值，为工具栏按钮提供自定义工具提示文本。

CMFCToolBarButton::OnGlobalFontsChanged

当更改全局字体时，由框架调用。

virtual void OnGlobalFontsChanged();

注解

此方法的默认实现不执行任何操作。 重写此方法以更新用于显示按钮文本的字体。

CMFCToolBarButton::OnMove

当父工具栏移动时，由框架调用。

virtual void OnMove();

备注

此方法的默认实现不执行任何操作。 重写此方法以在父工具栏移动时重新定位按钮。

CMFCToolBarButton::OnShow

当按钮变为可见或不可见时，由框架调用。

virtual void OnShow(BOOL bShow);

参数

bShow
[in] 指定按钮是否可见。 如果此参数为 TRUE，则按钮可见。 否则，按钮不可见。

注解

此方法的默认实现不执行任何操作。 重写此方法以更新按钮的可见性。

CMFCToolBarButton::OnSize

当父工具栏更改其大小或位置并且此更改导致按钮大小发生更改时，由框架调用。

virtual void OnSize(int iSize);

参数

iSize
[in] 按钮的新宽度。

备注

此方法的默认实现不执行任何操作。 重写此方法以在父工具栏的大小或位置发生更改时重设按钮的大小。

CMFCToolBarButton::OnToolHitTest

当父工具栏必须确定某个点是否位于按钮的边框中时，由框架调用。

virtual BOOL OnToolHitTest(
    const CWnd* pWnd,
    TOOLINFO* pTI);

参数

pWnd
[in] 按钮的父窗口。 可以为 NULL。

pTI
[in] TOOLINFO 结构，其中包含有关工具提示控件中工具的信息。

返回值

如果按钮可以检索指向父框架窗口的指针，则为 OnMenuButtonToolHitTest 的结果；否则为 FALSE。

注解

如果此方法可以将父窗口转换为有效的框架对象，则调用以下方法之一：

• CMDIFrameWndEx::OnMenuButtonToolHitTest

• CFrameWndEx::OnMenuButtonToolHitTest

• COleIPFrameWndEx::OnMenuButtonToolHitTest

CMFCToolBarButton::OnUpdateToolTip

当父工具栏更新其工具提示文本时，由框架调用。

virtual BOOL OnUpdateToolTip(
    CWnd* pWndParent,
    int iButtonIndex,
    CToolTipCtrl& wndToolTip,
    CString& str);

参数

pWndParent
[in] 父窗口。

iButtonIndex
[in] 父按钮集合中按钮的从零开始的索引。

wndToolTip
[in] 显示工具提示文本的控件。

str
[out] 接收更新的工具提示文本的 CString 对象。

返回值

此方法返回 FALSE。

备注

此方法的默认实现不执行任何操作并返回 FALSE。 如果提供工具提示文本字符串，请重写此方法以返回非零值。

CMFCToolBarButton::PrepareDrag

当按钮即将执行拖放操作时，由框架调用。

virtual BOOL PrepareDrag(COleDataSource& srcItem);

参数

srcItem
[in] 一个 COleDataSource 对象，用于存储有关拖放操作的状态信息。

返回值

如果操作成功，则为 TRUE；否则为 FALSE。

备注

框架调用此方法来准备工具栏按钮以将其状态存储在提供的 COleDataSource 对象中。 此方法通过将自身序列化为共享文件并将该文件传递给 COleDataSource::CacheGlobalData 方法来存储其状态。 有关工具栏按钮序列化的详细信息，请参阅 CMFCToolBarButton::Serialize。

如果无法存储按钮，则此方法不执行任何操作并返回 TRUE（CMFCToolBarButton::CanBeStored 方法返回 FALSE）。 如果在对象序列化期间发生异常，它将返回 FALSE。

有关 OLE 拖放操作的详细信息，请参阅 OLE 拖放。

CMFCToolBarButton::Rect

检索按钮的边框。

const CRect& Rect() const;

返回值

一个包含按钮边框的 CRect 对象。

CMFCToolBarButton::ResetImageToDefault

将与按钮关联的图像设置为默认值。

virtual void ResetImageToDefault();

备注

此方法使用 CMFCToolBar::GetDefaultImage 方法从其父工具栏中检索默认图像。 如果按钮没有关联的默认图像，则此方法使用 CStringT::LoadString 方法根据其字符串资源设置按钮的文本标签。 有关字符串资源的详细信息，请参阅使用资源文件。

如果按钮具有用户定义的图像，则此方法不执行任何操作。

CMFCToolBarButton::SaveBarState

保存工具栏按钮的状态。

virtual void SaveBarState();

注解

当作为拖放操作的结果创建 CMFCToolBarButton 对象时，框架将调用此方法。

此方法的默认实现不执行任何操作。 重写此方法，将工具栏按钮的状态保存到外部数据源。

CMFCToolBarButton::Serialize

从存档中读取此对象或将其写入存档。

virtual void Serialize(CArchive& ar);

参数

ar
[in] 要从其进行序列化或要序列化为的 CArchive 对象。

备注

此方法支持数据传输过程，例如剪贴板或拖放操作。 它从/向提供的 CArchive 对象读取/写入按钮的属性，例如 ID、文本标签和图像 ID。

有关序列化示例，请参阅序列化：对象的序列化。

CMFCToolBarButton::SetACCData

使用工具栏按钮中的辅助功能数据填充所提供的 CAccessibilityData 对象。

virtual BOOL SetACCData(
    CWnd* pParent,
    CAccessibilityData& data);

参数

pParent
[in] 工具栏按钮的父窗口。

data
[in] 使用工具栏按钮的辅助功能数据填充的 CAccessibilityData 对象。

返回值

该方法返回 TRUE。

注解

如果工具栏按钮不提供辅助功能数据，请重写此方法以返回 FALSE。

CMFCToolBarButton::SetClipboardFormatName

重命名全局剪贴板格式。

static void __stdcall SetClipboardFormatName(LPCTSTR lpszName);

参数

lpszName
[in] 全局剪贴板格式的新名称。 不能为 NULL。

注解

通过此方法，可以在多个应用程序之间执行拖放操作。 每个应用程序必须提供相同的剪贴板格式名称。

必须在框架调用 CMFCToolBarButton::GetClipboardFormat 之前调用此方法。

CMFCToolBarButton::SetImage

设置按钮的图像索引。

virtual void SetImage(int iImage);

参数

iImage
[in] 工具栏图像集合中图像的索引。

备注

如果工具栏按钮是一个分隔符，则 iImage 指的是分隔符按钮的新宽度。

如果 iImage 小于零，则此方法会禁用图像绘制并启用按钮文本标签的绘制。

CMFCToolBarButton::SetProtectedCommands

设置用户无法自定义的命令列表。

static void SetProtectedCommands(const CList<UINT,UINT>& lstCmds);

参数

lstCmds
[in] 受保护命令的列表。

备注

在自定义模式下，框架会禁用受保护的工具栏按钮命令。 用户无法在禁用的工具栏按钮上执行拖放和编辑操作。

使用 CMFCToolBarButton::GetProtectedCommands 方法检索受保护命令的列表。

CMFCToolBarButton::SetRadio

当按钮更改其选中状态时，由框架调用。

virtual void SetRadio();

备注

此方法的默认实现不执行任何操作。 重写此方法以在按钮更改其选中状态时执行自定义操作。

CMFCToolBarButton::SetRect

设置按钮的边框。

void SetRect(const CRect rect);

参数

rect
[in] 按钮的新边框。

备注

此方法在设置新的边框后调用 CMFCToolBarButton::OnMove 方法。

CMFCToolBarButton::SetStyle

设置按钮的样式。

virtual void SetStyle(UINT nStyle);

参数

nStyle
[in] 按钮的新样式。

注解

默认实现将 CMFCToolBarButton::m_nStyle 数据成员设置为 nStyle。 如果要执行额外的处理来处理样式的更改，请重写此方法。 有关有效样式标志的列表，请参阅工具栏控件样式。

CMFCToolBarButton::SetVisible

指定按钮是否可见。

void SetVisible(BOOL bShow=TRUE);

参数

bShow
[in] 一个布尔值，指定是显示还是隐藏按钮。 如果此参数为 TRUE，则显示按钮。 如果此参数为 FALSE，则隐藏按钮。

备注

使用此函数可隐藏或显示特定工具栏按钮。 调用此方法后调用 CPanel::Adjust Size Immediate 方法。

CMFCToolBarButton::Show

显示或隐藏按钮。

void Show(BOOL bShow);

参数

bShow
[in] 一个布尔值，指定是显示还是隐藏按钮。 如果此参数为 TRUE，则显示按钮。 如果此参数为 FALSE，则隐藏按钮。

备注

当重设工具栏按钮的父工具栏的大小时，框架将调用此方法来更新工具栏按钮的可见性。 当按钮大小超出工具栏的边界时，框架将调用此方法并将 bShow 设置为 FALSE。 将按钮大小重新调整到工具栏边界内时，框架会调用此方法并将 bShow 设置为 TRUE。

使用 CMFCToolBarButton::SetVisible 方法设置按钮的一般可见性。

此方法在更新按钮的可见性状态后调用 CMFCToolBarButton::OnShow 方法。

另请参阅

层次结构图
类
CMFCToolBar 类
CMFCToolBarImages 类