BaseListBoxControl.CustomizeItem Event

Allows you to dynamically customize templated items.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v18.2.dll

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.
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 an item template that you can create at design time or in code with the BaseListBoxControl.Templates property.

The CustomizeItem event fires for each templated ListBox item that is about to be displayed. Handle this event to dynamically modify the rendering of certain items.

A template typically consists of one or more elements, each of which can display text and/or image. When handling the CustomizeItem event, you can access template elements with the e.TemplatedItem.Elements collection and modify their text, image, alignment and appearance settings.

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

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the CustomizeItem event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

filteringUiContext-how-to-replace-filtering-template/CS/Templates/TileList.cs#L11

    InitializeComponent();
    Part_Values.CustomizeItem += PART_Values_CustomizeItem;
}

VB.NET

filteringUiContext-how-to-replace-filtering-template/VB/Templates/TileList.vb#L14

    InitializeComponent()
    AddHandler Part_Values.CustomizeItem, AddressOf PART_Values_CustomizeItem
End Sub