`CListBox` 類別

發行項
06/16/2023

提供 Windows 清單方塊的功能。

語法

class CListBox : public CWnd

成員

公用建構函式

名稱	描述
`CListBox::CListBox`	建構 `CListBox` 物件。

公用方法

名稱	描述
`CListBox::AddString`	將字串新增至清單方塊。
`CListBox::CharToItem`	覆寫以提供沒有字串之擁有者繪製清單方塊的自訂 `WM_CHAR` 處理。
`CListBox::CompareItem`	由架構呼叫，以判斷新專案在已排序的擁有者繪製清單方塊中的位置。
`CListBox::Create`	建立 Windows 清單方塊，並將它附加至 `CListBox` 物件。
`CListBox::DeleteItem`	當使用者從擁有者繪製清單方塊中刪除專案時，由架構呼叫。
`CListBox::DeleteString`	從清單方塊刪除字串。
`CListBox::Dir`	將檔案名、磁片磁碟機或兩者從目前目錄新增至清單方塊。
`CListBox::DrawItem`	當擁有者繪製清單方塊的視覺層面變更時，由架構呼叫。
`CListBox::FindString`	在清單方塊中搜尋字串。
`CListBox::FindStringExact`	尋找符合指定字串的第一個清單方塊字串。
`CListBox::GetAnchorIndex`	擷取清單方塊中目前錨點專案的以零起始的索引。
`CListBox::GetCaretIndex`	決定在多重選取範圍清單方塊中具有焦點矩形的專案索引。
`CListBox::GetCount`	傳回清單方塊中的字串數目。
`CListBox::GetCurSel`	傳回清單方塊中目前選取字串之以零起始的索引。
`CListBox::GetHorizontalExtent`	傳回清單方塊可以水準捲動的圖元寬度。
`CListBox::GetItemData`	傳回與清單方塊專案相關聯的值。
`CListBox::GetItemDataPtr`	傳回清單方塊專案的指標。
`CListBox::GetItemHeight`	決定清單方塊中專案的高度。
`CListBox::GetItemRect`	傳回清單方塊專案的周框，因為它目前顯示。
`CListBox::GetListBoxInfo`	擷取每個資料行的專案數。
`CListBox::GetLocale`	擷取清單方塊的地區設定識別碼。
`CListBox::GetSel`	傳回清單方塊專案的選取狀態。
`CListBox::GetSelCount`	傳回目前在多重選取清單方塊中選取的字串數目。
`CListBox::GetSelItems`	傳回目前在清單方塊中選取之字串的索引。
`CListBox::GetText`	將清單方塊專案複製到緩衝區。
`CListBox::GetTextLen`	傳回清單方塊專案的位元組長度。
`CListBox::GetTopIndex`	傳回清單方塊中第一個可見字串的索引。
`CListBox::InitStorage`	預先配置清單方塊專案和字串的記憶體區塊。
`CListBox::InsertString`	在清單方塊中的特定位置插入字串。
`CListBox::ItemFromPoint`	傳回最接近某個點的清單方塊專案的索引。
`CListBox::MeasureItem`	建立擁有者繪製清單方塊以決定清單方塊維度時，由架構呼叫。
`CListBox::ResetContent`	從清單方塊清除所有專案。
`CListBox::SelectString`	在單一選取清單方塊中搜尋並選取字串。
`CListBox::SelItemRange`	選取或取消選取多重選取清單方塊中的字串範圍。
`CListBox::SetAnchorIndex`	設定多重選取範圍清單方塊中的錨點，以開始延伸選取範圍。
`CListBox::SetCaretIndex`	將焦點矩形設定為位於多重選取清單方塊中指定索引處的專案。
`CListBox::SetColumnWidth`	設定多欄清單方塊的資料行寬度。
`CListBox::SetCurSel`	選取清單方塊字串。
`CListBox::SetHorizontalExtent`	設定清單方塊可以水準捲動的圖元寬度。
`CListBox::SetItemData`	設定與清單方塊專案相關聯的值。
`CListBox::SetItemDataPtr`	設定清單方塊專案的指標。
`CListBox::SetItemHeight`	設定清單方塊中專案的高度。
`CListBox::SetLocale`	設定清單方塊的地區設定識別碼。
`CListBox::SetSel`	選取或取消選取多重選取清單方塊中的清單方塊專案。
`CListBox::SetTabStops`	設定清單方塊中的定位停駐點位置。
`CListBox::SetTopIndex`	設定清單方塊中第一個可見字串之以零起始的索引。
`CListBox::VKeyToItem`	覆寫以提供樣式集的清單方塊 `LBS_WANTKEYBOARDINPUT` 自訂 `WM_KEYDOWN` 處理。

備註

清單方塊會顯示使用者可以檢視和選取的專案清單，例如檔案名。

在單一選取清單方塊中，使用者只能選取一個專案。在多重選取清單方塊中，可以選取一系列專案。當使用者選取專案時，它會反白顯示，而清單方塊會將通知訊息傳送至父視窗。

您可以從對話方塊範本或直接在程式碼中建立清單方塊。若要直接建立物件，請建構 CListBox 物件，然後呼叫 Create 成員函式來建立 Windows 清單方塊控制項， CListBox 並將它附加至物件。若要在對話方塊範本中使用清單方塊，請在對話方塊類別中宣告清單方塊變數，然後在 DDX_Control 對話方塊類別的 DoDataExchange 函式中使用，將成員變數連接到控制項。（當您將控制項變數新增至對話方塊類別時，系統會自動為您完成此動作。

建構可以是衍生自 CListBox 的類別中的一個步驟程式。撰寫衍生類別的建構函式，並從建構函式內呼叫 Create 。

如果您想要處理清單方塊傳送至其父系的 Windows 通知訊息（通常是衍生自 CDialog 的類別），請將訊息對應專案和訊息處理常式成員函式新增至每個訊息的父類別。

每個訊息對應專案採用下列格式：

ON_Notification( id, memberFxn )

其中 id 會指定傳送通知之清單方塊控制項的子視窗識別碼，而 memberFxn 是您寫入以處理通知的父成員函式名稱。

父系的函式原型如下所示：

afx_msg void memberFxn( );

以下是潛在的訊息對應專案清單，以及將傳送至父系之案例的描述：

ON_LBN_DBLCLK 使用者按兩下清單方塊中的字串。只有具有 LBS_NOTIFY 樣式的清單方塊才會傳送此通知訊息。
ON_LBN_ERRSPACE 清單方塊無法配置足夠的記憶體以符合要求。
ON_LBN_KILLFOCUS 清單方塊會失去輸入焦點。
ON_LBN_SELCANCEL 目前的清單方塊選取專案已取消。只有在清單方塊具有 LBS_NOTIFY 樣式時，才會傳送此訊息。
ON_LBN_SELCHANGE 清單方塊中的選取範圍已變更。如果成員函式變更 CListBox::SetCurSel 選取範圍，則不會傳送此通知。此通知僅適用于具有 LBS_NOTIFY 樣式的清單方塊。 LBN_SELCHANGE每當使用者按下方向鍵時，就會傳送多選清單方塊的通知訊息，即使選取範圍沒有變更也一樣。
ON_LBN_SETFOCUS 清單方塊正在接收輸入焦點。
ON_WM_CHARTOITEM 沒有字串的擁有者繪製清單方塊會收到 WM_CHAR 訊息。
ON_WM_VKEYTOITEM 具有 LBS_WANTKEYBOARDINPUT 樣式的清單方塊會收到 WM_KEYDOWN 訊息。

