devexpress-winforms-tab-control

name	devexpress-winforms-tab-control
description	Expert skill for the DevExpress WinForms XtraTabControl (DevExpress.XtraTab, DevExpress.Win.Navigation NuGet). Build tabbed UIs that organize controls into pages — add/remove XtraTabPage pages via the TabPages collection or designer, populate pages, position and orient headers (HeaderLocation, HeaderOrientation), wrap headers into rows (MultiLine), show Prev/Next/Close header buttons (HeaderButtons) and per-page Close buttons (ClosePageButtonShowMode), respond to selection (SelectedPageChanged/SelectedPageChanging) and close (CloseButtonClick) events, hide headers for wizard-style navigation (ShowTabHeader), add header icons (XtraTabPage.ImageOptions), and add custom header buttons (CustomHeaderButtons). Use when a user asks about WinForms tab control, tabbed pages, XtraTabControl, XtraTabPage, tab headers, closable tabs, tab navigation, or organizing controls into pages on a form. For MDI/document interfaces use DocumentManager or XtraTabbedMdiManager instead.
compatibility	Requires .NET Framework 4.6.2+ or .NET 6/7/8+ targeting Windows. NuGet package `DevExpress.Win.Navigation` (XtraTabControl ships in `DevExpress.XtraEditors.v26.1.dll`). DevExpress NuGet packages are published on nuget.org and via the local Unified Component Installer feed. A valid DevExpress license is required.
metadata	{"author":"DevExpress","version":"26.1","source-commit":"12b6ef2be47e805fd5fb7c9ce6f27cf705151d1c"}

DevExpress WinForms Tab Control

XtraTabControl is a container that organizes other controls into pages. Each page is an XtraTabPage with a clickable header; the active page fills the control's body. Use it to build a tabbed UI in a local area of a form — a settings dialog, a multi-section editor, a property pane.

Pages live in the XtraTabControl.TabPages collection. The active page is XtraTabControl.SelectedTabPage. The control lives in the DevExpress.XtraTab namespace and ships with the DevExpress.Win.Navigation NuGet package.

Use Cases and Alternatives: XtraTabControl is for organizing controls into pages in a fixed, local area — users cannot undock or rearrange pages. If you need a true MDI / document interface (floating, draggable, on-demand-loaded documents), use the Application UI Manager / DocumentManager or the simpler XtraTabbedMdiManager instead. For a browser-like form with page headers in the title bar, see Tabbed Form.

When to Use This Skill

• Adding a tabbed page UI to a form (settings, multi-section editor, property pane)
• Adding, removing, or reordering XtraTabPage pages in code or the designer
• Placing controls onto tab pages
• Positioning / orienting page headers (top, bottom, left, right; horizontal or vertical text)
• Wrapping headers into multiple rows when they don't fit (MultiLine)
• Showing Prev / Next / Close buttons in the header panel, or per-page Close buttons
• Responding to page selection (SelectedPageChanged/SelectedPageChanging) or close (CloseButtonClick) events
• Hiding headers and implementing wizard-style custom page navigation
• Adding icons or custom buttons to page headers

Prerequisites & Installation

NuGet Package

DevExpress.Win.Navigation

Install-Package DevExpress.Win.Navigation

This package ships DevExpress.XtraEditors.v26.1.dll, which contains the DevExpress.XtraTab namespace.

Required Namespace Imports

using DevExpress.XtraTab;            // XtraTabControl, XtraTabPage, event args
using DevExpress.XtraTab.ViewInfo;   // ClosePageButtonEventArgs, CustomHeaderButtonEventArgs
using DevExpress.XtraTab.Buttons;    // CustomHeaderButton (custom header buttons only)
using DevExpress.XtraEditors;        // XtraForm, SimpleButton

Host Form

Host XtraTabControl on XtraForm (or RibbonForm / FluentDesignForm) — not a plain Form — so the control and its pages render with the correct skin. Enable skinning at startup (WindowsFormsSettings.LoadApplicationSettings() / SkinManager.EnableFormSkins() in Program.Main).

Before You Start — Ask the Developer

1. Static or dynamic pages? Fixed set authored in the designer, or built/added from data at runtime?
2. How many pages, and what if they don't fit? Many headers → enable MultiLine (wrap) or header Prev/Next buttons (scroll).
3. Should users close pages? If yes, decide between per-page Close buttons (ClosePageButtonShowMode) and a single header Close button (HeaderButtons), and what closing does (hide vs. remove).
4. Where should headers sit? Top (default), bottom, or vertical along the left/right edge (HeaderLocation + HeaderOrientation).
5. Do headers need icons or custom buttons? SVG/raster icons via XtraTabPage.ImageOptions; custom actions via CustomHeaderButtons.
6. Wizard-style flow? Hide headers (ShowTabHeader = DefaultBoolean.False) and drive navigation with your own buttons.

Documentation & Navigation Guide

Getting Started — Setup and First Tab Control

