User Tools

BCGControlBar Library framework supports user-defined tools. User-defined tool is a special menu item, that executes an external, specified by the user, program. User-defined tools management is a part of customization process, implemented by the framework.

The customization dialog automatically inserts the "Tools" property page, if enabled. The following is a picture of the "Tools" page:

To enable user-defined tools in the application you need to perform the following steps:

1. In the resource editor create a dummy menu item with ID_TOOLS_ENTRY command ID.
   
2. Optionally, you can help your users with selection of directories and arguments for the tools (external programs). In the resource editor create two popup menus ID_MENU_ARGS and ID_MENU_DIRS.
   
3. You have to inform the framework how many user-defined tools are allowed in your application. The command IDs for the tools must take continuous numbers. For example, define ID_USER_TOOL1 to ID_USER_TOOL10 in the string table to allow ten tools.
   
4. Call CBCGPWorkspace::EnableUserTools to enable user-defined tools. Specify ID_TOOLS_ENTRY as a dummy command ID, ID_USER_TOOL1 and ID_USER_TOOL10 as the interval of tools commands, RUNTIME_CLASS (CBCGPUserTool) for the class that handles specific user tool. The ID_MENU_ARGS and ID_MENU_DIRS popup menus are optional.
   
5. When you invoke the customization dialog (OnViewCustomize, in this example), always call CBCGPToolbarCustomize::EnableUserTools to insert the "Tools" page into the customization property sheet.
   

Note. The framework will search for ID_TOOLS_ENTRY and replace it with the actual user-defined tools entries, if any. If you want to implement a custom object, which handles user tools, derive a class from the CBCGPUserTool class and provide its runtime class information when calling EnableUserTools

If you need to predefine some tools at the application startup:

1. Override the LoadFrame function (it is a member of CBCGPFrameWnd, CBCGPMDIFrameWnd and CBCGPOleIPFrameWnd classes).
   
2. Obtain a pointer to the CBCGPUserToolsManager object by calling CBCGPWorkspace::GetUserToolsManager.
   
3. For each tool you want to create call CBCGPUserToolsManager::CreateNewTool. It returns a pointer to a CBCGPUserTool object and adds the newly created user tool to the internal collection of tools.
   
4. For each tool, set its text label and command (CBCGPUserTool::m_strLabel, CBCGPUserTool::SetCommand). The default implementation of CBCGPUserTool automatically retrieves available icons from the specified in SetCommand program.
   

Note. If you derive your own class from CBCGPUserTool and have provided its runtime information in CBCGPWorkspace::EnableUserTools, CreateNewTool dynamically creates CBCGPUserTool-derived object.

Back to the Developer Area