如果您在對話方塊內建立 CListBox 物件（透過對話方塊資源）， CListBox 當使用者關閉對話方塊時，就會自動終結物件。

如果您在視窗中建立 CListBox 物件，您可能需要終結 CListBox 物件。如果您在堆疊上建立 CListBox 物件，它會自動終結。如果您使用函式在堆積上建立 CListBox 物件，則必須在使用者關閉父視窗時呼叫 delete 物件來終結 new 它。

如果您在物件中 CListBox 配置任何記憶體，請覆寫 CListBox 解構函式以處置配置。

繼承階層架構

CObject

CCmdTarget

CWnd

CListBox

需求

標頭：afxwin.h

`CListBox::AddString`

將字串新增至清單方塊。

int AddString(LPCTSTR lpszItem);

參數

lpszItem
指向要加入的 Null 終止字串。

傳回值

清單方塊中字串以零起始的索引。如果發生錯誤，則傳回值 LB_ERR 是 ;如果空間不足而無法儲存新字串，則傳回值為 LB_ERRSPACE 。

備註

如果未使用 LBS_SORT 樣式建立清單方塊，字串就會新增至清單結尾。否則，字串會插入清單中，並排序清單。如果清單方塊是以樣式建立， LBS_SORT 但不是 LBS_HASSTRINGS 樣式，則架構會依一或多個對成員函式的 CompareItem 呼叫來排序清單。

使用 InsertString 將字串插入清單方塊中的特定位置。

範例

// Add 10 items to the list box.
CString str;
for (int i = 0; i < 10; i++)
{
   str.Format(_T("item string %d"), i);
   m_myListBox.AddString(str);
}

`CListBox::CharToItem`

當清單方塊的父視窗收到 WM_CHARTOITEM 清單方塊的訊息時，由架構呼叫。

virtual int CharToItem(
    UINT nKey,
    UINT nIndex);

參數

nKey
使用者輸入之字元的 ANSI 程式碼。

nIndex
清單方塊插入號的目前位置。

傳回值

會傳回 - 1 或 - 2，表示沒有進一步的動作或非負數，以指定要執行按鍵預設動作的清單方塊專案的索引。預設實作會傳回 - 1。

備註

當 WM_CHARTOITEM 清單方塊收到 WM_CHAR 訊息時，訊息會由清單方塊傳送，但前提是清單方塊符合下列所有準則：

這是擁有者繪製清單方塊。
LBS_HASSTRINGS沒有樣式集。
至少有一個專案。

您不應該自行呼叫此函式。覆寫此函式以提供您自己的鍵盤訊息自訂處理。

在您的覆寫中，您必須傳回值，以告知架構您執行的動作。傳回值 - 1 或 - 2 表示您已處理選取專案的所有層面，而且清單方塊不需要採取任何進一步的動作。傳回 - 1 或 - 2 之前，您可以設定選取範圍或移動插入號或兩者。若要設定選取範圍，請使用 SetCurSel 或 SetSel 。若要移動插入號，請使用 SetCaretIndex 。

傳回值為 0 或更新的值會指定清單方塊中專案的索引，並指出清單方塊應該對指定專案執行按鍵的預設動作。

範例

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example moves the caret down one item on a numeric key and up one item
// on an alphabetic key. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::CharToItem(UINT nChar, UINT nIndex)
{
   // On a numeric key, move the caret up one item.
   if (isdigit(nChar) && (nIndex > 0))
   {
      SetCaretIndex(nIndex - 1);
   }
   // On an alphabetic key, move the caret down one item.
   else if (isalpha(nChar) && (nIndex < (UINT)GetCount()))
   {
      SetCaretIndex(nIndex + 1);
   }

   // Do not perform any default processing.
   return -1;
}

`CListBox::CListBox`

建構 CListBox 物件。

CListBox();

備註

您會在兩個步驟中建構 CListBox 物件。首先，呼叫建構函式 ClistBox ，然後呼叫 Create ，它會初始化 Windows 清單方塊，並將它附加至 CListBox 。

範例

// Declare a local CListBox object.
CListBox myListBox;

// Declare a dynamic CListBox object.
CListBox *pmyListBox = new CListBox;

`CListBox::CompareItem`

由架構呼叫，以判斷新專案在已排序的擁有者繪製清單方塊中的相對位置。

virtual int CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct);

參數

lpCompareItemStruct
結構的長指標 COMPAREITEMSTRUCT 。

傳回值

指出結構中所描述之兩個專案的 COMPAREITEMSTRUCT 相對位置。它可以是下列任何一個值：

值	意義
-1	專案 1 在專案 2 之前排序。
0	專案 1 和專案 2 會排序相同。
1	專案 1 在專案 2 之後排序。

如需結構的描述， COMPAREITEMSTRUCT 請參閱 CWnd::OnCompareItem 。

備註

根據預設，此成員函式不會執行任何動作。如果您使用樣式建立擁有者繪製清單方塊 LBS_SORT ，則必須覆寫此成員函式，以協助架構排序新增至清單方塊的新專案。

範例

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example compares two items using _tcscmp to sort items in reverse
// alphabetical order. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct)
{
   ASSERT(lpCompareItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText1 = (LPCTSTR)lpCompareItemStruct->itemData1;
   ASSERT(lpszText1 != NULL);
   LPCTSTR lpszText2 = (LPCTSTR)lpCompareItemStruct->itemData2;
   ASSERT(lpszText2 != NULL);

   return _tcscmp(lpszText2, lpszText1);
}

`CListBox::Create`

建立 Windows 清單方塊，並將它附加至 CListBox 物件。

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

參數

dwStyle
指定清單方塊的樣式。將清單方塊樣式的任何組合套用至方塊。

rect
指定清單方塊的大小和位置。可以是 CRect 物件或 RECT 結構。

pParentWnd
指定清單方塊的父視窗（通常是 CDialog 物件）。它不得為 NULL 。

nID
指定清單方塊的控制項識別碼。

傳回值

如果成功則為非零；否則為 0。

備註

您會在兩個步驟中建構 CListBox 物件。首先，呼叫建構函式，然後呼叫 Create ，它會初始化 Windows 清單方塊，並將它附加至 CListBox 物件。

執行時 Create ，Windows 會將 WM_NCCREATE 、 WM_CREATE 、 WM_NCCALCSIZE 和 WM_GETMINMAXINFO 訊息傳送至清單方塊控制項。

基類中的 CWnd 、 OnNcCalcSizeOnCreate 和 OnGetMinMaxInfo 成員函式預設 OnNcCreate 會處理這些訊息。若要擴充預設訊息處理，請從 CListBox 衍生類別、將訊息對應新增至新類別，並覆寫上述訊息處理常式成員函式。例如，覆寫 OnCreate ，以執行新類別所需的初始化。

將下列視窗樣式套用至清單方塊控制項。

WS_CHILD 總是
WS_VISIBLE 通常
WS_DISABLED 很少
WS_VSCROLL 若要新增垂直捲動條
WS_HSCROLL 若要新增水準捲軸
WS_GROUP 將控制項分組
WS_TABSTOP 允許索引標籤至此控制項

範例

// pParentWnd is a pointer to the parent window.
m_myListBox.Create(WS_CHILD | WS_VISIBLE | LBS_STANDARD | WS_HSCROLL,
                   CRect(10, 10, 200, 200), pParentWnd, IDC_MYLISTBOX);

`CListBox::DeleteItem`

當使用者從擁有者繪製 CListBox 物件中刪除專案或終結清單方塊時，由架構呼叫。

virtual void DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct);

