共用方式為

關於清單框

  • 發行項

清單框控制件包含簡單的清單，使用者通常會從中選取一或多個專案。 與清單檢視控件相比，清單框提供有限的彈性。

清單框專案可以透過文字字串、點陣圖或兩者來表示。 如果清單框不夠大，無法同時顯示所有清單框專案，清單框就會提供滾動條。 使用者會捲動清單框專案，並視需要套用或移除選取狀態。 選取清單框項目會變更其視覺外觀，通常是將文字和背景色彩變更為相關操作系統計量所指定的色彩。 當使用者選取或取消選取專案時，系統會將通知訊息傳送至清單框的父視窗。

針對 ANSI 應用程式，系統會使用 CP_ACP 代碼頁，將清單框中的文字轉換成 Unicode。 這可能會導致問題。 例如，Windows 中非 Unicode 清單框中的輔色羅馬字元，日文版本會以大寫顯示。 若要修正此問題，請將應用程式編譯為 Unicode，或使用擁有者繪製的清單框。

本節討論下列主題：

建立清單框

在對話框中建立清單框最簡單的方式，就是將清單框從 Microsoft Visual Studio 中的工具箱拖曳到您的對話框資源。 若要動態建立清單框，或在對話方塊以外的視窗中建立清單框，請使用 CreateWindowEx 函式，指定WC_LISTBOX視窗類別和適當的清單框樣式。

清單框類型和樣式

清單框有兩種類型：單一選取範圍（預設值）和多重選取範圍。 在單一選取清單框中，使用者一次只能選取一個專案。 在多重選取清單框中，用戶可以一次選取多個專案。 若要建立多重選取清單框，請指定LBS_MULTIPLESEL或LBS_EXTENDEDSEL樣式。

清單框的外觀和作業是由 清單框樣式 和視窗樣式所控制。 這些樣式會指出清單是否經過排序、排列在多個數據行中、由應用程式繪製等等。 清單框的維度和樣式通常會定義在應用程式資源中包含的對話框範本中。

注意

若要搭配這些控件使用可視化樣式，應用程式必須包含指令清單，而且必須在程式開頭呼叫 InitCommonControls。 如需可視化樣式的資訊，請參閱 可視化樣式。 如需指令清單的資訊，請參閱 啟用可視化樣式。

清單框函式

DlgDirList 函式會將清單框的內容取代為符合一組指定準則的磁碟驅動器、目錄和檔案名稱。 DlgDirSelectEx 函式會擷取由 DlgDirList 初始化的清單框中目前的選取範圍。 這些函式可讓使用者從清單框中選取磁碟驅動器、目錄或檔案，而不需要輸入檔案的位置和名稱。

此外， GetListBoxInfo 函式會傳回指定清單框中每個數據行的項目數。

清單框的通知訊息

當清單框中發生事件時，清單框會以WM_COMMAND訊息的形式，將通知程式代碼傳送至擁有者視窗的對話框程式。 當使用者選取、按兩下或取消清單框專案時，會傳送清單框通知代碼;當清單框接收或失去鍵盤焦點時;當系統無法為清單框要求配置足夠的記憶體時。 WM_COMMAND訊息包含 wParam 參數低序字組的清單框標識碼，以及高序字組的通知碼。 lParam 參數包含控制元件視窗句柄。

處理這些訊息不需要對話框程式;默認視窗程式會加以處理。

應用程式應該監視及處理下列清單框通知碼。

通知程序代碼 描述
LBN_DBLCLK 用戶按兩下清單框中的專案。
LBN_ERRSPACE 清單框無法配置足夠的記憶體來滿足要求。
LBN_KILLFOCUS 清單框會失去鍵盤焦點。
LBN_SELCANCEL 使用者取消清單框中項目的選取專案。
LBN_SELCHANGE 清單框中的選取範圍即將變更。
LBN_SETFOCUS 清單框會接收鍵盤焦點。

清單框的訊息

對話框程式可以將訊息傳送至清單框，以新增、刪除、檢查及變更清單框專案。 例如，對話框程式可以將LB_ADDSTRING訊息傳送至清單框以新增專案，以及LB_GETSEL訊息來判斷專案是否已選取。 其他訊息會設定並擷取清單框的大小、外觀和行為相關信息。 例如， LB_SETHORIZONTALEXTENT 訊息會設定清單框的可捲動寬度。 對話框程式可以使用 SendMessage 或 SendDlgItemMessage 函式，將任何訊息傳送至清單方塊。

清單框專案通常由索引參考，這是代表專案在清單框中位置的整數。 清單框中第一個專案的索引為0、第二個專案的索引為1，依故。

下表描述預先定義的清單框程式如何回應清單框訊息。

訊息 回應
LB_ADDFILE 將檔案插入 DlgDirList 函式所填入的目錄清單框中，並擷取插入項目的清單框索引。
LB_ADDSTRING 將字串加入至清單框，並傳回其索引。
LB_DELETESTRING 從清單框中移除字串，並傳回保留在清單中的字串數目。
LB_DIR 將檔案名清單新增至清單框，並傳回已新增之檔名的索引。
LB_FINDSTRING 傳回清單框中以指定字串開頭之第一個字串的索引。
LB_FINDSTRINGEXACT 傳回清單框中等於指定字串的字串索引。
LB_GETANCHORINDEX 傳回滑鼠上次選取之專案的索引。
LB_GETCARETINDEX 傳回具有焦點矩形之專案的索引。
LB_GETCOUNT 傳回清單框中的項目數。
LB_GETCURSEL 傳回目前選取專案的索引。
LB_GETHORIZONTALEXTENT 傳回清單框的可捲動寬度，以像素為單位。
LB_GETITEMDATA 傳回與指定項目相關聯的值。
LB_GETITEMHEIGHT 傳回清單框中專案的高度，以像素為單位。
LB_GETITEMRECT 擷取指定清單框專案的用戶端座標。
LB_GETLOCALE 擷取清單框的地區設定。 高序字包含國家/地區代碼，低序字則包含語言標識符。
LB_GETSEL 傳回清單框項目的選取狀態。
LB_GETSELCOUNT 會傳回多重選取清單框中選取的項目數。
LB_GETSELITEMS 在多重選取清單框中，建立所有選取專案的索引陣列，並傳回選取項目的總數。
LB_GETTEXT 擷取與指定專案和字串長度相關聯的字串。
LB_GETTEXTLEN 傳回與指定專案相關聯之字串的長度，以字元為單位。
LB_GETTOPINDEX 傳回清單框中第一個可見專案的索引。
LB_INITSTORAGE 為指定的項目數目及其相關聯的字串配置記憶體。
LB_INSERTSTRING 在清單框中的指定索引處插入字串。
LB_ITEMFROMPOINT 擷取清單框中最接近指定點之專案之以零起始的索引。
LB_RESETCONTENT 從清單框中移除所有專案。
LB_SELECTSTRING 選取它找到符合指定前置詞的第一個字串。
LB_SELITEMRANGE 在清單框中選取指定的項目範圍。
LB_SELITEMRANGEEX 如果範圍中第一個專案的索引小於範圍中最後一個專案的索引，則選取指定的項目範圍。 如果第一個專案的索引大於最後一個專案，則取消範圍中的選取範圍。
LB_SETANCHORINDEX 將滑鼠最後選取的項目設定為指定的專案。
LB_SETCARETINDEX 將焦點矩形設定為指定的清單框專案。
LB_SETCOLUMNWIDTH 設定清單框中所有數據行的寬度，以像素為單位。
LB_SETCOUNT 設定清單框中的項目數。
LB_SETCURSEL 選取指定的清單框專案。
LB_SETHORIZONTALEXTENT 設定清單框的可捲動寬度，以像素為單位。
LB_SETITEMDATA 將值與清單框專案產生關聯。
LB_SETITEMHEIGHT 設定清單框中專案的高度，以像素為單位。
LB_SETLOCALE 設定清單框的地區設定，並傳回先前的地區設定標識符。
LB_SETSEL 在多重選取清單框中選取專案。
LB_SETTABSTOPS 將製表位設定為指定數位中指定的定位點。
LB_SETTOPINDEX 捲動清單框，使指定的項目位於可見範圍的頂端。

默認視窗訊息處理

