共用方式為


關於清單檢視控件

請參閱虛擬 listview 控件範例

清單檢視控件是顯示專案集合的視窗。 清單檢視控件提供數種方式來排列和顯示專案,而且比簡單的 清單框更有彈性。 例如,每個專案的其他資訊可以顯示在圖示和標籤右邊的數據行中。

清單檢視樣式和檢視

清單檢視控件可以在五個不同的檢視中顯示專案。 控制件的視窗樣式會指定預設檢視。 其他窗口樣式會指定專案和控件特定功能的對齊方式。 下表描述檢視。

檢視表名稱 描述
圖示檢視 LVS_ICON視窗樣式指定,或使用LVM_SETVIEW訊息傳遞LV_VIEW_ICON。 每個項目都會以完整大小的圖示顯示,其下方有標籤。 用戶可以將專案拖曳至清單檢視視窗中的任何位置。
小型圖示檢視 LVS_SMALLICON視窗樣式指定,或使用 LVM_SETVIEW 傳遞LV_VIEW_SMALLICON。 每個項目都會以小型圖示顯示,其中標籤在右邊。 用戶可以將專案拖曳至任何位置。
清單檢視 LVS_LIST視窗樣式指定,或使用 LVM_SETVIEW 傳遞LV_VIEW_LIST。 每個項目都會以小型圖示的形式顯示,其右側有標籤。 專案會排列在數據行中,而且用戶無法將其拖曳至任意位置。
報表 (詳細數據) 檢視 LVS_REPORT視窗樣式指定,或使用 LVM_SETVIEW 傳遞LV_VIEW_DETAILS。 每個項目都會以自己的行顯示,其中的資訊會排列在數據行中。 最左邊的數據行一律靠左對齊,並包含小型圖示和標籤。 後續數據行包含應用程式所指定的子專案。 除非您也指定 LVS_NOCOLUMNHEADER 視窗樣式,否則每個數據行都有標頭。
磚檢視 第 6 版和更新版本。 使用 LVM_SETVIEW 傳遞LV_VIEW_TILE來指定。 每個項目都會以完整大小的圖示顯示,其標籤旁邊有一或多個行的標籤。

 

下列螢幕快照會使用檢視來顯示每個七隻寵物的不同數量資訊。 檢視會示範資訊如何在 Windows Vista 上顯示。 控件的可視化樣式已使用 SetWindowTheme 設定為 “Explorer” 主題。

下列螢幕快照顯示詳細數據檢視。

screen shot that shows information in five columns and seven rows

下列螢幕快照顯示圖示檢視。

screen shot that shows only the name of each pet and an icon indicating the species

下列螢幕快照顯示清單檢視。

screen shot that shows, for each pet, a large icon next the text of the pet's name, breed, and price

下列螢幕快照顯示磚檢視。

tile view.

您可以在建立清單檢視控件之後變更檢視類型。 若要擷取和變更窗口樣式,請使用 GetWindowLong SetWindowLong 函式。 若要判斷目前檢視的窗口樣式,請使用 LVS_TYPEMASK 值。

您可以指定LVS_ALIGNTOPLVS_ALIGNLEFT視窗樣式,來控制專案在圖示或小型圖示檢視中排列的方式。

您可以在建立清單檢視控件之後變更對齊方式。 若要判斷目前的對齊方式,請使用 LVS_ALIGNMASK 值。

其他視窗樣式提供其他選項,例如使用者是否可以編輯標籤或一次選取多個專案。 如需完整清單,請參閱 清單檢視窗口樣式

擴充清單檢視樣式

擴充清單檢視控件樣式提供選項,例如複選框、平面滾動條、網格線和熱追蹤。 如需完整清單,請參閱 擴充清單檢視樣式。 您不會以與標準視窗樣式相同的方式存取擴充清單檢視樣式。 您不使用 GetWindowLongSetWindowLong 函式來進行延伸樣式變更。

有兩則訊息會設定和擷取擴充樣式資訊,LVM_SETEXTENDEDLISTVIEWSTYLELVM_GETEXTENDEDLISTVIEWSTYLE。 您可以使用下列對應的宏,而不是明確傳送訊息:ListView_SetExtendedListViewStyleListView_SetExtendedListViewStyleExListView_GetExtendedListViewStyle。

虛擬清單檢視樣式