參數

lpDeleteItemStruct
Windows DELETEITEMSTRUCT 結構的長指標，其中包含已刪除專案的相關資訊。

備註

此函式的預設實作不做任何動作。覆寫此函式，視需要重新繪製擁有者繪製清單方塊。

如需結構的描述， DELETEITEMSTRUCT 請參閱 CWnd::OnDeleteItem 。

範例

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example simply frees the item's text. The list box control was created
// with the following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct)
{
   ASSERT(lpDeleteItemStruct->CtlType == ODT_LISTBOX);
   LPVOID lpszText = (LPVOID)lpDeleteItemStruct->itemData;
   ASSERT(lpszText != NULL);

   free(lpszText);

   CListBox::DeleteItem(lpDeleteItemStruct);
}

`CListBox::DeleteString`

從清單方塊中刪除位置 nIndex 中的專案。

int DeleteString(UINT nIndex);

參數

nIndex
指定要刪除之字串的以零起始的索引。

傳回值

清單中剩餘的字串計數。如果指定索引大於清單中的專案數目，則傳回值 LB_ERRnIndex 為。

備註

之後 nIndex 的所有專案現在都會向下移動一個位置。例如，如果清單方塊包含兩個專案，刪除第一個專案會導致剩餘的專案現在處於第一個位置。 nIndex第一個位置之專案的 =0。

範例

// Delete every other item from the list box.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.DeleteString(i);
}

`CListBox::Dir`

將檔案名、磁片磁碟機或兩者的清單新增至清單方塊。

int Dir(
    UINT attr,
    LPCTSTR lpszWildCard);

參數

attr
可以是中 CFile::GetStatus 描述的任何值組合 enum ，或下列值的任何組合：

值	意義
0x0000	檔案可以讀取或寫入。
0x0001	檔案可以從讀取，但無法寫入。
0x0002	檔案是隱藏的，而且不會出現在目錄清單中。
0x0004	檔案是系統檔案。
0x0010	所 `lpszWildCard` 指定的名稱會指定目錄。
0x0020	檔案已封存。
0x4000	包含符合所 `lpszWildCard` 指定名稱的所有磁片磁碟機。
0x8000	獨佔旗標。如果已設定獨佔旗標，則只會列出指定類型的檔案。否則，除了「一般」檔案之外，也會列出指定類型的檔案。

lpszWildCard
指向檔案規格字串。字串可以包含萬用字元（例如 *.*）。

傳回值

新增至清單之最後一個檔案名之以零起始的索引。如果發生錯誤，則傳回值 LB_ERR 是 ;如果空間不足而無法儲存新的字串，則傳回值為 LB_ERRSPACE 。

範例

// Add all the files and directories in the windows directory.
TCHAR lpszWinPath[MAX_PATH], lpszOldPath[MAX_PATH];
::GetWindowsDirectory(lpszWinPath, MAX_PATH);

::GetCurrentDirectory(MAX_PATH, lpszOldPath);
::SetCurrentDirectory(lpszWinPath);

m_myListBox.ResetContent();
m_myListBox.Dir(DDL_READWRITE | DDL_DIRECTORY, _T("*.*"));

::SetCurrentDirectory(lpszOldPath);

`CListBox::DrawItem`

當擁有者繪製清單方塊的視覺層面變更時，由架構呼叫。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

參數

lpDrawItemStruct
結構的長指標 DRAWITEMSTRUCT ，其中包含所需繪圖類型的相關資訊。

備註

結構的 itemAction 和 itemState 成員 DRAWITEMSTRUCT 會定義要執行的繪圖動作。

根據預設，此成員函式不會執行任何動作。覆寫這個成員函式，以實作擁有者繪製物件的繪圖 CListBox 。應用程式應該還原為此成員函式終止之前，針對所提供 lpDrawItemStruct 顯示內容選取的所有圖形裝置介面（GDI）物件。

如需結構的描述， DRAWITEMSTRUCT 請參閱 CWnd::OnDrawItem 。

