CContextMenuManager 类

项目
06/16/2023

CContextMenuManager 对象管理快捷菜单（也称为上下文菜单）。

语法

class CContextMenuManager : public CObject

成员

公共构造函数

名称	描述
CContextMenuManager::CContextMenuManager	构造 `CContextMenuManager` 对象。
`CContextMenuManager::~CContextMenuManager`	析构函数。

公共方法

名称	描述
CContextMenuManager::AddMenu	添加新的快捷菜单。
CContextMenuManager::GetMenuById	返回与所提供资源 ID 关联的菜单的句柄。
CContextMenuManager::GetMenuByName	返回与所提供菜单名称匹配的菜单的句柄。
CContextMenuManager::GetMenuNames	返回菜单名称的列表。
CContextMenuManager::LoadState	加载存储在 Windows 注册表中的快捷菜单。
CContextMenuManager::ResetState	从上下文菜单管理器中清除快捷菜单。
CContextMenuManager::SaveState	将快捷菜单保存到 Windows 注册表。
CContextMenuManager::SetDontCloseActiveMenu	控制 `CContextMenuManager` 在显示新快捷菜单时是否关闭活动快捷菜单。
CContextMenuManager::ShowPopupMenu	显示指定的快捷菜单。
CContextMenuManager::TrackPopupMenu	显示指定的快捷菜单。返回所选菜单命令的索引。

备注

CContextMenuManager 管理快捷菜单，并确保其外观一致。

不应手动创建 CContextMenuManager 对象。应用程序的框架创建 CContextMenuManager 对象。但是，在初始化应用程序时，应调用 CWinAppEx::InitContextMenuManager。初始化上下文管理器后，使用方法 CWinAppEx::GetContextMenuManager 获取指向应用程序的上下文管理器的指针。

可以通过调用 AddMenu 在运行时创建快捷菜单。如果要在不先接收用户输入的情况下显示菜单，请调用 ShowPopupMenu。当你希望创建菜单并等待用户输入时，请使用 TrackPopupMenu。 TrackPopupMenu 返回所选命令的索引，如果用户未选择任何内容就退出，则返回 0。

CContextMenuManager 还可以将其状态保存并加载到 Windows 注册表中。

示例

以下示例演示如何将菜单添加到 CContextMenuManager 对象，以及如何在 CContextMenuManager 对象显示新的弹出菜单时不关闭活动的弹出菜单。此代码片段属于自定义页面示例。

// The GetContextMenuManager method is inherited from the CWinAppEx class.
GetContextMenuManager()->AddMenu(_T("My menu"), IDR_CONTEXT_MENU);
GetContextMenuManager()->SetDontCloseActiveMenu(true);

继承层次结构

CObject

CContextMenuManager

要求

标头：afxcontextmenumanager.h

CContextMenuManager::AddMenu

将新的快捷菜单添加到 CContextMenuManager。

BOOL AddMenu(
    UINT uiMenuNameResId,
    UINT uiMenuResId);

BOOL AddMenu(
    LPCTSTR lpszName,
    UINT uiMenuResId);

参数

uiMenuNameResId
[in] 包含新菜单名称的字符串的资源 ID。

uiMenuResId
[in] 菜单资源 ID。

lpszName
[in] 包含新菜单名称的字符串。

返回值

如果方法成功，则为非零；如果方法失败，则为 0。

备注

如果 uiMenuResId 无效或另一个同名菜单已在 CContextMenuManager 中，则此方法失败。

CContextMenuManager::CContextMenuManager

构造 CContextMenuManager 对象。

CContextMenuManager();

备注

在大多数情况下，不应手动创建 CContextMenuManager。应用程序的框架创建 CContextMenuManager 对象。应该在应用程序初始化期间调用 CWinAppEx::InitContextMenuManager。若要获取指向上下文管理器的指针，请调用 CWinAppEx::GetContextMenuManager。

CContextMenuManager::GetMenuById

返回与给定资源 ID 关联的菜单的句柄。

HMENU GetMenuById(UINT nMenuResId) const;

参数

nMenuResId
[in] 菜单的资源 ID。

返回值

关联菜单的句柄，如果未找到菜单，则为 NULL。

CContextMenuManager::GetMenuByName

返回特定菜单的句柄。

HMENU GetMenuByName(
    LPCTSTR lpszName,
    UINT* puiOrigResID = NULL) const;

参数

lpszName
[in] 包含要检索的菜单名称的字符串。

puiOrigResID
[out] 指向 UINT 的指针。此参数包含指定菜单的资源 ID（如果找到）。

返回值

与 lpszName 指定的名称匹配的菜单句柄。如果没有名为 lpszName 的菜单，则为 NULL。

备注

如果此方法找到与 lpszName 匹配的菜单，则 GetMenuByName 将菜单资源 ID 存储在参数 puiOrigResID 中。

