True DBGrid for WinForms provides many features for customizing and controlling the in-cell editing. The grid's default editing behavior depends on the setting of the MarqueeStyle property. If the floating editor marquee style is used, the editing behavior differs from that of other marquee styles. The following sections summarize True DBGrid's editing behavior and state any exceptions that arise when using the floating editor.

Initiating Cell Editing

A cell is either in display or edit mode. The EditActive property sets and returns the desired mode. Place the current cell in edit mode by setting EditActive to True, or end editing by setting it to False. The user may enter edit mode by clicking once on the current cell or by pressing the F2 key. A blinking text cursor (caret) will appear in the cell—at the beginning of the text when the cell is clicked and at the end when the F2 key is used. The BeforeColEdit event will be triggered when the cell enters edit mode. The EditActive property is True when the cell is in edit mode.

Floating Editor Differences: A blinking caret already exists at the beginning of the cell highlight even when in display mode. To enter edit mode, the user can click on any character location within the cell text to specify the text insertion point. The BeforeColEdit event is not triggered and the EditActive property is False until the user has made changes to the cell text.

Color and WordWrap

In edit mode, the cell color is determined by the ForeColor and BackColor properties of the EditorStyle style object. The text being edited will wordwrap, regardless of the setting of the column style's WrapText property. If the text is too big to fit into the cell, a built-in drop-down edit control will automatically appear. For more information, see Working with Text.

Floating Editor Differences: In edit mode, the text highlight disappears, and the cell color is the same as the normal cell color. The text being edited is wrapped only if the column style's WrapText property is True. The built-in drop-down edit control is not available.

Determining Modification Status

While editing is in progress, inspect the DataChanged property of the grid to determine whether the user has made any changes to the current row.

Set the grid's DataChanged property to False to exit editing, discard all changes to the current row, and refresh the current row display from the data source.

The icon in the record selector column of the current row reflects the status of the grid's DataChanged property. If DataChanged is False, a triangle-shaped arrow will be shown in the record selector column. If DataChanged is True, a pencil icon will appear instead.

Determining Cell Contents

While editing is in progress, the column's Text and Value properties contain the text the user currently sees in the modified row. Whenever the user presses a key, the Change event fires to notify the application that the user has just modified the current cell. However, the Change event does not mean the user is finished with the process, only that a single change has been made and the grid is still in edit mode.

The Change event does not fire when the grid is not in edit mode, such as when the contents of a cell are changed through code or when the user clicks a cell to cycle through ValueItem objects.

Terminating Cell Editing

The user completes the editing process by performing any of the following:

• Pressing the ENTER key.
• Pressing the ESC key.
• Moving to another cell with the arrow keys, the TAB key, or the mouse.
• Setting focus to another control on the form.

Handling Editing Events

The following sections describe the default editing behavior of True DBGrid for WinForms can be altered by responding to its events.

Standard Keystroke Events

True DBGrid for WinForms supports the standard keystroke events contained in the .NET environment:

The KeyDown and KeyUp events trap all keys, including function keys, ALT and SHIFT keys, and numeric keypad keys. The KeyPress event only traps letters and numbers, punctuation marks and symbols, and editing keys such as TAB, ENTER, and BACKSPACE.

Use these events to restrict and modify user input as you would be done for any other intrinsic .NET control.

For more information on these or any other native .NET events see MSDN or .NET help.

Column Editing Events

True DBGrid for WinForms provides full control over the cell editing process with the following events, listed in the order in which they occur during a successful editing attempt:

Use the BeforeColEdit event to control the editability of cells on a per-cell basis, or to translate the initial keystroke into a default value.

The ColEdit event signals that the current cell has entered edit mode; the AfterColEdit event signals that edit mode was terminated. Use these two events to provide additional feedback while editing is in progress:

private void c1TrueDBGrid1_ColEdit(object sender, ColEventArgs e)
        {
            TextBoxBase tb = c1TrueDBGrid1.Editor as TextBoxBase;
            if (tb != null)
            {
                c1SpellChecker1.SetSpellChecking(tb, true);
                if (c1SpellChecker1.CheckText(tb.Text).Count > 0)
                {
                    allowCommit = false;
                    errorProvider1.SetError(c1TrueDBGrid1, "There is a spelling error.  Please correct the spelling error before moving on.");
                }
                else
                {
                    allowCommit = true;
                    errorProvider1.Clear();
                }
            }
        }

Changing Cell Contents with a Single Keystroke

You can use the BeforeColEdit event to customize the editing behavior of True DBGrid for WinForms controls. BeforeColEdit is fired before any other editing events occur, which provides the opportunity to do virtually anything desired before editing begins. For example, cancel the edit request and override the built-in text editor with your own drop-down list box.

A True DBGrid for WinForms control enters edit mode in one of four ways:

• If the user clicks on the current cell with the mouse, editing begins with the current cell contents.
• If the user presses the F2 key, editing also begins using the current cell contents.
• If the user begins typing, the typed character replaces the contents of the cell and editing begins.
• You can set the EditActive property in your code to force editing to begin.

The BeforeColEdit event fires in the first three cases, but not in the last case, since True DBGrid for WinForms assumes you will never want to cancel a request made from code.

To differentiate a user's edit request based upon whether he or she used the mouse or the keyboard to start editing, set BeforeColEdit to KeyChar, which will be zero if the user clicked on the cell with the mouse, and will be an ASCII character if the user typed a character to begin editing.

When BeforeColEdit is fired, the ASCII character has not yet been placed into the current cell, so if editing in BeforeColEdit is cancelled, the ASCII key is discarded. This leads to an interesting technique.

Assume a Boolean field called Done exists, and its NumberFormat property is set to specify Yes/No as the display format. Further assume that, when the user presses Y or N, the cell contents change immediately instead of entering edit mode.

Note that the event handler terminates when KeyChar is zero, so mouse editing is still permitted.

Working with Text

This section briefly describes the properties related to text editing.

Limiting the Size of Data Entry Fields

Use the DataWidth property of a C1DataColumn object to restrict the number of characters the user can enter. Setting this property to zero imposes no limits.

Providing a Drop-Down Edit Control for Long Fields

Whenever the user attempts to edit cell text that is too big to fit within the cell, the grid will automatically activate a multiple-line drop-down text editor. While editing, text in the drop-down edit control will be wrapped regardless of the setting of the column style's WrapText property. The drop-down text editor can be turned off and editing can be forced to occur within cell boundaries by setting the grid's EditDropDown property to False (the default is True). The drop-down text editor is not available if the grid's MarqueeStyle property is set to MarqueeEnum.FloatingEditor.

The following code uses the grid's built-in column button feature to activate the drop-down edit control to modify the cell data in the Comments column:

private void Form1_Load(System.object sender, System.EventArgs e)
{
         this.c1TrueDBGrid1.MarqueeStyle = MarqueeEnum.SolidCellBorder;
         this.c1TrueDBGrid1.Splits[0].DisplayColumns["OrderID"].Button = true;
         // Redundant since default = true.
         this.c1TrueDBGrid1.EditDropDown = true;
}
 
private void C1TrueDBGrid1_ButtonClick(object sender, C1.Win.C1TrueDBGrid.ColEventArgs e)
{
    // Place the cell into edit mode.
    this.c1TrueDBGrid1.EditActive = true;
}

If the current cell is in the Comments column, initiate editing either by clicking on the current cell or by clicking the built-in button.

Selecting and Replacing Text

True DBGrid for WinForms supports the standard text selection properties found in many TextBox type controls: