Custom Painting Scenarios

  • 6 minutes to read

Custom draw events provide complete control over the appearance of grid elements. This document provides examples illustrating common scenarios for custom draw events. For basic information on custom painting in Grid Control, refer to the Custom Painting Basics topic.

NOTE

Custom painting and alpha blending features are not applied to the print and export versions of the Grid Control.

NOTE

In specific paint themes (e.g., skins and Office2003), you are not able to change the background of some elements. Changing the background of these elements via the Appearance parameter of custom draw events is also not supported.

There are three main scenarios for custom draw event usage.

 

Manual Element Rendering

Custom draw events allow you to manually render grid elements using the methods provided by the event's CustomDrawEventArgs.Cache and CustomDrawEventArgs.Appearance objects. These objects' methods allow you to draw various graphics primitives (lines, rectangles, ellipses, images, etc.). When performing manual element rendering, you typically need to set the event's CustomDrawEventArgs.Handled parameter to true. Otherwise, the default painting mechanism will be invoked after event execution, and it will override your rendering.

 

The following example demonstrates how to use the GridView.CustomDrawCell event to custom paint the RequiredDate column's cells. If a cell refers to the current or following date, its background is filled with a gradient brush. If the cell contains a date that is greater than the current date, the cell will display the number of days left until the specified date. The appearance of the other cells is not affected.

CD_CustomDraw_SamplesDrawCell


using System.Drawing.Drawing2D;

private void gridView1_CustomDrawCell(object sender, DevExpress.XtraGrid.Views.Base.RowCellCustomDrawEventArgs e) {
    if (e.Column.FieldName != "RequiredDate") return;
    DateTime requiredDate = (DateTime)e.CellValue;
    if (requiredDate < DateTime.Today) return;
    //The text to display in the cell 
    string displayText;
    if (requiredDate > DateTime.Today)
        displayText = ((TimeSpan)(requiredDate - DateTime.Today)).Days.ToString() + " day(s) left";
    else
        displayText = e.DisplayText;
    LinearGradientBrush brush = new LinearGradientBrush(e.Bounds, Color.Pink, Color.White, LinearGradientMode.ForwardDiagonal);
    using (brush) {
        e.Cache.FillRectangle(brush, e.Bounds);
    }
    e.Cache.DrawString(displayText, e.Appearance.Font, Brushes.Black, e.Bounds);
    //Prohibit default painting 
    e.Handled = true;
}

Combining Default Painting and Custom Painting

The following scenario allows you to paint custom information over the default rendering. To accomplish this task, first invoke the default painting mechanism for an element using the CustomDrawEventArgs.DefaultDraw method. Then, you can paint additional information over the default rendering using the methods of the event's CustomDrawEventArgs.Graphics and CustomDrawEventArgs.Appearance properties.

Before invoking the default painting mechanism, you can modify an element's display information. The default rendering mechanism, when invoked, will apply these changes. For instance, you can modify the appearance of an element using the event's CustomDrawEventArgs.Appearance property. Custom draw events for some elements (filter panel, band and column headers, view footer, group footer, group rows, preview section, row indicator and footer cells) provide the Info parameter, which contains element-specific view information. For these events, you can change the Info object's properties to customize an element's display text or change the boundaries of inner elements. If an event contains a DisplayText property, you can set it to a custom value before invoking the default rendering.

A call to the CustomDrawEventArgs.DefaultDraw method automatically sets the event's Handled parameter to true. This prevents the default painting mechanism from being re-invoked after event execution.

Note that modifying the boundaries of elements or inner elements changes the View layout. If you need to change the boundaries of elements for the purpose of custom painting, you should restore the boundaries immediately after the default painting mechanism is invoked.

 

In the sample below, the GridView.CustomDrawCell event is handled to custom-paint data cells.

The CustomDrawEventArgs.DefaultDraw method applies the default draw to all cells. For all "Units in Stock" cells that display 0, a custom icon is drawn on top of this default cell rendering.

GridView-CustomDrawCell-UseDefaultDraw

Image warningImage = Image.FromFile("c:\\warning.png");

private void gridView1_CustomDrawCell(object sender, DevExpress.XtraGrid.Views.Base.RowCellCustomDrawEventArgs e) {
    if (e.Column.FieldName == "UnitsInStock") {
        e.DefaultDraw();
        if (Convert.ToInt32(e.CellValue) == 0)
            e.Cache.DrawImage(warningImage, e.Bounds.Location);
    }
}

Customizing Element Display Information for Default Rendering

When handling a custom draw event, you can change an element's view information (e.g., appearance or content) and set the event's CustomDrawEventArgs.Handled property to false (the default value). In this case, the default rendering will automatically be invoked after the event execution. The painting mechanism will use the modified view information to render the element.

The following table describes custom draw events that allow you to customize an element's display information.

Custom draw event

Allows you to ...

GridView.CustomDrawColumnHeader

ColumnView.CustomDrawFilterPanel

GridView.CustomDrawFooter

GridView.CustomDrawFooterCell

GridView.CustomDrawGroupRow

GridView.CustomDrawRowFooter

GridView.CustomDrawRowFooterCell

GridView.CustomDrawRowIndicator

GridView.CustomDrawRowPreview

BandedGridView.CustomDrawBandHeader

LayoutView.CustomDrawCardBackground

  • Change the display information via the event's Info parameter.

    The Info object allows you to change the display text (if it is available for the element being painted).

    Avoid changing the boundaries of the inner elements as this may corrupt the View's layout.

  • Provide a custom appearance using the event's Appearance property.

GridView.CustomDrawCell

CardView.CustomDrawCardFieldValue

CardView.CustomDrawCardFieldCaption

CardView.CustomDrawCardCaption

LayoutView.CustomDrawCardCaption

LayoutView.CustomDrawCardFieldCaption

LayoutView.CustomDrawCardFieldValue

  • Dynamically supply custom display text via the DisplayText/CardCaption parameter.
  • Provide a custom appearance using the event's Appearance property.

 

The following example demonstrates how to specify a custom background for footer cells using the GridView.CustomDrawFooterCell event. The default appearance settings specified by the View's GridViewAppearances.FooterPanel property will be ignored.

The image below shows the result.

CD_CustomDraw_SamplesFooterCell


gridView1.PaintStyleName = "Flat";

private void gridView1_CustomDrawFooterCell(object sender, DevExpress.XtraGrid.Views.Grid.FooterCellCustomDrawEventArgs e) {
    if (e.Column.SummaryItem.SummaryType == DevExpress.Data.SummaryItemType.Count)
        e.Appearance.BackColor = Color.Pink;
    else {
        if (e.Column.SummaryItem.SummaryType == DevExpress.Data.SummaryItemType.Average)
            e.Appearance.BackColor = Color.Thistle;
        else
            e.Appearance.BackColor = Color.Moccasin;
    }
}
See Also