SpreadsheetControl.CustomDrawCell Event

Allows you to paint cell content.

Namespace: DevExpress.XtraSpreadsheet

Assembly: DevExpress.XtraSpreadsheet.v24.1.dll

NuGet Package: DevExpress.Win.Spreadsheet

Declaration

C#

public event CustomDrawCellEventHandler CustomDrawCell

VB.NET

Public Event CustomDrawCell As CustomDrawCellEventHandler

Event Data

The CustomDrawCell event's data class is CustomDrawCellEventArgs. The following properties provide information specific to this event:

Property	Description
Bounds	Returns the bounding rectangle of the drawing area. Inherited from CustomDrawCellEventArgsBase.
Cache	Gets an object that serves as the storage for pens, fonts and brushes. Inherited from CustomDrawObjectEventsArgs.
Cell	Gets the worksheet cell being painted. Inherited from CustomDrawCellEventArgsBase.
FillBounds	Returns the bounding rectangle of the drawing area for painting the cell background. Inherited from CustomDrawCellEventArgsBase.
Font	Gets the font attributes of the painted cell.
ForeColor	Gets or sets the color of the text within the painted cell.
Graphics	Gets an object used for painting. Inherited from CustomDrawObjectEventsArgs.
Handled	Gets or sets whether an event is handled. If true, the default actions are not required. Inherited from CustomDrawObjectEventsArgs.
Text	Gets or sets the painted cell’s text.

The event data class exposes the following methods:

Method	Description
DrawDefault()	Renders the element using the default drawing mechanism. Inherited from CustomDrawObjectEventsArgs.

Remarks

The CustomDrawCell and CustomDrawCellBackground events fire for each cell in the visible worksheet area and allow you to draw cells in a custom manner.

If you perform custom draw actions, set the CustomDrawObjectEventsArgs.Handled property to true to cancel default painting.

You can also combine your custom painting with the default painting. Call the CustomDrawObjectEventsArgs.DrawDefault method to draw cells with the default painter. Set CustomDrawObjectEventsArgs.Handled to true and use the CustomDrawObjectEventsArgs.Graphics property to display custom elements over default graphics.

Important

Never change cell values or format settings on this event. Any action that causes the control’s layout update can lead to an incorrect result or throw an unhandled exception.

Note

In v18.2 and earlier, the CustomDrawCell and CustomDrawCellBackground events fire only for cells that have a value or formatting applied. If you need to restore this behavior, set the EnableLegacyLayoutEngine property to true to switch back to the SpreadsheetControl’s legacy layout engine.

Example

The code snippet below uses the SpreadsheetControl.CustomDrawCell event to display images for product categories and add callouts to cells that contain 0 in the “Units In Stock” column. The Spreadsheet control uses the default drawing mechanism to render these cells and then displays custom graphics over cells.

View Example: Use Custom Draw Events to Customize the Appearance of Spreadsheet Elements

C#

using System;
using System.Drawing;
using DevExpress.Spreadsheet;
using DevExpress.XtraSpreadsheet;
// ...
private void spreadsheetControl1_CustomDrawCell(object sender, CustomDrawCellEventArgs e)
{

    // Check whether a cell belongs to the "Category" column.
    if (e.Cell.ColumnIndex == 1) { 

        // Obtain the category name. 
        String categoryName = e.Cell.Value.ToString();

        // Return the image that corresponds to the category name. 
        Image categoryImage = ChooseImage(categoryName);

        // Specify the image location (the upper-right corner of the cell).
        Point point = new Point(e.Bounds.Right - 50, e.Bounds.Top);

        // Draw the category image over the cell.
        if (categoryImage != null)
            e.Graphics.DrawImage(categoryImage, point);
    }

    // If a cell belongs to the "Units In Stock" column and the cell value is "0",
    // draw a callout to the right of this cell.
    if (e.Cell.ColumnIndex == 4 && e.Cell.Value.IsNumeric && e.Cell.Value.NumericValue == 0)
    {
        // Specify callout text.
        string text = "OUT OF STOCK";

        using (Font font = new Font(e.Font.Name, 9f, FontStyle.Bold))
        {
            using (StringFormat format = new StringFormat())
            {
                // Align callout text.
                format.LineAlignment = StringAlignment.Center;
                format.Alignment = StringAlignment.Center;

                // Calculate the callout bounds.
                SizeF size = e.Graphics.MeasureString(text, font, int.MaxValue, format);
                Rectangle textBounds = new Rectangle(
                    e.Bounds.Right + 15,
                    (int)Math.Round(e.Bounds.Top + (e.Bounds.Height - size.Height) / 2),
                    (int)(size.Width + 8),
                    (int)Math.Round(size.Height));

                int middle = (int)Math.Round(textBounds.Height / 2.0);

                Point[] points = new Point[] {
                    new Point(textBounds.Left, textBounds.Top),
                    new Point(textBounds.Left - middle, textBounds.Top + middle),
                    new Point(textBounds.Left, textBounds.Bottom)
                };

                // Draw the callout.
                Brush brush = e.Cache.GetSolidBrush(Color.FromArgb(200, 44, 74));
                e.Graphics.FillPolygon(brush, points);
                e.Cache.FillRectangle(brush, textBounds);
                e.Graphics.DrawString(text, font, e.Cache.GetSolidBrush(Color.White), textBounds, format);
            }
        }
    }
}

