<%@ Page language="c#" AutoEventWireup="false" %> SandGrid Documentation

SandGrid User Guide

Editing

Back to Table of Contents

The data in a cell can be edited, regardless of whether there is a GridCell instance providing the data or you are using virtual rows or some other means of obtaining your data. When editing is enabled or started programmatically an editor replaces the contents of the cell, supporting full user interaction until the edit operation is complete. We supply some standard editors with SandGrid and you can also create your own, hosting any Windows Forms control in the cell.

Choosing an Editor

The editor used to edit data in a cell is usually governed by the EditorType property on the parent column. This property is settable at design-time. Alternatively you can respond to the ChooseEditor event on your grid, which gives you a just-in-time chance to specify an editor dynamically.

The default editor used by most columns is GridTextBoxEditor. As its name suggests it is simply a standard textbox into which the formatted data is placed ready for editing. When editing is complete the text is parsed back by the column type and stored by whatever storage medium your data is using. Because formatting and parsing is handled by the column, a textbox editor can be used to edit integer, datetime or any datatype with associated converters.

GridDateTimeEditor is an editor that uses a DateTimePicker as its interface. It is used by default by the GridDateTimeColumn class.

GridComboBoxEditor is an editor that uses a ComboBox as its interface. It is used by default by the GridForeignKeyColumn class, which uses it to display a list of values in a primary key table for selection. This is a very useful editor that can be used to edit pretty much any kind of data where a list of "standard" value is required for picking by the user. We even supply a simple NameValuePair class that can be used with the combo box in order to present a list of names that have underlying values. See further down the page for how to customize the contents of this editor.

GridUpDownEditor is an editor that uses a NumericUpDown as its interface. It is not the default editor for any column type but would be suitable for any numeric column such as GridIntegerColumn or GridDoubleColumn.

Starting an Edit Operation

Whether the user can start an edit operation on a cell themselves depends on the KeyboardEditMode and MouseEditMode properties of your grid. These are both set to None by default.

A keyboard edit operation can be started when the user starts typing, which is how spreadsheet input normally works. Or, it can be started by explicitly pressing F2, the function key normally reserved for starting an edit operation. Alternatively you can specify that an edit operation is started when either of these events occurs.

Mouse editing can be started after a short delay after a single click, like the standard ListView and TreeView controls, or immediately upon a double-click. When a user starts an edit operation using the mouse, the RowEditMode property can be used to specify whether the cell under the mouse cursor or the primary cell is edited.

An edit operation can also be started programmatically by calling the BeginEdit method of the SandGrid class. This method taken a row and a column, and the cell at the intersection of the two is edited. Alternatively there is a BeginEdit method on GridRow and also on GridCell, which are functionally equivalent.

Customising an Editor

The BeforeEdit event is raised in a grid when an editor has been created and initialized with cell content, but just before it is shown. This gives your application an opportunity to customise it or to cancel the edit before it has begun. Event arguments passed to the handler include the row, the column and the editor instance.

An editor instance is always a Windows Forms control that implements IGridCellEditor. The standard editors all derive from Windows Forms controls. For example, if you were using a combo box editor you might use the following code to populate it with values:

private void sandGrid1_BeforeEdit(object sender, GridBeforeEditEventArgs e)
{
	// Obtain the editor being used
	GridComboBoxEditor combo = (GridComboBoxEditor)e.Editor;

	// Since this is a ComboBox editor we support a special method to populate it full of name/value pairs
	NameValuePair[] contents = new NameValuePair[] { new NameValuePair("Apple", 0), new NameValuePair("Orange", 1), new NameValuePair("Banana", 2) };
	combo.Populate(contents);

	// Uncomment the following line to enforce the choice of an item from the list by disabling text input
	//combo.DropDownStyle = ComboBoxStyle.DropDownList;
}

Creating a Custom Editor

You may wish to create your own editor, because none of the standard editors quite fit the bill for your application. This is quite easy to do. Your editor needs to inherit from the Windows Forms control you wish to use for editing, and implement the IGridCellEditor interface. This interface has a number of members, all of which are for communication between the editor and SandGrid about the context of the edit operation, the value being edited and how the editor is presented.

Many of the members of the IGridCellEditor are self-explanatory and the demonstration application should be consulted for an example of how a custom editor can be written. The important points to consider are explained below.

  • Use the InitializeContext method to prepare your editor for display and store the instance of the grid hosting the editor.
  • Your DesiredType property should tell the grid what type of data you are expecting.
  • The EditorValue property is used by the grid to set the value before editing, and to retrieve the value when the edit is complete. It should be able to cope with null values.
  • When data is changed, you MUST set the EditorDirty property on the grid (you stored the grid during InitializeContext) to true. If you don't, the grid will assume no change has been made when the edit operation finishes and the new value will not be stored.

Next: Rendering