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

NameDescription
CUserTool::CopyIconToClipboard
CUserTool::DrawToolIconDraws the user tool icon in a specified rectangle.
CUserTool::GetCommandReturns a string that contains the text of the command associated with the user tool.
CUserTool::GetCommandIdReturns the command ID of the menu item of the user tool.
CUserTool::InvokeExecutes the command associated with the user tool.
CUserTool::SerializeReads or writes this object from or to an archive. (Overrides CObject::Serialize.)
CUserTool::SetCommandSets the command associated with the user tool.
CUserTool::SetToolIconLoads the icon for the user tool from the application associated with the tool.

Protected Methods

NameDescription
CUserTool::LoadDefaultIconLoads the default icon for a user tool.

Data Members

NameDescription
CUserTool::m_strArgumentsThe command-line arguments for the user tool.
CUserTool::m_strInitialDirectoryThe initial directory for the user tool.
CUserTool::m_strLabelThe 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"));

CObject

CUserTool

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

Show: