Log In
[Expand]General Information
[Collapse]WinForms Controls
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Collapse]Editors and Simple Controls
    Templated ListBox Items
   [Expand]Simple Editors
   [Expand]Lookup Editors
   [Expand]Token Edit Control
   [Expand]Breadcrumb Edit Control
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Report Server
[Expand]eXpressApp Framework
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Templated ListBox Items

You can choose between two rendering approaches when displaying multiple text and image elements in items in ListBox controls (ListBoxControl, CheckedListBoxControl, and ImageListBoxControl):

  • Custom painting - Allows you to paint each item with the BaseListBoxControl.DrawItem event manually. With this approach, you need to calculate each element's position and size and draw these elements manually in code.
  • Item templates - Allows you to define an item pattern at design time (or in code) the Listbox control uses to render its items .

    The item template allows each item to display values from multiple data source fields when you bind your Listbox control to a data source. The dedicated Item Template Designer helps you access these data source fields and arrange them as required.

Expanded Item Template Capabilities

  • The item template can consist of any number of text and image elements. You can display images in all Listbox controls, not only in the ImageListBoxControl.
  • The dedicated Item Template Designer provides the capability to set up the item template at design time.
  • Dynamic customization of templated items at runtime with the BaseListBoxControl.CustomizeItem event.
  • Create multiple item templates and substitute them at runtime with the BaseListBoxControl.CustomItemTemplate event.
  • Bound and unbound elements in the item template. Unbound elements are used to display static text and images. Using bound elements, you can display data from underlying data source fields.
  • Multiple alignment options for template elements, including alignment relative to other elements, and specifying absolute or relative element sizes.
  • Customize the appearance (font attributes and colors) of certain elements using corresponding properties.

Expanded Invoke Item Template Designer

Click the Listbox control's smart tag and select the Edit Item Templates command.

This opens the Item Template Designer. The designer prompts you to create a new one if there are no existing templates.

Once you provide a name for the new template, the Item Template Designer shows the template design surface.

When the control is bound at design time, the Columns list provides access to the available data source fields.

  • Columns list - Displays fields from the data source currently bound to the ListBox control. If the ListBox control is not currently bound, the Columns list only displays the DisplayMember item (this identifies a listbox item's default text content).
  • Elements list - Displays existing template elements. You can add and delete elements using the buttons at the top. You can also add elements by dragging fields from the Columns list onto the design surface.
  • Properties grid - Allows you to modify the selected element's settings.

Expanded Set Up Item Template

The item template is set up based on the common Table Layout concept, in which the design surface is divided into logical columns and rows, and the contents are placed in corresponding cells (which can be merged if required).

The supported template customization actions include:
  • Drag-and-drop fields from the Columns list onto table cells.

    When you drop a field onto a cell, it automatically creates a bound template element.

  • Drag-and-drop created elements between cells.
  • Placing multiple elements in the same cell and providing different alignment options for these elements to prevent overlapping.
  • Merging cells by selecting them with the mouse and then clicking the Merge button.
  • Unmerging previously merged cells using the Unmerge button.
  • Resizing cells using the mouse
  • Resizing the item template with the mouse by dragging its edges.
  • Adding/removing columns and rows using the buttons and context menu.

  • Selecting a cell (by clicking it) and customizing the cell's size, size type (absolute or relative) and padding in the Property Grid.

  • Accessing a dropped element (by clicking it) and customizing its settings in the Property Grid.

  • Manipulating the element collection via the Elements list. For instance, you can add unbound elements. When an element is created, it is automatically added to the template.
  • Support for multiple templates.

Expanded Multiple Item Templates

A template created in the designer is added to the BaseListBoxControl.Templates collection. The first template in this collection becomes the active one, and it is used to render all items (by default).

You can create more templates and apply them to different items or in different cases. For instance, you can create two item templates ("compact" providing less information, and "detailed" providing more details) and switch between them depending on the control's width.

To create multiple item templates, use the Save As button (), which saves a copy of the current template with a different name. You can then modify the new template and save the changes.

To dynamically provide templates for items, handle the BaseListBoxControl.CustomItemTemplate event.

Expanded Item Height

When you resize an item template vertically, you change the item's height in the BaseListBoxControl.ItemHeight property. All item templates share this setting.

All items in the ListBox control have the same item height by default (BaseListBoxControl.ItemHeight). If you need to provide different heights for different items, handle the BaseListBoxControl.MeasureItem event.

How would you rate this topic?​​​​​​​