CMFCToolBarMenuButton 类

包含一个弹出菜单的工具栏按钮。 有关详细信息,请参阅所安装的 Visual Studio 的 C\atlmfc\src\mfc 文件夹中的源代码。

语法

class CMFCToolBarMenuButton : public CMFCToolBarButton

成员

公共构造函数

名称 描述
CMFCToolBarMenuButton::CMFCToolBarMenuButton 构造 CMFCToolBarMenuButton 对象。

公共方法

名称 描述
CMFCToolBarMenuButton::CompareWith 将此实例与提供的 CMFCToolBarButton 对象进行比较。 (替代 CMFCToolBarButton::CompareWith。)
CMFCToolBarMenuButton::CopyFrom 将另一个工具栏按钮的属性复制到当前按钮。 (替代 CMFCToolBarButton::CopyFrom。)
CMFCToolBarMenuButton::CreateFromMenu 从 Windows 菜单句柄初始化工具栏菜单。
CMFCToolBarMenuButton::CreateMenu 创建一个由工具栏菜单中的命令组成的 Windows 菜单。 返回 Windows 菜单的句柄。
CMFCToolBarMenuButton::CreatePopupMenu 创建一个弹出菜单对象(CMFCPopupMenu 类)以显示工具栏菜单。
CMFCToolBarMenuButton::EnableQuickCustomize
CMFCToolBarMenuButton::GetCommands 提供对工具栏菜单中命令列表的只读访问权限。
CMFCToolBarMenuButton::GetImageRect 检索按钮图像的边框。
CMFCToolBarMenuButton::GetPaletteRows 当菜单处于调色板模式时,返回弹出菜单中的行数。
CMFCToolBarMenuButton::GetPopupMenu 返回指向与按钮关联的弹出菜单对象的指针。
CMFCToolBarMenuButton::HasButton
CMFCToolBarMenuButton::HaveHotBorder 确定当用户选择按钮时是否显示按钮的边框。 (替代 CMFCToolBarButton::HaveHotBorder。)
CMFCToolBarMenuButton::IsBorder
CMFCToolBarMenuButton::IsClickedOnMenu
CMFCToolBarMenuButton::IsDroppedDown 确定是否显示弹出菜单。
CMFCToolBarMenuButton::IsEmptyMenuAllowed 由框架调用,用于确定用户是否可以从所选菜单项打开子菜单。
CMFCToolBarMenuButton::IsExclusive 确定该按钮是否处于独占模式,也就是说,即使用户将指针移到另一个工具栏或按钮上,弹出菜单是否也保持打开状态。
CMFCToolBarMenuButton::IsMenuPaletteMode 确定弹出菜单是否处于调色板模式。
CMFCToolBarMenuButton::IsQuickMode
CMFCToolBarMenuButton::IsTearOffMenu 确定弹出菜单是否具有拖曳栏。
CMFCToolBarMenuButton::OnAfterCreatePopupMenu
CMFCToolBarMenuButton::OnBeforeDrag 指定是否可以拖动按钮。 (替代 CMFCToolBarButton::OnBeforeDrag。)
CMFCToolBarMenuButton::OnCalculateSize 由框架调用,以计算指定设备上下文和停靠状态的按钮大小。 (替代 CMFCToolBarButton::OnCalculateSize。)
CMFCToolBarMenuButton::OnCancelMode 由框架调用,用于处理 WM_CANCELMODE 消息。 (替代 CMFCToolBarButton::OnCancelMode。)
CMFCToolBarMenuButton::OnChangeParentWnd 当按钮插入新工具栏时由框架调用。 (替代 CMFCToolBarButton::OnChangeParentWnd。)
CMFCToolBarMenuButton::OnClick 当用户单击鼠标按钮时由框架调用。 (替代 CMFCToolBarButton::OnClick。)
CMFCToolBarMenuButton::OnClickMenuItem 当用户在弹出菜单中选择项时由框架调用。
CMFCToolBarMenuButton::OnContextHelp 当父工具栏处理 WM_HELPHITTEST 消息时由框架调用。 (替代 CMFCToolBarButton::OnContextHelp。)
CMFCToolBarMenuButton::OnDraw 由框架调用,用于使用指定的样式和选项绘制按钮。 (替代 CMFCToolBarButton::OnDraw。)
CMFCToolBarMenuButton::OnDrawOnCustomizeList 由框架调用,用于在“自定义”对话框的“命令”窗格中绘制按钮。 (替代 CMFCToolBarButton::OnDrawOnCustomizeList。)
CMFCToolBarMenuButton::OpenPopupMenu 当用户打开弹出菜单时由框架调用。
CMFCToolBarMenuButton::ResetImageToDefault 将与按钮关联的图像设置为默认值。 (替代 CMFCToolBarButton::ResetImageToDefault。)
CMFCToolBarMenuButton::SaveBarState 保存工具栏按钮的状态。 (替代 CMFCToolBarButton::SaveBarState。)
CMFCToolBarMenuButton::Serialize 从存档中读取此对象或将其写入存档。 (替代 CMFCToolBarButton::Serialize。)
CMFCToolBarMenuButton::SetACCData 使用工具栏按钮中的辅助功能数据填充所提供的 CAccessibilityData 对象。 (替代 CMFCToolBarButton::SetACCData。)
CMFCToolBarMenuButton::SetMenuOnly 指定是否可以将按钮添加到工具栏。
CMFCToolBarMenuButton::SetMenuPaletteMode 指定弹出菜单是否处于调色板模式。
CMFCToolBarMenuButton::SetMessageWnd
CMFCToolBarMenuButton::SetRadio 强制工具栏菜单按钮显示一个图标,指示它处于选中状态。
CMFCToolBarMenuButton::SetTearOff 指定弹出菜单的拖曳栏 ID。

