LayoutControl.CustomDraw Event

Allows you to custom paint individual items in the LayoutControl.

Namespace: DevExpress.XtraLayout

Assembly: DevExpress.XtraLayout.v24.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

C#

[DXCategory("CustomDraw")]
public virtual event EventHandler<ItemCustomDrawEventArgs> CustomDraw

VB.NET

<DXCategory("CustomDraw")>
Public Overridable Event CustomDraw As EventHandler(Of ItemCustomDrawEventArgs)

Event Data

The CustomDraw event's data class is DevExpress.XtraLayout.ItemCustomDrawEventArgs.

Remarks

To custom paint a certain item, you can handle the LayoutControl.CustomDraw or BaseLayoutItem.CustomDraw event. The LayoutControl.CustomDraw event fires repeatedly for each layout item within the LayoutControl, while the BaseLayoutItem.CustomDraw event only fires for the source layout item. LayoutGroups allow you to custom paint their captions and backgrounds separately using the dedicated LayoutGroup.CustomDrawCaption and LayoutGroup.CustomDrawBackground events. The LayoutControl.CustomDraw and BaseLayoutItem.CustomDraw events also fire for LayoutGroups (LayoutGroups are BaseLayoutItem descendants). While handling the CustomDraw events for LayoutGroups, you can use the event arguments to identify the text and client area bounds and paint these areas manually.

Custom draw events allow you to:

• Paint an item manually.
• Invoke the default painting mechanism for an item (during or after event execution).
• Change the item’s paint information and then invoke the default painting mechanism.

The Layout Control’s custom draw events provide the DefaultDraw method (accessible from the event arguments), which allows you to invoke the default painting mechanism for the currently processed item during event execution. There is also another implicit way to invoke the default painting mechanism. If the event’s Handled parameter is set to false (the default value), the default painting mechanism will automatically be invoked after your custom draw event handler is completed. Note that the default painting mechanism overrides all rendering you may have performed previously. The DefaultDraw method automatically sets the Handled parameter to true, to prevent the default painting mechanism from being invoked again after event execution. However, if you paint an element manually and do not use the DefaultDraw method, you should manually set the Handled parameter to true.

To custom paint items, use the methods provided by the event’s Cache parameter. To retrieve various paint information (including the item’s bounds) use the event’s ViewInfo parameter (in certain custom draw events, this information is accessible from the Info parameter.

Example

The following example handles the CustomDraw event to custom paint an item’s background, draw a custom image for another item, and change the text color for a third item. The DefaultDraw method is called to perform the default item painting. The Handled parameter set to true ensures that no default painting is invoked after your CustomDraw event handler is executed.

For the third item, the text color is changed to red. Note that this item is not manually painted in the CustomDraw event handler. The Handled parameter is set to false to paint the item using the default painting mechanism after your CustomDraw event handler is performed.

C#

using DevExpress.Utils;
using DevExpress.Utils.Design;

Random rnd = new Random();

private void layoutControl1_CustomDraw(object sender, DevExpress.XtraLayout.ItemCustomDrawEventArgs e) {
    if (e.Item.Text.StartsWith("Name")) {
        e.DefaultDraw();
        int hue = rnd.Next(256);
        // Paint the item's background with a shade of gray.
        using(var fillBrush = new SolidBrush(Color.FromArgb(50, hue, hue, hue)))
            e.Cache.FillRectangle(fillBrush, e.Bounds);
        e.Handled = true; //This statement is superfluous, since the DefaultDraw method automatically sets the Handled parameter to true.
    }

    if (e.Item.Text.StartsWith("Notes")) {
        e.DefaultDraw();
        // Draw an image at the item's top left corner. The image may overlap the item's text in the case of insufficient item height.
        Image img = DxImageAssemblyUtil.ImageProvider.GetImage("warning", ImageSize.Size16x16, ImageType.Colored);
        Point pt = e.ViewInfo.TextAreaRelativeToControl.Location;
        e.Cache.DrawImage(img, pt);
        e.Handled = true; //This statement is superfluous, since the DefaultDraw method automatically sets the Handled parameter to true.
    }

    if (e.Item.Text.StartsWith("Phone")) {
        // Change the color of the item's text and allow the default painting mechanism to paint this text.
        e.Item.AppearanceItemCaption.ForeColor = Color.Red;
        e.Handled = false; // //This statement is superfluous, since the Handled parameter is set to false by default.
    }
}