devexpress/agent-skills/devexpress-winforms-editors

DevExpress WinForms Data Editors

The DevExpress Editors suite (DevExpress.XtraEditors) is a family of standalone WinForms input controls plus the repository-item infrastructure that lets the same editor be embedded into data-aware controls (Data Grid, TreeList, Ribbon, etc.). Almost every editor derives from BaseEdit, which contributes the bindable EditValue property; a smaller set of controls inherit from BaseControl directly and are used for display, action, or layout — buttons, labels, list boxes, navigators.

This skill covers three things at once:

1. The editor hierarchy — the BaseEdit tree (TextEdit branch, BaseCheckEdit branch, PictureEdit, ProgressBar, RadioGroup, RatingControl, TrackBar, TokenEdit, SparklineEdit), the non-BaseEdit controls, and how to pick the right one.
2. Masks — the input-mask system shared across TextEdit descendants: Numeric, DateTime/DateOnly/TimeOnly/DateTimeOffset, Simple, TimeSpan, RegEx (Extended Regular Expressions), Simplified RegEx, including the MaskSettings.Configure<> fluent API and the EditMask data-annotation attributes.
3. Editor buttons — EditorButton, ButtonPredefines, EditorButtonImageOptions, Properties.Buttons collection, click handling, captions/icons/tooltips, in ButtonEdit descendants (ButtonEdit, ComboBoxEdit, LookUpEdit, SpinEdit, BrowsePathEdit, PopupBaseEdit, ColorPickEdit, PopupGalleryEdit, PopupContainerEdit).

When to Use This Skill

• Adding any DevExpress editor to a form for text, number, date, time, lookup, color, image, file path, etc.
• Choosing between editor families (TextEdit vs ButtonEdit vs ComboBoxEdit vs LookUpEdit vs GridLookUpEdit vs SearchLookUpEdit; DateEdit vs TimeEdit vs DateTimeOffsetEdit; CheckEdit vs ToggleSwitch; ProgressBarControl vs MarqueeProgressBarControl).
• Knowing what is not a BaseEdit (no EditValue) and when to use a simple control instead — labels, buttons, list boxes, breadcrumb, navigator.
• Applying input masks, including DateTime, Numeric (c, n, p, f, d), Simple metacharacter patterns, RegEx patterns, and culture-aware behavior.
• Adding, customizing, hiding, or removing buttons in ButtonEdit descendants — predefined glyphs (ButtonPredefines.Ellipsis, Search, Plus, Minus, Up, Down, Clear, Delete, OK, Close, Right, Left, Combo, DropDown, …), custom SVG/raster images, captions, alignment, tooltips, and click events.
• Hiding the text box (TextEditStyle.HideTextEditor) or making it read-only (DisableTextEditor).
• Embedding editors into the Grid / TreeList / Ribbon via repository items.

Prerequisites & Installation

NuGet Packages

Host Form

Use DevExpress.XtraEditors.XtraForm (or RibbonForm when using a ribbon) for correct skin integration.

Common Namespaces

using DevExpress.XtraEditors;
using DevExpress.XtraEditors.Controls;       // EditorButton, ButtonPredefines, TextEditStyles, ImageLocation, KeyShortcut
using DevExpress.XtraEditors.Repository;     // RepositoryItem*, RepositoryItemButtonEdit
using DevExpress.XtraEditors.Mask;           // MaskType, MaskProperties, MaskSettings.*
using DevExpress.Utils.Svg;                  // SvgImage.FromFile, SvgImage.FromStream
using DevExpress.Utils;                      // ImageCollection helpers, DefaultBoolean

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. What type of value does the editor edit — string / number / date / time / bool / collection / hierarchical lookup / color / image / file path?
2. Does it need an embedded dropdown panel (list, calendar, color palette, image gallery, custom UI), or a calculator popup, or a button to invoke an external dialog?
3. Does it need a mask (e.g., phone, ZIP code, currency, ISO 8601 date), and which culture should drive separators?
4. Should it be embedded in the Grid/TreeList/Ribbon as a cell editor or used only standalone? If both, the repository item is the canonical reference.
5. Does it need immediate post on change (InplaceModeImmediatePostChanges = DefaultBoolean.True) or wait until focus leaves?
6. Should the text box be visible, read-only, or completely hidden (TextEditStyle.HideTextEditor — turns a ButtonEdit into a button-only control)?

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 the right NuGet package, understand the BaseEdit / BaseControl hierarchy at a glance, choose between standalone vs embedded use, and set the focused/leaving behavior (EnterMoveNextControl).

Editor Variants (BaseEdit Descendants)

Refer to references/editor-variants.md When you need to: pick the right editor — text (TextEdit, MemoEdit, MemoExEdit), numeric (SpinEdit, CalcEdit), date/time (DateEdit, TimeEdit, TimeSpanEdit, DateTimeOffsetEdit), boolean (CheckEdit, ToggleSwitch), single-choice (ComboBoxEdit, ImageComboBoxEdit, RadioGroup, FontEdit, MRUEdit, PopupGalleryEdit), multi-choice (CheckedComboBoxEdit, TokenEdit), lookup (LookUpEdit, GridLookUpEdit, SearchLookUpEdit, TreeListLookUpEdit), color (ColorEdit, ColorPickEdit), image (PictureEdit, ImageEdit), progress (ProgressBarControl, MarqueeProgressBarControl), slider (TrackBarControl, RangeTrackBarControl, ZoomTrackBarControl, RatingControl), hyperlink (HyperLinkEdit), breadcrumb (BreadCrumbEdit), sparkline (SparklineEdit), generic popup (PopupContainerEdit).

Non-BaseEdit Simple Controls

Refer to references/non-baseedit-controls.md When you need to: pick a control that does not edit a value — LabelControl / HyperlinkLabelControl for text display, SimpleButton / DropDownButton / CheckButton for actions, ListBoxControl / ImageListBoxControl / CheckedListBoxControl for selection lists, ProgressPanel for loading overlays, NavigatorBase / DataNavigator / ControlNavigator for record navigation, FilterControl for filter UI, SearchControl for filter-as-you-type over an attached control, CalendarControl, XtraOpenFileDialog/XtraSaveFileDialog/XtraFolderBrowserDialog.

Input Masks

Refer to references/masks.md When you need to: apply a phone/ZIP/currency/ISO-date mask, switch between Numeric / DateTime / DateOnly / TimeOnly / DateTimeOffset / Simple / TimeSpan / RegEx / Simplified RegEx mask types, build custom patterns, use MaskSettings.Configure<MaskSettings.Numeric>(...) fluent API, set UseMaskAsDisplayFormat, handle culture, use [EditMask] / [NumericEditMask] / [DateOnlyEditMask] / [RegExEditMask] attributes on a code-first model, and decide which editors support masks (TextEdit descendants except LookUpEdit/GridLookUpEdit/TreeListLookUpEdit/MemoEdit/MemoExEdit/ImageComboBoxEdit/MRUEdit).

Buttons in Editors

Refer to references/buttons-in-editors.md When you need to: add/customize buttons in ButtonEdit and its many descendants (ComboBoxEdit, LookUpEdit, SpinEdit, BrowsePathEdit, PopupBaseEdit, PopupColorEdit/ColorPickEdit, PopupGalleryEdit, PopupContainerEdit, SearchLookUpEdit, GridLookUpEdit, TreeListLookUpEdit, DateEdit, TimeEdit, CalcEdit, FontEdit, MemoExEdit, MRUEdit, ImageEdit, ColorEdit); pick a ButtonPredefines.Kind (Glyph, Ellipsis, Search, OK, Close, Delete, Clear, Plus, Minus, Up, Down, Right, Left, Combo, DropDown, Redo, Undo, SpinUp, SpinDown, SpinLeft, SpinRight, Separator, …); attach SVG/raster icons via EditorButtonImageOptions; respond to clicks with ButtonClick/ButtonPressed; align (IsLeft), set keyboard shortcuts (Shortcut), captions, tooltips, default button, TextEditStyle.HideTextEditor / DisableTextEditor.

Quick Start

Three editors with EditValue data binding

using DevExpress.XtraEditors;
using DevExpress.XtraEditors.Mask;
 
var name = new TextEdit { Width = 240 };
name.Properties.NullValuePrompt = "Full name";
name.Properties.MaskSettings.Configure<MaskSettings.RegExp>(s => {
    s.MaskExpression = "[A-Z][a-z]+( [A-Z][a-z]+)+";   // First Last with capitalization
    s.IsAutoComplete = true;
});
 
var salary = new SpinEdit { Width = 140 };
salary.Properties.MinValue = 0;
salary.Properties.MaxValue = 1_000_000;
salary.Properties.Increment = 100;
salary.Properties.MaskSettings.Configure<MaskSettings.Numeric>(s => s.MaskExpression = "c0");
 
var birth = new DateEdit { Width = 140 };
birth.Properties.VistaCalendarViewStyle = DevExpress.XtraEditors.VistaCalendarViewStyle.YearView;
birth.Properties.MaskSettings.Configure<MaskSettings.DateTime>(s => s.MaskExpression = "d");
 
employeeBindingSource.DataSource = currentEmployee;
name.DataBindings.Add("EditValue", employeeBindingSource, "FullName");
salary.DataBindings.Add("EditValue", employeeBindingSource, "Salary");
birth.DataBindings.Add("EditValue", employeeBindingSource, "Birthday");

ButtonEdit with two buttons

using DevExpress.XtraEditors;
using DevExpress.XtraEditors.Controls;
 
var path = new ButtonEdit { Width = 360 };
path.Properties.Buttons.Clear();
path.Properties.Buttons.Add(new EditorButton(ButtonPredefines.Ellipsis) { Tag = "browse" });
path.Properties.Buttons.Add(new EditorButton(ButtonPredefines.Clear)    { Tag = "clear"  });
path.ButtonClick += (s, e) => {
    var edit = (ButtonEdit)s;
    if ((string)e.Button.Tag == "browse") {
        using var dlg = new XtraOpenFileDialog();
        if (dlg.ShowDialog() == DialogResult.OK) edit.EditValue = dlg.FileName;
    }
    if (e.Button.Kind == ButtonPredefines.Clear) edit.Clear();
};

Key API Surface