受保护方法

名称 描述
CMFCToolBarMenuButton::DrawDocumentIcon 在菜单按钮上绘制图标。

数据成员

名称 描述
CMFCToolBarMenuButton::m_bAlwaysCallOwnerDraw 如果为 TRUE,则框架在绘制按钮时始终调用 CFrameWndEx::OnDrawMenuImage

备注

CMFCToolBarMenuButton 可以显示为菜单、具有子菜单的菜单项、执行命令或显示菜单的按钮或仅显示菜单的按钮。 可以通过在构造函数 CMFCToolbarMenuButton::CMFCToolbarMenuButton 中指定与按钮相关联的图像、文本、菜单句柄和命令 ID 等参数来确定菜单按钮的行为和外观。

CMFCToolbarMenuButton 类派生的自定义类必须使用 DECLARE_SERIAL 宏。 当应用程序关闭时,DECLARE_DYNCREATE 宏会生成错误。

示例

以下示例演示如何配置 CMFCToolBarMenuButton 对象。 该代码说明了如何指定下拉菜单处于调色板模式,并指定当用户将菜单按钮拖离菜单栏时创建的拖曳栏的 ID。 此代码片段属于 Word Pad 示例

pBorderType->SetMenuPaletteMode(TRUE, 2 /* Rows number */);
pBorderType->SetTearOff(ID_BORDER_TEAROFF);

继承层次结构

CObject

CMFCToolBarButton

CMFCToolBarMenuButton

要求

标头: afxtoolbarmenubutton.h

CMFCToolBarMenuButton::CMFCToolBarMenuButton

构造 CMFCToolBarMenuButton 对象。

CMFCToolBarMenuButton();
CMFCToolBarMenuButton(const CMFCToolBarMenuButton& src);

CMFCToolBarMenuButton(
    UINT uiID,
    HMENU hMenu,
    int iImage,
    LPCTSTR lpszText=NULL,
    BOOL bUserButton=FALSE);

参数

src
[in] 要复制到此 CMFCToolBarMenuButton 对象的现有 CMFCToolBarMenuButton 对象。

