syncfusion-winforms-contextmenustrip（同步融合 winforms contextmenustrip）

Implementing ContextMenuStripEx

Guide for implementing enhanced context menus with rich item types, multi-level navigation, and extensive customization options in Windows Forms applications.

When to Use This Skill

Use this skill when you need to:

• Add context menus (right-click menus) to Windows Forms controls
• Implement multi-level menu hierarchies with submenus
• Create menus with mixed item types (MenuItem, TextBox, ComboBox, Separator)
• Configure checked/unchecked states for menu items
• Add keyboard shortcuts to menu items
• Customize menu appearance (colors, fonts, sizing)
• Handle menu item click events and triggers
• Enable/disable menu items dynamically
• Implement auto-close behavior for menus
• Support touch mode in menu interfaces

Component Overview

ContextMenuStripEx is an enhanced version of the standard Windows Forms ContextMenuStrip that provides:

• Support for multiple ToolStripItem types in one menu
• Rich customization options for appearance
• Multi-level menu hierarchies
• Keyboard shortcut display and handling
• Touch mode support
• Flexible item state management (checked, disabled, etc.)

Key Features:

• Mixed item types: MenuItem, TextBox, ComboBox, Separator
• Multi-level submenu support via DropDownItems
• Checked/unchecked/indeterminate states
• Enable/disable items dynamically
• Auto-close configuration
• Extensive appearance customization
• Keyboard shortcut support
• Tooltip support for menu items
• Touch-friendly sizing

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and required assemblies
• Adding ContextMenuStripEx via designer
• Adding ContextMenuStripEx via code
• Associating context menu with controls
• Basic menu item creation
• Initial configuration

ToolStripItem Types

📄 Read: references/toolstrip-item-types.md

• MenuItem properties and configuration
• TextBox items in context menus
• ComboBox items in context menus
• Separator for visual grouping
• Adding each item type via designer and code
• Item-specific properties and behaviors

Menu Item States

📄 Read: references/menu-item-states.md

• Checked and unchecked states
• CheckedState property (Checked, Unchecked, Indeterminate)
• Enabling and disabling menu items
• Dynamic state management
• Visual indicators for states

Multi-level Menus

📄 Read: references/multilevel-menus.md

• Creating submenu hierarchies
• Using DropDownItems property
• Nested menu structures
• Multi-level navigation patterns
• Deep menu hierarchies

Menu Behavior

📄 Read: references/menu-behavior.md

• Auto-close functionality
• Click event handling
• Trigger mechanisms
• Opening and closing behavior
• Runtime behavior control
• Event lifecycle

Keyboard Shortcuts and Touch Support

📄 Read: references/keyboard-and-touch.md

• Keyboard shortcuts configuration
• ShowShortcutKeys property
• ShortcutKeys assignment
• ShortcutKeyDisplayString customization
• Touch mode support
• Accessibility features

Appearance Customization

📄 Read: references/appearance-customization.md

• Background and foreground colors
• Font customization
• Size and AutoSize configuration
• Margins and shadows
• Tooltip configuration
• Render modes
• Visual styling options

Quick Start Example

Basic Context Menu Implementation

Via Designer:

1. Drag ContextMenuStripEx from toolbox to form
   (appears in component tray)
2. Click "Type Here" to add menu items
3. Select item type (MenuItem, TextBox, ComboBox, Separator)
4. Configure item properties in Properties panel
5. Right-click target control → Properties → ContextMenuStrip
6. Select the ContextMenuStripEx instance

Via Code:

using Syncfusion.Windows.Forms.Tools;
using System.Windows.Forms;

// Declarations
private ContextMenuStripEx contextMenuStripEx;
private ToolStripMenuItem menuItemCut;
private ToolStripMenuItem menuItemCopy;
private ToolStripMenuItem menuItemPaste;
private RichTextBox richTextBox1;

