windowsforms-devexpress-dot-xtraeditors-dot-baselistboxcontrol-8372e9f9.md
Allows you to customize templated items dynamically.
Namespace : DevExpress.XtraEditors
Assembly : DevExpress.XtraEditors.v25.2.dll
NuGet Package : DevExpress.Win.Navigation
[DXCategory("Behavior")]
public event CustomizeTemplatedItemEventHandler CustomizeItem
<DXCategory("Behavior")>
Public Event CustomizeItem As CustomizeTemplatedItemEventHandler
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. |
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:
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.The following example changes the background color of a ‘status’ HTML element:
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");
}
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:
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.
The following example clears the SVG image assigned to the ‘IsCompleted’ element:
void listBoxControl1_CustomizeItem(object sender, CustomizeTemplatedItemEventArgs e) {
var item = e.DataItem as TodoItem;
if(!item.IsCompleted)
e.TemplatedItem.Elements["IsCompleted"].ImageOptions.SvgImage = null;
}
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
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:
The image below demonstrates the result.
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 = "";
}
}
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
See Also