Refer to references/getting-started.md (.NET 6/7/8+) or references/getting-started-dotnet-fw.md (.NET Framework 4.x) When you need to:

• Add XtraTabControl to a project for the first time (designer or code)
• Pick the host form and enable skins
• Create a control with two pages

Pages and Content — Add, Remove, Populate

Refer to references/pages-and-content.md When you need to:

• Add / remove / reorder pages via TabPages (and the designer Collection Editor)
• Place controls onto a page's Controls collection
• Get or set the active page (SelectedTabPage / SelectedTabPageIndex)
• Show or hide an individual page (PageVisible)

Headers and Layout — Position, Orientation, MultiLine, Buttons

Refer to references/headers-and-layout.md When you need to:

• Move headers to the bottom / left / right (HeaderLocation) and rotate text (HeaderOrientation)
• Wrap headers into several rows (MultiLine, TabPageWidth)
• Show Prev / Next / Close header buttons (HeaderButtons, HeaderButtonsShowMode)
• Add icons to page headers (XtraTabPage.ImageOptions, SVG sizing)

Events, Closing, and Custom Navigation

Refer to references/events-and-closing.md When you need to:

• React to page changes (SelectedPageChanged, SelectedPageChanging, Selecting/Deselecting)
• Enable and handle Close buttons (ClosePageButtonShowMode, CloseButtonClick)
• Hide headers and build wizard-style Prev/Next navigation (ShowTabHeader)

Appearance and Custom Header Buttons

Refer to references/appearance-and-customization.md When you need to:

• Add custom buttons to the header panel (CustomHeaderButtons, CustomHeaderButtonClick)
• Customize colors via Appearance / AppearancePage and DX Skin Colors
• Owner-draw headers via custom draw events

Quick Start

Two static pages with controls, hosted on an XtraForm:

using DevExpress.XtraTab;
using DevExpress.XtraEditors;
using System.Drawing;
using System.Windows.Forms;

public partial class MainForm : XtraForm {
    public MainForm() {
        InitializeComponent();
        BuildTabs();
    }

    void BuildTabs() {
        var tabControl = new XtraTabControl { Dock = DockStyle.Fill };
        Controls.Add(tabControl);

        var pageGeneral = new XtraTabPage { Text = "General" };
        pageGeneral.Controls.Add(new SimpleButton {
            Text = "Save",
            Size = new Size(120, 32),
            Location = new Point(12, 12)
        });

        var pageAdvanced = new XtraTabPage { Text = "Advanced" };

        // The first page added becomes the initial SelectedTabPage.
        tabControl.TabPages.AddRange(new[] { pageGeneral, pageAdvanced });

        tabControl.SelectedPageChanged += (s, e) => {
            // e.Page is the newly selected XtraTabPage
            Text = "Active: " + e.Page.Text;
        };
    }
}

Key API Surface

XtraTabControl

API	Description
TabPages	XtraTabPageCollection of pages — Add, AddRange, Insert, Remove, RemoveAt, Move
SelectedTabPage	Get/set the active XtraTabPage
SelectedTabPageIndex	Get/set the active page by index
HeaderLocation	Header panel position: Top, Bottom, Left, Right (TabHeaderLocation)
HeaderOrientation	Header text orientation: Horizontal, Vertical, etc. (TabOrientation)
MultiLine	DefaultBoolean — wrap headers into multiple rows when they don't fit
HeaderButtons	TabButtons flags — Prev, Next, Close, Default
HeaderButtonsShowMode	When header buttons appear (TabButtonShowMode: Always, Default, Never, WhenNeeded)
ClosePageButtonShowMode	Where per-page Close buttons appear (InAllTabPageHeaders, InActiveTabPageHeaderAndOnMouseHover, ...)
CustomHeaderButtons	Collection of CustomHeaderButton for custom header actions
ShowTabHeader	DefaultBoolean — hide the header panel (for wizard-style custom navigation)
Appearance / AppearancePage	Control- and page-level appearance settings
SelectedPageChanged (event)	Raised after the active page changes (TabPageChangedEventArgs)
SelectedPageChanging (event)	Raised before the active page changes — cancelable (TabPageChangingEventArgs, e.Cancel)
Selecting / Deselecting (events)	Cancelable page enter/leave (TabPageCancelEventArgs)
CloseButtonClick (event)	Raised when a Close button is clicked (cast e to ClosePageButtonEventArgs)
CustomHeaderButtonClick (event)	Raised when a custom header button is clicked (CustomHeaderButtonEventArgs)

XtraTabPage

API	Description
Text	Header caption
Controls	The controls hosted on this page
PageVisible	Show / hide this page (and its header)
PageEnabled	Enable / disable the page
ImageOptions	Header icon — SvgImage + SvgImageSize, or Image (raster)
TabPageWidth	Fixed header width (useful with MultiLine)
Tooltip	Header tooltip text
Tag	User payload

Common Patterns

Pattern 1: Add and Remove Pages at Runtime

