devexpress/agent-skills/devexpress-winforms-data-grid

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 in InitializeComponent(), 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

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

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. 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: declare columns in InitializeComponent(), 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: build master-detail 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).