devexpress-winforms-data-grid

name	devexpress-winforms-data-grid
description	DevExpress WinForms Data Grid — GridControl with GridView, BandedGridView, AdvBandedGridView, CardView, LayoutView, TileView, and WinExplorerView, plus the TreeList for hierarchical data. Covers data binding (regular, ServerMode, InstantFeedback, VirtualServerModeSource), column generation (PopulateColumns, AddVisible, unbound columns via UnboundExpression, bands, ColumnEdit), cell display and editing (RepositoryItem, CustomRowCellEdit, DisplayFormat, edit forms, OptionsColumn), conditional formatting (FormatRules), validation (ValidateRow, SetColumnError), filtering (Excel-style, Auto Filter Row, Find Panel, ActiveFilterString), sorting and grouping (SortInfo, GroupInterval), master-detail (LevelTree, pattern views), print and export (ExportToXlsx/Pdf), focus and selection (FocusedRow, MultiSelect), drag-and-drop, and layout persistence (SaveLayoutToXml). Use for any WinForms grid, tree-list, or card-view scenario.
compatibility	Requires .NET Framework 4.6.2+ or .NET 8+ targeting Windows. Primary NuGet packages — `DevExpress.Win.Grid` (GridControl, all views), `DevExpress.Win.TreeList` (TreeList), `DevExpress.Win.Navigation` (shared navigation), `DevExpress.Win.Printing` (export and print). 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 Data Grid, Tree List, and CardView

DevExpress WinForms Data Grid (DevExpress.XtraGrid.GridControl) is a high-performance, DirectX-accelerated data-aware container that uses a flexible View-based architecture. A single GridControl hosts one or more views — GridView (tabular), BandedGridView, AdvBandedGridView, CardView, LayoutView, TileView, WinExplorerView — each presenting the same underlying data differently. The TreeList control (DevExpress.XtraTreeList.TreeList) is a separate but conceptually similar control for hierarchical data with parent-child relationships.

Many concepts are shared across GridView, BandedGridView, CardView, LayoutView, and TreeList: data binding, column/field definition, in-place editors, conditional formatting, validation, filtering, sorting, focus/selection, drag-and-drop, and layout persistence. Some concepts are unique: master-detail belongs to GridControl, hierarchical node manipulation belongs to TreeList, and card-specific layout settings belong to CardView/LayoutView. This skill covers all three controls in one place because developers rarely use them in isolation.

When to Use This Skill

• Bind a grid or tree list to any data source (DataTable, BindingSource, IList, Entity Framework, XPO, LINQ to SQL, MongoDB, JSON, ServerMode/InstantFeedback sources, VirtualServerModeSource for infinite scrolling).
• Define columns at design time (Grid Designer), via auto-generation (AutoPopulateColumns), or in code (PopulateColumns, Columns.AddVisible). Configure unbound columns with UnboundExpression or CustomUnboundColumnData.
• Assign in-place editors with RepositoryItem descendants (RepositoryItemSpinEdit, RepositoryItemLookUpEdit, RepositoryItemCheckEdit, RepositoryItemProgressBar, RepositoryItemRichTextEdit, etc.). Use CustomRowCellEdit and CustomRowCellEditForEditing for per-cell editors.
• Format cell values (DisplayFormat, EditFormat, CustomColumnDisplayText) and switch between in-place edit, edit-form, and edit-entire-row modes.
• Apply conditional formatting (color scales, data bars, icon sets, expressions) via FormatRules.
• Validate cell or row input with ValidatingEditor, ValidateRow, InvalidValueException, SetColumnError, or IDXDataErrorInfo.
• Configure UI filtering (Excel-style filters, Auto Filter Row, Filter Editor, Find Panel) and apply filters in code (ActiveFilterString, ActiveFilterCriteria, CustomRowFilter, SubstituteFilter).
• Implement sorting and grouping, including custom comparisons (CustomColumnSort, CustomColumnGroup), grouping by display text, and grouping by date intervals.
• Build master-detail layouts with multiple nesting levels, hide detail relations conditionally, and access clone views.
• Print and export data (data-aware export to XLS/XLSX/CSV, WYSIWYG export to PDF/HTML/RTF, customize exported cells via XlsxExportOptionsEx.CustomizeCell).
• Configure focus and selection (FocusedRowChanged, MultiSelect, MultiSelectMode, Selection Binding).
• Implement drag-and-drop between Grid, TreeList, and ListBox via the Drag-and-Drop Behavior.
• Work with TreeList nodes programmatically (AppendNode, FocusedNode, FindNodeByKeyID, virtual mode).
• Configure CardView layout (card size, caption, row/column counts).
• Save and restore layout to XML, JSON, Stream, or system Registry.

