User-Tools Menu

Objective Toolkit’s user-tools menu classes implement a user-configurable Tools menu like the one in Microsoft Visual Studio. A user-tool is an executable that the application can spawn programmatically. The user can add his or her own menu items to the Tools menu and specify an action for each menu item.

Example User-Tools Dialog

The User-Tools Menu Classes

Two classes are involved in the implementation of the user-tools menu feature. SECUserTool encapsulates the information required to execute a tool. SECUserToolsDlg allows the user to manage the list of tools.

User-Tool Menu Class Hierarchy

SECUserTool

TheSECUserTool class provides an abstraction of a user-tool. An SECUserTool object encapsulates the filename, command-line arguments, and initial directory that describe how and where to run the executable. In addition, the SECUserTool interface contains an Execute() method that uses these attributes to launch the user-defined tool.

SECUserToolsDlg

The SECUserToolsDlg class implements a user-tools dialog. A user-tools dialog allows the user to edit a list of user-tools, where each user-tool is represented by one SECUserTool object. Through this dialog, the user can create new user-tools, edit and delete existing user-tools, and reorder the list of user-tools.

Using the User-Tools Menu Classes

To add user-tool support to your application:

1. Add a CObArray member to your main frame class (usually CMainFrame) to store the SECUserTool objects.

2. Instantiate an SECUserTool object and add it to the CObArray.

3. Call the SetMenuText() method to set the menu text associated with the user-tool.

4. Call the SetCommand() method to set the absolute path and filename of the executable for the user-tool.

5. Call the SetArgs() method to set the command-line arguments that are passed to the user-tool upon execution.

6. Call the SetDirectory() method to set the absolute path of the directory in which the user-tool is initially executed.

7. Alternatively, instantiate an SECUserToolsDlg dialog and initialize it by calling SetToolsArrayPtr() with the array of SECUserTool objects. Activate the dialog, which automatically performs calls the preceding methods using the information that the user provides for each user-tool.

To execute a user-tool:

Call the Execute() method and pass the pReplacements parameter to run the user-tool with the specified arguments and initial directory.

To make a copy of a user-tool:

Call the Clone() method.

To serialize an array of user-tools:

Use the ReadUserToolFile() or WriteUserToolFile() global function.

To append an array of user-tools to a menu:

Use the AppendUserTools() function.

To delete an array of user-tools:

Use the EmptyUserToolArray() function.

User-Tool Menu Sample

The Objective Toolkittoolmenu sample (Samples\Toolkit\MFC\UIext\toolmenu) demonstrates the capabilities of the user-definable tools menu and dialog. This sample does not ship with the product. For information on how to obtain this sample, see Location of Sample Code in the Getting Started part.