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

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

  • Статья

Задает или получает атрибуты элемента представления списка. Эта структура была обновлена для поддержки нового значения маски (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 является указателем на буфер, который получает текст элемента. Обратите внимание, что хотя элемент управления list-view позволяет хранить строку любой длины в виде текста элемента, отображаются только первые 259 TCHAR.

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

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

cchTextMax

Тип: int

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

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

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

iImage

Тип: int

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

lParam

Тип: LPARAM

Значение, относящееся к элементу. Если вы используете сообщение LVM_SORTITEMS , элемент управления list-view передает это значение в определяемую приложением функцию сравнения. Вы также можете использовать сообщение 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 при изменении элемента списка.

Пример кода см. в разделе Использование элементов управления List-View.

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

Примечание

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

Требования

   
Минимальная версия клиента Windows Vista [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Верхняя часть commctrl.h