Displaying Both Text and Pictures in a Cell

Once the ValueItems object is configured to perform text-to-picture translations for a column, you can display both the Value string and the DisplayValue bitmap to appear within the same cell by selecting the AnnotatePicture property. Or, in code:

· Visual Basic

Me.C1TrueDBGrid1.Columns("Country").ValueItems.AnnotatePicture = True

· C#

this.c1TrueDBGrid1.Columns["Country"].ValueItems.AnnotatePicture = true;

· Delphi

Self.C1TrueDBGrid1.Columns['Country'].ValueItems.AnnotatePicture := True;

The horizontal placement of the bitmap with respect to the cell text is determined by the HorizontalAlignment and ForegroundPicturePosition properties of the column's Style object. The enumeration objects for these two properties are the AlignHorzEnum and ForegroundPicturePositionEnum objects respectively. In the following example, HorizontalAlignment is set to AlignHorzEnum.General. Since the Country column represents a string field, the cell text is left-aligned. However, since the ForegroundPicturePosition property is set to the default value of ForegroundPicturePosition.Near, the bitmap is placed at the left edge of the cell, and the cell text is left-aligned in the remaining space.

However, if you change the ForegroundPicturePosition property to ForegroundPicturePositionEnum.Far, then the cell text is left-aligned as usual, but the bitmap is right-aligned.

To place the cell text below the bitmap while centering both items, set the HorizontalAlignment property to AlignHorzEnum.Center and the ForegroundPicturePosition property to ForegroundPicturePositionEnum.TopofText.

Note: For an illustration of all possible combinations of the HorizontalAlignment and ForegroundPicturePosition properties, see Displaying Foreground Pictures.

When editing, the editor uses all space available in the text portion of the cell. When the Presentation property of the ValueItemCollection object is set to one of the combo box options, the bitmap will not change until editing is completed.

Note that in the preceding examples, the text is displayed as it is stored in the database without formatting. Since the ValueItem object can only accommodate one translation, displaying both a picture and formatted text cannot be accomplished with ValueItems alone. Therefore, use the FormatText event to translate the text, and then use the ValueItems to associate the translated text (not the underlying data value) with a picture:

· Visual Basic

Me.C1TrueDBGrid1.Columns("Country").NumberFormat = "FormatText Event"

· C#

this.c1TrueDBGrid1.Columns("Country").NumberFormat = "FormatText Event";

· Delphi

Self.C1TrueDBGrid1.Columns['Country'].NumberFormat := 'FormatText Event';

In this example, the NumberFormat property is set to a special value that causes the FormatText event to fire:

· Visual Basic

Private Sub C1TrueDBGrid1_FormatText(ByVal sender As Object, ByVal e As C1.Win.C1TrueDBGrid.FormatTextEventArgs) Handles C1TrueDBGrid1.FormatText

Select Case e.Value

Case "CAN"

e.Value = "Canada"

Case "UK"

e.Value = "United Kingdom"

Case "USA"

e.Value = "United States"

Case "JPN"

e.Value = "Japan"

Case "AUS"

e.Value = "Australia"

End Select

End Sub

· C#

private void C1TrueDBGrid1_FormatText( object sender, C1.Win.C1TrueDBGrid.FormatTextEventArgs e)

{

switch (e.value)

{

case "CAN":

e.value = "Canada";

break;

case "UK":

e.value = "United Kingdom";

break;

case "USA":

e.value = "United States";

break;

case "JPN":

e.value = "Japan";

break;

case "AUS":

e.value = "Australia";

break;

}

· Delphi

procedure TWinForm.C1TrueDBGrid1_FormatText(sender: System.Object; e: C1.Win.C1TrueDBGrid.FormatTextEventArgs);

begin

if (e.Value = 'CAN');

e.Value := 'Canada'

else if (e.Value = 'UK') then

e.Value := 'United Kingdom'

else if (e.Value = 'USA') then

e.Value := 'United States'

else if (e.Value = 'JPN') then

e.Value := 'Japan'

else if (e.Value = 'AUS') then

e.Value := 'Australia';

end;

Since the FormatText event now translates the country codes stored in the database into actual names for display, the Value property of each ValueItem in the ValueItemCollection object must be changed accordingly.

Assuming that the HorizontalAlignment and ForegroundPicturePosition properties are set as in the previous example, the end result is that the underlying data is displayed as both descriptive text and a picture.

Note: DisplayValue pictures are ideally suited for translating status codes or other fields where the number of allowable values is relatively small. To get a more generalized picture display mechanism than the ValueItemCollection object offers, use the ForegroundPicturePosition property in conjunction with the FetchCellStyle event to display arbitrary pictures on a per-cell basis. For more information, see Displaying Foreground Pictures.