Skip to main content
All docs
V24.1

BaseListBoxControl.CustomDrawEmptyForeground Event

Allows you to draw custom content within the empty list box.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v24.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

[DXCategory("Appearance")]
public event EventHandler<ListBoxDrawEmptyForegroundEventArgs> CustomDrawEmptyForeground

Event Data

The CustomDrawEmptyForeground event's data class is DevExpress.XtraEditors.ListBoxDrawEmptyForegroundEventArgs.

Remarks

The CustomDrawEmptyForeground event fires when the list box has no items (the Items collection or data source is empty). Handle this event to display custom content within the list box. You can use the custom draw API, or render an HTML template within the list box.

Example 1 - Custom Draw API

WinForms ListBox - Custom Draw API, DevExpress

private void listBoxControl1_CustomDrawEmptyForeground(object sender, ListBoxDrawEmptyForegroundEventArgs e) {
    e.Appearance.TextOptions.HAlignment = DevExpress.Utils.HorzAlignment.Center;
    e.Appearance.DrawString(e.Cache, "The ListBox is empty.", e.Bounds);
}

Example 2 - Render HTML Template

WinForms ListBox - Display Custom Content, DevExpress

// Local painting context that contains HTML tree state.
DxHtmlPainterContext ctx = new DxHtmlPainterContext();

// Draw HTML template.
HtmlTemplate htmlTemplate = new HtmlTemplate(LoadTemplate("ListBoxEmptyForeground.html"), LoadTemplate("ListBoxEmptyForeground.css"));
private void listBoxControl1_CustomDrawEmptyForeground(object sender, ListBoxDrawEmptyForegroundEventArgs e) {
    e.DrawHtml(htmlTemplate, ctx);
}

static string LoadTemplate(string fileName) {
    return File.ReadAllText(fileName);
}

private void listBoxControl1_MouseMove(object sender, MouseEventArgs e) {
    ListBoxControl listControl = sender as ListBoxControl;
    if(listControl.ItemCount == 0) {
        ctx.OnMouseMove(e);
        listControl.Cursor = ctx.GetCursor(e.Location);
        listControl.Invalidate();
    } else listControl.Cursor = Cursors.Default;
}

// Handle the 'Add Items' button's click to add items.
// You can add items to the 'Items' collection or bind the list box to a data source.
private void listBoxControl1_MouseDown(object sender, MouseEventArgs e) {
    ListBoxControl listControl = sender as ListBoxControl;
    if(listControl.ItemCount == 0 && e.Button == MouseButtons.Left) {
        var clickInfo = ctx.CalcHitInfo(e.Location);
        if(clickInfo != null && clickInfo.ParentHasId("btnAdd"))
            listControl.Items.AddRange(new string[] {
                "Item 1",
                "Item 2",
                "Item 3"
            });
    }
}

Run Demo

See Also