虛擬清單檢視是具有 LVS_OWNERDATA 樣式的清單檢視控件。 此樣式可讓控件處理數百萬個專案,因為擁有者會收到管理專案數據的負擔。 這可讓您將虛擬清單檢視控件與大型資訊資料庫搭配使用,其中已有特定的數據存取方法。

虛擬清單檢視控件會維護很少的項目資訊本身。 除了項目選取和焦點資訊之外,控件的擁有者必須管理所有項目資訊。 其他進程會使用 LVN_GETDISPINFO 通知碼向擁有者要求項目資訊。

由於這種類型的清單控件適用於大型數據集,因此建議您快取要求的項目數據,以改善擷取效能。 清單檢視提供可協助優化快取的快取提示機制。 提示是以LVN_ODCACHEHINT通知程序代碼的形式實作。

建立虛擬清單檢視控件

您可以使用 CreateWindow 或 CreateWindowEx 函式建立虛擬清單檢視控件,並將LVS_OWNERDATA視窗樣式指定為 dwStyle 函式參數的一部分。 不支援動態切換至LVS_OWNERDATA樣式及從 LVS_OWNERDATA 樣式。

除了LVS_SORTASCENDING或LVS_SORTDESCENDING樣式以外,您可以使用LVS_OWNERDATA樣式與其他大多數窗口樣式。 所有虛擬清單檢視控件預設為 LVS_AUTOARRANGE 樣式。

若要讓項目顯示在清單中,您必須先明確或使用 ListView_SetItemCountEx 宏來傳送LVM_SETITEMCOUNT訊息。

LVS_OWNERDATA 樣式不支援下列訊息:LVM_ENABLEGROUPVIEWLVM_GETITEMTEXTLVM_SETTILEINFOLVM_MAPIDTOINDEX。

相容性問題

所有四個清單檢視樣式—圖示、小型圖示、清單和報表檢視—都支援 LVS_OWNERDATA 樣式。 具有 LVS_OWNERDATA 樣式的清單檢視控件不會儲存任何專案特定資訊。 因此,您可以套用至專案的唯一有效項目狀態旗標是LVIS_SELECTEDLVIS_FOCUSED。 不會儲存其他狀態資訊。 特別是清單檢視控件不會維護每個項目的狀態或重疊影像。 不過,您可以藉由傳送 LVM_SETCALLBACKMASK 訊息,讓清單檢視控件查詢您的應用程式是否有這些影像。

大部分的清單檢視控件訊息和相關聯的宏都完全受到支援。 不過,當您使用 LVS_OWNERDATA 樣式時,某些訊息有限制或不受支援。 下表摘要說明受影響的訊息。

訊息 限制
LVM_ARRANGE 不支援 LVA_SNAPTOGRID 樣式。
LVM_DELETEALLITEMS 將專案計數設定為零,並清除所有內部選取變數,但實際上不會刪除任何專案。 它會發出通知回呼。
LVM_DELETEITEM 僅支持選取完整性,而且不會實際刪除專案。
LVM_GETITEMSTATE 只傳回焦點和選取狀態(也就是清單檢視控件所儲存的狀態)。
LVM_GETNEXTITEM 不支援清單檢視搜尋準則 LVNI_CUTLVNI_HIDDENLVNI_DROPHILITED。 支援所有其他準則。
LVM_GETWORKAREAS 不支援 。
LVM_INSERTITEM 僅支持選取完整性。
LVM_SETITEM 不支援 。 若要設定項目狀態,請使用 ListView_SetItemState 訊息。
LVM_SETITEMCOUNT 設定清單中目前的項目數。 如果清單檢視控件傳送通知,要求任何項目的數據上限,則擁有者必須準備好提供該數據。 訊息參數支持虛擬清單檢視控件。
LVM_SETITEMPOSITION 不支援 。
LVM_SETITEMSTATE 只允許變更項目的選取和焦點狀態。
LVM_SETITEMTEXT 不支援 。 應用程式必須負責維護項目文字。
LVM_SETWORKAREAS 不支援 。
LVM_SORTITEMS 不支援 。 應用程式有責任以所需的順序呈現專案。

 

處理虛擬清單檢視控件通知碼