預先定義清單框視窗類別的視窗程式會針對清單框未處理的所有訊息執行預設處理。 當清單框程式傳回 訊息的 FALSE 時，預先定義的視窗程式會檢查訊息並執行預設動作，如下表所示。

訊息 默認動作
WM_CHAR 將選取範圍移至以使用者輸入的字元開頭的第一個專案。 如果清單框具有 LBS_OWNERDRAW 樣式，則不會發生任何動作。 在短間隔內輸入的多個字元會被視為群組，並選取以該數位字元開頭的第一個專案。
WM_CREATE 建立空的清單框。
WM_DESTROY 終結清單框，並釋放其使用的任何資源。
將訊息傳遞至對話框程式或父窗口進程。
WM_ENABLE 如果控件是可見的，則會使矩形失效，以便將字串繪製成灰色。
WM_ERASEBKGND 清除清單框的背景。 如果清單框具有 LBS_OWNERDRAW 樣式，則不會清除背景。
WM_GETDLGCODE 傳回DLGC_WANTARROWS |DLGC_WANTCHARS，表示預設清單框程式會處理箭頭鍵和 WM_CHAR 訊息。
WM_GETFONT 傳回清單框目前字型的句柄。
WM_HSCROLL 水平捲動清單框。
WM_KEYDOWN 處理虛擬金鑰以進行捲動。 虛擬索引鍵是要移動插入號的專案索引。 不會變更選取範圍。
WM_KILLFOCUS 關閉插入號並摧毀它。 將 LBN_KILLFOCUS 通知碼傳送給清單框的擁有者。
WM_LBUTTONDBLCLK 追蹤清單框工作區中的滑鼠。 這可讓使用者在清單框工作區外放開滑鼠按鈕時取消選取專案。
WM_LBUTTONDOWN 追蹤清單框工作區中的滑鼠。 這可讓使用者在清單框工作區外放開滑鼠按鈕時取消選取專案。
WM_LBUTTONUP 追蹤清單框工作區中的滑鼠。 這可讓使用者在清單框工作區外放開滑鼠按鈕時取消選取專案。
WM_MOUSEMOVE 追蹤清單框工作區中的滑鼠。 這可讓使用者在清單框工作區外放開滑鼠按鈕時取消選取專案。
WM_PAINT 使用清單框句柄對裝置內容 （DC） 執行子類別化繪製作業。
WM_SETFOCUS 開啟插入號，並將LBN_SETFOCUS通知碼傳送給清單框的擁有者。
WM_SETFONT 設定清單框的新字型。
WM_SETREDRAW 根據 wParam 的值設定或清除重繪旗標。
WM_SIZE 將清單框大小調整為整數項目數。
WM_VSCROLL 垂直捲動清單框。

預先定義的清單框程式會將所有其他訊息傳遞至 DefWindowProc 以進行默認處理。

擁有者繪製的清單框

應用程式可以建立 擁有者繪製 清單框，以負責繪製清單專案。 需要繪製清單框部分時，擁有者繪製清單框的父視窗或對話框（其 擁有者）會收到 WM_DRAWITEM 訊息。 擁有者繪製的清單框可以列出文字字串以外的資訊，或是以外的資訊。

擁有者繪製清單框的擁有者必須處理 WM_DRAWITEM 訊息。 每當必須重新繪製清單框的一部分時，就會傳送此訊息。 根據清單框指定的樣式，擁有者可能需要處理其他訊息。

應用程式可以藉由指定LBS_OWNERDRAWFIXED或LBS_OWNERDRAWVARIABLE樣式來建立擁有者繪製的清單框。 如果清單框中的所有清單專案高度相同，例如字串或圖示，則應用程式可以使用 LBS_OWNERDRAWFIXED 樣式。 如果清單專案高度不同（例如不同大小的點陣圖），應用程式可以使用 LBS_OWNERDRAWVARIABLE 樣式。

