Skip to main content

ListBox

WATCH & LEARN0:48 · Animated tutorial
7 scenesPlay, pause, or scrub at your own pace

The Wisej.Web.ListBox control displays a list of strings or data-bound values, allowing the user to select one or multiple options.

info

For a full list of properties, methods and events see the API documentation.

Features​

Label​

The ListBox control supports the inline Label property. This allows an application to set a label in relation to a ListBox control without having to create an additional Label control.

Labels

Data Binding​

Data binding is fully supported, including formatting and conversion of the value, through the default data binding infrastructure.

In addition to binding the value (Text, or SelectedItem or SelectedValue bindable properties), the ListBox control also supports data binding to populate the list using the DataSource property in conjunction with the DisplayMember, ValueMember, ToolTipMember and IconMember properties.

info

You can use DisplayMember, ValueMember, ToolTipMember and IconMember to name which properties to use from objects in the ListBox.Items list without binding to a DataSource.

When ShowToolTips is true, the ListBox reads the property named by ToolTipMember to obtain each item's tooltip text.

Data Binding

Selection Modes​

Use SelectionMode to choose how users can select items:

Selection ModeDescription
NoneNo items can be selected.
OneOnly one item can be selected.
MultiSimpleMultiple items can be selected.
MultiExtendedMultiple items can be selected, and the user can use the SHIFT, CTRL, and arrow keys to make selections.

You can see the different configuration options shown below.

Lazy Loading​

The ListBox control includes lazy loading support. Lazy loading works by sending the minimum number of records to the browser that is required for display within the control.

Lazy loading will significantly reduce waiting times related to rendering on the browser and network congestion caused by transferring large datasets from the server to the client (browser).

Virtual Scrolling​

The ListBox control has the ability to use virtual scrolling, a feature that only renders the list items currently visible in the browser.

Using this option can drastically reduce the amount of time spent rendering in the browser for large datasets. For a List containing 25,000 strings, the effect will be a noticeable difference of several seconds.

Try the following sample code to test the loading times:

private void Page1_Load(object sender, EventArgs e)
{
	var myList = new List<string>();
	
	for (int i=0; i<25000; i++)
	{
		myList.Add($"String {i}");
	}

	this.listBox1.VirtualScroll = true;
	this.listBox1.DataSource = myList;
}

How To​

Populate a List​

There are a few different ways to populate a ListBox control.

You can add a list of strings using the Items property of the ListBox control.

private void button1_Click(object sender, EventArgs e)
{
	this.listBox1.Items.AddRange(new[] {
		"Eggs",
		"Milk",
		"Carrots"
	});
}

Alternatively, you can assign a list of items using the DataSource property of the control.

private void button1_Click(object sender, EventArgs e)
{
	var myList = new List<dynamic>()
	{
		new { id = 1, name = "John" },
		new { id = 2, name = "Jane" },
		new { id = 3, name = "Sally" }
	};

	this.listBox1.ValueMember = "id";
	this.listBox1.DisplayMember = "name";
	
	this.listBox1.DataSource = myList;
}
info

When assigning a list of complex objects to the DataSource or Items property, the objects will be converted into their string representations for display in the ListBox control unless the DisplayMember property is set.

Add an Icon​

Icon

Building off of the previous code snippet, it is easy to add an icon to the ListBox items.

private void button1_Click(object sender, EventArgs e)
{
	var myList = new List<dynamic>()
	{
		new { id = 1, name = "John", icon = "Images/People/1.png" },
		new { id = 2, name = "Jane", icon = "Images/People/2.png" },
		new { id = 3, name = "Sally", icon = "Images/People/3.png" }
	};

	this.listBox1.IconMember = "icon";
	this.listBox1.DisplayMember = "name";
	this.listBox1.DataSource = myList;
}
info

IconMember, DisplayMember, ToolTipMember, and ValueMember identify the item properties used for its icon, display text, tooltip, and selected value, respectively.

The icon paths specified in each object refer to the location of the image relative to the root of the project.

The above code will result in something similar to the following:

Format a String​

Use FormatString to control how the ListBox displays currencies, dates, and other formatted values.

private void button1_Click(object sender, EventArgs e)
{
	var myList = new List<dynamic>()
	{
		new { id = 1, name = "John", payment = 32.53 },
		new { id = 2, name = "Jane", payment = 235.53 },
		new { id = 3, name = "Sally", payment = 45.21 }
	};

	this.listBox1.FormatString = "C2";
	this.listBox1.FormattingEnabled = true;
	this.listBox1.DisplayMember = "payment";
	this.listBox1.DataSource = myList;
}
warning

You only need to specify FormattingEnabled = true when using a DisplayMember.

The result will look something like this (dependent on system currency):

Advanced​

JavaScript Widget​

ItemDescription
Class namewisej.web.ListBox for the ListBox. wisej.web.listbox.ListItem for each list box item.
Theme appearance"list", "listitem" for the items in the list box, see Themes.
ListBox child components"scrollbar-x" is the horizontal scrollbar and "scrollbar-y" is the vertical scrollbar. See JavaScript.
List item child components"checkbox" is the list item's checkbox. "icon" is the list item's icon. See JavaScript.
ToolContainer state"listbox", see Embedded Tools.
Source codehttps://github.com/iceteagroup/wisej-js