Skip to main content
All docs
V24.2

DevExpress v24.2 Update — Your Feedback Matters

Our What's New in v24.2 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

BaseListBoxControl.CustomDrawEmptyForeground Event

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

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v24.2.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