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
| 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. |
| Name | Description |
|---|---|
| CUserTool::LoadDefaultIcon | Loads the default icon for a user tool. |
| 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
For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
BOOL CopyIconToClipboard();
Draws the user tool icon at the center of a specified rectangle.
void DrawToolIcon(
CDC* pDC,
const CRect& rectImage);
pDC
[in] A pointer to a device context.
rectImage
[in] 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;
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;
The command ID of this user tool.
Executes the command associated with the user tool.
virtual BOOL Invoke();
Nonzero if the command was executed successfully; otherwise 0.
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();
A handle to the loaded icon ( HICON), or NULL if the default icon cannot be loaded.
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;
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;
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;
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);
[in] ar
Sets the application that the user tool runs.
void SetCommand(LPCTSTR lpszCmd);
lpszCmd
[in] Specifies the new application to be associated with the user tool.
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();
A handle to the loaded icon.
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