CUserTool Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CUserTool Class.
A user tool is a menu item that runs an external application. The Tools tab of the Customize dialog box ( CMFCToolBarsCustomizeDialog Class) enables the user to add user tools, and to specify the name, command, arguments, and initial directory for each user tool.
class CUserTool : public CObject
Public Methods
| Name | Description |
|---|---|
| CUserTool::CopyIconToClipboard | |
| CUserTool::DrawToolIcon | Draws the user tool icon in a specified rectangle. |
| CUserTool::GetCommand | Returns a string that contains the text of the command associated with the user tool. |
| CUserTool::GetCommandId | Returns the command ID of the menu item of the user tool. |
| CUserTool::Invoke | Executes the command associated with the user tool. |
| CUserTool::Serialize | Reads or writes this object from or to an archive. (Overrides CObject::Serialize.) |
| CUserTool::SetCommand | Sets the command associated with the user tool. |
| CUserTool::SetToolIcon | Loads the icon for the user tool from the application associated with the tool. |
Protected Methods
| Name | Description |
|---|---|
| CUserTool::LoadDefaultIcon | Loads the default icon for a user tool. |
Data Members
| Name | Description |
|---|---|
| CUserTool::m_strArguments | The command-line arguments for the user tool. |
| CUserTool::m_strInitialDirectory | The initial directory for the user tool. |
| CUserTool::m_strLabel | The tool name that is displayed in the menu item for the tool. |
For more information about how to enable user tools in your application, see CUserToolsManager Class.
The following example demonstrates how to create a tool from a CUserToolsManager object, set the m_strLabel member variable, and set the application that the user tool runs. This code snippet is part of the Visual Studio Demo sample.
// CUserToolsManager* pUserToolsManager CUserTool* pTool1 = pUserToolsManager->CreateNewTool(); pTool1->m_strLabel = _T("&Notepad"); pTool1->SetCommand(_T("notepad.exe"));
Header: afxusertool.h
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
BOOL CopyIconToClipboard();
Return Value
Remarks
Draws the user tool icon at the center of a specified rectangle.
void DrawToolIcon(
CDC* pDC,
const CRect& rectImage);
Parameters
[in] pDC
A pointer to a device context.
[in] rectImage
Specifies the coordinates of the area to display the icon.
Returns a string that contains the text of the command associated with the user tool.
const CString& GetCommand() const;
Return Value
A reference to CString object that contains the text of the command associated with the user tool.
Returns the command ID of the user tool.
UINT GetCommandId() const;
Return Value
The command ID of this user tool.
Executes the command associated with the user tool.
virtual BOOL Invoke();
Return Value
Nonzero if the command was executed successfully; otherwise 0.
Remarks
Calls ShellExecute to execute a command associated with the user tool. The function fails if the command is empty or if ShellExecute fails.
Loads the default icon for a user tool.
virtual HICON LoadDefaultIcon();
Return Value
A handle to the loaded icon ( HICON), or NULL if the default icon cannot be loaded.
Remarks
The framework calls this method when it is unable to load an icon for a user-defined tool from the executable file of the tool.
Override this method to supply your own default tool icon.
The command-line arguments for the user tool.
CString m_strArguments;
Remarks
This string is passed to the tool when you call CUserTool::Invoke or when a user clicks the command associated with this tool.
Specifies the initial directory for the user tool.
CString m_strInitialDirectory;
Remarks
This variable specifies the initial directory that the tool executes in when you call CUserTool::Invoke or when a user clicks the command associated with this tool.
The label that is displayed in the menu item for the tool.
CString m_strLabel;
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual void Serialize(CArchive& ar);
Parameters
[in] ar
Remarks
Sets the application that the user tool runs.
void SetCommand(LPCTSTR lpszCmd);
Parameters
[in] lpszCmd
Specifies the new application to be associated with the user tool.
Remarks
Call this method to set a new application that the user tool runs. The method destroys the old icon and loads a new icon from the given application. If it cannot load an icon from the application, it loads the default icon for a user tool by calling CUserTool::LoadDefaultIcon.
Loads the icon for the user tool from the application that the tool uses.
virtual HICON SetToolIcon();
Return Value
A handle to the loaded icon.
Remarks
Call this method to load the icon to be displayed on the menu item. This method searches for the icon in the executable file that the tool uses. If it does not have a default icon, the icon provided by CUserTool::LoadDefaultIcon is used instead.
Hierarchy Chart
Classes
CWinAppEx Class
CUserToolsManager Class