// Initialization
private void InitializeContextMenu()
{
    // Create context menu
    this.contextMenuStripEx = new ContextMenuStripEx();

    // Create menu items
    this.menuItemCut = new ToolStripMenuItem();
    this.menuItemCopy = new ToolStripMenuItem();
    this.menuItemPaste = new ToolStripMenuItem();

    // Configure menu items
    this.menuItemCut.Text = "Cut";
    this.menuItemCut.ShortcutKeys = Keys.Control | Keys.X;
    this.menuItemCut.Click += MenuItemCut_Click;

    this.menuItemCopy.Text = "Copy";
    this.menuItemCopy.ShortcutKeys = Keys.Control | Keys.C;
    this.menuItemCopy.Click += MenuItemCopy_Click;

    this.menuItemPaste.Text = "Paste";
    this.menuItemPaste.ShortcutKeys = Keys.Control | Keys.V;
    this.menuItemPaste.Click += MenuItemPaste_Click;

    // Add items to context menu
    this.contextMenuStripEx.Items.AddRange(new ToolStripItem[] {
        this.menuItemCut,
        this.menuItemCopy,
        this.menuItemPaste
    });

    // Associate with control
    this.richTextBox1 = new RichTextBox();
    this.richTextBox1.ContextMenuStrip = this.contextMenuStripEx;
    this.Controls.Add(this.richTextBox1);
}

// Event handlers
private void MenuItemCut_Click(object sender, EventArgs e)
{
    richTextBox1.Cut();
}

private void MenuItemCopy_Click(object sender, EventArgs e)
{
    richTextBox1.Copy();
}

private void MenuItemPaste_Click(object sender, EventArgs e)
{
    richTextBox1.Paste();
}

Common Patterns

Pattern 1: Editing Context Menu (Cut/Copy/Paste)

private void CreateEditContextMenu()
{
    var contextMenu = new ContextMenuStripEx();

    var cutItem = new ToolStripMenuItem("Cut", null, (s, e) => textBox.Cut());
    cutItem.ShortcutKeys = Keys.Control | Keys.X;

    var copyItem = new ToolStripMenuItem("Copy", null, (s, e) => textBox.Copy());
    copyItem.ShortcutKeys = Keys.Control | Keys.C;

    var pasteItem = new ToolStripMenuItem("Paste", null, (s, e) => textBox.Paste());
    pasteItem.ShortcutKeys = Keys.Control | Keys.V;

    contextMenu.Items.AddRange(new ToolStripItem[] {
        cutItem, copyItem, pasteItem
    });

    textBox.ContextMenuStrip = contextMenu;
}

Pattern 2: Multi-level Menu with Submenus

private void CreateMultiLevelMenu()
{
    var contextMenu = new ContextMenuStripEx();

    // Parent menu item with submenus
    var newMenuItem = new ToolStripMenuItem("New");

    // Submenu items
    var newDocItem = new ToolStripMenuItem("New Document");
    var newProjectItem = new ToolStripMenuItem("New Project");
    var newFileItem = new ToolStripMenuItem("New File");

    // Add submenus to parent
    newMenuItem.DropDownItems.AddRange(new ToolStripItem[] {
        newDocItem, newProjectItem, newFileItem
    });

    // Add to context menu
    contextMenu.Items.Add(newMenuItem);

    control.ContextMenuStrip = contextMenu;
}

Pattern 3: Dynamic Menu with Checked States

private void CreateDynamicCheckedMenu()
{
    var contextMenu = new ContextMenuStripEx();

    var boldItem = new ToolStripMenuItem("Bold");
    boldItem.CheckOnClick = true;
    boldItem.Checked = false;
    boldItem.Click += (s, e) => {
        var item = s as ToolStripMenuItem;
        // Apply bold formatting based on checked state
        ApplyBoldFormatting(item.Checked);
    };

    var italicItem = new ToolStripMenuItem("Italic");
    italicItem.CheckOnClick = true;
    italicItem.Checked = false;

    var underlineItem = new ToolStripMenuItem("Underline");
    underlineItem.CheckOnClick = true;
    underlineItem.Checked = false;

    contextMenu.Items.AddRange(new ToolStripItem[] {
        boldItem, italicItem, underlineItem
    });

    richTextBox.ContextMenuStrip = contextMenu;
}

Pattern 4: Mixed Item Types Menu