範例

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example draws an item's text centered vertically and horizontally. The
// list box control was created with the following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct)
{
   ASSERT(lpDrawItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText = (LPCTSTR)lpDrawItemStruct->itemData;
   ASSERT(lpszText != NULL);
   CDC dc;

   dc.Attach(lpDrawItemStruct->hDC);

   // Save these value to restore them when done drawing.
   COLORREF crOldTextColor = dc.GetTextColor();
   COLORREF crOldBkColor = dc.GetBkColor();

   // If this item is selected, set the background color
   // and the text color to appropriate values. Also, erase
   // rect by filling it with the background color.
   if ((lpDrawItemStruct->itemAction | ODA_SELECT) &&
       (lpDrawItemStruct->itemState & ODS_SELECTED))
   {
      dc.SetTextColor(::GetSysColor(COLOR_HIGHLIGHTTEXT));
      dc.SetBkColor(::GetSysColor(COLOR_HIGHLIGHT));
      dc.FillSolidRect(&lpDrawItemStruct->rcItem,
                       ::GetSysColor(COLOR_HIGHLIGHT));
   }
   else
   {
      dc.FillSolidRect(&lpDrawItemStruct->rcItem, crOldBkColor);
   }

   // If this item has the focus, draw a red frame around the
   // item's rect.
   if ((lpDrawItemStruct->itemAction | ODA_FOCUS) &&
       (lpDrawItemStruct->itemState & ODS_FOCUS))
   {
      CBrush br(RGB(255, 0, 0));
      dc.FrameRect(&lpDrawItemStruct->rcItem, &br);
   }

   // Draw the text.
   dc.DrawText(
       lpszText,
       (int)_tcslen(lpszText),
       &lpDrawItemStruct->rcItem,
       DT_CENTER | DT_SINGLELINE | DT_VCENTER);

   // Reset the background color and the text color back to their
   // original values.
   dc.SetTextColor(crOldTextColor);
   dc.SetBkColor(crOldBkColor);

   dc.Detach();
}

`CListBox::FindString`

在清單方塊中尋找包含指定前置詞的第一個字串，而不變更清單方塊選取範圍。

int FindString(
    int nStartAfter,
    LPCTSTR lpszItem) const;

參數

nStartAfter
包含專案以零起始的索引，再搜尋第一個專案。當搜尋到達清單方塊底部時，它會從清單方塊的頂端繼續回到所 nStartAfter 指定的專案。如果 nStartAfter 為 -1，則會從頭搜尋整個清單方塊。

lpszItem
指向包含要搜尋之前置詞的 Null 終止字串。搜尋不區分大小寫，因此此字串可能包含大寫和小寫字母的任何組合。

傳回值

比對專案之以零起始的索引，如果 LB_ERR 搜尋失敗，則為。

備註

SelectString使用成員函式來尋找並選取字串。

範例

// The string to match.
LPCTSTR lpszmyString = _T("item");

// Delete all items that begin with the specified string.
int nIndex = 0;
while ((nIndex = m_myListBox.FindString(nIndex, lpszmyString)) != LB_ERR)
{
   m_myListBox.DeleteString(nIndex);
}

`CListBox::FindStringExact`

尋找符合中所 lpszFind 指定字串的第一個清單方塊字串。

int FindStringExact(
    int nIndexStart,
    LPCTSTR lpszFind) const;

參數

nIndexStart
指定要在搜尋第一個專案之前，以零起始的專案索引。當搜尋到達清單方塊底部時，它會從清單方塊的頂端繼續回到所 nIndexStart 指定的專案。如果 nIndexStart 為 -1，則會從頭搜尋整個清單方塊。

lpszFind
指向要搜尋的 Null 終止字串。此字串可以包含完整的檔案名，包括副檔名。搜尋不區分大小寫，因此字串可以包含大寫和小寫字母的任何組合。

傳回值

比對專案的索引，如果 LB_ERR 搜尋失敗，則為。

備註

如果清單方塊是以擁有者繪製樣式所建立，但沒有 LBS_HASSTRINGS 樣式， FindStringExact 則成員函式會嘗試比對雙字值與的值 lpszFind 。

範例

// The string to match.
LPCTSTR lpszmyString = _T("item string 3");

// Delete all items that exactly match the specified string.
int nIndex = 0;
while ((nIndex = m_myListBox.FindStringExact(nIndex, lpszmyString)) != LB_ERR)
{
   m_myListBox.DeleteString(nIndex);
}

`CListBox::GetAnchorIndex`

擷取清單方塊中目前錨點專案的以零起始的索引。

int GetAnchorIndex() const;

傳回值

如果成功，則為目前錨點專案的索引;否則為 LB_ERR。

備註

在多重選取清單方塊中，錨點專案是連續選取專案區塊中的第一個或最後一個專案。

範例

請參閱的 CListBox::SetAnchorIndex 範例。

`CListBox::GetCaretIndex`

決定在多重選取範圍清單方塊中具有焦點矩形的專案索引。

int GetCaretIndex() const;

傳回值

清單方塊中具有焦點矩形的專案以零起始的索引。如果清單方塊是單一選取清單方塊，則傳回值是所選取專案的索引，如果有的話。

備註

專案可能或可能未選取。

範例

請參閱的 CListBox::SetCaretIndex 範例。

`CListBox::GetCount`

擷取清單方塊中的專案數。

int GetCount() const;

傳回值

清單方塊中的專案數，如果 LB_ERR 發生錯誤，則為。

備註

傳回的計數大於最後一個專案的索引值（索引是以零起始的）。

範例

// Add 10 items to the list box.
CString str;
for (int i = 0; i < 10; i++)
{
   str.Format(_T("item %d"), i);
   m_myListBox.AddString(str);
}

// Verify that 10 items were added to the list box.
ASSERT(m_myListBox.GetCount() == 10);

`CListBox::GetCurSel`

在單一選取清單方塊中，擷取目前選取專案之以零起始的索引。

int GetCurSel() const;

傳回值

如果目前選取的專案是單一選取清單方塊，則為以零起始的索引。 LB_ERR如果目前未選取任何專案，則為。

在多重選取清單方塊中，具有焦點的專案索引。

備註

請勿呼叫 GetCurSel 多重選取清單方塊。請改用 CListBox::GetSelItems。

範例

// Select the next item of the currently selected one.
int nIndex = m_myListBox.GetCurSel();
int nCount = m_myListBox.GetCount();
if ((nIndex != LB_ERR) && (nCount > 1))
{
   if (++nIndex < nCount)
      m_myListBox.SetCurSel(nIndex);
   else
      m_myListBox.SetCurSel(0);
}

`CListBox::GetHorizontalExtent`

從清單方塊擷取寬度，以圖元為單位，可以水準捲動。

int GetHorizontalExtent() const;

傳回值

清單方塊的可捲動寬度，以圖元為單位。

備註

只有當清單方塊有水準捲軸時，才適用。

範例

// Find the longest string in the list box.
CString str;
CSize sz;
int dx = 0;
CDC *pDC = m_myListBox.GetDC();
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
m_myListBox.ReleaseDC(pDC);

// Set the horizontal extent only if the current extent is not large enough.
if (m_myListBox.GetHorizontalExtent() < dx)
{
   m_myListBox.SetHorizontalExtent(dx);
   ASSERT(m_myListBox.GetHorizontalExtent() == dx);
}

`CListBox::GetItemData`

擷取與指定清單方塊專案相關聯的應用程式提供的 doubleword 值。

DWORD_PTR GetItemData(int nIndex) const;

參數

nIndex
指定清單方塊中專案以零起始的索引。

傳回值

與專案相關聯的值，如果 LB_ERR 發生錯誤，則為。

備註

doubleword 值是 dwItemData 呼叫的參數 SetItemData 。

範例

// If any item's data is equal to zero then reset it to -1.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   if (m_myListBox.GetItemData(i) == 0)
   {
      m_myListBox.SetItemData(i, (DWORD)-1);
   }
}

`CListBox::GetItemDataPtr`

擷取與指定清單方塊專案相關聯的應用程式提供的 32 位值做為指標（ void* ）。

void* GetItemDataPtr(int nIndex) const;

參數

nIndex
指定清單方塊中專案以零起始的索引。

傳回值

擷取指標，如果發生錯誤，則為 -1。

範例

LPVOID lpmyPtr = pParentWnd;

// Check all the items in the list box; if an item's
// data pointer is equal to my pointer then reset it to NULL.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   if (m_myListBox.GetItemDataPtr(i) == lpmyPtr)
   {
      m_myListBox.SetItemDataPtr(i, NULL);
   }
}

`CListBox::GetItemHeight`

決定清單方塊中專案的高度。

int GetItemHeight(int nIndex) const;

參數

nIndex
指定清單方塊中專案以零起始的索引。只有當清單方塊具有 LBS_OWNERDRAWVARIABLE 樣式時，才會使用此參數，否則應該設定為 0。

傳回值