Prerequisites & Installation

NuGet Packages

Package	Required For
DevExpress.Win.Grid	GridControl + all built-in views (GridView, BandedGridView, AdvBandedGridView, CardView, LayoutView, TileView, WinExplorerView).
DevExpress.Win.TreeList	TreeList control.
DevExpress.Win.Navigation	Shared navigation primitives required by both Grid and TreeList.
DevExpress.Win.Printing	ExportToXlsx, ExportToPdf, print preview.
DevExpress.Win (optional umbrella)	Adds most DevExpress WinForms controls with design-time support. Heavier than per-control packages but simpler.
DevExpress.Data (transitive)	Server-mode sources, criteria/expression engine, IVirtualTreeListData, VirtualServerModeSource.

For ServerMode/InstantFeedback also reference one of DevExpress.Data.Linq (LINQ to SQL / EF), DevExpress.Xpo (XPO), or DevExpress.Data.ODataLinq (OData v4) per the data-binding reference.

Host Form Requirements

The Grid and TreeList work in a plain Form, but DevExpress recommends DevExpress.XtraEditors.XtraForm (or RibbonForm when the form hosts a RibbonControl) for consistent skin integration.

Common Namespaces

using DevExpress.XtraGrid;
using DevExpress.XtraGrid.Columns;
using DevExpress.XtraGrid.Views.Base;
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.XtraGrid.Views.Card;
using DevExpress.XtraGrid.Views.Layout;
using DevExpress.XtraGrid.Views.BandedGrid;
using DevExpress.XtraTreeList;
using DevExpress.XtraTreeList.Columns;
using DevExpress.XtraTreeList.Nodes;
using DevExpress.XtraEditors;
using DevExpress.XtraEditors.Repository;
using DevExpress.Data;
using DevExpress.Data.Filtering;

Before You Start — Ask the Developer

1. Which control: Data Grid (GridControl) for flat tabular/card/tile/layout views, TreeList for hierarchical data, or both (master-detail or side-by-side)?
2. Which view inside the GridControl: GridView (default tabular), BandedGridView (multi-row headers), CardView (vertical cards), LayoutView (flexible card template), TileView (Windows 8 tiles), WinExplorerView (Explorer-style)?
3. Data source characteristics: in-memory list / DataTable / EF DbContext / XPO / remote API? Size — fits in memory (<100k rows) or needs ServerMode/InstantFeedback/InfiniteScrolling?
4. Editing model: read-only, in-place cell editing, Edit Form per row, or both? Should rows post immediately or only on row change?
5. Master-detail required? How many nesting levels? Same view type at each level or different?
6. Performance constraints: very wide tables, frequently-updated cells, complex unbound expressions, server-side filtering required?
7. Persistence: does the user need to save column visibility / order / widths between sessions? XML, JSON, Registry, or via PersistenceBehavior?

Documentation & Navigation Guide

Getting Started

Refer to references/getting-started.md When you need to: install NuGet packages, instantiate GridControl or TreeList in code or designer, assign a data source, and attach a default view.

Data Binding (Grid + TreeList)

Refer to references/data-binding.md When you need to: bind to DataTable, BindingSource, IList/IBindingList, EF/LINQ/XPO; switch to ServerMode (EntityServerModeSource, XPServerCollectionSource, LinqServerModeSource, WcfServerModeSource, ODataServerModeSource) or InstantFeedback; enable infinite scrolling via VirtualServerModeSource; configure TreeList.KeyFieldName/ParentFieldName/RootValue; understand mode limitations.

Columns

