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

Implementing Tab Controls (TabControlAdv)

The TabControlAdv is an advanced Windows Forms tab control that enables organizing visual content in a compact, tabbed interface. It extends the standard TabControl with extensive appearance customization, navigation features, editing capabilities, and styling options.

When to Use This Skill

Use this skill when you need to:

• Implement tabbed interfaces in Windows Forms applications
• Add TabControlAdv with multiple TabPageAdv items
• Customize tab appearance, colors, fonts, or styles
• Enable tab editing, drag-and-drop, or close buttons
• Configure tab navigation with TabPrimitives
• Handle tab events (selection, closing, editing, etc.)
• Apply Office, Metro, or Visual Studio themes to tabs
• Implement scrolling, tooltips, or multi-line tabs
• Persist tab state (order, active page) across sessions

Component Overview

TabControlAdv provides:

• Tab Alignment: Top, Bottom, Left, Right positioning
• Navigation Support: TabPrimitives for first/last/next/previous navigation
• Editing Support: Runtime tab header text editing
• Icons Support: Images in tab headers
• Drag and Drop: Rearrange tabs via drag-and-drop
• Close Buttons: Individual or global close buttons for tabs
• ToolTips: Standard and SuperToolTips for tabs
• Styling: 15+ built-in themes (2D, 3D, Metro, Office, VS styles)
• Serialization: Save and load tab states
• Scrolling: Smooth scrolling when tabs overflow

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Assembly deployment and NuGet packages
• Adding TabControlAdv through designer
• Adding control manually in code
• Creating and adding tabs (TabPageAdv)
• Adding controls to tab pages
• Basic tab placement configuration

Alignment and Layout

📄 Read: references/alignment-layout.md

• Tab alignment (Top, Bottom, Left, Right)
• Text alignment within tabs
• Multi-line tab support
• RTL (Right-to-Left) support
• Rotating tabs and text
• TabGap spacing

Appearance and Customization

📄 Read: references/appearance-customization.md

• Background colors and images
• Active and inactive tab colors
• Font and forecolor settings
• Border styles and colors
• Tab styles (2D, 3D, Metro, Office themes)
• SizeMode options (Normal, Fixed, ShrinkToFit, FillToRight)

Interactive Features

📄 Read: references/interactive-features.md

• Close button settings
• Tooltip and SuperTooltip support
• Scroll buttons and scrollbars
• Middle-click to close tabs
• Auto-scroll configuration

Tab Navigation

📄 Read: references/tab-navigation.md

• TabPrimitives overview
• Navigation control types (FirstTab, LastTab, NextTab, PreviousTab, etc.)
• DropDown and Close primitives
• Custom primitives
• Creating TabPrimitives programmatically

Customization and Editing

📄 Read: references/customization-editing.md

• Renaming tab headers at runtime (LabelEdit)
• Drag-and-drop tab reordering (UserMoveTabs)
• Padding and spacing
• Tab page border styles
• Animated GIF images in tabs
• Preventing specific tabs from moving

Serialization

📄 Read: references/serialization.md

• PersistTabState property
• Automatic tab state persistence
• Saving tab order and active page

Events and Event Handling

📄 Read: references/events.md

• Edit events (BeforeEdit, AfterEdit)
• Selection events (SelectedIndexChanging, SelectedIndexChanged)
• Tab primitive click events
• DrawItem for custom rendering
• Tab page events (Closed, Closing)
• Other events (Paint, BackgroundImageChanged, etc.)

Quick Start Example

Basic Implementation

using Syncfusion.Windows.Forms.Tools;

// Create TabControlAdv
TabControlAdv tabControlAdv1 = new TabControlAdv();
tabControlAdv1.Size = new Size(400, 300);

// Create and add tab pages
TabPageAdv tabPage1 = new TabPageAdv();
tabPage1.Text = "Home";
tabPage1.ImageIndex = 0; // Optional icon

TabPageAdv tabPage2 = new TabPageAdv();
tabPage2.Text = "Settings";

tabControlAdv1.TabPages.Add(tabPage1);
tabControlAdv1.TabPages.Add(tabPage2);

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

With Styling and Features

// Apply Office 2016 theme
tabControlAdv1.TabStyle = typeof(TabRendererOffice2016Colorful);

// Enable features
tabControlAdv1.ShowTabCloseButton = true;
tabControlAdv1.UserMoveTabs = true;
tabControlAdv1.LabelEdit = true;
tabControlAdv1.ShowToolTips = true;