具有 LVS_OWNERDATA 樣式的清單檢視控件會傳送與其他清單檢視控件相同的通知碼,另外兩個控件: LVN_ODCACHEHINTLVN_ODFINDITEM。 以下是清單檢視控件與 LVS_OWNERDATA 樣式傳送的最常見通知。

通知 描述
LVN_GETDISPINFO 虛擬清單檢視控件會自行維護很少的項目資訊。 因此,它通常會傳送 LVN_GETDISPINFO 通知程式代碼來要求項目資訊。 此訊息的處理方式與標準清單控制件中的回呼專案大致相同。 因為控件所支援的項目數目可能非常大,因此快取項目數據可改善效能。 處理LVN_GETDISPINFO時,控件的擁有者會先嘗試從快取提供要求的項目資訊(如需詳細資訊,請參閱 快取管理)。 如果未快取要求的專案,則必須準備擁有者以其他方式提供資訊。
LVN_ODCACHEHINT 虛擬清單檢視會 傳送LVN_ODCACHEHINT 通知程式代碼,以協助優化快取。 通知程式代碼會為建議快取的專案範圍提供內含索引值。 收到通知碼時,擁有者必須準備好以要求範圍的專案資訊載入快取,以便在傳送LVN_GETDISPINFO訊息時隨時提供資訊。
LVN_ODFINDITEM 控件需要擁有者尋找特定回呼專案時,虛擬清單檢視控件會傳送LVN_ODFINDITEM 通知碼。 當清單檢視控件收到快速密鑰存取或收到LVM_FINDITEM訊息時,就會傳送通知碼。 搜尋資訊會以 LVFINDINFO 結構的形式傳送,這是 NMLVFINDITEM 結構的成員。 擁有者必須準備好搜尋符合清單檢視控件所提供信息的專案。 如果成功,擁有者會傳回專案的索引,如果找不到相符的專案,則傳回 -1。

 

快取管理

具有LVS_OWNERDATA樣式的清單檢視控件會產生大量LVN_GETDISPINFO通知碼,以及協助優化快取LVN_ODCACHEHINT訊息。 LVN_ODCACHEHINT訊息會提供建議專案的相關信息,以包含在快取中。 這些訊息會以WM_NOTIFY訊息的形式傳送,而 lParam 值會做為 NMLVCACHEHINT 結構的位址。

NMLVCACHEHINT 結構包含兩個整數成員 iFromiTo,代表最可能需要之專案範圍的內含端點。 擁有者必須準備好以建議範圍內每個專案的專案資訊載入快取。

清單控制項通常需要第一個項目的專案資訊(位移0)。 LVN_ODCACHEHINT通知程式代碼不一定包含專案 0,但必須一律包含在快取中。

通常會存取清單中的最後一個專案。 因此,擁有者可能會想要保留第二個快取,其中包含清單結尾的專案。 從 LVN_ODCACHEHINT 的要求範圍可以針對端快取進行檢查,使其可供自動使用,而不是每次重載相同的結束範圍。

清單檢視工作區域

清單檢視控件支援工作區域,這是清單檢視控件用來排列其專案的矩形虛擬區域。 工作區不是視窗,而且不能有可見的框線。 根據預設,清單檢視控件沒有工作區域。 藉由建立工作區,您可以在專案的左、上或右方建立空白框線,或導致水準滾動條在通常不會顯示時顯示。

建立工作區時,位於工作區內的專案會成為工作區的成員。 同樣地,如果專案移至工作區域,專案就會成為該工作區域的成員。 如果項目不位於任何工作區域內,它會自動成為第一個 (索引 0) 工作區的成員。 若要將新專案放在特定工作區域內,您必須先建立專案,然後使用LVM_SETITEMPOSITIONLVM_SETITEMPOSITION32訊息將它移至所需的工作區域。

下圖是清單檢視控件的範例,其中包含四個工作區域,每個區域位於不同工作區的象限中。

screen shot of a list-view control with one working area in each quadrant of the client area

多個工作區域可用於在一個檢視內建立不同的區域。 您可以在具有不同意義的單一檢視中建立區域。 例如,文件系統的檢視可能有讀取/寫入檔案的區域,以及唯讀檔案的另一個區域。 用戶可以將專案放在不同的工作區域中來分類專案。 如果檔案移至唯讀區域,它會自動變成唯讀。

