BaseListBoxControl.CustomizeItem Event
Allows you to dynamically customize templated items.
Namespace: DevExpress.XtraEditors
Assembly: DevExpress.XtraEditors.v21.2.dll
NuGet Packages: DevExpress.Win.Design, DevExpress.Win.Navigation
Declaration
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.
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 = "";
}
}