Visit the Ultimate Toolbox main page for an overview and configuration guide to the Ultimate Toolbox library.
Contents
COXCustomizeManager is a derived class that serves as a control center that provides customization functionality for different aspects of your application. COXCustomizeManager is a container of customize page(s). Each customize page is responsible for customization of a particular area of your application functionality (e.g. customizing menus and toolbars). Refer to the COXCustomizePage class overview and overviews for the standard customize page classes (like COXCustomizeCommandsPage).CDialog
COXCustomizeManager is responsible for initializing all customize pages inserted in the manager. It organizes all pages in groups (by default there is only one group defined - the one that contains standard (predefined) customize pages) and provides navigation facilities by using a shortcut bar control (COXShortcutBar class).
COXCustomizeManager is designed to be easily overridden in order to provide support for custom-defined customize pages. It has many virtual functions that define its behaviour, which can be overridden in order to provide additional customization functionality.
Although the customize manager is easily expandable, in most cases a programmer will use a predefined set of standard customize pages (Customize Commands, Customize Toolbars, Customize Workspace, etc.). COXCustomizeManager provides interface functions for accessing the standard pages and their initialization functions (refer to the class reference for details). In most cases a customization feature will require a programmer to call only one initialization function.
COXCustomizeManager provides a rich set of functions for navigating through customize pages programmatically. These will be useful mostly for programmers who decide to derive their own classes and provide additional functionality.
We've developed many predefined customize pages that will satisfy the more common customization needs (e.g. toolbars, menus, accelerator tables, etc.). All standard pages are documented, and are listed in the overview for the COXCustomizePage class (base class for any customize page).
Note that you do not have to implement your own COXCustomizeManager-derived class in order to specify what standard pages will be included in the customize manager. Moreover, you don't have to include the code that implements the standard pages if you are not interested in using them. For example, in order to include support for customizing toolbars and menus you need to include the following define in your stdafx.h file:
#define OX_CUSTOMIZE_TOOLBARS
The list of all defines that correspond to standard pages can be found in the COXCustomizePage overview in the CHM documentation.
Below you will find the details on how you can use customize manager in your application. (Note that some of the standard pages might require additional initialization steps).
Usage
- In your stdafx.h file include defines for the standard pages you are going to use in the customize manager:
#define OX_CUSTOMIZE_TOOLBARS
#define OX_CUSTOMIZE_COMMANDS
These defines will include "Customize Toolbars" and "Customize Commands" standard pages.
- Declare a member variable of
COXCustomizeManager class in the main window of your application (usually CMainFrame class for SDI/MDI applications)
COXCustomizeManager m_customizeManager;
- Handle the
WM_CREATE message for the main window and in the handler and call initialization routines for the pages included in the customize manager:
#ifdef OX_CUSTOMIZE_TOOLBARS
VERIFY(m_customizeManager.InitializeToolbars());
#endif
#ifdef OX_CUSTOMIZE_COMMANDS
VERIFY(m_customizeManager.InitializeCommands());
#endif
This code will initialize the "Customize Toolbars" and "Customize Commands" standard pages. Note that you have to refer to the documentation for the appropriate way of initializing any particular standard, customized routines because some of them require additional initialization step(s).
Before initializing any page in the Customize manager you have to make sure that the variable that points to application main window is already defined (i.e. AfxGetMainWnd() function returns a pointer to created window). The default MFC implementation sets this variable in the CWinApp-derived class InitInstance() function after loading the frame. Unfortunately, it is too late for some of the standard customize pages. So make sure that you put the following line of code before calling any Initialize... functions:
AfxGetApp()->m_pMainWnd=this;
- If you want to save the state of the pages (pages allows you to save the changed settings in the registry) you have to handle
WM_CLOSE message for the main window and add the following line of code to this handler:
m_customizeManager.SaveWorkspaceState();
- In order to display the customize manager (it is always displayed as modeless window) you can use the following code:
f(!::IsWindow(m_customizeManager.GetSafeHwnd()))
{
VERIFY(m_customizeManager.Create(COXCustomizeManager::IDD,this));
}
m_customizeManager.SetActiveWindow();
m_customizeManager.ShowWindow(SW_SHOW);
That's all you need to do.
COXCustomizeManager automatically recognizes if it is being used in with the docking windows framework. It behaves differently in a docking windows environment. If your application doesn't use the docking framework then you must to add the following define to your stdafx.h file:
#define OX_CUSTOMIZE_NOTSUPPORTING_DOCKING_FRAMEWORK
For more on the COXCustomizeManager and associated configuration pages, refer to the Application Customization Framework section of the compiled HTML help documentation.
Initial CodeProject release August 2007.