CContextMenuManager::GetMenuNames

返回添加到 CContextMenuManager 的菜单名称列表。

void GetMenuNames(CStringList& listOfNames) const;

参数

listOfNames
[out] 对 CStringList 参数的引用。此方法将菜单名称列表写入此参数。

CContextMenuManager::LoadState

从 Windows 注册表加载与 CContextMenuManager 类关联的信息。

virtual BOOL LoadState(LPCTSTR lpszProfileName = NULL);

参数

lpszProfileName
[in] 包含注册表键相对路径的字符串。

返回值

如果此方法成功，返回值为非零；否则返回值是 0。

注解

lpszProfileName 参数不是注册表项的绝对路径。它是添加到应用程序默认注册表项末尾的相对路径。若要获取或设置默认注册表项，请分别使用方法 CWinAppEx::GetRegistryBase 和 CWinAppEx::SetRegistryBase。

使用方法 CContextMenuManager::SaveState 将快捷菜单保存到注册表。

CContextMenuManager::ResetState

从与 CContextMenuManager 类关联的快捷菜单中清除所有项。

virtual BOOL ResetState();

返回值

如果方法成功，则为 TRUE；如果发生故障，则为 FALSE。

注解

此方法清除弹出菜单，并从 CContextMenuManager 中将其删除。

CContextMenuManager::SaveState

将与 CContextMenuManager 类关联的信息保存到 Windows 注册表。

virtual BOOL SaveState(LPCTSTR lpszProfileName = NULL);

参数

lpszProfileName
[in] 包含注册表键相对路径的字符串。

返回值

如果此方法成功，返回值为非零；否则返回值是 0。

注解

使用方法 CContextMenuManager::LoadState 从注册表加载快捷菜单。

CContextMenuManager::SetDontCloseActiveMenu

控制 CContextMenuManager 在显示新的弹出菜单时是否关闭活动的弹出菜单。

void SetDontCloseActiveMenu (BOOL bSet = TRUE);

参数

bSet
[in] 一个布尔参数，控制是否关闭活动的弹出菜单。 TRUE 值表示活动的弹出菜单未关闭。 FALSE 表示活动的弹出菜单已关闭。

注解

默认情况下，CContextMenuManager 关闭活动的弹出菜单。

CContextMenuManager::ShowPopupMenu

显示指定的快捷菜单。

virtual BOOL ShowPopupMenu(
    UINT uiMenuResId,
    int x,
    int y,
    CWnd* pWndOwner,
    BOOL bOwnMessage = FALSE,
    BOOL bRightAlign = FALSE);

virtual CMFCPopupMenu* ShowPopupMenu(
    HMENU hmenuPopup,
    int x,
    int y,
    CWnd* pWndOwner,
    BOOL bOwnMessage = FALSE,
    BOOL bAutoDestroy = TRUE,
    BOOL bRightAlign = FALSE);

参数

uiMenuResId
[in] 此方法将显示的菜单的资源 ID。

x
[in] 客户端坐标中快捷菜单的水平偏移。

y
[in] 客户端坐标中快捷菜单的垂直偏移

pWndOwner
[in] 指向快捷菜单的父窗口的指针。

bOwnMessage
[in] 指示消息路由方式的布尔参数。如果 bOwnMessage 为 FALSE，则使用标准 MFC 路由。否则，pWndOwner 接收消息。

hmenuPopup
[in] 此方法将显示的菜单句柄。

bAutoDestroy
[in] 一个布尔参数，指示是否自动销毁菜单。

bRightAlign
[in] 一个布尔参数，指示菜单项的对齐方式。如果 bRightAlign 为 TRUE，则菜单按从右到左的读取顺序向右对齐。

返回值

如果方法成功显示菜单，则第一个方法重载返回非零；否则为 0。如果快捷菜单显示正确，则第二个方法重载返回指向 CMFCPopupMenu 的指针；否则为 NULL。

备注

此方法类似于方法 CContextMenuManager::TrackPopupMenu，因为这两种方法都显示快捷菜单。不过，TrackPopupMenu 返回所选菜单命令的索引。

如果参数 bAutoDestroy 为 FALSE，则必须手动调用继承的 DestroyMenu 方法以释放内存资源。 ShowPopupMenu 的默认实现不使用参数 bAutoDestroy。它供将来使用或 CContextMenuManager 类派生的自定义类使用。

CContextMenuManager::TrackPopupMenu

显示指定的快捷菜单并返回所选快捷菜单命令的索引。

virtual UINT TrackPopupMenu(
    HMENU hmenuPopup,
    int x,
    int y,
    CWnd* pWndOwner,
    BOOL bRightAlign = FALSE);

参数

hmenuPopup
[in] 此方法显示的快捷菜单的句柄。