Tutorial: Customize Row Preview Sections

• Oct 29, 2020
• 4 minutes to read

This walkthrough is a transcript of the Customize Row Preview Sections video available on the DevExpress YouTube Channel.

In this tutorial, you will learn how to customize the content and size of row preview sections using Grid View events. First, you will customize the text to include values from multiple data fields. Then, you’ll specify the preview section height for individual sections based on their content. Finally, you will use a CustomDraw event to add images to previews.

Starting Point

Start with a grid control that has row preview sections enabled where you show values from the Description field.

Displaying Values from Multiple Data Fields

First, you’ll see how you can extend these preview sections with values from two more fields – MPG City and MPG Highway.

At design time, access the Grid View’s settings and write a handler for the GridView.CalcPreviewText event. Declare a separate CalculateMyPreviewText method that obtains the data row using the CalcPreviewTextEventArgs.RowHandle parameter and then obtains values of three fields: MPG City, MPG Highway and Description. If the description is empty then the method simply returns an empty string. Otherwise, it returns a string that combines values from all three fields.

Call this method in the event handler to specify the CalcPreviewTextEventArgs.PreviewText parameter value and thus customize the text to be displayed.

C#

private void gridView1_CalcPreviewText(object sender, DevExpress.XtraGrid.Views.Grid.CalcPreviewTextEventArgs e) {
    e.PreviewText = CalculateMyPreviewText(e.RowHandle);
}

private string CalculateMyPreviewText(int rowHandle) {
    DataRow row = gridView1.GetDataRow(rowHandle);
    string mpgcity = row["MPG City"].ToString();
    string mpghwy = row["MPG Highway"].ToString();
    string description = row["Description"].ToString();
    if (string.IsNullOrEmpty(description))
        return string.Empty;
    return string.Format("MPG City: {0}, MPG Highway: {1}\n{2}", mpgcity, mpghwy, description);
}

When you run the application, you’ll see that only the first string is displayed, since the grid will not calculate the preview height automatically for custom text.

Set the GridView.PreviewLineCount property to 5 to see that the Description field values are also displayed.

Specifying Height for Individual Preview Sections

All preview sections reserve space for 5 lines of text, even if it’s not needed. Even if the preview text is empty, the empty space is still displayed.

To fix this, close the application and write a handler for the Grid View’s GridView.MeasurePreviewHeight event. If the Description field value is an empty string, the code sets the height to 0. Otherwise, the height is set to the height of the image in that row using the yet undefined GetRowImage function.

Then, define this function so that it obtains the Bitmap from the Image field in the specified row.

C#

using DevExpress.XtraGrid.Views.Grid;
// ...
private void gridView1_MeasurePreviewHeight(object sender, DevExpress.XtraGrid.Views.Grid.RowHeightEventArgs e) {
    GridView view = sender as GridView;
    if (view == null) return;
    DataRow row = view.GetDataRow(e.RowHandle);
    if (row["Description"].ToString() == String.Empty)
        e.RowHeight = 0;
    else
        e.RowHeight = GetRowImage(e.RowHandle).Height;
}

private Bitmap GetRowImage(int rowHandle) {
    DataRow row = gridView1.GetDataRow(rowHandle);
    if (row["Image"] == System.DBNull.Value)
        return null;
    byte[] imageData = (byte[])row["Image"];
    return new Bitmap(new System.IO.MemoryStream(imageData));
}

Run the application. You’ll see that all preview sections containing text display more than one row by default. Rows that have empty Description field values don’t show previews.

Adding Images to Preview Sections

Now add images. Return to design time and handle the GridView.CustomDrawRowPreview event. The GetImage method that you used to calculate the preview height will obviously be useful here too. The obtained image is drawn using the CustomDrawEventArgs.Cache parameter.

Then, calculate the rectangle where the text will be painted. The left top corner is initialized, taking into account the image width and an additional 20 pixel offset. The rectangle’s width is also adjusted to fit the image.

The next step is to obtain the text, which is done using the CalculateMyPreviewText method declared in the beginning of this tutorial and used in the GridView.CalcPreviewText event. Finally, specify the trimming style and draw the text. Set CustomDrawEventArgs.Handled to true to disable default painting.

C#

private void gridView1_CustomDrawRowPreview(object sender, DevExpress.XtraGrid.Views.Base.RowObjectCustomDrawEventArgs e) {
    Bitmap image = GetRowImage(e.RowHandle);
    e.Cache.DrawImage(image, e.Bounds.X, e.Bounds.Y, image.Width, image.Height);

    Point textOrigin = new Point(e.Bounds.X + image.Width + 20, e.Bounds.Y + 4);
    Rectangle textRect = new Rectangle(textOrigin.X, textOrigin.Y, e.Bounds.Width - textOrigin.X, e.Bounds.Height - 8);
    string text = CalculateMyPreviewText(e.RowHandle);
    StringFormat format = e.Appearance.GetStringFormat();
    format.Trimming = StringTrimming.EllipsisWord;
    e.Cache.DrawString(text, e.Appearance.Font, e.Appearance.GetForeBrush(e.Cache), textRect, format);

    e.Handled = true;
}

Run the application to see the result. You can now hide the columns that display the same information as shown in row preview sections.