`CListBox` 類別

文章
07/05/2024

提供 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`