多個工作區域可以交集,但位於交集內的任何專案會變成具有較低索引的區域成員;因此,最好避免這種情況。 排序多個工作區域時,專案會與相同工作區域中的其他項目進行排序。

可以使用LVM_GETNUMBEROFWORKAREAS訊息來擷取工作區域數目。 工作區域會隨著LVM_SETWORKAREAS訊息變更,而且可以使用LVM_GETWORKAREAS訊息來擷取。 這兩則訊息都會採用 RECT 結構的數位位址做為 lParam,而 RECT 結構的數目則為 wParam。 這些 結構的左頂端 成員會指定工作區左上角(原點)的座標,而 成員則指定工作區的右下 角。 所有座標都位於清單檢視的用戶端座標中。 允許的工作區域數目上限是由 LV_MAX_WORKAREAS 值所定義。

變更工作區不會影響具有LVS_LIST或LVS_REPORT檢視的清單檢視控件,但工作區域會在檢視類型變更時維持。 使用LVS_ICONLVS_SMALLICON檢視,即可修改工作區以變更項目顯示的方式。 使工作區的寬度 (右 - 左) 大於控件的用戶端寬度,會使專案以該寬度包裝,並顯示水準滾動條。 使工作區的寬度小於控件工作區的寬度,會使專案包裝在工作區域內,而不是工作區。 將左成員或頂端成員設定為正值,會使專案從工作區域開始顯示,在控件邊緣與專案之間建立空白空間。 您也可以在控件的右邊緣與項目之間建立空白空間,方法是讓工作區的寬度小於控件的用戶端寬度。

清單檢視影像清單

根據預設,清單檢視控件不會顯示專案影像。 若要顯示專案影像,您必須建立影像清單,並將其與 控件產生關聯。 清單檢視控制項可以有三個影像清單:

  • 影像清單,其中包含控件處於圖示檢視時所顯示的完整大小圖示。
  • 影像清單,其中包含控件處於小型圖示檢視、清單檢視或報表檢視時所顯示的小型圖示。
  • 包含狀態影像的影像清單,其會顯示在完整大小或小型圖示的左邊。 您可以使用狀態影像,例如已核取和已清除的複選框,來指出應用程式定義的項目狀態。 狀態影像會顯示在圖示檢視、小型圖示檢視、清單檢視和報表檢視中。

完整大小和小型圖示影像清單也可以包含 重疊影像,其設計目的是要以透明的方式繪製在項目圖示上。

若要在清單檢視控件中使用重疊影像:

  1. 呼叫 ImageList_SetOverlayImage 函式,將重疊影像索引指派給完整大小和小型圖示影像清單中的影像。 重疊影像是由一個以單一為基礎的索引來識別。
  2. 呼叫ListView_InsertItemListView_SetItem宏時,您可以將重疊影像索引與專案產生關聯。 使用 INDEXTOOVERLAYMASK 宏,在專案的 LVITEM 結構狀態成員中指定重疊影像索引。 您也必須在 stateMask 成員中設定LVIS_OVERLAYMASK位。

如果指定狀態影像清單,清單檢視控件會保留狀態影像每個項目圖示左邊的空間。

若要將狀態影像與專案產生關聯,請使用 INDEXTOSTATEIMAGEMASK 宏,在 LVITEM 結構的狀態成員指定狀態影像索引。 索引會識別控件狀態映像清單中的影像。 雖然影像清單索引是以零起始,但控件會使用單一式索引來識別狀態影像。 狀態影像索引為零,表示項目沒有狀態影像。

根據預設,當清單檢視控件終結時,它會終結指派給它的影像清單。 不過,如果清單檢視控件具有 LVS_SHAREIMAGELISTS 視窗樣式,應用程式會負責在影像清單不再使用時終結影像清單。 如果您將相同的影像清單指派給多個清單檢視控件,則應該指定此樣式;否則,多個控件可能會嘗試終結相同的映像清單。

清單檢視專案和子專案

清單檢視控件中的每個專案都有圖示、標籤、目前狀態,以及應用程式定義的值。 藉由使用清單檢視訊息,您可以新增、修改和刪除專案,以及擷取專案的相關信息。

每個專案可以有一或多個 子專案。 子專案是一個字串,在報表檢視中會顯示在與項目圖示和標籤分開的數據行中。 若要指定子專案的文字,請使用LVM_SETITEMTEXTLVM_SETITEM訊息。 清單檢視控件中的所有專案都有相同的子項目數目。 子項目數目取決於清單檢視控件中的數據行數目。 當您將資料行加入清單檢視控件時,您可以指定其相關聯的子專案索引。

