BaseListBoxControl.CustomizeItem Event

Allows you to customize templated items dynamically.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v24.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

C#

[DXCategory("Behavior")]
public event CustomizeTemplatedItemEventHandler CustomizeItem

VB.NET

<DXCategory("Behavior")>
Public Event CustomizeItem As CustomizeTemplatedItemEventHandler

Event Data

The CustomizeItem event's data class is CustomizeTemplatedItemEventArgs. The following properties provide information specific to this event:

Property	Description
DataItem	Gets the current item’s underlying data object. For a bound ListBoxControl, the DataItem property returns the corresponding record in the data source.
HtmlElement	Returns the HtmlElement (tag) associated with the current event.
Index	Gets the current item’s visual position. For a bound ListBoxControl, this property’s value matches the index of a corresponding record in the data source.
TemplatedItem	Gets the template used to render the current item. Customize this template when handling the BaseListBoxControl.CustomizeItem event.
Value	Gets the item’s value.

Remarks

A ListBox control can render its items based on HTML-CSS-based or regular item templates that you can create with the BaseListBoxControl.HtmlTemplates and BaseListBoxControl.Templates properties at design time or in code.

The CustomizeItem event fires for each templated ListBox item that is about to be displayed. A template typically consists of one or more elements. You can access and customize these template elements while handling the CustomizeItem event as follows:

Access and Customize Template Elements When You Use HTML-CSS Templates

Use the e.Element event parameter to access HTML elements of the currently processed item. The following methods allow you to retrieve HTML elements by tag, class, and ID:

• Element.FindElementsByTag — Returns a list of HTML elements that have the specified tag.
• Element.FindElementsByClass — Returns a list of HTML elements that are of the specified class.
• Element.FindElementById — Returns an HTML element with the specified ID.

The elements returned by these methods expose properties to change element display settings. The main properties include:

• HtmlElement.Hidden — Allows you to hide (collapse) the element.
• HtmlElement.Disabled — Allows you to disable the element.
• HtmlElement.Style — Allows you to modify CSS style properties applied to the element. This object exposes the SetBackgroundColor, SetForeColor, SetVisibility (displays an empty region instead of the element), and SetProperty methods for this purpose.

Example

The following example changes the background color of a ‘status’ HTML element:

C#

void ListBoxControl1_CustomizeItem(object sender, XtraEditors.CustomizeTemplatedItemEventArgs e) {
    var statusBadge = e.HtmlElement?.FindElementById("status");
    bool online = employeesOnline[e.Index];
    if(statusBadge != null && online)
        statusBadge.Style.SetBackgroundColor("@Green");
}

VB.NET

Private Sub ListBoxControl1_CustomizeItem(ByVal sender As Object, ByVal e As XtraEditors.CustomizeTemplatedItemEventArgs)
    Dim statusBadge = e.HtmlElement?.FindElementById("status")
    Dim online As Boolean = employeesOnline(e.Index)
    If statusBadge IsNot Nothing AndAlso online Then statusBadge.Style.SetBackgroundColor("@Green")
End Sub

See the following demo for complete code:

Run Demo: ListBox Control

Access and Customize Template Elements When You Use Regular Templates

Use the e.TemplatedItem.Elements collection or the e.TemplatedItem.GetElementByName method to access regular template elements. Properties of these elements allow you to modify their text, image, alignment, and appearance settings.

Example

The following example clears the SVG image assigned to the ‘IsCompleted’ element:

C#

void listBoxControl1_CustomizeItem(object sender, CustomizeTemplatedItemEventArgs e) {
    var item = e.DataItem as TodoItem;
    if(!item.IsCompleted)
        e.TemplatedItem.Elements["IsCompleted"].ImageOptions.SvgImage = null;
}

VB.NET

Sub listBoxControl1_CustomizeItem(ByVal sender As Object, ByVal e As CustomizeTemplatedItemEventArgs)
    Dim item = TryCast(e.DataItem, TodoItem)
    If Not item.IsCompleted Then e.TemplatedItem.Elements("IsCompleted").ImageOptions.SvgImage = Nothing
