Структура LVITEMA (commctrl.h)

Статья
08/22/2023

Задает или получает атрибуты элемента представления списка. Эта структура была обновлена для поддержки нового значения маски (LVIF_INDENT), которое включает отступ элементов. Эта структура заменяет структуру LV_ITEM.

Синтаксис

typedef struct tagLVITEMA {
  UINT   mask;
  int    iItem;
  int    iSubItem;
  UINT   state;
  UINT   stateMask;
  LPSTR  pszText;
  int    cchTextMax;
  int    iImage;
  LPARAM lParam;
  int    iIndent;
  int    iGroupId;
  UINT   cColumns;
  PUINT  puColumns;
  int    *piColFmt;
  int    iGroup;
} LVITEMA, *LPLVITEMA;

Члены

mask

Тип: UINT

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

Ценность	Значение
LVIF_COLFMT	Windows Vista и более поздние версии. Элемент piColFmt является допустимым или должен быть задан. Если этот флаг используется, cColumns является допустимым или должен быть задан.
LVIF_COLUMNS	Элемент cColumns является допустимым или должен быть задан.
LVIF_DI_SETITEM	Операционная система должна хранить запрошенные сведения о элементе списка и не запрашивать его снова. Этот флаг используется только с кодом уведомления LVN_GETDISPINFO.
LVIF_GROUPID	Элемент iGroupId является допустимым или должен быть задан. Если этот флаг не задан при отправке сообщения LVM_INSERTITEM, предполагается, что значение iGroupId будет I_GROUPIDCALLBACK.
LVIF_IMAGE	Элемент iImage является допустимым или должен быть задан.
LVIF_INDENT	элемент iIndent является допустимым или должен быть задан.
LVIF_NORECOMPUTE	Элемент управления не создаст LVN_GETDISPINFO для получения текстовых сведений, если он получает LVM_GETITEM сообщение. Вместо этого элемент pszText будет содержать LPSTR_TEXTCALLBACK.
LVIF_PARAM	lParam является допустимым или должен быть задан.
LVIF_STATE	Элемент состояния является допустимым или должен быть задан.
LVIF_TEXT	Элемент pszText является допустимым или должен быть задан.

iItem

Тип: int

Отсчитываемый от нуля индекс элемента, к которому относится эта структура.

iSubItem

Тип: int

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

state

Тип: UINT

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

Биты от 0 до 7 этого элемента содержат флаги состояния элемента. Это может быть одно или несколько значений состояния элемента .

Биты от 8 до 11 этого элемента указывают индекс одноуровневого наложения изображения. Как полный список изображений значков, так и список небольших значков могут содержать изображения наложения. Изображение наложения наложено на изображение значка элемента. Если эти биты равны нулю, элемент не имеет изображения наложения. Чтобы изолировать эти биты, используйте маску LVIS_OVERLAYMASK. Чтобы задать индекс изображения наложения в этом элементе, следует использовать макрос INDEXTOOVERLAYMASK. Изображения списка изображений задаются с помощью функции ImageList_SetOverlayImage.

Биты от 12 до 15 этого члена указывают индекс образа состояния. Изображение состояния отображается рядом со значком элемента, чтобы указать определенное приложением состояние. Если эти биты равны нулю, элемент не имеет образа состояния. Чтобы изолировать эти биты, используйте маску LVIS_STATEIMAGEMASK. Чтобы задать индекс изображения состояния, используйте макрос INDEXTOSTATEIMAGEMASK. Индекс изображения состояния указывает индекс изображения в списке изображений состояния, который должен быть нарисован. Список образов состояния указывается с сообщением LVM_SETIMAGELIST.

stateMask

Тип: UINT

Значение, указывающее, какие биты состояния член будут извлечены или изменены. Например, установка этого элемента на LVIS_SELECTED приведет к извлечению только состояния выбора элемента.

Этот элемент позволяет изменять одно или несколько состояний элемента, не получая сначала все состояния элемента. Например, установка этого элемента на LVIS_SELECTED и состояние равно нулю приведет к очистке состояния выбора элемента, но ни одно из других состояний не будет затронуты.

Чтобы получить или изменить все состояния, задайте для этого элемента значение (UINT)-1.

Макрос можно использовать ListView_SetItemState как для задания, так и для очистки битов.

pszText

Тип: LPTSTR

Если структура указывает атрибуты элемента, pszText является указателем на строку, завершающую значение NULL, содержащую текст элемента. При реагировании на уведомление LVN_GETDISPINFO убедитесь, что этот указатель остается действительным до момента получения следующего уведомления.

Если структура получает атрибуты элемента, pszText является указателем на буфер, который получает текст элемента. Обратите внимание, что хотя элемент управления представлением списка позволяет хранить любую строку длины в виде текста элемента, отображаются только первые 259 TCHAR.

Если значение pszText LPSTR_TEXTCALLBACK, элемент является элементом обратного вызова. Если текст обратного вызова изменяется, необходимо явно задать pszText LPSTR_TEXTCALLBACK и уведомить элемент управления представлением списка об изменении, отправив LVM_SETITEM или сообщение LVM_SETITEMTEXT.