清單方塊中專案的高度，以圖元為單位。如果清單方塊具有 LBS_OWNERDRAWVARIABLE 樣式，則傳回值是所 nIndex 指定專案的高度。如果發生錯誤，傳回值為 LB_ERR 。

範例

// Set the height of every item so the item
// is completely visible.
CString str;
CSize sz;
CDC *pDC = m_myListBox.GetDC();
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   // Only want to set the item height if the current height
   // is not big enough.
   if (m_myListBox.GetItemHeight(i) < sz.cy)
      m_myListBox.SetItemHeight(i, sz.cy);
}
m_myListBox.ReleaseDC(pDC);

`CListBox::GetItemRect`

擷取周框維度，此矩形會系結清單方塊專案，因為它目前顯示在清單方塊視窗中。

int GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

參數

nIndex
指定專案以零起始的索引。

lpRect
指定接收專案清單方塊用戶端座標之結構的長指標。 RECT

傳回值

LB_ERR 如果發生錯誤，則為。

範例

// Dump all of the items bounds.
CString str;
RECT r;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetItemRect(i, &r);

   str.Format(_T("item %d: left = %d, top = %d, right = %d, ")
              _T("bottom = %d\r\n"),
              i,
              r.left,
              r.top,
              r.right,
              r.bottom);
   AFXDUMP(str);
}

`CListBox::GetListBoxInfo`

擷取每個資料行的專案數。

DWORD GetListBoxInfo() const;

傳回值

物件的每個資料行 CListBox 的專案數。

備註

此成員函式會模擬訊息的功能 LB_GETLISTBOXINFO ，如 Windows SDK 中所述。

`CListBox::GetLocale`

擷取清單方塊所使用的地區設定。

LCID GetLocale() const;

傳回值

清單方塊中字串的地區設定識別碼（LCID）值。

備註

例如，地區設定可用來判斷排序清單方塊中字串的排序次序。

範例

請參閱的 CListBox::SetLocale 範例。

`CListBox::GetSel`

擷取專案的選取狀態。

int GetSel(int nIndex) const;

參數

nIndex
指定專案以零起始的索引。

傳回值

如果選取指定的專案，則為正數;否則為 0。如果發生錯誤，則傳回值為 LB_ERR 。

備註

此成員函式適用于單一和多重選取清單方塊。

若要擷取目前選取清單方塊專案的索引，請使用 CListBox::GetCurSel 。

範例

// Dump all of the items select state.
CString str;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   str.Format(_T("item %d: select state is %s\r\n"),
              i,
              m_myListBox.GetSel(i) > 0 ? _T("true") : _T("false"));
   AFXDUMP(str);
}

`CListBox::GetSelCount`

擷取多重選取清單方塊中選取的專案總數。

int GetSelCount() const;

傳回值

清單方塊中所選項目的計數。如果清單方塊是單一選取清單方塊，則傳回值為 LB_ERR 。

範例

請參閱的 CListBox::GetSelItems 範例。

`CListBox::GetSelItems`

以整數陣列填滿緩衝區，以指定多重選取清單方塊中所選取專案的專案編號。

int GetSelItems(
    int nMaxItems,
    LPINT rgIndex) const;

參數

nMaxItems
指定要在緩衝區中放置專案編號的選取專案數目上限。

rgIndex
指定緩衝區的指標，足以容納所 nMaxItems 指定的整數數目。

傳回值

放置於緩衝區中的實際專案數目。如果清單方塊是單一選取清單方塊，則傳回值為 LB_ERR 。

範例

// Get the indexes of all the selected items.
int nCount = m_myODListBox.GetSelCount();
CArray<int, int> aryListBoxSel;

aryListBoxSel.SetSize(nCount);
m_myODListBox.GetSelItems(nCount, aryListBoxSel.GetData());

// Dump the selection array.
AFXDUMP(aryListBoxSel);

`CListBox::GetText`

從清單方塊取得字串。

int GetText(
    int nIndex,
    LPTSTR lpszBuffer) const;

void GetText(
    int nIndex,
    CString& rString) const;

參數

nIndex
指定要擷取之字串的以零起始的索引。

lpszBuffer
指向接收字串的緩衝區。緩衝區必須有足夠的空間供字串和終止的 Null 字元使用。藉由呼叫 GetTextLen 成員函式，可以事先判斷字串的大小。

rString
對 CString 物件的參考。

傳回值

字串的長度（以位元組為單位），不包括終止的 Null 字元。如果未 nIndex 指定有效的索引，則傳回值為 LB_ERR 。

備註

這個成員函式的第二種 CString 形式會以字串文字填滿物件。

範例

// Dump all of the items in the list box.
CString str, str2;
int n;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   n = m_myListBox.GetTextLen(i);
   m_myListBox.GetText(i, str.GetBuffer(n));
   str.ReleaseBuffer();

   str2.Format(_T("item %d: %s\r\n"), i, str.GetBuffer(0));
   AFXDUMP(str2);
}

`CListBox::GetTextLen`

取得清單方塊專案中字串的長度。

int GetTextLen(int nIndex) const;

參數

nIndex
指定以零起始的字串索引。

傳回值

以字元為單位的字串長度，不包括終止的 Null 字元。如果未 nIndex 指定有效的索引，則傳回值為 LB_ERR 。

範例

請參閱的 CListBox::GetText 範例。

`CListBox::GetTopIndex`

擷取清單方塊中第一個可見專案的以零起始的索引。

int GetTopIndex() const;

傳回值

如果成功，則為清單方塊中第一個可見專案的以零起始的索引， LB_ERR 否則為。

備註

一開始，專案 0 位於清單方塊頂端，但如果清單方塊捲動，另一個專案可能位於頂端。

範例

// Want an item in the bottom half to be the first visible item.
int n = m_myListBox.GetCount() / 2;
if (m_myListBox.GetTopIndex() < n)
{
   m_myListBox.SetTopIndex(n);
   ASSERT(m_myListBox.GetTopIndex() == n);
}

`CListBox::InitStorage`

配置記憶體來儲存清單方塊專案。

int InitStorage(
    int nItems,
    UINT nBytes);

參數

nItems
指定要加入的專案數目。

nBytes
指定要配置給專案字串的記憶體數量，以位元組為單位。

傳回值

如果成功，清單方塊可以在需要記憶體重新配置之前儲存的最大專案數目，否則 LB_ERRSPACE 表示沒有足夠的記憶體可用。

備註

將大量專案新增至 CListBox 之前，請先呼叫此函式。

此函式有助於加速具有大量專案的清單方塊初始化（超過 100 個）。它會預先配置指定的記憶體數量，讓後續 AddString 的、 InsertString 和函 Dir 式需要最短的時間。您可以使用參數的估計值。如果您高估，則會配置一些額外的記憶體;如果您低估，則一般配置會用於超過預先配置數量的專案。

僅限 Windows 95/98：參數 nItems 限制為 16 位值。這表示清單方塊不能包含超過 32,767 個專案。雖然限制專案數目，但清單方塊中專案的總大小只會受限於可用的記憶體。

範例