Refer to references/columns.md When you need to: create columns at design time via Grid Designer, auto-generate via AutoPopulateColumns, call PopulateColumns() after data-source changes, create columns in code with Columns.AddVisible, configure unbound columns (UnboundDataType, UnboundExpression, CustomUnboundColumnData), use Display attribute to control auto-generation, configure bands in BandedGridView/AdvBandedGridView, set FieldName vs Name, and customize columns at runtime on events.

Cell Display and Editing

Refer to references/cell-display-and-editing.md When you need to: assign in-place editors via ColumnEdit, share RepositoryItem instances, format cell values (DisplayFormat, EditFormat, CustomColumnDisplayText), switch between Default / Inplace / Edit-Form / EditFormInplace EditingMode, configure per-cell editors with CustomRowCellEdit/CustomRowCellEditForEditing, control row vs cell editability with OptionsColumn.AllowEdit / OptionsColumn.ReadOnly / OptionsBehavior.Editable / ShowingEditor / EditFormShowing, and customize Edit Form layout.

Conditional Formatting

Refer to references/conditional-formatting.md When you need to: add FormatRules (rule + column + condition); choose between FormatConditionRuleValue, FormatConditionRule2ColorScale, FormatConditionRule3ColorScale, FormatConditionRuleDataBar, FormatConditionRuleIconSet, FormatConditionRuleExpression, FormatConditionRuleTopBottom, FormatConditionRuleAboveBelowAverage, FormatConditionRuleDataUpdate; combine rules with StopIfTrue; let end-users manage rules via the Conditional Formatting menu.

Validation

Refer to references/validation.md When you need to: validate cell input (ValidatingEditor + InvalidValueException), validate full rows (ValidateRow + InvalidRowException), display per-cell errors with SetColumnError, react to invalid values via ExceptionMode, integrate with IDXDataErrorInfo / IDataErrorInfo, and validate inside Edit Forms.

Filtering and Search

Refer to references/filtering-and-search.md When you need to: enable Excel-style filter dropdowns, the Auto Filter Row, the Filter Editor, the Find Panel; apply filters in code via ActiveFilterString / ActiveFilterCriteria / ActiveFilter.NonColumnFilter; implement custom row visibility with CustomRowFilter; intercept filter application with SubstituteFilter; add custom predefined filters via FilterPopupExcelData; configure MRU filters; trigger LocateByValue / ApplyFindFilter programmatically.

Sorting and Grouping

Refer to references/sorting-and-grouping.md When you need to: sort by one or many columns (SortInfo, GridMergedColumnSortInfo), enable group panel and group by column, choose ColumnSortMode (Default, DisplayText, Value, Custom), implement custom sort/group comparisons (CustomColumnSort, CustomColumnGroup), group by date intervals (GroupInterval.DateYear/Month/Day/Range), sort lookup columns by display text via FieldNameSortGroup, and customize group row text with CustomColumnDisplayText.

Master-Detail

Refer to references/master-detail.md When you need to: configure master-detail at design time via the Grid Designer, build it in code through GridControl.LevelTree and GridLevelNode, mix view types per level (e.g., GridView master + CardView detail), expand/collapse master rows (SetMasterRowExpanded, MasterRowExpanded), hide expand buttons for empty details (MasterRowEmpty), implement runtime relation counts (MasterRowGetRelationCount/MasterRowGetRelationName), enable joint group panel and Clone-View synchronization, restrict drill-down, and understand limitations (no master-detail in ServerMode).

Printing and Exporting

Refer to references/printing-and-exporting.md When you need to: decide what is configurable at design time (OptionsPrint, a Ribbon Print command) vs runtime-only (ExportTo*, export events, PrintingSystem), choose the right approach (one-call export → options object → data-aware/WYSIWYG → events → PrintingSystem/XtraReports), choose between data-aware (default for GridView/BandedGridView) and WYSIWYG modes, call ExportToXlsx/ExportToXls/ExportToCsv/ExportToPdf/ExportToHtml, customize the exported document via XlsxExportOptionsEx (CustomizeCell, AfterAddRow, CustomizeSheetHeader, CustomizeSheetFooter, CustomizeSheetSettings), print master-detail (OptionsPrint.PrintDetails, ExpandAllDetails), and use the PrintingSystem for advanced reports.