uiID
[in] 用户单击按钮时要执行的命令的 ID;对于不直接执行命令的菜单按钮,则为 (UINT)-1。

hMenu
[in] 菜单的句柄;如果按钮没有菜单,则为 NULL。

iImage
[in] 按钮图像的索引;如果此按钮没有图标或使用 uiID 指定的命令的图标,则为 -1。 对于应用程序中的每个 CMFCToolBarImages 对象,索引是相同的。

lpszText
[in] 工具栏菜单按钮的文本。

bUserButton
[in] 如果按钮显示用户定义的图像,则为 TRUE;如果按钮显示与 uiID 指定的命令相关联的预定义图像,则为 FALSE。

备注

如果 uiID 是有效的命令 ID,则该按钮会在用户单击它时执行该命令。 如果 hMenu 是一个有效的菜单句柄,则该按钮在出现在工具栏中时提供一个下拉菜单,或者在出现在菜单中时提供一个子菜单。 如果 uiID 和 hMenu 都有效,则该按钮是一个拆分按钮,其中一部分将在用户单击它时执行命令,带有向下箭头的部分将在用户单击它时下拉菜单。 但是,如果 hMenu 有效,则当按钮插入菜单时,用户将无法单击该按钮来执行命令。

示例

以下示例演示如何构造 CMFCToolBarMenuButton 类的对象。 此代码片段属于 Word Pad 示例

CMFCToolBarMenuButton *pBorderType = new CMFCToolBarMenuButton(ID_BORDER_1, pPopup->GetSafeHmenu(),
                                                               GetCmdMgr()->GetCmdImage(ID_BORDER_1, FALSE),
                                                               _T("Borders"));

CMFCToolBarMenuButton::CompareWith

virtual BOOL CompareWith(const CMFCToolBarButton& other) const;

参数

[in] other

返回值

注解

CMFCToolBarMenuButton::CopyFrom

virtual void CopyFrom(const CMFCToolBarButton& src);

参数

[in] src

备注

CMFCToolBarMenuButton::CreateFromMenu

从 Windows 菜单句柄初始化工具栏菜单。

virtual void CreateFromMenu(HMENU hMenu);

参数

hMenu
[in] 菜单的句柄。

注解

工具栏菜单按钮可以显示下拉子菜单。

框架调用此方法,以从菜单中初始化子菜单中的命令。

CMFCToolBarMenuButton::CreateMenu

创建一个由工具栏菜单中的命令组成的菜单。 返回菜单的句柄。

virtual HMENU CreateMenu() const;

返回值

如果成功,则为菜单的句柄。 如果与工具栏菜单按钮关联的命令列表为空,则为 NULL。

备注

可以在派生类中重写此方法,以自定义菜单的生成方式。

CMFCToolBarMenuButton::CreatePopupMenu

创建一个 CMFCPopupMenu 对象以显示工具栏菜单。

virtual CMFCPopupMenu* CreatePopupMenu();

返回值

指向一个 CMFCPopupMenu 对象的指针,该对象显示与工具栏菜单按钮关联的下拉菜单。

备注

框架调用此方法,以准备与按钮关联的下拉菜单的显示。

默认实现只是构造并返回一个新 CMFCPopupMenu 对象。 如果要使用 CMFCPopupMenu 类的派生类型或执行其他初始化,请重写此方法。

CMFCToolBarMenuButton::DrawDocumentIcon

在菜单按钮上绘制文档图标。

void DrawDocumentIcon(
    CDC* pDC,
    const CRect& rectImage,
    HICON hIcon);

参数

pDC
[in] 指向设备上下文的指针。

rectImage
[in] 图像边框的坐标。

hIcon
[in] 图标的句柄。

备注

此方法采用文档图标并将其绘制在菜单按钮上,位于 rectImage 指定区域的中心。

CMFCToolBarMenuButton::EnableQuickCustomize

