ListBox 类
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
表示用于显示项列表的 Windows 控件。
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[<System.ComponentModel.DefaultBindingProperty("SelectedValue")>]
[<System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.AutoDispatch)>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type ListBox = class
inherit ListControl[<System.ComponentModel.DefaultBindingProperty("SelectedValue")>]
type ListBox = class
inherit ListControlPublic Class ListBox
Inherits ListControl- 继承
- 派生
- 属性
示例
下面的代码示例演示如何创建一个 ListBox 控件，该控件在列中显示多个项，并且可以在控件的列表中选择多个项。 该示例的代码使用 Add 类的 ListBox.ObjectCollection 方法将 50 个项添加到 ListBox ，然后使用 方法从列表中选择SetSelected三项。 然后，代码通过 属性显示集合SelectedItems中的ListBox.SelectedObjectCollection值，以及 ListBox.SelectedIndexCollection通过 SelectedIndices 属性显示 的值。 此示例要求代码位于 中，并从 中 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 <= 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 );
#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 <= 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());
}
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
注解
控件 ListBox 使你能够向用户显示用户可以通过单击选择的项列表。 ListBox控件可以使用 属性提供单个或多个选择SelectionMode。 ListBox还提供 MultiColumn 属性，以允许在列中显示项，而不是直接垂直的项列表。 这样，控件可以显示更多可见的项，并且用户不再需要滚动到项。
通常，Windows 处理绘制要显示在 中的 ListBox项的任务。 可以使用 DrawMode 属性并处理 和 DrawItem 事件，MeasureItem以便可以替代 Windows 提供的自动绘制并自行绘制项。 可以使用所有者绘制 ListBox 的控件来显示可变高度的项目、图像，或者列表中每个项的文本使用不同的颜色或字体。 属性 HorizontalExtentGetItemHeight、 和 GetItemRectangle 还有助于绘制自己的项。
除了显示和选择功能外， ListBox 还提供了一项功能，使你能够有效地向 ListBox 添加项，并在列表项内查找文本。 和 BeginUpdateEndUpdate 方法使你能够将大量项添加到 ， ListBox 而无需在每次将项添加到列表中时重新绘制控件。 和 FindStringFindStringExact 方法使你能够在列表中搜索包含特定搜索字符串的项。
、 ItemsSelectedItems和 SelectedIndices 属性提供对 使用的ListBox三个集合的访问权限。 下表概述了 使用的三个 ListBox 集合及其在 控件中的用法。
| 集合类 | 在 ListBox |
|---|---|
| ListBox.ObjectCollection | 包含 控件中包含的 ListBox 所有项。 |
| ListBox.SelectedObjectCollection | 包含选定项的集合，该集合是控件中包含的项的 ListBox 子集。 |
| ListBox.SelectedIndexCollection | 包含所选索引的集合，该集合是 的索引的 ListBox.ObjectCollection子集。 这些索引指定所选的项。 |
以下三个示例显示了 类支持的三个 ListBox 索引集合。
下表显示了如何在 ListBox.ObjectCollection 示例 中存储 的 ListBox 项及其选择状态的示例 ListBox。
| 索引 | 项 | ListBox 中的选择状态 |
|---|---|---|
| 0 | object1 | 未选定 |
| 1 | object2 | 已选定 |
| 2 | object3 | 未选定 |
| 3 | object4 | 已选定 |
| 4 | object5 | 已选定 |
根据 ListBox.ObjectCollection 上表中所示的 ，此表显示了 的显示方式 ListBox.SelectedObjectCollection 。
| 索引 | 项 |
|---|---|
| 0 | object2 |
| 1 | object4 |
| 2 | object5 |
根据 ListBox.ObjectCollection 上表中所示的 ，此表显示了 的显示方式 ListBox.SelectedIndexCollection 。
| 索引 | 项索引 |
|---|---|
| 0 | 1 |
| 1 | 3 |
| 2 | 4 |
类 Add 的 ListBox.ObjectCollection 方法使你能够将项添加到 ListBox。 将 成员添加到 时， AddListBox方法可以接受任何 对象。 将对象添加到 ListBox时，控件使用 在 对象的 方法中 ToString 定义的文本，除非在 属性中 DisplayMember 指定了 对象中的成员名称。 除了使用 Add 类的 方法添加项外， ListBox.ObjectCollection 还可以使用 DataSource 类的 ListControl 属性添加项。
注意
如果在基础 Windows 窗体上具有 ListBox、 ComboBox或 CheckedListBox ，并且想要修改派生 Windows 窗体中这些控件的字符串集合，则基本 Windows 窗体中这些控件的字符串集合必须为空。 如果字符串集合不为空，则当你派生另一个 Windows 窗体时，它们将成为只读的。
构造函数
| ListBox() |
初始化 ListBox 类的新实例。 |
字段
| DefaultItemHeight |
为所有者描述的 ListBox 指定默认项高度。 |
| NoMatches |
指定在搜索过程中没有找到匹配项。 |
属性
| AccessibilityObject |
获取分配给该控件的 AccessibleObject。 (继承自 Control) |
| AccessibleDefaultActionDescription |
获取或设置控件的默认操作说明以供具有辅助功能的客户端应用程序使用。 (继承自 Control) |
| AccessibleDescription |
获取或设置辅助功能客户端应用程序使用的控件说明。 (继承自 Control) |
| AccessibleName |
获取或设置辅助功能客户端应用程序所使用的控件名称。 (继承自 Control) |
| AccessibleRole |
获取或设置控件的辅助性角色。 (继承自 Control) |
| AllowDrop |
获取或设置一个值，该值指示控件是否可以接受用户拖放到它上面的数据。 (继承自 Control) |
| AllowSelection |
获取一个值，该值指示 ListBox 当前是否启用了列表项的选择。 |
| AllowSelection |
获取一个值，该值指示列表是否启用列表项的选择。 (继承自 ListControl) |
| Anchor |
获取或设置控件绑定到的容器的边缘并确定控件如何随其父级一起调整大小。 (继承自 Control) |
| AutoScrollOffset |
获取或设置一个值，该值指示在 ScrollControlIntoView(Control) 中将控件滚动到何处。 (继承自 Control) |
| AutoSize |
此属性与此类无关。 (继承自 Control) |
| BackColor |
获取或设置控件的背景色。 |
| BackgroundImage |
此属性与此类无关。 |
| BackgroundImageLayout |
按照 ListBox 枚举中的定义获取或设置 ImageLayout 的背景图像布局。 |
| BackgroundImageLayout |
获取或设置在 ImageLayout 枚举中定义的背景图像布局。 (继承自 Control) |
| BindingContext |
获取或设置控件的 BindingContext。 (继承自 Control) |
| BorderStyle |
获取或设置在 ListBox 四周绘制的边框的类型。 |
| Bottom |
获取控件下边缘与其容器的工作区上边缘之间的距离（以像素为单位）。 (继承自 Control) |
| Bounds |
获取或设置控件（包括其非工作区元素）相对于其父控件的大小和位置（以像素为单位）。 (继承自 Control) |
| CanEnableIme |
获取一个用以指示是否可以将 ImeMode 属性设置为活动值的值，以启用 IME 支持。 (继承自 Control) |
| CanFocus |
获取一个值，该值指示控件是否可以接收焦点。 (继承自 Control) |
| CanRaiseEvents |
确定是否可以在控件上引发事件。 (继承自 Control) |
| CanSelect |
获取一个值，该值指示是否可以选中控件。 (继承自 Control) |
| Capture |
获取或设置一个值，该值指示控件是否已捕获鼠标。 (继承自 Control) |
| CausesValidation |
获取或设置一个值，该值指示控件是否会引起在任何需要在接收焦点时执行验证的控件上执行验证。 (继承自 Control) |
| ClientRectangle |
获取表示控件的工作区的矩形。 (继承自 Control) |
| ClientSize |
获取或设置控件的工作区的高度和宽度。 (继承自 Control) |
| ColumnWidth |
获取或设置多列 ListBox 中列的宽度。 |
| CompanyName |
获取包含控件的应用程序的公司名称或创建者。 (继承自 Control) |
| Container |
获取包含 IContainer 的 Component。 (继承自 Component) |
| ContainsFocus |
获取一个值，该值指示控件或它的一个子控件当前是否有输入焦点。 (继承自 Control) |
| ContextMenu |
获取或设置与控件关联的快捷菜单。 (继承自 Control) |
| ContextMenuStrip |
获取或设置与此控件关联的 ContextMenuStrip。 (继承自 Control) |
| Controls |
获取包含在控件内的控件的集合。 (继承自 Control) |
| Created |
获取一个值，该值指示控件是否已经创建。 (继承自 Control) |
| CreateParams |
获取创建控件句柄时所需要的创建参数。 |
| Cursor |
获取或设置当鼠标指针位于控件上时显示的光标。 (继承自 Control) |
| CustomTabOffsets |
获取 ListBox 中的项之间的制表符的宽度。 |
| DataBindings |
为该控件获取数据绑定。 (继承自 Control) |
| DataContext |
获取或设置用于数据绑定的数据上下文。 这是一个环境属性。 (继承自 Control) |
| DataManager |
获取与此控件关联的 CurrencyManager。 (继承自 ListControl) |
| DataSource |
获取或设置此 ListControl 的数据源。 (继承自 ListControl) |
| DefaultCursor |
获取或设置控件的默认光标。 (继承自 Control) |
| DefaultImeMode |
获取控件支持的默认输入法编辑器 (IME) 模式。 (继承自 Control) |
| DefaultMargin |
获取控件之间默认指定的间距（以像素为单位）。 (继承自 Control) |
| DefaultMaximumSize |
获取以像素为单位的长度和高度，此长度和高度被指定为控件的默认最大大小。 (继承自 Control) |
| DefaultMinimumSize |
获取以像素为单位的长度和高度，此长度和高度被指定为控件的默认最小大小。 (继承自 Control) |
| DefaultPadding |
获取 控件内容的默认内部间距（以像素为单位）。 (继承自 Control) |
| DefaultSize |
获取控件的默认大小。 |
| DesignMode |
获取一个值，用以指示 Component 当前是否处于设计模式。 (继承自 Component) |
| DeviceDpi |
获取显示当前控件的显示设备的 DPI 值。 (继承自 Control) |
| DisplayMember |
获取或设置要为此 ListControl 显示的属性。 (继承自 ListControl) |
| DisplayRectangle |
获取表示控件的显示区域的矩形。 (继承自 Control) |
| Disposing |
获取一个值，该值指示 Control 基类是否在释放进程中。 (继承自 Control) |
| Dock |
获取或设置哪些控件边框停靠到其父控件并确定控件如何随其父级一起调整大小。 (继承自 Control) |
| DoubleBuffered |
获取或设置一个值，该值指示此控件是否应使用辅助缓冲区重绘其图面，以减少或避免闪烁。 (继承自 Control) |
| DrawMode |
获取或设置控件的绘图模式。 |
| Enabled |
获取或设置一个值，该值指示控件是否可以对用户交互作出响应。 (继承自 Control) |
| Events |
获取附加到此 Component 的事件处理程序的列表。 (继承自 Component) |
| Focused |
获取一个值，该值指示控件是否有输入焦点。 (继承自 Control) |
| Font |
获取或设置控件显示的文字的字体。 |
| Font |
获取或设置控件显示的文字的字体。 (继承自 Control) |
| FontHeight |
获取或设置控件的字体的高度。 (继承自 Control) |
| ForeColor |
获取或设置控件的前景色。 |
| FormatInfo |
获取或设置提供自定义格式设置行为的 IFormatProvider。 (继承自 ListControl) |
| FormatString |
获取或设置指示显示值的方式的格式说明符字符。 (继承自 ListControl) |
| FormattingEnabled |
获取或设置一个值，该值指示是否将格式设置应用于 DisplayMember 的 ListControl 属性。 (继承自 ListControl) |
| Handle |
获取控件绑定到的窗口句柄。 (继承自 Control) |
| HasChildren |
获取一个值，该值指示控件是否包含一个或多个子控件。 (继承自 Control) |
| Height |
获取或设置控件的高度。 (继承自 Control) |
| HorizontalExtent |
获取或设置 ListBox 的水平滚动条可滚动的宽度。 |
| HorizontalScrollbar |
获取或设置一个值，该值指示是否在控件中显示水平滚动条。 |
| ImeMode |
获取或设置控件的输入法编辑器 (IME) 模式。 (继承自 Control) |
| ImeModeBase |
获取或设置控件的 IME 模式。 (继承自 Control) |
| IntegralHeight |
获取或设置一个值，该值指示控件是否应调整大小以避免只显示项的局部。 |
| InvokeRequired |
获取一个值，该值指示调用方在对控件进行方法调用时是否必须调用 Invoke 方法，因为调用方位于创建控件所在的线程以外的线程中。 (继承自 Control) |
| IsAccessible |
获取或设置一个值，该值指示控件对辅助功能应用程序是否可见。 (继承自 Control) |
| IsAncestorSiteInDesignMode |
指示此控件的上级之一是否位于 DesignMode 中。 此属性为只读。 (继承自 Control) |
| IsDisposed |
获取一个值，该值指示控件是否已经被释放。 (继承自 Control) |
| IsHandleCreated |
获取一个值，该值指示控件是否有与它关联的句柄。 (继承自 Control) |
| IsMirrored |
获取一个值，该值指示此控件是否为镜像控件。 (继承自 Control) |
| ItemHeight |
获取或设置 ListBox 中项的高度。 |
| Items |
获取 ListBox 的项。 |
| LayoutEngine |
获取控件的布局引擎的缓存实例。 (继承自 Control) |
| Left |
获取或设置控件左边缘与其容器的工作区左边缘之间的距离（以像素为单位）。 (继承自 Control) |
| Location |
获取或设置该控件的左上角相对于其容器的左上角的坐标。 (继承自 Control) |
| Margin |
获取或设置控件之间的空间。 (继承自 Control) |
| MaximumSize |
获取或设置大小，该大小是 GetPreferredSize(Size) 可以指定的上限。 (继承自 Control) |
| MinimumSize |
获取或设置大小，该大小是 GetPreferredSize(Size) 可以指定的下限。 (继承自 Control) |
| MultiColumn |
获取或设置一个值，该值指示 ListBox 是否支持多列。 |
| Name |
获取或设置控件的名称。 (继承自 Control) |
| Padding |
此属性与此类无关。 |
| Padding |
获取或设置控件内的空白。 (继承自 Control) |
| Parent |
获取或设置控件的父容器。 (继承自 Control) |
| PreferredHeight |
获取 ListBox 中所有项的组合高度。 |
| PreferredSize |
获取可以容纳控件的矩形区域的大小。 (继承自 Control) |
| ProductName |
获取包含控件的程序集的产品名称。 (继承自 Control) |
| ProductVersion |
获取包含控件的程序集的版本。 (继承自 Control) |
| RecreatingHandle |
获取一个值，该值指示控件当前是否在重新创建其句柄。 (继承自 Control) |
| Region |
获取或设置与控件关联的窗口区域。 (继承自 Control) |
| RenderRightToLeft |
已过时.
已过时.
此属性现已过时。 (继承自 Control) |
| ResizeRedraw |
获取或设置一个值，该值指示控件在调整大小时是否重绘自己。 (继承自 Control) |
| Right |
获取控件右边缘与其容器的工作区左边缘之间的距离（以像素为单位）。 (继承自 Control) |
| RightToLeft |
获取或设置一个值，该值指示由控件显示的文本是否从右向左显示。 |
| RightToLeft |
获取或设置一个值，该值指示是否将控件的元素对齐以支持使用从右向左的字体的区域设置。 (继承自 Control) |
| ScaleChildren |
获取一个值，该值确定子控件的缩放。 (继承自 Control) |
| ScrollAlwaysVisible |
获取或设置一个值，该值指示是否任何时候都显示垂直滚动条。 |
| SelectedIndex |
获取或设置 ListBox 中当前选定项的从零开始的索引。 |
| SelectedIndices |
获取一个集合，该集合包含 ListBox 中所有当前选定项的从零开始的索引。 |
| SelectedItem |
获取或设置 ListBox 中的当前选定项。 |
| SelectedItems |
获取包含 ListBox 中当前选定项的集合。 |
| SelectedValue |
获取或设置由 ValueMember 属性指定的成员属性的值。 (继承自 ListControl) |
| SelectionMode |
获取或设置在 ListBox 中选择项所用的方法。 |
| ShowFocusCues |
获取一个值，该值指示控件是否应显示聚焦框。 (继承自 Control) |
| ShowKeyboardCues |
获取一个值，该值指示用户界面是否处于适当的状态以显示或隐藏键盘快捷键。 (继承自 Control) |
| Site |
获取或设置控件的站点。 (继承自 Control) |
| Size |
获取或设置控件的高度和宽度。 (继承自 Control) |
| Sorted |
获取或设置一个值，该值指示 ListBox 中的项是否按字母顺序排序。 |
| TabIndex |
获取或设置控件在其容器内的 Tab 键顺序。 (继承自 Control) |
| TabStop |
获取或设置一个值，该值指示用户能否使用 Tab 键将焦点放到该控件上。 (继承自 Control) |
| Tag |
获取或设置包含有关控件的数据的对象。 (继承自 Control) |
| Text |
获取或搜索 ListBox 中当前选定项的文本。 |
| Top |
获取或设置控件上边缘与其容器的工作区上边缘之间的距离（以像素为单位）。 (继承自 Control) |
| TopIndex |
获取或设置 ListBox 中第一个可见项的索引。 |
| TopLevelControl |
获取没有另一个 Windows 窗体控件作为其父级的父控件。 通常，这是控件所在的最外面的 Form。 (继承自 Control) |
| UseCustomTabOffsets |
获取或设置一个值，它指示 ListBox 在通过使用 CustomTabOffsets 整数数组绘制字符串时是否识别并展开制表符。 |
| UseTabStops |
获取或设置一个值，该值指示 ListBox 在绘制其字符串时是否可识别和展开制表符。 |
| UseWaitCursor |
获取或设置一个值，该值指示是否将等待光标用于当前控件以及所有子控件。 (继承自 Control) |
| ValueMember |
获取或设置属性的路径，它将用作 ListControl 中的项的实际值。 (继承自 ListControl) |
| Visible |
获取或设置一个值，该值指示是否显示该控件及其所有子控件。 (继承自 Control) |
| Width |
获取或设置控件的宽度。 (继承自 Control) |
| WindowTarget |
此属性与此类无关。 (继承自 Control) |
方法
事件
显式接口实现
| IDropTarget.OnDragDrop(DragEventArgs) |
引发 DragDrop 事件。 (继承自 Control) |
| IDropTarget.OnDragEnter(DragEventArgs) |
引发 DragEnter 事件。 (继承自 Control) |
| IDropTarget.OnDragLeave(EventArgs) |
引发 DragLeave 事件。 (继承自 Control) |
| IDropTarget.OnDragOver(DragEventArgs) |
引发 DragOver 事件。 (继承自 Control) |
