In-place Editors

  • 6 minutes to read

The GridControl allows you to edit cell values using in-place data editors:

TIP

Demo: Cell Editors

Requires installation of WPF Subscription. Download

Availability

Data editing is allowed if the DataViewBase.AllowEditing property is set to true and the DataViewBase.NavigationStyle property is set to GridViewNavigationStyle.Cell.

Individual columns provide the ColumnBase.AllowEditing property. The property's default value is Default - the View controls the column's behavior. Set this property to true or false to override the default behavior. For example, you can set the column's ColumnBase.AllowEditing property to false to prevent an end user from changing its values.

If the column's ColumnBase.ReadOnly property is set to true:

  • End users cannot modify the column's cell values (they can invoke cell editors, select and copy their values).
  • You can change cell values in code using the GridControl.SetCellValue method.

If the View is in edit mode, the DataViewBase.ActiveEditor property returns the edited cell's editor and the DataViewBase.IsEditing property returns true.

Assign Editors to Columns

The GridControl automatically creates an editor for a column based on its value type. For example, if a column is bound to a DateTime field, the GridControl creates the DateEdit for it. If a column is bound to a numeric field, the SpinEdit is used. Otherwise, the TextEdit is used.

Each editor has a helper class responsible for the editor's functionality.

Use the ColumnBase.EditSettings property to specify an in-place editor for a column. The following code sample shows how to assign a spin editor to the UnitPrice column:

<dxg:GridColumn x:Name="colUnitPrice" FieldName="UnitPrice">
    <dxg:GridColumn.EditSettings>
        <dxe:SpinEditSettings MaxValue="999" MinValue="1" DisplayFormat="c2"/>
    </dxg:GridColumn.EditSettings>
</dxg:GridColumn>

When the same editor is used in multiple locations, the GridControl uses the helper class to paint its cells. The actual editors are only created when end users start to edit a cell and are automatically destroyed when editing is completed. This improves the application's performance.

To obtain a column's actual editor, use the ColumnBase.ActualEditSettings property. This property returns the editor's helper class that is responsible for the editor's functionality and behavior.

TIP

The GridControl supports the Smart Columns Generation feature. When this feature is enabled, the GridControl automatically creates the layout and configures data editors for all generated columns according to data types, Data Annotations and DevExpress Fluent API attributes specified in the underlying data source.

Cell Templates

You can use the ColumnBase.CellTemplate / DataViewBase.CellTemplate to define data cells' presentation. These templates allow you to:

  • Specify settings that an editor's helper class does not have.
  • Provide different settings to editors in the same column.
  • Create a custom editor.
<dxg:GridControl AutoGenerateColumns="AddNew" EnableSmartColumnsGeneration="True" ItemsSource="{Binding Items}">
    <dxg:GridColumn FieldName="Country"/>
    <dxg:GridColumn FieldName="City">
        <dxg:GridColumn.CellTemplate>
            <DataTemplate>
                <dxe:ComboBoxEdit x:Name="PART_Editor" ItemsSource="{Binding RowData.Row.Cities}"/>
            </DataTemplate>
        </dxg:GridColumn.CellTemplate>
    </dxg:GridColumn>
    <dxg:GridControl.View>
        <dxg:TableView/>
    </dxg:GridControl.View>
</dxg:GridControl> 

Display and Edit Templates

In-place editors are used to present and edit data. You can use separate in-place editors for both tasks. Each column provides two templates that allow you to define custom editors that display (when the grid is in browse mode) and/or edit (when the grid is in edit mode) column values:

Template Description
ColumnBase.CellDisplayTemplate / DataViewBase.CellDisplayTemplate Defines a template that displays column values.
ColumnBase.CellEditTemplate / DataViewBase.CellEditTemplate Defines a template that represents an editor used to edit cell values.

Process End User Actions

The GridControl provides the following events to process end user actions:

Event Description
DataViewBase.GetIsEditorActivationAction Allows you to specify whether an action (key down, text input, or mouse left button click) activates the focused editor.
DataViewBase.ProcessEditorActivationAction Allows you to make the focused editor process an activation action.
DataViewBase.GetActiveEditorNeedsKey Allows you to specify whether an active editor responds to keys an end user presses.

Show and Hide Editors in UI

An end user can switch the GridControl to edit mode in the following ways:

  • Click the required cell
  • Press Enter
  • Press F2
  • Start typing.

This activates the focused cell's in-place editor to allow an end user to modify the value.

To save the changes and close the editor, an end user should press Enter or move the cell focus to another cell. Pressing Esc closes the editor and discards the changes.

Show and Hide Editors in Code

Show Editors

To invoke the cell's editor in code, focus the cell and call the DataViewBase.ShowEditor method. Refer to Focusing for information on how to move cell and row focus.

The GridViewBase.ShowingEditor / TreeListView.ShowingEditor events are raised before the focused cell's editor is activated. These events allow you to cancel the action and prevent its value from being edited. After the editor has been shown, the GridControl raises the GridViewBase.ShownEditor / TreeListView.ShownEditor event.

Hide Editors

The GridControl provides two methods to hide the active editor:

Method Description
DataViewBase.CloseEditor Hides the active editor and saves the changes.
DataViewBase.HideEditor Hides the active editor and discards the changes.

To save changes to a data source without closing the active editor, use the DataViewBase.PostEditor method.

Before the active editor's new value is posted to a data source, it is validated. If a new value is valid, it is posted to a data source and the editor can be closed. Otherwise, if a new value is invalid, the active editor cannot be closed, and cell focus cannot be moved to another cell until its value is correct. Refer to the Cell Validation topic for more information.

After the editor has been closed, the GridControl raises the GridViewBase.HiddenEditor / TreeListView.HiddenEditor event.

Immediate Posting

After a cell has been edited, an end user should unfocus the cell to post the cell's value to a data source. You can make the GridControl post values to a data source after an end user changes a cell's value.

NOTE

The GridControl does not support immediate posting if you use Cell Templates.

Approach 1

Set the DataViewBase.EnableImmediatePosting property to true.

Approach 2

Handle the GridViewBase.CellValueChanging event and call the DataViewBase.PostEditor method in the event handler. Use this approach if you need to implement complex logic.

The following code sample posts the Name column's values:

<dxg:TableView CellValueChanging="CellValueChanging" />
void CellValueChanging(object sender, DevExpress.Xpf.Grid.CellValueChangedEventArgs e) {
    if (e.Column.FieldName == "Name")
        e.Source.PostEditor();
}

Edit Entire Row

The GridControl provides an edit mode that allows you to edit an entire row and post changes to the data source. In this mode, the GridControl shows the Update and Cancel buttons for the row that is being edited. Change the row's cell values and then click Update to post chages: