syncfusion-winforms-popup-menu

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing 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尺寸的图标
无障碍适配:
  • 为常用命令始终提供键盘快捷键
  • 使用助记符(&文本)支持键盘导航
  • 为仅图标项设置描述性的提示文本
  • 确保禁用项有明显的视觉区分
设计器与代码选择:
  • 静态菜单结构使用设计器开发效率更高
  • 动态菜单使用代码实现可控性更好
  • 使用设计器中的智能标签快速完成设置
  • 同时测试设计器和代码路径确保一致性

如需详细的实现指导,请导航到「文档与导航指南」部分列出的参考文件。