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:
- In the resource editor create a dummy menu item with ID_TOOLS_ENTRY command ID.
- 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.
- 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.
- 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.
- 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, 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:
- Override the LoadFrame function (it is a member of 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 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