void EnableQuickCustomize();

备注

CMFCToolBarMenuButton::HasButton

virtual BOOL HasButton() const;

返回值

备注

CMFCToolBarMenuButton::HaveHotBorder

virtual BOOL HaveHotBorder() const;

返回值

备注

CMFCToolBarMenuButton::IsBorder

virtual BOOL IsBorder() const;

返回值

备注

CMFCToolBarMenuButton::IsClickedOnMenu

BOOL IsClickedOnMenu() const;

返回值

注解

CMFCToolBarMenuButton::IsQuickMode

BOOL IsQuickMode();

返回值

备注

CMFCToolBarMenuButton::GetCommands

提供对工具栏菜单中命令列表的只读访问权限。

const CObList& GetCommands() const;

返回值

CObList 类对象的 const 引用,其中包含 CMFCToolBarButton 类对象的集合。

备注

工具栏菜单按钮可以显示子菜单。 可以在构造函数的子菜单中或在 CMFCToolBarMenuButton::CreateFromMenu 中提供命令列表作为菜单的句柄 (HMENU)。 菜单被转换为从 CMFCToolBarButton 类派生并存储在内部 CObList 对象中的对象列表。 可以通过调用此方法访问此列表。

CMFCToolBarMenuButton::GetImageRect

检索按钮图像的边框。

void GetImageRect(CRect& rectImage);

参数

rectImage
[out] 对接收图像边框坐标的 CRect 对象的引用。

CMFCToolBarMenuButton::GetPaletteRows

当菜单处于调色板模式时,返回下拉菜单中的行数。

int GetPaletteRows() const;

返回值

调色板中的行数。

备注

当菜单按钮设置为调色板模式时,菜单项将出现在只有有限行数的多个列中。 调用此方法以获取行数。 可以使用 CMFCToolBarMenuButton::SetMenuPaletteMode 启用或禁用调色板模式并指定行数。

CMFCToolBarMenuButton::GetPopupMenu

返回指向表示按钮下拉菜单的 CMFCPopupMenu 类对象的指针。

CMFCPopupMenu* GetPopupMenu() const;

返回值

指向在框架绘制工具栏菜单按钮的子菜单时创建的 CMFCPopupMenu 类对象的指针;如果没有显示子菜单,则为 NULL。

注解

当工具栏菜单按钮显示下拉菜单时,该按钮会创建一个 CMFCPopupMenu 类对象来表示该菜单。 调用此方法以获取指向 CMFCPopupMenu 对象的指针。 不应存储返回的指针,因为它是临时的并且在用户关闭下拉菜单时变得无效。

CMFCToolBarMenuButton::IsDroppedDown

指示当前是否显示弹出菜单。

virtual BOOL IsDroppedDown() const;

返回值

如果工具栏菜单按钮显示子菜单,则为 TRUE;否则为 FALSE。

CMFCToolBarMenuButton::IsEmptyMenuAllowed

指定菜单项是否显示空子菜单。

virtual BOOL IsEmptyMenuAllowed() const;

返回值

如果框架从当前选定的菜单项打开子菜单,即使子菜单为空,则为 TRUE;否则为 FALSE。

备注

当用户尝试从当前选定的菜单项打开子菜单时,框架将调用此方法。 如果子菜单为空并且 IsEmptyMenuAllowed 返回 FALSE,则子菜单将不会打开。

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

CMFCToolBarMenuButton::IsExclusive

指示按钮是否处于独占模式。

virtual BOOL IsExclusive() const;

返回值

如果按钮在独占模式下工作,则为 TRUE;否则为 FALSE。

备注

当用户打开按钮的弹出菜单,然后将鼠标指针移到另一个工具栏或菜单按钮上时,弹出菜单将关闭,除非该按钮处于独占模式。

默认实现始终返回 FALSE。 如果要打开独占模式,请在派生类中重写此方法。

CMFCToolBarMenuButton::IsMenuPaletteMode

