# Translate

## Content

Although the [FormatText](/componentone/docs/win/online-truedbgrid/) 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](/componentone/docs/win/online-truedbgrid/) 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](/componentone/docs/win/online-truedbgrid/) object contains a collection and properties that define the association between an underlying data value and its visual representation within the grid. The [ValueItems](/componentone/docs/win/online-truedbgrid/) object contains a [ValueItemCollection](/componentone/docs/win/online-truedbgrid/) of zero or more [ValueItem](/componentone/docs/win/online-truedbgrid/) objects. Each [ValueItem](/componentone/docs/win/online-truedbgrid/) supports two main properties: [Value](/componentone/docs/win/online-truedbgrid/), the underlying data value, and [DisplayValue](/componentone/docs/win/online-truedbgrid/), its visual representation. Both properties are of type Object. Additionally, each [C1DataColumn](/componentone/docs/win/online-truedbgrid/) object contains [ValueItems](/componentone/docs/win/online-truedbgrid/) object.

In code, manipulate the collection of [ValueItem](/componentone/docs/win/online-truedbgrid/) pairs as you would any other **True DBGrid for WinForms** or Visual Studio collection. [ValueItems](/componentone/docs/win/online-truedbgrid/) can be added, removed, or manipulated through the [ValueItemCollection](/componentone/docs/win/online-truedbgrid/) object.

At design time a **ValueItem Collection Editor** is available through the **C1TrueDBGrid Designer**. For more information see [Using the ValueItemCollection Editor](/componentone/docs/win/online-truedbgrid/design-time/collection-editors#valueitem-collection-editor).

## Specifying Text-to-Text Translations

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

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/country-codes.png)

To display the character codes as proper names, use the column's [ValueItemCollection](/componentone/docs/win/online-truedbgrid/) object to specify automatic data translations. At design time, this is done with .NET's [ValueItemCollection](/componentone/docs/win/online-truedbgrid/) editor.
Altering the [ValueItemCollection](/componentone/docs/win/online-truedbgrid/) 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](/componentone/docs/win/online-truedbgrid/) editor.
3. In the right pane under the **ValueItems** node, set the [Translate](/componentone/docs/win/online-truedbgrid/) property to **True**.
4. Clicking on the **Add** button in the left pane will add [ValueItem](/componentone/docs/win/online-truedbgrid/) objects. In the right pane specify a [Value](/componentone/docs/win/online-truedbgrid/) and [DisplayValue](/componentone/docs/win/online-truedbgrid/) for each [ValueItem](/componentone/docs/win/online-truedbgrid/). When entering the [ValueItem](/componentone/docs/win/online-truedbgrid/) text, disregard the **drop-down** button. This is used for entering a bitmap as a [DisplayValue](/componentone/docs/win/online-truedbgrid/).
5. Select **OK** or **Apply** to commit the changes.

When the program is run, *Country* field values that match any items in the [Value](/componentone/docs/win/online-truedbgrid/) column appear as the corresponding [DisplayValue](/componentone/docs/win/online-truedbgrid/) entry. For example, *CAN* becomes *Canada*, *UK* becomes *United\_\_Kingdom*, and so on.

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/translate-country-abbreviation.png)

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:

```csharp
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](/componentone/docs/win/online-truedbgrid/) 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](/componentone/docs/win/online-truedbgrid/) property box and either select another bitmap or type in text.
Note that the [Translate](/componentone/docs/win/online-truedbgrid/) property for the [ValueItems](/componentone/docs/win/online-truedbgrid/) object must be set to **True**. Depending upon the height of the bitmaps, it may be necessary to increase the value of the [RowHeight](/componentone/docs/win/online-truedbgrid/) property. If that is done, change the [VerticalAlignment](/componentone/docs/win/online-truedbgrid/) member of the grid's [Style](/componentone/docs/win/online-truedbgrid/) 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](/componentone/docs/win/online-truedbgrid/) column appear as the corresponding [DisplayValue](/componentone/docs/win/online-truedbgrid/) picture:

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/translate-country-flag.png)

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:

```csharp
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](/componentone/docs/win/online-truedbgrid/) object to represent Boolean values as in-cell checkboxes. The effect of a working Boolean checkbox can be achieved without defining any [ValueItem](/componentone/docs/win/online-truedbgrid/) objects—just set the [Presentation](/componentone/docs/win/online-truedbgrid/) property to [PresentationEnum.CheckBox](/componentone/docs/win/online-truedbgrid/).

Note that the [Translate](/componentone/docs/win/online-truedbgrid/) checkbox does not need to be selected to enable automatic data translation, nor does the [CycleOnClick](/componentone/docs/win/online-truedbgrid/) 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.

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/checkbox-presentation.png)

>type=note
> **Note**: To use different check box bitmaps, define a two-state collection of [ValueItem](/componentone/docs/win/online-truedbgrid/) objects through the [Values](/componentone/docs/win/online-truedbgrid/) property of the [C1DataColumn](/componentone/docs/win/online-truedbgrid/). Set the [Presentation](/componentone/docs/win/online-truedbgrid/) property to [PresentationEnum.Normal](/componentone/docs/win/online-truedbgrid/), and set the [Translate](/componentone/docs/win/online-truedbgrid/) and [CycleOnClick](/componentone/docs/win/online-truedbgrid/) properties to **True**.

## 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:

![](https://cdn.mescius.io/document-site-files/images/a1b176e5-6638-4b1f-a786-e41a817558bb/images/truedbdropdown-auto-translation.png)

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](/componentone/docs/win/online-truedbgrid/) 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.