Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Collapse]Data Grid
   [Expand]Getting Started
   [Expand]Binding to Data
   [Expand]Grid View
   [Expand]View Technology
   [Expand]Grouping
   [Expand]Sorting
   [Expand]Summaries
   [Collapse]Data Editing
    [Collapse]Edit Form
      Custom Edit Form
    [Expand]Editing via Code
    [Expand]In-place Editors
    [Expand]Input Validation
    [Expand]New Item Row
     Tutorial: Add or Remove Rows
     Tutorial: Data Input Validation
   [Expand]Filtering and Locating Rows
   [Expand]Focus and Selection Handling
   [Expand]Processing Rows
   [Expand]Formatting Cell Values
   [Expand]Master-Detail Relationships
   [Expand]Asynchronous Image Load
   [Expand]Export and Printing
   [Expand]Appearance and Conditional Formatting
   [Expand]Batch Modifications
   [Expand]Hit Information
   [Expand]Hints
   [Expand]Popup Menus
   [Expand]Saving and Restoring Layouts
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]Examples
   [Expand]End-User Capabilities
    Included Components
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Edit Form

The Edit Form provides an alternative to in-place editing within grid cells (see In-place Editors Overview). It is an in-line panel (UserControl) or modal form that contains standalone editors for editing grid data.

This topic consists of the following sections.

Expanded Online Video

Expanded Overview

In the GridView and its descendants, you can choose from a number of data edit modes. In addition to the most commonly used In-place edit mode (see the In-place Editors Overview topic for details), data can be edited via an Edit Form, which provides standalone editors for editing grid data. An Edit Form can be displayed as a separate modal window or as an in-line panel embedded between grid rows in the grid. In the following image, an Edit Form is shown as a modal window.

Expanded Enable EditForm

To switch from the default in-place edit mode to the Edit Form, use the GridOptionsBehavior.EditingMode property of the GridEditingMode type. You can assign a value to this property at design time.

You can also specify the edit mode in code.

To use an EditForm, set the GridOptionsBehavior.EditingMode property to one of the following modes: Edit Form, EditFormInplace or EditFormInplaceHideCurrentRow.

  • Edit Form mode – Row data is edited in a separate modal Edit Form.

    An end-user can make changes to a record via the Edit Form, and then save or discard the changes. In this mode, access to an application window is blocked while a modal Edit Form window is displayed.

  • EditFormInplace mode – Row data is edited in an in-line Edit Form that appears immediately below the selected row.

    In EditFormInplace mode, functionality such as filtering, grouping and sorting is blocked while the Edit Form is open. This mode does not block access to the application window, and an end-user can, for example, scroll the grid or move focus to another grid row.

  • EditFormInplaceHideCurrentRow mode – Row data is edited in an in-line Edit Form while the selected row is hidden.

    Like EditFormInplace mode, in EditFormInplaceHideCurrentRow mode, the filtering, grouping and sorting functionalities are disabled while an Edit Form is open.

Note

Detail Views do not support an inline Edit Form. Data in these Views can only be edited in-place, or using a popup Edit Form.

Expanded EditForm Settings

The GridView.OptionsEditForm property provides general Edit Form settings. Grid columns are represented in an Edit Form by the appropriate editors. The GridColumn.OptionsEditForm property provides the settings of the editor in an Edit Form that corresponds to the current grid column.

An end-user can open an Edit Form by double clicking on a grid row, or by pressing the Enter or F2 key. To disable these features, use the GridOptionsEditForm.ShowOnDoubleClick, GridOptionsEditForm.ShowOnEnterKey and GridOptionsEditForm.ShowOnF2Key properties, respectively.

When an Edit Form is displayed in-line, an end-user can move focus to another grid row. If an Edit Form does not contain changes, it closes without displaying any confirmation dialog. If an Edit Form contains unsaved changes, a confirmation dialog is displayed. To disable the confirmation dialog, or to specify the type of confirmation, use the GridOptionsEditForm.ActionOnModifiedRowChange property of the EditFormModifiedAction type. The EditFormModifiedAction enumeration provides the following modes.

  • Save and Default - A confirmation dialog asking the user to save or discard the changes, or cancel the action:

  • Cancel - A confirmation dialog asking to discard the changes:

  • Nothing - No confirmation is requested and it is not possible to move focus to another grid row.

To save changes, an end-user can click the built-in Update button or press the Ctrl+Enter key combination. To discard the changes, it is possible to use the built-in Cancel button or the Escape key. To show or hide the Update and Cancel buttons in an Edit Form, utilize the GridOptionsEditForm.ShowUpdateCancelPanel property.

An Edit Form provides the GridOptionsEditForm.BindingMode property, which specifies the mode in which data from an Edit Form is passed back to the grid. The EditFormBindingMode enumeration provides you with the following modes.

  • Direct and Default - An edited field value in an Edit Form is passed back to the grid at the moment an end-user moves focus to another field in an Edit Form.
  • Cached - Edited field values in an Edit Form are collected in a proxy and passed back to the grid simultaneously when an end-user saves changes.

Expanded Popup EditForm Settings

When displayed as a modal window, the width of an Edit Form can be specified by the GridOptionsEditForm.PopupEditFormWidth property. The caption of an Edit Form displayed as a modal window can be specified by the GridOptionsEditForm.FormCaptionFormat property. To display a data record field value within the Edit Form window caption, place the field name in braces.

