Add Method

ListBox::ObjectCollection::Add Method (Object^)


Adds an item to the list of items for a ListBox.

Namespace:   System.Windows.Forms
Assembly:  System.Windows.Forms (in System.Windows.Forms.dll)

int Add(
	Object^ item


Type: System::Object^

An object representing the item to add to the collection.

Return Value

Type: System::Int32

The zero-based index of the item in the collection, or -1 if BeginUpdate has been called.

Exception Condition

There is insufficient space available to add the new item to the list.


item is null.

If the Sorted property of the ListBox is set to true, the item is inserted into the list alphabetically. Otherwise, the item is inserted at the end of the list. To insert an item into the list box at a specific position, use the Insert method. To add a set of items to the list box in a single operation, use the AddRange method. If you want to use the Add method to add a large number of items to the list, use the BeginUpdate and EndUpdate methods to prevent the ListBox from repainting each time an item is added to the list until all items are added to the list. When adding items to a ListBox, it is more efficient to sort the items first and then add new items.

When an object is added to the collection, the ListBox first checks to see if the DisplayMember property of the ListControl class has the name of a member from the object specified to reference when obtaining the item text. If the DisplayMember property does not have a member specified, the ListBox then calls the ToString method of the object to obtain the text to display in the list.

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.

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.

   // Loop through and add 50 items to the ListBox.
   for ( int x = 1; x <= 50; x++ )
      listBox1->Items->Add( String::Format( "Item {0}", x ) );


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

   #if defined(DEBUG)
   // 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 ] );

.NET Framework
Available since 1.1
Return to top
© 2016 Microsoft