private Image ChooseImage(string categoryName)
{
    switch (categoryName)
    {
        case "Beverages":
            return Image.FromFile("images/beverages.png");
        case "Condiments":
            return Image.FromFile("images/condiments.png");
        case "Confections":
            return Image.FromFile("images/confections.png");
        case "Dairy Products":
            return Image.FromFile("images/dairy.png");
        case "Grains/Cereals":
            return Image.FromFile("images/cereals.png");
        case "Meat/Poultry":
            return Image.FromFile("images/meat.png");
        case "Produce":
            return Image.FromFile("images/produce.png");
        case "Seafood":
            return Image.FromFile("images/seafood.png");
    }

    return null;
}

VB.NET

Imports System
Imports System.Drawing
Imports DevExpress.Spreadsheet
Imports DevExpress.XtraSpreadsheet
' ...
Private Sub spreadsheetControl1_CustomDrawCell(ByVal sender As Object, ByVal e As CustomDrawCellEventArgs)
    ' Check whether a cell belongs to the "Category" column.
    If e.Cell.ColumnIndex = 1 Then

        ' Obtain the category name. 
        Dim categoryName As String = e.Cell.Value.ToString()

        ' Return the image that corresponds to the category name. 
        Dim categoryImage As Image = ChooseImage(categoryName)

        ' Specify the image location (the upper-right corner of the cell).
        Dim point As New Point(e.Bounds.Right - 50, e.Bounds.Top)

        ' Draw the category image over the cell.
        If categoryImage IsNot Nothing Then
            e.Graphics.DrawImage(categoryImage, point)
        End If
    End If

    ' If a cell belongs to the "Units In Stock" column and the cell value is "0",
    ' draw a callout to the right of this cell.
    If e.Cell.ColumnIndex = 4 AndAlso e.Cell.Value.IsNumeric AndAlso e.Cell.Value.NumericValue = 0 Then
        ' Specify callout text.
        Dim text As String = "OUT OF STOCK"

        Using font As New Font(e.Font.Name, 9.0F, FontStyle.Bold)
            Using format As New StringFormat()
                ' Align callout text.
                format.LineAlignment = StringAlignment.Center
                format.Alignment = StringAlignment.Center

                ' Calculate the callout bounds.
                Dim size As SizeF = e.Graphics.MeasureString(text, font, Integer.MaxValue, format)
                Dim textBounds As New Rectangle(
                    e.Bounds.Right + 15,
                    CInt(Math.Truncate(Math.Round(e.Bounds.Top + (e.Bounds.Height - size.Height) / 2))),
                    CInt(Math.Truncate(size.Width + 8)),
                    CInt(Math.Truncate(Math.Round(size.Height))))

                Dim middle As Integer = CInt(Math.Truncate(Math.Round(textBounds.Height / 2.0)))

                Dim points() As Point = {
                    New Point(textBounds.Left, textBounds.Top),
                    New Point(textBounds.Left - middle, textBounds.Top + middle),
                    New Point(textBounds.Left, textBounds.Bottom)
                }

                ' Draw the callout.
                Dim brush As Brush = e.Cache.GetSolidBrush(Color.FromArgb(200, 44, 74))
                e.Graphics.FillPolygon(brush, points)
                e.Cache.FillRectangle(brush, textBounds)
                e.Graphics.DrawString(text, font, e.Cache.GetSolidBrush(Color.White), textBounds, format)
            End Using
        End Using
    End If
End Sub

Private Function ChooseImage(categoryName As String) As Image
    Select Case categoryName
        Case "Beverages"
            Return Image.FromFile("images/beverages.png")
        Case "Condiments"
            Return Image.FromFile("images/condiments.png")
        Case "Confections"
            Return Image.FromFile("images/confections.png")
        Case "Dairy Products"
            Return Image.FromFile("images/dairy.png")
        Case "Grains/Cereals"
            Return Image.FromFile("images/cereals.png")
        Case "Meat/Poultry"
            Return Image.FromFile("images/meat.png")
        Case "Produce"
            Return Image.FromFile("images/produce.png")
        Case "Seafood"
            Return Image.FromFile("images/seafood.png")
    End Select

    Return Nothing
End Function

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the CustomDrawCell event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

VB.NET

winforms-spreadsheet-custom-draw-example/VB/CustomDrawExample/Form1.vb#L23

AddHandler spreadsheetControl1.CustomDrawRowHeaderBackground, AddressOf spreadsheetControl1_CustomDrawRowHeaderBackground
AddHandler spreadsheetControl1.CustomDrawCell, AddressOf spreadsheetControl1_CustomDrawCell
AddHandler spreadsheetControl1.CustomDrawCellBackground, AddressOf spreadsheetControl1_CustomDrawCellBackground