關於清單框

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

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

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

本節討論下列主題：

• 建立清單框
• 清單框類型和樣式
• 清單框函式
• 從清單框的通知訊息
• 對清單框的訊息
• 預設視窗訊息處理
• Owner-Drawn 清單框
• 拖曳列表框
  • 建立拖曳列表框
  • 拖曳列表框訊息
  • 拖曳清單框通知碼

建立清單框

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

清單框類型和樣式

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

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

注意

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

清單框函式

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_擦除背景	清除清單框的背景。 如果清單框具有 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，以進行默認處理。

Owner-Drawn 清單框

應用程式可以建立 業主繪製的 清單框，以負責繪製清單項目。 當需要繪製清單框的部分時，由擁有者繪製的清單框的父窗口或對話框（其擁有者為 ）才會收到 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 訊息。

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

拖曳清單框

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

建立拖曳清單框

拖曳列表框具有相同的窗口樣式，並處理與標準清單框相同的訊息。 若要建立拖曳列表框，請先建立標準清單框，然後呼叫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 通知碼。 拖曳清單框會在傳送任一個通知之前釋放滑鼠擷取。 這兩個通知的傳回值將被忽略。 拖曳清單