LVITEM 結構會定義清單檢視專案或子專案。 iItem 成員是專案以零起始的索引。 如果結構包含專案的相關信息,則 iSubItem 成員是子專案的單一索引或零。 其他成員會指定項目的文字、圖示、狀態和項目資料。 項目數據 是與清單檢視專案相關聯的應用程式定義值。

若要將專案新增至清單檢視控件,請使用LVM_INSERTITEM訊息,並指定 LVITEM 結構的位址。 新增多個專案之前,您可以傳送控件LVM_SETITEMCOUNT訊息,指定控件最終將包含的項目數目。 此訊息可讓清單檢視控件只重新配置其內部數據結構一次,而不是每次新增專案時。 您可以使用LVM_GETITEMCOUNT訊息來判斷清單檢視控制項中的項目數目。 如果您要將大量專案新增至清單檢視控件,您可以先停用重繪再新增專案,然後在新增專案之後啟用重新繪製,以加速程式。 使用WM_SETREDRAW訊息來啟用和停用重繪。

若要變更清單檢視項目的屬性,請使用LVM_SETITEM訊息,指定 LVITEM 結構的位址。 這個 結構的遮罩 成員會指定您想要變更的項目屬性。 例如,若只要變更專案或子專案的文字,請使用 LVM_SETITEMTEXT 訊息。

若要擷取清單檢視專案的相關信息,請使用LVM_GETITEM訊息,指定要填入之 LVITEM 結構的位址。 這個 結構的遮罩 成員會指定要擷取的項目屬性。 若要只擷取專案或子專案的文字,請使用 LVM_GETITEMTEXT 訊息。

若要刪除清單檢視專案,請使用 LVM_DELETEITEM 訊息。 您可以使用LVM_DELETEALLITEMS訊息,刪除清單檢視控件中的所有專案。

清單檢視項目狀態

專案的狀態是指定專案可用性、指出用戶動作或反映項目狀態的值。 清單檢視控件會變更一些狀態位,例如當用戶選取專案時。 應用程式可能會變更其他狀態位來停用或隱藏專案,或指定重疊影像或狀態影像。 如需重疊影像和狀態影像的詳細資訊,請參閱 清單檢視影像清單

項目的狀態是由 LVITEM 結構的狀態成員所指定。 當您指定或變更項目的狀態時, stateMask 成員會指定您需要變更的狀態位。 您可以使用LVM_SETITEMSTATE訊息來變更項目的狀態。 您可以在建立專案時,或使用LVM_SETITEM訊息來變更其屬性時指定其狀態。 若要判斷專案的目前狀態,請使用LVM_GETITEMSTATELVM_GETITEM訊息。

若要設定專案的重疊影像,LVITEM 結構的 stateMask 成員必須包含LVIS_OVERLAYMASK值,而狀態成員必須使用 INDEXTOOVERLAYMASK 宏,包含以單一為基礎的重疊影像索引,該重疊影像的左移位為 8 位。 索引可以是零,以指定沒有重疊影像。

若要設定專案的狀態影像,LVITEM 結構的 stateMask 成員必須包含LVIS_STATEIMAGEMASK值,而狀態成員必須使用 INDEXTOSTATEIMAGEMASK 宏,包含狀態影像的一個基底索引,而狀態影像的左移位為 12 位。 索引可以是零,以指定沒有狀態影像。

回呼項目和回呼遮罩

針對每個專案,清單檢視控件通常會儲存標籤文字、專案圖示的影像清單索引,以及項目狀態的一組位旗標。 您可以定義回呼專案或變更控件的回呼遮罩,以指出應用程式而非控件會儲存部分或全部的資訊。 如果您的應用程式儲存其中一些資訊,您可能會想要使用回呼。

清單檢視控件中的回呼專案是應用程式儲存文字或圖示索引或兩者的專案。 當您將LVM_INSERTITEM訊息傳送至清單檢視控件時,您可以定義回呼專案。 如果應用程式儲存專案或子專案的文字,請將專案的 LVITEM 結構的 pszText 成員設定LPSTR_TEXTCALLBACK 如果應用程式儲存專案的圖示索引,請將專案的 LVITEM 結構的 iImage 成員設定I_IMAGECALLBACK

