Класс `CListBox`

Статья
10/12/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`	Переопределите, чтобы обеспечить настраиваемую `WM_KEYDOWN` обработку списков с набором стилей `LBS_WANTKEYBOARDINPUT` .

Замечания

В поле списка отображается список элементов, таких как имена файлов, которые пользователь может просматривать и выбирать.

В поле с одним выбором пользователь может выбрать только один элемент. В списке с несколькими выборами можно выбрать диапазон элементов. Когда пользователь выбирает элемент, он выделен, а поле списка отправляет уведомление в родительское окно.

Вы можете создать поле списка из шаблона диалогового окна или непосредственно в коде. Чтобы создать его непосредственно, создайте CListBox объект, а затем вызовите Create функцию-член, чтобы создать элемент управления "Список Windows" и присоединить его к объекту CListBox . Чтобы использовать поле списка в шаблоне диалогового окна, объявите переменную списка в классе диалогового окна, а затем используйте DDX_Control функцию класса DoDataExchange диалогового окна для подключения переменной-члена к элементу управления. (это делается автоматически при добавлении переменной элемента управления в класс диалогового окна.)

Построение может быть одношаговным процессом в классе, производным от CListBox. Напишите конструктор для производного класса и вызов Create из конструктора.

Если вы хотите обрабатывать сообщения уведомлений Windows, отправляемые полем списка его родительскому элементу (как правило, классу, производным от CDialog), добавьте запись карты сообщений и функцию-обработчик сообщения в родительский класс для каждого сообщения.

Каждая запись карты сообщений принимает следующую форму:

ON_Notification( id, memberFxn )

где id указывает идентификатор дочернего окна элемента управления list-box, отправляющий уведомление, и 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_WANTKEYBOARDINPUTWM_KEYDOWN получает сообщение.

При создании CListBox объекта в диалоговом окне (с помощью ресурса диалогового окна) CListBox объект автоматически уничтожается, когда пользователь закрывает диалоговое окно.

При создании CListBox объекта в окне может потребоваться уничтожить CListBox объект. При создании CListBox объекта в стеке он автоматически уничтожается. Если вы создаете CListBox объект в куче с помощью new функции, необходимо вызвать 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_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.

См 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
Указывает идентификатор элемента управления списка.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Вы создаете CListBox объект на двух шагах. Сначала вызовите конструктор, а затем вызовите Create, который инициализирует поле списка Windows и присоединяет его к объекту CListBox .

При Create выполнении Windows отправляет WM_NCCREATEсообщения WM_CREATEWM_NCCALCSIZEи WM_GETMINMAXINFO сообщения в элемент управления list-box.

Эти сообщения обрабатываются по умолчанию функциями OnNcCreate, OnCreateOnNcCalcSizeи OnGetMinMaxInfo членами в базовом CWnd классе. Чтобы расширить обработку сообщений по умолчанию, наследуйте класс, CListBoxдобавьте карту сообщений в новый класс и переопределите предыдущие функции-обработчика сообщений. Переопределите OnCreate, например, чтобы выполнить необходимую инициализацию для нового класса.

Примените следующие стили окон к элементу управления list-box.

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 , содержащую сведения об удаленном элементе.

Замечания

Реализация по умолчанию этой функции не выполняет никаких действий. Переопределите эту функцию, чтобы повторно создать поле списка для рисования владельца по мере необходимости.

См 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
Указывает отсчитываемый от нуля индекс строки для удаления.

Возвращаемое значение

Количество строк, оставшихся в списке. Возвращаемое значение имеет LB_ERR значение, если nIndex указывает индекс, превышающий число элементов в списке.

Замечания

Все следующие элементы 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
Может быть любое сочетание значений enum , описанных в CFile::GetStatus, или любое сочетание следующих значений:

Значение	Значение
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 указатель на структуру, содержащую сведения о типе документа, необходимом.

Замечания

itemStateDRAWITEMSTRUCT Элементы itemAction структуры определяют выполняемую операцию рисования.

По умолчанию эта функция-член ничего не делает. Переопределите эту функцию-член, чтобы реализовать рисование для объекта owner-draw CListBox . Приложение должно восстановить все объекты интерфейса графического устройства (GDI), выбранные для контекста отображения, предоставленного lpDrawItemStruct перед завершением этой функции-члена.

См 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 если поиск был неудачным.

Замечания

Если поле списка было создано с стилем рисования владельца, FindStringExact но без LBS_HASSTRINGS стиля, функция-член пытается сопоставить значение doubleword со значением.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`

