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

Assembly Dependencies

Required assemblies:

• Syncfusion.Shared.Base
• Syncfusion.Shared.Windows
• Syncfusion.Tools.Base
• Syncfusion.Tools.Windows

NuGet Package: Install-Package Syncfusion.Tools.Windows

Implementing Split Buttons

When to Use This Skill

Use this skill when users need to implement Syncfusion SplitButton control in WinForms applications. This control is ideal for:

• Button-Dropdown Hybrid: Creating controls that combine a primary button action with a dropdown menu of related options
• Command Variations: Providing a default action with alternative variations (e.g., Save with Save As, Send options)
• Toggle with Options: Implementing toggle buttons that also provide dropdown menu choices
• Dynamic Button Text: Updating button caption based on user selection from dropdown items
• Office-Style UI: Building interfaces that match Microsoft Office split button patterns
• Custom Rendered Buttons: Creating fully customized button appearances using ISplitButtonRenderer

The SplitButton control provides two button modes (Normal and Toggle), dynamic caption management, built-in Office2016 themes, and extensive customization through custom renderers.

Component Overview

The SplitButton control is a hybrid control that behaves like a button with an integrated dropdown menu. When clicked on the button portion, it executes a primary action. When clicked on the dropdown arrow, it displays a menu of additional options. This pattern is commonly seen in applications like Microsoft Word (Save/Save As) or Outlook (Reply/Reply All).

Key Capabilities:

• Two button modes: Normal (standard click) and Toggle (checked/unchecked state)
• DropDown items management (Add/Remove items dynamically)
• Static or dynamic button captions (set text or use selected dropdown item as caption)
• Six built-in visual styles: Office2016White, Office2016Black, Office2016DarkGray, Office2016Colorful, Metro, Default
• ISplitButtonRenderer interface for complete button customization
• ToolStripProfessionalRenderer for dropdown items appearance customization
• DropDownItemClicked event for handling item selection

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Read this first for basic setup and implementation:

• Assembly references and NuGet package installation
• Adding SplitButton through Designer (drag and drop from toolbox)
• Adding SplitButton through Code (programmatic creation)
• Adding and removing dropdown items using DropDownItems collection
• Basic configuration and minimal working examples

Button Modes and States

📄 Read: references/button-modes.md

Use when users need different button behaviors:

• Normal mode for standard button click actions
• Toggle mode for checked/unchecked state buttons
• ButtonMode property configuration (Normal vs Toggle)
• IsButtonChecked property for controlling toggle state
• Mode-specific click events and state management

Button Caption Management

📄 Read: references/button-caption.md

Use when users need to:

• Set static button text using Text property
• Update button caption dynamically from dropdown item selection
• Handle DropDownItemClicked event to update caption
• Display selected item text as button label

Visual Styles and Theming

📄 Read: references/visual-styles.md

Use when users want to:

• Apply built-in Office2016 themes (White, Black, DarkGray, Colorful)
• Use Metro or Default visual styles
• Match button appearance to application theme
• Set Style or ThemeName properties

Advanced Customization

📄 Read: references/advanced-customization.md

Use when users require:

• Custom button rendering using ISplitButtonRenderer interface
• Custom border, text, or arrow drawing (DrawBorder, DrawText, DrawArrow methods)
• Dropdown items appearance customization using DropDownRenderer
• Custom ToolStripProfessionalRenderer implementation
• Override methods: OnRenderItemText, OnRenderImageMargin, OnRenderItemImage, OnRenderToolStripBackground, OnRenderToolStripBorder

Quick Start Example

Here's a minimal example showing how to create a SplitButton with dropdown items:

Designer Approach:

1. Drag SplitButton from toolbox to form
2. Set Text property to "Actions"
3. Use DropDownItems property editor to add items
4. Set Style property to "Office2016Colorful"