private void CreateMixedItemMenu()
{
    var contextMenu = new ContextMenuStripEx();

    // Menu item
    var searchItem = new ToolStripMenuItem("Search");

    // TextBox for input
    var searchBox = new ToolStripTextBox();
    searchBox.Text = "Enter search term...";

    // Separator
    var separator = new ToolStripSeparator();

    // ComboBox for options
    var filterCombo = new ToolStripComboBox();
    filterCombo.Items.AddRange(new object[] { "All", "Documents", "Images" });
    filterCombo.SelectedIndex = 0;

    // Add all items
    contextMenu.Items.AddRange(new ToolStripItem[] {
        searchItem, searchBox, separator, filterCombo
    });

    control.ContextMenuStrip = contextMenu;
}

Pattern 5: Dynamically Enable/Disable Items

private void UpdateMenuItemStates()
{
    // Enable/disable based on application state
    menuItemCut.Enabled = textBox.SelectionLength > 0;
    menuItemCopy.Enabled = textBox.SelectionLength > 0;
    menuItemPaste.Enabled = Clipboard.ContainsText();
}

private void ContextMenu_Opening(object sender, CancelEventArgs e)
{
    // Update states before menu opens
    UpdateMenuItemStates();
}

// Subscribe to Opening event
contextMenuStripEx.Opening += ContextMenu_Opening;

Key Properties

ContextMenuStripEx Properties

• Items: Collection of ToolStripItems in the menu
• AutoClose: Whether menu closes on user actions
• BackColor: Background color of the menu
• Font: Font applied to all menu items
• Size: Height and width of the menu
• RenderMode: Painting style (Professional, System, Custom)

ToolStripMenuItem Properties

• Text: Display text for the menu item
• Checked: Whether check mark appears
• CheckedState: State (Checked, Unchecked, Indeterminate)
• Enabled: Whether item is enabled
• ShortcutKeys: Keyboard shortcut
• ShowShortcutKeys: Display shortcut in menu
• DropDownItems: Submenu items collection
• ToolTipText: Tooltip when hovering

Event Properties

• Click: Fires when menu item is clicked
• CheckedChanged: Fires when checked state changes
• Opening: Fires before context menu opens
• Closed: Fires when context menu closes

Common Use Cases

Use Case 1: Text Editor Context Menu

Implement standard editing operations (cut, copy, paste, select all) with keyboard shortcuts displayed.

Reference: getting-started.md, keyboard-and-touch.md

Use Case 2: Application Options Menu

Create a menu with checkable items for toggling features (show toolbar, show status bar, word wrap).

Reference: menu-item-states.md, menu-behavior.md

Use Case 3: File Operations Menu

Build a hierarchical menu for file operations (New → Document/Project/File, Open, Save, Close).

Reference: multilevel-menus.md, toolstrip-item-types.md

Use Case 4: Search and Filter Menu

Combine TextBox for input and ComboBox for filter selection within the context menu.

Reference: toolstrip-item-types.md, appearance-customization.md

Use Case 5: Context-Aware Menu

Enable/disable menu items based on current selection or application state.

Reference: menu-item-states.md, menu-behavior.md

Implementation Workflow

1. Plan Menu Structure: Identify menu items, hierarchy, and item types needed
2. Add ContextMenuStripEx: Via designer or code
3. Create Menu Items: Add ToolStripMenuItems, TextBoxes, ComboBoxes, Separators
4. Configure Properties: Set text, shortcuts, states, appearance
5. Build Hierarchy: Add submenus using DropDownItems if needed
6. Wire Events: Subscribe to Click events for each actionable item
7. Associate with Control: Set control's ContextMenuStrip property
8. Test Interaction: Right-click to verify menu appears and functions
9. Customize Appearance: Apply colors, fonts, sizing as needed
10. Handle Dynamic States: Update enabled/checked states based on context

Troubleshooting

Menu Not Appearing:

• Verify ContextMenuStrip property is set on target control
• Check that menu has at least one item
• Ensure control allows right-click events

Shortcuts Not Working:

• Set ShowShortcutKeys = true to display shortcuts
• Verify ShortcutKeys property is configured correctly
• Check for keyboard shortcut conflicts with other controls

Items Not Enabled:

• Check Enabled property of menu items
• Verify event handlers are updating states correctly
• Use Opening event to update states before menu displays

Submenus Not Showing:

• Ensure parent item has DropDownItems populated
• Verify submenu items are properly initialized
• Check that parent item is not disabled

For detailed information on specific features, navigate to the appropriate reference file listed in the Documentation and Navigation Guide section.