CUserToolsManager Class
Maintains the collection of CUserTool Class objects in an application. A user tool is a menu item that runs an external application. The CUserToolsManager object enables the user or developer to add new user tools to the application. It supports the execution of the commands associated with user tools, and it also saves information about user tools in the Windows registry.
Syntax
class CUserToolsManager : public CObject
Members
Public Constructors
| Name | Description |
|---|---|
| CUserToolsManager::CUserToolsManager | Constructs a CUserToolsManager. |
Public Methods
| Name | Description |
|---|---|
| CUserToolsManager::CreateNewTool | Creates a new user tool. |
| CUserToolsManager::FindTool | Returns the pointer to the CMFCUserTool object that is associated with a specified command ID. |
| CUserToolsManager::GetArgumentsMenuID | Returns the resource ID that is associated with the Arguments menu on the Tools tab of the Customize dialog box. |
| CUserToolsManager::GetDefExt | Returns the default extension that the File Open dialog box ( CFileDialog) uses in the Command field on the Tools tab of the Customize dialog box. |
| CUserToolsManager::GetFilter | Returns the file filter that the File Open dialog box ( CFileDialog Class) uses in the Command field on the Tools tab of the Customize dialog box. |
| CUserToolsManager::GetInitialDirMenuID | Returns the resource ID that is associated with the Initial directory menu on the Tools tab of the Customize dialog box. |
| CUserToolsManager::GetMaxTools | Returns the maximum number of user tools that can be allocated in the application. |
| CUserToolsManager::GetToolsEntryCmd | Returns the command ID of the menu item placeholder for user tools. |
| CUserToolsManager::GetUserTools | Returns a reference to the list of user tools. |
| CUserToolsManager::InvokeTool | Executes an application associated with the user tool that has a specified command ID. |
| CUserToolsManager::IsUserToolCmd | Determines whether a command ID is associated with a user tool. |
| CUserToolsManager::LoadState | Loads information about user tools from the Windows registry. |
| CUserToolsManager::MoveToolDown | Moves the specified user tool down in the list of user tools. |
| CUserToolsManager::MoveToolUp | Moves the specified user tool up in the list of user tools. |
| CUserToolsManager::RemoveTool | Removes the specified user tool from the application. |
| CUserToolsManager::SaveState | Stores information about user tools in the Windows registry. |
| CUserToolsManager::SetDefExt | Specifies the default extension that the File Open dialog box ( CFileDialog Class) uses in the Command field on the Tools tab of the Customize dialog box. |
| CUserToolsManager::SetFilter | Specifies the file filter that the File Open dialog box ( CFileDialog Class) uses in the Command field on the Tools tab of the Customize dialog box. |
Remarks
To incorporate user tools into your application, you must:
Reserve a menu item and an associated command ID for a user tool menu entry.
Reserve a sequential command ID for each user tool that a user can define in your application.
Call the CWinAppEx::EnableUserTools method and supply the following parameters: menu command ID, first user tool command ID, and last user tool command ID.
There should be only one global CUserToolsManager object per application.
For an example of user tools, see the VisualStudioDemo sample project.
Example
The following example demonstrates how to retrieve a reference to a CUserToolsManager object and how to create new user tools. This code snippet is part of the Visual Studio Demo sample.
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"));
}
Inheritance Hierarchy
CUserToolsManager
Requirements
Header: afxusertoolsmanager.h
CUserToolsManager::CreateNewTool
Creates a new user tool.
CUserTool* CreateNewTool();
Return Value
A pointer to the newly created user tool, or NULL if the number of user tools has exceeded the maximum. The returned type is the same as the type that is passed to CWinAppEx::EnableUserTools as the pToolRTC parameter.
Remarks
This method finds the first available menu command ID in the range that is supplied in the call to CWinAppEx::EnableUserTools and assigns the user tool this ID.
The method fails if the number of tools has reached the maximum. This occurs when all command IDs within the range are assigned to user tools. You can retrieve the maximum number of tools by calling CUserToolsManager::GetMaxTools. You can get access to the tools list by calling the CUserToolsManager::GetUserTools method.
CUserToolsManager::CUserToolsManager
Constructs a CUserToolsManager. Each application must have at most one user tools manager.
CUserToolsManager();
CUserToolsManager(
const UINT uiCmdToolsDummy,
const UINT uiCmdFirst,
const UINT uiCmdLast,
CRuntimeClass* pToolRTC=RUNTIME_CLASS(CUserTool),
UINT uArgMenuID=0,
UINT uInitDirMenuID=0);
Parameters
uiCmdToolsDummy
[in] An unsigned integer that the framework uses as a placeholder for the command ID of the user tools menu.
uiCmdFirst
[in] The command ID for the first user tool command.
uiCmdLast
[in] The command ID for the last user tool command.
pToolRTC
[in] The class that CUserToolsManager::CreateNewTool creates. By using this class, you can use a derived type of CUserTool Class instead of the default implementation.
uArgMenuID
[in] The menu resource ID of the arguments popup menu.
uInitDirMenuID
[in] The menu resource ID of the initial directory popup menu.
Remarks
Do not call this constructor. Instead, call CWinAppEx::EnableUserTools to enable user tools, and call CWinAppEx::GetUserToolsManager to obtain a pointer to the CUserToolsManager. For more information, see User-defined Tools.
CUserToolsManager::FindTool
Returns the pointer to the CUserTool Class object that is associated with a specified command ID.
CUserTool* FindTool(UINT uiCmdId) const;
Parameters
uiCmdId
[in] A menu command identifier.
Return Value
A pointer to a CUserTool Class or CUserTool-derived object if success; otherwise NULL.
Remarks
When FindTool is successful, the returned type is the same as the type of the pToolRTC parameter to CWinAppEx::EnableUserTools.
CUserToolsManager::GetArgumentsMenuID
Returns the resource ID that is associated with the Arguments menu on the Tools tab of the Customize dialog box.
UINT GetArgumentsMenuID() const;
Return Value
The identifier of a menu resource.
Remarks
The uArgMenuID parameter of CWinAppEx::EnableUserTools specifies the ID of the resource.
CUserToolsManager::GetDefExt
Returns the default extension that the File Open dialog box ( CFileDialog) uses in the Command field on the Tools tab of the Customize dialog box.
const CString& GetDefExt() const;
Return Value
A reference to the CString object that contains the extension.
CUserToolsManager::GetFilter
Returns the file filter that the File Open dialog box ( CFileDialog Class) uses in the Command field on the Tools tab of the Customize dialog box.
const CString& GetFilter() const;
Return Value
A reference to the CString object that contains the filter.
CUserToolsManager::GetInitialDirMenuID
Returns the resource ID that is associated with the Initial directory menu on the Tools tab of the Customize dialog box.
UINT GetInitialDirMenuID() const;
Return Value
A menu resource identifier.
Remarks
The returned ID is specified in the uInitDirMenuID parameter of CWinAppEx::EnableUserTools.
CUserToolsManager::GetMaxTools
Returns the maximum number of user tools that can be allocated in the application.
int GetMaxTools() const;
Return Value
The maximum number of user tools that can be allocated.
Remarks
Call this method to retrieve the maximum number of tools that can be allocated in the application. This number is the number of IDs in the range from the uiCmdFirst through the uiCmdLast parameters that you pass to CWinAppEx::EnableUserTools.
CUserToolsManager::GetToolsEntryCmd
Returns the command ID of the menu item placeholder for user tools.
UINT GetToolsEntryCmd() const;
Return Value
The command ID of the placeholder.
Remarks
To enable user tools, you call CWinAppEx::EnableUserTools. The uiCmdToolsDummy parameter specifies the command ID of the tools entry command. This method returns the tools entry command ID. Wherever that ID is used in a menu, it is replaced by the list of user tools when the menu appears.
CUserToolsManager::GetUserTools
Returns a reference to the list of user tools.
const CObList& GetUserTools() const;
Return Value
A const reference to a CObList Class object that contains a list of user tools.
Remarks
Call this method to retrieve a list of user tools that the CUserToolsManager object maintains. Each user tool is represented by an object of type CUserTool Class or a type derived from CUserTool. The type is specified by the pToolRTC parameter when you call CWinAppEx::EnableUserTools to enable user tools.
CUserToolsManager::InvokeTool
Executes an application associated with the user tool that has a specified command ID.
BOOL InvokeTool(UINT uiCmdId);
Parameters
uiCmdId
[in] The menu command ID associated with the user tool.
Return Value
Nonzero if the command associated with user tool was executed successfully; otherwise 0.
Remarks
Call this method to execute an application associated with the user tool that has the command ID specified by uiCmdId.
CUserToolsManager::IsUserToolCmd
Determines whether a command ID is associated with a user tool.
BOOL IsUserToolCmd(UINT uiCmdId) const;
Parameters
uiCmdId
[in] A command ID of the menu item.
Return Value
Nonzero if a given command ID is associated with a user tool; otherwise 0.
Remarks
This method checks whether the given command ID is in the command ID range. You specify the range when you call CWinAppEx::EnableUserTools to enable user tools.
CUserToolsManager::LoadState
Loads information about user tools from the Windows registry.
BOOL LoadState(LPCTSTR lpszProfileName=NULL);
Parameters
lpszProfileName
[in] The path of the Windows registry key.
Return Value
Nonzero if the state was loaded successfully; otherwise 0.
Remarks
This method loads the state of the CUserToolsManager object from the Windows registry.
Usually, you do not call this method directly. CWinAppEx::LoadState calls it as part of workspace initialization process.
CUserToolsManager::MoveToolDown
Moves the specified user tool down in the list of user tools.
BOOL MoveToolDown(CUserTool* pTool);
Parameters
pTool
[in] Specifies the user tool to move.
Return Value
Nonzero if the user tool was moved down successfully; otherwise 0.
Remarks
The method fails if the tool that the pTool specifies is not in the internal list or if the tool is last in the list.
CUserToolsManager::MoveToolUp
Moves the specified user tool up in the list of user tools.
BOOL MoveToolUp(CUserTool* pTool);
Parameters
pTool
[in] Specifies the user tool to move.
Return Value
Nonzero if the user tool was moved up successfully; otherwise 0.
Remarks
The method fails if the tool that the pTool parameter specifies is not in the internal list or if the tool is the first tool item in the list.
CUserToolsManager::RemoveTool
Removes the specified user tool from the application.
BOOL RemoveTool(CUserTool* pTool);
Parameters
pTool
[in, out] A pointer to a user tool to be removed.
Return Value
TRUE if the tool is successfully removed. Otherwise, FALSE.
Remarks
If the tool is successfully removed, this method deletes pTool.
CUserToolsManager::SaveState
Stores information about user tools in the Windows registry.
BOOL SaveState(LPCTSTR lpszProfileName=NULL);
Parameters
lpszProfileName
[in] A path to the Windows registry key.
Return Value
Nonzero if the state was saved successfully; otherwise 0.
Remarks
The method stores the current state of the CUserToolsManager object in the Windows registry.
Usually, you do not need to call this method directly, CWinAppEx::SaveState calls it automatically as a part of the workspace serialization process of the application.
CUserToolsManager::SetDefExt
Specifies the default extension that the File Open dialog box ( CFileDialog Class) uses in the Command field on the Tools tab of the Customize dialog box.
void SetDefExt(const CString& strDefExt);
Parameters
strDefExt
[in] A text string that contains the default file name extension.
Remarks
Call this method to specify a default file name extension in the File Open dialog box, which is displayed when the user selects an application to associate with the user tool. The default is "exe".
CUserToolsManager::SetFilter
Specifies the file filter that the File Open dialog box ( CFileDialog Class) uses in the Command field on the Tools tab of the Customize dialog box.
void SetFilter(const CString& strFilter);
Parameters
strFilter
[in] Specifies the filter.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for