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.
class CUserToolsManager : public CObject
| Name | Description |
|---|---|
| CUserToolsManager::CUserToolsManager | Constructs a CUserToolsManager. |
| 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. |
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.
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"));
}
CUserToolsManager
Header: afxusertoolsmanager.h
Creates a new user tool.
CUserTool* CreateNewTool();
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.
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.
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);
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.
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.
Returns the pointer to the CUserTool Class object that is associated with a specified command ID.
CUserTool* FindTool(UINT uiCmdId) const;
uiCmdId
[in] A menu command identifier.
A pointer to a CUserTool Class or CUserTool-derived object if success; otherwise NULL.
When FindTool is successful, the returned type is the same as the type of the pToolRTC parameter to CWinAppEx::EnableUserTools.
Returns the resource ID that is associated with the Arguments menu on the Tools tab of the Customize dialog box.
UINT GetArgumentsMenuID() const;
The identifier of a menu resource.
The uArgMenuID parameter of CWinAppEx::EnableUserTools specifies the ID of the resource.
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;
A reference to the CString object that contains the extension.
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;
A reference to the CString object that contains the filter.
Returns the resource ID that is associated with the Initial directory menu on the Tools tab of the Customize dialog box.
UINT GetInitialDirMenuID() const;
A menu resource identifier.
The returned ID is specified in the uInitDirMenuID parameter of CWinAppEx::EnableUserTools.
Returns the maximum number of user tools that can be allocated in the application.
int GetMaxTools() const;
The maximum number of user tools that can be allocated.
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.
Returns the command ID of the menu item placeholder for user tools.
UINT GetToolsEntryCmd() const;
The command ID of the placeholder.
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.
Returns a reference to the list of user tools.
const CObList& GetUserTools() const;
A const reference to a CObList Class object that contains a list of user tools.
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.
Executes an application associated with the user tool that has a specified command ID.
BOOL InvokeTool(UINT uiCmdId);
uiCmdId
[in] The menu command ID associated with the user tool.
Nonzero if the command associated with user tool was executed successfully; otherwise 0.
Call this method to execute an application associated with the user tool that has the command ID specified by uiCmdId.
Determines whether a command ID is associated with a user tool.
BOOL IsUserToolCmd(UINT uiCmdId) const;
uiCmdId
[in] A command ID of the menu item.
Nonzero if a given command ID is associated with a user tool; otherwise 0.
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.
Loads information about user tools from the Windows registry.
BOOL LoadState(LPCTSTR lpszProfileName=NULL);
lpszProfileName
[in] The path of the Windows registry key.
Nonzero if the state was loaded successfully; otherwise 0.
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.
Moves the specified user tool down in the list of user tools.
BOOL MoveToolDown(CUserTool* pTool);
pTool
[in] Specifies the user tool to move.
Nonzero if the user tool was moved down successfully; otherwise 0.
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.
Moves the specified user tool up in the list of user tools.
BOOL MoveToolUp(CUserTool* pTool);
pTool
[in] Specifies the user tool to move.
Nonzero if the user tool was moved up successfully; otherwise 0.
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.
Removes the specified user tool from the application.
BOOL RemoveTool(CUserTool* pTool);
pTool
[in, out] A pointer to a user tool to be removed.
TRUE if the tool is successfully removed. Otherwise, FALSE.
If the tool is successfully removed, this method deletes pTool.
Stores information about user tools in the Windows registry.
BOOL SaveState(LPCTSTR lpszProfileName=NULL);
lpszProfileName
[in] A path to the Windows registry key.
Nonzero if the state was saved successfully; otherwise 0.
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.
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);
strDefExt
[in] A text string that contains the default file name extension.
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".
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);
strFilter
[in] Specifies the filter.