CListCtrl 類別
封裝「清單檢視控制項」的功能，顯示項目集合，其中每個項目是由圖示 (來自影像清單) 和標籤所組成的。
語法
class CListCtrl : public CWnd
成員
公用建構函式
| 名稱 | 描述 |
|---|---|
CListCtrl::CListCtrl |
建構 CListCtrl 物件。 |
公用方法
備註
除了圖示和標籤之外，每個專案都可以在圖示和標籤右邊的數據列中顯示資訊。 此控件（因此類別 CListCtrl ）僅適用於在 Windows 95/98 和 Windows NT 3.51 版和更新版本下執行的程式。
以下是 類別的簡短概 CListCtrl 觀。 如需詳細的概念討論，請參閱 使用 CListCtrl 和 控件。
檢視
清單檢視控件可以透過四種不同的方式顯示其內容，稱為「檢視」。
圖示檢視
每個項目都會以完整大小的圖示（32 x 32 像素）顯示，其下方有標籤。 用戶可以將專案拖曳至清單檢視視窗中的任何位置。
小型圖示檢視
每個項目都會以小圖示（16 x 16 像素）顯示，其右邊有標籤。 用戶可以將專案拖曳至清單檢視視窗中的任何位置。
清單檢視
每個項目都會以小型圖示的形式顯示，其右側有標籤。 專案會排列在數據行中，而且無法拖曳至清單檢視視窗中的任何位置。
報表檢視
每個項目都會出現在它自己的行上，並在右側的數據行中排列其他資訊。 最左邊的數據行包含小型圖示和標籤，而後續的數據行包含應用程式所指定的子專案。 內嵌標頭控件 （類別
CHeaderCtrl） 會實作這些數據行。 如需報表檢視中標題控制項和資料列的詳細資訊，請參閱 使用CListCtrl：將資料行加入控制件 （報表檢視） 。
控件目前清單檢視的樣式會決定目前的檢視。 如需這些樣式及其使用方式的詳細資訊，請參閱 使用 CListCtrl：變更清單控件樣式。
擴充樣式
除了標準清單樣式之外，類別 CListCtrl 還支援一組大型擴充樣式，以提供擴充的功能。 這項功能的一些範例包括：
暫留選取範圍
啟用時，當游標停留在專案一段時間時，允許自動選取專案。
虛擬清單檢視
啟用時，允許控件支援最多 DWORD 專案。 您可以藉由在應用程式上管理項目數據的額外負荷來達成此情況。 除了項目選取和焦點資訊之外，所有專案資訊都必須由應用程式管理。 如需詳細資訊，請參閱 使用
CListCtrl：虛擬清單控制件。單鍵和兩鍵啟用
啟用時，允許熱追蹤（自動醒目提示專案文字），以及醒目提示專案的單鍵或兩鍵啟用。
拖放數據行排序
啟用時，允許在清單檢視控件中重新排序數據行。 僅適用於報表檢視。
如需使用這些新擴充樣式的資訊，請參閱 使用 CListCtrl：變更清單控件樣式。
專案和子專案
清單檢視控件中的每個專案都包含圖示（從影像清單）、標籤、目前狀態，以及應用程式定義的值（稱為「項目數據」）。 一或多個子專案也可以與每個專案相關聯。 「子專案」是一個字串，在報表檢視中，可以顯示在項目圖示和標籤右邊的數據行中。 清單檢視控件中的所有專案都必須有相同數目的子專案。
類別 CListCtrl 提供數個函式來插入、刪除、尋找及修改這些專案。 如需詳細資訊，請參閱 CListCtrl::GetItem、 CListCtrl::InsertItem和 CListCtrl::FindItem， 將專案加入至控件，以及在 清單控件中捲動、排列、排序和尋找。
根據預設，清單檢視控件負責儲存項目的圖示和文字屬性。 不過，除了這些項目類型之外，類別 CListCtrl 還支援「回呼專案」。「回呼專案」是應用程式而非控件儲存文字、圖示或兩者的清單檢視專案。 回呼遮罩可用來指定應用程式提供的專案屬性（文字和/或圖示）。 如果應用程式使用回呼專案，則必須能夠視需要提供文字和/或圖示屬性。 當您的應用程式已經維護其中一些資訊時，回呼專案會很有説明。 如需詳細資訊，請參閱 使用 CListCtrl：回呼專案和回呼遮罩。
影像清單
清單檢視專案的圖示、標頭專案影像和應用程式定義狀態包含在數個影像清單中（由 類別 CImageList實作），您建立並指派給清單檢視控件。 每個清單檢視控制項最多可以有四種不同類型的影像清單：
大型圖示
用於完整大小的圖示檢視中。
小型圖示
用於小型圖示、清單和報表檢視中，用於圖示檢視中使用的較小圖示版本。
應用程式定義狀態
包含狀態影像，這些影像會顯示在項目圖示旁，以指出應用程式定義的狀態。
標頭項目
用於報表檢視中，用於出現在每個標頭控件專案中的小型影像。
根據預設，清單檢視控件會在終結時終結指派給它的影像清單;不過，開發人員可以藉由不再使用每個映像清單來自定義此行為，如應用程式所決定。 如需詳細資訊，請參閱 使用 CListCtrl：清單專案和影像清單。
繼承階層架構
CListCtrl
需求
標頭： afxcmn.h
CListCtrl::ApproximateViewRect
決定顯示清單檢視控件專案所需的寬度和高度。
CSize ApproximateViewRect(
CSize sz = CSize(-1, -1),
int iCount = -1) const;
參數
sz
控件的建議維度，以像素為單位。 如果未指定維度，架構會使用控件目前的寬度或高度值。
iCount
要顯示在控件中的項目數。 傳遞 -1 以使用控件中目前的項目總數。
傳回值
CSize物件，包含以像素為單位顯示專案所需的近似寬度和高度。
備註
此成員函式會實作 Win32 巨集的行為， ListView_ApproximateViewRect如 Windows SDK 中所述。
CListCtrl::Arrange
將專案重新置放在圖示檢視中，使其對齊網格線。
BOOL Arrange(UINT nCode);
參數
nCode
指定專案的對齊樣式。 它可能是下列其中一個值：
LVA_ALIGNLEFT對齊視窗左邊緣的專案。LVA_ALIGNTOP對齊視窗上邊緣的專案。LVA_DEFAULT根據清單檢視的目前對齊樣式來對齊專案（預設值）。LVA_SNAPTOGRID將所有圖示貼齊至最接近的網格線位置。
傳回值
如果成功則不為零，否則為 0。
備註
參數 nCode 會指定對齊樣式。
範例
// Align all of the list view control items along the top
// of the window (the list view control must be in icon or
// small icon mode).
m_myListCtrl.Arrange(LVA_ALIGNTOP);
CListCtrl::CancelEditLabel
取消專案文字編輯作業。
void CancelEditLabel();
備註
此成員函式會模擬訊息的功能 LVM_CANCELEDITLABEL ，如 Windows SDK 中所述。
CListCtrl::CListCtrl
建構 CListCtrl 物件。
CListCtrl();
CListCtrl::Create
建立清單控制件，並將它附加至 CListCtrl 物件。
virtual BOOL Create(
DWORD dwStyle,
const RECT& rect,
CWnd* pParentWnd,
UINT nID);
參數
dwStyle
指定清單控制件的樣式。 將清單控制件樣式的任何組合套用至 控制項。 如需這些樣式的完整清單，請參閱 Windows SDK 中的清單檢視視窗樣式 。 使用 SetExtendedStyle設定控件特有的擴充樣式。
rect
指定清單控制件的大小和位置。 它可以是 CRect 對象或 RECT 結構。
pParentWnd
指定清單控制件的父視窗，通常是 CDialog。 它不得為 NULL。
nID
指定清單控制件的識別碼。
傳回值
如果成功則不為零，否則為 0。
備註
您會在兩個步驟中建構 CListCtrl 。 首先，呼叫 建構函式，然後呼叫 Create，這會建立清單檢視控件，並將它附加至 CListCtrl 物件。
若要將擴充的 Windows 樣式套用至清單控制件物件，請呼叫 CreateEx 而不是 Create。
範例
m_myListCtrl.Create(
WS_CHILD|WS_VISIBLE|WS_BORDER|LVS_REPORT|LVS_EDITLABELS,
CRect(10,10,400,200), pParentWnd, IDD_MYLISTCTRL);
CListCtrl::CreateEx
建立控件（子視窗），並將它與 CListCtrl 對象產生關聯。
virtual BOOL CreateEx(
DWORD dwExStyle,
DWORD dwStyle,
const RECT& rect,
CWnd* pParentWnd,
UINT nID);
參數
dwExStyle
指定要建立之控件的擴充樣式。 如需擴充 Windows 樣式的清單，請參閱 Windows SDK 中的 dwExStyle 參數 CreateWindowEx 。
dwStyle
指定清單控制件的樣式。 將清單控制件樣式的任何組合套用至 控制項。 如需這些樣式的完整清單，請參閱 Windows SDK 中的清單檢視視窗樣式 。
rect
結構的參考 RECT ，描述要建立之視窗的大小和位置，在的用戶端座標中 pParentWnd。
pParentWnd
控件父系之視窗的指標。
nID
控制件的子視窗識別碼。
傳回值
如果成功則為非零；否則為 0。
備註
使用 CreateEx 而不是 Create 套用延伸的 Windows 樣式，由 Windows 擴充樣式前置詞 WS_EX_所指定。
CreateEx 使用 所 dwExStyle指定的擴充 Windows 樣式來建立 控件。 若要設定控制項特定的擴充樣式，請呼叫 SetExtendedStyle。 例如，使用 CreateEx 來設定這類樣式，例如WS_EX_CONTEXTHELP，但使用 SetExtendedStyle 來設定這類樣式，例如LVS_EX_FULLROWSELECT。 如需詳細資訊，請參閱 Windows SDK 中的擴充清單檢視樣式一文 中所述的樣式 。
CListCtrl::CreateDragImage
建立 所 nItem指定專案的拖曳影像清單。
CImageList* CreateDragImage(
int nItem,
LPPOINT lpPoint);
參數
*nItem*
要建立拖曳影像清單的專案索引。
lpPoint
POINT在檢視座標中，接收影像左上角初始位置的結構位址。
傳回值
如果成功，則為拖曳影像清單的指標;否則 NULL為 。
備註
物件 CImageList 是永久性的，而且您必須在完成時將其刪除。 例如：
CImageList* pImageList = m_myListCtrl.CreateDragImage(nItem, &point);
// do something
delete pImageList;
CListCtrl::DeleteAllItems
從清單檢視控件刪除所有專案。
BOOL DeleteAllItems();
傳回值
如果成功則不為零，否則為 0。
範例
// Delete all of the items from the list view control.
m_myListCtrl.DeleteAllItems();
ASSERT(m_myListCtrl.GetItemCount() == 0);
CListCtrl::DeleteColumn
從清單檢視控件刪除數據行。
BOOL DeleteColumn(int nCol);
參數
nCol
要刪除之數據行的索引。
傳回值
如果成功則不為零，否則為 0。
範例
int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();
// Delete all of the columns.
for (int i=0; i < nColumnCount; i++)
{
m_myListCtrl.DeleteColumn(0);
}
CListCtrl::DeleteItem
從清單檢視控件刪除專案。
BOOL DeleteItem(int nItem);
參數
nItem
指定要刪除之專案的索引。
傳回值
如果成功則不為零，否則為 0。
範例
int nCount = m_myListCtrl.GetItemCount();
// Delete all of the items from the list view control.
for (int i=0; i < nCount; i++)
{
m_myListCtrl.DeleteItem(0);
}
CListCtrl::DrawItem
當擁有者繪製清單檢視控件的視覺層面變更時，由架構呼叫。
virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);
參數
lpDrawItemStruct
結構的長指標 DRAWITEMSTRUCT ，其中包含所需繪圖類型的相關信息。
備註
結構 itemAction 的成員 DRAWITEMSTRUCT 會定義要執行的繪圖動作。
根據預設，此成員函式不會執行任何動作。 覆寫這個成員函式，以實作擁有者繪製對象的繪圖 CListCtrl 。
應用程式應該還原為此成員函式終止之前，針對 所提供 lpDrawItemStruct 顯示內容選取的所有圖形裝置介面 （GDI） 物件。
CListCtrl::EditLabel
開始就地編輯項目的文字。
CEdit* EditLabel(int nItem);
參數
nItem
要編輯的清單檢視專案索引。
傳回值
如果成功，則為用來編輯項目文字之物件的指標 CEdit ，否則 NULL為 。
備註
具有 LVS_EDITLABELS 窗口樣式的清單檢視控件可讓使用者就地編輯專案標籤。 用戶開始編輯，方法是按兩下具有焦點的項目標籤。
使用此函式開始就地編輯指定的清單檢視專案的文字。
範例
// Make sure the focus is set to the list view control.
m_myListCtrl.SetFocus();
// Show the edit control on the label of the first
// item in the list view control.
CEdit* pmyEdit = m_myListCtrl.EditLabel(1);
ASSERT(pmyEdit != NULL);
CListCtrl::EnableGroupView
啟用或停用清單檢視控件中的專案是否顯示為群組。
LRESULT EnableGroupView(BOOL fEnable);
參數
fEnable
指出是否要啟用 listview 控件來群組顯示的專案。 TRUE 啟用群組; FALSE 以停用它。
傳回值
傳回下列其中一值：
- 0 將清單檢視項目顯示為群組的功能已經啟用或停用。
- 1 控制件的狀態已成功變更。
- -1 作業失敗。
備註
此成員函式會模擬訊息的功能 LVM_ENABLEGROUPVIEW ，如 Windows SDK 中所述。
CListCtrl::EnsureVisible
確保清單檢視專案至少部分可見。
BOOL EnsureVisible(
int nItem,
BOOL bPartialOK);
參數
nItem
要顯示的清單檢視專案的索引。
bPartialOK
指定是否可接受部分可見性。
傳回值
如果成功則不為零，否則為 0。
備註
如有必要，會卷動清單檢視控件。 如果 bPartialOK 參數為非零，則專案部分可見時不會發生捲動。
範例
// Ensure that the last item is visible.
int nCount = m_myListCtrl.GetItemCount();
if (nCount > 0)
m_myListCtrl.EnsureVisible(nCount-1, FALSE);
CListCtrl::FindItem
搜尋具有指定特性的清單檢視專案。
int FindItem(
LVFINDINFO* pFindInfo,
int nStart = -1) const;
參數
pFindInfo
結構的指標 LVFINDINFO ，其中包含要搜尋之專案的相關信息。
nStart
要開始搜尋的專案索引，或從頭開始的 -1。 如果 nStart 不等於 -1，則會從搜尋中排除位於 nStart 的專案。
傳回值
如果成功，則為專案的索引，否則為 -1。
備註
參數 pFindInfo 指向 LVFINDINFO 結構，其中包含用來搜尋清單檢視項目的資訊。
範例
LVFINDINFO info;
int nIndex;
info.flags = LVFI_PARTIAL|LVFI_STRING;
info.psz = _T("item");
// Delete all of the items that begin with the string.
while ((nIndex = m_myListCtrl.FindItem(&info)) != -1)
{
m_myListCtrl.DeleteItem(nIndex);
}
CListCtrl::GetBkColor
擷取清單檢視控件的背景色彩。
COLORREF GetBkColor() const;
傳回值
用來指定 RGB 色彩的 32 位值。
範例
請參閱 CListCtrl::SetBkColor 的範例。
CListCtrl::GetBkImage
擷取清單檢視控件的目前背景影像。
BOOL GetBkImage(LVBKIMAGE* plvbkImage) const;
參數
plvbkImage
結構的指標 LVBKIMAGE ，其中包含清單檢視的目前背景影像。
傳回值
如果成功，則傳回非零，否則傳回零。
備註
此方法會實作 Win32 巨集的行為， ListView_GetBkImage如 Windows SDK 中所述。
範例
LVBKIMAGE bki;
// If no background image is set for the list view control use
// the Microsoft homepage image as the background image.
if (m_myListCtrl.GetBkImage(&bki) && (bki.ulFlags == LVBKIF_SOURCE_NONE))
{
m_myListCtrl.SetBkImage(
_T("https://www.microsoft.com/library/images/gifs/homepage/microsoft.gif"),
TRUE);
}
CListCtrl::GetCallbackMask
擷取清單檢視控件的回呼遮罩。
UINT GetCallbackMask() const;
傳回值
清單檢視控件的回呼遮罩。
備註
「回呼專案」是應用程式而非控件儲存文字、圖示或兩者的清單檢視專案。 雖然清單檢視控制項可以為您儲存這些屬性，但如果您的應用程式已經維護其中一些資訊，您可能會想要使用回呼專案。 回呼遮罩會指定應用程式維護的項目狀態位，而且會套用至整個控件，而不是套用至特定專案。 回呼遮罩預設為零，表示控制項正在追蹤所有項目的狀態。 如果應用程式使用回呼專案或指定非零回呼遮罩，則必須能夠視需要提供清單檢視項目屬性。
範例
請參閱 CListCtrl::SetCallbackMask 的範例。
CListCtrl::GetCheck
擷取與專案相關聯之狀態影像的目前顯示狀態。
BOOL GetCheck(int nItem) const;
參數
nItem
清單控制件專案的以零起始的索引。
傳回值
如果選取專案，則為非零，否則為 0。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetCheckState如 Windows SDK 中所述。
範例
請參閱 CListCtrl::SetCheck 的範例。
CListCtrl::GetColumn
擷取清單檢視控件數據行的屬性。
BOOL GetColumn(
int nCol,
LVCOLUMN* pColumn) const;
參數
nCol
要擷取其屬性的數據行索引。
pColumn
結構位址 LVCOLUMN ，指定要擷取和接收數據行相關信息的資訊。 成員 mask 指定要擷取的數據行屬性。 mask如果成員指定LVCF_TEXT值，成員pszText必須包含接收專案文字的緩衝區位址，而且cchTextMax成員必須指定緩衝區的大小。
傳回值
如果成功則不為零，否則為 0。
備註
結構 LVCOLUMN 包含報表檢視中數據行的相關信息。
範例
LVCOLUMN col;
col.mask = LVCF_WIDTH;
// Double the column width of the first column.
if (m_myListCtrl.GetColumn(0, &col))
{
col.cx *= 2;
m_myListCtrl.SetColumn(0, &col);
}
CListCtrl::GetColumnOrderArray
擷取清單檢視控件的數據行順序（由左至右）。
BOOL GetColumnOrderArray(
LPINT piArray,
int iCount = -1);
參數
piArray
緩衝區的指標，將包含清單檢視控件中數據行的索引值。 緩衝區必須夠大，才能包含清單檢視控件中的數據行總數。
iCount
清單檢視控件中的數據行數目。 如果此參數為 -1，架構會自動擷取數據行數目。
傳回值
如果成功則不為零，否則為 0。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetColumnOrderArray如 Windows SDK 中所述。
範例
// Reverse the order of the columns in the list view control
// (i.e. make the first column the last, the last column
// the first, and so on...).
CHeaderCtrl* pHeaderCtrl = m_myListCtrl.GetHeaderCtrl();
if (pHeaderCtrl != NULL)
{
int nColumnCount = pHeaderCtrl->GetItemCount();
LPINT pnOrder = (LPINT) malloc(nColumnCount*sizeof(int));
ASSERT(pnOrder != NULL);
m_myListCtrl.GetColumnOrderArray(pnOrder, nColumnCount);
int i, j, nTemp;
for (i = 0, j = nColumnCount-1; i < j; i++, j--)
{
nTemp = pnOrder[i];
pnOrder[i] = pnOrder[j];
pnOrder[j] = nTemp;
}
m_myListCtrl.SetColumnOrderArray(nColumnCount, pnOrder);
free(pnOrder);
}
CListCtrl::GetColumnWidth
擷取報表檢視或清單檢視中數據行的寬度。
int GetColumnWidth(int nCol) const;
參數
nCol
指定要擷取其寬度的數據行索引。
傳回值
所指定數據行的寬度，以像素為單位 nCol。
範例
// Increase the column width of the second column by 20.
int nWidth = m_myListCtrl.GetColumnWidth(1);
m_myListCtrl.SetColumnWidth(1, 20 + nWidth);
CListCtrl::GetCountPerPage
計算在清單檢視或報表檢視時，可以在清單檢視控件的可見區域中垂直調整的項目數目。
int GetCountPerPage() const;
傳回值
在清單檢視或報表檢視中時，可以垂直放入清單檢視控件可見區域的項目數目。
範例
請參閱 CListCtrl::GetTopIndex 的範例。
CListCtrl::GetEditControl
擷取用來編輯清單檢視專案文字的編輯控件句柄。
CEdit* GetEditControl() const;
傳回值
如果成功，則為用來編輯項目文字之物件的指標 CEdit ，否則 NULL為 。
範例
// The string replacing the text in the edit control.
LPCTSTR lpszmyString = _T("custom label!");
// If possible, replace the text in the label edit control.
CEdit* pEdit = m_myListCtrl.GetEditControl();
if (pEdit != NULL)
{
pEdit->SetWindowText(lpszmyString);
}
CListCtrl::GetEmptyText
擷取字串，以顯示目前的清單檢視控件是否為空白。
CString GetEmptyText() const;
傳回值
CString，包含控件為空白時要顯示的文字。
備註
這個方法會傳送 LVM_GETEMPTYTEXT 訊息，如 Windows SDK 中所述。
CListCtrl::GetExtendedStyle
擷取清單檢視控件目前的擴充樣式。
DWORD GetExtendedStyle();
傳回值
清單檢視控件目前使用中的擴充樣式組合。 如需這些擴充樣式的描述性清單，請參閱 Windows SDK 中的擴充清單檢視樣式 一文。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetExtendedListViewStyle如 Windows SDK 中所述。
範例
請參閱 CListCtrl::SetExtendedStyle 的範例。
CListCtrl::GetFirstSelectedItemPosition
取得清單檢視控件中第一個選取專案的位置。
POSITION GetFirstSelectedItemPosition() const;
傳回值
POSITION值，可用於反覆專案或物件指標擷取;NULL如果未選取任何專案，則為 。
範例
下列程式代碼範例示範此函式的使用方式。
POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
if (pos == NULL)
{
TRACE(_T("No items were selected!\n"));
}
else
{
while (pos)
{
int nItem = m_myListCtrl.GetNextSelectedItem(pos);
TRACE(_T("Item %d was selected!\n"), nItem);
// you could do your own processing on nItem here
}
}
CListCtrl::GetFocusedGroup
擷取目前清單檢視控件中具有鍵盤焦點的群組。
int GetFocusedGroup() const;
傳回值
如果有這樣的群組，其狀態為 LVGS_FOCUSED的群組索引，則為 ，否則為 -1。
備註
這個方法會傳送 LVM_GETFOCUSEDGROUP 訊息，如 Windows SDK 中所述。 如需詳細資訊，請參閱 LVGS_FOCUSED 結構成員LVGROUP的值state。
CListCtrl::GetGroupCount
擷取目前清單檢視控件中的群組數目。
int GetGroupCount()const;
傳回值
清單檢視控件中的群組數目。
備註
這個方法會傳送 LVM_GETGROUPCOUNT 訊息，如 Windows SDK --中所述>。
CListCtrl::GetGroupInfo
取得清單檢視控件之指定群組的資訊。
int GetGroupInfo(
int iGroupId,
PLVGROUP pgrp) const;
參數
iGroupId
要擷取其資訊的群組標識碼。
pgrp
指定 LVGROUP 之群組上包含資訊的指標。
傳回值
如果成功，則傳回群組的標識符，否則傳回 -1。
備註
此成員函式會模擬訊息的功能 LVM_GETGROUPINFO ，如 Windows SDK 中所述。
CListCtrl::GetGroupInfoByIndex
擷取目前清單檢視控件中指定群組的相關信息。
BOOL GetGroupInfoByIndex(
int iIndex,
PLVGROUP pGroup) const;
參數
iIndex
[in]以零起始的群組索引。
pGroup
[out]LVGROUP 結構的指標，這個結構會接收 iIndex 參數所指定群組的相關信息。 呼叫端負責初始化 LVGROUP 結構的成員。 將 cbSize 成員設定為 結構的大小，以及要擷取之成員的 mask 旗標。
傳回值
TRUE 如果此方法成功，則為 ;否則為 FALSE。
備註
這個方法會傳送 LVM_GETGROUPINFOBYINDEX 訊息，如 Windows SDK --中所述>。
範例
第一個程式代碼範例會定義用來存取目前清單檢視控制元件的變數 m_listCtrl。 下一個範例中會使用此變數。
public:
// Variable used to access the list control.
CListCtrl m_listCtrl;
下一個程式代碼範例示範 GetGroupInfoByIndex 方法。 在此程式代碼範例的上一節中，我們建立了清單檢視控件，在報表檢視中顯示標題為 “ClientID” 和 “Grade” 的兩個數據行。 如果這類群組存在，下列程式代碼範例會擷取其索引為 0 的群組相關信息。
// GetGroupInfoByIndex
const int GROUP_HEADER_BUFFER_SIZE = 40;
// Initialize the structure
LVGROUP gInfo = {0};
gInfo.cbSize = sizeof(LVGROUP);
wchar_t wstrHeadGet[GROUP_HEADER_BUFFER_SIZE] = {0};
gInfo.cchHeader = GROUP_HEADER_BUFFER_SIZE;
gInfo.pszHeader = wstrHeadGet;
gInfo.mask = (LVGF_ALIGN | LVGF_STATE | LVGF_HEADER | LVGF_GROUPID);
gInfo.state = LVGS_NORMAL;
gInfo.uAlign = LVGA_HEADER_LEFT;
BOOL bRet = m_listCtrl.GetGroupInfoByIndex( 0, &gInfo );
if (bRet == TRUE) {
CString strHeader = CString( gInfo.pszHeader );
CString str;
str.Format(_T("Header: '%s'"), strHeader);
AfxMessageBox(str, MB_ICONINFORMATION);
}
else
{
AfxMessageBox(_T("No group information was retrieved."));
}
CListCtrl::GetGroupMetrics
擷取群組的計量。
void GetGroupMetrics(PLVGROUPMETRICS pGroupMetrics) const;
參數
pGroupMetrics
包含群組計量資訊的指標 LVGROUPMETRICS 。
備註
此成員函式會模擬訊息的功能 LVM_GETGROUPMETRICS ，如 Windows SDK 中所述。
CListCtrl::GetGroupRect
擷取目前清單檢視控件中指定群組的周框。
BOOL GetGroupRect(
int iGroupId,
LPRECT lpRect,
int iCoords = LVGGR_GROUP) const;
參數
iGroupId
[in]指定群組。
lpRect
[in， out]結構的 RECT 指標。 如果這個方法成功，結構會接收 所 iGroupId指定群組的矩形座標。
iCoords
[in]指定要擷取的矩形座標。 使用下列其中一個值：
LVGGR_GROUP- （預設） 整個展開群組的座標。LVGGR_HEADER- 只有標頭的座標（折疊的群組）。LVGGR_SUBSETLINK- 只有子集連結的座標（標記子集）。
傳回值
TRUE 如果此方法成功，則為 ;否則為 FALSE。
備註
呼叫端負責配置 RECT 參數所 pRect 指向的結構。
這個方法會傳送 LVM_GETGROUPRECT 訊息，如 Windows SDK 中所述。
範例
第一個程式代碼範例會定義用來存取目前清單檢視控制元件的變數 m_listCtrl。 下一個範例中會使用此變數。
public:
// Variable used to access the list control.
CListCtrl m_listCtrl;
下一個程式代碼範例示範 GetGroupRect 方法。 在此程式代碼範例的上一節中，我們建立了清單檢視控件，在報表檢視中顯示標題為 “ClientID” 和 “Grade” 的兩個數據行。 如果這類群組存在，下列程式代碼範例會在索引為0的群組周圍繪製3D矩形。
// GetGroupRect
// Get the graphics rectangle that surrounds group 0.
CRect rect;
BOOL bRet = m_listCtrl.GetGroupRect( 0, &rect, LVGGR_GROUP);
// Draw a blue rectangle around group 0.
if (bRet == TRUE) {
m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(0, 0, 255), RGB(0, 0, 255));
}
else {
AfxMessageBox(_T("No group information was retrieved."), MB_ICONINFORMATION);
}
CListCtrl::GetGroupState
擷取目前清單檢視控件中指定群組的狀態。
UINT GetGroupState(
int iGroupId,
DWORD dwMask) const;
參數
iGroupId
[in]以零起始的群組索引。
dwMask
[in]遮罩，指定要擷取指定群組的狀態值。 如需詳細資訊，請參閱 mask 結構的成員 LVGROUP 。
傳回值
指定群組的要求狀態，如果找不到群組，則為 0。
備註
傳回值是 參數位dwMask AND 運算結果，以及表示目前列表檢視控件之結構成員LVGROUP的值state。
這個方法會傳送 LVM_GETGROUPSTATE 訊息，如 Windows SDK 中所述。 如需詳細資訊，請參閱 ListView_GetGroupState 巨集。
CListCtrl::GetHeaderCtrl
擷取清單檢視控件的標頭控件。
CHeaderCtrl* GetHeaderCtrl();
傳回值
清單檢視控件所使用的標頭控件指標。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetHeader如 Windows SDK 中所述。
範例
請參閱 CListCtrl::GetColumnOrderArray 的範例。
CListCtrl::GetHotCursor
擷取針對清單檢視控件啟用熱追蹤時所使用的數據指標。
HCURSOR GetHotCursor();
傳回值
清單檢視控件所使用的目前作用中數據指標資源的句柄。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetHotCursor如 Windows SDK 中所述。 當游標通過任何清單檢視專案時，只有啟用暫留選取範圍時，才會顯示作用中的游標。 藉由設定LVS_EX_TRACKSELECT擴充樣式來啟用暫留選取。
範例
// Set the hot cursor to be the system app starting cursor.
HCURSOR hCursor = ::LoadCursor(NULL, IDC_APPSTARTING);
m_myListCtrl.SetHotCursor(hCursor);
ASSERT(m_myListCtrl.GetHotCursor() == hCursor);
CListCtrl::GetHotItem
擷取目前在游標底下的清單檢視專案。
int GetHotItem();
傳回值
清單檢視控件目前作用中專案的索引。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetHotItem如 Windows SDK 中所述。 作用中專案會在啟用熱追蹤時，定義為目前選取的專案（以及暫留選取專案）。
如果啟用熱追蹤，當使用者在清單檢視項目上暫停時，系統會自動醒目提示專案標籤，而不需要使用滑鼠按鈕。
範例
// Set the hot item to the first item only if no other item is
// highlighted.
if (m_myListCtrl.GetHotItem() == -1)
m_myListCtrl.SetHotItem(0);
CListCtrl::GetHoverTime
擷取清單檢視控件目前的暫留時間。
DWORD GetHoverTime() const;
傳回值
傳回延遲，以毫秒為單位，滑鼠游標必須在選取專案之前將滑鼠游標暫留在專案上。 如果傳回值為 -1，則暫留時間是預設暫留時間。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetHoverTime如 Windows SDK 中所述。
範例
// If the hover time is the default set to 1 sec.
DWORD dwTime = m_myListCtrl.GetHoverTime();
if (dwTime == -1)
m_myListCtrl.SetHoverTime(1000);
CListCtrl::GetImageList
擷取用於繪製清單檢視專案的影像清單句柄。
CImageList* GetImageList(int nImageList) const;
參數
nImageList
值，指定要擷取的影像清單。 它可以是下列其中一個值：
LVSIL_NORMAL具有大型圖示的影像清單。LVSIL_SMALL具有小型圖示的影像清單。LVSIL_STATE具有狀態影像的映像清單。
傳回值
用於繪製清單檢視專案的影像清單指標。
範例
ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == NULL);
m_myListCtrl.SetImageList(&m_lcImageList, LVSIL_NORMAL);
ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == &m_lcImageList);
CListCtrl::GetInsertMark
擷取插入標記的目前位置。
BOOL GetInsertMark(LPLVINSERTMARK plvim) const;
參數
plvim
結構的指標 LVINSERTMARK ，其中包含插入標記的資訊。
傳回值
如果成功則傳回 TRUE，否則傳回 FALSE。 FALSE如果結構成員LVINSERTMARK中的cbSize大小不等於結構的實際大小，則會傳回 。
備註
此成員函式會模擬訊息的功能 LVM_GETINSERTMARK ，如 Windows SDK 中所述。
CListCtrl::GetInsertMarkColor
擷取插入標記的目前色彩。
COLORREF GetInsertMarkColor() const;
傳回值
傳 COLORREF 回結構，其中包含插入點的色彩。
備註
此成員函式會模擬訊息的功能 LVM_GETINSERTMARKCOLOR ，如 Windows SDK 中所述。
CListCtrl::GetInsertMarkRect
擷取系結插入點的矩形。
int GetInsertMarkRect(LPRECT pRect) const;
參數
pRect
RECT結構的指標，其中包含系結插入點之矩形的座標。
傳回值
傳回下列其中一值：
- 0 找不到插入點。
- 1 找到插入點。
備註
此成員函式會模擬訊息的功能 LVM_GETINSERTMARKRECT ，如 Windows SDK 中所述。
CListCtrl::GetItem
擷取部分或所有清單檢視項目的屬性。
BOOL GetItem(LVITEM* pItem) const;
參數
pItem
LVITEM接收項目屬性之結構的指標。
傳回值
如果成功則不為零，否則為 0。
備註
結構 LVITEM 會指定或接收清單檢視項目的屬性。
CListCtrl::GetItemCount
擷取清單檢視控件中的項目數目。
int GetItemCount() const;
傳回值
清單檢視控件中的項目數。
範例
請參閱 CListCtrl::DeleteItem 的範例。
CListCtrl::GetItemData
擷取與 所 nItem指定專案相關聯的32位應用程式特定值（如果您要編譯 x64，則為64位。
DWORD_PTR GetItemData(int nItem) const;
參數
nItem
要擷取其數據的清單專案索引。
傳回值
如果您要針對與指定專案相關聯的 x64 應用程式特定值進行編譯，則為 32 位 （64 位）。
備註
此值是 lParam 結構的成員 LVITEM ，如 Windows SDK 中所述
範例
// If any item's data is equal to zero then reset it to -1.
for (int i=0; i < m_myListCtrl.GetItemCount(); i++)
{
if (m_myListCtrl.GetItemData(i) == 0)
{
m_myListCtrl.SetItemData(i, (DWORD) -1);
}
}
CListCtrl::GetItemIndexRect
擷取目前清單檢視控件中子專案之所有或部分的周框。
BOOL GetItemIndexRect(
PLVITEMINDEX pItemIndex,
int iColumn,
int rectType,
LPRECT pRect) const;
參數
pItemIndex
[in] LVITEMINDEX 子專案的父項目結構指標。 呼叫端負責配置和設定 結構的成員 LVITEMINDEX 。 這個參數不可以是 NULL。
iColumn
[in]控件中數據行之以零起始的索引。
rectType
[in]擷取周框之清單檢視子專案的一部分。 指定下列其中一個值：
LVIR_BOUNDS- 傳回整個子專案的周框，包括圖示和標籤。LVIR_ICON- 傳回子項目的圖示或小型圖示的周框。LVIR_LABEL- 傳回子項目文字的周框。
pRect
[out] RECT 結構的指標，這個結構會接收子專案周框的相關信息。 呼叫端負責配置 RECT 結構。 這個參數不可以是 NULL。
傳回值
TRUE 如果此方法成功，則為 ;否則為 FALSE。
備註
這個方法會傳送 LVM_GETITEMINDEXRECT 訊息，如 Windows SDK 中所述。 如需詳細資訊，請參閱 ListView_GetItemIndexRect 巨集。
範例
第一個程式代碼範例會定義用來存取目前清單檢視控制元件的變數 m_listCtrl。 下一個範例中會使用此變數。
public:
// Variable used to access the list control.
CListCtrl m_listCtrl;
下一個程式代碼範例示範 GetGroupRect 方法。 在輸入此程式碼範例之前，我們建立了清單檢視控件，在報表檢視中顯示標題為 「ClientID」 和 「Grade」 的兩個數據行。 下列程式代碼範例會在這兩個數據行的第二個子項目周圍繪製 3D 矩形。
// GetItemIndexRect
// Get the rectangle that bounds the second item in the first group.
LVITEMINDEX lvItemIndex;
lvItemIndex.iGroup = 0;
lvItemIndex.iItem = 1;
CRect rect;
BOOL bRet = m_listCtrl.GetItemIndexRect(
&lvItemIndex, 0, LVIR_BOUNDS, &rect);
// Draw a red rectangle around the item.
m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(255, 0, 0), RGB(255, 0, 0) );
CListCtrl::GetItemPosition
擷取清單檢視專案的位置。
BOOL GetItemPosition(
int nItem,
LPPOINT lpPoint) const;
參數
nItem
要擷取其位置的專案索引。
lpPoint
POINT在檢視座標中，接收專案左上角位置的結構位址。
傳回值
如果成功則不為零，否則為 0。
範例
POINT pt;
// Move all items in the list control 100 pixels to the right.
UINT i, nCount = m_myListCtrl.GetItemCount();
for (i=0; i < nCount; i++)
{
m_myListCtrl.GetItemPosition(i, &pt);
pt.x += 100;
m_myListCtrl.SetItemPosition(i, pt);
}
CListCtrl::GetItemRect
擷取目前檢視中專案之所有或部分的周框。
BOOL GetItemRect(
int nItem,
LPRECT lpRect,
UINT nCode) const;
參數
nItem
要擷取其位置的專案索引。
lpRect
RECT接收周框之結構的位址。
nCode
要擷取周框的清單檢視專案部分。 它可以是下列其中一個值：
LVIR_BOUNDS傳回整個專案的周框，包括圖示和標籤。LVIR_ICON傳回圖示或小型圖示的周框。LVIR_LABEL傳回專案文字的周框。
傳回值
如果成功則不為零，否則為 0。
範例
// OnClick is the handler for the NM_CLICK notification
void CListCtrlDlg::OnClick(NMHDR* pNMHDR, LRESULT* pResult)
{
UNREFERENCED_PARAMETER(pResult);
LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
// Get the current mouse location and convert it to client
// coordinates.
CPoint pos( ::GetMessagePos() );
ScreenToClient(&pos);
// Get indexes of the first and last visible items in
// the listview control.
int index = m_myListCtrl.GetTopIndex();
int last_visible_index = index + m_myListCtrl.GetCountPerPage();
if (last_visible_index > m_myListCtrl.GetItemCount())
last_visible_index = m_myListCtrl.GetItemCount();
// Loop until number visible items has been reached.
while (index <= last_visible_index)
{
// Get the bounding rectangle of an item. If the mouse
// location is within the bounding rectangle of the item,
// you know you have found the item that was being clicked.
CRect r;
m_myListCtrl.GetItemRect(index, &r, LVIR_BOUNDS);
if (r.PtInRect(pia->ptAction))
{
UINT flag = LVIS_SELECTED | LVIS_FOCUSED;
m_myListCtrl.SetItemState(index, flag, flag);
break;
}
// Get the next item in listview control.
index++;
}
}
CListCtrl::GetItemSpacing
計算目前清單檢視控件中專案之間的間距。
BOOL GetItemSpacing(
BOOL fSmall,
int* pnHorzSpacing,
int* pnVertSpacing) const;
參數
fSmall
[in]要擷取專案間距的檢視。 指定 TRUE 小型圖示檢視或 FALSE 圖示檢視。
pnHorzSpacing
[out]包含專案之間的水準間距。
pnVertSpacing
[out]包含專案之間的垂直間距。
傳回值
TRUE 如果此方法成功，則為 ;否則為 FALSE。
備註
這個方法會傳送 LVM_GETITEMSPACING 訊息，如 Windows SDK 中所述。
CListCtrl::GetItemState
擷取清單檢視項目的狀態。
UINT GetItemState(
int nItem,
UINT nMask) const;
參數
nItem
要擷取其狀態的專案索引。
nMask
遮罩，指定要傳回的項目狀態旗標。
傳回值
指定清單檢視項目的狀態旗標。
備註
項目的狀態是由 state 結構的成員 LVITEM 所指定，如 Windows SDK 中所述。 當您指定或變更項目的狀態時， stateMask 成員會指定您要變更的狀態位。
範例
請參閱 CListCtrl::GetTopIndex 的範例。
CListCtrl::GetItemText
擷取清單檢視專案或子專案的文字。
int GetItemText(
int nItem,
int nSubItem,
LPTSTR lpszText,
int nLen) const;
CString GetItemText(
int nItem,
int nSubItem) const;
參數
nItem
要擷取其文字的專案索引。
nSubItem
指定要擷取文字的子專案。
lpszText
要接收項目文字之字串的指標。
nLen
所 lpszText指向之緩衝區的長度。
傳回值
傳 int 回的版本會傳回所擷取字串的長度。
傳 CString 回的版本會傳回項目文字。
備註
如果 nSubItem 為零，則此函式會擷取專案卷標;如果 nSubItem 為非零，則會擷取子專案的文字。 如需子專案自變數的詳細資訊，請參閱 Windows SDK 中結構的討論 LVITEM 。
CListCtrl::GetNextItem
搜尋具有指定屬性的清單檢視專案，以及具有指定專案之指定關聯性的清單檢視專案。
int GetNextItem(
int nItem,
int nFlags) const;
參數
nItem
要開始搜尋的專案索引，或 -1 尋找符合指定旗標的第一個專案。 指定的專案本身會從搜尋中排除。
nFlags
所要求專案的幾何關聯性與指定的專案，以及所要求項目的狀態。 幾何關聯可以是下列其中一個值：
LVNI_ABOVE搜尋指定專案上方的專案。LVNI_ALL依索引搜尋後續專案（預設值）。LVNI_BELOW搜尋位於指定專案下方的專案。LVNI_TOLEFT搜尋指定專案左邊的專案。LVNI_TORIGHT搜尋指定專案右邊的專案。
狀態可以是零，也可以是下列其中一或多個值：
LVNI_DROPHILITED項目已LVIS_DROPHILITED設定狀態旗標。LVNI_FOCUSED項目已LVIS_FOCUSED設定狀態旗標。LVNI_SELECTED項目已LVIS_SELECTED設定狀態旗標。
如果專案未設定所有指定的狀態旗標，搜尋會繼續進行下一個專案。
傳回值
如果成功，則為下一個專案的索引，否則為 -1。
CListCtrl::GetNextItemIndex
擷取目前清單檢視控件中具有指定屬性集的專案索引。
BOOL GetNextItemIndex(
PLVITEMINDEX pItemIndex,
int nFlags) const;
參數
pItemIndex
[in， out]LVITEMINDEX描述搜尋開始之項目的結構指標，或 -1，以尋找符合 nFlags 參數中旗標的第一個專案。 如果此方法成功，結構 LVITEMINDEX 會描述搜尋所找到的專案。
nFlags
[in]指定如何執行搜尋的旗標位組合 （OR） 。 搜尋可能取決於目標專案的索引、狀態或外觀，或目標專案相對於 參數所 pItemIndex 指定之專案的實體位置。 如需詳細資訊，請參閱 flags 訊息中的 LVM_GETNEXTITEMINDEX 參數。
傳回值
TRUE 如果此方法成功，則為 ;否則為 FALSE。
備註
呼叫端負責配置和設定 參數所指向pItemIndex之 LVITEMINDEX 結構的成員。
這個方法會傳送 LVM_GETNEXTITEMINDEX 訊息，如 Windows SDK 中所述。
CListCtrl::GetNextSelectedItem
取得 所 pos識別清單專案的索引，然後將 設定 pos 為 POSITION 值。
int GetNextSelectedItem(POSITION& pos) const;
參數
pos
先前呼叫 GetNextSelectedItem 或 GetFirstSelectedItemPosition所傳回之 POSITION 值的參考。 這個呼叫會將值更新為下一個位置。
傳回值
所 pos識別清單專案的索引。
備註
如果您使用 呼叫 GetFirstSelectedItemPosition建立初始位置，則可以GetNextSelectedItem在正向反覆運算循環中使用 。
您必須確定您的 POSITION 值有效。 如果無效，則Microsoft基礎類別庫的偵錯版本判斷提示。
範例
下列程式代碼範例示範此函式的使用方式。
POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
if (pos == NULL)
{
TRACE(_T("No items were selected!\n"));
}
else
{
while (pos)
{
int nItem = m_myListCtrl.GetNextSelectedItem(pos);
TRACE(_T("Item %d was selected!\n"), nItem);
// you could do your own processing on nItem here
}
}
CListCtrl::GetNumberOfWorkAreas
擷取清單檢視控件目前的工作區域數目。
UINT GetNumberOfWorkAreas() const;
傳回值
目前未使用。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetNumberOfWorkAreas如 Windows SDK 中所述。
範例
UINT i, uCount = m_myListCtrl.GetNumberOfWorkAreas();
LPRECT lpRects = (LPRECT) malloc(uCount*sizeof(RECT));
if (lpRects != NULL)
{
// Dump all of the work area dimensions.
m_myListCtrl.GetWorkAreas(uCount, lpRects);
for (i=0; i < uCount; i++)
{
TRACE(_T("Work area %d; left = %d, top = %d, right = %d, ")
_T("bottom = %d\r\n"),
i, lpRects[i].left, lpRects[i].top, lpRects[i].right,
lpRects[i].bottom);
}
free(lpRects);
}
else
{
TRACE(_T("Couldn't allocate enough memory!"));
}
CListCtrl::GetOutlineColor
擷取清單檢視控件框線的色彩。
COLORREF GetOutlineColor() const;
傳回值
傳 COLORREF 回包含外框色彩的結構。
備註
此成員函式會模擬訊息的功能 LVM_GETOUTLINECOLOR ，如 Windows SDK 中所述。
CListCtrl::GetOrigin
擷取清單檢視控件的目前檢視原點。
BOOL GetOrigin(LPPOINT lpPoint) const;
參數
lpPoint
POINT接收檢視來源之結構的位址。
傳回值
如果成功則不為零，否則為 0。 不過，如果控件在報表檢視中，傳回值一律為零。
CListCtrl::GetSelectedColumn
擷取清單控制項中目前選取之數據行的索引。
UINT GetSelectedColumn() const;
傳回值
選取資料行的索引。
備註
此成員函式會模擬訊息的功能 LVM_GETSELECTEDCOLUMN ，如 Windows SDK 中所述。
CListCtrl::GetSelectedCount
擷取清單檢視控件中選取的項目數目。
UINT GetSelectedCount() const;
傳回值
清單檢視控件中選取的項目數目。
範例
UINT i, uSelectedCount = m_myListCtrl.GetSelectedCount();
int nItem = -1;
// Update all of the selected items.
if (uSelectedCount > 0)
{
for (i=0; i < uSelectedCount; i++)
{
nItem = m_myListCtrl.GetNextItem(nItem, LVNI_SELECTED);
ASSERT(nItem != -1);
m_myListCtrl.Update(nItem);
}
}
CListCtrl::GetSelectionMark
擷取清單檢視控件的選取標記。
int GetSelectionMark();
傳回值
以零起始的選取標記，如果沒有選取標記，則為 -1。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetSelectionMark如 Windows SDK 中所述。
範例
// Set the selection mark to the first item only if no other item is
// selected.
if (m_myListCtrl.GetSelectionMark() == -1)
m_myListCtrl.SetSelectionMark(0);
CListCtrl::GetStringWidth
決定顯示所有指定字串所需的最小數據行寬度。
int GetStringWidth(LPCTSTR lpsz) const;
參數
lpsz
要決定寬度的 Null 終止字串位址。
傳回值
所指向字串的寬度，以像素為單位 lpsz。
備註
傳回的寬度會考慮控件目前的字型和數據行邊界，但不會考慮小圖標的寬度。
範例
CString strColumn;
int nWidth;
// Insert six columns in the list view control. Make the width of
// the column be the width of the column header plus 50%.
for (int i = 0; i < 6; i++)
{
strColumn.Format(_T("column %d"), i);
nWidth = 3*m_myListCtrl.GetStringWidth(strColumn)/2;
m_myListCtrl.InsertColumn(i, strColumn, LVCFMT_LEFT, nWidth);
}
CListCtrl::GetSubItemRect
擷取清單檢視控件中專案的周框。
BOOL GetSubItemRect(
int iItem,
int iSubItem,
int nArea,
CRect& ref);
參數
iItem
子專案的父專案索引。
iSubItem
子專案的單一式索引。
nArea
決定要擷取之周框的部分（清單檢視子專案）。 周框的部分（圖示、標籤或兩者）是藉由將位 OR 運算子套用至下列一或多個值來指定：
LVIR_BOUNDS傳回整個專案的周框，包括圖示和標籤。LVIR_ICON傳回圖示或小型圖示的周框。LVIR_LABEL傳回整個專案的周框，包括圖示和標籤。 這與LVIR_BOUNDS相同。
ref
對象參考 CRect ，其中包含子專案的周框座標。
傳回值
如果成功則不為零，否則為 0。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetSubItemRect如 Windows SDK 中所述。
CListCtrl::GetTextBkColor
擷取清單檢視控件的文字背景色彩。
COLORREF GetTextBkColor() const;
傳回值
用來指定 RGB 色彩的 32 位值。
範例
請參閱 CListCtrl::SetTextBkColor 的範例。
CListCtrl::GetTextColor
擷取清單檢視控件的文字色彩。
COLORREF GetTextColor() const;
傳回值
用來指定 RGB 色彩的 32 位值。
範例
請參閱 CListCtrl::SetTextColor 的範例。
CListCtrl::GetTileInfo
擷取清單檢視控件中磚的相關信息。
BOOL GetTileInfo(PLVTILEINFO plvti) const;
參數
plvti
接收磚資訊之結構的指標 LVTILEINFO 。
傳回值
不會使用傳回值。
備註
此成員函式會模擬訊息的功能 LVM_GETTILEINFO ，如 Windows SDK 中所述。
CListCtrl::GetTileViewInfo
擷取磚檢視中清單檢視控件的相關信息。
BOOL GetTileViewInfo(PLVTILEVIEWINFO ptvi) const;
參數
ptvi
接收所擷取資訊之 結構的指標 LVTILEVIEWINFO 。
傳回值
不會使用傳回值。
備註
此成員函式會模擬訊息的功能 LVM_GETTILEVIEWINFO ，如 Windows SDK 中所述。
CListCtrl::GetToolTips
擷取清單檢視控制項用來顯示工具提示的工具提示控制項。
CToolTipCtrl* GetToolTips() const;
傳回值
清單控制件所要使用的物件指標 CToolTipCtrl 。 Create如果成員函式使用 樣式LVS_NOTOOLTIPS，則不會使用任何工具提示，而且會傳回NULL。
備註
此成員函式會實作 Win32 訊息 LVM_GETTOOLTIPS 的行為，如 Windows SDK 中所述。 的 GetToolTips MFC 實作會 CToolTipCtrl 傳回物件，此物件由清單控制項使用，而不是工具提示控件的句柄。
範例
CToolTipCtrl* pTip = m_myListCtrl.GetToolTips();
if (NULL != pTip)
{
pTip->UpdateTipText(_T("I'm a list view!"), &m_myListCtrl,
IDD_MYLISTCTRL);
}
CListCtrl::GetTopIndex
在清單檢視或報表檢視中，擷取最上層可見專案的索引。
int GetTopIndex() const;
傳回值
最上層可見專案的索引。
範例
// Make sure the focus is set to the list view control.
m_myListCtrl.SetFocus();
// Select all of the items that are completely visible.
int n = m_myListCtrl.GetTopIndex();
int nLast = n + m_myListCtrl.GetCountPerPage();
for (; n < nLast; n++)
{
m_myListCtrl.SetItemState(n, LVIS_SELECTED, LVIS_SELECTED);
ASSERT(m_myListCtrl.GetItemState(n, LVIS_SELECTED) == LVIS_SELECTED);
}
CListCtrl::GetView
取得清單檢視控件的檢視。
DWORD GetView() const;
傳回值
清單檢視控件的目前檢視。
備註
此成員函式會模擬訊息的功能 LVM_GETVIEW ，如 Windows SDK 中所述。
CListCtrl::GetViewRect
擷取清單檢視控件中所有專案的周框。
BOOL GetViewRect(LPRECT lpRect) const;
參數
lpRect
結構的 RECT 位址。
傳回值
如果成功則不為零，否則為 0。
備註
清單檢視必須位於圖示檢視或小型圖示檢視中。
CListCtrl::GetWorkAreas
擷取清單檢視控件的目前工作區域。
void GetWorkAreas(
int nWorkAreas,
LPRECT pRect) const;
參數
nWorkAreas
陣列中包含的pRect結構數目RECT。
pRect
接收清單檢視控件工作區域之結構數位的指標 RECT 。 CRect 。 這些結構中的值位於用戶端座標中。
備註
此成員函式會實作 Win32 巨集的行為， ListView_GetWorkAreas如 Windows SDK 中所述。
範例
請參閱 CListCtrl::GetNumberOfWorkAreas 的範例。
CListCtrl::HasGroup
判斷清單檢視控件是否具有指定的群組。
BOOL HasGroup(int iGroupId) const;
參數
iGroupId
所要求群組的標識碼。
傳回值
成功時傳回 TRUE，失敗時則傳回 FALSE。
備註
此成員函式會模擬訊息的功能 LVM_HASGROUP ，如 Windows SDK 中所述。
CListCtrl::HitTest
判斷哪個清單檢視專案，如果有的話，位於指定的位置。
int HitTest(LVHITTESTINFO* pHitTestInfo) const;
int HitTest(
CPoint pt,
UINT* pFlags = NULL) const;
參數
pHitTestInfo
LVHITTESTINFO結構位址，其中包含點擊測試的位置，以及接收點擊測試結果的相關信息。
pt
要測試的點。
pFlags
接收測試結果相關信息的整數指標。 請參閱 Windows SDK 中 結構成員LVHITTESTINFO的說明flags。
傳回值
如果為 ，則為 所指定 pHitTestInfo位置的專案索引，否則為 -1。
備註
您可以使用 LVHT_ABOVE結構成員的 flag 、 LVHT_BELOW、 LVHT_TOLEFT和 LVHT_TORIGHT 值來判斷是否捲動清單檢視控件的內容。 其中兩個旗標可以合併，例如，如果位置在工作區的上方和左邊。
您可以測試 LVHT_ONITEM 結構 flag 成員的值，以判斷指定的位置是否超過清單檢視專案。 這個值是 結構成員的 LVHT_ONITEMICON、 LVHT_ONITEMLABEL和 LVHT_ONITEMSTATEICON 值 flag 上的位 OR 運算。
範例
void CListCtrlDlg::OnRClick(NMHDR* pNMHDR, LRESULT* pResult)
{
LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
CPoint point(pia->ptAction);
// Select the item the user clicked on.
UINT uFlags;
int nItem = m_myListCtrl.HitTest(point, &uFlags);
if (uFlags & LVHT_ONITEMLABEL)
{
m_myListCtrl.SetItem(nItem, 0, LVIF_STATE, NULL, 0, LVIS_SELECTED,
LVIS_SELECTED, 0);
}
*pResult = 0;
}
CListCtrl::InsertColumn
在清單檢視控件中插入新的數據行。
int InsertColumn(
int nCol,
const LVCOLUMN* pColumn);
int InsertColumn(
int nCol,
LPCTSTR lpszColumnHeading,
int nFormat = LVCFMT_LEFT,
int nWidth = -1,
int nSubItem = -1);
參數
nCol
新數據行的索引。
pColumn
LVCOLUMN結構位址，其中包含新數據行的屬性。
lpszColumnHeading
包含數據列標題的字串位址。
nFormat
指定數據行對齊方式的整數。 它可以是下列其中一個值： LVCFMT_LEFT、 LVCFMT_RIGHT或 LVCFMT_CENTER。
nWidth
數據行的寬度，以像素為單位。 如果此參數是 -1，則不會設定數據行寬度。
nSubItem
與數據行相關聯的子專案的索引。 如果這個參數是 -1，則沒有任何子項目與數據行相關聯。
傳回值
如果成功，則為新數據行的索引，否則為 -1。
備註
清單檢視控件中最左邊的數據行必須靠左對齊。
結構 LVCOLUMN 包含報表檢視中數據行的屬性。 它也可用來接收數據行的相關信息。 此結構會在 Windows SDK 中描述。
CListCtrl::InsertGroup
將群組插入清單檢視控制件。
LRESULT InsertGroup(
int index,
PLVGROUP pgrp);
參數
index
要插入群組之專案的索引。
pgrp
結構的指標 LVGROUP ，其中包含要加入的群組。
傳回值
傳回群組新增至的專案索引，如果作業失敗，則傳回 -1。
備註
此成員函式會模擬訊息的功能 LVM_INSERTGROUP ，如 Windows SDK 中所述。
CListCtrl::InsertGroupSorted
將指定的群組插入已排序的群組清單中。
LRESULT InsertGroupSorted(PLVINSERTGROUPSORTED pStructInsert);
參數
pStructInsert
結構的指標 LVINSERTGROUPSORTED ，其中包含要插入的群組。
傳回值
不會使用傳回值。
備註
此成員函式會模擬訊息的功能 LVM_INSERTGROUPSORTED ，如 Windows SDK 中所述。
CListCtrl::InsertItem
將專案插入清單檢視控制件。
int InsertItem(const LVITEM* pItem);
int InsertItem(
int nItem,
LPCTSTR lpszItem);
int InsertItem(
int nItem,
LPCTSTR lpszItem,
int nImage);
int InsertItem(
UINT nMask,
int nItem,
LPCTSTR lpszItem,
UINT nState,
UINT nStateMask,
int nImage,
LPARAM lParam);
參數
pItem
指定項目屬性的 LVITEM 結構的指標，如 Windows SDK 中所述。
nItem
要插入之專案的索引。
lpszItem
包含項目標籤的字串位址，如果 LPSTR_TEXTCALLBACK 專案是回呼專案，則為 。 如需回呼項目的資訊，請參閱 CListCtrl::GetCallbackMask。
nImage
專案的影像索引，如果 I_IMAGECALLBACK 專案是回呼專案，則為 。 如需回呼項目的資訊，請參閱 CListCtrl::GetCallbackMask。
nMask
參數 nMask 會指定傳遞為參數的項目屬性有效。 它可以是 Windows SDK 中結構中所述LVITEM的一或多個遮罩值。 有效值可以與位 OR 運算子結合。
nState
指出專案的狀態、狀態影像和重疊影像。 如需詳細資訊，請參閱 Windows SDK 主題 LVITEM 結構 與 列表檢視項目狀態 ，以取得有效旗標的清單。
nStateMask
指出要擷取或修改狀態成員的位。 如需詳細資訊，請參閱 LVITEM Windows SDK 中的結構 。
lParam
與專案相關聯的 32 位應用程式特定值 （如果您要編譯 x64，則為 64 位。 如果指定此參數，您必須設定 nMask 屬性 LVIF_PARAM。
傳回值
如果成功或 -1，則為新專案的索引。
備註
呼叫這個方法可能會導致 LVM_INSERTITEM 訊息傳送至控件視窗。 控件的相關訊息處理程式可能無法在特定條件下設定專案文字（例如使用視窗樣式，例如 LVS_OWNERDRAW）。 如需這些條件的詳細資訊，請參閱 LVM_INSERTITEM Windows SDK。
範例
CString strText;
int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();
// Insert 10 items in the list view control.
for (int i = 0; i < 10; i++)
{
strText.Format(TEXT("item %d"), i);
// Insert the item, select every other item.
m_myListCtrl.InsertItem(LVIF_TEXT | LVIF_STATE, i, strText,
(i % 2) == 0 ? LVIS_SELECTED : 0, LVIS_SELECTED, 0, 0);
// Initialize the text of the subitems.
for (int j = 1; j < nColumnCount; j++)
{
strText.Format(TEXT("sub-item %d %d"), i, j);
m_myListCtrl.SetItemText(i, j, strText);
}
}
CListCtrl::InsertMarkHitTest
擷取最接近指定點的插入點。
int InsertMarkHitTest(
LPPOINT pPoint,
LPLVINSERTMARK plvim) const;
參數
pPoint
結構指標 POINT ，包含點擊測試座標，相對於清單控件的工作區。
plvim
結構的指標 LVINSERTMARK ，指定最接近point 參數所定義座標的插入點。
傳回值
最接近指定點的插入點。
備註
此成員函式會模擬訊息的功能 LVM_INSERTMARKHITTEST ，如 Windows SDK 中所述。
CListCtrl::IsGroupViewEnabled
判斷是否為清單檢視控件啟用群組檢視。
BOOL IsGroupViewEnabled() const;
傳回值
TRUE如果已開啟群組檢視，則FALSE傳回 ，否則傳回 。
備註
此成員函式會模擬訊息的功能 LVM_ISGROUPVIEWENABLED ，如 Windows SDK 中所述。
CListCtrl::IsItemVisible
指出目前清單檢視控件中的指定專案是否可見。
BOOL IsItemVisible(int index) const;
參數
index
[in]目前清單檢視控件中專案以零起始的索引。
傳回值
TRUE 如果可見指定的專案，則為 ;否則為 FALSE。
備註
這個方法會傳送 LVM_ISITEMVISIBLE 訊息，如 Windows SDK 中所述。
CListCtrl::MapIDToIndex
將目前清單檢視控件中專案的唯一標識碼對應至索引。
UINT MapIDToIndex(UINT id) const;
參數
id
[in]專案的唯一標識碼。
傳回值
指定之標識碼的目前索引。
備註
清單檢視控件會在內部依索引追蹤專案。 這可能會產生問題，因為索引在控件的存留期內可能會變更。 清單檢視控件可以在建立專案時標記具有標識符的專案，而且您可以使用此標識符來保證清單檢視控件存留期間的唯一性。
在多線程環境中，索引只會在裝載清單檢視控件的線程上保證，而不是在背景線程上。
這個方法會傳送 LVM_MAPIDTOINDEX 訊息，如 Windows SDK 中所述。
CListCtrl::MapIndexToID
將目前清單檢視控件中專案的索引對應至唯一標識碼。
UINT MapIndexToID(UINT index) const;
參數
index
[in]專案之以零起始的索引。
傳回值
指定專案的唯一識別碼。
備註
清單檢視控件會在內部依索引追蹤專案。 這可能會產生問題，因為索引在控件的存留期內可能會變更。 清單檢視控件可以在建立專案時標記標識碼的專案。 您可以使用此識別碼來存取清單檢視控制項存留期的特定專案。
在多線程環境中，索引只會在裝載清單檢視控件的線程上保證，而不是在背景線程上。
這個方法會傳送 LVM_MAPINDEXTOID 訊息，如 Windows SDK 中所述。
範例
第一個程式代碼範例會定義用來存取目前清單檢視控制元件的變數 m_listCtrl。 下一個範例中會使用此變數。
public:
// Variable used to access the list control.
CListCtrl m_listCtrl;
下一個程式代碼範例示範 MapIndexToID 方法。 在此程式代碼範例的上一節中，我們建立了清單檢視控件，在報表檢視中顯示標題為 “ClientID” 和 “Grade” 的兩個數據行。 下列範例會將每個清單檢視專案的索引對應至標識符，然後擷取每個標識碼的索引。 最後，此範例會報告是否已擷取原始索引。
// MapIndexToID
int iCount = m_listCtrl.GetItemCount();
UINT nId = 0;
UINT nIndex = 0;
for (int iIndexOriginal = 0; iIndexOriginal < iCount; iIndexOriginal++)
{
// Map index to ID.
nId = m_listCtrl.MapIndexToID((UINT)iIndexOriginal);
// Map ID to index.
nIndex = m_listCtrl.MapIDToIndex(nId);
if (nIndex != (UINT)(iIndexOriginal))
{
CString str;
str.Format(_T("Mapped index (%d) is not equal to original index (%d)"),
nIndex, (UINT)(iIndexOriginal));
AfxMessageBox(str);
return;
}
}
AfxMessageBox(_T("The mapped indexes and original indexes are equal."),
MB_ICONINFORMATION);
CListCtrl::MoveGroup
將指定的群組移至清單檢視控件的指定以零起始的索引。
LRESULT MoveGroup(
int iGroupId,
int toIndex);
參數
iGroupId
要移動之群組的標識碼。
toIndex
要移動群組之以零起始的索引。
傳回值
不會使用傳回值。
備註
此成員函式會模擬訊息的功能 LVM_MOVEGROUP ，如 Windows SDK 中所述。
CListCtrl::MoveItemToGroup
將指定的項目移至指定的群組。
void MoveItemToGroup(
int idItemFrom,
int idGroupTo);
參數
idItemFrom
[in]要移動之專案的索引。
idGroupTo
[in]專案將移至之群組的標識碼。
備註
注意
這個方法目前尚未實作。
此方法會模擬訊息的功能 LVM_MOVEITEMTOGROUP ，如 Windows SDK 中所述。
CListCtrl::RedrawItems
強制清單檢視控件重新繪出一系列專案。
BOOL RedrawItems(
int nFirst,
int nLast);
參數
nFirst
要重新繪製之第一個專案的索引。
nLast
要重新繪製之最後一個專案的索引。
傳回值
如果成功則不為零，否則為 0。
備註
除非清單檢視視窗收到WM_PAINT訊息，否則不會重新繪製指定的專案。 若要立即重繪，請在使用此函式之後呼叫 Windows UpdateWindow 函式。
CListCtrl::RemoveAllGroups
從清單檢視控件移除所有群組。
void RemoveAllGroups();
備註
此成員函式會模擬訊息的功能 LVM_REMOVEALLGROUPS ，如 Windows SDK 中所述。
CListCtrl::RemoveGroup
從清單檢視控件中移除指定的群組。
LRESULT RemoveGroup(int iGroupId);
參數
iGroupId
要移除之群組的標識碼。
傳回值
如果成功，則傳回群組的索引，否則傳回 -1。
備註
此成員函式會模擬訊息的功能 LVM_REMOVEGROUP ，如 Windows SDK 中所述。
CListCtrl::Scroll
卷動清單檢視控件的內容。
BOOL Scroll(CSize size);
參數
size
CSize物件，指定水準和垂直捲動的數量，以像素為單位。 y大小的成員會除以像素為單位的清單檢視控件行的高度，而控件則依產生的行數卷動。
傳回值
如果成功則不為零，否則為 0。
CListCtrl::SetBkColor
設定清單檢視控件的背景色彩。
BOOL SetBkColor(COLORREF cr);
參數
cr
要設定的背景色彩，或 CLR_NONE 沒有背景色彩的值。 具有背景色彩的清單檢視控件會比沒有背景色彩的清單檢視控件更快速。 如需詳細資訊，請參閱 COLORREF Windows SDK 中的 。
傳回值
如果成功則不為零，否則為 0。
範例
// Use the 3D button face color for the background.
COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
m_myListCtrl.SetBkColor(crBkColor);
ASSERT(m_myListCtrl.GetBkColor() == crBkColor);
CListCtrl::SetBkImage
設定清單檢視控件的背景影像。
BOOL SetBkImage(LVBKIMAGE* plvbkImage);
BOOL SetBkImage(
HBITMAP hBitmap,
BOOL fTile = TRUE,
int xOffsetPercent = 0,
int yOffsetPercent = 0);
BOOL SetBkImage(
LPTSTR pszUrl,
BOOL fTile = TRUE,
int xOffsetPercent = 0,
int yOffsetPercent = 0);
參數
plvbkImage
LVBKIMAGE結構的位址，包含新的背景影像資訊。
hBitmap
點陣圖的句柄。
pszUrl
NULL包含背景影像 URL 的終止字串。
fTile
如果要在清單檢視控件的背景中並排影像，則為非零;否則為 0。
xOffsetPercent
影像左邊緣的位移，以像素為單位，從清單檢視控件的原點。
yOffsetPercent
影像上邊緣的位移，以像素為單位，來自清單檢視控件的來源。
傳回值
如果成功，則傳回非零，否則傳回零。
備註
注意
由於 CListCtrl::SetBkImage 使用 OLE COM 功能，因此必須先初始化 OLE 連結庫，才能使用 SetBkImage。 最好在應用程式初始化時初始化 COM 連結庫，並在應用程式終止時取消初始化連結庫。 這會自動在 MFC 應用程式中完成，這些應用程式會使用 ActiveX 技術、OLE 自動化、OLE Linking/Embedding 或 ODBC/DAO 作業。
範例
請參閱 CListCtrl::GetBkImage 的範例。
CListCtrl::SetCallbackMask
設定清單檢視控件的回呼遮罩。
BOOL SetCallbackMask(UINT nMask);
參數
nMask
回呼遮罩的新值。
傳回值
如果成功則不為零，否則為 0。
範例
// Set the callback mask so that only the selected and focused states
// are stored for each item.
m_myListCtrl.SetCallbackMask(LVIS_SELECTED|LVIS_FOCUSED);
ASSERT(m_myListCtrl.GetCallbackMask() ==
(LVIS_SELECTED|LVIS_FOCUSED));
CListCtrl::SetCheck
判斷清單控制項項目的狀態影像是否可見。
BOOL SetCheck(
int nItem,
BOOL fCheck = TRUE);
參數
nItem
清單控制件專案的以零起始的索引。
fCheck
指定項目的狀態影像是否應該可見。 默認為 TRUE ，fCheck且狀態影像為可見。 如果 fCheck 為 FALSE，則看不到。
傳回值
如果已核取專案，則為非零，否則為 0。
範例
int nCount = m_myListCtrl.GetItemCount();
BOOL fCheck = FALSE;
// Set the check state of every other item to TRUE and
// all others to FALSE.
for (int i = 0; i < nCount; i++)
{
m_myListCtrl.SetCheck(i, fCheck);
ASSERT((m_myListCtrl.GetCheck(i) && fCheck) ||
(!m_myListCtrl.GetCheck(i) && !fCheck));
fCheck = !fCheck;
}
CListCtrl::SetColumn
設定清單檢視資料行的屬性。
BOOL SetColumn(
int nCol,
const LVCOLUMN* pColumn);
參數
nCol
要設定其屬性的數據行索引。
pColumn
LVCOLUMN包含新數據行屬性的結構位址，如 Windows SDK 中所述。 結構 mask 的成員會指定要設定的數據行屬性。 mask如果成員指定LVCF_TEXT值，則結構pszText的成員是 Null 終止字串的位址，而且會忽略結構cchTextMax的成員。
傳回值
如果成功則不為零，否則為 0。
範例
請參閱 CListCtrl::GetColumn 的範例。
CListCtrl::SetColumnOrderArray
設定清單檢視控件的數據行順序（由左至右）。
BOOL SetColumnOrderArray(
int iCount,
LPINT piArray);
參數
piArray
緩衝區的指標，其中包含清單檢視控件中數據行的索引值（從左至右）。 緩衝區必須夠大，才能包含清單檢視控件中的數據行總數。
iCount
清單檢視控件中的數據行數目。
傳回值
如果成功則不為零，否則為 0。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetColumnOrderArray如 Windows SDK 中所述。
範例
請參閱 CListCtrl::GetColumnOrderArray 的範例。
CListCtrl::SetColumnWidth
變更報表檢視或清單檢視中數據行的寬度。
BOOL SetColumnWidth(
int nCol,
int cx);
參數
nCol
要設定寬度的數據行索引。 在清單檢視中，此參數必須是 0。
cx
數據行的新寬度。 可以是 LVSCW_AUTOSIZE 或 LVSCW_AUTOSIZE_USEHEADER，如 Windows SDK 中所述 LVM_SETCOLUMNWIDTH 。
傳回值
如果成功則不為零，否則為 0。
CListCtrl::SetExtendedStyle
設定清單檢視控件的目前擴充樣式。
DWORD SetExtendedStyle(DWORD dwNewStyle);
參數
dwNewStyle
清單檢視控件要使用的擴充樣式組合。 如需這些樣式的描述性清單，請參閱 Windows SDK 中的擴充清單檢視樣式 主題。
傳回值
清單檢視控件所使用的先前擴充樣式組合。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetExtendedListViewStyle如 Windows SDK 中所述。
範例
// Allow the header controls item to be movable by the user.
m_myListCtrl.SetExtendedStyle
(m_myListCtrl.GetExtendedStyle()|LVS_EX_HEADERDRAGDROP);
CListCtrl::SetGroupInfo
設定描述目前清單檢視控件之指定群組的資訊。
int SetGroupInfo(
int iGroupId,
PLVGROUP pgrp);
參數
iGroupId
設定資訊之群組的標識碼。
pgrp
LVGROUP結構指標，其中包含要設定的資訊。 呼叫端負責配置此結構並設定其成員。
傳回值
如果方法成功，則為群組的標識符;否則為 -1。
備註
這個方法會傳送 LVM_SETGROUPINFO 訊息，如 Windows SDK 中所述。
CListCtrl::SetGroupMetrics
設定清單檢視控件的群組計量。
void SetGroupMetrics(PLVGROUPMETRICS pGroupMetrics);
參數
pGroupMetrics
結構的指標 LVGROUPMETRICS ，其中包含要設定的群組計量資訊。
備註
此成員函式會模擬訊息的功能 LVM_SETGROUPMETRICS ，如 Windows SDK 中所述。
CListCtrl::SetHotCursor
設定針對清單檢視控件啟用熱追蹤時所使用的數據指標。
HCURSOR SetHotCursor(HCURSOR hc);
參數
hc
數據指標資源的句柄，用來表示作用中數據指標。
傳回值
清單檢視控件所使用的上一個經常性數據指標資源的句柄。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetHotCursor如 Windows SDK 中所述。
作用中數據指標只有在啟用暫留選取時才會顯示，當游標通過任何清單檢視專案時才會顯示。 藉由設定 LVS_EX_TRACKSELECT 擴充樣式來啟用暫留選取。
範例
請參閱 CListCtrl::GetHotCursor 的範例。
CListCtrl::SetHotItem
設定清單檢視控件的目前作用中專案。
int SetHotItem(int iIndex);
參數
iIndex
要設定為作用中專案之專案的以零起始的索引。
傳回值
先前作用中專案之以零起始的索引。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetHotItem如 Windows SDK 中所述。
範例
請參閱 CListCtrl::GetHotItem 的範例。
CListCtrl::SetHoverTime
設定清單檢視控件目前的暫留時間。
DWORD SetHoverTime(DWORD dwHoverTime = (DWORD)-1);
參數
dwHoverTime
新的延遲，以毫秒為單位，滑鼠游標必須在選取專案之前將滑鼠游標暫留在專案上。 如果傳遞預設值，時間會設定為預設暫留時間。
傳回值
先前的暫留時間，以毫秒為單位。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetHoverTime如 Windows SDK 中所述。
範例
請參閱 CListCtrl::GetHoverTime 的範例。
CListCtrl::SetIconSpacing
設定清單檢視控件中圖示之間的間距。
CSize SetIconSpacing(
int cx,
int cy);
CSize SetIconSpacing(CSize size);
參數
cx
X 軸上圖示之間的距離（以像素為單位）。
cy
Y 軸上圖示之間的距離（以像素為單位）。
size
CSize物件，指定 x 軸和 y 軸上圖示之間的距離（以像素為單位）。
傳回值
CSize物件，包含先前圖示間距的值。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetIconSpacing如 Windows SDK 中所述。
範例
// Leave lots of space between icons.
m_myListCtrl.SetIconSpacing(CSize(100, 100));
CListCtrl::SetImageList
將影像清單指派給清單檢視控件。
CImageList* SetImageList(
CImageList* pImageList,
int nImageListType);
參數
pImageList
要指派之影像清單的指標。
nImageListType
影像清單的類型。 它可以是下列其中一個值：
LVSIL_NORMAL具有大型圖示的影像清單。LVSIL_SMALL具有小型圖示的影像清單。LVSIL_STATE具有狀態影像的映像清單。
傳回值
上一個影像清單的指標。
範例
請參閱 CListCtrl::GetImageList 的範例。
CListCtrl::SetInfoTip
設定工具提示文字。
BOOL SetInfoTip(PLVSETINFOTIP plvInfoTip);
參數
plvInfoTip
結構的指標 LVFSETINFOTIP ，其中包含要設定的資訊。
傳回值
成功時傳回 TRUE，失敗時則傳回 FALSE。
備註
此成員函式會模擬訊息的功能 LVM_SETINFOTIP ，如 Windows SDK 中所述。
CListCtrl::SetInsertMark
將插入點設定為定義的位置。
BOOL SetInsertMark(LPLVINSERTMARK plvim);
參數
plvim
結構的指標 LVINSERTMARK ，指定要設定插入點的位置。
傳回值
如果成功則傳回 TRUE，否則傳回 FALSE。 FALSE如果結構成員LVINSERTMARK中的cbSize大小不等於結構的實際大小，或插入點未套用在目前檢視中，則會傳回 。
備註
此成員函式會模擬訊息的功能 LVM_SETINSERTMARK ，如 Windows SDK 中所述。
CListCtrl::SetInsertMarkColor
設定插入點的色彩。
COLORREF SetInsertMarkColor(COLORREF color);
參數
color
COLORREF結構，指定要設定插入點的色彩。
傳回值
傳回包含上一個 COLORREF 色彩的結構。
備註
此成員函式會模擬訊息的功能 LVM_SETINSERTMARKCOLOR ，如 Windows SDK 中所述。
CListCtrl::SetItem
設定部分或所有清單檢視項目的屬性。
BOOL SetItem(const LVITEM* pItem);
BOOL SetItem(
int nItem,
int nSubItem,
UINT nMask,
LPCTSTR lpszItem,
int nImage,
UINT nState,
UINT nStateMask,
LPARAM lParam);
BOOL SetItem(
int nItem,
int nSubItem,
UINT nMask,
LPCTSTR lpszItem,
int nImage,
UINT nState,
UINT nStateMask,
LPARAM lParam,
int nIndent);
參數
pItem
LVITEM包含新專案屬性的結構位址，如 Windows SDK 中所述。 結構的 iItem 和 iSubItem 成員會識別專案或子專案，而結構 mask 的成員會指定要設定的屬性。 如需成員的詳細資訊mask，請參閱。
nItem
要設定其屬性的專案索引。
nSubItem
要設定其屬性的子專案的索引。
nMask
指定要設定的屬性（請參閱。
lpszItem
指定項目標籤之 Null 終止字串的位址。
nImage
影像清單中的專案影像索引。
nState
指定要變更的狀態值（請參閱。
nStateMask
指定要變更的狀態（請參閱。
lParam
如果您要編譯 x64 的應用程式特定值，則為 32 位（64 位），以與專案產生關聯。
nIndent
縮排的寬度，以像素為單位。 如果 nIndent 小於系統定義的最小寬度，新的寬度會設定為系統定義的最小值
傳回值
如果成功則不為零，否則為 0。
備註
結構和 iItem 和參數的 LVITEM nItem nSubItem 和 iSubItem 成員會識別要設定其屬性的項目和子專案。
結構與 mask nMask 參數的成員LVITEM指定要設定的項目屬性：
LVIF_TEXT成員pszText或lpszItem參數是 Null 終止字串的位址;cchTextMax會忽略成員。LVIF_STATE成員stateMask或nStateMask參數會指定要變更的項目狀態，而state成員或nState參數包含這些狀態的值。
範例
請參閱 CListCtrl::HitTest 的範例。
CListCtrl::SetItemCount
準備清單檢視控件以新增大量專案。
void SetItemCount(int nItems);
參數
nItems
控制件最終將包含的項目數目。
備註
若要設定虛擬清單檢視控制元件的項目計數，請參閱 CListCtrl::SetItemCountEx。
此成員函式會實作 Win32 巨集的行為， ListView_SetItemCount如 Windows SDK 中所述。
範例
CString str;
// Add 1024 items to the list view control.
m_myListCtrl.SetItemCount(1024);
for (int i = 0; i < 1024; i++)
{
str.Format(TEXT("item %d"), i);
m_myListCtrl.InsertItem(i, str);
}
CListCtrl::SetItemCountEx
設定虛擬清單檢視控件的項目計數。
BOOL SetItemCountEx(
int iCount,
DWORD dwFlags = LVSICF_NOINVALIDATEALL);
參數
iCount
控制件最終將包含的項目數目。
dwFlags
指定重設專案計數之後清單檢視控件的行為。 此值可以是下列各項的組合：
LVSICF_NOINVALIDATEALL除非受影響的專案目前在檢視中，否則清單檢視控件不會重新重繪。 這是預設值。LVSICF_NOSCROLL清單檢視控件不會在專案計數變更時變更卷動位置。
傳回值
如果成功則不為零，否則為 0。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetItemCountEx如 Windows SDKand 中所述，應該只針對虛擬清單檢視呼叫。
範例
CString str;
// Add 1024 items to the list view control.
// Force my virtual list view control to allocate
// enough memory for my 1024 items.
m_myVirtualListCtrl.SetItemCountEx(1024, LVSICF_NOSCROLL|
LVSICF_NOINVALIDATEALL);
for (int i = 0; i < 1024; i++)
{
str.Format(TEXT("item %d"), i);
m_myVirtualListCtrl.InsertItem(i, str);
}
CListCtrl::SetItemData
設定與所 nItem指定專案相關聯的32位（64位）應用程式特定值。
BOOL SetItemData(int nItem, DWORD_PTR dwData);
參數
nItem
要設定其數據的清單專案索引。
dwData
32 位值（如果您要編譯 x64，則為64位），以與專案產生關聯。
傳回值
如果成功則為非零；否則為 0。
備註
此值是 lParam 結構的成員 LVITEM ，如 Windows SDK 中所述。
範例
// Set the data of each item to be equal to its index.
for (int i = 0; i < m_myListCtrl.GetItemCount(); i++)
{
m_myListCtrl.SetItemData(i, i);
}
CListCtrl::SetItemIndexState
設定目前清單檢視控件中項目的狀態。
BOOL SetItemIndexState(
PLVITEMINDEX pItemIndex,
DWORD dwState,
DWORD dwMask) const;
參數
pItemIndex
[in] LVITEMINDEX 描述專案之結構的指標。 呼叫端負責配置此結構並設定其成員。
dwState
[in]要設定項目的狀態，這是清單檢視項目狀態的位元組合。 指定要重設的零，或指定要設定的狀態。
dwMask
[in]參數所 dwState 指定之狀態有效位的遮罩。 指定清單檢視項目狀態的位組合（OR）。
傳回值
TRUE 如果此方法成功，則為 ;否則為 FALSE。
備註
如需 參數的詳細資訊 dwState ，請參閱 清單檢視項目狀態。
如需 參數的詳細資訊 dwMask ，請參閱 stateMask 結構的成員 LVITEM 。
這個方法會傳送 LVM_SETITEMINDEXSTATE 訊息，如 Windows SDK 中所述。
CListCtrl::SetItemPosition
將專案移至清單檢視控制件中的指定位置。
BOOL SetItemPosition(
int nItem,
POINT pt);
參數
nItem
要設定其位置的專案索引。
pt
POINT結構，指定專案左上角的新位置，以檢視座標表示。
傳回值
如果成功則不為零，否則為 0。
備註
控件必須位於圖示或小型圖示檢視中。
如果清單檢視控制元件具有 LVS_AUTOARRANGE 樣式，則會在設定專案的位置之後排列清單檢視。
範例
請參閱 CListCtrl::GetItemPosition 的範例。
CListCtrl::SetItemState
變更清單檢視控件中項目的狀態。
BOOL SetItemState(
int nItem,
LVITEM* pItem);
BOOL SetItemState(
int nItem,
UINT nState,
UINT nMask);
參數
nItem
要設定其狀態的專案索引。 傳遞 -1 以將狀態變更套用至所有專案。
pItem
LVITEM結構的位址，如 Windows SDK 中所述。 結構 stateMask 的成員會指定要變更的狀態位，而 結構 state 的成員包含這些位的新值。 會忽略其他成員。
nState
狀態位的新值。 如需可能值的清單，請參閱 CListCtrl::GetNextItem 和 LVITEM 狀態成員。
nMask
遮罩，指定要變更的狀態位。 這個值會對應至 結構的狀態 LVITEM Mask 成員。
傳回值
如果成功則不為零，否則為 0。
備註
專案的「狀態」是指定專案可用性、指出用戶動作或反映項目狀態的值。 清單檢視控件會變更一些狀態位，例如當用戶選取專案時。 應用程式可能會變更其他狀態位來停用或隱藏專案，或指定重疊影像或狀態影像。
範例
請參閱 CListCtrl::GetTopIndex 的範例。
CListCtrl::SetItemText
變更清單檢視專案或子專案的文字。
BOOL SetItemText(
int nItem,
int nSubItem,
LPCTSTR lpszText);
參數
nItem
要設定其文字的專案索引。
nSubItem
子專案的索引，或零來設定專案標籤。
lpszText
包含新專案文字的字串指標。
傳回值
如果成功則不為零，否則為 0。
備註
此方法不適用於包含視窗樣式的 LVS_OWNERDATA 控件（事實上，這會導致偵錯組建中的判斷提示）。 如需此清單控件樣式的詳細資訊，請參閱 清單檢視控件概觀。
範例
請參閱 CListCtrl::InsertItem 的範例。
CListCtrl::SetOutlineColor
如果 LVS_EX_BORDERSELECT 設定延伸視窗樣式，則設定清單檢視控件框線的色彩。
COLORREF SetOutlineColor(COLORREF color);
參數
color
包含外框色彩的新 COLORREF 結構。
傳回值
上一 COLORREF 個結構，包含外框色彩
備註
此成員函式會模擬訊息的功能 LVM_SETOUTLINECOLOR ，如 Windows SDK 中所述。
CListCtrl：：SetSelectedColumn
設定清單檢視控件的選取資料行。
LRESULT SetSelectedColumn(int iCol);
參數
iCol
要選取之數據行的索引。
傳回值
不會使用傳回值。
備註
此成員函式會模擬訊息的功能 LVM_SETSELECTEDCOLUMN ，如 Windows SDK 中所述。
CListCtrl::SetSelectionMark
設定清單檢視控件的選取標記。
int SetSelectionMark(int iIndex);
參數
iIndex
多重選取範圍中第一個專案之以零起始的索引。
傳回值
上一個選取標記，如果沒有選取標記，則為 -1。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetSelectionMark如 Windows SDK 中所述。
範例
請參閱 CListCtrl::GetSelectionMark 的範例。
CListCtrl::SetTextBkColor
設定清單檢視控件中文字的背景色彩。
BOOL SetTextBkColor(COLORREF cr);
參數
cr
COLORREF，指定新的文字背景色彩。 如需詳細資訊，請參閱 COLORREF Windows SDK 中的 。
傳回值
如果成功則不為零，否則為 0。
範例
// Use the 3D button face color for the background.
COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
m_myListCtrl.SetTextBkColor(crBkColor);
ASSERT(m_myListCtrl.GetTextBkColor() == crBkColor);
CListCtrl::SetTextColor
設定清單檢視控件的文字色彩。
BOOL SetTextColor(COLORREF cr);
參數
cr
COLORREF，指定新的文字色彩。 如需詳細資訊，請參閱 COLORREF Windows SDK 中的 。
傳回值
如果成功則不為零，否則為 0。
範例
// Use the window text color for
// the item text of the list view control.
COLORREF crTextColor = ::GetSysColor(COLOR_WINDOWTEXT);
m_myListCtrl.SetTextColor(crTextColor);
ASSERT(m_myListCtrl.GetTextColor() == crTextColor);
CListCtrl::SetTileInfo
設定清單檢視控件磚的資訊。
BOOL SetTileInfo(PLVTILEINFO pTileInfo);
參數
pTileInfo
結構的指標 LVTILEINFO ，其中包含要設定的資訊。
傳回值
成功時傳回 TRUE，失敗時則傳回 FALSE。
備註
此成員函式會模擬訊息的功能 LVM_SETTILEINFO ，如 Windows SDK 中所述。
CListCtrl::SetTileViewInfo
設定清單檢視控件在磚檢視中使用的資訊。
BOOL SetTileViewInfo(PLVTILEVIEWINFO ptvi);
參數
ptvi
結構的指標 LVTILEVIEWINFO ，其中包含要設定的資訊。
傳回值
成功時傳回 TRUE，失敗時則傳回 FALSE。
備註
此成員函式會模擬訊息的功能 LVM_SETTILEVIEWINFO ，如 Windows SDK 中所述。
CListCtrl::SetToolTips
設定清單檢視控件將用來顯示工具提示的工具提示控件。
CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);
參數
pWndTip
清單控制件將使用之物件的指標 CToolTipCtrl 。
傳回值
物件的指標 CToolTipCtrl ，包含控件先前使用的工具提示，或 NULL 先前未使用任何工具提示。
備註
此成員函式會實作 Win32 訊息 LVM_SETTOOLTIPS 的行為，如 Windows SDK 中所述。
若要不使用工具提示，請在 LVS_NOTOOLTIPS 建立 CListCtrl 物件時指出樣式。
CListCtrl::SetView
設定清單檢視控件的檢視。
DWORD SetView(int iView);
參數
iView
要選取的檢視。
傳回值
如果成功，則傳回 1，否則傳回 -1。 例如，如果檢視無效，則會傳回 -1。
備註
此成員函式會模擬訊息的功能 LVM_SETVIEW ，如 Windows SDK 中所述。
CListCtrl::SetWorkAreas
設定可以在清單檢視控件中顯示圖示的區域。
void SetWorkAreas(
int nWorkAreas,
LPRECT lpRect);
參數
nWorkAreas
所指向lpRect之陣列中的結構數目RECT（或 CRect 物件）。
lpRect
指定清單檢視控件之新工作區域之結構數位的位址 RECT 。 CRect 。 這些區域必須在用戶端座標中指定。 如果此參數為 NULL，工作區域將會設定為控件的工作區。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SetWorkAreas如 Windows SDK 中所述。
範例
// Remove all working areas.
m_myListCtrl.SetWorkAreas(0, NULL);
CListCtrl::SortGroups
使用應用程式定義的比較函式，依清單檢視控件中的標識元排序群組。
BOOL SortGroups(
PFNLVGROUPCOMPARE _pfnGroupCompare,
LPVOID _plv);
參數
_pfnGroupCompare
群組比較函式的指標。
_plv
void 指標。
傳回值
成功時傳回 TRUE，失敗時則傳回 FALSE。
備註
此成員函式會模擬訊息的功能 LVM_SORTGROUPS ，如 Windows SDK 中所述。
CListCtrl::SortItems
使用應用程式定義的比較函式來排序列表檢視專案。
BOOL SortItems(
PFNLVCOMPARE pfnCompare,
DWORD_PTR dwData);
參數
pfnCompare
[in]應用程式定義的比較函式位址。
每次需要判斷兩個清單項目的相對順序時，排序作業都會呼叫比較函式。 比較函式必須是類別的靜態成員，或是不是任何類別成員的獨立函式。
dwData
[in]傳遞至比較函式的應用程式定義值。
傳回值
TRUE 如果方法成功，則為 ;否則 FALSE為 。
備註
此方法會變更每個專案的索引，以反映新的序列。
比較函式 pfnCompare具有下列形式：
int CALLBACK CompareFunc(LPARAM lParam1,
LPARAM lParam2,
LPARAM lParamSort);
如果第一個專案應位於第二個專案之前，則比較函式必須傳回負值、如果第一個項目應該遵循第二個專案，則傳回正值，如果兩個專案相等，則傳回零。
參數 lParam1 是與比較第一個專案相關聯的 32 位值（如果您要編譯 x64，則為 64 位），而 lParam2 參數是與第二個專案相關聯的值。 這些值是在項目LVITEM結構的成員中lParam插入清單時所指定的值。 參數 lParamSort 與 值相同 dwData 。
這個方法會傳送 LVM_SORTITEMS 訊息，如 Windows SDK 中所述。
範例
以下是簡單的比較函式，可讓專案依其 lParam 值排序。
// Sort items by associated lParam
int CALLBACK CListCtrlDlg::MyCompareProc(LPARAM lParam1, LPARAM lParam2,
LPARAM lParamSort)
{
UNREFERENCED_PARAMETER(lParamSort);
return (int)(lParam1 - lParam2);
}
// Sort the items by passing in the comparison function.
void CListCtrlDlg::Sort()
{
m_myListCtrl.SortItems(&CListCtrlDlg::MyCompareProc, 0);
}
CListCtrl::SortItemsEx
使用應用程式定義的比較函式，排序目前清單檢視控件的專案。
BOOL SortItemsEx(
PFNLVCOMPARE pfnCompare,
DWORD_PTR dwData);
參數
pfnCompare
[in]應用程式定義的比較函式位址。 每次需要判斷兩個清單項目的相對順序時，排序作業都會呼叫比較函式。 比較函式必須是類別的靜態成員，或是不是任何類別成員的獨立函式。
dwData
[in]傳遞至比較函式的應用程式定義值。
傳回值
TRUE 如果此方法成功，則為 ;否則為 FALSE。
備註
此方法會變更每個專案的索引，以反映新的序列。
比較函式 pfnCompare具有下列形式：
int CALLBACK CompareFunc(LPARAM lParam1,
LPARAM lParam2,
LPARAM lParamSort);
此訊息類似 LVM_SORTITEMS，但傳遞至比較函式的信息類型除外。 在 中 LVM_SORTITEMS， lParam1 和 lParam2 是要比較的專案值。 在 中 LVM_SORTITEMSEX， lParam1 是要比較之第一個專案的目前索引，也是 lParam2 第二個專案的目前索引。 您可以傳送 LVM_GETITEMTEXT 訊息來擷取項目的詳細資訊。
如果第一個專案應位於第二個專案之前，則比較函式必須傳回負值、如果第一個項目應該遵循第二個專案，則傳回正值，如果兩個專案相等，則傳回零。
注意
在排序過程中，清單檢視內容不穩定。 如果回調函式將任何訊息傳送至以外的 LVM_GETITEM清單檢視控件，則結果無法預測。
這個方法會傳送 LVM_SORTITEMSEX 訊息，如 Windows SDK 中所述。
範例
第一個程式代碼範例會定義用來存取目前清單檢視控制元件的變數 m_listCtrl。 下一個範例中會使用此變數。
public:
// Variable used to access the list control.
CListCtrl m_listCtrl;
下一個程式代碼範例示範 SortItemEx 方法。 在此程式代碼範例的上一節中，我們建立了清單檢視控件，在報表檢視中顯示標題為 “ClientID” 和 “Grade” 的兩個數據行。 下列程式代碼範例會使用 「Grade」 資料行中的值來排序數據表。
// The ListCompareFunc() method is a global function used by SortItemEx().
int CALLBACK ListCompareFunc(
LPARAM lParam1,
LPARAM lParam2,
LPARAM lParamSort)
{
CListCtrl* pListCtrl = (CListCtrl*) lParamSort;
CString strItem1 = pListCtrl->GetItemText(static_cast<int>(lParam1), 1);
CString strItem2 = pListCtrl->GetItemText(static_cast<int>(lParam2), 1)
int x1 = _tstoi(strItem1.GetBuffer());
int x2 = _tstoi(strItem2.GetBuffer());
int result = 0;
if ((x1 - x2) < 0)
result = -1;
else if ((x1 - x2) == 0)
result = 0;
else
result = 1;
return result;
}
void CCListCtrl_s2Dlg::OnBnClickedButton1()
{
// SortItemsEx
m_listCtrl.SortItemsEx( ListCompareFunc, (LPARAM)&m_listCtrl );
}
CListCtrl::SubItemHitTest
判斷哪個清單檢視專案，如果有的話，位於指定的位置。
int SubItemHitTest(LPLVHITTESTINFO pInfo);
參數
pInfo
結構的 LVHITTESTINFO 指標。
傳回值
要測試之專案或子專案的一個索引（如果有的話），否則為 -1。
備註
此成員函式會實作 Win32 巨集的行為， ListView_SubItemHitTest如 Windows SDK 中所述。
範例
void CListCtrlDlg::OnDblClk(NMHDR* pNMHDR, LRESULT* pResult)
{
UNREFERENCED_PARAMETER(pResult);
LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
LVHITTESTINFO lvhti;
// Clear the subitem text the user clicked on.
lvhti.pt = pia->ptAction;
m_myListCtrl.SubItemHitTest(&lvhti);
if (lvhti.flags & LVHT_ONITEMLABEL)
{
m_myListCtrl.SetItemText(lvhti.iItem, lvhti.iSubItem, NULL);
}
}
CListCtrl::Update
強制清單檢視控件重新繪出 所 nItem指定的專案。
BOOL Update(int nItem);
參數
nItem
要更新之專案的索引。
傳回值
如果成功則不為零，否則為 0。
備註
如果清單檢視控制項具有樣式， LVS_AUTOARRANGE 此函式也會排列清單檢視控件。
範例
請參閱 CListCtrl::GetSelectedCount 的範例。