syncfusion-winforms-popup-menu（同步融合 winforms 弹出菜单）

Implementing PopupMenu in Windows Forms

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.

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

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)

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

BarItem Types and Configuration

📄 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

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

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

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

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

Quick Start Example

Basic PopupMenu with BarItems

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();
    }
}

Common Patterns

Pattern 1: Multi-Level Menu Structure

// 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);

Pattern 2: Grouping with Separators

// 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);

Pattern 3: Checked Menu Items

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
};

Pattern 4: Menu Items with Images

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)

// 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;

Key Properties and Events

PopupMenu Properties

• ParentBarItem: Root container holding all menu items (required)

ParentBarItem Properties

• 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

BarItem Properties

• 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

PopupMenusManager Methods

• SetXPContextMenu(Control, PopupMenu): Associate popup menu with a control

ParentBarItem Methods

• BeginGroupAt(BarItem): Add separator before specified item
• RemoveGroupAt(BarItem): Remove separator before specified item
• IsGroupBeginning(BarItem): Check if item starts a group

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

Common Use Cases

Use Case 1: Text Editor Context Menu

Create a context menu for RichTextBox with Cut, Copy, Paste, Select All, and formatting options.

Use Case 2: Grid/DataGridView Context Menu

Add context menu to grid with options like Add Row, Delete Row, Edit Cell, Export Data, etc.

Use Case 3: File/Folder Context Menu

Implement Windows Explorer-style context menu with Open, Copy, Delete, Properties, and nested submenus.

Use Case 4: Form Control Context Menu

Add context menu to buttons, labels, or panels with control-specific actions.

Use Case 5: Application-Wide Menu System

Integrate PopupMenu with Bar Manager for consistent menu experience across the application.

Use Case 6: Dynamic Context Menus

Use BeforePopup event to customize menu items based on application state (enable/disable items, show/hide options).

Use Case 7: Touch-Enabled Menus

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.*