// Customize appearance
tabControlAdv1.ActiveTabColor = Color.FromArgb(255, 255, 255);
tabControlAdv1.InactiveTabColor = Color.FromArgb(240, 240, 240);
tabControlAdv1.ActiveTabFont = new Font("Segoe UI", 9F, FontStyle.Bold);

Common Patterns

Pattern 1: Tabbed Document Interface

// Create tab control for documents
TabControlAdv documentTabs = new TabControlAdv();
documentTabs.Dock = DockStyle.Fill;
documentTabs.ShowTabCloseButton = true;
documentTabs.ShowCloseButtonForActiveTabOnly = true;

// Add document tabs dynamically
void AddDocumentTab(string title, Control content)
{
    TabPageAdv docTab = new TabPageAdv();
    docTab.Text = title;
    docTab.Controls.Add(content);
    content.Dock = DockStyle.Fill;
    documentTabs.TabPages.Add(docTab);
    documentTabs.SelectedTab = docTab;
}

// Handle tab closing
documentTabs.SelectedTab.Closing += (sender, e) =>
{
    var result = MessageBox.Show("Save changes?", "Close",
        MessageBoxButtons.YesNoCancel);
    if (result == DialogResult.Cancel)
        e.Cancel = true;
};

Pattern 2: Navigation Tabs with Icons

// Setup image list
ImageList tabImages = new ImageList();
tabImages.Images.Add("home", Properties.Resources.HomeIcon);
tabImages.Images.Add("settings", Properties.Resources.SettingsIcon);
tabControlAdv1.ImageList = tabImages;

// Create tabs with icons
TabPageAdv homeTab = new TabPageAdv();
homeTab.Text = "Home";
homeTab.ImageIndex = 0;

TabPageAdv settingsTab = new TabPageAdv();
settingsTab.Text = "Settings";
settingsTab.ImageIndex = 1;

// Configure alignment
tabControlAdv1.ImageAlignmentR = RelativeImageAlignment.LeftOfText;

Pattern 3: Tab Navigation Controls

// Enable navigation primitives
tabControlAdv1.TabPrimitivesHost.Visible = true;

// Add navigation buttons
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.FirstTab, null, Color.Empty, true, 1, "First"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.PreviousTab, null, Color.Empty, true, 1, "Previous"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.NextTab, null, Color.Empty, true, 1, "Next"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.LastTab, null, Color.Empty, true, 1, "Last"));
tabControlAdv1.TabPrimitivesHost.TabPrimitives.Add(
    new TabPrimitive(TabPrimitiveType.DropDown, null, Color.Empty, true, 1, "DropDown"));

Pattern 4: Handling Tab Selection

// Prevent selection of specific tab
tabControlAdv1.SelectedIndexChanging += (sender, e) =>
{
    if (e.NewSelectedIndex == 2) // Prevent selecting 3rd tab
    {
        e.Cancel = true;
        MessageBox.Show("This tab is disabled");
    }
};

// React to selection changes
tabControlAdv1.SelectedIndexChanged += (sender, e) =>
{
    var selectedTab = tabControlAdv1.SelectedTab;
    Console.WriteLine($"Selected tab: {selectedTab.Text}");
    // Load content for selected tab
};

Key Properties

Core Properties

Appearance Properties

Feature Properties

Navigation Properties

Common Use Cases

Use Case 1: Application Settings Dialog

Create a tabbed settings dialog with categories like "General", "Appearance", "Advanced":

• Use Alignment = TabAlignment.Left for vertical tabs
• Apply consistent styling with TabStyle
• Add icons to tabs with ImageList

Use Case 2: Multi-Document Editor

Build a document editor with closeable tabs:

• Enable ShowTabCloseButton = true
• Handle Closing event to prompt for unsaved changes
• Use UserMoveTabs = true for reordering

Use Case 3: Wizard Interface

Create a step-by-step wizard with disabled tab selection:

• Use SelectedIndexChanging to control navigation
• Apply custom colors to indicate progress
• Show/hide tabs based on wizard flow

Use Case 4: Dashboard with Sections

Organize dashboard content into sections:

• Use Multiline = true for many tabs
• Apply SizeMode.FillToRight for uniform tab widths
• Enable ShowScroll for overflow handling

Assembly References

Required assemblies:

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

For Grid controls in tabs, also add:

• Syncfusion.Grid.Base.dll
• Syncfusion.Grid.Windows.dll