CMFCToolBarsCustomizeDialog Class
A modeless tab dialog box ( CPropertySheet Class) that enables the user to customize the toolbars, menus, keyboard shortcuts, user-defined tools, and visual style in an application. Typically, the user accesses this dialog box by selecting Customize from the Tools menu.
The Customize dialog box has six tabs: Commands, Toolbars, Tools, Keyboard, Menu, and Options.
class CMFCToolBarsCustomizeDialog : public CPropertySheet
| Name | Description |
|---|---|
| CMFCToolBarsCustomizeDialog::CMFCToolBarsCustomizeDialog | Constructs a CMFCToolBarsCustomizeDialog object. |
CMFCToolBarsCustomizeDialog::~CMFCToolBarsCustomizeDialog |
Destructor. |
| Name | Description |
|---|---|
| CMFCToolBarsCustomizeDialog::AddButton | Inserts a toolbar button into the list of commands on the Commands page |
| CMFCToolBarsCustomizeDialog::AddMenu | Loads a menu from the resources and calls CMFCToolBarsCustomizeDialog::AddMenuCommands to add that menu to the list of commands on the Commands page. |
| CMFCToolBarsCustomizeDialog::AddMenuCommands | Loads a menu from the resources and calls CMFCToolBarsCustomizeDialog::AddMenuCommands to add that menu to the list of commands on the Commands page. |
| CMFCToolBarsCustomizeDialog::AddToolBar | Loads a toolbar from the resources. Then, for each command in the menu calls the CMFCToolBarsCustomizeDialog::AddButton method to insert a button in the list of commands on the Commands page under the specified category. |
| CMFCToolBarsCustomizeDialog::Create | Displays the Customization dialog box. |
CMFCToolBarsCustomizeDialog::EnableTools |
Reserved for future use. |
| CMFCToolBarsCustomizeDialog::EnableUserDefinedToolbars | Enables or disables creating new toolbars by using the Customize dialog box. |
| CMFCToolBarsCustomizeDialog::FillAllCommandsList | Populates the provided CListBox object with the commands in the All Commands category. |
| CMFCToolBarsCustomizeDialog::FillCategoriesComboBox | Populates the provided CComboBox object with the name of each command category in the Customize dialog box. |
| CMFCToolBarsCustomizeDialog::FillCategoriesListBox | Populates the provided CListBox object with the name of each command category in the Customize dialog box. |
| CMFCToolBarsCustomizeDialog::GetCommandName | Retrieves the name that is associated with the given command ID. |
| CMFCToolBarsCustomizeDialog::GetCountInCategory | Retrieves the number of items in the provided list that have a given text label. |
| CMFCToolBarsCustomizeDialog::GetFlags | Retrieves the set of flags that affect the behavior of the dialog box. |
CMFCToolBarsCustomizeDialog::GetThisClass |
Used by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type. |
| CMFCToolBarsCustomizeDialog::OnEditToolbarMenuImage | Starts an image editor so that a user can customize a toolbar button or menu item icon. |
| CMFCToolBarsCustomizeDialog::OnInitDialog | Overrides to augment property sheet initialization. (Overrides CPropertySheet::OnInitDialog.) |
| CMFCToolBarsCustomizeDialog::PostNcDestroy | Called by the framework after the window has been destroyed. (Overrides CPropertySheet::PostNcDestroy.) |
| CMFCToolBarsCustomizeDialog::RemoveButton | Removes the button with the specified command ID from the specified category, or from all categories. |
| CMFCToolBarsCustomizeDialog::RenameCategory | Renames a category in the list box of categories on the Commands tab. |
| CMFCToolBarsCustomizeDialog::ReplaceButton | Replaces a button in the list of commands on the Commands tab with a new toolbar button object. |
| CMFCToolBarsCustomizeDialog::SetUserCategory | Adds a category to the list of categories that will be displayed on the Commands tab. |
| Name | Description |
|---|---|
| CMFCToolBarsCustomizeDialog::CheckToolsValidity | Called by the framework to determine whether the list of user-defined tools is valid. |
| CMFCToolBarsCustomizeDialog::OnAfterChangeTool | Called by the framework when the properties of a user-defined tool change. |
| CMFCToolBarsCustomizeDialog::OnAssignKey | Determines whether a specified keyboard shortcut can be assigned to an action. |
| CMFCToolBarsCustomizeDialog::OnBeforeChangeTool | Determines whether a user-defined tool can be changed. |
| CMFCToolBarsCustomizeDialog::OnInitToolsPage | Called by the framework when the user chooses the Tools tab is requested. |
To display the Customize dialog box, create a CMFCToolBarsCustomizeDialog object and call the CMFCToolBarsCustomizeDialog::Create method.
While the Customize dialog box is active, the application works in a special mode that limits the user to customization tasks.
The following example demonstrates how to use various methods in the CMFCToolBarsCustomizeDialog class. The example shows how to replace a toolbar button in the list box of commands on the Commands page, enable creating new toolbars by using the Customize dialog box, and display the Customization dialog box. This code snippet is part of the IE Demo sample.
pDlgCust->ReplaceButton(ID_FAVORITS_DUMMY,
CMFCToolBarMenuButton((UINT)-1, menuFavorites, -1, strFavorites));
pDlgCust->EnableUserDefinedToolbars();
pDlgCust->Create();
CMFCToolBarsCustomizeDialog
Header: afxToolBarsCustomizeDialog.h
Inserts a toolbar button into the list of commands on the Commands page.
void AddButton(
UINT uiCategoryId,
const CMFCToolBarButton& button,
int iInsertBefore=-1);
void AddButton(
LPCTSTR lpszCategory,
const CMFCToolBarButton& button,
int iInsertBefore=-1);
uiCategoryId
[in] Specifies the category ID into which to insert the button.
button
[in] Specifies the button to insert.
iInsertBefore
[in] Specifies the zero-based index of a toolbar button before which the button is inserted.
lpszCategory
[in] Specifies the category string to insert the button.
The AddButton method ignores buttons that have the standard command IDs (such as ID_FILE_MRU_FILE1), commands that are not permitted (see CMFCToolBar::IsCommandPermitted) and dummy buttons.
This method creates a new object of the same type as button (usually a CMFCToolBarButton Class) by using the runtime class of the button. It then calls CMFCToolBarButton::CopyFrom to copy the data members of button, and inserts the copy into the specified category.
When the new button is inserted, it receives the OnAddToCustomizePage notification.
If iInsertBefore is -1, the button is appended to the list of categories; otherwise it is inserted before the item with the specified index.
The following example demonstrates how to use the AddButton method of the CMFCToolBarsCustomizeDialog class. This code snippet is part of the Slider sample.
CMFCToolBarsCustomizeDialog *pDlgCust = new CMFCToolBarsCustomizeDialog(this,
TRUE /* Automatic menus scaning */);
CSliderButton btnSlider(ID_SLIDER);
btnSlider.SetRange(0, 100);
pDlgCust->AddButton(_T("Edit"), btnSlider);
Loads a menu from the resources and calls CMFCToolBarsCustomizeDialog::AddMenuCommands to add that menu to the list of commands on the Commands page.
BOOL AddMenu(UINT uiMenuResId);
uiMenuResId
[in] Specifies the resource ID of a menu to load.
TRUE if a menu was added successfully; otherwise FALSE.
In the call to AddMenuCommands, bPopup is FALSE. As a result, that method does not add menu items that contain submenus to the list of commands. This method does add the menu items in the submenus to the list of commands.
Adds items to the list of commands in the Commands page to represent all the items in the specified menu.
void AddMenuCommands(
const CMenu* pMenu,
BOOL bPopup,
LPCTSTR lpszCategory=NULL,
LPCTSTR lpszMenuPath=NULL);
pMenu
[in] A pointer to the CMenu object to add.
bPopup
[in] Specifies whether to insert the popup menu items to the list of commands.
lpszCategory
[in] The name of the category to insert the menu.
lpszMenuPath
[in] A prefix that is added to the name when the command is shown in the All Categories list.
The AddMenuCommands method loops over all menu items of pMenu. For each menu item that does not contain a submenu, this method creates a CMFCToolBarButton Class object and calls the CMFCToolBarsCustomizeDialog::AddButton method to add the menu item as a toolbar button to the list of commands on the Commands page. Separators are ignored in this process.
If bPopup is TRUE, for each menu item that contains a submenu this method creates a CMFCToolBarMenuButton Class object and inserts it into the list of commands by calling AddButton. Otherwise menu items that contain submenus are not displayed in the list of commands. In either case, when AddMenuCommands encounters a menu item with a submenu it calls itself recursively, passing a pointer to the submenu as the pMenu parameter and appending the label of the submenu to lpszMenuPath.
Loads a toolbar from the resources. Then, for each command in the menu calls the CMFCToolBarsCustomizeDialog::AddButton method to insert a button in the list of commands on the Commands page under the specified category.
BOOL AddToolBar(
UINT uiCategoryId,
UINT uiToolbarResId);
BOOL AddToolBar(
LPCTSTR lpszCategory,
UINT uiToolbarResId);
uiCategoryId
[in] Specifies the resource ID of the category to add the toolbar to.
uiToolbarResId
[in] Specifies the resource ID of a toolbar whose commands are inserted into the list of commands.
lpszCategory
[in] Specifies the name of the category to which to add the toolbar.
TRUE if the method is successful; otherwise FALSE.
The following example demonstrates how to use the AddToolBar method in the CMFCToolBarsCustomizeDialog class. This code snippet is part of the Word Pad sample.
CMFCToolBarsCustomizeDialog *pDlgCust = new CMFCToolBarsCustomizeDialog(this,
TRUE /* Automatic menus scaning */,
AFX_CUSTOMIZE_MENU_SHADOWS | AFX_CUSTOMIZE_TEXT_LABELS |
AFX_CUSTOMIZE_MENU_ANIMATIONS);
pDlgCust->AddToolBar(_T("Format"), IDR_FORMATBAR);
The control that is used to represent each command is a CMFCToolBarButton Class object. After you add the toolbar, you can replace the button with a control of a derived type by calling CMFCToolBarsCustomizeDialog::ReplaceButton.
Verifies the validity of the list of user tools.
virtual BOOL CheckToolsValidity(const CObList& lstTools);
lstTools
[in] The list of user-defined tools to check.
Returns TRUE if the list of user-defined tools is valid; otherwise FALSE. The default implementation always returns TRUE.
The framework calls this method to verify the validity of objects that represent user-defined tools returned by CMFCToolBarsCustomizeDialog::CheckToolsValidity.
Override the CheckToolsValidity method in a class derived from CMFCToolBarsCustomizeDialog if you want to validate the user tools before the user closes the dialog box. If this method returns FALSE when the user clicks either the Close button in the upper-right corner of the dialog box or the button labeled Close in the lower-right corner of the dialog box, the dialog box displays the Tools tab instead of closing. If this method returns FALSE when the user clicks a tab to navigate away from the Tools tab, the navigation does not occur. You should display an appropriate message box to inform the user of the problem that caused validation to fail.
Constructs a CMFCToolBarsCustomizeDialog object.
CMFCToolBarsCustomizeDialog(
CFrameWnd* pWndParentFrame,
BOOL bAutoSetFromMenus = FALSE,
UINT uiFlags = (AFX_CUSTOMIZE_MENU_SHADOWS | AFX_CUSTOMIZE_TEXT_LABELS | AFX_CUSTOMIZE_MENU_ANIMATIONS | AFX_CUSTOMIZE_NOHELP),
CList <CRuntimeClass*, CRuntimeClass*>* p listCustomPages = NULL);
pWndParentFrame
[in] A pointer to the parent frame. This parameter must not be NULL.
bAutoSetFromMenus
[in] A Boolean value that specifies whether to add the menu commands from all menus to the list of commands on the Commands page. If this parameter is TRUE, the menu commands are added. Otherwise, the menu commands are not added.
uiFlags
[in] A combination of flags that affect the behavior of the dialog box. This parameter can be one or more of the following values:
AFX_CUSTOMIZE_MENU_SHADOWS
AFX_CUSTOMIZE_TEXT_LABELS
AFX_CUSTOMIZE_MENU_ANIMATIONS
AFX_CUSTOMIZE_NOHELP
AFX_CUSTOMIZE_CONTEXT_HELP
AFX_CUSTOMIZE_NOTOOLS
AFX_CUSTOMIZE_MENUAMPERS
AFX_CUSTOMIZE_NO_LARGE_ICONS
plistCustomPages
[in] A pointer to a list of CRuntimeClass objects that specify additional custom pages.
The plistCustomPages parameter refers to the list of CRuntimeClass objects that specify additional custom pages. The constructor adds more pages to the dialog box by using the CRuntimeClass::CreateObject method. See the CustomPages sample for an example that adds more pages to the Customize dialog box.
For more information about the values that you can pass in the uiFlags parameter, see CMFCToolBarsCustomizeDialog::GetFlags.
The following example demonstrates how to construct an object of the CMFCToolBarsCustomizeDialog class. This code snippet is part of the Custom Pages sample.
CMFCToolBarsCustomizeDialog *pDlgCust = new CMFCToolBarsCustomizeDialog(this,
TRUE /* Automatic menus scaning */,
AFX_CUSTOMIZE_MENU_SHADOWS | AFX_CUSTOMIZE_TEXT_LABELS |
AFX_CUSTOMIZE_MENU_ANIMATIONS, // default parameters
&lstCustomPages); // pointer to the list of runtime classes of the custom property pages
Displays the Customization dialog box.
virtual BOOL Create();
TRUE if the customization property sheet is created successfully; otherwise FALSE.
Call the Create method only after you fully initialize the class.
Enables or disables creating new toolbars by using the Customize dialog box.
void EnableUserDefinedToolbars(BOOL bEnable=TRUE);
bEnable
[in] TRUE to enable the user-defined toolbars; FALSE to disable the toolbars.
If bEnable is TRUE, the New, Rename and Delete buttons are displayed on the Toolbars page.
By default, or if bEnable is FALSE, these buttons are not displayed and the user cannot define new toolbars.
Populates the provided CListBox object with the commands in the All Commands category.
virtual void FillAllCommandsList(CListBox& wndListOfCommands) const;
wndListOfCommands
[out] A reference to the CListBox object to populate.
The All Commands category contains the commands of all categories. The CMFCToolBarsCustomizeDialog::AddButton method adds the command that is associated with the provided button to the All Commands category for you.
This method clears the contents of the provided CListBox object before populating it with the commands in the All Commands category.
The CMFCMousePropertyPage class uses this method to populate the double-click event list box.
Populates the provided CComboBox object with the name of each command category in the Customize dialog box.
void FillCategoriesComboBox(
CComboBox& wndCategory,
BOOL bAddEmpty = TRUE) const;
wndCategory
[out] A reference to the CComboBox object to populate.
bAddEmpty
[in] A Boolean value that specifies whether to add categories to the combo box that do not have commands. If this parameter is TRUE, empty categories are added to the combo box. Otherwise, empty categories are not added.
This method is like the CMFCToolBarsCustomizeDialog::FillCategoriesListBox method except that this method works with a CComboBox object.
This method does not clear the contents of the CComboBox object before populating it. It guarantees that the All Commands category is the final item in the combo box.
You can add new command categories by using the CMFCToolBarsCustomizeDialog::AddButton method. You can change the name of an existing category by using the CMFCToolBarsCustomizeDialog::RenameCategory method.
The CMFCToolBarsKeyboardPropertyPage and CMFCKeyMapDialog classes use this method to categorize keyboard mappings.
Populates the provided CListBox object with the name of each command category in the Customize dialog box.
void FillCategoriesListBox(
CListBox& wndCategory,
BOOL bAddEmpty = TRUE) const;
wndCategory
[out] A reference to the CListBox object to populate.
bAddEmpty
[in] A Boolean value that specifies whether to add categories to the list box that do not have commands. If this parameter is TRUE, empty categories are added to the list box. Otherwise, empty categories are not added.
This method is like the CMFCToolBarsCustomizeDialog::FillCategoriesComboBox method except that this method works with a CListBox object.
This method does not clear the contents of the CListBox object before populating it. It guarantees that the All Commands category is the final item in the list box.
You can add new command categories by using the CMFCToolBarsCustomizeDialog::AddButton method. You can change the name of an existing category by using the CMFCToolBarsCustomizeDialog::RenameCategory method.
The CMFCToolBarsCommandsPropertyPage class uses this method to show the list of commands that is associated with each command category.
Retrieves the name that is associated with the given command ID.
LPCTSTR GetCommandName(UINT uiCmd) const;
uiCmd
[in] The ID of the command to retrieve.
The name that is associated with the given command ID, or NULL if the command does not exist.
Retrieves the number of items in the provided list that have a given text label.
int GetCountInCategory(
LPCTSTR lpszItemName,
const CObList& lstCommands) const;
lpszItemName
[in] The text label to match.
lstCommands
[in] A reference to a list that contains CMFCToolBarButton objects.
The number of items in the provided list whose text label equals lpszItemName.
Each element in the provided object list must be of type CMFCToolBarButton. This method compares lpszItemName with the CMFCToolBarButton::m_strText data member.
Retrieves the set of flags that affect the behavior of the dialog box.
UINT GetFlags() const;
The set of flags that affect the behavior of the dialog box.
This method retrieves the value of the uiFlags parameter that is passed to the constructor. The return value can be one or more of the following values:
| Name | Description |
|---|---|
| AFX_CUSTOMIZE_MENU_SHADOWS | Allows the user to specify the shadow appearance of the menu. |
| AFX_CUSTOMIZE_TEXT_LABELS | Allows the user to specify whether text labels are shown underneath the toolbar button images. |
| AFX_CUSTOMIZE_MENU_ANIMATIONS | Allows the user to specify the menu animation style. |
| AFX_CUSTOMIZE_NOHELP | Removes the help button from the customization dialog box. |
| AFX_CUSTOMIZE_CONTEXT_HELP | Enables the WS_EX_CONTEXTHELP visual style. |
| AFX_CUSTOMIZE_NOTOOLS | Removes the Tools page from the customization dialog box. This flag is valid if your application uses the CUserToolsManager class. |
| AFX_CUSTOMIZE_MENUAMPERS | Allows button captions to contain the ampersand ( &) character. |
| AFX_CUSTOMIZE_NO_LARGE_ICONS | Removes the Large Icons option from the customization dialog box. |
For more information about the WS_EX_CONTEXTHELP visual style, see Extended Window Styles.
Responds to a change in a user tool immediately after it occurs.
virtual void OnAfterChangeTool(CUserTool* pSelTool);
pSelTool
[in, out] A pointer to the user tool object that has been changed.
This method is called by the framework when a user changes the properties of a user-defined tool. The default implementation does nothing. Override this method in a class derived from CMFCToolBarsCustomizeDialog to perform processing after a change to a user tool occurs.
Validates keyboard shortcuts as a user defines them.
virtual BOOL OnAssignKey(ACCEL* pAccel);
pAccel
[in, out] Pointer to the proposed keyboard assignment that is expressed as an ACCEL struct.
TRUE if the key can be assigned, or FALSE if the key cannot be assigned. The default implementation always returns TRUE.
Override this method in a derived class to perform extra processing when a user assigns a new keyboard shortcut, or to validate keyboard shortcuts as the user defines them. To prevent a shortcut from being assigned, return FALSE. You should also display a message box or otherwise inform the user of the reason why the keyboard shortcut was rejected.
Performs custom processing when a change to a user tool when the user is about to apply a change.
virtual void OnBeforeChangeTool(CUserTool* pSelTool);
pSelTool
[in, out] A pointer to the user tool object that is about to be replaced.
This method is called by the framework when the properties of a user-defined tool is about to change. The default implementation does nothing. Override the OnBeforeChangeTool method in a class derived from CMFCToolBarsCustomizeDialog if you want to perform processing before a change to a user tool occurs, such as releasing resources that pSelTool uses.
Starts an image editor so that a user can customize a toolbar button or menu item icon.
virtual BOOL OnEditToolbarMenuImage(
CWnd* pWndParent,
CBitmap& bitmap,
int nBitsPerPixel);
pWndParent
[in] A pointer to the parent window.
bitmap
[in] A reference to a bitmap object to be edited.
nBitsPerPixel
[in] Bitmap color resolution, in bits per pixel.
TRUE if a change is being committed; otherwise FALSE. The default implementation displays a dialog box and returns TRUE if the user clicks OK, or FALSE if the user clicks Cancel or the Close button.
This method is called by the framework when the user runs the image editor. The default implementation displays CMFCImageEditorDialog Class dialog box. Override OnEditToolbarMenuImage in a derived class to use a custom image editor.
Overrides to augment property sheet initialization.
virtual BOOL OnInitDialog();
The result of calling the CPropertySheet::OnInitDialog method.
This method extends the base class implementation, CPropertySheet::OnInitDialog, by displaying the Close button, by making sure that the dialog box fits the current screen size, and by moving the Help button to the lower-left corner of the dialog box.
Handles the notification from the framework that the Tools page is about to be initialized.
virtual void OnInitToolsPage();
The default implementation does nothing. Override this method in a derived class to process this notification.
Called by the framework after the window has been destroyed.
virtual void PostNcDestroy();
This method extends the base class implementation, CPropertySheet::PostNcDestroy, by restoring the application to the previous mode.
The CMFCToolBarsCustomizeDialog::Create method puts the application in a special mode that limits the user to customization tasks.
Removes the button with the specified command ID from the specified category, or from all categories.
int RemoveButton(
UINT uiCategoryId,
UINT uiCmdId);
int RemoveButton(
LPCTSTR lpszCategory,
UINT uiCmdId);
uiCategoryId
[in] Specifies the category ID from which to remove the button.
uiCmdId
[in] Specifies the command ID of the button.
lpszCategory
[in] Specifies the name of the category from which to remove the button.
The zero-based index of the removed button, or -1 if the specified command ID was not found in the specified category. If uiCategoryId is -1, the return value is 0.
To remove a button from all categories, call the first overload of this method and set uiCategoryId to -1.
Renames a category in the list box of categories on the Commands page.
BOOL RenameCategory(
LPCTSTR lpszCategoryOld,
LPCTSTR lpszCategoryNew);
lpszCategoryOld
[in] The category name to change.
lpszCategoryNew
[in] The new category name.
TRUE if the method was successful; otherwise FALSE.
The category name must be unique.
Replaces a toolbar button in the list box of commands on the Commands page.
void ReplaceButton(
UINT uiCmd,
const CMFCToolBarButton& button);
uiCmd
[in] Specifies the command of the button to be replaced.
button
[in] A const reference to the toolbar button object that replaces the old button.
When CMFCToolBarsCustomizeDialog::AddMenu, CMFCToolBarsCustomizeDialog::AddMenuCommands, or CMFCToolBarsCustomizeDialog::AddToolBar adds a command to the Commands page, that command is in the form of a CMFCToolBarButton Class object (or a CMFCToolBarMenuButton Class object for a menu item that contains a submenu added by AddMenuCommands). The framework also calls these three methods to add commands automatically. If you want a command to be represented by a derived type instead, call ReplaceButton and pass in a button of the derived type.
The following example demonstrates how to use the ReplaceButton method in the CMFCToolBarsCustomizeDialog class. This code snippet is part of the Visual Studio Demo sample.
// CMFCToolBarsCustomizeDialog* pDlgCust
// CMFCToolBarComboBoxButton comboButtonConfig
pDlgCust->ReplaceButton(ID_DUMMY_SELECT_ACTIVE_CONFIGURATION, comboButtonConfig);
Specifies which category in the list of categories on the Commands page is the user category. You must call this function before you call CMFCToolBarsCustomizeDialog::Create.
BOOL SetUserCategory(LPCTSTR lpszCategory);
lpszCategory
[in] The name of the category.
TRUE if the method is successful; otherwise FALSE.
The user category setting is not currently used by the framework.