End Sub

Example

This example shows how to use the BaseListBoxControl.CustomizeItem event to dynamically change the visibility and appearance of item elements for a templated ListBoxControl, which is bound to a data source.

The default template that is about to be customized contains four elements.

Three elements (‘CompanyName’, ‘Country’ and ‘City’) are bound to existing fields in the data source, and thus obtain their values automatically. The ‘countryflag’ template element is not bound to any existing field in the bound data source, and thus is not auto-populated with data at runtime by default. If you run the application without additionally customizing the template, you get the following result.

This example handles the BaseListBoxControl.CustomizeItem event to customize individual listbox items:

• Change elements’ foreground color
• Provide images for the ‘countryflag’ element
• Hide text in specific elements

The image below demonstrates the result.

C#

static Image flagGermany = Image.FromFile(@"c:\Data\germanyflag.png");
static Image flagSweden = Image.FromFile(@"c:\Data\swedenflag.png");

Dictionary<string, Color> countrycolors = new Dictionary<string, Color>() {
    {"Germany", Color.Black },
    {"Mexico", Color.Green },
    {"UK", Color.Red }
};

Dictionary<string, Image> countryFlags = new Dictionary<string, Image>() {
    { "Germany", flagGermany},
    { "Sweden", flagSweden}
};

private void listBoxControl1_CustomizeItem(object sender, DevExpress.XtraEditors.CustomizeTemplatedItemEventArgs e) {
    DataRowView row = e.DataItem as DataRowView;
    if (row == null) return;
    // Get the currently processed 'Country'
    string country = row["Country"].ToString(); 
    Color countrycolor = Color.Gray;
    if (countrycolors.ContainsKey(country)) {
        countrycolor = countrycolors[country];
        foreach (TemplatedItemElement element in e.TemplatedItem.Elements) {
            //Set a foreground color for all elements
            element.Appearance.Normal.ForeColor = countrycolor; 
        }
    }
    if (country == "Germany" || country == "Sweden") {
        // Display a custom image in the 'countryflag' template element
        TemplatedItemElement countryflag = e.TemplatedItem.Elements["countryflag"];
        countryflag.ImageOptions.Image = countryFlags[country];
        countryflag.ImageOptions.ImageScaleMode = DevExpress.XtraEditors.TileItemImageScaleMode.Stretch;
        // Hide the 'Country' element's text portion
        e.TemplatedItem.Elements["Country"].Text = ""; 
    }
}

VB.NET

Shared flagGermany As Image = Image.FromFile("c:\Data\germanyflag.png")
Shared flagSweden As Image = Image.FromFile("c:\Data\swedenflag.png")
Private countrycolors As Dictionary(Of String, Color) = New Dictionary(Of String, Color)() From {
        {"Germany", Color.Black},
        {"Mexico", Color.Green},
        {"UK", Color.Red}
    }
Private countryFlags As Dictionary(Of String, Image) = New Dictionary(Of String, Image)() From {
        {"Germany", flagGermany},
        {"Sweden", flagSweden}
    }

Private Sub ListBoxControl1_CustomizeItem(sender As Object, e As DevExpress.XtraEditors.CustomizeTemplatedItemEventArgs) Handles ListBoxControl1.CustomizeItem
    Dim row As DataRowView = TryCast(e.DataItem, DataRowView)
    If row Is Nothing Then Return
    Dim country As String = row("Country").ToString()
    Dim countrycolor As Color = Color.Gray

    If countrycolors.ContainsKey(country) Then
        countrycolor = countrycolors(country)

        For Each element As TemplatedItemElement In e.TemplatedItem.Elements
            element.Appearance.Normal.ForeColor = countrycolor
        Next
    End If

    If country = "Germany" OrElse country = "Sweden" Then
        Dim countryflag As TemplatedItemElement = e.TemplatedItem.Elements("countryflag")
        countryflag.ImageOptions.Image = countryFlags(country)
        countryflag.ImageOptions.ImageScaleMode = TileItemImageScaleMode.Stretch
        e.TemplatedItem.Elements("Country").Text = ""
    End If
End Sub