DataGridView

WATCH & LEARN0:51 · Animated tutorial

7 scenesPlay, pause, or scrub at your own pace

The DataGridView control provides a customizable table for displaying data. The DataGridView class allows customization of cells, rows, columns, and borders through the use of properties such as DefaultCellStyle, ColumnHeadersDefaultCellStyle, CellBorderStyle, and GridColor.

You can use a DataGridView control to display data with or without an underlying data source. Without specifying a data source, you can create columns and rows that contain data and add them directly to the DataGridView using the Rows and Columns properties. You can also use the Rows collection to access DataGridViewRow objects and the DataGridViewRow.Cells property to read or write cell values directly.

As an alternative to populating the control manually, you can set the DataSource and DataMember properties to bind the DataGridView to a data source and automatically populate it with data.

When working with very large amounts of data, you can set the VirtualMode property to true to display a subset of the available data. Virtual mode requires the implementation of a data cache from which the DataGridView control is populated.

info

For a complete list of properties, methods, and events, see the API documentation.

Features

Append and Fill

Populate the DataGridView without binding it to a data source by using the Append and Fill methods.

AutoSizing

AutoSizeColumnsMode and AutoSizeRowsMode let you configure the control so that column widths and row heights are automatically adjusted either to fill the control or to fit cell contents. Size adjustments occur in fill mode whenever the width of the control changes. In content-based sizing modes, size adjustments occur whenever cell contents change or, if WrapMode is enabled, whenever row heights change. Some content-based sizing modes let you limit the size adjustment to the currently displayed rows in order to increase performance.

To change the sizing mode for an individual column, set its AutoSizeMode property. The default value of this property is NotSet, indicating that the column inherits its behavior and its InheritedAutoSizeMode property value from the control.

warning

Don't confuse the AutoSize property with the rows and columns autosizing. If you set the AutoSize property of the DataGridView to true, it will cause the grid to grow horizontally and/or vertically (depending on the layout settings) to fit all the columns and all the rows.

Data Binding

The DataGridView control supports the standard Windows Forms data binding model, so it can bind to a variety of data sources. Usually, you bind to a BindingSource that manages the interaction with the data source. The BindingSource can be any Windows Forms data source, which gives you great flexibility when choosing or modifying your data's location.

To connect a DataGridView control to data:

1. Implement a method to handle the details of retrieving the data.
2. In the form's Load event handler, bind the DataGridView control to the BindingSource, and call the appropriate method to retrieve the data.

Dynamic Columns

Columns are automatically generated when AutoGenerateColumns is set to true and the DataSource or DataMember properties are set or changed. Columns can also be automatically generated when the AutoGenerateColumns property is changed from false to true. If this property is true and the DataSource changes so there are columns that do not match the columns of the previous DataSource value, data in the unmatched columns is discarded. This property is ignored if the DataSource or DataMember properties are not set.

When AutoGenerateColumns is set to true, the DataGridView control generates one column for each public property of the objects in the data source. If the bound objects implement the ICustomTypeDescriptor interface, the control generates one column for each property returned by the GetProperties method. Each column header will contain the value of the property name the column represents.

Virtual Mode

Virtual mode lets your application manage how the DataGridView retrieves and updates data.

Virtual mode is designed for use with very large stores of data. When the VirtualMode property is true, you create a DataGridView with a set number of rows and columns and then handle the CellValueNeeded event to populate the cells. Virtual mode requires implementation of an underlying data cache to handle the population, editing, and deletion of DataGridView cells based on actions of the user.

tip

Use the DataGridView.DataRead event to build and maintain your server-side cache or data retrieval code that collects the data to feed the CellValueNeeded event.

Advanced

The DataGridView control is probably the largest and most complex control and widget in Wisej.NET. It exposes dozens of events, properties and methods and supports a large set of complex and advanced features.

Composable DataGrid

A common way to extend a DataGridView with a status bar, paging strip, or related controls is to place the grid and those controls inside a UserControl.

This approach, however, "hides" the DataGridView in a UserControl (or another container) and may require a large number of wrapper properties, events and methods to expose the DataGridView features to the code that uses the new custom control.

The Wisej.NET DataGridView can itself act as a container. Add controls directly to it in the designer or in code, and it adjusts its internal layout to accommodate them. This creates a composed DataGridView while keeping the grid's own API directly accessible.

You can do that directly in the container using the composed grid, or you can create a custom control extending the DataGridView and dropping controls in there.

info

Control the layout using Docking and BringToFront or SendToBack. You can also set the ResizableEdges property of the inner controls and implement a simple splitting system where the user can resize the inner controls.

Cell Editors

When the built-in cell editors are not sufficient, or you need to customize the editing of any cell, you can assign a custom editing control to DataGridViewColumn.Editor and Wisej.NET will use that instance of the control to edit the content of the cells in that column.

this.dataGridView.Columns[1].Editor = new MonthCalendar();

danger

Unless the editing control fires the TextChanged event when edited, it's up to your code to handle the CellBeginEdit and CellEndEdit events and update the value of the cell.

Cell Controls

When cell editors, HTML content, or custom painting do not meet your needs, place a control directly in a DataGridView cell. A control can also span multiple cells.

this.dataGridView1.Rows[0][0].Control = new Button { 
  Text = "Click Me",
  Dock = DockStyle.Fill
};
this.dataGridView1.Rows[0][0].Style.RowSpan = 2;
this.dataGridView1.Rows[0][2].Control = new TrackBar
{
 Value = 10,
 Dock = DockStyle.Fill
};
this.dataGridView1.Rows[0][2].Style.ColSpan = 2;

"With great power come great responsibility".

Each embedded control adds browser rendering work and server memory usage. Adding one control per row to a grid with 10,000 rows creates 10,000 controls, so use cell controls selectively for large datasets.

Cell Painting

When you really need to display something too complex for HTML, or you have an existing painting routine in .NET, the DataGridView allows you to paint directly into the cell.

Attach a handler to DataGridView.CellPaint and enable user painting on the cell by setting the UserPaint property to true:

this.dataGridView1.RowCount = 10;
this.dataGridView1.Rows[0][0].UserPaint = true;

private void dataGridView1_CellPaint(object sender, DataGridViewCellPaintEventArgs e)
{
  var rect = e.ClipRectangle;
  rect.Inflate(-1, -1);
  e.Graphics.DrawArc(Pens.Red, rect, 0, 360);
}

Cell HTML

Setting the AllowHtml property of a DataGridViewColumn or a specific DataGridViewCell allows the cell to display HTML text in the browser. This feature allows you to display many kinds of content in a cell, including images, progress bars, charts, and multiple data values.

this.dataGrid.SetValue(
    0, 0, 
    "<img src='img1.png'/><img src='img2.png'/>Two Icons");

Another way to display custom HTML in a cell without having to store HTML in the cell value is to use the CellFormatting event. It allows you to "render" the display of the cell:

private void dataGridView_CellFormatting(
    object sender, DataGridViewCellFormattingEventArgs e)
{
    var level = (int)e.Value;
    e.FormattingApplied = true;
    e.Value = $"<div style='background-color:green;width:{level/100}px;height:20px'/>";
}

info

You can detect clicks inside a particular element inside a cell by setting the "role" attribute of the HTML element and checking the e.Role string that comes with the cell click events.

JavaScript Widget

Item	Description
Class name	wisej.web.DataGrid
Theme appearance	"table" is the entire widget. All components of the grid use the "table-[name]" appearance key. See Themes.
Child components	See JavaScript.
ToolContainer state	"datagrid", see Embedded Tools.
Source code	https://github.com/iceteagroup/wisej-js