devexpress/agent-skills/devexpress-winforms-layout

DevExpress WinForms Layout Management

DevExpress WinForms ships a family of layout controls that cover form composition scenarios — from responsive data-entry forms to IDE-style dockable tool windows. The main controls ship in the `DevExpress.Win.Navigation` NuGet package; the lightweight StackPanel/TablePanel live in `DevExpress.Utils` (pulled in transitively).

Common misconception: There is no separate FlowLayoutControl or TableLayoutControl class. Flow Layout and Table Layout are modes (LayoutMode) on a LayoutControlGroup inside LayoutControl.

Author layouts in the form's `*.Designer.cs` by default. Generate the layout inside InitializeComponent(), the same way the Visual Studio WinForms designer serializes it — not in the form constructor body. Only build a layout in runtime code when the user explicitly asks for it or the structure is genuinely dynamic/data-driven. See rule 1 in Constraints & Rules and the worked example in references/getting-started.md. (For a form generated from a table or class, prefer DataLayoutControl + RetrieveFields() over a hand-built LayoutControl.)

When to Use This Skill

• Add a LayoutControl to a form and arrange editors with labels, groups, tabbed groups, and size constraints.
• Use DataLayoutControl to auto-generate a bound edit form from a DataTable or business object.
• Add a DockManager to enable VS-style dockable panel UI.
• Use StackPanel or TablePanel as lightweight layout containers.
• Save and restore any layout to XML, JSON, stream, or registry; or manage multiple layout slots with WorkspaceManager.

Prerequisites & Installation

DevExpress.Win.Navigation

Host form: DevExpress.XtraEditors.XtraForm (or RibbonForm).

Namespaces:

using DevExpress.XtraLayout;
using DevExpress.XtraLayout.Utils;   // LayoutMode (Flow/Table layout mode)
using DevExpress.XtraDataLayout;
using DevExpress.XtraBars.Docking;
using DevExpress.XtraEditors;
using DevExpress.Utils.Layout;       // StackPanel, TablePanel

Before You Start — Ask the Developer

If the host agent has a structured question-asking tool available, use it to ask these questions one at a time with clear options — for example, Claude Code's AskUserQuestion tool or GitHub Copilot's askQuestions tool. If no such tool is available, ask the questions directly in the chat response before generating code.

1. Control type: Which layout control is needed — LayoutControl (manual, labeled form), DataLayoutControl (data-driven auto-generated form — the default when the form is built from a table or class), DockManager (VS-style panels), or StackPanel/TablePanel (lightweight containers)?
2. Layout structure: How many groups? Do groups need tabs (TabbedControlGroup)? Is a flat list of editors sufficient?
3. Layout mode (for LayoutControl): Free (default), Flow (items wrap in rows), or Table (grid with row/column indexes)?
4. Data source (for DataLayoutControl): What type — DataTable, BindingSource, business object (POCO)? Are [DataAnnotations] attributes on the business object?
5. Runtime customization: Should end-users be allowed to rearrange or hide editors at runtime?
6. Persistence: Should the layout be saved between sessions? One layout slot or multiple (named workspaces)?
7. DockManager target: Will panels contain specific controls (grid, property editor, output log)? Should panels be closeable, floatable, auto-hideable?

Documentation & Navigation Guide

Getting Started

Refer to references/getting-started.md (.NET 8+) or references/getting-started-dotnet-fw.md (.NET Framework 4.x) When you need to: install DevExpress.Win.Navigation, reference the correct assemblies and namespaces, author a layout in the form's *.Designer.cs (the default), and write the minimal boilerplate for each control type.

Layout Control Variants — When to Use Which

Refer to references/layout-controls.md When you need to: choose between LayoutControl, DataLayoutControl, DockManager, StackPanel, and TablePanel; understand the decision criteria and the differences; clarify naming confusion (FlowLayoutControl/TableLayoutControl vs LayoutMode).

Building Layouts in Code

Refer to references/building-layouts.md When you need to: construct a LayoutControl hierarchy (AddItem, AddGroup, AddTabbedGroup, EmptySpaceItem, SplitterItem), enable Flow or Table layout mode on a group, set size constraints, hide/show items, dock panels with DockManager (AddPanel, DockTo, DockAsTab), or configure StackPanel/TablePanel rows/columns. (Prefer authoring in the *.Designer.cs file — see Getting Started — unless the layout is built dynamically at runtime.)

Saving and Restoring Layout

Refer to references/saving-restoring-layout.md When you need to: persist layout state to XML/JSON/stream/registry for LayoutControl or DockManager; control what is serialized via OptionsSerialization; manage multiple named layout slots with WorkspaceManager; implement Form_Load restore and FormClosing save patterns; reset to default layout using a cached MemoryStream.

Quick Start

Default to the designer. For a normal form, author the LayoutControl/DockManager and its items in MainForm.Designer.cs (InitializeComponent) so the form stays editable in the WinForms designer — see references/getting-started.md for the worked *.Designer.cs example. The runtime-code snippets below show the same API for the cases where you build the layout dynamically (or the user explicitly asks for code) — do not put this in the form constructor body of a designer-backed form.

LayoutControl with Two Groups (runtime / dynamic)

public partial class MainForm : DevExpress.XtraEditors.XtraForm
{
    public MainForm() {
        InitializeComponent();
 
        var lc = new LayoutControl { Dock = DockStyle.Fill };
        Controls.Add(lc);
 
        lc.BeginUpdate();
        try {
            // Group 1: Personal
            LayoutControlGroup g1 = lc.Root.AddGroup();
            g1.Text = "Personal Info";
            g1.Name = "lcgPersonal";
            g1.AddItem("First Name", new TextEdit { Name = "edFirst" }).Name = "lciFirst";
            g1.AddItem("Last Name",  new TextEdit { Name = "edLast"  }).Name = "lciLast";
 
            // Group 2: Contact
            LayoutControlGroup g2 = lc.Root.AddGroup();
            g2.Text = "Contact";
            g2.Name = "lcgContact";
            g2.AddItem("Email",  new TextEdit { Name = "edEmail" }).Name = "lciEmail";
            g2.AddItem("Phone",  new TextEdit { Name = "edPhone" }).Name = "lciPhone";
        }
        finally {
            lc.EndUpdate();
        }
    }
}

DockManager with Three Panels

var dm = new DockManager { Form = this };
 
var left   = dm.AddPanel(DockingStyle.Left);
left.Text  = "Explorer";  left.Width = 220; left.Name = "pnlExplorer";
 
var right  = dm.AddPanel(DockingStyle.Right);
right.Text = "Properties"; right.Width = 240; right.Name = "pnlProperties";
 
var bottom = dm.AddPanel(DockingStyle.Bottom);
bottom.Text = "Output"; bottom.Height = 120; bottom.Name = "pnlOutput";
 
left.Controls.Add(new TreeView { Dock = DockStyle.Fill });

Persist DockManager Layout

void Form_Load(object sender, EventArgs e) {
    if (File.Exists("dock.xml")) dockManager1.RestoreLayoutFromXml("dock.xml");
}
void Form_FormClosing(object sender, FormClosingEventArgs e) {
    dockManager1.SaveLayoutToXml("dock.xml");
}

Key API Surface

Troubleshooting