Focus and Selection

Refer to references/focus-and-selection.md When you need to: track the focused row (FocusedRow, FocusedRowHandle, FocusedRowChanged, RowClick), enable multi-select (MultiSelect), pick a selection mode (GridMultiSelectMode.RowSelect / CellSelect / CheckBoxRowSelect), bind selection state to a data field (Selection Binding), batch programmatic selection (BeginSelection/EndSelection), and handle SelectionChanged.

Drag and Drop

Refer to references/drag-and-drop.md When you need to: attach the Drag-and-Drop Behavior via BehaviorManager, reorder rows in GridView/TileView, move rows between Grid and TreeList, configure TreeListOptionsDragAndDrop.DragNodesMode (Single/Multiple), accept outer drops with AcceptOuterNodes + CustomizeNewNodeFromOuterData, customize drop targets via DragDropEvents, and handle drag in master-detail.

TreeList — Working with Nodes

Refer to references/treelist-nodes.md When you need to: build a TreeList in unbound mode (AppendNode, Nodes, SetValue), navigate nodes (FocusedNode, FirstNode, LastNode, NextNode, ParentNode, Nodes), find nodes (FindNodeByKeyID, FindNodeByFieldValue, FindNode(Predicate)), move/copy nodes, expand/collapse, work with checkboxes (OptionsView.ShowCheckBoxes, CheckState, SetCheckedChildNodesRecursive), and use virtual mode (IVirtualTreeListData, ChildListFieldName, dynamic data loading via events).

CardView — Card Layout and Settings

Refer to references/cardview-layout.md When you need to: pick CardView vs LayoutView, configure CardWidth, MaximumCardRows, MaximumCardColumns, CardCaptionFormat, CardOptionsView.ShowFieldCaptions, CardOptionsBehavior.AutoHorzWidth, CardOptionsView.ShowEmptyFields, customize card captions/borders/expand buttons, and switch to LayoutView for flexible per-field templates (TemplateCard, CardMinSize).

Saving and Restoring Layout

Refer to references/saving-and-restoring-layout.md When you need to: call SaveLayoutToXml/Json/Stream/Registry and the matching RestoreLayoutFrom... methods on Views and TreeList; control which options persist via OptionsLayoutBase/OptionsLayoutGrid/OptionsLayoutTreeList; persist appearance, filters, summaries, columns; perform post-restore fix-ups in LayoutUpgrade; use the form-level PersistenceBehavior / WorkspaceManager to bundle layout with other controls.

Quick Start

Bind a GridControl with a GridView to in-memory data

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

        var grid = new GridControl { Dock = DockStyle.Fill };
        var view = new GridView(grid);
        grid.MainView = view;
        grid.ViewCollection.Add(view);
        Controls.Add(grid);

        grid.DataSource = LoadOrders();        // any IList / BindingList / DataTable
        // The view auto-creates columns from data-source fields when
        // view.OptionsBehavior.AutoPopulateColumns is true (default).

        view.OptionsView.ShowGroupPanel = true;
        view.OptionsView.ShowAutoFilterRow = true;
        view.OptionsBehavior.Editable = false;
    }
}

Bind a TreeList to self-referenced data

treeList1.KeyFieldName = "ID";
treeList1.ParentFieldName = "ParentID";
treeList1.RootValue = 0;
treeList1.DataSource = LoadEmployees();
treeList1.ExpandAll();

Convert a GridView to CardView

var cardView = new CardView(grid);
grid.ViewCollection.Add(cardView);
grid.MainView = cardView;
cardView.CardWidth = 240;
cardView.OptionsView.ShowQuickCustomizeButton = false;

Key API Surface

