Custom Draw Scenarios

Apr 11, 2022
5 minutes to read

Custom draw events provide complete control over the appearance of the control’s elements. This document covers the main scenarios for custom draw event usage.

Note

Custom draw events do not allow you to change the appearance of a printed/exported version of the Tree List.

The TreeList’s custom draw events can be handled to implement the following scenarios.

Manual Element Rendering
Combining Default Painting and Custom Painting
Customizing Element Display Information for Default Rendering

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.

Example

The following example custom paints column headers, summary footer, footer cells and indicator cells via the TreeList.CustomDrawColumnHeader, TreeList.CustomDrawFooter, TreeList.CustomDrawFooterCell and TreeList.CustomDrawNodeIndicator events.

Three functions are declared that implement custom painting. These are used to draw the background of the raised and sunken elements, and to paint the text with the predefined alignment within elements.

The image below shows the result.

C#
VB.NET

csharp

using System.Drawing.Drawing2D;
using DevExpress.XtraTreeList;
//...

// Custom paints the column headers.
private void treeList1_CustomDrawColumnHeader(object sender, DevExpress.XtraTreeList.CustomDrawColumnHeaderEventArgs e) {
    if (e.Pressed)
        paintSunkenBackground(e);
    else
        paintRaisedBackground(e);
    if (e.ColumnType == HitInfoType.Column)
        paintHAlignedText(e, e.Column.GetCaption(), StringAlignment.Near);
    e.Handled = true;
}

// Custom paints the summary footer.
private void treeList1_CustomDrawFooter(object sender, DevExpress.XtraTreeList.CustomDrawEventArgs e) {
    paintRaisedBackground(e);
    e.Handled = true;
}

// Custom paints the cells of the summary footer.
private void treeList1_CustomDrawFooterCell(object sender, DevExpress.XtraTreeList.CustomDrawFooterCellEventArgs e) {
    if (e.Text == String.Empty) return;
    paintSunkenBackground(e);
    paintHAlignedText(e, e.Text, StringAlignment.Far);
    e.Handled = true;
}

// Custom paints the indicator cells.
private void treeList1_CustomDrawNodeIndicator(object sender, DevExpress.XtraTreeList.CustomDrawNodeIndicatorEventArgs e) {
    paintRaisedBackground(e);
    e.Handled = true;
}

// Custom draw methods:

// Paints the background of raised elements.
private void paintRaisedBackground(CustomDrawEventArgs e)
{
    Brush brush = e.Cache.GetGradientBrush(e.Bounds, Color.Yellow, Color.Gold, LinearGradientMode.Vertical);
    e.Cache.FillRectangle(brush, e.Bounds);
    e.Cache.DrawRectangle(e.Cache.GetPen(Color.LightGray), e.Bounds);
}

// Paints the background of sunken elements.
private void paintSunkenBackground(CustomDrawEventArgs e)
{
    Brush brush = e.Cache.GetGradientBrush(e.Bounds, Color.CornflowerBlue, Color.LightGray, LinearGradientMode.Vertical);
    e.Cache.FillRectangle(brush, e.Bounds);
    e.Cache.DrawRectangle(e.Cache.GetPen(Color.LightGray), e.Bounds);
}

// Paints the aligned text.
private void paintHAlignedText(CustomDrawEventArgs e, String text, StringAlignment align)
{
    Brush textBrush = e.Cache.GetSolidBrush(Color.Black);

    StringFormat outStringFormat = e.Appearance.GetStringFormat();
    outStringFormat.Alignment = align;
    outStringFormat.LineAlignment = StringAlignment.Center;
    outStringFormat.FormatFlags = StringFormatFlags.NoWrap;
    outStringFormat.Trimming = StringTrimming.EllipsisCharacter;

    e.Cache.DrawString(text, e.Appearance.Font, textBrush, e.Bounds, outStringFormat);
}

Imports System.Drawing.Drawing2D
Imports DevExpress.XtraTreeList
'...

' Custom paints the column headers.
Private Sub TreeList1_CustomDrawColumnHeader(ByVal sender As Object, ByVal e As DevExpress.XtraTreeList.CustomDrawColumnHeaderEventArgs) _
Handles TreeList1.CustomDrawColumnHeader
    If e.Pressed Then
        paintSunkenBackground(e)
    Else
        paintRaisedBackground(e)
    End If
    If e.ColumnType = HitInfoType.Column Then
        paintHAlignedText(e, e.Column.GetCaption(), StringAlignment.Near)
    End If
    e.Handled = True
End Sub

' Custom paints the summary footer.
Private Sub TreeList1_CustomDrawFooter(ByVal sender As Object, ByVal e As DevExpress.XtraTreeList.CustomDrawEventArgs) _
Handles TreeList1.CustomDrawFooter
    paintRaisedBackground(e)
    e.Handled = True
End Sub

' Custom paints the cells of the summary footer.
Private Sub TreeList1_CustomDrawFooterCell(ByVal sender As Object, ByVal e As DevExpress.XtraTreeList.CustomDrawFooterCellEventArgs) _
Handles TreeList1.CustomDrawFooterCell
    If e.Text = String.Empty Then
        Return
    End If
    paintSunkenBackground(e)
    paintHAlignedText(e, e.Text, StringAlignment.Far)
    e.Handled = True
End Sub

' Custom paints indicator cells.
Private Sub TreeList1_CustomDrawNodeIndicator(ByVal sender As Object, ByVal e As DevExpress.XtraTreeList.CustomDrawNodeIndicatorEventArgs) _
Handles TreeList1.CustomDrawNodeIndicator
    paintRaisedBackground(e)
    e.Handled = True
End Sub

' Custom draw methods:

' Paints the background of raised elements.
Private Sub paintRaisedBackground(ByVal e As CustomDrawEventArgs)
    Dim brush As Brush = e.Cache.GetGradientBrush(e.Bounds, Color.Yellow, Color.Gold, LinearGradientMode.Vertical)
    e.Cache.FillRectangle(brush, e.Bounds)
    e.Cache.DrawRectangle(e.Cache.GetPen(Color.LightGray), e.Bounds)
End Sub

' Paints the background of sunken elements.
Private Sub paintSunkenBackground(ByVal e As CustomDrawEventArgs)
    Dim brush As Brush = e.Cache.GetGradientBrush(e.Bounds, Color.CornflowerBlue, Color.LightGray, LinearGradientMode.Vertical)
    e.Cache.FillRectangle(brush, e.Bounds)
    e.Cache.DrawRectangle(e.Cache.GetPen(Color.LightGray), e.Bounds)
End Sub

' Paints the aligned text.
Private Sub paintHAlignedText(ByVal e As CustomDrawEventArgs, ByVal text As String, ByVal align As StringAlignment)
    Dim textBrush As Brush = e.Cache.GetSolidBrush(Color.Black)

    Dim outStringFormat As StringFormat = e.Appearance.GetStringFormat()
    outStringFormat.Alignment = align
    outStringFormat.LineAlignment = StringAlignment.Center
    outStringFormat.FormatFlags = StringFormatFlags.NoWrap
    outStringFormat.Trimming = StringTrimming.EllipsisCharacter

    e.Cache.DrawString(text, e.Appearance.Font, textBrush, e.Bounds, outStringFormat)
End Sub