Edit

Share via

CUserToolsManager Class

  • Article

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:

  1. Reserve a menu item and an associated command ID for a user tool menu entry.

  2. Reserve a sequential command ID for each user tool that a user can define in your application.

  3. 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

CObject

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

Hierarchy Chart
Classes
CWinAppEx Class
CUserTool Class