CMFCToolBarsCustomizeDialog 类
使用户能够自定义应用程序中的工具栏、菜单、键盘快捷键、用户定义的工具和视觉样式的无模式选项卡对话框（CPropertySheet 类）。 通常，用户可从 “工具” 菜单中选择 “自定义” 来访问此对话框。
“自定义”对话框包含六个选项卡：命令、工具栏、工具、键盘、菜单和选项。
语法
class CMFCToolBarsCustomizeDialog : public CPropertySheet
成员
公共构造函数
| 名称 | 描述 |
|---|---|
| CMFCToolBarsCustomizeDialog::CMFCToolBarsCustomizeDialog | 构造 CMFCToolBarsCustomizeDialog 对象。 |
CMFCToolBarsCustomizeDialog::~CMFCToolBarsCustomizeDialog |
析构函数。 |
公共方法
受保护方法
| 名称 | 描述 |
|---|---|
| CMFCToolBarsCustomizeDialog::CheckToolsValidity | 由框架调用以确定用户定义的工具列表是否有效。 |
| CMFCToolBarsCustomizeDialog::OnAfterChangeTool | 当用户定义工具的属性发生更改时由框架调用。 |
| CMFCToolBarsCustomizeDialog::OnAssignKey | 确定是否可以将指定的键盘快捷方式分配给操作。 |
| CMFCToolBarsCustomizeDialog::OnBeforeChangeTool | 确定是否可以更改用户定义工具。 |
| CMFCToolBarsCustomizeDialog::OnInitToolsPage | 当用户选择请求“工具”选项卡时由框架调用。 |
注解
若要显示“自定义”对话框，请创建一个 CMFCToolBarsCustomizeDialog 对象并调用 CMFCToolBarsCustomizeDialog::Create 方法。
当“自定义”对话框处于活动状态时，应用程序以特殊模式工作，限制用户仅完成自定义任务。
示例
下面的示例演示了如何使用 CMFCToolBarsCustomizeDialog 类中的各种方法。 该示例演示如何替换“命令”页上命令列表框中的工具栏按钮，如何使用“自定义”对话框启用创建新的工具栏，以及如何显示“自定义”对话框。 此代码片段是 IE 演示示例的一部分。
pDlgCust->ReplaceButton(ID_FAVORITS_DUMMY,
CMFCToolBarMenuButton((UINT)-1, menuFavorites, -1, strFavorites));
pDlgCust->EnableUserDefinedToolbars();
pDlgCust->Create();
继承层次结构
CMFCToolBarsCustomizeDialog
要求
标头：afxToolBarsCustomizeDialog.h
CMFCToolBarsCustomizeDialog::AddButton
在“命令”页上的命令列表中插入工具栏按钮。
void AddButton(
UINT uiCategoryId,
const CMFCToolBarButton& button,
int iInsertBefore=-1);
void AddButton(
LPCTSTR lpszCategory,
const CMFCToolBarButton& button,
int iInsertBefore=-1);
参数
uiCategoryId
[in] 指定要在其中插入按钮的类别 ID。
按钮
[in] 指定要插入的按钮。
iInsertBefore
[in] 指定在其前面插入按钮的工具栏按钮的从零开始的索引。
lpszCategory
[in] 指定要插入按钮的类别字符串。
备注
AddButton 方法忽略具有标准命令 ID（例如 ID_FILE_MRU_FILE1）的按钮、不允许的命令（请参阅 CMFCToolBar::IsCommandPermitted）和虚拟按钮。
此方法使用按钮的运行时类创建类型与 button 相同的新对象（通常是 CMFCToolBarButton Class）。 然后，它会调用 CMFCToolBarButton::CopyFrom 复制按钮的数据成员，并将副本插入指定类别。
插入新按钮时，它会收到 OnAddToCustomizePage 通知。
如果 iInsertBefore 为 -1，则按钮将追加到类别列表；否则将其插入具有指定索引的项之前。
示例
下面的示例演示如何使用 CMFCToolBarsCustomizeDialog 类的 AddButton 方法。 此代码片段是 Slider 示例的一部分。
CMFCToolBarsCustomizeDialog *pDlgCust = new CMFCToolBarsCustomizeDialog(this,
TRUE /* Automatic menus scaning */);
CSliderButton btnSlider(ID_SLIDER);
btnSlider.SetRange(0, 100);
pDlgCust->AddButton(_T("Edit"), btnSlider);
CMFCToolBarsCustomizeDialog::AddMenu
从资源加载菜单，并调用 CMFCToolBarsCustomizeDialog::AddMenuCommands 将菜单添加到“命令”页上的命令列表中。
BOOL AddMenu(UINT uiMenuResId);
参数
uiMenuResId
[in] 指定要加载的菜单的资源 ID。
返回值
如果成功添加了菜单，则为 TRUE；否则为 FALSE。
备注
在对 AddMenuCommands 的调用中，bPopup 为 FALSE。 因此，该方法不会向命令列表添加包含子菜单的菜单项。 此方法将子菜单中的菜单项添加到命令列表中。
CMFCToolBarsCustomizeDialog::AddMenuCommands
将项添加到“命令”页中的命令列表中，以表示指定菜单中的所有项。
void AddMenuCommands(
const CMenu* pMenu,
BOOL bPopup,
LPCTSTR lpszCategory=NULL,
LPCTSTR lpszMenuPath=NULL);
参数
pMenu
[in] 指向要添加的 CMenu 对象的指针。
bPopup
[in] 指定是否将弹出菜单项插入命令列表。
lpszCategory
[in] 要插入菜单的类别名称。
lpszMenuPath
[in] 在“所有类别”列表中显示命令时添加到名称的前缀。
备注
AddMenuCommands 方法循环访问 pMenu 的所有菜单项。 对于每个不包含子菜单的菜单项，此方法会创建一个 CMFCToolBarButton Class 对象并调用 CMFCToolBarsCustomizeDialog::AddButton 方法将菜单项作为工具栏按钮添加到“命令”页面上的命令列表。 在此过程中会忽略分隔符。
如果 bPopup 为 TRUE，则此方法会为每个包含子菜单的菜单项创建一个 CMFCToolBarMenuButton Class 对象，并通过调用 AddButton 将其插入命令列表中。 否则，包含子菜单的菜单项不会显示在命令列表中。 无论哪种情况，当 AddMenuCommands 遇到带有子菜单的菜单项时，它会递归调用自身，将指向子菜单的指针作为 pMenu 参数传递，并将子菜单的标签附加到 lpszMenuPath。
CMFCToolBarsCustomizeDialog::AddToolBar
从资源加载工具栏。 然后，对于菜单中的每个命令，调用 CMFCToolBarsCustomizeDialog::AddButton 方法，在指定类别下的“命令”页上的命令列表中插入一个按钮。
BOOL AddToolBar(
UINT uiCategoryId,
UINT uiToolbarResId);
BOOL AddToolBar(
LPCTSTR lpszCategory,
UINT uiToolbarResId);
参数
uiCategoryId
[in] 指定要添加工具栏的类别的资源 ID。
uiToolbarResId
[in] 指定将其命令插入到命令列表的工具栏的资源 ID。
lpszCategory
[in] 指定要添加工具栏的类别的名称。
返回值
如果此方法成功，则为 TRUE；否则为 FALSE。
示例
以下示例演示了如何在 CMFCToolBarsCustomizeDialog 类中使用 AddToolBar 方法。 此代码片段属于 Word Pad 示例。
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);
注解
用于表示每个命令的控件是 CMFCToolBarButton Class 对象。 添加工具栏后，可以通过调用 CMFCToolBarsCustomizeDialog::ReplaceButton 将按钮替换为派生类型的控件。
CMFCToolBarsCustomizeDialog::CheckToolsValidity
验证用户工具列表的有效性。
virtual BOOL CheckToolsValidity(const CObList& lstTools);
参数
lstTools
[in] 要检查的用户定义工具的列表。
返回值
如果用户定义工具的列表有效，则返回 TRUE；否则返回 FALSE。 默认实现始终返回 TRUE。
注解
框架调用此方法来验证表示 CMFCToolBarsCustomizeDialog::CheckToolsValidity 返回的用户定义工具的对象的有效性。
如果要在用户关闭对话框之前验证用户工具，请在派生自 CMFCToolBarsCustomizeDialog 的类中重写 CheckToolsValidity 方法。 如果用户单击对话框右上角的“关闭”按钮或对话框右下角标记为“关闭”的按钮时，此方法返回 FALSE，则对话框将显示“工具”选项卡而不是“正在关闭”。 如果用户单击选项卡以导航离开“工具”选项卡时，此方法返回 FALSE，则不会发生导航。 应显示适当的消息框，告知用户导致验证失败的问题。
CMFCToolBarsCustomizeDialog::CMFCToolBarsCustomizeDialog
构造 CMFCToolBarsCustomizeDialog 对象。
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] 指向父框架的指针。 此参数不能为 NULL。
bAutoSetFromMenus
[in] 指定是否将所有菜单上的菜单命令添加到“命令”页上的命令列表的布尔值。 如果此参数为 TRUE，则添加菜单命令。 否则，不会添加菜单命令。
uiFlags
[in] 影响此对话框的行为的标志组合。 此参数可能是以下一个或多个值：
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] 指向指定其他自定义页面的 CRuntimeClass 对象列表的指针。
备注
plistCustomPages 参数是指指定其他自定义页面的 CRuntimeClass 对象的列表。 构造函数使用 CRuntimeClass::CreateObject 方法向对话框添加更多页面。 有关向“自定义”对话框添加更多页面的示例，请参阅 CustomPages 示例。
有关可以传入 uiFlags 参数的值的详细信息，请参阅 CMFCToolBarsCustomizeDialog::GetFlags。
示例
以下示例演示如何构造 CMFCToolBarsCustomizeDialog 类的对象。 此代码片段属于自定义页面示例。
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
CMFCToolBarsCustomizeDialog::Create
显示“自定义”对话框。
virtual BOOL Create();
返回值
如果已成功创建自定义属性表，则为 TRUE；否则为 FALSE。
备注
仅在完全初始化类后调用 Create 方法。
CMFCToolBarsCustomizeDialog::EnableUserDefinedToolbars
使用“自定义”对话框启用或禁用创建新工具栏。
void EnableUserDefinedToolbars(BOOL bEnable=TRUE);
参数
bEnable
[in] 若要启用用户定义工具栏，则为 TRUE；若要禁用工具栏，则为 FALSE。
备注
如果 bEnable 为 TRUE，则“工具栏”页上会显示“新建”、“重命名”和“删除”按钮。
默认情况下，或者如果 bEnable 为 FALSE，则不会显示这些按钮，并且用户无法定义新工具栏。
CMFCToolBarsCustomizeDialog::FillAllCommandsList
使用“所有命令”类别中的命令填充所提供的 CListBox 对象。
virtual void FillAllCommandsList(CListBox& wndListOfCommands) const;
参数
wndListOfCommands
[out] 对要填充的 CListBox 对象的引用。
备注
“所有命令”类别包含所有类别的命令。 CMFCToolBarsCustomizeDialog::AddButton 方法会将与提供的按钮关联的命令添加到“所有命令”类别中。
此方法在使用“所有命令”类别中的命令填充提供的 CListBox 对象之前，会清除该对象的内容。
CMFCMousePropertyPage 类使用此方法填充双击事件列表框。
CMFCToolBarsCustomizeDialog::FillCategoriesComboBox
使用“自定义”对话框中每个命令类别的名称填充所提供的 CComboBox 对象。
void FillCategoriesComboBox(
CComboBox& wndCategory,
BOOL bAddEmpty = TRUE) const;
参数
wndCategory
[out] 对要填充的 CComboBox 对象的引用。
bAddEmpty
[in] 指定是否向没有命令的组合框添加类别的布尔值。 如果此参数为 TRUE，则空类别将添加到组合框中。 否则，不会添加空类别。
备注
此方法类似于 CMFCToolBarsCustomizeDialog::FillCategoriesListBox 方法，只是此方法适用于 CComboBox 对象。
此方法在填充 CComboBox 对象之前不会清除该对象的内容。 它保证“所有命令”类别是组合框中的最后一项。
可以使用 CMFCToolBarsCustomizeDialog::AddButton 方法添加新的命令类别。 可以使用 CMFCToolBarsCustomizeDialog::RenameCategory 方法更改现有类别的名称。
CMFCToolBarsKeyboardPropertyPage 和 CMFCKeyMapDialog 类使用此方法对键盘映射进行分类。
CMFCToolBarsCustomizeDialog::FillCategoriesListBox
使用“自定义”对话框中每个命令类别的名称填充所提供的 CListBox 对象。
void FillCategoriesListBox(
CListBox& wndCategory,
BOOL bAddEmpty = TRUE) const;
参数
wndCategory
[out] 对要填充的 CListBox 对象的引用。
bAddEmpty
[in] 指定是否向没有命令的列表框添加类别的布尔值。 如果此参数为 TRUE，则空类别将添加到列表框中。 否则，不会添加空类别。
备注
此方法类似于 CMFCToolBarsCustomizeDialog::FillCategoriesComboBox 方法，只是此方法适用于 CListBox 对象。
此方法在填充 CListBox 对象之前不会清除该对象的内容。 它保证“所有命令”类别是列表框中的最后一项。
可以使用 CMFCToolBarsCustomizeDialog::AddButton 方法添加新的命令类别。 可以使用 CMFCToolBarsCustomizeDialog::RenameCategory 方法更改现有类别的名称。
CMFCToolBarsCommandsPropertyPage 类使用此方法显示与每个命令类别关联的命令列表。
CMFCToolBarsCustomizeDialog::GetCommandName
检索与给定命令 ID 关联的名称。
LPCTSTR GetCommandName(UINT uiCmd) const;
参数
uiCmd
[in] 要检索的命令的 ID。
返回值
与给定命令 ID 关联的名称；或者如果命令不存在，则为 NULL。
CMFCToolBarsCustomizeDialog::GetCountInCategory
检索在所提供的列表中具有给定文本标签的项数。
int GetCountInCategory(
LPCTSTR lpszItemName,
const CObList& lstCommands) const;
参数
lpszItemName
[in] 要匹配的文本标签。
lstCommands
[in] 对包含 CMFCToolBarButton 对象的列表的引用。
返回值
所提供列表中文本标签等于 lpszItemName 的项的数量。
注解
所提供的对象列表中的每个元素都必须为 CMFCToolBarButton 类型。 此方法将 lpszItemName 与 CMFCToolBarButton::m_strText 数据成员进行比较。
CMFCToolBarsCustomizeDialog::GetFlags
检索影响对话框行为的标志集。
UINT GetFlags() const;
返回值
影响对话框行为的标志集。
备注
此方法检索传递给构造函数的 uiFlags 参数的值。 返回值可以为以下一个或多个值：
| 名称 | 描述 |
|---|---|
| AFX_CUSTOMIZE_MENU_SHADOWS | 允许用户指定菜单的阴影外观。 |
| AFX_CUSTOMIZE_TEXT_LABELS | 允许用户指定是否在工具栏按钮图像下显示文本标签。 |
| AFX_CUSTOMIZE_MENU_ANIMATIONS | 允许用户指定菜单动画样式。 |
| AFX_CUSTOMIZE_NOHELP | 从自定义对话框中移除帮助按钮。 |
| AFX_CUSTOMIZE_CONTEXT_HELP | 启用 WS_EX_CONTEXTHELP 视觉样式。 |
| AFX_CUSTOMIZE_NOTOOLS | 从自定义对话框中移除“工具”页面。 如果应用程序使用 CUserToolsManager 类，则此标志有效。 |
| AFX_CUSTOMIZE_MENUAMPERS | 允许按钮描述文字包含和 (&) 字符。 |
| AFX_CUSTOMIZE_NO_LARGE_ICONS | 从自定义对话框中移除“大图标”选项。 |
有关 WS_EX_CONTEXTHELP 视觉样式的详细信息，请参阅扩展的窗口样式。
CMFCToolBarsCustomizeDialog::OnAfterChangeTool
在用户工具发生更改后立即响应更改。
virtual void OnAfterChangeTool(CUserTool* pSelTool);
参数
pSelTool
[in, out] 指向已更改的用户工具对象的指针。
备注
当用户更改用户定义工具的属性时，框架将调用此方法。 默认实现不执行任何操作。 在派生自 CMFCToolBarsCustomizeDialog 的类中重写此方法，以在用户工具发生更改后执行处理。
CMFCToolBarsCustomizeDialog::OnAssignKey
在用户定义键盘快捷方式时进行验证。
virtual BOOL OnAssignKey(ACCEL* pAccel);
参数
pAccel
[in, out] 指向建议的以 ACCEL 结构表示的键盘分配的指针。
返回值
如果可以分配密钥，则为 TRUE；如果无法分配密钥，则为 FALSE。 默认实现始终返回 TRUE。
备注
在派生类中此方法，以在用户分配新的键盘快捷方式时执行额外处理，或在用户定义键盘快捷方式时进行验证。 若要防止分配快捷方式，请返回 FALSE。 还应显示一个消息框，否则应通知用户键盘快捷方式被拒绝的原因。
CMFCToolBarsCustomizeDialog::OnBeforeChangeTool
当用户即将应用更改时，对用户工具进行更改时，执行自定义处理。
virtual void OnBeforeChangeTool(CUserTool* pSelTool);
参数
pSelTool
[in, out] 指向即将替换的用户工具对象的指针。
备注
当用户定义工具的属性即将更改时，框架会调用此方法。 默认实现不执行任何操作。 如果要在用户工具发生更改（例如释放 pSelTool 使用的资源）之前执行处理，请在派生自 CMFCToolBarsCustomizeDialog 的类中重写 OnBeforeChangeTool 方法。
CMFCToolBarsCustomizeDialog::OnEditToolbarMenuImage
启动图像编辑器，以便用户可以自定义工具栏按钮或菜单项图标。
virtual BOOL OnEditToolbarMenuImage(
CWnd* pWndParent,
CBitmap& bitmap,
int nBitsPerPixel);
参数
pWndParent
[in] 指向父窗口的指针。
位图
[in] 对要编辑的位图对象的引用。
nBitsPerPixel
[in] 位图颜色分辨率（以每像素位数为单位）。
返回值
如果正在提交更改，则为 TRUE；否则为 FALSE。 默认实现显示一个对话框，如果用户单击“确定”，则返回 TRUE；如果用户单击“取消”或“关闭”按钮，则返回 FALSE。
注解
当用户运行图像编辑器时，框架会调用此方法。 默认实现显示 CMFCImageEditorDialog 类 对话框。 在派生类中重写 OnEditToolbarMenuImage 以使用自定义图像编辑器。
CMFCToolBarsCustomizeDialog::OnInitDialog
重写以增强属性表初始化。
virtual BOOL OnInitDialog();
返回值
调用 CPropertySheet::OnInitDialog 方法的结果。
备注
此方法通过显示“关闭”按钮、确保对话框适合当前屏幕尺寸以及将“帮助”按钮移动到对话框的左下角，来扩展基类实现 CPropertySheet::OnInitDialog。
CMFCToolBarsCustomizeDialog::OnInitToolsPage
处理来自框架的通知：“工具”页即将初始化。
virtual void OnInitToolsPage();
注解
默认实现不执行任何操作。 在派生类中重写此方法以处理此通知。
CMFCToolBarsCustomizeDialog::PostNcDestroy
在窗口销毁后由框架调用。
virtual void PostNcDestroy();
备注
此方法通过将应用程序还原到上一模式来扩展基类实现 CPropertySheet::PostNcDestroy。
CMFCToolBarsCustomizeDialog::Create 方法将应用程序置于一种特殊模式，以限制用户只能完成自定义任务。
CMFCToolBarsCustomizeDialog::RemoveButton
从指定类别或从所有类别中删除具有指定命令 ID 的按钮。
int RemoveButton(
UINT uiCategoryId,
UINT uiCmdId);
int RemoveButton(
LPCTSTR lpszCategory,
UINT uiCmdId);
参数
uiCategoryId
[in] 指定要从中移除按钮的类别 ID。
uiCmdId
[in] 指定按钮的命令 ID。
lpszCategory
[in] 指定要从中移除按钮的类别的名称。
返回值
移除按钮的从零开始的索引；如果未在指定类别中找到指定的命令 ID，则为 -1。 如果 uiCategoryId 为 -1，则返回值为 0。
备注
若要移除所有类别中的按钮，请调用此方法的第一个重载并将 uiCategoryId 设置为 -1。
CMFCToolBarsCustomizeDialog::RenameCategory
重命名“命令”页上类别列表框中的类别。
BOOL RenameCategory(
LPCTSTR lpszCategoryOld,
LPCTSTR lpszCategoryNew);
参数
lpszCategoryOld
[in] 要更改的类别名称。
lpszCategoryNew
[in] 新类别名称。
返回值
如果此方法成功，则为 TRUE；否则为 FALSE。
注解
类别名称必须唯一。
CMFCToolBarsCustomizeDialog::ReplaceButton
在“命令”页上的命令列表框中替换工具栏按钮。
void ReplaceButton(
UINT uiCmd,
const CMFCToolBarButton& button);
参数
uiCmd
[in] 指定要替换的按钮的命令。
按钮
[in] 对替换旧按钮的工具栏按钮对象的 const 引用。
备注
当 CMFCToolBarsCustomizeDialog::AddMenu、CMFCToolBarsCustomizeDialog::AddMenuCommands 或 CMFCToolBarsCustomizeDialog::AddToolBar 将命令添加到“命令”页面时，该命令采用 CMFCToolBarButton Class 对象（或包含由 AddMenuCommands 添加的子菜单的菜单项的 CMFCToolBarMenuButton Class 对象）的形式。 框架还调用这三种方法来自动添加命令。 如果希望命令改由派生类型表示，请调用 ReplaceButton 并传入派生类型的按钮。
示例
以下示例演示了如何在 CMFCToolBarsCustomizeDialog 类中使用 ReplaceButton 方法。 此代码片段是 Visual Studio 演示示例的一部分。
// CMFCToolBarsCustomizeDialog* pDlgCust
// CMFCToolBarComboBoxButton comboButtonConfig
pDlgCust->ReplaceButton(ID_DUMMY_SELECT_ACTIVE_CONFIGURATION, comboButtonConfig);
CMFCToolBarsCustomizeDialog::SetUserCategory
指定“命令”页上类别列表中的哪个类别是用户类别。 在调用 CMFCToolBarsCustomizeDialog::Create 之前，必须调用此函数。
BOOL SetUserCategory(LPCTSTR lpszCategory);
参数
lpszCategory
[in] 类别的名称。
返回值
如果此方法成功，则为 TRUE；否则为 FALSE。
备注
框架当前不使用用户类别设置。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