A newer version of this page is available. Switch to the current version.

Editors and Simple Controls

  • 7 minutes to read

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 controls only;
  • Utility components.

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

Demos:

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".

repos

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.

repo-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.

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 object is a repository item for a TextEdit editor, and a RepositoryItemDateEdit stores DateEdit settings.

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

using DevExpress.XtraEditors;

var myToggleSwitch = new ToggleSwitch();
myToggleSwitch.Width = 200;
//access a repository item
var repoItem = myToggleSwitch.Properties;
repoItem.OnText = "Enabled";
repoItem.OffText = "Disabled";
this.Controls.Add(myToggleSwitch);

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

create-item

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

// Use a ToggleSwitch editor for the boolean "Mark" column
RepositoryItemToggleSwitch edit = new RepositoryItemToggleSwitch();
edit.OnText = "Enabled";
edit.OffText = "Disabled";
gridControl.RepositoryItems.Add(edit);
gridView.Columns["Mark"].ColumnEdit = edit;

You can also add repository items to an external repository (the 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.

Editor Value

Textbox-based editors' Text and EditValue properties specify their current value. These properties override the corresponding 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 with default settings returns the same string value for both properties.

VS-watch

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

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

VS-watch2

VS-watch3

VS-watch5

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.

var ri = checkedComboBoxEdit1.Properties;
//parameter #1 - value, parameter #2 - item caption
ri.Items.Add(1, "Integer item");
ri.Items.Add(true, "Boolean item");
ri.Items.Add("Hello", "String item");
ri.Items.Add(Color.Red, "Color item");

checkedComboBoxEdit1.CheckAll();
//Text: "Integer item, Boolean item, String item, Color item" (string)
//EditValue: "1, True, Hello, Color [Red]" (sting)
TIP

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.

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.

bound

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.

bind-single

dateEdit2.DataBindings.Add(new System.Windows.Forms.Binding(
    "EditValue", this.ordersBindingSource1, "OrderDate", true,
    System.Windows.Forms.DataSourceUpdateMode.OnValidation));

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.

sync

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.

lookups

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 with items that correspond to records stored in the "northwindDataSet".

public void FillTokenEditor() {
    foreach (DataRow Row in northwindDataSet1.Products.Rows) {
        TokenEditToken token = new TokenEditToken() {
            Value = Row["ProductID"],
            Description = Row["ProductName"].ToString()
        };
        tokenEdit1.Properties.Tokens.Add(token);
    }
}

Bind to Enumerations

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

token-enum

public enum Day
{
    Sat = 7,
    Sun = 1,
    Mon = 2,
    Tue = 3,
    Wed = 4,
    Thu = 5,
    Fri = 6
};

tokenEdit1.Properties.AddEnum(typeof(Day));

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

public enum Day
{
    [Description("Saturday")]
    Sat = 7,
    [Description("Sunday")]
    Sun = 1,
    //. . .
};

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

bindenum-converter

radioGroup1.Properties.AddEnum<Day>(new Converter<Day, string>(MyConverter));

public static string MyConverter(Day d)
{
    Type dayType = d.GetType();
    Type dayUnderlyingType = Enum.GetUnderlyingType(dayType);
    string result = Convert.ChangeType(d, dayUnderlyingType).ToString() + ". " + d.ToString();
    if (d == Day.Sat || d == Day.Sun) result += " (weekend)";
    return result;
}

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

checkedComboBoxEdit1.Properties.SetFlags(typeof(MultiHue));

[Flags]
public enum MultiHue
{
    None = 0,
    Black = 1,
    Red = 2,
    Green = 4,
    Blue = 8
};

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.

addflags

See Also