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選取三個專案。 程式代碼接著會透過 ListBox.SelectedObjectCollectionSelectedItems 屬性顯示集合中的值，以及 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 屬性，並處理 MeasureItem 和 DrawItem 事件，讓您可以覆寫 Windows 提供並自行繪製項目的自動繪圖。 您可以使用擁有者繪製 ListBox 的控制項來顯示清單中每個項目文字的可變高度專案、影像或不同色彩或字型。 屬性 HorizontalExtent 、 GetItemHeight和 GetItemRectangle 也可協助您繪製自己的專案。
除了顯示和選取功能之外， ListBox 也提供可讓您有效率地將專案新增至 ListBox ，以及在清單專案內尋找文字的功能。 BeginUpdate和 EndUpdate 方法可讓您在每次將專案加入清單時，將大量的專案新增至 ListBox ，而不需要重新繪製控件。 FindString和 FindStringExact 方法可讓您搜尋清單中包含特定搜尋字串的專案。
Items、 SelectedItems和 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。 方法 Add 可以在將成員加入 至 ListBox時接受任何物件。 當物件加入至 ListBox時，控件會使用 物件方法中 ToString 定義的文字，除非 在屬性中 DisplayMember 指定物件中的成員名稱。 除了使用 Add 類別的 ListBox.ObjectCollection 方法新增專案之外，您也可以使用 DataSource 類別的 ListControl 屬性來新增專案。
注意
如果您在 ListBox基底 Windows 窗體上有、 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 |
取得控制項下邊緣和其容器工作區 (Client Area) 上邊緣之間的距離 (單位為像素)。 (繼承來源 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 |
取得控制項的資料繫結 (Data Binding)。 (繼承來源 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 |
取得或設定值，指出這個控制項是否應使用次要緩衝區重繪其介面，以減少或防止重繪閃動 (Flicker)。 (繼承來源 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 |
取得或設定控制項左邊緣和其容器工作區 (Client Area) 左邊緣之間的距離 (單位為像素)。 (繼承來源 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 |
取得控制項右邊緣和其容器工作區 (Client Area) 左邊緣之間的距離 (單位為像素)。 (繼承來源 Control) |
| RightToLeft |
取得或設定值，指出控制項所顯示的文字是否從右到左。 |
| RightToLeft |
取得或設定值，指出控制項的項目是否對齊，以支援使用由右至左字型的地區設定。 (繼承來源 Control) |
| ScaleChildren |
取得值，以判斷子控制項的縮放。 (繼承來源 Control) |
| ScrollAlwaysVisible |
取得或設定值，指出是否永遠顯示垂直捲軸。 |
| SelectedIndex |
取得或設定 ListBox 中目前選取項目之以零起始的索引。 |
| SelectedIndices |
取得集合，其中包含 ListBox 中所有目前選取項目之以零起始的索引。 |
| SelectedItem |
取得或設定 ListBox 中目前選取的項目。 |
| SelectedItems |
取得集合，其中含有 ListBox 中目前選取的項目。 |
| SelectedValue |
取得或設定 ValueMember 屬性指定的成員屬性值。 (繼承來源 ListControl) |
| SelectionMode |
取得或設定 ListBox 中，用來選取項目的方法。 |
| ShowFocusCues |
取得指示控制項是否應顯示焦點矩形 (Focus Rectangle) 的值。 (繼承來源 Control) |
| ShowKeyboardCues |
取得值，指出使用者介面是否處於可顯示或隱藏鍵盤快速鍵的適當狀態下。 (繼承來源 Control) |
| Site |
取得或設定控制項的站台。 (繼承來源 Control) |
| Size |
取得或設定控制項的高度和寬度。 (繼承來源 Control) |
| Sorted |
取得或設定值，指出 ListBox 中的項目是否依照字母順序排序。 |
| TabIndex |
取得或設定控制項容器中的控制項定位順序。 (繼承來源 Control) |
| TabStop |
取得或設定值，指出使用者是否能使用 TAB 鍵，將焦點 (Focus) 給予這個控制項。 (繼承來源 Control) |
| Tag |
取得或設定物件，其包含控制項相關資料。 (繼承來源 Control) |
| Text |
取得或搜尋 ListBox 中目前選取項目的文字。 |
| Top |
取得或設定控制項上邊緣和其容器工作區 (Client Area) 上邊緣之間的距離 (單位為像素)。 (繼承來源 Control) |
| TopIndex |
取得或設定 ListBox 中第一個可見項目的索引。 |
| TopLevelControl |
取得沒有其他 Windows Form 父控制項的父控制項。 通常，這會是內含控制項最外層的 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) |
