Home

List-Based Controls: List Boxes

 

Fundamentals of List Boxes

 

Introduction

A list box presents a list of items to choose from. Each item displays on a line. The user makes a selection by clicking in the list. Once clicked, the item or line on which the mouse landed becomes highlighted, indicating that it is the current choice. Here is an example:

The Commands tab of the Customize dialog box of Microsoft Access

After an item has been selected, to make a different selection, the user would click another. The new clicked item becomes selected or highlighted; the previously selected item looses its highlighting attribute. The user can also change the selection by pressing the up or down arrow keys.

List boxes are categorized in two types: single and multi-selection. The second category allows a user to select more than one item by pressing Ctrl to select items at random or by pressing Shift to select items in a range.

One of the main reasons for using a list box is to display a list of items to the user. Sometimes the list would be very large. If the list is longer than the available client area of the control, the control would be equipped with a scroll bar that allows the user to navigate up and down to access all items of the list. You will have the option of deciding how many items to display on the list.

Creating a List Box

To support list boxes, the .NET Framework provides the ListBox class. To programmatically create a list box, declare a variable of type ListBox and add it to the Controls property of its eventual container. Here is an example:

open System
open System.Drawing
open System.Windows.Forms

let exercise : Form = new  System.Windows.Forms.Form()
exercise.Text <- "Family"
exercise.StartPosition <- FormStartPosition.CenterScreen

let lbxFamily : ListBox = new ListBox()

exercise.Controls.Add lbxFamily

do
    Application.Run exercise
Author Note In our applications, the names of the list-based controls will be in plural. This is not a rule and it is not based on any preconceived standard.
 

The Items of a List Box

 

Adding Items to a List Box

The most important characteristic of a list box is the list of items it contains. This list is represented by the Items property. The Items list is created and managed by a ListBox-nested class named ObjectCollection. ObjectCollection is a collection class that implements the IList, the ICollection, and the IEnumerable interfaces.

To add an item to the list, access the Items property, call its Add() method, and pass the new item. You can do this continually for each item. Here are examples:

open System
open System.Drawing
open System.Windows.Forms

let exercise : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
exercise.Text <- "Family"
exercise.ClientSize <- new System.Drawing.Size(125, 83)
exercise.StartPosition <- FormStartPosition.CenterScreen

let lbxFamily : ListBox = new ListBox()
lbxFamily.Location <- new Point(12, 12)
lbxFamily.Size <- new System.Drawing.Size(100, 60)

lbxFamily.Items.Add "Son" |> ignore
lbxFamily.Items.Add "Daughter" |> ignore
lbxFamily.Items.Add "Father" |> ignore
lbxFamily.Items.Add "Mother" |> ignore

exercise.Controls.Add(lbxFamily)

do
    Application.Run exercise

This would produce:

Adding Items to a List Box

 To insert a new item somewhere inside of the list, call the Insert() method.

Selecting an Item in a List Box

To use an item from a list box, the user must locate and click the desired item. That item is said to have been selected. To programmatically select an item, you can assign the index of the desired item to the ListBox.SelectedIndex property. The indices of the items of a list box are stored in a zero-based array. This means that the first item has an index of 0, the second has an index of 1, and so on. Here is an example that will select the fourth item of  the list:

open System
open System.Drawing
open System.Windows.Forms

let exercise : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
exercise.Text <- "Family"
exercise.ClientSize <- new System.Drawing.Size(125, 83)
exercise.StartPosition <- FormStartPosition.CenterScreen

let lbxFamily : ListBox = new ListBox()
lbxFamily.Location <- new Point(12, 12)
lbxFamily.Size <- new System.Drawing.Size(100, 60)

lbxFamily.Items.Add "Son" |> ignore
lbxFamily.Items.Add "Daughter" |> ignore
lbxFamily.Items.Add "Father" |> ignore
lbxFamily.Items.Add "Mother" |> ignore

lbxFamily.SelectedIndex <- 2

exercise.Controls.Add(lbxFamily)

do
    Application.Run exercise

This would produce:

Selecting an Item in a List Box