擁有者繪製清單框的擁有者可以處理 WM_MEASUREITEM 訊息，以指定清單項目的維度。 如果應用程式使用 LBS_OWNERDRAWFIXED 樣式建立清單框，系統只會傳送 WM_MEASUREITEM 訊息一次。 擁有者所指定的維度會用於所有清單專案。 如果使用LBS_OWNERDRAWVARIABLE樣式，系統會針對新增至清單框的每個清單專案傳送WM_MEASUREITEM訊息。 擁有者可以使用LB_GETITEMHEIGHT和LB_SETITEMHEIGHT訊息，隨時判斷或設定清單專案的高度。

如果主控繪製清單框中顯示的資訊包含文字，應用程式可以藉由指定 LBS_HASSTRINGS 樣式來追蹤每個清單專案的文字。 具有 LBS_SORT 樣式的清單框會根據此文字排序。 如果清單框已排序，但不是LBS_HASSTRINGS樣式，則擁有者必須處理WM_COMPAREITEM訊息。

在擁有者繪製的清單框中，擁有者必須追蹤包含文字以外的信息的清單專案。 若要這樣做，其中一個便利方式是使用 LB_SETITEMDATA 訊息，將句柄儲存至資訊做為項目數據。 若要釋放與清單框中專案相關聯的數據對象，擁有者可以處理 WM_DELETEITEM 訊息。

如需擁有者繪製清單框的範例，請參閱 如何建立擁有者繪製清單框。

拖曳清單框

拖曳列表框是特殊的清單框類型，可讓使用者將專案從某個位置拖曳到另一個位置。 應用程式可以使用拖曳列表框來顯示特定序列中的字串，並讓使用者將專案拖曳到位置來變更序列。

建立拖曳清單框

拖曳列表框具有相同的窗口樣式，並處理與標準清單框相同的訊息。 若要建立拖曳列表框，請先建立標準清單框，然後呼叫 MakeDragList 函式。 若要將對話框中的清單框轉換成拖曳列表框，您可以在處理WM_INITDIALOG訊息時呼叫 MakeDragList 。

拖曳清單框訊息

拖曳列表框會藉由傳送拖曳列表訊息，通知拖曳事件的父視窗。 父窗口必須處理拖曳清單訊息。

呼叫MakeDragList函式時，拖曳清單框會註冊此訊息。 若要擷取拖曳列表訊息的訊息標識碼（數值），請呼叫 RegisterWindowMessage 函式並指定 DRAGLISTMSGSTRING 值。

拖曳清單訊息的 wParam 參數是拖曳列表框的控制標識符。 lParam 參數是 DRAGLISTINFO 結構的位址，其中包含拖曳事件和其他資訊的通知碼。 訊息的傳回值取決於通知。

拖曳清單框通知碼

拖曳清單通知程序代碼，由拖曳列表訊息隨附之 DRAGLISTINFO 結構的 uNotification 成員識別，可以是DL_BEGINDRAG、DL_DRAGGING、DL_CANCELDRAG或DL_DROPPED。

當 游標位於清單專案上，且使用者按兩下滑鼠左鍵時，就會傳送DL_BEGINDRAG 通知碼。 父視窗可以傳回 TRUE 以開始拖曳作業或 FALSE 以不允許拖曳。 如此一來，父視窗就可以針對某些清單專案啟用拖曳，並停用其他專案。 您可以使用 LBItemFromPt 函式來判斷位於指定位置的清單專案。

如果拖曳生效， 每當移動滑鼠時，就會傳送DL_DRAGGING 通知碼，如果滑鼠未移動，則會定期傳送通知碼。 父視窗應該先使用 LBItemFromPt 來判斷游標下的清單專案，然後使用 DrawInsert 函式繪製插入圖示。 藉由為 LBItemFromPt 的 bAutoScroll 參數指定 TRUE，當游標位於其工作區上方或下方時，可能會讓清單框捲動一行。 您為此通知傳回的值會指定拖曳列表框應該設定的滑鼠游標類型。

如果使用者按下滑鼠右鍵或按下 ESC 鍵來取消拖曳作業，就會傳送DL_CANCELDRAG通知碼。 如果用戶藉由放開滑鼠左鍵來完成拖曳作業，即使游標不在清單專案上，也會傳送DL_DROPPED通知碼。 拖曳清單框會在傳送任一個通知之前釋放滑鼠擷取。 會忽略這兩個通知的傳回值。 拖曳清單