Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Represents a Windows control to display a list of items.
public ref class ListBox : System::Windows::Forms::ListControlpublic class ListBox : System.Windows.Forms.ListControl[System.ComponentModel.DefaultBindingProperty("SelectedValue")] [System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.AutoDispatch)] [System.Runtime.InteropServices.ComVisible(true)] public class ListBox : System.Windows.Forms.ListControl[System.ComponentModel.DefaultBindingProperty("SelectedValue")] public class ListBox : System.Windows.Forms.ListControltype ListBox = class inherit ListControl[] [] [] type ListBox = class inherit ListControl[] type ListBox = class inherit ListControlPublic Class ListBox Inherits ListControlThe 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. listBox1->BeginUpdate(); // Loop through and add 50 items to the ListBox. for ( int x = 1; x Items->Add( String::Format( "Item ", x ) ); > listBox1->EndUpdate(); // 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 ] ); #endif > 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 // 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()); > 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 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.
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.
Initializes a new instance of the ListBox class.
Specifies the default item height for an owner-drawn ListBox.
Specifies that no matches are found during a search.
Gets the AccessibleObject assigned to the control.
Gets or sets the default action description of the control for use by accessibility client applications.
Gets or sets the description of the control used by accessibility client applications.
Gets or sets the name of the control used by accessibility client applications.
Gets or sets the accessible role of the control.
Gets or sets a value indicating whether the control can accept data that the user drags onto it.
Gets a value indicating whether the ListBox currently enables selection of list items.
Gets a value indicating whether the list enables selection of list items.
Gets or sets the edges of the container to which a control is bound and determines how a control is resized with its parent.
Gets or sets where this control is scrolled to in ScrollControlIntoView(Control).
This property is not relevant for this class.
Gets or sets the background color for the control.
This property is not relevant to this class.
Gets or sets the background image layout for a ListBox as defined in the ImageLayout enumeration.
Gets or sets the background image layout as defined in the ImageLayout enumeration.
Gets or sets the BindingContext for the control.
Gets or sets the type of border that is drawn around the ListBox.
Gets the distance, in pixels, between the bottom edge of the control and the top edge of its container's client area.
Gets or sets the size and location of the control including its nonclient elements, in pixels, relative to the parent control.
Gets a value indicating whether the ImeMode property can be set to an active value, to enable IME support.
Gets a value indicating whether the control can receive focus.
Determines if events can be raised on the control.
Gets a value indicating whether the control can be selected.
Gets or sets a value indicating whether the control has captured the mouse.
Gets or sets a value indicating whether the control causes validation to be performed on any controls that require validation when it receives focus.
Gets the rectangle that represents the client area of the control.
Gets or sets the height and width of the client area of the control.
Gets or sets the width of columns in a multicolumn ListBox.
Gets the name of the company or creator of the application containing the control.
Gets the IContainer that contains the Component.
Gets a value indicating whether the control, or one of its child controls, currently has the input focus.
Gets or sets the shortcut menu associated with the control.
Gets or sets the ContextMenuStrip associated with this control.
Gets the collection of controls contained within the control.
Gets a value indicating whether the control has been created.
Gets the required creation parameters when the control handle is created.
Gets or sets the cursor that is displayed when the mouse pointer is over the control.
Gets the width of the tabs between the items in the ListBox.
Gets the data bindings for the control.
Gets or sets the data context for the purpose of data binding. This is an ambient property.
Gets the CurrencyManager associated with this control.
Gets or sets the data source for this ListControl.
Gets or sets the default cursor for the control.
Gets the default Input Method Editor (IME) mode supported by the control.
Gets the space, in pixels, that is specified by default between controls.
Gets the length and height, in pixels, that is specified as the default maximum size of a control.
Gets the length and height, in pixels, that is specified as the default minimum size of a control.
Gets the default internal spacing, in pixels, of the contents of a control.
Gets the default size of the control.
Gets a value that indicates whether the Component is currently in design mode.
Gets the DPI value for the display device where the control is currently being displayed.
Gets or sets the property to display for this ListControl.
Gets the rectangle that represents the display area of the control.
Gets a value indicating whether the base Control class is in the process of disposing.
Gets or sets which control borders are docked to its parent control and determines how a control is resized with its parent.
Gets or sets a value indicating whether this control should redraw its surface using a secondary buffer to reduce or prevent flicker.
Gets or sets the drawing mode for the control.
Gets or sets a value indicating whether the control can respond to user interaction.
Gets the list of event handlers that are attached to this Component.
Gets a value indicating whether the control has input focus.
Gets or sets the font of the text displayed by the control.
Gets or sets the font of the text displayed by the control.
Gets or sets the height of the font of the control.
Gets or sets the foreground color of the control.
Gets or sets the IFormatProvider that provides custom formatting behavior.
Gets or sets the format-specifier characters that indicate how a value is to be displayed.
Gets or sets a value indicating whether formatting is applied to the DisplayMember property of the ListControl.
Gets the window handle that the control is bound to.
Gets a value indicating whether the control contains one or more child controls.
Gets or sets the height of the control.
Gets or sets the width by which the horizontal scroll bar of a ListBox can scroll.
Gets or sets a value indicating whether a horizontal scroll bar is displayed in the control.
Gets or sets the Input Method Editor (IME) mode of the control.
Gets or sets the IME mode of a control.
Gets or sets a value indicating whether the control should resize to avoid showing partial items.
Gets a value indicating whether the caller must call an invoke method when making method calls to the control because the caller is on a different thread than the one the control was created on.
Gets or sets a value indicating whether the control is visible to accessibility applications.
Indicates if one of the Ancestors of this control is sited and that site in DesignMode. This property is read-only.
Gets a value indicating whether the control has been disposed of.
Gets a value indicating whether the control has a handle associated with it.
Gets a value indicating whether the control is mirrored.
Gets or sets the height of an item in the ListBox.
Gets the items of the ListBox.
Gets a cached instance of the control's layout engine.
Gets or sets the distance, in pixels, between the left edge of the control and the left edge of its container's client area.
Gets or sets the coordinates of the upper-left corner of the control relative to the upper-left corner of its container.
Gets or sets the space between controls.
Gets or sets the size that is the upper limit that GetPreferredSize(Size) can specify.
Gets or sets the size that is the lower limit that GetPreferredSize(Size) can specify.
Gets or sets a value indicating whether the ListBox supports multiple columns.
Gets or sets the name of the control.
This property is not relevant to this class.
Gets or sets padding within the control.
Gets or sets the parent container of the control.
Gets the combined height of all items in the ListBox.
Gets the size of a rectangular area into which the control can fit.
Gets the product name of the assembly containing the control.
Gets the version of the assembly containing the control.
Gets a value indicating whether the control is currently re-creating its handle.
Gets or sets the window region associated with the control.
Obsolete. Obsolete.This property is now obsolete.
Gets or sets a value indicating whether the control redraws itself when resized.
Gets the distance, in pixels, between the right edge of the control and the left edge of its container's client area.
Gets or sets a value indicating whether text displayed by the control is displayed from right to left.
Gets or sets a value indicating whether control's elements are aligned to support locales using right-to-left fonts.
Gets a value that determines the scaling of child controls.
Gets or sets a value indicating whether the vertical scroll bar is shown at all times.
Gets or sets the zero-based index of the currently selected item in a ListBox.
Gets a collection that contains the zero-based indexes of all currently selected items in the ListBox.
Gets or sets the currently selected item in the ListBox.
Gets a collection containing the currently selected items in the ListBox.
Gets or sets the value of the member property specified by the ValueMember property.
Gets or sets the method in which items are selected in the ListBox.
Gets a value indicating whether the control should display focus rectangles.
Gets a value indicating whether the user interface is in the appropriate state to show or hide keyboard accelerators.
Gets or sets the site of the control.
Gets or sets the height and width of the control.
Gets or sets a value indicating whether the items in the ListBox are sorted alphabetically.
Gets or sets the tab order of the control within its container.
Gets or sets a value indicating whether the user can give the focus to this control using the TAB key.
Gets or sets the object that contains data about the control.
Gets or searches for the text of the currently selected item in the ListBox.
Gets or sets the distance, in pixels, between the top edge of the control and the top edge of its container's client area.
Gets or sets the index of the first visible item in the ListBox.
Gets the parent control that is not parented by another Windows Forms control. Typically, this is the outermost Form that the control is contained in.
Gets or sets a value indicating whether the ListBox recognizes and expands tab characters when it draws its strings by using the CustomTabOffsets integer array.
Gets or sets a value indicating whether the ListBox can recognize and expand tab characters when drawing its strings.
Gets or sets a value indicating whether to use the wait cursor for the current control and all child controls.
Gets or sets the path of the property to use as the actual value for the items in the ListControl.
Gets or sets a value indicating whether the control and all its child controls are displayed.
Gets or sets the width of the control.
This property is not relevant for this class.
Notifies the accessibility client applications of the specified AccessibleEvents for the specified child control .
Notifies the accessibility client applications of the specified AccessibleEvents for the specified child control.
Obsolete. Obsolete.This member is obsolete, and there is no replacement.
Executes the specified delegate asynchronously on the thread that the control's underlying handle was created on.
Executes the specified delegate asynchronously with the specified arguments, on the thread that the control's underlying handle was created on.
Executes the specified delegate asynchronously on the thread that the control's underlying handle was created on.
Maintains performance while items are added to the ListBox one at a time by preventing the control from drawing until the EndUpdate() method is called.
Brings the control to the front of the z-order.
Unselects all items in the ListBox.
Retrieves a value indicating whether the specified control is a child of the control.
Creates a new accessibility object for this control.
Creates a new accessibility object for the control.
Forces the creation of the visible control, including the creation of the handle and any visible child controls.
Creates a new instance of the control collection for the control.
Creates the Graphics for the control.
Creates a handle for the control.
Creates a new instance of the item collection.
Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Sends the specified message to the default window procedure.
Destroys the handle associated with the control.
Releases all resources used by the Component.
Releases the unmanaged resources used by the Control and its child controls and optionally releases the managed resources.
Begins a drag operation.
Begins a drag-and-drop operation.
Supports rendering to the specified bitmap.
Retrieves the return value of the asynchronous operation represented by the IAsyncResult passed.
Resumes painting the ListBox control after painting is suspended by the BeginUpdate() method.
Determines whether the specified object is equal to the current object.
Returns the current value of the ListControl item, if it is a property of an object given the item and the property name.
Retrieves the current value of the ListControl item, if it is a property of an object, given the item.
Retrieves the form that the control is on.
Finds the first item in the ListBox that starts with the specified string. The search starts at a specific starting index.
Finds the first item in the ListBox that starts with the specified string.
Finds the first item in the ListBox that exactly matches the specified string. The search starts at a specific starting index.
Finds the first item in the ListBox that exactly matches the specified string.
Sets input focus to the control.
Retrieves the specified AccessibleObject.
Retrieves a value indicating how a control will behave when its AutoSize property is enabled.
Retrieves the child control that is located at the specified coordinates, specifying whether to ignore child controls of a certain type.
Retrieves the child control that is located at the specified coordinates.
Returns the next ContainerControl up the control's chain of parent controls.
Serves as the default hash function.
Returns the height of an item in the ListBox.
Returns the bounding rectangle for an item in the ListBox.
Returns the text representation of the specified item.
Obsolete.Retrieves the current lifetime service object that controls the lifetime policy for this instance.
Retrieves the next control forward or back in the tab order of child controls.
Retrieves the size of a rectangular area into which a control can be fitted.
Retrieves the bounds within which the ListBox is scaled.
Retrieves the bounds within which the control is scaled.
Returns a value indicating whether the specified item is selected.
Returns an object that represents a service provided by the Component or by its Container.
Retrieves the value of the specified control style bit for the control.
Determines if the control is a top-level control.
Gets the Type of the current instance.
Conceals the control from the user.
Returns the zero-based index of the item at the specified coordinates.
Returns the zero-based index of the item at the specified coordinates.
Obsolete.Obtains a lifetime service object to control the lifetime policy for this instance.
Called after the control has been added to another container.
Invalidates the entire surface of the control and causes the control to be redrawn.
Invalidates a specific region of the control and causes a paint message to be sent to the control. Optionally, invalidates the child controls assigned to the control.
Invalidates the specified region of the control (adds it to the control's update region, which is the area that will be repainted at the next paint operation), and causes a paint message to be sent to the control. Optionally, invalidates the child controls assigned to the control.
Invalidates the specified region of the control (adds it to the control's update region, which is the area that will be repainted at the next paint operation), and causes a paint message to be sent to the control.
Invalidates the specified region of the control (adds it to the control's update region, which is the area that will be repainted at the next paint operation), and causes a paint message to be sent to the control. Optionally, invalidates the child controls assigned to the control.
Invalidates the specified region of the control (adds it to the control's update region, which is the area that will be repainted at the next paint operation), and causes a paint message to be sent to the control.
Executes the specified delegate on the thread that owns the control's underlying window handle.
Executes the specified delegate, on the thread that owns the control's underlying window handle, with the specified list of arguments.
Executes the specified delegate on the thread that owns the control's underlying window handle.
Executes the specified delegate on the thread that owns the control's underlying window handle.
Raises the GotFocus event for the specified control.
Raises the LostFocus event for the specified control.
Raises the Click event for the specified control.
Raises the Paint event for the specified control.
Raises the PaintBackground event for the specified control.
Determines if a character is an input character that the control recognizes.
Handles special input keys, such as PAGE UP, PAGE DOWN, HOME, END, and so on.
Converts a Logical DPI value to its equivalent DeviceUnit DPI value.
Transforms a size from logical to device units by scaling it for the current DPI and rounding down to the nearest integer value for width and height.
Creates a shallow copy of the current Object.
Creates a shallow copy of the current MarshalByRefObject object.
Raises the Invalidated event with a specified region of the control to invalidate.