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:
To enable user-defined tools in the application, you need to perform the following steps:
- In the resource editor, create a dummy menu item with the ID_TOOLS_ENTRY command ID.
- 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.
- 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.
- 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.
- 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:
- Override the LoadFrame function (it is a member of the CBCGPFrameWnd, CBCGPMDIFrameWnd, and CBCGPOleIPFrameWnd
classes).
- Obtain a pointer to the CBCGPUserToolsManager object by calling CBCGPWorkspace::GetUserToolsManager.
- 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.
- 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