The following image shows an Edit Form displayed as a modal window with a custom caption.

Expanded EditForm Layout

All layout settings mentioned in this sub-section are in effect for automatically generated EditForms. If you use a custom Edit Form (see the Default and Custom EditForms section), these settings are ignored.

The layout of editors in an Edit Form is created automatically, based on the options provided by the GridView.OptionsEditForm and GridColumn.OptionsEditForm properties.

At design time, the Edit Form's layout can be customized via the EditForm Designer page of the Grid Designer. The EditForm Designer provides access to related settings and shows a preview of the customizations made.

The Edit Form space is divided into layout columns and rows. The total number of layout columns in an Edit Form is specified by the GridOptionsEditForm.EditFormColumnCount property. It is set to 3 by default.

The following images show an Edit Form when the GridOptionsEditForm.EditFormColumnCount property is set to 2 and 4, respectively.

Each grid column is represented in an Edit Form by an appropriate editor and caption. If the OptionsColumnEditForm.UseEditorColRowSpan property is set to true, each editor spans a default number of layout columns and rows, and these values depend on the editor type. With the exception of the MemoEdit and PictureEdit controls, all editors span one layout column and one layout row. By default, the MemoEdit spans three layout rows vertically and all layout columns horizontally. The PictureEdit spans two layout columns and three layout rows by default.

Set the OptionsColumnEditForm.UseEditorColRowSpan property to false if you wish to use custom column and row spans. Then, to set custom column and row spans, use the OptionsColumnEditForm.ColumnSpan and OptionsColumnEditForm.RowSpan properties.

In the following image, the "Product" editor spans two layout columns in an Edit Form, whereas other editors span one layout column.

You can start a new row of editors in an Edit Form with a specific editor. For this purpose, set the OptionsColumnEditForm.StartNewRow property of the corresponding grid column to true.

In the following image, an editor that represents the "Unit Price" grid column starts a new row.

The OptionsColumnEditForm.VisibleIndex property allows you to arrange editors in an Edit Form. By default, the OptionsColumnEditForm.VisibleIndex property of all editors in an Edit Form is set to 0. In this case, the editors are arranged in an Edit Form according to the indexes of the corresponding grid columns in the ColumnView.Columns collection. If you wish to arrange editors in a different way, utilize the OptionsColumnEditForm.VisibleIndex property.

Note that editors with negative OptionsColumnEditForm.VisibleIndex property values are still visible in an Edit Form (they are displayed before editors that have greater visible indexes). To hide an editor, set the OptionsColumnEditForm.Visible property of the corresponding grid column to False.

By default, an editor's caption matches the corresponding grid column's caption. You can override the editor's caption in an Edit Form via the OptionsColumnEditForm.Caption property. It is also possible to specify a caption location via the OptionsColumnEditForm.CaptionLocation property. The EditFormColumnCaptionLocation enumeration provides the following values.

  • Default and Near - A caption is located on the left side of an editor in a left-to-right layout. In a right-to-left layout, the near position is right.
  • Top - A caption is located above the editor.
  • None - A caption is not displayed.

If you use the Top value, ensure that an editor spans a minimum of two layout rows within an Edit Form.

Expanded Default and Custom EditForms

The Grid Control can generate the layout of editors in an Edit Form automatically, based on the settings provided by the GridView.OptionsEditForm and GridColumn.OptionsEditForm properties. If the default layout does not meet your requirements, you can create a custom Edit Form (UserControl), which arranges editors in a specific manner. The EditFormUserControl is the base class used to create a custom Edit Form. To use this form, assign it to the GridOptionsEditForm.CustomEditFormLayout property.

The following image shows an example of a custom Edit Form:

For an in-depth explanation of the custom Edit Form, see the Custom Edit Form topic.

Expanded Showing and Hiding an EditForm in Code

The GridView provides methods to open and close an Edit Form for the focused row. These methods are in effect if the GridOptionsBehavior.EditingMode property is set to a value that enables data editing via an Edit Form.

Note

If there is insufficient space in the View to display an Edit Form as an in-line panel, it is displayed as a separate modal window.

To get whether or not an Edit Form is open, use the GridView.IsEditFormVisible property.

You can respond to the opening of an Edit Form, and prevent it from being displayed by handling the GridView.EditFormShowing event.

The following example shows how to prohibit an Edit Form from opening in specific rows.

In this example, the GridView.EditFormShowing event is handled and the Allow event parameter is set to false for orders shipped to France.

To close an opened Edit Form, call the GridView.CloseEditForm method. This method saves changes and closes the Edit Form if data is successfully saved. If it is not possible to save data (for instance, if the data is not valid), the GridView.CloseEditForm method returns false, and does not close the Edit Form. To close an Edit Form without saving changes, use the GridView.HideEditForm method.

Expanded Form Editors

Editors in the Edit Form are only initialized once, when the Edit Form is opened for the first time. If you want to replace default editors with custom ones, handle the GridView.CustomRowCellEditForEditing event.

Every time the Edit Form is displayed, the GridView.EditFormPrepared event fires. This event allows you to access all editors displayed within the form and customize them as required.

When the Edit Form is displayed, focus moves to the first editor within the Edit Form. The following example shows how to handle the GridView.EditFormPrepared event to set focus to an editor corresponding to the focused GridColumn.

To check the validity of data entered by end-users within editors, handle the BaseView.ValidatingEditor event.

Expanded See Also

How would you rate this topic?​​​​​​​