System.Windows.Forms.DataGrid Class

Displays ADO.NET data in a scrollable grid. The System.Windows.Forms.DataGridView control replaces and adds functionality to the System.Windows.Forms.DataGrid control; however, the System.Windows.Forms.DataGrid control is retained for both backward compatibility and future use, if you choose.

See Also: DataGrid Members


[System.ComponentModel.ComplexBindingProperties("DataSource", "DataMember")]
[System.ComponentModel.Designer("System.Windows.Forms.Design.DataGridDesigner, System.Design, Version=, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.ComponentModel.Design.IDesigner")]
public class DataGrid : Control, System.ComponentModel.ISupportInitialize, IDataGridEditingService


The System.Windows.Forms.DataGrid displays Web-like links to child tables. You can click on a link to navigate to the child table. When a child table is displayed, a back button appears in the caption that can be clicked to navigate back to the parent table. The data from the parent rows is displayed below the caption and above the column headers. You can hide the parent row information by clicking the button to the right of the back button.

To display a table in the System.Windows.Forms.DataGrid at run time, use the DataGrid.SetDataBinding(object, string) method to set the DataGrid.DataSource and DataGrid.DataMember properties to a valid data source. The following data sources are valid:

For more information about the System.Data.DataSet class, see [<topic://cpconCreatingUsingDataSets>].

You can create a grid that enables users to edit data but prevents them from adding new rows by using a System.Data.DataView as the data source and setting the System.Data.DataView.AllowNew property to false.

Data sources are further managed by System.Windows.Forms.BindingManagerBase objects. For each table in a data source, a System.Windows.Forms.BindingManagerBase can be returned from the form's System.Windows.Forms.BindingContext. For example, you can determine the number of rows contained by a data source by returning the associated System.Windows.Forms.BindingManagerBase object's BindingManagerBase.Count property.

To validate data, use the underlying objects that represent data and their events. For example, if the data comes from a System.Data.DataTable in a System.Data.DataSet, use the System.Data.DataTable.ColumnChanging and System.Data.DataTable.RowChanging events.


Because the number of columns can be customized (by adding or deleting members of the System.Windows.Forms.GridColumnStylesCollection) and the rows can be sorted by column, the DataGridCell.RowNumber and DataGridCell.ColumnNumber property values cannot be guaranteed to correspond to System.Data.DataRow and System.Data.DataColumn indexes in a System.Data.DataTable. Therefore you should avoid using those properties in the Control.Validating event to validate data.

To determine which cell is selected, use the DataGrid.CurrentCell property. Change the value of any cell by using the DataGrid.Item(int, int) property, which can take either the row and column indexes of the cell, or a single System.Windows.Forms.DataGridCell. Monitor the DataGrid.CurrentCellChanged event to detect when the user selects another cell.

To determine which part of the control the user clicked, use the DataGrid.HitTest(int, int) method in the Control.MouseDown event. The DataGrid.HitTest(int, int) method returns a System.Windows.Forms.DataGrid.HitTestInfo object, which contains the row and column of a clicked area.

To manage the appearance of the control at run time, several properties for setting the color and caption attributes are available, including the DataGrid.CaptionForeColor, DataGrid.CaptionBackColor, DataGrid.CaptionFont, and so on.

The appearance of the displayed grid (or grids) can be further modified by creating System.Windows.Forms.DataGridTableStyle objects and adding them to the System.Windows.Forms.GridTableStylesCollection, which is accessed through the DataGrid.TableStyles property. For example, if the DataGrid.DataSource is set to a System.Data.DataSet containing three System.Data.DataTable objects, you can add three System.Windows.Forms.DataGridTableStyle objects to the collection, one for each table. To synchronize each System.Windows.Forms.DataGridTableStyle object with a System.Data.DataTable, set the DataGridTableStyle.MappingName of the System.Windows.Forms.DataGridTableStyle to the System.Data.DataTable.TableName of the System.Data.DataTable. For more information about binding to an array of objects, see the DataGridTableStyle.MappingName property.

To create a customized view of a table, create an instance of a System.Windows.Forms.DataGridTextBoxColumn or System.Windows.Forms.DataGridBoolColumn class and add the object to the System.Windows.Forms.GridTableStylesCollection accessed through the DataGrid.TableStyles property. Both classes inherit from System.Windows.Forms.DataGridColumnStyle. For each column style, set the DataGridColumnStyle.MappingName to the System.Data.DataColumn.ColumnName of a column that you want to show in the grid. To hide a column, set its DataGridColumnStyle.MappingName to something other than a valid System.Data.DataColumn.ColumnName.

To format the text of a column, set the DataGridTextBoxColumn.Format property of the System.Windows.Forms.DataGridTextBoxColumn to one of the values found in Formatting Types and Custom DateTime Format Strings.

To bind the System.Windows.Forms.DataGrid to a strongly typed array of objects, the object type must contain public properties. To create a System.Windows.Forms.DataGridTableStyle that displays the array, set the DataGridTableStyle.MappingName property to typename[] where typename is replaced by the name of the object type. Also note that the DataGridTableStyle.MappingName property is case-sensitive; the type name must be matched exactly. See the DataGridTableStyle.MappingName property for an example.

You can also bind the System.Windows.Forms.DataGrid to an ArrayList. A feature of the ArrayList is that it can contain objects of multiple types, but the System.Windows.Forms.DataGrid can only bind to such a list when all items in the list are of the same type as the first item. This means that all objects must either be of the same type, or they must inherit from the same class as the first item in the list. For example, if the first item in a list is a System.Windows.Forms.Control, the second item could be a System.Windows.Forms.TextBox (which inherits from System.Windows.Forms.Control). If, on the other hand, the first item is a System.Windows.Forms.TextBox, the second object cannot be a System.Windows.Forms.Control. Further, the ArrayList must have items in it when it is bound. An empty ArrayList will result in an empty grid. In addition, the objects in the ArrayList must contain public properties. When binding to an ArrayList, set the DataGridTableStyle.MappingName of the System.Windows.Forms.DataGridTableStyle to "ArrayList" (the type name).

For each System.Windows.Forms.DataGridTableStyle, you can set color and caption attributes that override the settings for the System.Windows.Forms.DataGrid control. However, if those properties are not set, the settings for the control are used by default. The following properties can be overridden by System.Windows.Forms.DataGridTableStyle properties:

To customize the appearance of individual columns, add System.Windows.Forms.DataGridColumnStyle objects to the System.Windows.Forms.GridColumnStylesCollection, which is accessed through the DataGridTableStyle.GridColumnStyles property of each System.Windows.Forms.DataGridTableStyle. To synchronize each System.Windows.Forms.DataGridColumnStyle with a System.Data.DataColumn in the System.Data.DataTable, set the DataGridColumnStyle.MappingName to the System.Data.DataColumn.ColumnName of a System.Data.DataColumn. When constructing a System.Windows.Forms.DataGridColumnStyle, you can also set a formatting string that specifies how the column displays data. For example, you can specify that the column use a short-date format to display dates contained in the table.


Always create System.Windows.Forms.DataGridColumnStyle objects and add them to the System.Windows.Forms.GridColumnStylesCollection before adding System.Windows.Forms.DataGridTableStyle objects to the System.Windows.Forms.GridTableStylesCollection. When you add an empty System.Windows.Forms.DataGridTableStyle with a valid DataGridTableStyle.MappingName value to the collection, System.Windows.Forms.DataGridColumnStyle objects are automatically generated for you. Consequently, an exception will be thrown if you try to add new System.Windows.Forms.DataGridColumnStyle objects with duplicate DataGridTableStyle.MappingName values to the System.Windows.Forms.GridColumnStylesCollection.


The System.Windows.Forms.DataGridView control replaces and adds functionality to the System.Windows.Forms.DataGrid control; however, the System.Windows.Forms.DataGrid control is retained for both backward compatibility and future use, if you choose. For more information, see Differences Between the Windows Forms DataGridView and DataGrid Controls.


Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in System.Windows.Forms.dll)
Assembly Versions: 1.0.5000.0,