In-place Editors
- 8 minutes to read
The GridControl allows you to edit cell values using in-place data editors:
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.
- BarCodeEditSettings
- CheckEditSettings
- ColorEditSettings
- HyperlinkEditSettings
- ImageEditSettings
- ListBoxEditSettings
- PasswordBoxEditSettings
- RatingEditSettings
- SparklineEditSettings
- TextEditSettings
- CalcEditSettings
- DateEditSettings
- LookUpEditSettingsBase
- MemoEditSettings
- PopupColorEditSettings
- PopupImageEditSettings
- SpinEditSettings
- ToggleSwitchEditSettings
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>
Tip
GitHub Example: How to Assign a ComboBox Editor to a Column
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. |
Tip
GitHub Example: How to Use Custom Editors 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. |
Tip
GitHub Example: How to Specify Navigation in Custom Cell Editors
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.
Tip
GitHub Example: How to Prevent Individual Cells From Being Edited
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:
You cannot navigate away from an edited row unless you click the Update / Cancel button or press Esc twice.
To enable the Edit Entire Row mode, specify the TableView.ShowUpdateRowButtons / TreeListView.ShowUpdateRowButtons property:
When the property value is OnCellEditorOpen, the buttons are shown after you open a cell editor:
When the property value is OnCellValueChange, the buttons are shown after you change a cell value:
Click the Update button to post the edited row’s changes to the data source. Alternatively, you can call the TableView.UpdateRow / TreeListView.UpdateRow method or the TableViewCommands.UpdateRow / TreeListViewCommands.UpdateRow command.
Click the Cancel button to discard the edited row’s changes. Alternatively, you can call the TableView.CancelRowChanges / TreeListView.CancelRowChanges method or the TableViewCommands.CancelRowChanges / TreeListViewCommands.CancelRowChanges command.
Use the TableView.UpdateRowButtonsTemplate / TreeListView.UpdateRowButtonsTemplate property to change the appearance of the Update and Cancel buttons.
To post changes to an underlying data source (database), handle the GridViewBase.ValidateRow event and explicitly save the changes. For example, if you bind the GridControl to the Entity Framework, call the SaveChanges method on the DataContext:
<dxg:TableView ShowUpdateRowButtons="OnCellEditorOpen" ValidateRow="TableView_ValidateRow"/>
void TableView_ValidateRow(object sender, GridRowValidationEventArgs e) {
var issue = (Issue)e.Row;
using(var context = new IssuesContext()) {
var result = context.Issues.SingleOrDefault(b => b.Id == issue.Id);
if(result != null) {
result.Subject = issue.Subject;
result.Priority = issue.Priority;
result.Votes = issue.Votes;
result.Priority = issue.Priority;
context.SaveChanges();
}
}
}
If an underlying data source (database) cannot save changes, the GridControl will allow you to correct the values or click the Cancel button to return the previous values.
Tip
GitHub Example: How to Update Entire Row in the GridControl
Limitations
- The Edit Entire Row mode is available in optimized mode only.
- The Edit Entire Row mode is incompatible with the Edit Form.