[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications, and Dialogs
  [Collapse]Editors and Simple Controls
    Included Controls and Components
   [Expand]Common Editor Features and Concepts
   [Expand]Lookup Editors
    Popup Container Editor
   [Expand]Token Edit Control
   [Expand]Breadcrumb Edit Control
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
    Templated ListBox Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Gantt Control
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Editors and Simple Controls

DevExpress Editors suite includes three types of controls:

  • Editors that can be used in stand-alone mode and embedded in data-aware controls' cells (for example, see the Cell Values, Editors, and Validation Data Grid help article);
  • Editors that can be used as stand-alone control only;
  • Utility components.

See the Controls and Components included in XtraEditors Suite article for a complete list of included controls and components.


Expanded Editor Architecture: Repositories and Repository Items

Any DevExpress editor that can be embedded into composite controls (Data Grid, Ribbon, etc.) stores its behavior settings, content settings, and event handlers in an object called a "repository item".

You can "see" a repository item if you drop an editor onto a form and inspect its settings in Visual Studio. All settings in the "Properties" group are owned by a repository item.

Composite controls like Data Grid store these repository items instead of real editors. When a user needs to edit data, the host control dynamically creates an editor from a repository item, and destroys this editor when it is no longer needed. This design improves application performance and reduces the resource consumption rate.

Expanded Create and Access Repository Items

A repository item is an object of a class whose name starts with "RepositoryItem", followed by the related editor class name. For instance, a RepositoryItemTextEdit (see RepositoryItemTextEdit) object is a repository item for a TextEdit (see TextEdit) editor, and a RepositoryItemDateEdit (see RepositoryItemDateEdit) stores DateEdit (see DateEdit) settings.

To access a repository item, use the editor's "Properties" setting.

To embed editors in data-aware controls, use these controls' designers...

... or create repository items in code, add them to a data-aware control's RepositoryItems collection, and assign them to columns or individual cells.

You can also add repository items to an external repository (the PersistentRepository (see PersistentRepository) class object) instead of the internal storage of individual controls. This allows you to share editors across all controls that are bound to this storage.

Expanded Editor Value

Textbox-based editors' Text and EditValue properties specify their current value. These properties override the corresponding BaseEdit (see BaseEdit) virtual properties.

  • BaseEdit.EditValue - returns the object that is the actual editor value, stored internally.
  • BaseEdit.Text - the string representation of the EditValue visible to users.

A TextEdit (see TextEdit) with default settings returns the same string value for both properties.

However, in the majority of cases the Text differs from the EditValue.

  • The editor stores non-string values. For example, a SpinEdit (see SpinEdit).

Expanded EditValue in Multi-Item Editors

If an editor has multiple child items (radio buttons in a RadioGroup, checkbox items in a CheckedComboBoxEdit, etc.), each item has a unique value. When a user checks an item, its value is assigned to the editor's EditValue (or added to it if the editor supports multiple checked items).

In the code sample below, the editor's EditValue is a string that contains comma-separated values of every child item.


A CheckedComboBoxEdit can also keep checked items' values as a List object, assigned to the EditValue. To do this, change the RepositoryItemCheckedComboBoxEdit.EditValueType property to List.

Expanded EditValue in Data-Bound Editors

EditValue and Text property values of data-bound editors (lookups) depend on what data field you bind to the following properties:

  • ValueMember - gets or sets a data field whose cell value is assigned to the EditValue property.
  • DisplayMember - a data field whose cell value is assigned to the Text property.

Expanded Bind Editors to Data

Single-Value Editors

Single-value editors (TextEdit, ButtonEdit, CheckEdit, etc.) can be bound to the current data source record. To do that, expand the DataBindings section in the Visual Studio "Properties" window, click the ellipsis button in the "Advanced" row, and bind a data field to the EditValue property.

Single-value editors display values from the current source record only. To display a value from a different row, use a control or a component bound to the same data source that can traverse source records. In the figure below, editors display values of a data source record when a user selects a corresponding Data Grid row.

Lookups and other Bindable Multi-Value Editors

Editors with the DataSource property (LookUpEdit, GridLookUpEdit, SearchLookUpEdit, TreeListLookUpEdit, BaseListBoxControl descendants) can retrieve values from a data source.

See the Data Binding Common Concepts documentation section for more information on how to bind to different data source types.

Multi-Value Editors without the DataSource Property

Editors in this group (ComboBoxEdit, BreadCrumbEdit, TokenEdit, ColorEdit, etc.) cannot be bound to a source directly. Instead, process data source records and initialize new editor items.

The example below illustrates how to fill a TokenEdit (see TokenEdit) with items that correspond to records stored in the "northwindDataSet".

Bind to Enumerations

If an editor's repository item provides the AddEnum and AddEnum<T> methods, you can populate this editor with enumeration values.

You can change item captions with the System.ComponentModel.Description attribute...

...or with custom converters assigned as parameters to typed AddEnum methods.

The CheckedComboBoxEdit editor also provides the RepositoryItemCheckedComboBoxEdit.SetFlags method that supports bit-wise (flag) enumerators.

The following figure illustrates the result. Note that the zero-value flag ("None") is not present in the drop-down menu but is selected when all other items are unchecked.

Expanded See Also

Is this topic helpful?​​​​​​​