syncfusion-winforms-popup-menu
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing PopupMenu in Windows Forms
在Windows Forms中实现PopupMenu
This skill provides comprehensive guidance for implementing the Syncfusion PopupMenu control in Windows Forms applications. PopupMenu represents a context menu that appears on user interaction, supporting multiple BarItem types, multi-level hierarchies, keyboard navigation, and integration with Bar Manager.
本技能为在Windows Forms应用中实现Syncfusion PopupMenu控件提供全面指导。PopupMenu是一种在用户交互时弹出的上下文菜单,支持多种BarItem类型、多级层级结构、键盘导航,以及与Bar Manager的集成。
When to Use This Skill
何时使用本技能
Use this skill when the user:
- Needs to implement context menus or right-click menus in WinForms
- Wants to create popup menus with various item types (buttons, dropdowns, comboboxes, lists)
- Needs multi-level menu structures with nested submenus
- Wants keyboard shortcuts, mnemonics, or touch support for menus
- Needs to group menu items with separators
- Wants checked/unchecked states or disabled items in menus
- Needs to display images and tooltips in menu items
- Wants to integrate popup menus with Bar Manager or CommandBar
- Needs partial menus with frequently used items prioritized
- Is building context-sensitive menu systems for desktop applications
当用户有以下需求时可使用本技能:
- 需要在WinForms中实现上下文菜单或右键菜单
- 想要创建包含多种项类型(按钮、下拉框、组合框、列表)的弹出菜单
- 需要带有嵌套子菜单的多级菜单结构
- 想要为菜单添加键盘快捷键、助记符或触摸支持
- 需要使用分隔符对菜单项进行分组
- 想要在菜单中实现选中/未选中状态或禁用项
- 需要在菜单项中展示图片和提示框
- 想要将弹出菜单与Bar Manager或CommandBar集成
- 需要优先展示常用项的精简菜单
- 正在为桌面应用构建上下文相关的菜单系统
Component Overview
组件概述
PopupMenu is a context menu control that remains hidden by default and displays over any control when triggered (typically by right-click). It supports rich menu structures with seven types of BarItems, multi-level nesting, visual customization, and comprehensive keyboard/touch interaction.
Key Features:
- 7 BarItem Types: BarItem, ParentBarItem, DropDownBarItem, ComboBoxBarItem, ListBarItem, StaticBarItem, TextBoxBarItem
- Multi-Level Menus: Nested submenu structures with unlimited depth
- Grouping: Separators between related menu items
- States: Checked/unchecked, enabled/disabled support
- Visual Customization: Images (normal, disabled, highlighted), tooltips
- Keyboard Support: Shortcuts, mnemonics, keyboard navigation
- Touch Support: Touch-enabled by default for modern devices
- Partial Menus: Prioritize frequently used items, hide others
- Integration: Bar Manager, CommandBar, PopupMenusManager
- Events: BeforePopup, Popup, Collapse, ParentBarItemChanged
Core Components:
- PopupMenu: Main control that hosts the menu structure
- ParentBarItem: Root container that holds all menu items
- PopupMenusManager: Associates popup menus with controls
- BarItems: Individual menu items (7 types available)
PopupMenu 是一种默认隐藏的上下文菜单控件,触发时(通常是右键点击)会展示在任意控件上方。它支持丰富的菜单结构,包含7种BarItem类型、多级嵌套、视觉自定义以及完善的键盘/触摸交互能力。
核心特性:
- 7种BarItem类型: BarItem、ParentBarItem、DropDownBarItem、ComboBoxBarItem、ListBarItem、StaticBarItem、TextBoxBarItem
- 多级菜单: 深度无限制的嵌套子菜单结构
- 分组功能: 相关菜单项之间的分隔符
- 状态支持: 支持选中/未选中、启用/禁用状态
- 视觉自定义: 图片(普通、禁用、高亮状态)、提示框
- 键盘支持: 快捷键、助记符、键盘导航
- 触摸支持: 默认支持触摸,适配现代设备
- 精简菜单: 优先展示常用项,隐藏其他项
- 集成能力: 兼容Bar Manager、CommandBar、PopupMenusManager
- 事件支持: BeforePopup、Popup、Collapse、ParentBarItemChanged
核心组件:
- PopupMenu: 承载菜单结构的主控件
- ParentBarItem: 容纳所有菜单项的根容器
- PopupMenusManager: 用于将弹出菜单与控件关联
- BarItems: 独立菜单项(共7种可用类型)
Documentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- Assembly references and dependencies
- Adding PopupMenu through designer (drag-drop from toolbox)
- Adding PopupMenu through code (initialization and setup)
- PopupMenusManager configuration
- Associating popup menus with controls (RichTextBox, Button, etc.)
- Adding default ParentBarItem
- Creating basic BarItems with text and images
- NuGet package installation
📄 阅读: references/getting-started.md
- 程序集引用与依赖项
- 通过设计器添加PopupMenu(从工具箱拖拽)
- 通过代码添加PopupMenu(初始化与设置)
- PopupMenusManager配置
- 将弹出菜单与控件关联(RichTextBox、Button等)
- 添加默认ParentBarItem
- 创建带文本和图片的基础BarItems
- NuGet包安装
BarItem Types and Configuration
BarItem类型与配置
📄 Read: references/baritem-types.md
- BarItem: Standard menu item with text, image, events
- ParentBarItem: Container for submenu items (hierarchical menus)
- DropDownBarItem: Dropdown with custom PopupControlContainer (ColorPicker, etc.)
- ComboBoxBarItem: Editable combo box in menu
- ListBarItem: List of child items in menu
- StaticBarItem: Label/static text for adjacent items
- TextBoxBarItem: Text input field in menu
- Designer and code examples for each type
- When to use each BarItem type
📄 阅读: references/baritem-types.md
- BarItem: 带文本、图片、事件的标准菜单项
- ParentBarItem: 子菜单项的容器(用于层级菜单)
- DropDownBarItem: 带自定义PopupControlContainer的下拉框(取色器等)
- ComboBoxBarItem: 菜单内的可编辑组合框
- ListBarItem: 菜单内的子项列表
- StaticBarItem: 用于相邻项的标签/静态文本
- TextBoxBarItem: 菜单内的文本输入框
- 每种类型的设计器和代码示例
- 不同BarItem类型的适用场景
Multi-Level Menus and Grouping
多级菜单与分组
📄 Read: references/multilevel-menus.md
- Creating nested menu structures
- Adding ParentBarItem as submenu containers
- Building hierarchical menus (File → New → New Project)
- Unlimited depth menu hierarchies
- Complex menu examples with multiple levels
📄 Read: references/grouping-baritems.md
- Adding separators between menu items
- SeparatorIndices property for grouping
- BeginGroupAt() method for programmatic grouping
- RemoveGroupAt() method to remove separators
- IsGroupBeginning() to check grouping state
- Visual organization patterns
📄 阅读: references/multilevel-menus.md
- 创建嵌套菜单结构
- 添加ParentBarItem作为子菜单容器
- 构建层级菜单(文件 → 新建 → 新建项目)
- 深度无限制的菜单层级
- 多层级的复杂菜单示例
📄 阅读: references/grouping-baritems.md
- 在菜单项之间添加分隔符
- 使用SeparatorIndices属性实现分组
- 使用BeginGroupAt()方法进行程序化分组
- 使用RemoveGroupAt()方法移除分隔符
- 使用IsGroupBeginning()检查分组状态
- 视觉组织模式
Visual Customization
视觉自定义
📄 Read: references/baritem-states.md
- Checked/unchecked states (Checked property)
- Toggle behavior with Click events
- Enabled/disabled states (Enabled property)
- State management patterns
- OverlapCheckBoxImageBounds (checkbox/image overlap control)
- When to use checked states vs other indicators
📄 Read: references/images-and-tooltips.md
- Adding images to BarItems (Image property)
- ImageExt class for image loading
- DisabledImage for disabled state
- HighlightedImage for hover/selection state
- Tooltip configuration (Tooltip property)
- ShowToolTipInPopUp to enable tooltips
- Icon guidelines and best practices
📄 阅读: references/baritem-states.md
- 选中/未选中状态(Checked属性)
- 点击事件的切换行为
- 启用/禁用状态(Enabled属性)
- 状态管理模式
- OverlapCheckBoxImageBounds(复选框/图片重叠控制)
- 选中状态与其他指示器的适用场景
📄 阅读: references/images-and-tooltips.md
- 为BarItems添加图片(Image属性)
- 用于图片加载的ImageExt类
- 禁用状态的DisabledImage
- 悬停/选中状态的HighlightedImage
- 提示框配置(Tooltip属性)
- 使用ShowToolTipInPopUp启用提示框
- 图标规范与最佳实践
Keyboard and Interaction
键盘与交互
📄 Read: references/keyboard-interaction.md
- Touch support (enabled by default)
- Keyboard shortcuts (Shortcut property, e.g., Ctrl+F)
- Custom shortcut text (ShortcutText property)
- Keyboard mnemonics (&Text, e.g., "&File")
- ShowMnemonicUnderlinesAlways for visible mnemonics
- Click event handling for menu item selection
- Triggering actions via keyboard vs mouse
📄 阅读: references/keyboard-interaction.md
- 触摸支持(默认启用)
- 键盘快捷键(Shortcut属性,例如Ctrl+F)
- 自定义快捷键文本(ShortcutText属性)
- 键盘助记符(&文本,例如"&文件")
- 使用ShowMnemonicUnderlinesAlways永久展示助记符下划线
- 菜单项选择的点击事件处理
- 键盘与鼠标触发操作的对比
Advanced Integration
高级集成
📄 Read: references/advanced-features.md
- Partial menus (UsePartialMenus property)
- IsRecentlyUsedItem for usage prioritization
- Bar Manager integration for application-wide menus
- CommandBar association (PopupMenu as dropdown)
- CommandBarController setup
- Events: BeforePopup, Popup, Collapse, ParentBarItemChanged
- Event-driven menu customization
📄 Read: references/troubleshooting.md
- Common setup issues
- Designer vs code differences
- Assembly reference problems
- PopupMenusManager configuration issues
- BarItem visibility problems
- Event handling troubleshooting
📄 阅读: references/advanced-features.md
- 精简菜单(UsePartialMenus属性)
- 用于使用优先级的IsRecentlyUsedItem
- 与Bar Manager集成实现应用全局菜单
- CommandBar关联(将PopupMenu作为下拉框)
- CommandBarController设置
- 事件:BeforePopup、Popup、Collapse、ParentBarItemChanged
- 事件驱动的菜单自定义
📄 阅读: references/troubleshooting.md
- 常见设置问题
- 设计器与代码的差异
- 程序集引用问题
- PopupMenusManager配置问题
- BarItem可见性问题
- 事件处理故障排查
Quick Start Example
快速入门示例
Basic PopupMenu with BarItems
带BarItems的基础PopupMenu
csharp
using Syncfusion.Windows.Forms.Tools.XPMenus;
using System.Windows.Forms;
public partial class Form1 : Form
{
private PopupMenu popupMenu1;
private ParentBarItem parentBarItem1;
private BarItem barItem1;
private BarItem barItem2;
private BarItem barItem3;
private PopupMenusManager popupMenusManager1;
private RichTextBox richTextBox1;
public Form1()
{
InitializeComponent();
// Initialize components
this.popupMenu1 = new PopupMenu(this.components);
this.parentBarItem1 = new ParentBarItem();
this.barItem1 = new BarItem();
this.barItem2 = new BarItem();
this.barItem3 = new BarItem();
this.richTextBox1 = new RichTextBox();
this.popupMenusManager1 = new PopupMenusManager(this.components);
// Configure popup menu
this.popupMenu1.ParentBarItem = this.parentBarItem1;
// Configure BarItems
this.barItem1.Text = "Cut";
this.barItem1.Shortcut = Shortcut.CtrlX;
this.barItem1.Click += BarItem1_Click;
this.barItem2.Text = "Copy";
this.barItem2.Shortcut = Shortcut.CtrlC;
this.barItem2.Click += BarItem2_Click;
this.barItem3.Text = "Paste";
this.barItem3.Shortcut = Shortcut.CtrlV;
this.barItem3.Click += BarItem3_Click;
// Add items to parent
this.parentBarItem1.Items.AddRange(new BarItem[] {
this.barItem1, this.barItem2, this.barItem3
});
this.parentBarItem1.SizeToFit = true;
// Associate with control
this.richTextBox1.Size = new System.Drawing.Size(300, 200);
this.popupMenusManager1.SetXPContextMenu(this.richTextBox1, this.popupMenu1);
// Add to form
this.Controls.Add(this.richTextBox1);
}
private void BarItem1_Click(object sender, EventArgs e)
{
if (richTextBox1.SelectionLength > 0)
{
richTextBox1.Cut();
}
}
private void BarItem2_Click(object sender, EventArgs e)
{
if (richTextBox1.SelectionLength > 0)
{
richTextBox1.Copy();
}
}
private void BarItem3_Click(object sender, EventArgs e)
{
richTextBox1.Paste();
}
}csharp
using Syncfusion.Windows.Forms.Tools.XPMenus;
using System.Windows.Forms;
public partial class Form1 : Form
{
private PopupMenu popupMenu1;
private ParentBarItem parentBarItem1;
private BarItem barItem1;
private BarItem barItem2;
private BarItem barItem3;
private PopupMenusManager popupMenusManager1;
private RichTextBox richTextBox1;
public Form1()
{
InitializeComponent();
// 初始化组件
this.popupMenu1 = new PopupMenu(this.components);
this.parentBarItem1 = new ParentBarItem();
this.barItem1 = new BarItem();
this.barItem2 = new BarItem();
this.barItem3 = new BarItem();
this.richTextBox1 = new RichTextBox();
this.popupMenusManager1 = new PopupMenusManager(this.components);
// 配置弹出菜单
this.popupMenu1.ParentBarItem = this.parentBarItem1;
// 配置BarItems
this.barItem1.Text = "Cut";
this.barItem1.Shortcut = Shortcut.CtrlX;
this.barItem1.Click += BarItem1_Click;
this.barItem2.Text = "Copy";
this.barItem2.Shortcut = Shortcut.CtrlC;
this.barItem2.Click += BarItem2_Click;
this.barItem3.Text = "Paste";
this.barItem3.Shortcut = Shortcut.CtrlV;
this.barItem3.Click += BarItem3_Click;
// 向父容器添加项
this.parentBarItem1.Items.AddRange(new BarItem[] {
this.barItem1, this.barItem2, this.barItem3
});
this.parentBarItem1.SizeToFit = true;
// 与控件关联
this.richTextBox1.Size = new System.Drawing.Size(300, 200);
this.popupMenusManager1.SetXPContextMenu(this.richTextBox1, this.popupMenu1);
// 添加到窗体
this.Controls.Add(this.richTextBox1);
}
private void BarItem1_Click(object sender, EventArgs e)
{
if (richTextBox1.SelectionLength > 0)
{
richTextBox1.Cut();
}
}
private void BarItem2_Click(object sender, EventArgs e)
{
if (richTextBox1.SelectionLength > 0)
{
richTextBox1.Copy();
}
}
private void BarItem3_Click(object sender, EventArgs e)
{
richTextBox1.Paste();
}
}Common Patterns
常用模式
Pattern 1: Multi-Level Menu Structure
模式1:多级菜单结构
csharp
// Create hierarchy: File → New → New Project, New Website
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "File";
ParentBarItem newSubmenu = new ParentBarItem();
newSubmenu.Text = "New";
BarItem newProject = new BarItem();
newProject.Text = "New Project...";
newProject.Click += NewProject_Click;
BarItem newWebsite = new BarItem();
newWebsite.Text = "New Website...";
newWebsite.Click += NewWebsite_Click;
// Build hierarchy
newSubmenu.Items.AddRange(new BarItem[] { newProject, newWebsite });
fileMenu.Items.Add(newSubmenu);
parentBarItem1.Items.Add(fileMenu);csharp
// 创建层级:文件 → 新建 → 新建项目、新建网站
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "File";
ParentBarItem newSubmenu = new ParentBarItem();
newSubmenu.Text = "New";
BarItem newProject = new BarItem();
newProject.Text = "New Project...";
newProject.Click += NewProject_Click;
BarItem newWebsite = new BarItem();
newWebsite.Text = "New Website...";
newWebsite.Click += NewWebsite_Click;
// 构建层级
newSubmenu.Items.AddRange(new BarItem[] { newProject, newWebsite });
fileMenu.Items.Add(newSubmenu);
parentBarItem1.Items.Add(fileMenu);Pattern 2: Grouping with Separators
模式2:使用分隔符分组
csharp
// Create menu items
BarItem cut = new BarItem { Text = "Cut" };
BarItem copy = new BarItem { Text = "Copy" };
BarItem paste = new BarItem { Text = "Paste" };
BarItem selectAll = new BarItem { Text = "Select All" };
// Add items
parentBarItem1.Items.AddRange(new BarItem[] { cut, copy, paste, selectAll });
// Add separator after index 2 (after Paste)
parentBarItem1.SeparatorIndices.Add(2);
// Alternative: Use method
parentBarItem1.BeginGroupAt(selectAll);csharp
// 创建菜单项
BarItem cut = new BarItem { Text = "Cut" };
BarItem copy = new BarItem { Text = "Copy" };
BarItem paste = new BarItem { Text = "Paste" };
BarItem selectAll = new BarItem { Text = "Select All" };
// 添加项
parentBarItem1.Items.AddRange(new BarItem[] { cut, copy, paste, selectAll });
// 在索引2之后(粘贴之后)添加分隔符
parentBarItem1.SeparatorIndices.Add(2);
// 替代方案:使用方法
parentBarItem1.BeginGroupAt(selectAll);Pattern 3: Checked Menu Items
模式3:选中状态菜单项
csharp
BarItem wordWrap = new BarItem();
wordWrap.Text = "Word Wrap";
wordWrap.Checked = true; // Initial state
wordWrap.Click += (s, e) =>
{
wordWrap.Checked = !wordWrap.Checked; // Toggle
richTextBox1.WordWrap = wordWrap.Checked; // Apply setting
};csharp
BarItem wordWrap = new BarItem();
wordWrap.Text = "Word Wrap";
wordWrap.Checked = true; // 初始状态
wordWrap.Click += (s, e) =>
{
wordWrap.Checked = !wordWrap.Checked; // 切换状态
richTextBox1.WordWrap = wordWrap.Checked; // 应用设置
};Pattern 4: Menu Items with Images
模式4:带图片的菜单项
csharp
BarItem saveItem = new BarItem();
saveItem.Text = "Save";
saveItem.Image = new ImageExt(Image.FromFile(@"icons\save.png"));
saveItem.DisabledImage = new ImageExt(Image.FromFile(@"icons\save_disabled.png"));
saveItem.HighlightedImage = new ImageExt(Image.FromFile(@"icons\save_highlight.png"));
saveItem.Shortcut = Shortcut.CtrlS;
saveItem.Tooltip = "Save the current document";
saveItem.ShowToolTipInPopUp = true;csharp
BarItem saveItem = new BarItem();
saveItem.Text = "Save";
saveItem.Image = new ImageExt(Image.FromFile(@"icons\save.png"));
saveItem.DisabledImage = new ImageExt(Image.FromFile(@"icons\save_disabled.png"));
saveItem.HighlightedImage = new ImageExt(Image.FromFile(@"icons\save_highlight.png"));
saveItem.Shortcut = Shortcut.CtrlS;
saveItem.Tooltip = "Save the current document";
saveItem.ShowToolTipInPopUp = true;Pattern 5: Partial Menus (Frequently Used Items)
模式5:精简菜单(常用项优先)
csharp
// Enable partial menus
parentBarItem1.UsePartialMenus = true;
// Mark items as frequently used (visible by default)
cutItem.IsRecentlyUsedItem = true;
copyItem.IsRecentlyUsedItem = true;
pasteItem.IsRecentlyUsedItem = true;
// Mark items as less frequently used (hidden initially)
advancedItem.IsRecentlyUsedItem = false;
optionsItem.IsRecentlyUsedItem = false;csharp
// 启用精简菜单
parentBarItem1.UsePartialMenus = true;
// 标记为常用项(默认可见)
cutItem.IsRecentlyUsedItem = true;
copyItem.IsRecentlyUsedItem = true;
pasteItem.IsRecentlyUsedItem = true;
// 标记为非常用项(默认隐藏)
advancedItem.IsRecentlyUsedItem = false;
optionsItem.IsRecentlyUsedItem = false;Key Properties and Events
核心属性与事件
PopupMenu Properties
PopupMenu属性
- ParentBarItem: Root container holding all menu items (required)
- ParentBarItem: 容纳所有菜单项的根容器(必填)
ParentBarItem Properties
ParentBarItem属性
- Items: Collection of BarItems in the menu
- SizeToFit: Auto-size menu items to fit content
- SeparatorIndices: Collection of indices where separators appear
- UsePartialMenus: Enable prioritized menu display
- OverlapCheckBoxImageBounds: Control checkbox/image overlap behavior
- Items: 菜单中BarItems的集合
- SizeToFit: 自动调整菜单项尺寸适配内容
- SeparatorIndices: 分隔符所在的索引集合
- UsePartialMenus: 启用优先展示的菜单显示模式
- OverlapCheckBoxImageBounds: 控制复选框/图片重叠行为
BarItem Properties
BarItem属性
- Text: Display text for the menu item
- Image: Icon displayed with the item
- DisabledImage: Icon when item is disabled
- HighlightedImage: Icon when item is highlighted/hovered
- Tooltip: Tooltip text displayed on hover
- ShowToolTipInPopUp: Enable tooltip display
- Shortcut: Keyboard shortcut (Ctrl+C, Alt+F, etc.)
- ShortcutText: Custom text for shortcut display
- Checked: Show checkmark before text
- Enabled: Enable/disable the menu item
- IsRecentlyUsedItem: Mark as frequently used (for partial menus)
- ShowMnemonicUnderlinesAlways: Always show mnemonic underlines
- SizeToFit: Auto-size item to fit content
- Text: 菜单项展示的文本
- Image: 项旁展示的图标
- DisabledImage: 项禁用时的图标
- HighlightedImage: 项高亮/悬停时的图标
- Tooltip: 悬停时展示的提示文本
- ShowToolTipInPopUp: 启用提示框展示
- Shortcut: 键盘快捷键(Ctrl+C、Alt+F等)
- ShortcutText: 快捷键展示的自定义文本
- Checked: 在文本前展示勾选标记
- Enabled: 启用/禁用菜单项
- IsRecentlyUsedItem: 标记为常用项(用于精简菜单)
- ShowMnemonicUnderlinesAlways: 永久展示助记符下划线
- SizeToFit: 自动调整项尺寸适配内容
PopupMenusManager Methods
PopupMenusManager方法
- SetXPContextMenu(Control, PopupMenu): Associate popup menu with a control
- SetXPContextMenu(Control, PopupMenu): 将弹出菜单与控件关联
ParentBarItem Methods
ParentBarItem方法
- BeginGroupAt(BarItem): Add separator before specified item
- RemoveGroupAt(BarItem): Remove separator before specified item
- IsGroupBeginning(BarItem): Check if item starts a group
- BeginGroupAt(BarItem): 在指定项前添加分隔符
- RemoveGroupAt(BarItem): 移除指定项前的分隔符
- IsGroupBeginning(BarItem): 检查项是否为分组起始项
Events
事件
- BeforePopup: Fired before menu is displayed (get mouse position, customize menu)
- Popup: Fired after menu is displayed
- Collapse: Fired when menu is closed
- ParentBarItemChanged: Fired when ParentBarItem properties change
- Click (BarItem): Fired when menu item is clicked
- BeforePopup: 菜单展示前触发(获取鼠标位置、自定义菜单)
- Popup: 菜单展示后触发
- Collapse: 菜单关闭时触发
- ParentBarItemChanged: ParentBarItem属性变更时触发
- Click (BarItem): 菜单项被点击时触发
Common Use Cases
常见使用场景
Use Case 1: Text Editor Context Menu
场景1:文本编辑器上下文菜单
Create a context menu for RichTextBox with Cut, Copy, Paste, Select All, and formatting options.
为RichTextBox创建包含剪切、复制、粘贴、全选和格式化选项的上下文菜单。
Use Case 2: Grid/DataGridView Context Menu
场景2:表格/DataGridView上下文菜单
Add context menu to grid with options like Add Row, Delete Row, Edit Cell, Export Data, etc.
为表格添加上下文菜单,包含添加行、删除行、编辑单元格、导出数据等选项。
Use Case 3: File/Folder Context Menu
场景3:文件/文件夹上下文菜单
Implement Windows Explorer-style context menu with Open, Copy, Delete, Properties, and nested submenus.
实现类似Windows资源管理器的上下文菜单,包含打开、复制、删除、属性和嵌套子菜单。
Use Case 4: Form Control Context Menu
场景4:窗体控件上下文菜单
Add context menu to buttons, labels, or panels with control-specific actions.
为按钮、标签或面板添加上下文菜单,提供控件专属操作。
Use Case 5: Application-Wide Menu System
场景5:应用全局菜单系统
Integrate PopupMenu with Bar Manager for consistent menu experience across the application.
将PopupMenu与Bar Manager集成,为整个应用提供一致的菜单体验。
Use Case 6: Dynamic Context Menus
场景6:动态上下文菜单
Use BeforePopup event to customize menu items based on application state (enable/disable items, show/hide options).
使用BeforePopup事件根据应用状态自定义菜单项(启用/禁用项、显示/隐藏选项)。
Use Case 7: Touch-Enabled Menus
场景7:触摸适配菜单
Leverage built-in touch support for tablet and touch-screen applications.
利用内置触摸支持,为平板和触摸屏应用提供适配菜单。
Tips and Best Practices
提示与最佳实践
BarItem Type Selection:
- Use BarItem for standard menu commands
- Use ParentBarItem for submenus
- Use DropDownBarItem when you need custom controls (ColorPicker, custom panels)
- Use ComboBoxBarItem for selection with editing capability
- Use ListBarItem for fixed selection lists
- Use StaticBarItem for labels/headings
- Use TextBoxBarItem for text input in menus
Performance:
- Reuse PopupMenu instances across multiple controls when possible
- Use BeforePopup event for dynamic customization instead of recreating menus
- Avoid loading large images for menu items; use 16x16 or 24x24 icons
Accessibility:
- Always provide keyboard shortcuts for frequently used commands
- Use mnemonics (&Text) for keyboard navigation
- Set descriptive tooltip text for icon-only items
- Ensure disabled items are visually distinct
Designer vs Code:
- Designer is faster for static menu structures
- Code provides better control for dynamic menus
- Use Smart Tags in designer for quick setup
- Test both designer and code paths to ensure consistency
For detailed implementation guidance, navigate to the reference files listed in the Documentation and Navigation Guide section.
BarItem类型选择:
- 标准菜单命令使用 BarItem
- 子菜单使用 ParentBarItem
- 需要自定义控件(取色器、自定义面板)时使用 DropDownBarItem
- 可编辑选择项使用 ComboBoxBarItem
- 固定选择列表使用 ListBarItem
- 标签/标题使用 StaticBarItem
- 菜单内文本输入使用 TextBoxBarItem
性能优化:
- 尽可能在多个控件之间复用PopupMenu实例
- 使用BeforePopup事件进行动态自定义,而非重复创建菜单
- 避免为菜单项加载大图片,使用16x16或24x24尺寸的图标
无障碍适配:
- 为常用命令始终提供键盘快捷键
- 使用助记符(&文本)支持键盘导航
- 为仅图标项设置描述性的提示文本
- 确保禁用项有明显的视觉区分
设计器与代码选择:
- 静态菜单结构使用设计器开发效率更高
- 动态菜单使用代码实现可控性更好
- 使用设计器中的智能标签快速完成设置
- 同时测试设计器和代码路径确保一致性
如需详细的实现指导,请导航到「文档与导航指南」部分列出的参考文件。