清單檢視控件的回呼遮罩是一組位旗標,可指定應用程式而非控件儲存目前數據的項目狀態。 回呼遮罩適用於所有控制項的項目,與套用至特定項目的回呼項目指定不同。 回呼遮罩預設為零,這表示清單檢視控件會儲存所有項目狀態資訊。 建立清單檢視控件並初始化其項目之後,您可以傳送 LVM_SETCALLBACKMASK 訊息來變更回呼遮罩。 若要擷取目前的回呼遮罩,請傳送 LVM_GETCALLBACKMASK 訊息。

當清單檢視控件必須顯示或排序應用程式儲存回呼資訊的清單檢視專案時,控件會將LVN_GETDISPINFO通知程式代碼傳送至控件的父視窗。 此訊息會 指定 NMLVDISPINFO 結構,其中包含所需的信息類型,並識別要擷取的專案或子專案。 父窗口必須處理LVN_GETDISPINFO以提供要求的數據。

如果清單檢視控件偵測到專案回呼資訊的變更,例如文字、圖示或狀態資訊的變更,控件就會傳送 LVN_SETDISPINFO 通知程式代碼來通知您變更。

如果您變更回呼項目的屬性或狀態位,您可以使用 LVM_UPDATE 訊息來強制控件重新繪出專案。 如果控件具有LVS_AUTOARRANGE樣式,此訊息也會讓控件排列其專案。 您可以使用 LVM_REDRAWITEMS 訊息來重新繪製專案範圍,方法是使清單檢視控件工作區的對應部分失效。

藉由有效地使用回呼專案和回呼遮罩,您可以確保每個項目屬性都只保留在一個位置。 這樣做可以簡化您的應用程式,但唯一儲存的空間是儲存專案卷標和子專案文字所需的記憶體。

清單檢視專案位置

每個清單檢視專案都有一個位置和大小,您可以使用訊息來擷取和設定。 您也可以判斷哪個專案,如果有的話,位於指定的位置。 清單檢視專案的位置是在檢視座標指定,這些座標是由捲動位置所位移的用戶端座標。

若要擷取和設定專案的位置,請使用 LVM_GETITEMPOSITIONLVM_SETITEMPOSITION 訊息。 LVM_GETITEMPOSITION適用於所有檢視,但LVM_SETITEMPOSITION僅適用於圖示和小型圖示檢視。

您可以使用LVM_HITTEST訊息來判斷位於特定位置的專案。

若要擷取清單專案的周框,或只擷取其圖示或標籤的周框,請使用 LVM_GETITEMRECT 訊息。

排列、排序和尋找專案

您可以使用清單檢視訊息來排列和排序專案,並根據項目的屬性或位置尋找專案。 排列重新定位專案以對齊網格線,但專案的索引不會變更。 排序會變更項目順序(及其對應的索引),然後據以重新置放。 您只能在圖示和小型圖示檢視中排列專案,但您可以在任何檢視中排序專案。 若要尋找專案,您可以傳送指定專案位置或屬性的清單檢視訊息。

若要排列專案,請使用 LVM_ARRANGE 訊息。 您可以指定 LVS_AUTOARRANGE 視窗樣式,以確保專案隨時排列。

若要排序專案,請使用 LVM_SORTITEMS 訊息。 當您使用此訊息排序時,您會指定清單檢視控件呼叫的應用程式定義回呼函式,以比較任兩個項目的相對順序。 控件會傳遞至比較函式,將項目數據與這兩個專案的每個專案相關聯。 項目數據是在專案 LVITEM 結構之 lParam 成員中插入清單時所指定的值。 藉由指定適當的項目數據並提供適當的比較函式,您可以依其標籤、任何子專案或任何其他屬性來排序專案。 請注意,排序專案不會重新排序對應的子專案。 重新排序專案時,其對應的子專案會隨其一起攜帶;也就是說,整個數據列會一起保留。 若要彼此分開排序數據行,請將子專案與其專案中斷連結,您必須在使用 LVM_SETITEM 排序之後重新產生數據行。