Не устанавливайте pszText LPSTR_TEXTCALLBACK, если элемент управления представлением списка имеет стиль LVS_SORTASCENDING или LVS_SORTDESCENDING.

cchTextMax

Тип: int

Число TCHAR в буфере, на которое указывает pszText, включая завершение NULL.

Этот элемент используется только в том случае, если структура получает атрибуты элемента. При указании атрибутов элемента структура игнорируется. Например, cchTextMax игнорируется во время LVM_SETITEM и LVM_INSERTITEM. Он доступен только для чтения во время LVN_GETDISPINFO и других уведомлений LVN_.

примечание никогда не копируйте больше cchTextMaxTCHAR, где cchTextMax включает NULL— в pszText во время уведомления LVN_, в противном случае программа может завершиться ошибкой.

iImage

Тип: int

Индекс значка элемента в списке изображений элемента. Это относится как к большому, так и к небольшому списку изображений. Если этот элемент является значением I_IMAGECALLBACK, родительское окно отвечает за хранение индекса. В этом случае элемент управления представлением списка отправляет родительский код уведомления LVN_GETDISPINFO, чтобы получить индекс, когда он должен отобразить изображение.

lParam

Тип: LPARAM

Значение, относящееся к элементу. Если вы используете сообщение LVM_SORTITEMS, элемент управления представлением списка передает это значение в определяемую приложением функцию сравнения. Можно также использовать сообщение LVM_FINDITEM для поиска элемента управления представлением списка для элемента с указанным значением lParam.

iIndent

Тип: int

версии 4.70. Число ширин изображения для отступа элемента. Одно отступ равно ширине изображения элемента. Таким образом, значение 1 отступов отступов по ширине одного изображения, значения 2 отступа двумя изображениями и т. д. Обратите внимание, что это поле поддерживается только для элементов. Попытка задать отступ подсети приведет к сбою вызывающей функции.

iGroupId

Тип: int

версии 6.0 идентификатор группы, к которой принадлежит элемент, или одно из следующих значений.

Ценность	Значение
I_GROUPIDCALLBACK	Элемент управления listview отправляет родительский код уведомления LVN_GETDISPINFO для получения индекса группы.
I_GROUPIDNONE	Элемент не принадлежит группе.

cColumns

Тип: UINT

версии 6.0 число столбцов данных (подсемей), отображаемых для этого элемента в представлении плитки. Максимальное значение — 20. Если это значение I_COLUMNSCALLBACK, размер массива столбцов и самого массива (puColumns) получаются путем отправки уведомления LVN_GETDISPINFO.

puColumns

Тип: PUINT

версии 6.0 Указатель на массив индексов столбцов, указывающий, какие столбцы отображаются для этого элемента, а также порядок этих столбцов.

piColFmt

Тип: int*

Windows Vista: Не реализовано. Windows 7 и более поздних версий: указатель на массив следующих флагов (отдельно или в сочетании), указывающий формат каждого дочернего элемента в расширенном представлении плиток.

Ценность	Значение
LVCFMT_LINE_BREAK	Принудительно помещать столбец в верхнюю часть следующего списка столбцов.
LVCFMT_FILL	Заполняет оставшуюся часть области плитки. Возможно, у вас есть название.
LVCFMT_WRAP	Позволяет столбцу упаковывать в оставшееся пространство в списке столбцов.
LVCFMT_NO_TITLE	Удаляет заголовок из подсети.
LVCFMT_TILE_PLACEMENTMASK	Эквивалентно сочетанию LVCFMT_LINE_BREAK и LVCFMT_FILL.

iGroup

Тип: int

Windows Vista: групповый индекс элемента. Допустимо только для данных владельца или обратного вызова (один элемент в нескольких группах).

Замечания

Структура LVITEM используется с несколькими сообщениями, включая LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEMи LVM_DELETEITEM.

В представлении плитки имя элемента отображается справа от значка. Можно указать дополнительные вложенные элементы (соответствующие столбцам в представлении сведений), которые будут отображаться в строках под именем элемента. Массив puColumns содержит индексы дочерних объектов, отображаемых. Индексы должны быть больше 0, так как подсеть 0, имя элемента уже отображается. Сведения о столбцах также можно задать в структуре LVTILEINFO при изменении элемента списка.

Пример кода см. в разделе Using List-View Controls.

примечание Comctl32.dll версии 6 не распространяется, но оно включается в Windows или более поздней версии. Чтобы использовать Comctl32.dll версии 6, укажите его в манифесте. Дополнительные сведения о манифестах см. в разделе Включениевизуальных стилей.

Заметка

Заголовок commctrl.h определяет LVITEM как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
заголовка	commctrl.h

Поделиться через

Структура LVITEMA (commctrl.h)

Синтаксис

Члены

Замечания

Требования

Обратная связь

Дополнительные ресурсы