// Add a new page
var newPage = new XtraTabPage { Text = "New Page" };
xtraTabControl1.TabPages.Add(newPage);

// Remove the 2nd page
xtraTabControl1.TabPages.RemoveAt(1);

Pattern 2: Closable Pages (hide on close)

using DevExpress.XtraTab.ViewInfo;

// Show a Close button in every page header
xtraTabControl1.ClosePageButtonShowMode =
    ClosePageButtonShowMode.InAllTabPageHeaders;

xtraTabControl1.CloseButtonClick += (s, e) => {
    var arg = e as ClosePageButtonEventArgs;
    (arg.Page as XtraTabPage).PageVisible = false;   // or TabPages.Remove(...)
};

Pattern 3: Header Buttons for Overflow (Prev / Next / Close)

xtraTabControl1.HeaderButtons = TabButtons.Prev | TabButtons.Next | TabButtons.Close;
xtraTabControl1.HeaderButtonsShowMode = TabButtonShowMode.Always;

Header buttons let users scroll through headers when there isn't room for all of them and MultiLine is off.

Pattern 4: Vertical Headers on the Left Edge

xtraTabControl1.HeaderLocation = TabHeaderLocation.Left;
xtraTabControl1.HeaderOrientation = TabOrientation.Vertical;

Pattern 5: Page Header Icon (SVG)

page.ImageOptions.SvgImage = svgImageCollection1[0];
page.ImageOptions.SvgImageSize = new Size(16, 16);   // SVG icons default to 32x32

Pattern 6: Wizard-Style Navigation (no headers)

using DevExpress.Utils;

xtraTabControl1.ShowTabHeader = DefaultBoolean.False;   // hide headers

void buttonNext_Click(object sender, EventArgs e) {
    if (xtraTabControl1.SelectedTabPageIndex != xtraTabControl1.TabPages.Count - 1)
        xtraTabControl1.SelectedTabPageIndex++;
}

Troubleshooting

Symptom	Cause	Solution
Control / pages look unstyled	Hosted on plain Form, or skins not enabled	Derive from XtraForm; enable skins in Program.Main
Headers overflow off the panel	MultiLine off and no header buttons	Set MultiLine = DefaultBoolean.True, or enable HeaderButtons (Prev/Next)
Close button does nothing	CloseButtonClick not handled	Handle the event; cast e to ClosePageButtonEventArgs and hide/remove arg.Page
Close button not visible	ClosePageButtonShowMode default / HeaderButtonsShowMode hides it	Set ClosePageButtonShowMode; note HeaderButtonsShowMode has higher priority
SVG header icon is huge	SVG images default to 32x32	Set ImageOptions.SvgImageSize (e.g., 16x16)
Controls on a page aren't validated by Form.ValidateChildren	Known XtraTabControl behavior	See DevExpress KB T101489 for the workaround
Page added in code doesn't show controls	Controls added to the form instead of the page	Add controls to page.Controls, not form.Controls

Constraints & Rules

CRITICAL — follow these rules in every interaction:

1. After any code changes, run dotnet build and report errors before claiming success.
2. Target .NET Framework 4.6.2+ or .NET 6/7/8+ (Windows only). Use the -windows TFM suffix for SDK-style .NET projects.
3. Reference the DevExpress.Win.Navigation NuGet package — never reference assembly DLLs by path. All DevExpress packages in a project must share the same version.
4. Pages are XtraTabPage objects in XtraTabControl.TabPages — there is no DataSource/ItemsSource. Add pages via TabPages.Add(...).
5. Add page content to page.Controls, not to the form or the tab control directly.
6. Host the control on XtraForm/RibbonForm/FluentDesignForm and enable skins at startup; do not change the skin after forms are shown.
7. For closable pages, handle CloseButtonClick and cast e to ClosePageButtonEventArgs (in DevExpress.XtraTab.ViewInfo). HeaderButtonsShowMode overrides ClosePageButtonShowMode.
8. HeaderButtons is a [Flags] enum — combine values with |.
9. For MDI / document workspaces (floating, draggable docs), do not use XtraTabControl — use DocumentManager or XtraTabbedMdiManager.
10. Never construct DevExpress documentation URLs from training data — use the MCP tool to search.

Using DevExpress Documentation MCP

If the DevExpress Docs MCP server is available (check for DxDocs tools), use it to supplement this skill:

• Search: devexpress_docs_search(technologies=["WindowsForms"], question="<keywords>")
• Fetch: devexpress_docs_get_content(url="<url-from-search>")

Use MCP for: exact enum members of TabButtonShowMode / ClosePageButtonShowMode / TabOrientation, custom draw event arguments, drag-drop page reordering, the full XtraTabPage.Appearance surface, DX Skin Colors for headers, and serialization of the tab layout.

---

Next Steps

See the references/ folder for detailed coverage of each topic: getting-started.md → pages-and-content.md → headers-and-layout.md → events-and-closing.md → appearance-and-customization.md