ListBox Class (System.Windows.Forms)

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:

.NET Framework Class Library

ListBox Class

Represents a Windows control to display a list of items.

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in system.windows.forms.dll)

Syntax

Visual Basic (Declaration)

<ComVisibleAttribute(True)> _
<ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)> _
Public Class ListBox
    Inherits ListControl

Visual Basic (Usage)

Dim instance As ListBox

[ComVisibleAttribute(true)] 
[ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)] 
public class ListBox : ListControl

C++

[ComVisibleAttribute(true)] 
[ClassInterfaceAttribute(ClassInterfaceType::AutoDispatch)] 
public ref class ListBox : public ListControl

/** @attribute ComVisibleAttribute(true) */ 
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) */ 
public class ListBox extends ListControl

JScript

ComVisibleAttribute(true) 
ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) 
public class ListBox extends ListControl

Remarks

The ListBox control enables you to display a list of items to the user that the user can select by clicking. A ListBox control can provide single or multiple selections using the SelectionMode property. The ListBox also provides the MultiColumn property to enable the display of items in columns instead of a straight vertical list of items. With this, the control can display more visible items and the user no longer needs to scroll to an item.

Typically, Windows handles the task of drawing the items to display in the ListBox. You can use the DrawMode property, and handle the MeasureItem and DrawItem events so you can override the automatic drawing that Windows provides and draw the items yourself. You can use owner-drawn ListBox controls to display variable-height items, images, or a different color or font for the text of each item in the list. The HorizontalExtent property, GetItemHeight, and GetItemRectangle also help you draw your own items.

In addition to display and selection functionality, the ListBox also provides features that enable you to efficiently add items to the ListBox and to find text within the items of the list. The BeginUpdate and EndUpdate methods enable you to add a large number of items to the ListBox without the control being repainted each time an item is added to the list. The FindString and FindStringExact methods enable you to search for an item in the list that contains a specific search string.

The Items, SelectedItems, and SelectedIndices properties provide access to the three collections that are used by the ListBox. The following table outlines the three collections used by the ListBox and their use within the control.

Collection class	Use within the ListBox
ListBox.ObjectCollection	Contains all items contained in the ListBox control.
ListBox.SelectedObjectCollection	Contains a collection of the selected items which is a subset of the items contained in the ListBox control.
ListBox.SelectedIndexCollection	Contains a collection of the selected indexes, which is a subset of the indexes of the ListBox.ObjectCollection. These indexes specify items that are selected.

The following three examples show the three indexed collections that the ListBox class supports.

The following table shows an example of how the ListBox.ObjectCollection stores the items of the ListBox as well as their selection state within an example ListBox.

Index	Item	Selection state within the ListBox
0	object1	Unselected
1	object2	Selected
2	object3	Unselected
3	object4	Selected
4	object5	Selected

Based on the ListBox.ObjectCollection shown in the previous table, this table shows how the ListBox.SelectedObjectCollection would appear.

Index	Item
0	object2
1	object4
2	object5

Based on the ListBox.ObjectCollection shown in the previous table, this table shows how the ListBox.SelectedIndexCollection would appear.

Index	Index of item
0	1
1	3
2	4

The Add method of the ListBox.ObjectCollection class enables you to add items to the ListBox. The Add method can accept any object when adding a member to the ListBox. When an object is being added to the ListBox, the control uses the text defined in the ToString method of the object unless a member name within the object is specified in the DisplayMember property. In addition to adding items using the Add method of the ListBox.ObjectCollection class you can also add items using the DataSource property of the ListControl class.

Note
If you have a ListBox, ComboBox, or CheckedListBox on a base Windows form and want to modify the string collections of those controls in a derived Windows form, the string collections of those controls in the base Windows form must be empty. If the string collections are not empty, they become read-only when you derive another Windows form.

Example