确定下拉菜单是否处于调色板模式。

BOOL IsMenuPaletteMode() const;

返回值

如果启用了调色板模式,则为 TRUE,否则为 FALSE。

备注

当菜单按钮设置为调色板模式时,菜单项出现在只有有限行数的多个列中。 调用此方法以获取行数。 可以通过调用 CMFCToolBarMenuButton::SetMenuPaletteMode 来启用或禁用调色板模式。

CMFCToolBarMenuButton::IsTearOffMenu

指示下拉菜单是否具有拖曳栏。

virtual BOOL IsTearOffMenu() const;

返回值

如果工具栏菜单按钮有一个拖曳栏,则为 TRUE;否则为 FALSE。

注解

若要启用拖曳功能并设置拖曳栏 ID,请调用 CMFCToolBarMenuButton::SetTearOff

CMFCToolBarMenuButton::m_bAlwaysCallOwnerDraw

指定在绘制按钮时框架是否始终调用 CFrameWndEx::OnDrawMenuImage

static BOOL m_bAlwaysCallOwnerDraw;

备注

当此成员变量设置为 TRUE 时,按钮始终调用 CFrameWndEx::OnDrawMenuImage 方法在按钮上显示图像。 当 m_bAlwaysCallOwnerDraw 为 FALSE 时,如果图像是预定义的,则按钮本身会绘制图像。 否则,会调用 OnDrawMenuImage

CMFCToolBarMenuButton::OnAfterCreatePopupMenu

virtual void OnAfterCreatePopupMenu();

注解

CMFCToolBarMenuButton::OnBeforeDrag

virtual BOOL OnBeforeDrag() const;

返回值

注解

CMFCToolBarMenuButton::OnCalculateSize

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

参数

[in] pDC
[in] sizeDefault
[in] bHorz

返回值

备注

CMFCToolBarMenuButton::OnCancelMode

virtual void OnCancelMode();

备注

CMFCToolBarMenuButton::OnChangeParentWnd

virtual void OnChangeParentWnd(CWnd* pWndParent);

参数

[in] pWndParent

注解

CMFCToolBarMenuButton::OnClick

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

参数

[in] pWnd
[in] bDelay

返回值

注解

CMFCToolBarMenuButton::OnClickMenuItem

当用户在下拉菜单中选择项时由框架调用。

virtual BOOL OnClickMenuItem();

返回值

如果框架应继续默认菜单项处理,则为 FALSE;否则为 TRUE。 默认实现始终返回 FALSE。

备注

当用户单击菜单项时,框架将执行与该项关联的命令。

若要自定义菜单项处理,请在派生自 CMFCToolBarMenuButton 类的类中重写 OnClickMenuItem。 还必须重写 CFrameWndEx::OnShowPopupMenu,并将需要特殊处理的菜单按钮替换为派生类的实例。

CMFCToolBarMenuButton::OnContextHelp

virtual BOOL OnContextHelp(CWnd* pWnd);

参数

[in] pWnd

返回值

备注

CMFCToolBarMenuButton::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);

参数

[in] pDC
[in] rect
[in] pImages
[in] bHorz
[in] bCustomizeMode
[in] bHighlight
[in] bDrawBorder
[in] bGrayDisabledButtons

备注

CMFCToolBarMenuButton::OnDrawOnCustomizeList

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

参数

[in] pDC
[in] rect
[in] bSelected

返回值

备注

CMFCToolBarMenuButton::OpenPopupMenu

当用户打开工具栏菜单按钮的下拉菜单时由框架调用。

virtual BOOL OpenPopupMenu(CWnd* pWnd=NULL);

参数

pWnd
[in] 指定接收下拉菜单命令的窗口。 仅当工具栏菜单按钮具有父窗口时,它才可为 NULL。

返回值

创建并成功打开 CMFCPopupMenu 类对象时,为 TRUE;否则为 FALSE。

注解

