Seth Grossman
Visual Studio Team
Microsoft Corporation
December 2002
Summary: Quite a few basic tasks related to formatting the Windows Forms DataGrid control require you to create and implement your own custom column styles. However, once you are familiar with these objects, you will have a lot of power at your disposal. (11 printed pages)
Requirements
The following software is referenced within this whitepaper:
Contents
Synopsis
Background
Column Styles
Basic Techniques
Advanced Scenarios
Conclusion
Synopsis
In this paper, you will:
- Create a class that defines a custom column style for the Windows Forms DataGrid control.
- Implement that class as a column within the DataGrid control.
- Learn about other possible customizations to columns that will enhance the behavior of the DataGrid control.
Background
A number of tasks you may want to accomplish with the Windows Forms DataGrid control are, surprisingly, more difficult than you might expect. Primarily, this is because the Windows Forms DataGrid control is column-based, rather than cell-based. As a result, to accomplish most tasks, you have to work with the columns, not the cells themselves.
One example of a group of tasks that requires working with columns is changing the display properties of the grid (foreground color, background color, data format, and so on). These display properties are all maintained through column formatting.
Column Styles
To format columns, you need to create a column style. A column style is an object that defines what the column looks and behaves like, including such things as color, font, and the presence of controls, such as check boxes. The .NET Framework includes two types of column-style classes by default: the DataGridTextBoxColumn [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwindowsformsdatagridtextboxcolumnclasstopic.asp ] and DataGridBoolColumn [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwindowsformsdatagridboolcolumnclasstopic.asp ] classes. The DataGridTextBoxColumn class exposes very basic "edit box" functionality; users can enter text into it. The DataGridBoolColumn class exposes a column of check boxes within the column to represent Boolean [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystembooleanclasstopic.asp ] values.
Since neither of these column styles enables you to color the cells of the grid, you will have to create your own custom column style.
Basic Techniques
To work with column styles, you need to create a column-style object and then implement the behavior you would like it to display at run time. Specifically, you need to inherit from an existing column style (either the DataGridTextBoxColumn or DataGridBoolColumn) and then override some of its functionality.
After creating the class, you have to tell the grid to use it. Later in the paper, you will find details about how to use the custom column-style class within the grid.
Step I: Creating a Custom ColumnStyle Class
One example of a custom column style would be one that displays a column of text that, when certain criteria have been met (such as a specific value in a cell), the cell's color is set.
The following example illustrates how to implement a column style that colors the cells of a grid when the value displayed in the cell is greater than 1. The code for this class inherits from the .NET Framework's DataGridTextBoxColumn [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwindowsformsdatagridtextboxcolumnclasstopic.asp ] class and overrides the Paint method, so that you can do custom painting of the cell. Note that this class expects the data in the column to be of type Integer.
Public Class ColoredTextBoxColumn
Inherits DataGridTextBoxColumn
Protected Overloads Overrides Sub Paint(ByVal graph As Graphics, _
ByVal rectbounds As Rectangle, ByVal curmngrSrc As _
CurrencyManager, ByVal RowNumber As Integer, ByVal _
ForeColorBrush As Brush, ByVal BackColorBrush As Brush, _
ByVal AlignmentRight As Boolean)
Dim ObjVal As Object
ObjVal = Me.GetColumnValueAtRow(curmngrSrc, RowNumber)
If Not (IsNothing(ObjVal) Or IsDBNull (ObjVal)) Then
Dim cellValue As Integer
cellValue = CType(ObjVal, Integer)
If (cellValue > 1) Then
' Here is where we are going to do
' the actual painting.
' Color the contents of the cell Red
' and the background of the cell Yellow.
BackColorBrush = Brushes.Yellow
ForeColorBrush = Brushes.Red
Else
BackColorBrush = Brushes.White
ForeColorBrush = Brushes.Black
End If
End If
' Call Paint from the base class to
' accomplish the actual drawing.
MyBase.Paint(graph, rectbounds, curmngrSrc, RowNumber, _
BackColorBrush, ForeColorBrush, AlignmentRight)
End Sub
End Class
In the code above, the cell's value is cast to an integer and the cells of the grid have their ForeColor and BackColor set based on some condition; in this case, the condition is "value is greater than 1". The cell's ForeColor and BackColor are painted using brushes from the System.Drawing namespace.
Step II: Programming with Your Custom Column-Style Class
Now that you have a created a custom column-style class, you can implement it within a DataGrid control.
The Windows Forms DataGrid control maintains a collection of table styles. A table style represents the details about how a specific table is drawn by the DataGrid control (the table is specified by the MappingName [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwindowsformsdatagridtablestyleclassmappingnametopic.asp ] property). Each table style contains a collection of column styles. For more information about the role of table styles and how they work, see Formatting the Windows Forms DataGrid Control [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbcon/html/vbtskFormattingtheDataGridAtDesignTime.asp ] .
To make use of your custom column-style class, you first instantiate the new column-style and table-style classes. Then, you add the column style to the table style. Finally, you add the table style to the grid.
Note Adding these instances of the table and column styles to your datagrid control overrides all the existing column definitions.
Once you create a custom column definition and add it to the table, you need to define all the column styles in the grid. In order to do that, create instances of the base column style for each column you want to display and add them to the table style you created as well.
Public Sub AddFormattedColoredColumn()
Dim tsProducts As New DataGridTableStyle
tsProducts.MappingName = "Products"
Dim cstbProdName As New DataGridTextBoxColumn
cstbProdName.MappingName = "ProductName"
cstbProdName.HeaderText = "Product Name"
Dim cscolUnitPrice As New ColoredTextBoxColumn
cscolUnitPrice.MappingName = "UnitPrice"
cscolUnitPrice.HeaderText = "UnitPrice"
tsProducts.GridColumnStyles.Add(cstbProdName)
tsProducts.GridColumnStyles.Add(cscolUnitPrice)
DataGrid1.TableStyles.Add(tsProducts)
End Sub
In the code above, a new table style (tsProducts) and two new column styles (cstbProdName and cscolUnitPrice) are instantiated. The mapping names for all three are set to their respective table and columns. The column styles are added to the table style's collection of column styles; then the table style is added to the DataGrid control's collection of table styles.
Be sure to call the procedure above before the grid is loaded, so that the correct data is displayed by the grid.
Advanced Scenarios
Above is a basic description and implementation of custom column styles, which is intended to give you a general idea of how to manipulate columns and cells within the DataGrid control. At this point, there are a number of options available, if you wish to do more.
Setting Other Cell Properties
You can customize a number of different qualities that the cells of the DataGrid control exhibit. You can set column alignment and column width, and you can format your data for display.
Setting Column Alignment
You can set the alignment of the cell data within columns. The column object itself does not have an Alignment property; rather, a column's alignment is set by the column style.
The following example displays two columns, "Product Name" and "UnitPrice," and sets the alignment of the cells within each. This example assumes a DataGrid control (DataGrid1) displaying the "Products" table from the Northwind database with a ColoredTextBoxColumn column (code example above).
Public Sub AddAlignedColoredColumns()
Dim tsProducts As New DataGridTableStyle
tsProducts.MappingName = "Products"
Dim cstbProdName As New DataGridTextBoxColumn
cstbProdName.MappingName = "ProductName"
cstbProdName.HeaderText = "Product Name"
cstbProdName.Alignment = HorizontalAlignment.Left
Dim cscolUnitPrice As New ColoredTextBoxColumn
cscolUnitPrice.MappingName = "UnitPrice"
cscolUnitPrice.HeaderText = "UnitPrice"
cscolUnitPrice.Alignment = HorizontalAlignment.Center
tsProducts.GridColumnStyles.Add(cstbProdName)
tsProducts.GridColumnStyles.Add(cscolUnitPrice)
DataGrid1.TableStyles.Add(tsProducts)
End Sub
In the code above, once the column styles are created and their mapping names are set to the columns, the Alignment property is set.
Note In Visual Studio .NET 2002, the text of the column headers does not correctly display if the Alignment property is set to Center.
Setting Column Width
As with alignment, width of a column is specified in a column style; the column object itself does not have a Width property. The column object itself does not have a Width property; rather, a column's width is set by the column style.
The following example displays two columns, "Product Name" and "UnitPrice", and sets the size of each. This example assumes a DataGrid control (DataGrid1) displaying the "Products" table from the Northwind database with a BackColor/ForeColor column (code example above).
Public Sub AddSizedColoredColumns()
Dim tsProducts As New DataGridTableStyle
tsProducts.MappingName = "Products"
Dim cstbProdName As New DataGridTextBoxColumn
cstbProdName.MappingName = "ProductName"
cstbProdName.HeaderText= "Product Name"
cstbProdName.Width = 250
Dim cscolUnitPrice As New ColoredTextBoxColumn
cscolUnitPrice.MappingName = "UnitPrice"
cscolUnitPrice.HeaderText = "Unit Price"
cscolUnitPrice.Width = 150
tsProducts.GridColumnStyles.Add(cstbProdName)
tsProducts.GridColumnStyles.Add(cscolUnitPrice)
DataGrid1.TableStyles.Add(tsProducts)
End Sub
In the code above, once the column styles are created and their mapping names are set to the columns, the Width property is set.
Formatting Data For Display
You can format the contents of the cell into commonly recognized formats, such as currency or dates.
Formatting the string displayed within the cell of a grid can also be accomplished with the column style. As with specifying the column's width, it is as simple as setting a property. The Format [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwindowsformsdatagridtextboxcolumnclassformattopic.asp ] property of the DataGridTextBoxColumn class allows you to set a number of basic formatting types.
Keep in mind that the operating system's culture setting will also determine aspects of how the string is displayed. Markers such as currency type, decimal indicator, and units of measurement are some of the variables determined by the culture being displayed.
There are a few standard formats used by most developers. Here is a table naming the format expression, the original value from the data source (Input), the format expression's practical effect on your data (Output), and a brief description of the formatting type. Note that all of the examples in this table have English-United States (en-US) set as their culture.
Format Expressions: "English/United States" Culture
Format Expression |
Culture |
Input |
Output |
Description |
|---|
d |
en-US |
February 12, 1976 |
2/12/1976 |
Short date: The numerical month, day, and year. |
D |
en-US |
February 12, 1976 |
Thursday, February 12, 1976 |
Long date: The day of the week, month (spelled-out), day, and year. |
T |
en-US |
11:38:00 PM |
11:38:00 PM |
Long time: The hour, minute, second, and (in appropriate cultures) AM/PM designator. |
t |
en-US |
11:38:00 PM |
11:38 PM |
Short time: The hour and minute and (in appropriate cultures) AM/PM designator. |
F |
en-US |
Thursday, February 12, 1976 11:38:16 PM |
Thursday, February 12, 1976 11:38:16 PM |
Full date (long time): The day of the week, month (spelled-out), day, year, hour, minute, second, and (in appropriate cultures) AM/PM designator. |
f |
en-US |
Thursday, February 12, 1976 11:38:16 PM |
Thursday February 12, 1976 11:38 |
Full date (short time): The day of the week, month (spelled-out), day, year, hour, minute, and (in appropriate cultures) AM/PM designator. |
C (or c) |
en-US |
32.98 |
$32.98 |
Currency: A string representing a monetary value. The currency, decimal separator, and other numeric information are determined by the NumberFormatInfo [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemGlobalizationNumberFormatInfoClassTopic.asp ] class and the current culture set for that thread. See Setting the Culture and UI Culture for Windows Forms Globalization [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbcon/html/vbtskcustomizingsettingsforspecificcultures.asp ] for more information. |
The entries in the table below are a subset of the available format expressions, each with a different culture set.
Format Expressions: Various Cultures
Format Expression |
Culture |
Input |
Output |
Description |
|---|
T |
es-ES |
11:38:00 PM |
23:38:00 |
Long time: The hour, minute, second, and (in appropriate cultures) AM/PM designator. |
f |
fr-FR |
Thursday, February 12, 1976 11:38 PM |
jeudi 12 febrier 1976 23:38 |
Full date (short time): The day of the week, month (spelled-out), day, year, hour, minute, and (in appropriate cultures) AM/PM designator. Note that ordering of values may change depending on the culture selected. |
C (or c) |
jp-JP |
12132.98 |
¥12,132.98 |
Currency: A string representing a monetary value. The currency, decimal separator, and other numeric information are determined by the NumberFormatInfo [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemGlobalizationNumberFormatInfoClassTopic.asp ] class and the current culture set for that thread. See Setting the Culture and UI Culture for Windows Forms Globalization [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbcon/html/vbtskcustomizingsettingsforspecificcultures.asp ] for more information. |
The format you select for the data in your grid will be driven by the data being displayed. Be sure to consider the local culture of the operating system your application will run on when implementing format expressions.
The following example displays a column ("UnitPrice") formatted as a currency. This example assumes a DataGrid control (DataGrid1) displaying the "Products" table from the Northwind database with a BackColor/ForeColor column (code example above).
Public Sub AddFormattedColumn()
Dim tsProducts As New DataGridTableStyle
tsProducts.MappingName = "Products"
' Create a new column style from the example above.
Dim csUnitPrice As New ColoredTextBoxColumn
csUnitPrice.MappingName = "UnitPrice"
csUnitPrice.HeaderText= "Unit Price"
' Set the format of the column
' NOTE: The data must be of type Integer to for it to be
' formatted correctly as a currency.
csUnitPrice.Format = "c"
tsProducts.GridColumnStyles.Add(csUnitPrice)
DataGrid1.TableStyles.Add(tsProducts)
End Sub
In the code above, once the column style is created and its mapping name is set to a column, the Format property is set to currency, so that the strings representing the price will be displayed in the appropriate format.
More information about formatting strings is available in the Visual Basic documentation. For a discussion of the different types of formatting strings, see Formatting Types [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconformattingtypes.asp ] . For a list of standard date/time and numeric format strings, see Date and Time Format Strings [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondatetimeformatstrings.asp ] and Standard Numeric Format Strings [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconstandardnumericformatstrings.asp ] .
Implementing Graphics Within Cells
In addition to formatting the contents of the cells, you can tell the grid to paint itself in a variety of fashions. The System.Drawing namespace provides you with some interesting options for customizing columns with graphics.
Creating Textured Backgrounds Using Brushes
If your project calls for something less traditional than the ColoredTextBox class we created earlier, you can use one of the brushes provided in the System.Drawing.Drawing2D namespace. As an example, try replacing the ForeColorBrush and BackColorBrush specified in the code sample in the section "Step I: Creating a custom ColumnStyle class":
BackColorBrush = New SolidBrush(Color.Yellow)
ForeColorBrush = New SolidBrush(Color.Red)
with the following code:
BackColorBrush = New System.Drawing.Drawing2D.HatchBrush _
(Drawing2D.HatchStyle.SolidDiamond, Color.Plum, Color.Thistle)
ForeColorBrush = New SolidBrush(Color.DarkBlue)
This new code uses an instance of the HatchBrush [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemdrawingdrawing2dhatchbrushclasstopic.asp ] class to paint the background in a series of filled diamonds (the filled-diamond pattern is a member of the HatchStyle [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemdrawingdrawing2dhatchstyleclasstopic.asp ] enumeration). You can experiment with the different brush options available in the Drawing2D namespace to find a combination that is appealing to you.
Note Be sure to call the Dispose method [ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemdrawingbrushclassdisposetopic.asp ] when your code is finished using a brush.
Conclusion
As you can see, there are number of common tasks related to the Windows Forms DataGrid control that require creating and implementing your own custom column styles. Once you have begun working with these objects, a great deal of power is available to you. You can paint cells with a variety of brushes, set column alignment or width, or use the .NET Framework to format the contents of the grid's cells.