The following code example demonstrates how to create a ListBox control that displays multiple items in columns and can have more than one item selected in the control's list. The code for the example adds 50 items to the ListBox using the Add method of the ListBox.ObjectCollection class and then selects three items from the list using the SetSelected method. The code then displays values from the ListBox.SelectedObjectCollection collection, through the SelectedItems property, and the ListBox.SelectedIndexCollection, through the SelectedIndices property. This example requires that the code is located in and called from a Form.

Visual Basic

Private Sub button1_Click(sender As Object, e As System.EventArgs)
    ' Create an instance of the ListBox.
    Dim listBox1 As New ListBox()
    ' Set the size and location of the ListBox.
    listBox1.Size = New System.Drawing.Size(200, 100)
    listBox1.Location = New System.Drawing.Point(10, 10)
    ' Add the ListBox to the form.
    Me.Controls.Add(listBox1)
    ' Set the ListBox to display items in multiple columns.
    listBox1.MultiColumn = True
    ' Set the selection mode to multiple and extended.
    listBox1.SelectionMode = SelectionMode.MultiExtended
    
    ' Shutdown the painting of the ListBox as items are added.
    listBox1.BeginUpdate()
    ' Loop through and add 50 items to the ListBox.
    Dim x As Integer
    For x = 1 To 50
        listBox1.Items.Add("Item " & x.ToString())
    Next x
    ' Allow the ListBox to repaint and display the new items.
    listBox1.EndUpdate()
    
    ' Select three items from the ListBox.
    listBox1.SetSelected(1, True)
    listBox1.SetSelected(3, True)
    listBox1.SetSelected(5, True)
       
    ' Display the second selected item in the ListBox to the console.
    System.Diagnostics.Debug.WriteLine(listBox1.SelectedItems(1).ToString())
    ' Display the index of the first selected item in the ListBox.
    System.Diagnostics.Debug.WriteLine(listBox1.SelectedIndices(0).ToString())
End Sub

private void button1_Click(object sender, System.EventArgs e)
{
   // Create an instance of the ListBox.
   ListBox listBox1 = new ListBox();
   // Set the size and location of the ListBox.
   listBox1.Size = new System.Drawing.Size(200, 100);
   listBox1.Location = new System.Drawing.Point(10,10);
   // Add the ListBox to the form.
   this.Controls.Add(listBox1);
   // Set the ListBox to display items in multiple columns.
   listBox1.MultiColumn = true;
   // Set the selection mode to multiple and extended.
   listBox1.SelectionMode = SelectionMode.MultiExtended;
 
   // Shutdown the painting of the ListBox as items are added.
   listBox1.BeginUpdate();
   // Loop through and add 50 items to the ListBox.
   for (int x = 1; x <= 50; x++)
   {
      listBox1.Items.Add("Item " + x.ToString());
   }
   // Allow the ListBox to repaint and display the new items.
   listBox1.EndUpdate();
      
   // Select three items from the ListBox.
   listBox1.SetSelected(1, true);
   listBox1.SetSelected(3, true);
   listBox1.SetSelected(5, true);

   // Display the second selected item in the ListBox to the console.
   System.Diagnostics.Debug.WriteLine(listBox1.SelectedItems[1].ToString());
   // Display the index of the first selected item in the ListBox.
   System.Diagnostics.Debug.WriteLine(listBox1.SelectedIndices[0].ToString());             
}

C++

void button1_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
{
   
   // Create an instance of the ListBox.
   ListBox^ listBox1 = gcnew ListBox;
   
   // Set the size and location of the ListBox.
   listBox1->Size = System::Drawing::Size( 200, 100 );
   listBox1->Location = System::Drawing::Point( 10, 10 );
   
   // Add the ListBox to the form.
   this->Controls->Add( listBox1 );
   
   // Set the ListBox to display items in multiple columns.
   listBox1->MultiColumn = true;
   
   // Set the selection mode to multiple and extended.
   listBox1->SelectionMode = SelectionMode::MultiExtended;
   
   // Shutdown the painting of the ListBox as items are added.
   listBox1->BeginUpdate();
   
   // Loop through and add 50 items to the ListBox.
   for ( int x = 1; x <= 50; x++ )
   {
      listBox1->Items->Add( String::Format( "Item {0}", x ) );

   }
   listBox1->EndUpdate();
   
   // Select three items from the ListBox.
   listBox1->SetSelected( 1, true );
   listBox1->SetSelected( 3, true );
   listBox1->SetSelected( 5, true );
   
   // Display the second selected item in the ListBox to the console.
   System::Diagnostics::Debug::WriteLine( listBox1->SelectedItems[ 1 ] );
   
   // Display the index of the first selected item in the ListBox.
   System::Diagnostics::Debug::WriteLine( listBox1->SelectedIndices[ 0 ] );
}