// Initialize the storage of the list box to be 256 strings with
// about 10 characters per string, performance improvement.
int n = m_myListBox.InitStorage(256, 16 * sizeof(TCHAR));
ASSERT(n != LB_ERRSPACE);

// Add 256 items to the list box.
CString str;
for (int i = 0; i < 256; i++)
{
   str.Format(_T("item string %d"), i);
   m_myListBox.AddString(str);
}

`CListBox::InsertString`

將字串插入清單方塊。

int InsertString(
    int nIndex,
    LPCTSTR lpszItem);

參數

nIndex
指定要插入字串的位置之以零起始的索引。如果此參數為 -1，字串會新增至清單結尾。

lpszItem
指向要插入的 null 結尾字串。

傳回值

已插入字串之位置以零為基底的索引。如果發生錯誤，則傳回值 LB_ERR 是 ;如果空間不足而無法儲存新字串，則傳回值為 LB_ERRSPACE 。

備註

AddString不同于成員函式， InsertString 不會讓具有 LBS_SORT 樣式的清單排序。

範例

// Insert items in between existing items.
CString str;
int n = m_myListBox.GetCount();
for (int i = 0; i < n; i++)
{
   str.Format(_T("item string %c"), (char)('A' + i));
   m_myListBox.InsertString(2 * i, str);
}

`CListBox::ItemFromPoint`

決定最接近中指定的 pt 點的清單方塊專案。

UINT ItemFromPoint(
    CPoint pt,
    BOOL& bOutside) const;

參數

pt
要尋找最接近專案的點，指定相對於清單方塊工作區左上角。

bOutside
BOOL如果 pt 位於清單方塊的工作區之外，則為的變數參考， FALSE 如果 pt 位於清單方塊的工作區內，則 TRUE 為。

傳回值

指向中所 pt 指定點之最接近專案的索引。

備註

您可以使用此函式來判斷滑鼠游標移至哪一個清單方塊專案。

範例

請參閱的 CListBox::SetAnchorIndex 範例。

`CListBox::MeasureItem`

建立具有擁有者繪製樣式的清單方塊時，由架構呼叫。

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

參數

lpMeasureItemStruct
結構的長指標 MEASUREITEMSTRUCT 。

備註

根據預設，此成員函式不會執行任何動作。覆寫此成員函式並 MEASUREITEMSTRUCT 填入結構，以通知 Windows 清單方塊維度。如果清單方塊是以 LBS_OWNERDRAWVARIABLE 樣式建立，架構會針對清單方塊中的每個專案呼叫這個成員函式。否則，這個成員只會呼叫一次。

如需在以成員函 CWnd 式建立之擁有者繪製清單方塊中使用 LBS_OWNERDRAWFIXED 樣式的詳細資訊，請參閱 Technical Note 14 中的討論。 SubclassDlgItem

如需結構的描述， MEASUREITEMSTRUCT 請參閱 CWnd::OnMeasureItem 。

範例

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example measures an item and sets the height of the item to twice the
// vertical extent of its text. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct)
{
   ASSERT(lpMeasureItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText = (LPCTSTR)lpMeasureItemStruct->itemData;
   ASSERT(lpszText != NULL);
   CSize sz;
   CDC *pDC = GetDC();

   sz = pDC->GetTextExtent(lpszText);

   ReleaseDC(pDC);

   lpMeasureItemStruct->itemHeight = 2 * sz.cy;
}

`CListBox::ResetContent`

從清單方塊中移除所有專案。

void ResetContent();

範例

// Delete all the items from the list box.
m_myListBox.ResetContent();
ASSERT(m_myListBox.GetCount() == 0);

`CListBox::SelectString`

搜尋符合指定字串的清單方塊專案，如果找到相符的專案，則會選取該專案。

int SelectString(
    int nStartAfter,
    LPCTSTR lpszItem);

參數

lpszItem
指向包含要搜尋之前置詞的 Null 終止字串。搜尋不區分大小寫，因此此字串可能包含大寫和小寫字母的任何組合。

傳回值

如果搜尋成功，則為選取專案的索引。如果搜尋失敗，則傳回值為 LB_ERR ，且目前的選取範圍不會變更。

備註

如有必要，清單方塊會捲動，以將選取的專案帶入檢視中。

這個成員函式不能與具有 LBS_MULTIPLESEL 樣式的清單方塊搭配使用。

只有當專案的初始字元（從起點開始）符合所 lpszItem 指定的字串中的字元時，才會選取專案。

FindString使用成員函式來尋找字串，而不選取專案。

範例

// The string to match.
LPCTSTR lpszmyString = _T("item 5");

// Select the item that begins with the specified string.
int nIndex = m_myListBox.SelectString(0, lpszmyString);
ASSERT(nIndex != LB_ERR);

`CListBox::SelItemRange`

在多重選取清單方塊中選取多個連續專案。

int SelItemRange(
    BOOL bSelect,
    int nFirstItem,
    int nLastItem);

參數

bSelect
指定如何設定選取範圍。如果 bSelect 為 TRUE ，則會選取並反白顯示字串;如果 FALSE 已移除反白顯示，且不再選取字串。

nFirstItem
指定要設定之第一個專案之以零起始的索引。

nLastItem
指定要設定之最後一個專案之以零起始的索引。

傳回值

LB_ERR 如果發生錯誤，則為。

備註

只搭配多重選取清單方塊使用此成員函式。如果您需要在多重選取清單方塊中只選取一個專案，也就是說，如果 nFirstItem 等於 nLastItem ，請改為呼叫 SetSel 成員函式。

範例

// Select half of the items.
m_myODListBox.SelItemRange(TRUE, 0, m_myODListBox.GetCount() / 2);

`CListBox::SetAnchorIndex`

設定多重選取範圍清單方塊中的錨點，以開始延伸選取範圍。

void SetAnchorIndex(int nIndex);

參數

nIndex
指定清單方塊專案的以零起始的索引，該專案將會是錨點。

備註

在多重選取清單方塊中，錨點專案是連續選取專案區塊中的第一個或最後一個專案。

範例

void CMyODListBox::OnLButtonDown(UINT nFlags, CPoint point)
{
   BOOL bOutside = TRUE;
   UINT uItem = ItemFromPoint(point, bOutside);

   if (!bOutside)
   {
      // Set the anchor to be the middle item.
      SetAnchorIndex(uItem);
      ASSERT((UINT)GetAnchorIndex() == uItem);
   }

   CListBox::OnLButtonDown(nFlags, point);
}

`CListBox::SetCaretIndex`

將焦點矩形設定為位於多重選取清單方塊中指定索引處的專案。

int SetCaretIndex(
    int nIndex,
    BOOL bScroll = TRUE);

參數

nIndex
指定要在清單方塊中接收焦點矩形的專案以零起始的索引。

bScroll
如果此值為 0，則會捲動專案，直到它完全可見為止。如果此值不是 0，則專案會捲動，直到至少部分顯示為止。

傳回值

LB_ERR 如果發生錯誤，則為。

備註

如果看不到專案，則會捲動到檢視中。

範例

// Set the caret to be the middle item.
m_myListBox.SetCaretIndex(m_myListBox.GetCount() / 2);
ASSERT(m_myListBox.GetCaretIndex() == m_myListBox.GetCount() / 2);

`CListBox::SetColumnWidth`

設定多欄清單方塊中所有資料行的寬度，以圖元為單位（以 LBS_MULTICOLUMN 樣式建立）。

void SetColumnWidth(int cxWidth);

參數

cxWidth
以圖元為單位指定所有資料行的寬度。

範例

// Find the pixel width of the largest item.
CString str;
CSize   sz;
int     dx = 0;
CDC* pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
myListBox.ReleaseDC(pDC);

// Set the column width of the first column to be one and 1/3 units
// of the largest string. 
myListBox.SetColumnWidth(dx * 4 / 3);

`CListBox::SetCurSel`

視需要選取字串並將其捲動至檢視。

int SetCurSel(int nSelect);

參數

nSelect
指定要選取之字串的以零起始的索引。如果 nSelect 為 -1，則清單方塊會設定為沒有選取範圍。

傳回值

LB_ERR 如果發生錯誤，則為。

備註

選取新字串時，清單方塊會從先前選取的字串中移除醒目提示。

只搭配單選清單方塊使用此成員函式。

若要在多重選取清單方塊中設定或移除選取範圍，請使用 CListBox::SetSel 。

範例

// Select the last item in the list box.
int nCount = m_myListBox.GetCount();
if (nCount > 0)
   m_myListBox.SetCurSel(nCount - 1);

`CListBox::SetHorizontalExtent`

設定寬度，以圖元為單位，清單方塊可以水準捲動。

void SetHorizontalExtent(int cxExtent);

參數

cxExtent
指定清單方塊可以水準捲動的圖元數目。

備註

如果清單方塊的大小小於此值，水準捲軸就會水準捲動清單方塊中的專案。如果清單方塊大於此值，則會隱藏水準捲軸。

若要回應的 SetHorizontalExtent 呼叫，清單方塊必須已使用 WS_HSCROLL 樣式來定義。

這個成員函式不適用於多欄清單方塊。針對多欄清單方塊，呼叫 SetColumnWidth 成員函式。

範例

// Find the longest string in the list box.
CString str;
CSize sz;
int dx = 0;
TEXTMETRIC tm;
CDC *pDC = m_myListBox.GetDC();
CFont *pFont = m_myListBox.GetFont();

// Select the listbox font, save the old font
CFont *pOldFont = pDC->SelectObject(pFont);
// Get the text metrics for avg char width
pDC->GetTextMetrics(&tm);

for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   // Add the avg width to prevent clipping
   sz.cx += tm.tmAveCharWidth;

   if (sz.cx > dx)
      dx = sz.cx;
}
// Select the old font back into the DC
pDC->SelectObject(pOldFont);
m_myListBox.ReleaseDC(pDC);

