Although the FormatText event can be used to map data values into more descriptive display values, True DBGrid for WinForms also provides a mechanism for performing such data translations automatically without code. Through the use of the ValueItem object, alternate text or even pictures can be specified to be displayed in place of the underlying data values.

This feature is ideally suited for displaying numeric codes or cryptic abbreviations in a form that makes sense to end-users. For example, country codes can be rendered as proper names or even as pictures of their respective flags. Or, the numbers 0, 1, and 2 may be displayed as Yes, No, and Maybe. Either the actual values (0, 1, 2) or the translated values (Yes, No, Maybe) may be displayed as radio buttons in a cell or in a drop-down combo box.

The ValueItems object contains a collection and properties that define the association between an underlying data value and its visual representation within the grid. The ValueItems object contains a ValueItemCollection of zero or more ValueItem objects. Each ValueItem supports two main properties: Value, the underlying data value, and DisplayValue, its visual representation. Both properties are of type Object. Additionally, each C1DataColumn object contains ValueItems object.

In code, manipulate the collection of ValueItem pairs as you would any other True DBGrid for WinForms or Visual Studio collection. ValueItems can be added, removed, or manipulated through the ValueItemCollection object.

At design time a ValueItem Collection Editor is available through the C1TrueDBGrid Designer. For more information see Using the ValueItemCollection Editor.

Specifying Text-to-Text Translations

Consider the following example, in which the Country field is represented by a short character code.

To display the character codes as proper names, use the column's ValueItemCollection object to specify automatic data translations. At design time, this is done with .NET's ValueItemCollection editor.
Altering the ValueItemCollection object through the collection editor enables you to specify data translations on a per-column basis in a simple window. To construct a list of data translations for an individual column, complete the following steps:

1. Open up the C1TrueDBGrid Designer by clicking on the ellipsis button (…) next to the Columns collection in the Properties window.
2. Select the column whose contents you would like translated. In the left pane expand the ValueItems node. Clicking on the ellipsis button next to the Values node will bring up the ValueItemCollection editor.
3. In the right pane under the ValueItems node, set the Translate property to True.
4. Clicking on the Add button in the left pane will add ValueItem objects. In the right pane specify a Value and DisplayValue for each ValueItem. When entering the ValueItem text, disregard the drop-down button. This is used for entering a bitmap as a DisplayValue.
5. Select OK or Apply to commit the changes.

When the program is run, Country field values that match any items in the Value column appear as the corresponding DisplayValue entry. For example, CAN becomes Canada, UK becomes UnitedKingdom, and so on.

Note that the underlying database is not affected; only the presentation of the data value is different. The same effect can be achieved in code as follows:

ValueItemCollection v = this.c1TrueDBGrid1.Columns["Country"].ValueItems.Values;
v.Add(new ValueItem("Spain", "ESP"));
v.Add(new ValueItem("Germany", "DEU"));
v.Add(new ValueItem("United States", "USA"));
v.Add(new ValueItem("Hungary", "HUN"));
v.Add(new ValueItem("Austria", "AUT"));
v.Add(new ValueItem("Italy", "ITA"));
v.Add(new ValueItem("France", "FRA"));
this.c1TrueDBGrid1.Columns["Country"].ValueItems.Translate = true;

Specifying Text-to-Picture Translations

The same techniques used to specify text-to-text translations can also be used for text-to-picture translations. Within the ValueItem Collection Editor, instead of typing a string into the DisplayValue column, use the ellipsis button (...) to select a bitmap to be used for data translations. To delete your bitmap selection, simply delete the text in the DisplayValue property box and either select another bitmap or type in text.
Note that the Translate property for the ValueItems object must be set to True. Depending upon the height of the bitmaps, it may be necessary to increase the value of the RowHeight property. If that is done, change the VerticalAlignment member of the grid's Style property to Center to ensure that the bitmaps (as well as textual data in other columns) are centered vertically within grid cells instead of being anchored at the top.

When the program is run, Country field values that match an item in the Value column appear as the corresponding DisplayValue picture:

As with textual translations, the underlying database is not affected; only the presentation of the data value is different. The same effect can be achieved in code as follows:

ValueItemCollection v = this.c1TrueDBGrid1.Columns["Country"].ValueItems.Values;
ValueItem Item = new ValueItem();
Item.Value = "Germany";
Item.DisplayValue = Image.FromFile("german-flag.jpg");
v.Add(Item);
Item = new ValueItem();
Item.Value = "USA";
Item.DisplayValue = Image.FromFile("american-flag.jpg");
v.Add(Item);
Item = new ValueItem();
Item.Value = "France";
Item.DisplayValue = Image.FromFile("france-flag.jpg");
v.Add(Item);
Item = new ValueItem();
Item.Value = "Austria";
Item.DisplayValue = Image.FromFile("austria-flag.jpg");
v.Add(Item);
this.c1TrueDBGrid1.Columns["Country"].ValueItems.Translate = true;

Displaying Boolean Values as Check Boxes

Use the ValueItems object to represent Boolean values as in-cell checkboxes. The effect of a working Boolean checkbox can be achieved without defining any ValueItem objects—just set the Presentation property to PresentationEnum.CheckBox.

Note that the Translate checkbox does not need to be selected to enable automatic data translation, nor does the CycleOnClick checkbox need to be selected to enable end users to toggle the value of a cell by clicking it. The following figure shows a typical checkbox display.

Automatic Data Translation with True DBDropDown

Suppose a grid drop-down box is needed using data that contains a value and a corresponding text representation, as in the following image:

In this situation, you may not want the user to see the somewhat ambiguous TypeId, but instead want the more understandable TypeDesc to show in the drop-down. The ValueTranslate property automatically maps the TypeId value to the TypeDesc representation. In this way, when the user accesses the drop-down, it will display the TypeDesc text.