Извлекает предоставленное приложением двойное слово, связанное с указанным элементом списка.

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 структуру , которая получает координаты клиента list-box элемента.

Возвращаемое значение

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 сообщения, как описано в пакете SDK для Windows.

`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). Он предварительно выделяет указанный объем памяти, чтобы последующие AddStringInsertStringDir функции и функции занимают самое короткое время. Вы можете использовать оценки для параметров. Если вы переоцените, выделена дополнительная память; Если вы недооцениваете, обычное выделение используется для элементов, превышающих предварительно выделенный объем.

Только 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 переменную, которая будет задана TRUE , если pt находится вне клиентской области списка, FALSE если pt находится внутри клиентской области списка.

Возвращаемое значение

Индекс ближайшего элемента к точке, указанной в pt.

Замечания

Эту функцию можно использовать для определения элемента списка, над которым перемещается курсор мыши.

Пример

Пример см. в примере CListBox::SetAnchorIndex.

`CListBox::MeasureItem`

Вызывается платформой при создании поля списка с стилем рисования владельца.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Параметры

lpMeasureItemStruct
Длинный указатель на структуру MEASUREITEMSTRUCT .

Замечания

По умолчанию эта функция-член ничего не делает. Переопределите эту функцию-член и заполните структуру MEASUREITEMSTRUCT , чтобы сообщить Windows о измерениях списка. Если поле списка создается с LBS_OWNERDRAWVARIABLE помощью стиля, платформа вызывает эту функцию-член для каждого элемента в поле списка. В противном случае этот элемент вызывается только один раз.

Дополнительные сведения об использовании LBS_OWNERDRAWFIXED стиля в поле списка "Рисование владельца", созданном с SubclassDlgItem помощью функции-члена CWnd, см. в обсуждении в Техническом примечание 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);

Параметры

Возвращаемое значение

Индекс выбранного элемента, если поиск выполнен успешно. Если поиск был неудачным, возвращается 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
Указывает, как задать выделение. Если это TRUEтак, строка выбрана и выделена; если bSelectFALSEвыделение удаляется, а строка больше не выбрана.

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);

Параметры

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
Указывает, как задать выделение. Если это TRUEтак, строка выбрана и выделена; если bSelectFALSEвыделение удаляется, а строка больше не выбрана. Указанная строка выбрана и выделена по умолчанию.

Возвращаемое значение

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_VKEYTOITEM отправляется полем списка при получении WM_KEYDOWN сообщения, но только в том случае, если поле списка соответствует обоим из следующих:

Имеет набор стилей LBS_WANTKEYBOARDINPUT .
Имеет хотя бы один элемент.

Необходимо вернуть значение, чтобы сообщить платформе, какое действие выполняется переопределение. Возвращаемое значение - 2 указывает, что приложение обрабатывает все аспекты выбора элемента и не требует дальнейших действий в поле списка. Перед возвратом - 2 можно задать выделение или переместить курсор или оба. Чтобы задать выбор, используйте SetCurSel или SetSel. Чтобы переместить курсор, используйте SetCaretIndex.

Возвращаемое значение - 1 указывает, что поле списка должно выполнять действие по умолчанию в ответ на нажатие клавиш. Реализация по умолчанию возвращает значение – 1.

Пример

// 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;
}

См. также

Пример CTRLTEST MFC
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`

`CListBox::SelectString`