CUserToolsManager 类
维护应用程序中的 CUserTool 类对象的集合。 用户工具是运行外部应用程序的菜单项。 CUserToolsManager 对象使用户或开发人员能够将新的用户工具添加到应用程序中。 它支持与用户工具关联的命令的执行，并将与用户工具相关的信息保存到 Windows 注册表中。
语法
class CUserToolsManager : public CObject
成员
公共构造函数
| 名称 | 描述 |
|---|---|
| CUserToolsManager::CUserToolsManager | 构造一个 CUserToolsManager。 |
公共方法
备注
若要将用户工具合并到应用程序中，需要：
保留一个菜单项和一个用户工具菜单项的关联命令 ID。
保留用户可以在应用程序中定义的、每个用户工具的按序命令 ID。
调用 CWinAppEx::EnableUserTools 方法并提供以下参数：菜单命令 ID、第一个用户工具命令 ID 和最后一个用户工具命令 ID。
每个应用程序只能有一个全局 CUserToolsManager 对象。
有关用户工具的示例，请参阅 VisualStudioDemo 示例项目。
示例
下面的示例演示如何检索对 CUserToolsManager 对象的引用以及如何创建新的用户工具。 此代码片段是 Visual Studio 演示示例的一部分。
CUserToolsManager* pUserToolsManager = theApp.GetUserToolsManager();
if (pUserToolsManager != NULL && pUserToolsManager->GetUserTools().IsEmpty())
{
// CUserToolsManager* pUserToolsManager
CUserTool* pTool1 = pUserToolsManager->CreateNewTool();
pTool1->m_strLabel = _T("&Notepad");
pTool1->SetCommand(_T("notepad.exe"));
CUserTool* pTool2 = pUserToolsManager->CreateNewTool();
pTool2->m_strLabel = _T("Paint &Brush");
pTool2->SetCommand(_T("mspaint.exe"));
CUserTool* pTool3 = pUserToolsManager->CreateNewTool();
pTool3->m_strLabel = _T("&Windows Explorer");
pTool3->SetCommand(_T("explorer.exe"));
CUserTool* pTool4 = pUserToolsManager->CreateNewTool();
pTool4->m_strLabel = _T("Microsoft On-&Line");
pTool4->SetCommand(_T("http://www.microsoft.com"));
}
继承层次结构
CUserToolsManager
要求
标头：afxusertoolsmanager.h
CUserToolsManager::CreateNewTool
创建新的用户工具。
CUserTool* CreateNewTool();
返回值
指向新创建的用户工具的指针；如果用户工具数超过最大值，则为 NULL。 返回的类型与作为 pToolRTC 参数传递给 CWinAppEx::EnableUserTools 的类型相同。
注解
此方法查找对 CWinAppEx::EnableUserTools 的调用中提供的范围中的第一个可用菜单命令 ID，并向用户工具分配此 ID。
如果工具数达到最大值，该方法将失败。 当范围内的所有命令 ID 都分配给用户工具时会发生这种情况。 可以通过调用 CUserToolsManager::GetMaxTools 来检索工具的最大数目。 可以通过调用 CUserToolsManager::GetUserTools 方法来访问工具列表。
CUserToolsManager::CUserToolsManager
构造一个 CUserToolsManager。 每个应用程序最多只能有一个用户工具管理器。
CUserToolsManager();
CUserToolsManager(
const UINT uiCmdToolsDummy,
const UINT uiCmdFirst,
const UINT uiCmdLast,
CRuntimeClass* pToolRTC=RUNTIME_CLASS(CUserTool),
UINT uArgMenuID=0,
UINT uInitDirMenuID=0);
参数
uiCmdToolsDummy
[in] 框架用作用户工具菜单命令 ID 的占位符的无符号整数。
uiCmdFirst
[in] 第一个用户工具命令的命令 ID。
uiCmdLast
[in] 最后一个用户工具命令的命令 ID。
pToolRTC
[in] CUserToolsManager::CreateNewTool 创建的类。 通过使用此类，可以使用派生类型的 CUserTool 类而不是默认实现。
uArgMenuID
[in] 参数弹出菜单的菜单资源 ID。
uInitDirMenuID
[in] 初始目录弹出菜单的菜单资源 ID。
备注
请勿调用此构造函数。 请改为调用 CWinAppEx::EnableUserTools 来启用用户工具，并调用 CWinAppEx::GetUserToolsManager 来获取指向 CUserToolsManager 的指针。 有关详细信息，请参阅用户定义的工具。
CUserToolsManager::FindTool
返回指向与指定的命令 ID 关联的 CUserTool 类对象的指针。
CUserTool* FindTool(UINT uiCmdId) const;
参数
uiCmdId
[in] 菜单命令标识符。
返回值
如果成功，则为指向 CUserTool 类或 CUserTool 派生的对象的指针；否则为 NULL。
备注
如果 FindTool 成功，则返回的类型与 CWinAppEx::EnableUserTools 的 pToolRTC 参数的类型相同。
CUserToolsManager::GetArgumentsMenuID
返回与“自定义”对话框的“工具”选项卡上的“参数”菜单关联的资源 ID。
UINT GetArgumentsMenuID() const;
返回值
菜单资源的标识符。
备注
CWinAppEx::EnableUserTools 的 uArgMenuID 参数指定资源的 ID。
CUserToolsManager::GetDefExt
返回“文件打开”对话框 (CFileDialog) 在“自定义”对话框“工具”选项卡上“命令”字段中使用的默认扩展名。
const CString& GetDefExt() const;
返回值
对包含扩展名的 CString 对象的引用。
CUserToolsManager::GetFilter
返回“文件打开”对话框 (CFileDialog 类) 在“自定义”对话框“工具”选项卡上“命令”字段中使用的文件筛选器。
const CString& GetFilter() const;
返回值
对 CString 包含筛选器的对象的引用。
CUserToolsManager::GetInitialDirMenuID
返回与“自定义”对话框的“工具”选项卡上的“初始目录”菜单关联的资源 ID。
UINT GetInitialDirMenuID() const;
返回值
菜单资源标识符。
备注
返回的 ID 在 CWinAppEx::EnableUserTools 的 uInitDirMenuID 参数中指定。
CUserToolsManager::GetMaxTools
返回可在应用程序中分配的最大用户工具数。
int GetMaxTools() const;
返回值
可分配的用户工具的最大数目。
备注
调用此方法可检索可在应用程序中分配的最大工具数。 此数字是传递给 CWinAppEx::EnableUserTools 的从 uiCmdFirst 到 uiCmdLast 参数范围内的 ID 数。
CUserToolsManager::GetToolsEntryCmd
返回用户工具菜单项占位符的命令 ID。
UINT GetToolsEntryCmd() const;
返回值
占位符的命令 ID。
注解
若要启用用户工具，请调用 CWinAppEx::EnableUserTools。 uiCmdToolsDummy 参数指定工具条目命令的命令 ID。 此方法返回工具条目命令 ID。 无论在菜单中的什么位置使用该 ID，菜单显示时都会将其替换为用户工具列表。
CUserToolsManager::GetUserTools
返回对用户工具列表的引用。
const CObList& GetUserTools() const;
返回值
对包含用户工具列表的 CObList 类对象的常量引用。
注解
调用此方法可检索 CUserToolsManager 对象维护的用户工具列表。 每个用户工具由 CUserTool 类类型的对象或派生自 CUserTool 的类型表示。 调用 CWinAppEx::EnableUserTools 来启用用户工具时，由 pToolRTC 参数指定该类型。
CUserToolsManager::InvokeTool
执行与具有指定命令 ID 的用户工具关联的应用程序。
BOOL InvokeTool(UINT uiCmdId);
参数
uiCmdId
[in] 与用户工具关联的菜单命令 ID。
返回值
如果成功执行了与用户工具关联的命令，则返回非零值；否则返回 0。
备注
调用此方法以执行与具有 uiCmdId 指定的命令 ID 的用户工具关联的应用程序。
CUserToolsManager::IsUserToolCmd
确定命令 ID 是否与用户工具相关联。
BOOL IsUserToolCmd(UINT uiCmdId) const;
参数
uiCmdId
[in] 菜单项的命令 ID。
返回值
如果给定的命令 ID 与用户工具相关联，则返回非零值；否则返回 0。
备注
此方法检查给定的命令 ID 是否在命令 ID 范围内。 在调用 CWinAppEx::EnableUserTools 以启用用户工具时，将指定该范围。
CUserToolsManager::LoadState
从 Windows 注册表中加载有关用户工具的信息。
BOOL LoadState(LPCTSTR lpszProfileName=NULL);
参数
lpszProfileName
[in] Windows 注册表项的路径。
返回值
如果成功加载状态，则为非零值；否则为 0。
备注
此方法从 Windows 注册表加载 CUserToolsManager 对象的状态。
通常情况下不直接调用此方法。 CWinAppEx::LoadState 在工作区初始化过程中会调用它。
CUserToolsManager::MoveToolDown
在用户工具列表中向下移动指定的用户工具。
BOOL MoveToolDown(CUserTool* pTool);
参数
pTool
[in] 指定要移动的用户工具。
返回值
如果用户工具成功下移，则为非零值；否则为 0。
备注
如果 pTool 指定的工具不在内部列表中或该工具位于列表最后一位，该方法将失败。
CUserToolsManager::MoveToolUp
在用户工具列表中向上移动指定的用户工具。
BOOL MoveToolUp(CUserTool* pTool);
参数
pTool
[in] 指定要移动的用户工具。
返回值
如果用户工具成功移动，则为非零值；否则为 0。
注解
如果 pTool 参数指定的工具不在内部列表中，或该工具是列表中的第一个工具项，该方法将失败。
CUserToolsManager::RemoveTool
从应用程序中删除指定的用户工具。
BOOL RemoveTool(CUserTool* pTool);
参数
pTool
[in, out] 指向要删除的用户工具的指针。
返回值
如果成功移除该工具，则为 TRUE。 否则为 False。
备注
如果成功删除该工具，此方法将删除 pTool。
CUserToolsManager::SaveState
在 Windows 注册表中存储有关用户工具的信息。
BOOL SaveState(LPCTSTR lpszProfileName=NULL);
参数
lpszProfileName
[in] Windows 注册表项的路径。
返回值
如果已成功保存状态，则为非零值；否则为 0。
注解
该方法将 CUserToolsManager 对象的当前状态存储在 Windows 注册表中。
通常无需直接调用此方法，CWinAppEx::SaveState 会自动将其作为应用程序的工作区序列化过程的一部分进行调用。
CUserToolsManager::SetDefExt
指定“文件打开”对话框 (CFileDialog 类) 在“自定义”对话框“工具”选项卡上“命令”字段中使用的默认扩展名。
void SetDefExt(const CString& strDefExt);
参数
strDefExt
[in] 包含默认文件扩展名的文本字符串。
备注
调用此方法可在“文件打开”对话框中指定默认文件扩展名，该对话框在用户选择要与用户工具关联的应用程序时显示。 默认值为“exe”。
CUserToolsManager::SetFilter
指定“文件打开”对话框 (CFileDialog 类) 在“自定义”对话框“工具”选项卡上“命令”字段中使用的文件筛选器。
void SetFilter(const CString& strFilter);
参数
strFilter
[in] 指定筛选器。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