// Set the horizontal extent so every character of all strings
// can be scrolled to.
m_myListBox.SetHorizontalExtent(dx);

`CListBox::SetItemData`

設定與清單方塊中指定專案相關聯的值。

int SetItemData(
    int nIndex,
    DWORD_PTR dwItemData);

參數

nIndex
指定專案以零起始的索引。

dwItemData
指定要與專案相關聯的值。

傳回值

LB_ERR 如果發生錯誤，則為。

範例

// Set the data of each item to be equal to its index.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.SetItemData(i, i);
}

`CListBox::SetItemDataPtr`

將清單方塊中與指定專案相關聯的 32 位值設定為指定的指標（ void* 。

int SetItemDataPtr(
    int nIndex,
    void* pData);

參數

nIndex
指定專案以零起始的索引。

pData
指定要與專案相關聯的指標。

傳回值

LB_ERR 如果發生錯誤，則為。

備註

即使清單方塊內的專案相對位置在新增或移除專案時，此指標仍對清單方塊的存留期有效。因此，方塊內的專案索引可能會變更，但指標仍會保持可靠。

範例

// Set the data pointer of each item to be NULL.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.SetItemDataPtr(i, NULL);
}

`CListBox::SetItemHeight`

設定清單方塊中專案的高度。

int SetItemHeight(
    int nIndex,
    UINT cyItemHeight);

參數

nIndex
指定清單方塊中專案以零起始的索引。只有當清單方塊具有 LBS_OWNERDRAWVARIABLE 樣式時，才會使用此參數，否則應該設定為 0。

cyItemHeight
指定專案的高度，以圖元為單位。

傳回值

LB_ERR 如果索引或高度無效，則為。

備註

如果清單方塊具有 LBS_OWNERDRAWVARIABLE 樣式，此函式會設定所 nIndex 指定專案的高度。否則，此函式會設定清單方塊中所有專案的高度。

範例

// Set the height of every item to be the
// vertical size of the item's text extent.
CString str;
CSize sz;
CDC *pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   myListBox.SetItemHeight(i, sz.cy);
}
myListBox.ReleaseDC(pDC);

`CListBox::SetLocale`

設定此清單方塊的地區設定識別碼。

LCID SetLocale(LCID nNewLocale);

參數

nNewLocale
要為清單方塊設定的新地區設定識別碼（LCID）值。

傳回值

此清單方塊的前一個地區設定識別碼（LCID）值。

備註

如果未 SetLocale 呼叫，則會從系統取得預設地區設定。您可以使用主控台的區域（或國際）應用程式來修改此系統預設地區設定。

範例

// My LCID to use.
LCID mylcid = MAKELCID(MAKELANGID(LANG_SPANISH, SUBLANG_SPANISH_MEXICAN),
                       SORT_DEFAULT);

// Force the list box to use my locale.
m_myListBox.SetLocale(mylcid);
ASSERT(m_myListBox.GetLocale() == mylcid);

`CListBox::SetSel`

在多重選取清單方塊中選取字串。

int SetSel(
    int nIndex,
    BOOL bSelect = TRUE);

參數

nIndex
包含要設定之字串的以零起始的索引。如果為 -1，則會根據的值，在所有字串中新增或移除選取範圍 bSelect 。

bSelect
指定如何設定選取範圍。如果 bSelect 為 TRUE ，則會選取並反白顯示字串;如果 FALSE 已移除反白顯示，且不再選取字串。預設會選取並反白顯示指定的字串。

傳回值

LB_ERR 如果發生錯誤，則為。

備註

只搭配多重選取清單方塊使用此成員函式。

若要從單一選取清單方塊中選取專案，請使用 CListBox::SetCurSel 。

範例

// Select all of the items with an even index and
// deselect all others.
for (int i = 0; i < m_myODListBox.GetCount(); i++)
{
   m_myODListBox.SetSel(i, ((i % 2) == 0));
}

`CListBox::SetTabStops`

設定清單方塊中的定位停駐點位置。

void SetTabStops();
BOOL SetTabStops(const int& cxEachStop);

BOOL SetTabStops(
    int nTabStops,
    LPINT rgTabStops);

參數