您可以指定LVS_SORTASCENDINGLVS_SORTDESCENDING視窗樣式,確保一律排序列表檢視控件。 具有這些樣式的控件會使用專案的標籤文字,以遞增或遞減順序排序。 使用這些視窗樣式時,您無法提供比較函式。 如果清單檢視控件有其中一種樣式,如果您嘗試插入LPSTR_TEXTCALLBACK做為其 LVITEM 結構的 pszText 成員的專案LVM_INSERTITEM訊息將會失敗。

您可以使用LVM_FINDITEM訊息,找到具有特定屬性的清單檢視專案。 您可以使用LVM_GETNEXTITEM訊息,找到處於指定狀態且與指定專案具有指定關聯性的清單檢視專案。 例如,您可以擷取指定專案右邊的下一個選取專案。

清單檢視數據行

數據行會控制專案及其子項目在報表檢視中顯示的方式。 每個數據行都有標題和寬度,且與特定子項目相關聯;子專案零是專案的圖示和標籤。 數據行的屬性是由 LVCOLUMN 結構所定義。

若要將資料行新增至清單檢視控件,請使用 LVM_INSERTCOLUMN 訊息。 若要刪除資料行,請使用 LVM_DELETECOLUMN 訊息。

注意

只有在 ComCtl32.dll第 6 版和更新版本中才支援刪除清單檢視控件的數據行零。 第 5 版也支援刪除資料行零,但只有在您使用 CCM_SETVERSION 將版本設定為 5 或更新版本之後。 第 5 版之前的版本不支援刪除資料行零。

 

您可以使用LVM_GETCOLUMN和LVM_SETCOLUMN訊息來擷取和變更現有數據行的屬性。 若要擷取或變更數據行的寬度,請使用 LVM_GETCOLUMNWIDTHLVM_SETCOLUMNWIDTH 訊息。

除非指定 LVS_NOCOLUMNHEADER 視窗樣式,否則數據行標頭會出現在報表檢視中。 使用者可以按下數據行標頭,導致 LVN_COLUMNCLICK 通知程式代碼傳送至父視窗。 一般而言,父視窗會在發生這個按兩下時,依指定的數據行排序列表檢視控件。 使用者也可以拖曳標頭之間的數據行參考線,以調整數據行的大小。

清單檢視控件可以顯示數據行標題旁的影像。 若要實作這項功能,請指定LVCF_IMAGE值,並將影像的索引指派給 LVCOLUMN 結構中的 iImage 成員。

清單檢視控件可以設定顯示數據行的順序。 若要實作這項功能,請指定LVCF_ORDER值,並將數據行順序指派給 LVCOLUMN 結構中的 iOrder 成員。 數據行順序是以零起始,並以從左至右的順序排列。 例如,零表示最左邊的數據行。

清單檢視卷動位置

除非指定LVS_NOSCROLL視窗樣式,否則可以捲動清單檢視控件以顯示超過控件工作區中可容納的專案。 您可以擷取清單檢視控件的捲動位置和相關信息、依指定的數量卷動清單檢視控件,或捲動清單檢視控件,以便顯示指定的清單專案。

在圖示檢視或小型圖示檢視中,目前的捲動位置是由 檢視原點所定義。 檢視原點是相對於清單檢視控件可見區域,對應至檢視座標 (0, 0) 的座標集合。 若要擷取目前的檢視原點,請使用 LVM_GETORIGIN 訊息。 此訊息只應用於圖示或小型圖示檢視;它會在清單或報表檢視中傳回錯誤。

在清單或報表檢視中,目前的捲動位置是由 頂端索引所定義。 頂端索引是清單檢視控件中第一個可見專案的索引。 若要擷取目前的頂端索引,請使用 LVM_GETTOPINDEX 訊息。 此訊息只會在清單或報表檢視中傳回有效的結果;它會傳回圖示或小型圖示檢視中的零。

您可以使用 LVM_GETVIEWRECT 訊息來擷取清單檢視控件中所有專案的周框,相對於控件的可見區域。

LVM_GETCOUNTPERPAGE訊息會傳回符合清單檢視控件一頁的項目數。 此訊息只會在清單和報表檢視中傳回有效的結果;在圖示和小型圖示檢視中,它會傳回項目總數。

若要依特定數量卷動清單檢視控件,請使用 LVM_SCROLL 訊息。 使用LVM_ENSUREVISIBLE訊息,您可以視需要卷動清單檢視控件,以確保指定的項目可見。