After an item has been selected, to find out the index of the item that is currently selected, get the value of the ListBox.SelectedIndex property.

To select an item, the user can click it in the list box. When an item has been clicked, the list box fires a SelectedIndexChanged event. Because selecting an item is the most regularly performed operation on a list box, SelectedIndexChanged is the default event of a list box. This event is of type EventArgs which means that it does not provide any significant information other than to let you know that an item has been selected. Nonetheless, this event allows you to easily check if an item has been selected and what item has been selected.
To fire a SelectedIndexChanged event and to test what item has been selected in the list, you can double-click the list box.

The ListBox.SelectedIndex property allows you either to select an item or to find out what item is selected, using its index, that is, the numeric position of the item in the list. If you know the identity, such as the name, of the item you want to select, or if you want to identify the selected item based on its name, you can use the ListBox.SelectedItem property instead. This member identifies the item instead of locating it.

Selecting Multiple Items in a List Box

By default, the user can select only one item in the list. If you want the user to be able to select more than one item, change the value of the SelectionMode property. This property is based on the SelectionMode enumeration. After the user has selected more than one item, to get the indexes of the items that are selected, you can access the ListBox.SelectedIndices property which holds that list.

Removing Items From a List Box

If you have an undesired item in a list box, you can remove it. To support this operation, the ObjectCollection class is equipped with the Remove() method. When calling it, pass the name of the item as argument. This means that you must know the item you are trying to delete. If you call this method, the compiler would look for the item in the list. If the item is found, it would be deleted.

Instead of removing an item by its name or identification, you can use its position. To do that, you can call the RemoveAt() method and pass the zero-based index of the undesired item. If the index is valid, the item would be deleted from the list.

To remove all items from the list, you can call the Clear() method.

 
   
 

Characteristics of a List Box

 

A Sorted List Box

After creating the list, by default, each item assumes the position it received when it was added. If you want, you can rearrange them in ascending order. To do this, set the ListBox.Sorted Boolean property to true. If you create an unsorted list, then at one time get it sorted (for example, you can give the user the ability to sort the list, by clicking a button), the list would be sorted. If an item is added to the sorted list, the compiler would automatically insert it to the right position following the alphabetical, ascending, or chronological order. If at another time you allow the user to "unsort" the list, the list would keep its current order. If another item is added when the list is not sorted, the item would be positioned at the end of the list. If you want the list to have its original state, you would have to reset it through code.

The Scroll Bars

If you provide a longer list than the list box' height can display, it would have a vertical scroll bar. Here is an example:

open System
open System.Drawing
open System.Windows.Forms

let exercise : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
exercise.Text <- "Family"
exercise.ClientSize <- new System.Drawing.Size(125, 97)
exercise.StartPosition <- FormStartPosition.CenterScreen

let lbxFamily : ListBox = new ListBox()
lbxFamily.Location <- new Point(12, 12)
lbxFamily.Size <- new System.Drawing.Size(100, 80)

lbxFamily.Items.Add "Son" |> ignore
lbxFamily.Items.Add "Daughter" |> ignore
lbxFamily.Items.Add "Father" |> ignore
lbxFamily.Items.Add "Mother" |> ignore
lbxFamily.Items.Add "Niece" |> ignore
lbxFamily.Items.Add "Nephew" |> ignore
lbxFamily.Items.Add "Uncle" |> ignore

exercise.Controls.Add(lbxFamily)

do
    Application.Run exercise

This would produce:

A List Box With a Vertical Scroll Bar

Consider the following example:

open System
open System.Drawing
open System.Windows.Forms

let bookCollection : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
bookCollection.Text <- "Book Collection"
bookCollection.StartPosition <- FormStartPosition.CenterScreen

let lblTitle = new Label();
lblTitle.Text <- "Book Titles"
lblTitle.Location <- new Point(12, 12)
bookCollection.Controls.Add(lblTitle)

let lbxBooks = new ListBox()
lbxBooks.Location <- new Point(12, 36)