cxEachStop
定位點會在每個 cxEachStop 對話方塊單位設定。如需對話方塊單元的描述，請參閱 rgTabStops 。

nTabStops
指定要在清單方塊中擁有的定位停駐點數目。

rgTabStops
指向包含對話方塊單位中定位停駐點位置之整數陣列的第一個成員。對話方塊單位是水準或垂直距離。一個水準對話單位等於目前對話基底寬度單位的四分之一，而一個垂直對話單位等於目前對話基底高度單位的一八分之一。對話方塊基本單位是根據目前系統字型的高度和寬度計算。 Windows 函 GetDialogBaseUnits 式會以圖元為單位傳回目前的對話方塊基底單位。定位停駐點必須依遞增順序排序;不允許返回索引標籤。

傳回值

如果已設定所有索引標籤，則為非零;否則為 0。

備註

若要將定位停駐點設定為預設大小為 2 個對話方塊單位，請呼叫這個成員函式的無參數版本。若要將定位停駐點設定為 2 以外的大小，請使用 cxEachStop 引數呼叫版本。

若要將定位停駐點設定為大小陣列，請使用版本搭配 rgTabStops 和 nTabStops 引數。中每個值 rgTabStops 都會設定制表位，最多為所 nTabStops 指定的數位。

若要回應成員函式的呼叫 SetTabStops ，清單方塊必須使用樣式建立 LBS_USETABSTOPS 。

範例

// Find the pixel width of the largest first substring.
CString str;
CSize sz;
int nIndex, dx = 0;
CDC *pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);

   if ((nIndex = str.Find('\t')) != -1)
      str = str.Right(nIndex);

   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
myListBox.ReleaseDC(pDC);

// Set tab stops at every one and 1/3 units
// of the largest string.
// NOTE: Convert pixels to dialog units.
myListBox.SetTabStops((dx * 4 / 3 * 4) / LOWORD(::GetDialogBaseUnits()));

`CListBox::SetTopIndex`

確保特定清單方塊專案可見。

int SetTopIndex(int nIndex);

參數

nIndex
指定清單方塊專案以零起始的索引。

傳回值

如果成功，則為零，如果 LB_ERR 發生錯誤則為零。

備註

系統會捲動清單方塊，直到指定的專案 nIndex 出現在清單方塊頂端，或達到最大捲動範圍為止。

範例

// Set the first visible item in the list box to be the middle item
m_myListBox.SetTopIndex(m_myListBox.GetCount() / 2);

`CListBox::VKeyToItem`

當清單方塊的父視窗收到 WM_VKEYTOITEM 清單方塊的訊息時，由架構呼叫。

virtual int VKeyToItem(
    UINT nKey,
    UINT nIndex);

參數

nKey
使用者按下之按鍵的虛擬按鍵碼。如需標準虛擬金鑰碼的清單，請參閱 Winuser.h

nIndex
清單方塊插入號的目前位置。

傳回值

會傳回 - 2 表示沒有進一步的動作、-1 表示預設動作，或指定清單方塊專案的索引，以針對擊鍵執行預設動作。

備註

當 WM_VKEYTOITEM 清單方塊收到 WM_KEYDOWN 訊息時，訊息會由清單方塊傳送，但前提是清單方塊符合下列兩項：

LBS_WANTKEYBOARDINPUT具有樣式集。
至少有一個專案。

您不應該自行呼叫此函式。覆寫此函式以提供您自己的鍵盤訊息自訂處理。

您必須傳回值，以告知架構您的覆寫所執行的動作。傳回值 - 2 表示應用程式會處理選取專案的所有層面，而且清單方塊不需要採取任何進一步的動作。傳回 - 2 之前，您可以設定選取範圍或移動插入號或兩者。若要設定選取範圍，請使用 SetCurSel 或 SetSel 。若要移動插入號，請使用 SetCaretIndex 。

傳回值 - 1 表示清單方塊應該執行預設動作以回應擊鍵。預設實作會傳回 - 1。

傳回值為 0 或更新的值會指定清單方塊中專案的索引，並指出清單方塊應該對指定專案執行按鍵的預設動作。

範例

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example moves the caret down one item on the down key and up one item
// on the up key. The list box control was created with the following
// code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::VKeyToItem(UINT nKey, UINT nIndex)
{
   // On key up, move the caret up one item.
   if ((nKey == VK_UP) && (nIndex > 0))
   {
      SetCaretIndex(nIndex - 1);
   }
   // On key down, move the caret down one item.
   else if ((nKey == VK_DOWN) && (nIndex < (UINT)GetCount()))
   {
      SetCaretIndex(nIndex + 1);
   }

   // Do not perform any default processing.
   return -2;
}

另請參閱

MFC 範例 CTRLTEST
CWnd 類
 階層架構圖表
 CWnd 類
 CButton 類
 CComboBox 類
 CEdit 類
 CScrollBar 類
 CStatic 類

共用方式為

CListBox 類別

語法

成員

公用建構函式

公用方法

備註

繼承階層架構

需求

CListBox::AddString

參數

傳回值

備註

範例

CListBox::CharToItem

參數

傳回值

備註

範例

CListBox::CListBox

備註

範例

CListBox::CompareItem

參數

傳回值

備註

範例

CListBox::Create

參數

傳回值

備註

範例

CListBox::DeleteItem

參數

備註

範例

CListBox::DeleteString

參數

傳回值

備註

範例

CListBox::Dir

參數

傳回值

範例

CListBox::DrawItem

參數

備註

範例

CListBox::FindString

參數

傳回值

備註

範例

CListBox::FindStringExact

參數

傳回值

備註

範例

CListBox::GetAnchorIndex

傳回值

備註

範例

CListBox::GetCaretIndex

傳回值

備註

範例

CListBox::GetCount

傳回值

備註

範例

CListBox::GetCurSel

傳回值

備註

範例

CListBox::GetHorizontalExtent

傳回值

備註

範例

CListBox::GetItemData

`CListBox` 類別

`CListBox::AddString`

`CListBox::CharToItem`

`CListBox::CListBox`

`CListBox::CompareItem`

`CListBox::Create`

`CListBox::DeleteItem`

`CListBox::DeleteString`

`CListBox::Dir`

`CListBox::DrawItem`

`CListBox::FindString`

`CListBox::FindStringExact`

`CListBox::GetAnchorIndex`

`CListBox::GetCaretIndex`

`CListBox::GetCount`

`CListBox::GetCurSel`

`CListBox::GetHorizontalExtent`

`CListBox::GetItemData`

`CListBox::GetItemDataPtr`

`CListBox::GetItemHeight`

`CListBox::GetItemRect`

`CListBox::GetListBoxInfo`

`CListBox::GetLocale`

`CListBox::GetSel`

`CListBox::GetSelCount`

`CListBox::GetSelItems`

`CListBox::GetText`

`CListBox::GetTextLen`

`CListBox::GetTopIndex`

`CListBox::InitStorage`

`CListBox::InsertString`

`CListBox::ItemFromPoint`

`CListBox::MeasureItem`

`CListBox::ResetContent`