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.

Syntax

class CUserTool : public CObject

Members

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.

Remarks

For more information about how to enable user tools in your application, see CUserToolsManager Class.

Example

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"));

Inheritance Hierarchy

CObject

CUserTool

Requirements

Header: afxusertool.h

CUserTool::CopyIconToClipboard

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

CUserTool::DrawToolIcon

Draws the user tool icon at the center of a specified rectangle.

void DrawToolIcon(
    CDC* pDC,
    const CRect& rectImage);

Parameters

pDC
[in] A pointer to a device context.

rectImage
[in] Specifies the coordinates of the area to display the icon.

CUserTool::GetCommand

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.

CUserTool::GetCommandId

Returns the command ID of the user tool.

UINT GetCommandId() const;

Return Value

The command ID of this user tool.

CUserTool::Invoke

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.

CUserTool::LoadDefaultIcon

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.

CUserTool::m_strArguments

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.

CUserTool::m_strInitialDirectory

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.

CUserTool::m_strLabel

The label that is displayed in the menu item for the tool.

CString m_strLabel;

CUserTool::Serialize

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

CUserTool::SetCommand

Sets the application that the user tool runs.

void SetCommand(LPCTSTR lpszCmd);

Parameters

lpszCmd
[in] 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.

CUserTool::SetToolIcon

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.

See also

Hierarchy Chart
Classes
CWinAppEx Class
CUserToolsManager Class