lbxBooks.Items.Add "College Algebra" |> ignore
lbxBooks.Items.Add "Finite Mathematics" |> ignore
lbxBooks.Items.Add "Mathematical Structures" |> ignore
lbxBooks.Items.Add "MCAD 70-316 Training Guide" |> ignore
lbxBooks.Items.Add "C++Builder 6 Developer's Guide" |> ignore

bookCollection.Controls.Add(lbxBooks)

do
    Application.Run bookCollection

This would produce:

A list box with wide items

If at least one of the items of the list box is wider than the width of the control, the right side(s) of that (those) list item(s) may disappear. To allow the user to see the hidden part of the item(s), you should display a horizontal scroll bar. To support this, the ListBox class is equipped with a Boolean property named HorizontalScrollbar. To make a list box display a horizontal scroll bar, set its HorizontalScrollbar property to true. Here is an example:

open System
open System.Drawing
open System.Windows.Forms

let bookCollection : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
bookCollection.Text <- "Book Collection"
bookCollection.StartPosition <- FormStartPosition.CenterScreen

let lblTitle = new Label();
lblTitle.Text <- "Book Titles"
lblTitle.Location <- new Point(12, 12)
bookCollection.Controls.Add(lblTitle)

let lbxBooks : ListBox = new ListBox()
lbxBooks.Location <- new Point(12, 36)
lbxBooks.HorizontalScrollbar <- true

lbxBooks.Items.Add "College Algebra" |> ignore
lbxBooks.Items.Add "Finite Mathematics" |> ignore
lbxBooks.Items.Add "Mathematical Structures" |> ignore
lbxBooks.Items.Add "MCAD 70-316 Training Guide" |> ignore
lbxBooks.Items.Add "C++Builder 6 Developer's Guide" |> ignore

bookCollection.Controls.Add(lbxBooks)

do
    Application.Run bookCollection

This property allows the operating system to find the widest item in the list and provide a horizontal scroll bar that is long enough to display each item when the user scrolls to the right. The above code would produce:

A List Box With a Horizontal Scroll Bar

If the list of items requires it, the list box would display both the vertical and the horizontal scroll bars. Here is an example:

open System
open System.Drawing
open System.Windows.Forms

let bookCollection : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
bookCollection.Text <- "Book Collection"
bookCollection.StartPosition <- FormStartPosition.CenterScreen

let lblTitle = new Label();
lblTitle.Text <- "Book Titles"
lblTitle.Location <- new Point(12, 12)
bookCollection.Controls.Add(lblTitle)

let lbxBooks : ListBox = new ListBox()
lbxBooks.Location <- new Point(12, 36)
lbxBooks.HorizontalScrollbar <- true

lbxBooks.Items.Add "College Algebra" |> ignore
lbxBooks.Items.Add "Finite Mathematics" |> ignore
lbxBooks.Items.Add "Mathematical Structures" |> ignore
lbxBooks.Items.Add "MCAD 70-316 Training Guide" |> ignore
lbxBooks.Items.Add "C++Builder 6 Developer's Guide" |> ignore
lbxBooks.Items.Add "Patterns for a Purpose" |> ignore
lbxBooks.Items.Add "Basic Business Mathematics" |> ignore

bookCollection.Controls.Add(lbxBooks)

do
    Application.Run bookCollection

This would produce:

Characteristics of a List Box

If you prefer to decide how much width should be allowed, then set the desired value in the HorizontalExtent property. Here is an example:

open System
open System.Drawing
open System.Windows.Forms

let bookCollection : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
bookCollection.Text <- "Book Collection"
bookCollection.StartPosition <- FormStartPosition.CenterScreen

let lblTitle = new Label();
lblTitle.Text <- "Book Titles"
lblTitle.Location <- new Point(12, 12)
bookCollection.Controls.Add(lblTitle)

let lbxBooks : ListBox = new ListBox()
lbxBooks.Location <- new Point(12, 36)

lbxBooks.HorizontalExtent <- 120

