List Box

In This Topic

The list box is a widget that allows the user to select one or more items from a scrollable list. The items of the list box can be accessed and manipulated through its Items collection. Just like the combo box, the list box provides two methods for quickly filling it with items - FillFromEnum and FillFromArray. These methods automatically create a list box item for each enum/array value and assign the value to the Tag property of the created list box item, so that you can easily identify the value a selected list box item corresponds to.

Selection

The Selection property of the list box provides information about the current selection of the list box and helps the user control several selection related properties. It exposes the following properties:

Mode - specifies the selection mode. Can be Single and Multiple. When set to Multiple, the user can hold the Ctrl or Shift keys to select multiple items.
SelectedCount - gets the number of selected items.
SelectedItems - gets a list that contains t he selected items.
FirstSelected - gets the first selected item. The value of this property is null if no items are selected. This is the most commonly used method when the list box is in Single selection mode, because it returns the first selected item of the list box which in this mode is the only one or null if there isn't any item selected.
LastSelected - gets the last selected item. The value of this property is null if no items are selected.

The list box selection provides the following events:

Selected - occurs when an item has been selected. This is the most commonly used selection event.
Deselected - occurs when an item has been deselected.
UpdateStarted - occurs when the selection is going to be updated.
UpdateEnded - occurs when the selection has been updated.

Scrolling

Quite often a list box will contain more items than it can display. In such cases the list box will show a vertical scrollbar by default and some items not be rendered. The user will have to scroll down/up in order to see them. If you want to make sure a given item is visible you can take advantage of the EnsureVisible(NListBoxItem item) method.

The IntegralVScroll property determines whether the vertical scrollbar will scroll by discrete item height or not. By default set to true.

When needed, you can control the horizontal and vertical scroll mode of the list box respectively using its HScrollMode and VScrollMode properties. The supported modes are:

ENScrollMode	Description
Never	Scrollbars are never shown.
Always	Scrollbars are always shown.
WhenNeeded	Scrollbars are shown only when needed. This is the default value.

List Box Items

The list box item is a content element, i.e. a widget that can host another widget as its content. This makes it possible to easily create complex list box items. To do so you should create a widget to host the desired content and pass it to the NListBoxItem constructor. The following example demonstrates how to create a checkable list box item with image and text:

Advanced List Box Item	Copy Code
NStackPanel stack = new NStackPanel(); stack.Direction = ENHVDirection.LeftToRight; stack.HorizontalSpacing = 3; stack.Add(new NCheckBox()); NImage image = new NImage(new NUri(@"C:\MyImage.png")); stack.Add(new NImageBox(image)); stack.Add(new NLabel("Item " + i.ToString())); NListBoxItem item = new NListBoxItem(stack);

Advanced List Box Item

Copy Code

NStackPanel stack = new NStackPanel();
stack.Direction = ENHVDirection.LeftToRight;
stack.HorizontalSpacing = 3;
 
stack.Add(new NCheckBox());
NImage image = new NImage(new NUri(@"C:\MyImage.png"));
stack.Add(new NImageBox(image));
stack.Add(new NLabel("Item " + i.ToString()));
NListBoxItem item = new NListBoxItem(stack);

If you want to know if a given list box item is currently selected or not in its owner list box, you can check its Selected property. To get the list box that contains the given list box item, use its OwnerListBox property.

Code Examples

If you want to get the first selected item, you can use the following line of code:

List Box Selected Item	Copy Code
NListBoxItem firstSelectedItem = listBox.Selection.FirstSelected;

The example below demonstrates how to create a simple list box and how to subscribe to and handle its Selected and Deselected events:

List Box Selection Handling	Copy Code
NListBox listBox = new NListBox(); for (int i = 1; i <= 10; i++) { listBox.Items.Add(new NListBoxItem("Item " + i.ToString())); } listBox.Selection.Mode = ENSelectionMode.Multiple; listBox.Selection.Selected += new Function<NSelectEventArgs<NListBoxItem>>(OnItemSelected); listBox.Selection.Deselected += new Function<NSelectEventArgs<NListBoxItem>>(OnItemDeselected); private void OnItemSelected(NSelectEventArgs<NListBoxItem> arg1) { NListBoxItem selectedItem = arg1.Item; } private void OnItemDeselected(NSelectEventArgs<NListBoxItem> arg1) { NListBoxItem deselectedItem = arg1.Item; }

List Box Selection Handling

Copy Code

NListBox listBox = new NListBox();
for (int i = 1; i <= 10; i++)
{
    listBox.Items.Add(new NListBoxItem("Item " + i.ToString()));
}
 
listBox.Selection.Mode = ENSelectionMode.Multiple;
listBox.Selection.Selected += new Function<NSelectEventArgs<NListBoxItem>>(OnItemSelected);
listBox.Selection.Deselected += new Function<NSelectEventArgs<NListBoxItem>>(OnItemDeselected);
 
private void OnItemSelected(NSelectEventArgs<NListBoxItem> arg1)
{
    NListBoxItem selectedItem = arg1.Item;
}
private void OnItemDeselected(NSelectEventArgs<NListBoxItem> arg1)
{
    NListBoxItem deselectedItem = arg1.Item;
}