Code Approach (C#):

using Syncfusion.Windows.Forms.Tools;

// Create SplitButton
SplitButton splitButton = new SplitButton();
splitButton.Text = "Save";
splitButton.Size = new Size(120, 40);
splitButton.Location = new Point(20, 20);
splitButton.Style = SplitButtonVisualStyle.Office2016Colorful;

// Add dropdown items
ToolStripMenuItem saveItem = new ToolStripMenuItem("Save");
ToolStripMenuItem saveAsItem = new ToolStripMenuItem("Save As...");
ToolStripMenuItem saveAllItem = new ToolStripMenuItem("Save All");

splitButton.DropDownItems.Add(saveItem);
splitButton.DropDownItems.Add(saveAsItem);
splitButton.DropDownItems.Add(saveAllItem);

// Add to form
this.Controls.Add(splitButton);

Code Approach (VB.NET):

Imports Syncfusion.Windows.Forms.Tools

' Create SplitButton
Dim splitButton As New SplitButton()
splitButton.Text = "Save"
splitButton.Size = New Size(120, 40)
splitButton.Location = New Point(20, 20)
splitButton.Style = SplitButtonVisualStyle.Office2016Colorful

' Add dropdown items
Dim saveItem As New ToolStripMenuItem("Save")
Dim saveAsItem As New ToolStripMenuItem("Save As...")
Dim saveAllItem As New ToolStripMenuItem("Save All")

splitButton.DropDownItems.Add(saveItem)
splitButton.DropDownItems.Add(saveAsItem)
splitButton.DropDownItems.Add(saveAllItem)

' Add to form
Me.Controls.Add(splitButton)

Common Patterns

Pattern 1: Dynamic Caption from Selected Item

Update button text when user selects a dropdown item:

private void splitButton1_DropDownItemClicked(object sender, ToolStripItemClickedEventArgs e)
{
    // Set button caption to selected item text
    splitButton1.Text = e.ClickedItem.Text;
}

Pattern 2: Toggle Mode Button

Create a toggle button with dropdown options:

splitButton1.ButtonMode = ButtonMode.Toggle;
splitButton1.IsButtonChecked = false; // Initially unchecked

// Check if button is toggled
if (splitButton1.IsButtonChecked)
{
    // Perform checked state action
}

Pattern 3: Adding Items Dynamically

Add or remove dropdown items at runtime:

// Add new item
ToolStripMenuItem newItem = new ToolStripMenuItem("New Option");
splitButton1.DropDownItems.Add(newItem);

// Remove specific item
splitButton1.DropDownItems.Remove(existingItem);

// Remove by index
splitButton1.DropDownItems.RemoveAt(0);

Pattern 4: Themed Button

Apply Office2016 theme to match application:

// Or use ThemeName property
splitButton1.ThemeName = "Office2019Colorful";

Key Properties

Essential Properties:

Important Events:

Common Use Cases

Use Case 1: Save Button with Save As Option

Implement a split button like Microsoft Word's Save button:

• Primary button saves current file
• Dropdown provides "Save As", "Save All", "Save Copy" options
• Read getting-started.md for setup
• Read button-caption.md for dynamic text updates

Use Case 2: View Toggle with Layout Options

Create a toggle button for view modes with layout variations:

• Toggle mode for on/off view state
• Dropdown items for layout options (Grid, List, Details)
• Read button-modes.md for toggle configuration
• Read getting-started.md for item management

Use Case 3: Themed Toolbar Button

Build split buttons matching Office 2016/2019 theme:

• Apply Office2016Colorful or Office2019Colorful theme
• Match application's overall design language
• Read visual-styles.md for theme application

Use Case 4: Custom Branded Button

Create fully customized split button with company branding:

• Custom colors, borders, and arrow icon
• Custom dropdown appearance
• Read advanced-customization.md for ISplitButtonRenderer implementation

Decision Guide

Choose SplitButton when:

• Users need a primary action with related alternatives
• Button caption should change based on selection
• Toggle behavior is needed alongside dropdown options
• Office-style UI patterns are desired

Consider alternatives when:

• Only dropdown menu is needed → Use ComboBox or DropDownButton
• Simple button without menu → Use standard Button control
• Multiple independent actions → Use separate Button controls or ButtonAdv

Platform Note: This skill covers Syncfusion Essential Studio for Windows Forms. For other platforms:

• WPF: Use Syncfusion WPF SplitButton (different implementation)
• ASP.NET: Use Syncfusion ASP.NET SplitButton controls
• Blazor/MAUI/React: Refer to platform-specific split button documentation