lbxBooks.Items.Add "College Algebra" |> ignore
lbxBooks.Items.Add "Finite Mathematics" |> ignore
lbxBooks.Items.Add "Mathematical Structures" |> ignore
lbxBooks.Items.Add "MCAD 70-316 Training Guide" |> ignore
lbxBooks.Items.Add "C++Builder 6 Developer's Guide" |> ignore
lbxBooks.Items.Add "Patterns for a Purpose" |> ignore
lbxBooks.Items.Add "Basic Business Mathematics" |> ignore

bookCollection.Controls.Add(lbxBooks)

do
    Application.Run bookCollection

This would produce:

Characteristics of a List Box

A Multi-Column List Box

When you create a list of items, they appear in one column. If the number of items exceeds the height, a scrollbar would appear on the control. An alternative you can use is to span the list to more than one column. To support this, the ListBox class is equipped with the MultiColumn Boolean property. By default, the MultiColumn value is set to false, which means the items appear in one column. If you set this property to true, then the compiler would decide if or when the control needs the columns, based on the number of items in the list. Here is an example:

open System
open System.Drawing
open System.Windows.Forms

let bookCollection : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
bookCollection.Text <- "Book Collection"
bookCollection.StartPosition <- FormStartPosition.CenterScreen

let lblTitle = new Label();
lblTitle.Text <- "Book Titles"
lblTitle.Location <- new Point(12, 12)
bookCollection.Controls.Add(lblTitle)

let lbxBooks : ListBox = new ListBox()
lbxBooks.Location <- new Point(12, 36)
lbxBooks.Size <- new System.Drawing.Size(210, 90)

lbxBooks.MultiColumn <- true

lbxBooks.Items.Add "Mother" |> ignore
lbxBooks.Items.Add "Father" |> ignore
lbxBooks.Items.Add "Uncle" |> ignore
lbxBooks.Items.Add "Aunt" |> ignore
lbxBooks.Items.Add "Son" |> ignore
lbxBooks.Items.Add "Daughter" |> ignore
lbxBooks.Items.Add "Nephew" |> ignore
lbxBooks.Items.Add "Niece" |> ignore
lbxBooks.Items.Add "Ancestor" |> ignore
lbxBooks.Items.Add "Grand" |> ignore
lbxBooks.Items.Add "Great" |> ignore
lbxBooks.Items.Add "In-Law" |> ignore

bookCollection.Controls.Add(lbxBooks)

do
    Application.Run bookCollection

This would produce:

Characteristics of a List Box

Characteristics of a List Box

You can also specify the width of each column using the ColumnWidth property. Here is an example:

open System
open System.Drawing
open System.Windows.Forms

let bookCollection : System.Windows.Forms.Form = new  System.Windows.Forms.Form()
bookCollection.Text <- "Book Collection"
bookCollection.StartPosition <- FormStartPosition.CenterScreen

let lblTitle = new Label();
lblTitle.Text <- "Book Titles"
lblTitle.Location <- new Point(12, 12)
bookCollection.Controls.Add(lblTitle)

let lbxBooks : ListBox = new ListBox()
lbxBooks.Location <- new Point(12, 36)
lbxBooks.Size <- new System.Drawing.Size(210, 90)

lbxBooks.MultiColumn <- true
lbxBooks.ColumnWidth <- 100

lbxBooks.Items.Add "Mother" |> ignore
lbxBooks.Items.Add "Father" |> ignore
lbxBooks.Items.Add "Uncle" |> ignore
lbxBooks.Items.Add "Aunt" |> ignore
lbxBooks.Items.Add "Son" |> ignore
lbxBooks.Items.Add "Daughter" |> ignore
lbxBooks.Items.Add "Nephew" |> ignore
lbxBooks.Items.Add "Niece" |> ignore
lbxBooks.Items.Add "Ancestor" |> ignore
lbxBooks.Items.Add "Grand" |> ignore
lbxBooks.Items.Add "Great" |> ignore
lbxBooks.Items.Add "In-Law" |> ignore

bookCollection.Controls.Add(lbxBooks)

do
    Application.Run bookCollection

This would produce:

Characteristics of a List Box

 
 
   
 

Home Copyright © 2012-2015, FunctionX Home