The Wisej.Web.ListBox control displays a list of strings or data-bound values, allowing the user to select one or multiple options.
For a full list of properties, methods and events see the API documentation.
Features
Label
The ListBox control supports the inline property. This allows an application to set a label in relation to a ListBox control without having to create an additional Label control.
Data Binding
Data binding is fully supported, including formatting and conversion of the value, through the default 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.
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 the ShowToolTips property is set to true, the ComboBox control uses the name specified in the ToolTipMember to read the tooltip text to display next to each item in the drop down list.
Selection Modes
The ListBox control allows users to define one of several different selection modes for the control's configuration.
Selection Mode
Description
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:
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.
Alternatively, you can assign a list of items using the DataSource property of the control.
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.
IconMember, DisplayMember, ToolTipMember, and ValueMember retrieve and set the properties of the clicked data-bound item to use for the icon, text to display, tooltip text, and click 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
If you are working currencies, dates, or other forms of data, you might want to utilize the FormatString property of the ListBox control.
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
Item
Description
None
No items can be selected.
One
Only one item can be selected.
MultiSimple
Multiple items can be selected.
MultiExtended
Multiple items can be selected, and the user can use the SHIFT, CTRL, and arrow keys to make selections.
Class name
wisej.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.
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;
}
Private Sub Page1_Load(object sender, EventArgs e) Handles Page1.Load
Dim myList As New List(Of String)
For i = 0 To 25000
myList.Add($"String {i}")
Next
Me.listBox1.VirtualScroll = true
Me.listBox1.DataSource = myList
End Sub
Option Strict Off
Private Sub Button1_Click(sender as Object, e As EventArgs) Handles Button1.Click
Me.listBox1.Items.AddRange({
"Eggs",
"Milk",
"Carrots"
})
End Sub
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;
}
Option Strict Off
Private Sub Button1_Click(sender as Object, e As EventArgs) Handles Button1.Click
{
Dim myList As New List(Of Object) From
{
New With { .id = 1, .name = "John"},
New With { .id = 2, .name = "Jane"},
New With { .id = 3, .name = "Sally"}
}
Me.listBox1.ValueMember = "id"
Me.listBox1.DisplayMember = "name"
Ne.listBox1.DataSource = myList
End Sub
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;
}
Option Strict Off
Private Sub Button1_Click(sender as Object, e As EventArgs) Handles Button1.Click
{
Dim myList As New List(Of Object) From
{
New With { .id = 1, .name = "John", .icon = "Images/People/1.png" },
New With { .id = 2, .name = "Jane", .icon = "Images/People/2.png" },
New With { .id = 3, .name = "Sally", .icon = "Images/People/3.png" }
}
Me.listBox1.IconMember = "icon"
Me.listBox1.DisplayMember = "name"
Ne.listBox1.DataSource = myList
End Sub
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;
}
Option Strict Off
Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
Dim myList As New List(Of Object) From
{
New With { .id = 1, .name = "John", .payment = 32.53 }
New With { .id = 2, .name = "Jane", .payment = 235.53 }
New With { .id = 3, .name = "Sally", .payment = 45.21 }
}
Me.listBox1.FormatString = "C2"
Me.listBox1.FormattingEnabled = true
Me.listBox1.DisplayMember = "payment"
Me.listBox1.DataSource = myList
End Sub
For a full list of properties, methods and events see the API documentation.
Features
Checkbox
Each item within the CheckedListBox control has a checkbox on the left side of it.
Similar to DisplayMember, ValueMember, etc. The CheckedListBox control contains a property, CheckStateMember, that defines the property of the data source or list that sets the check state for each item.
The CheckOnClick property of the CheckedListBox control can also be set to accept check state changes on a list item.
How To
Apply Checkboxes
Adding Checkboxes to the CheckedListBox control is easy. See the following code snippet:
The above code snippet results in:
Advanced
JavaScript Widget
Item
Description
Class name
wisej.web.CheckedListBox for the CheckedListBox. 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 checkbox shown in each list item. "icon" is the icon shown in each list item. See JavaScript.
private void Page1_Load(object sender, EventArgs e)
{
var myGroceries = new List<dynamic>() {
new { name = "Eggs", price = 1.00, purchased = true },
new { name = "Apples", price = 0.50, purchased = false },
new { name = "Milk", price = 2.00, purchased = true },
new { name = "Juice", price = 3.00, purchased = false }
};
this.checkedListBox1.DataSource = myGroceries;
this.checkedListBox1.DisplayMember = "name";
this.checkedListBox1.CheckStateMember = "purchased";
}
Private Sub Page1_Load(ByVal sender As Object, ByVal e As EventArgs)
Dim myGroceries = New List(Of Object)() From {
New With {
.name = "Eggs",
.price = 1.0,
.purchased = True
},
New With {
.name = "Apples",
.price = 0.5,
.purchased = False
},
New With {
.name = "Milk",
.price = 2.0,
.purchased = True
},
New With {
.name = "Juice",
.price = 3.0,
.purchased = False
}
}
Me.checkedListBox1.DataSource = myGroceries
Me.checkedListBox1.DisplayMember = "name";
Me.checkedListBox1.CheckStateMember = "purchased";
End Sub
