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

C#

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

VB.NET

<DXCategory("Appearance")>
Public Event CustomDrawEmptyForeground As EventHandler(Of ListBoxDrawEmptyForegroundEventArgs)

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

C#

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);
}

VB.NET

Private Sub listBoxControl1_CustomDrawEmptyForeground(ByVal sender As Object, ByVal e As ListBoxDrawEmptyForegroundEventArgs)
    e.Appearance.TextOptions.HAlignment = DevExpress.Utils.HorzAlignment.Center
    e.Appearance.DrawString(e.Cache, "No items", e.Bounds)
End Sub

Example 2 - Render HTML Template

C#

// 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"
            });
    }
}

HTML

<div class="container">
    <div class="title">There are no items in the ListBox control</div>
    <div class="button" id="btnAdd">Add Items</div>
</div>

CSS

.container {
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center;
    height: 100%;
}

.title {
    font-size: 14px;
}

.button {
    background-color: @green;
    color: @white;
    opacity: 0.8;
    border: 1px solid @green;
    border-radius: 4px;
    padding: 8px 18px;
    font-size: 13px;
    margin: 8px;
    text-align: center;
    cursor: pointer;
}
    .button:hover {
        background-color: @green;
        box-shadow: 0px 0px 3px @green;
        opacity: 0.9;
    }

Run Demo