Area	Member	Notes
Host	GridControl.DataSource / DataMember	Assign data; DataMember for DataSet.
Host	GridControl.MainView / FocusedView / DefaultView	Access the active or top-level view.
Host	GridControl.LevelTree / ViewCollection	Configure master-detail and pattern views.
Host	GridControl.ForceInitialize()	Force view creation before reading view APIs in Form_Load.
View	BaseView.PopulateColumns() (and overloads)	Regenerate columns; call after data-source swap.
View	ColumnView.Columns	Column collection; supports AddVisible(fieldName, caption).
View	ColumnView.OptionsBehavior / OptionsView / OptionsSelection / OptionsFilter / OptionsCustomization	Per-view feature toggles.
Column	GridColumn.FieldName / Caption / ColumnEdit / DisplayFormat / UnboundDataType / UnboundExpression / SortMode / GroupInterval	Column configuration.
Editing	RepositoryItem* (e.g., RepositoryItemSpinEdit, RepositoryItemLookUpEdit, RepositoryItemCheckEdit)	Editor templates; add to GridControl.RepositoryItems.
Validation	ColumnView.ValidatingEditor / InvalidValueException / ValidateRow / InvalidRowException / SetColumnError	Cell- and row-level validation.
Filtering	ColumnView.ActiveFilterString / ActiveFilterCriteria / ActiveFilter.NonColumnFilter / CustomRowFilter / SubstituteFilter / ApplyFindFilter	UI and code filtering.
Sorting	GridColumn.SortOrder / SortIndex / SortMode; ColumnView.SortInfo; ColumnView.CustomColumnSort	Sort configuration.
Grouping	GridColumn.GroupIndex / GroupInterval; GridView.CustomColumnGroup / GroupFormat / OptionsView.ShowGroupPanel	Grouping.
Selection	ColumnView.MultiSelect / GridView.OptionsSelection.MultiSelectMode / SelectionChanged / SelectRow / GetSelectedRows	Selection.
Export	GridControl.ExportToXlsx / ExportToXls / ExportToCsv / ExportToPdf / ExportToHtml / ExportToRtf	One-call export.
Layout persistence	BaseView.SaveLayoutToXml / RestoreLayoutFromXml / OptionsLayout / LayoutUpgrade	View layout.
TreeList	TreeList.KeyFieldName / ParentFieldName / RootValue / Nodes / FocusedNode / AppendNode / FindNodeByKeyID / OptionsBehavior.PopulateServiceColumns	TreeList essentials.
Card/Layout	CardView.CardWidth / MaximumCardColumns / MaximumCardRows / CardCaptionFormat; LayoutView.TemplateCard / CardMinSize	Card layout.

Common Patterns

Pattern 1 — Read-only grid with auto-filter row

view.OptionsBehavior.Editable = false;
view.OptionsView.ShowAutoFilterRow = true;
view.OptionsView.ShowGroupPanel = false;
view.OptionsCustomization.AllowFilter = true;

Pattern 2 — Per-cell editor switching

view.CustomRowCellEdit += (s, e) => {
    if (e.Column.FieldName == "Value"
        && !(bool)view.GetRowCellValue(e.RowHandle, "AllowEdit"))
        e.RepositoryItem = readonlyRepository;
};

Pattern 3 — Unbound calculated column

var col = view.Columns.AddVisible("Total");
col.UnboundDataType = typeof(decimal);
col.UnboundExpression = "[Quantity] * [UnitPrice] * (1 - [Discount])";
col.DisplayFormat.FormatType = FormatType.Numeric;
col.DisplayFormat.FormatString = "c2";
col.OptionsColumn.AllowEdit = false;

Pattern 4 — Web-style multi-select with check column

view.OptionsSelection.MultiSelect = true;
view.OptionsSelection.MultiSelectMode = GridMultiSelectMode.CheckBoxRowSelect;
view.OptionsSelection.ShowCheckBoxSelectorInColumnHeader = true;

Pattern 5 — TreeList unbound mode with checkboxes

treeList.Columns.AddVisible("Name");
treeList.OptionsView.ShowCheckBoxes = true;
var root = treeList.AppendNode(new object[] { "Headquarters" }, null);
treeList.AppendNode(new object[] { "Sales" }, root, CheckState.Unchecked, tag: null);
treeList.AppendNode(new object[] { "Marketing" }, root, CheckState.Unchecked, tag: null);
treeList.ExpandAll();

Troubleshooting

