`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 对象。若要在对话框模板中使用列表框，请在对话框类中声明一个列表框变量，然后在对话框类的 DoDataExchange 函数中使用 DDX_Control 将成员变量连接到控件。（将控件变量添加到对话框类后，系统会自动完成此操作。）

构造可以是派生自 CListBox 的类中的单步过程。为派生类编写构造函数并从构造函数中调用 Create。

如果想处理由列表框发送到其父级（通常是从 CDialog 派生的类）的 Windows 通知消息，请将消息映射条目和消息处理程序成员函数添加到每个消息的父类。

每个消息映射条目采用以下格式：

ON_Notification( id, memberFxn )

其中 id 指定发送通知的列表框控件的子窗口 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 对象，则会自动销毁该对象。如果使用 new 函数在堆上创建 CListBox 对象，则必须在该对象上调用 delete 以在用户关闭父窗口时将其销毁。

如果在 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_CHAR 消息时发送 WM_CHARTOITEM 消息，但前提是列表框满足以下所有条件：

是所有者描述列表框。
没有 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 之后。

请参阅 CWnd::OnCompareItem 查看有关 COMPAREITEMSTRUCT 结构的说明。

注解

默认情况下，此成员函数不执行任何操作。如果使用 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
指定列表框的控件 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

请分两步构造 CListBox 对象。首先，调用构造函数，然后调用 Create，这将初始化 Windows 列表框并将其附加到 CListBox 对象。

Create 执行时，Windows 会将 WM_NCCREATE、WM_CREATE、WM_NCCALCSIZE 和 WM_GETMINMAXINFO 消息发送到列表框控件。

默认情况下，这些消息由 CWnd 基类中的 OnNcCreate、OnCreate、OnNcCalcSize 和 OnGetMinMaxInfo 成员函数处理。若要扩展默认消息处理，请从 CListBox 派生一个类，将消息映射添加到新类，并替代前面的消息处理程序成员函数。例如，重写 OnCreate 以为新类执行所需的初始化。

将以下窗口样式应用于列表框控件。

WS_CHILD：始终
WS_VISIBLE：通常
WS_DISABLED 很少
WS_VSCROLL 添加垂直滚动条
WS_HSCROLL 添加水平滚动条
WS_GROUP 对控件进行分组
WS_TABSTOP 允许按 Tab 键导航到此控件

示例

// 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 结构的长指针。

备注

此函数的默认实现不执行任何操作。重写此函数以根据需要重绘所有者描述列表框。

请参阅 CWnd::OnDeleteItem 查看有关 DELETEITEMSTRUCT 结构的说明。

示例

// 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
指定要删除的字符串的从零开始的索引。

返回值

列表中剩余的字符串计数。如果 nIndex 指定的索引大于列表中的项数，则返回值为 LB_ERR。

备注

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	Exclusive 标志。如果设置了独占标志，则仅列出指定类型的文件。否则，除了“普通”文件之外，还会列出指定类型的文件。

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 结构的长指针，其中包含有关所需绘图类型的信息。

备注

DRAWITEMSTRUCT 结构的 itemAction 和 itemState 成员定义要执行的绘图操作。

默认情况下，此成员函数不执行任何操作。替代此成员函数以实现所有者绘制 CListBox 对象的绘制。在此成员函数终止之前，应用程序应还原为 lpDrawItemStruct 中提供的显示上下文选择的所有图形设备接口 (GDI) 对象。

请参阅 CWnd::OnDrawItem 查看有关 DRAWITEMSTRUCT 结构的说明。

示例

// 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。

备注

返回的计数比最后一项的索引值大 1（索引从零开始）。

示例

// 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`

检索与指定列表框项关联的应用程序提供的双字值。

DWORD_PTR GetItemData(int nIndex) const;

参数

nIndex
指定列表框中项的从零开始的索引。

返回值

与项关联的值，如果发生错误，则为 LB_ERR。

备注

双字值是 SetItemData 调用的 dwItemData 参数。

示例

// 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
指向接收字符串的缓冲区。缓冲区必须有足够的空间来存储字符串和终止空字符。可以通过调用 GetTextLen 成员函数提前确定字符串的大小。

rString
对 CString 对象的引用。

返回值

字符串的长度（以字节为单位），不包括终止空字符。如果 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
指定字符串的从零开始的索引。

返回值

字符串的长度（以字符为单位），不包括终止空字符。如果 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 位于列表框的工作区之外，则该变量将设置为 TRUE，如果 pt 位于列表框的工作区之内，则该变量将设置为 FALSE。

返回值

离 pt 中指定的点最近的项的索引。

备注

可以使用此函数来确定鼠标光标移动到哪个列表框项。

示例

请参阅 CListBox::SetAnchorIndex 的示例。

`CListBox::MeasureItem`

在创建具有所有者绘制样式的列表框时由框架调用。

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

参数

lpMeasureItemStruct
指向 MEASUREITEMSTRUCT 结构的长指针。

备注

默认情况下，此成员函数不执行任何操作。重写此成员函数并填写 MEASUREITEMSTRUCT 结构以通知 Windows 列表框尺寸。如果列表框是使用 LBS_OWNERDRAWVARIABLE 样式创建的，则框架会为列表框中的每个项调用此成员函数。否则，此成员函数仅调用一次。

有关在使用 CWnd 的 SubclassDlgItem 成员函数创建的所有者描述列表框中使用 LBS_OWNERDRAWFIXED 样式的详细信息，请参阅技术说明 14 中的讨论。

请参阅 CWnd::OnMeasureItem 查看有关 MEASUREITEMSTRUCT 结构的说明。

示例

// 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
指向包含对话框单位中的制表位位置的整数数组的第一个成员。对话框单位是一个水平或垂直的距离。一个水平对话框单位等于当前对话框基本宽度单位的四分之一，一个垂直对话框单位等于当前对话框基本高度单位的八分之一。对话框基本单位根据当前系统字体的高度和宽度计算。 GetDialogBaseUnits Windows 函数以像素为单位返回当前对话框基本单位。制表位必须按升序排列；不允许使用后退选项卡。

返回值

如果设置了所有选项卡，则非零；否则为 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_KEYDOWN 消息时发送 WM_VKEYTOITEM 消息，但前提是列表框同时满足以下两个条件：

具有 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`