? Help Desk ↓ My downloads ⤷ Log in
Skip Navigation LinksBCGSoft > Support > Developer Area > User Tools

User Tools

The BCGControlBar Library framework supports user-defined tools. A user-defined tool is a special menu item that executes an external program, specified by the user. User-defined tools management is part of the 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:

BCGControlBar for MFC: user tools

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 the ID_TOOLS_ENTRY command ID.
  2. Optionally, you can help your users with the 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 have 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 a 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::EnableTools 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 that 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 the 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 icon from the corresponding program.
Note: If you derive your own class from CBCGPUserTool and have provided its runtime information in CBCGPWorkspace::EnableUserTools, CreateNewTool dynamically creates a CBCGPUserTool-derived object.

Back to the Developer Area