Symptom	Cause	Solution
view.Columns is empty in Form_Load	View not initialized yet.	Call gridControl1.ForceInitialize() before reading columns, or do so in Shown.
Grid does not show data	DataSource empty, columns invisible, or AutoPopulateColumns disabled with no manual columns.	Verify data source has rows; call PopulateColumns(); ensure column.Visible = true.
Edit Form does not appear on Enter	EditingMode is Inplace.	Set view.OptionsBehavior.EditingMode = GridEditingMode.EditForm (or EditFormInplace).
ColumnFilter works but Find Panel misses uppercase rows in ServerMode	ServerMode lowercases the search string.	Use a case-insensitive data source or follow the case-insensitive filter KB article.
ValidateRow never fires	Row was not modified, or user pressed Esc.	The event only fires when committing changed rows; force commit with view.UpdateCurrentRow().
Master-detail not expanding	EnableMasterViewMode is false, or the data source has no relations, or ShowOnlyPredefinedDetails blocks them.	Set the master view's OptionsDetail.EnableMasterViewMode = true and configure LevelTree.
TreeList shows a flat list	KeyFieldName/ParentFieldName/RootValue not set, or types do not match.	All three must be set; RootValue type must match ParentFieldName value type.
Drag-and-Drop Behavior inactive	Control.AllowDrop is true.	Leave AllowDrop = false so the Behavior owns the drop; do not mix engines.
Layout file restores columns but not appearance/filters	Default SaveLayoutTo... overload skips appearance/filters.	Pass an OptionsLayoutGrid instance with the desired flags, or OptionsLayoutBase.FullLayout.
Sorting a lookup column sorts by key not by display text	Default behavior sorts by FieldName.	Set column.FieldNameSortGroup to the display field, or column.SortMode = ColumnSortMode.DisplayText.
BindingSource used in ServerMode silently loads everything	BindingSource materializes the source.	Assign EntityServerModeSource / LinqServerModeSource etc. directly to DataSource.

Constraints & Rules

CRITICAL — follow these rules in every interaction:

1. Verify builds: after changes, run dotnet build and report errors before claiming success.
2. Target framework: confirm whether the project targets .NET Framework or modern .NET. Some helpers (e.g., the Data Source Configuration Wizard) are not available in .NET projects — generate datasets in a .NET Framework project and add the files to the .NET project.
3. NuGet rules: prefer atomic packages (DevExpress.Win.Grid, DevExpress.Win.TreeList) over the umbrella DevExpress.Win for faster designer load. Keep package versions aligned across all DevExpress references.
4. Host form: use XtraForm (or RibbonForm for ribbons) for correct skin integration.
5. WinForms is code-first: forms are designer-generated (.Designer.cs + .resx) or built in code — there is no XAML. When the user asks for "XAML", interpret it as "designer or code".
6. No BindingSource for ServerMode: assigning a BindingSource between a ServerMode source and the grid loads everything into memory and defeats ServerMode.
7. Do not mix drag-and-drop engines: enabling AllowDrop disables the DevExpress Drag-and-Drop Behavior. Pick one engine per control.
8. ColumnView.Columns[name] indexer matches Name (component name), not FieldName: when accessing columns by string, prefer view.Columns.ColumnByFieldName(...) or hold a typed reference.
9. Always set RootValue for TreeList: omitting it (or using the wrong type) yields a flat list. Default RootValue is 0, which fails when keys are strings or null.
10. Layout persistence: pass an explicit OptionsLayoutBase (e.g., OptionsLayoutGrid with StoreAppearance = true) when you need filters, summaries, or appearance to persist — default overloads omit them.

Using DevExpress Documentation MCP

• Search: devexpress_docs_search(technology="WindowsForms", query="<keywords>")
• Fetch: devexpress_docs_get_content(url="<url-from-search>")

Use MCP for: WinExplorerView, TileView, gantt-style banded views, advanced repository items (RepositoryItemRangeTrackBar, RepositoryItemRichTextEdit, RepositoryItemImageComboBox), batch modifications (BeginDataUpdate/EndDataUpdate), the Filtering UI Context, the Find Panel customization, Smart Paste, AI-Powered Semantic Search, document post-processing for printed output, and IXtraSerializable for custom layout properties.

---

Next Steps

Open the references folder for deep-dive guidance on each topic listed above. Each reference is self-contained — read only what the current task needs, then return here for cross-topic patterns or troubleshooting.