当用户从工具栏菜单按钮打开下拉菜单时,框架将调用此函数。

CMFCToolBarMenuButton::ResetImageToDefault

virtual void ResetImageToDefault();

注解

CMFCToolBarMenuButton::SaveBarState

virtual void SaveBarState();

备注

当作为拖放操作的结果创建工具栏按钮时,框架将调用此方法。 此方法调用顶级弹出菜单的 CMFCPopupMenu::SaveState 方法,这会导致弹出菜单的父按钮重新创建其菜单。

CMFCToolBarMenuButton::Serialize

virtual void Serialize(CArchive& ar);

参数

[in] ar

备注

CMFCToolBarMenuButton::SetACCData

设置功能区元素的可访问性数据。

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

参数

pParent
功能区元素的父窗口。

data
功能区元素的可访问性数据。

返回值

始终返回 TRUE。

注解

默认情况下,此方法将设置功能区元素的可访问性数据,并始终返回 TRUE。 重写此方法以设置可访问性数据并返回一个指示成功或失败的值。

CMFCToolBarMenuButton::SetMenuOnly

指定在按钮具有有效的命令 ID 和子菜单时,该按钮是绘制为菜单按钮还是拆分按钮。

void SetMenuOnly(BOOL bMenuOnly);

参数

bMenuOnly
[in] 如果此按钮同时具有有效的命令 ID 和子菜单,以将该按钮显示为菜单按钮,则为 TRUE,如果此按钮同时具有有效的命令 ID 和子菜单,以将该按钮显示为拆分按钮,则为 FALSE。

备注

通常,当工具栏菜单按钮同时具有子菜单和命令 ID 时,菜单将显示为具有主按钮和附加向下键按钮的拆分按钮。 如果调用此方法并且 bMenuOnly 为 TRUE,则该按钮将显示为一个带有向下箭头的菜单按钮。 当用户在任一模式下单击箭头时,子菜单将打开,当用户在任一模式下单击按钮的非箭头部分时,框架将执行命令。

CMFCToolBarMenuButton::SetMenuPaletteMode

指定下拉菜单是否处于调色板模式。

void SetMenuPaletteMode(
    BOOL bMenuPaletteMode=TRUE,
    int nPaletteRows=1);

参数

bMenuPaletteMode
[in] 指定下拉菜单是否处于调色板模式。

nPaletteRows
[in] 调色板中的行数。

备注

在调色板模式下,所有菜单项都显示为多列调色板。 使用 nPaletteRows 指定行数。

CMFCToolBarMenuButton::SetMessageWnd

void SetMessageWnd(CWnd* pWndMessage);

参数

[in] pWndMessage

备注

CMFCToolBarMenuButton::SetRadio

设置工具栏菜单按钮,以在选中时显示单选按钮样式图标。

virtual void SetRadio();

备注

如果在选中菜单按钮时绘制它,它会调用 CMFCVisualManager::OnDrawMenuCheck 来绘制一个复选标记图标。 默认情况下,OnDrawMenuCheck 请求当前虚拟管理器在菜单按钮上绘制一个复选框样式的复选标记。 调用此方法后,当前虚拟管理器会改为在菜单按钮上绘制单选按钮样式的复选标记。 无法撤消此更改。

调用此方法并且当前正在显示菜单按钮时,它将刷新。

CMFCToolBarMenuButton::SetTearOff

指定下拉菜单的拖曳栏的 ID。

virtual void SetTearOff(UINT uiBarID);

参数

uiBarID
[in] 指定新的拖曳栏 ID。

注解

调用此方法,用于指定当用户将菜单按钮拖离菜单栏时创建的拖曳栏的 ID。 如果 uiBarID 参数为 0,则用户无法拖曳菜单按钮。

调用 CWinAppEx::EnableTearOffMenus 以在应用程序中启用拖曳菜单功能。

另请参阅

层次结构图

CMFCToolBarButton 类
CMFCToolBar 类
CMFCPopupMenu 类