syncfusion-winforms-main-frame-bar-manager
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion WinForms MainFrameBarManager
实现Syncfusion WinForms MainFrameBarManager
When to Use This Skill
何时使用该技能
The MainFrameBarManager component is essential when you need to:
- Create hierarchical menu structures (File, Edit, View menus with submenus)
- Build customizable toolbars and command bars
- Add keyboard shortcuts and mnemonics to menu items
- Implement context menus and interactive tooltips
- Support MDI (Multiple Document Interface) applications with merged menus
- Persist menu and toolbar state between application sessions
- Enable end-users to customize menu layout at runtime
This component follows the XP Menus Framework pattern, providing a professional, enterprise-grade menu management system for Windows Forms applications.
当你需要完成以下需求时，MainFrameBarManager组件是必不可少的：
- 创建分层菜单结构（包含子菜单的文件、编辑、视图菜单）
- 构建可自定义的工具栏和命令栏
- 为菜单项添加键盘快捷键和助记键
- 实现上下文菜单和交互式工具提示
- 支持带有合并菜单的MDI（多文档界面）应用程序
- 在应用程序会话之间持久化保存菜单和工具栏状态
- 允许最终用户在运行时自定义菜单布局
该组件遵循XP Menus Framework模式，为Windows Forms应用程序提供专业的企业级菜单管理系统。
Quick Start Example
快速入门示例
csharp
// Create MainFrameBarManager
MainFrameBarManager mainFrameBarManager1 = new MainFrameBarManager();
mainFrameBarManager1.Style = Syncfusion.Windows.Forms.VisualStyle.Office2016Colorful;
mainFrameBarManager1.Form = this;
// Create a bar (menu container)
Bar fileBar = new Syncfusion.Windows.Forms.Tools.XPMenus.Bar();
fileBar.BarName = "File";
fileBar.Caption = "File";
fileBar.Manager = mainFrameBarManager1;
// Create parent menu item
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "&File";
// Create sub-menu items
BarItem newItem = new BarItem() { Text = "&New" };
BarItem openItem = new BarItem() { Text = "&Open" };
BarItem exitItem = new BarItem() { Text = "E&xit" };
// Assign shortcuts and mnemonics
newItem.Shortcut = Shortcut.CtrlN;
openItem.Shortcut = Shortcut.CtrlO;
exitItem.Shortcut = Shortcut.AltF4;
// Build hierarchy
fileMenu.Items.AddRange(new BarItem[] { newItem, openItem, exitItem });
fileBar.Items.Add(fileMenu);
// Add to manager
mainFrameBarManager1.Items.AddRange(new BarItem[] { fileMenu, newItem, openItem, exitItem });
mainFrameBarManager1.Bars.Add(fileBar);
mainFrameBarManager1.Categories.Add("Menu");csharp
// Create MainFrameBarManager
MainFrameBarManager mainFrameBarManager1 = new MainFrameBarManager();
mainFrameBarManager1.Style = Syncfusion.Windows.Forms.VisualStyle.Office2016Colorful;
mainFrameBarManager1.Form = this;
// Create a bar (menu container)
Bar fileBar = new Syncfusion.Windows.Forms.Tools.XPMenus.Bar();
fileBar.BarName = "File";
fileBar.Caption = "File";
fileBar.Manager = mainFrameBarManager1;
// Create parent menu item
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "&File";
// Create sub-menu items
BarItem newItem = new BarItem() { Text = "&New" };
BarItem openItem = new BarItem() { Text = "&Open" };
BarItem exitItem = new BarItem() { Text = "E&xit" };
// Assign shortcuts and mnemonics
newItem.Shortcut = Shortcut.CtrlN;
openItem.Shortcut = Shortcut.CtrlO;
exitItem.Shortcut = Shortcut.AltF4;
// Build hierarchy
fileMenu.Items.AddRange(new BarItem[] { newItem, openItem, exitItem });
fileBar.Items.Add(fileMenu);
// Add to manager
mainFrameBarManager1.Items.AddRange(new BarItem[] { fileMenu, newItem, openItem, exitItem });
mainFrameBarManager1.Bars.Add(fileBar);
mainFrameBarManager1.Categories.Add("Menu");Common Patterns
常见模式
Pattern 1: Creating Multi-Level Menus
模式1：创建多级菜单
Create nested ParentBarItems for submenus (File → Recent → Document1). Group related items under parent containers.
为子菜单创建嵌套的ParentBarItem（例如文件 → 最近打开 → 文档1），将相关项分组到父容器下。
Pattern 2: Adding Interactive Controls
模式2：添加交互控件
Use DropDownBarItem with PopupControlContainer for color pickers, ComboBoxBarItem for selections, TextBoxBarItem for input fields.
将DropDownBarItem与PopupControlContainer搭配使用实现颜色选择器，使用ComboBoxBarItem实现选择功能，使用TextBoxBarItem实现输入字段。
Pattern 3: Implementing Customization
模式3：实现自定义功能
Enable AutoPersistCustomization to allow users to rearrange menu items and save their preferences automatically.
启用AutoPersistCustomization以允许用户重新排列菜单项并自动保存他们的偏好设置。
Pattern 4: MDI Application Integration
模式4：MDI应用程序集成
Use MainFrameBarManager for parent forms and ChildFrameBarManager for child forms. Call RegisterMdiChildTypes() for automatic menu merging.
父窗体使用MainFrameBarManager，子窗体使用ChildFrameBarManager。调用RegisterMdiChildTypes()实现自动菜单合并。
Pattern 5: Keyboard Navigation
模式5：键盘导航
Assign Shortcut properties and use & symbol in Text for mnemonics (e.g., "&Save" creates Alt+S).
设置Shortcut属性，并在文本中使用&符号实现助记键（例如"&Save"会生成Alt+S快捷键）。
Key Properties
关键属性
| Property | Type | Purpose |
|---|---|---|
| Form | Form | Associates the menu manager with the parent form |
| Style | VisualStyle | Sets the visual style (Office2016, XPBlue, etc.) |
| Bars | BarCollection | Collection of Bar instances (menus, toolbars) |
| Items | BarItemCollection | All BarItem instances managed by this manager |
| Categories | StringCollection | Categories for organizing menu items in customization UI |
| AutoLoadToolBarPositions | bool | Auto-loads saved toolbar positions on startup |
| AutoPersistCustomization | bool | Auto-saves menu and toolbar customizations |
| DetachedCommandBars | CommandBarCollection | Collection of detachable CommandBar instances |
| 属性 | 类型 | 用途 |
|---|---|---|
| Form | Form | 将菜单管理器与父窗体关联 |
| Style | VisualStyle | 设置视觉样式（Office2016、XPBlue等） |
| Bars | BarCollection | Bar实例（菜单、工具栏）的集合 |
| Items | BarItemCollection | 该管理器管理的所有BarItem实例 |
| Categories | StringCollection | 用于在自定义UI中组织菜单项的分类 |
| AutoLoadToolBarPositions | bool | 启动时自动加载已保存的工具栏位置 |
| AutoPersistCustomization | bool | 自动保存菜单和工具栏的自定义配置 |
| DetachedCommandBars | CommandBarCollection | 可分离的CommandBar实例集合 |
Documentation & Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- NuGet package setup and assembly references
- Creating MainFrameBarManager instance
- Setting visual styles and form association
- License key configuration
📄 阅读： references/getting-started.md
- NuGet包设置和程序集引用
- 创建MainFrameBarManager实例
- 设置视觉样式和窗体关联
- 许可证密钥配置
Building Menus
构建菜单
📄 Read: references/menu-items-via-code.md
- Creating Bar instances programmatically
- Adding BarItem and ParentBarItem
- Child item hierarchies and sub-menus
- Event handler setup with code examples
📄 Read: references/menu-items-via-designer.md
- Designer-based menu creation (drag-and-drop)
- Customize dialog for bars and items
- Visual arrangement through UI
- Automatic assembly reference injection
📄 阅读： references/menu-items-via-code.md
- 以编程方式创建Bar实例
- 添加BarItem和ParentBarItem
- 子项层级结构和子菜单
- 带有代码示例的事件处理程序设置
📄 阅读： references/menu-items-via-designer.md
- 基于设计器的菜单创建（拖拽方式）
- 工具栏和项的自定义对话框
- 通过UI进行可视化排列
- 自动注入程序集引用
Menu Item Types & Features
菜单项类型与功能
📄 Read: references/menu-item-types.md
- BarItem (basic clickable items)
- ParentBarItem (submenu containers)
- DropDownBarItem (custom popup controls)
- ComboBoxBarItem (dropdown selections)
- StaticBarItem (label-like display items)
- TextBoxBarItem (text input fields)
- ToolBarListBarItem (toolbar customization options)
📄 阅读： references/menu-item-types.md
- BarItem（基础可点击项）
- ParentBarItem（子菜单容器）
- DropDownBarItem（自定义弹出控件）
- ComboBoxBarItem（下拉选择项）
- StaticBarItem（类标签展示项）
- TextBoxBarItem（文本输入字段）
- ToolBarListBarItem（工具栏自定义选项）
Interactive Features
交互功能
📄 Read: references/interactive-features.md
- SuperTooltip setup and appearance customization
- Context menu integration
- Tooltip visibility control
- Advanced tooltip editor configuration
📄 阅读： references/interactive-features.md
- SuperTooltip设置和外观自定义
- 上下文菜单集成
- 工具提示可见性控制
- 高级工具提示编辑器配置
Keyboard & Accessibility
键盘与无障碍支持
📄 Read: references/keyboard-support.md
- Assigning keyboard shortcuts to menu items
- Mnemonic text implementation with & symbol
- ShowMnemonicUnderlinesAlways property
- Keyboard navigation patterns
📄 阅读： references/keyboard-support.md
- 为菜单项分配键盘快捷键
- 使用&符号实现助记键文本
- ShowMnemonicUnderlinesAlways属性
- 键盘导航模式
State Persistence & MDI
状态持久化与MDI
📄 Read: references/state-persistence-mdi.md
- Enabling state persistence with AutoLoadToolBarPositions
- Automatic customization serialization
- MDI parent/child form integration
- ChildFrameBarManager and menu merging
- RegisterMdiChildTypes() for explicit merging
- MDI merge behavior matrix
📄 阅读： references/state-persistence-mdi.md
- 通过AutoLoadToolBarPositions启用状态持久化
- 自定义配置自动序列化
- MDI父/子窗体集成
- ChildFrameBarManager和菜单合并
- 使用RegisterMdiChildTypes()实现显式合并
- MDI合并行为矩阵
Detachable Toolbars
可分离工具栏
📄 Read: references/detachable-command-bars.md
- CommandBar creation and docking
- DockState property configuration
- Adding to DetachedCommandBars collection
- Designer vs. code-based approaches
📄 阅读： references/detachable-command-bars.md
- CommandBar创建和停靠
- DockState属性配置
- 添加到DetachedCommandBars集合
- 设计器 vs 基于代码的实现方式
Common Use Cases
常见用例
File Menu: Create a standard File menu with New, Open, Save, Recent Documents, and Exit items using ParentBarItem hierarchy.
Toolbar: Use multiple Bar instances with different BarNames to create separate toolbars, each docked to different positions.
Search Bar: Add TextBoxBarItem or ComboBoxBarItem to toolbar for search/filter functionality.
Color Picker in Menu: Use DropDownBarItem with PopupControlContainer containing ColorPickerUIAdv control.
Localized Menus: Set Text property to localized strings; mnemonics and shortcuts work across all languages.
Custom Shortcuts: Assign Shortcut.None to items without shortcuts, or use custom key combinations via Shortcut enum.
文件菜单： 使用ParentBarItem层级结构创建标准的文件菜单，包含新建、打开、保存、最近文档和退出项。
工具栏： 使用多个带有不同BarName的Bar实例创建独立的工具栏，每个工具栏停靠在不同位置。
搜索栏： 向工具栏添加TextBoxBarItem或ComboBoxBarItem实现搜索/筛选功能。
菜单中的颜色选择器： 将DropDownBarItem与包含ColorPickerUIAdv控件的PopupControlContainer搭配使用。
本地化菜单： 将Text属性设置为本地化字符串；助记键和快捷键支持所有语言。
自定义快捷键： 为没有快捷键的项分配Shortcut.None，或者通过Shortcut枚举使用自定义按键组合。