清單檢視標籤編輯

具有 LVS_EDITLABELS 視窗樣式的清單檢視控件,可讓使用者就地編輯專案標籤。 用戶開始編輯,方法是按兩下具有焦點的項目標籤。 或者,應用程式可以使用LVM_EDITLABEL訊息自動開始編輯。 清單檢視控件會在編輯開始時以及取消或完成時通知父視窗。 編輯完成時,父視窗會負責視需要更新專案的標籤。

標籤編輯開始時, 會建立、定位和初始化編輯控件 。 顯示之前,清單檢視控件會傳送其父視窗 LVN_BEGINLABELEDIT 通知碼。 如果您需要修改標籤編輯程式,您可以實作此通知的處理程式。

LVN_BEGINLABELEDIT通知處理程式的其中一個用途是控制使用者可以編輯的標籤。 若要防止標籤編輯,請傳回非零值。 若要自定義標籤編輯,請讓通知處理程式將LVM_GETEDITCONTROL訊息傳送至清單檢視控件,以擷取編輯控件的句柄。 擁有該句柄之後,您可以傳送一般EM_XXX訊息來自定義編輯控件。 例如,若要限制使用者可以輸入的文字數量,請傳送編輯控件 EM_LIMITTEXT 訊息。 您可以使用 SetWindowText 來變更編輯控制件的預設文字。 您甚至可以將編輯控件子類別化,以攔截和捨棄無效的字元。

當標籤編輯取消或完成時,清單檢視控件會傳送其父視窗 LVN_ENDLABELEDIT 通知碼。 lParam 參數是 NMLVDISPINFO 結構的位址 此結構的項目成員是 LVITEM 結構,其 iItem 成員會識別該專案。 如果取消編輯,則 LVITEM 結構的 pszText 成員NULL;否則,pszText 是編輯文字的位址。 如果父視窗想要保留新標籤,則父視窗會負責更新專案的標籤。

清單檢視色彩

應用程式可以擷取並設定清單檢視控件的三種色彩。

Color 用來擷取和設定色彩的訊息
文字色彩 LVM_GETTEXTCOLOR,LVM_SETTEXTCOLOR
文字背景色彩 LVM_GETTEXTBKCOLOR,LVM_SETTEXTBKCOLOR
視窗背景色彩 LVM_GETBKCOLOR,LVM_SETBKCOLOR

 

若要更明確地自定義清單檢視控件的外觀,請使用 NM_CUSTOMDRAW(清單檢視) 或使用可視化樣式(請參閱 可視化樣式啟用可視化樣式)。

依群組排列清單專案

清單檢視控件的分組功能可讓您以可視化方式將邏輯相關的專案集分組。 您可以根據專案屬性、屬性或其他特性來建立群組。 這些群組通常會在畫面上以包含群組名稱的水平標頭分隔。 下列螢幕快照顯示分組的專案。

screen shot of a list-view control, with dogs in one group and cats in another group

您可以使用 LVGROUP 結構來儲存群組的相關信息,例如頁首和頁尾文字、群組的目前狀態等等。 群組 API 包含訊息,可讓您藉由將專案新增至群組、將群組新增至檢視、排序群組專案,以及查詢專案大小和其他資訊的群組,來管理群組和群組元素。 例如,您可以使用ListView_SetGroupMetricsListView_GetGroupMetrics宏來設定和擷取每個群組顯示參數。

除了清單檢視之外,所有檢視都可以使用群組。 它不適用於具有LVS_OWNERDATA樣式的控件。

如需詳細資訊,請參閱 使用清單檢視控件

插入標記

插入標記會顯示將放置拖曳項目的使用者。 當使用者將專案拖曳到 [開始 ] 功能表或 [快速啟動] 列時,目前會顯示插入標記。 插入標記也適用於設定為 autoarrange 的清單。 當使用者將項目拖曳至另外兩個項目之間的某個點時,插入標記會顯示該項目的預期新位置。 下列螢幕快照顯示插入標記。

screen shot that shows an insertion mark when dragging one file between two others in a list-view control

插入標記 API 元素會藉由提供執行點擊偵測的訊息和旗標、依專案指定插入標記的位置和外觀,以及查詢插入標記目前大小和外觀的相關信息,來啟用插入標記的位置和外觀。

另請參閱