private void button1_Click(Object sender, System.EventArgs e)
{
    // Create an instance of the ListBox.
    ListBox listBox1 = new ListBox();

    // Set the size and location of the ListBox.
    listBox1.set_Size(new System.Drawing.Size(200,100));
    listBox1.set_Location(new System.Drawing.Point(10,10));

    // Add the ListBox to the form.
    this.get_Controls().Add(listBox1);

    // Set the ListBox to display items in multiple columns.
    listBox1.set_MultiColumn(true);

    // Set the selection mode to multiple and extended.
    listBox1.set_SelectionMode(SelectionMode.MultiExtended);

    // Shutdown the painting of the ListBox as items are added.
    listBox1.BeginUpdate();

    // Loop through and add 50 items to the ListBox.
    for (int x = 1; x <= 50; x++) {
        listBox1.get_Items().Add(("Item" + (new Integer(x)).ToString()));
    }

    // Allow the ListBox to repaint and display the new items.
    listBox1.EndUpdate();

    // Select three items from the ListBox.
    listBox1.SetSelected(1,true);
    listBox1.SetSelected(3,true);
    listBox1.SetSelected(5,true);

    // Display the second selected item in the ListBox to the console.
    System.Diagnostics.Debug.WriteLine
        (listBox1.get_SelectedItems().get_Item(1).ToString());

    // Display the index of the first selected item in the ListBox.
    System.Diagnostics.Debug.WriteLine((new Integer
        (listBox1.get_SelectedIndices().get_Item(0))).ToString());
} //button1_Click

JScript

private function button1_Click(sender : Object, e : System.EventArgs)
{
   // Create an instance of the ListBox.
   var listBox1 : ListBox = new ListBox();
   // Set the size and location of the ListBox.
   listBox1.Size = new System.Drawing.Size(200, 100);
   listBox1.Location = new System.Drawing.Point(10,10);
   // Add the ListBox to the form.
   this.Controls.Add(listBox1);
   // Set the ListBox to display items in multiple columns.
   listBox1.MultiColumn = true;
   // Set the selection mode to multiple and extended.
   listBox1.SelectionMode = SelectionMode.MultiExtended;
 
   // Shutdown the painting of the ListBox as items are added.
   listBox1.BeginUpdate();
   // Loop through and add 50 items to the ListBox.
   for (var x : int = 1; x <= 50; x++)
   {
      listBox1.Items.Add("Item " + x.ToString());
   }
   // Allow the ListBox to repaint and display the new items.
   listBox1.EndUpdate();
      
   // Select three items from the ListBox.
   listBox1.SetSelected(1, true);
   listBox1.SetSelected(3, true);
   listBox1.SetSelected(5, true);

   // Display the second selected item in the ListBox to the console.
   System.Diagnostics.Debug.WriteLine(listBox1.SelectedItems[1].ToString());
   // Display the index of the first selected item in the ListBox.
   System.Diagnostics.Debug.WriteLine(listBox1.SelectedIndices[0].ToString());             
}

Inheritance Hierarchy

System.Object
   System.MarshalByRefObject
     System.ComponentModel.Component
       System.Windows.Forms.Control
         System.Windows.Forms.ListControl
          System.Windows.Forms.ListBox
             System.Windows.Forms.CheckedListBox

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

Version Information

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

Reference

ListBox Members
System.Windows.Forms Namespace

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads

.NET Framework

.NET Compact Framework

Reference