Estructura LVITEM

Definición

typedef struct tagLVITEM {
  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;
} LVITEM, *PLVITEM;

Especifica o recibe los atributos de un ítem de un list-view. Esta estructura ha sido actualizada para soportar un nuevo valor de máscara (LVIF_INDENT) que permite la sangrar los ítems. Esta estructura sustituye a la estructura LV_ITEM.

Descripción

mask

Conjunto de banderas que especifican qué miembros de esta estructura contienen datos a asignar o qué miembros deben ser recuperados. Este miembro puede tener una o más de los siguientes banderas asignadas:

Valores	Singificado
LVIF_COLFMT	Windows Vista y posteriores. El miembro piColFmt es válido o debe ser obtenido. Si se usa esta bandera, el miembro cColumns también es válido o debe ser recuperado.
LVIF_COLUMNS	El miembro cColumns es válido o debe ser recuperado.
LVIF_DI_SETITEM	El sistema operativo debe almacenar la información del ítem suministrada y no volver a solicitarla. Esta bandera solo se usa con el código de notificación LVN_GETDISPINFO.
LVIF_GROUPID	El miembro iGroupId es válido o debe ser recuperado. Si esta bandera no está asignada cuando un mensaje LVM_INSERTITEM es enviado, se asume el valor I_GROUPIDCALLBACK para iGroupId.
LVIF_IMAGE	El miembro iImage es válido o debe ser recuperado.
LVIF_INDENT	El miembro iIndent es válido o debe ser recuperado.
LVIF_NORECOMPUTE	El control no generará códigos de notificación LVN_GETDISPINFO para recuperar información de texto si recibe un mensaje LVM_GETITEM. En lugar de eso, el moembro pszText tomará el valor LPSTR_TEXTCALLBACK.
LVIF_PARAM	El miembro lParam es válido o debe ser recuperado.
LVIF_STATE	El miembro state es válido o debe ser recuperado.
LVIF_TEXT	El miembro pszText es válido o debe ser recuperado.

iItem

Índice basado en cero del ítem al que se refiere esta estructura.

iSubItem

Índice basado en uno del subítem al que se refiere esta estructura, o cero si la estructura se refiere a un ítem y no a un subítem.

state

Indica el estado el ítem, la imagen de estado y la imagen superpuesta. El miembro stateMask indica los bits válidos de este miembro.

Los bits 0 a 7 de este miembro contienen las banderas de estado del ítem. Puede ser uno o más de los valores de estado de ítem.

Los bits 8 a 11 de este miembro espefican el índice basado en uno de la imagen superpuesta. Tanto la lista de imágenes de iconos de tamaño completo como la de iconos pequeños pueden tener imágenes superpuestas. La imagen superpuesta se muestra sobre la imagen del icono del ítem. Si estos bits son cero, el ítem no tedrá imagen superpuesta. Para aislar estos bits, usar la máscara LVIS_OVERLAYMASK. Para asignar el índice de la imagen superpuesta en este miembro, se debe usar la macro INDEXTOOVERLAYMASK. Las imágenes de la lista de imágenes superpuestas son asignadas con la macro ImageList_SetOverlayImage.

Los bits 12 a 15 de este miembro especifican el índice de la imagen de estado. lam imagen de estado es mostrada junto al icono del ítem para indicar un estado definido por la aplicación. Si estos bits son cero, el ítem no tendrá una imagen de estado. Para aislar estos bits, usar la máscara LVIS_STATEIMAGEMASK. Para asignar el índice de la imagen de estado usar la macro INDEXTOSTATEIMAGEMASK. El índice de imagen de estado especifica el índice de la imagen en la lista de imágenes de estado que debe ser mostrada. La lista de imágenes de estado se especifica con el mensaje LVM_SETIMAGELIST.

stateMask

Valor que especifica qué bits del miembro state deben ser recuperados o modificados. Por ejemplo, asignar LVIS_SELECTED a este miembro hará que solo se recuperen los bits de estado de seleccion del ítem.

Este miembro permite modificar uno o más estados de ítem sin necesidad de tener que recuperar todos ellos primero. Por ejemplo, asignando a este miembro LVIS_SELECTED y cero a state hará que el estado de selección del ítem sea eliminado, pero ninguno de los otros estados se verán afectados.

para recuperar o modificar todos los estados asignar (UINT)-1 a este miembro.

Se puede usar la macro ListView_SetItemState tanto para asignar como para eliminar bits.

pszText

Si la estructura asigna atributos de ítem, pszText es un puntero a una cadena terminada en cero que contiene el texto del ítem. Cuando se responde a una notificación LVN_GETDISPINFO, hay que asegurarse de que el puntero permanece válido hasta después de recibir la siguiente notificación.

Si la estructura recibe atributos de ítem, pszText es un puntero a un buffer que recibe el texto del ítem. Hay que tener en cuenta que aunque el control list-view permite cadenas de cualquier longitud para ser almacenadas como texto del ítem, solo los primeros 259 TCHARs son mostrados.

Si el valor de pszText es LPSTR_TEXTCALLBACK, el ítem es un ítem de retrollamada. Si el texto de retrollamada ha de modificarse, se debe asignar explícitamente a pszText el valor LPSTR_TEXTCALLBACK y notificar al control list-view el cambio enviando un mensaje LVM_SETITEM o LVM_SETITEMTEXT.

No se debe usar LPSTR_TEXTCALLBACK para pszText si el control list-view tiene los estilos LVS_SORTASCENDING o LVS_SORTDESCENDING.

cchTextMax

Número de TCHARs en el buffer apuntado por pszText, incluyendo el terminador nulo.

Este miembro solo es usado cuando la estructura recibe atributos. Es ignorado cuando la estructura los asigna. Por ejemplo cchTextMax es ignorado durante LVM_SETITEM y LVM_INSERTITEM. Es de solo lectura durante LVN_GETDISPINFO y otras notificaciones LVN_.

Nunca se deben copiar más de cchTextMax TCHARs—donde cchTextMax incluye el terminado nulo—en pszText durante el procesamiento de una notificación LVN_, o el programa fallará..

iImage

Índice del icono del ítem en la lista de imágenes del control. Esto se aplica tanto a la lista de imágenes de iconos grandes y como pequeños. So este miembro es el valor I_IMAGECALLBACK, la ventana padre es responsable de almacenar el índice. En ese caso, el control list-view enviará un código de notificación LVN_GETDISPINFO a su ventana padre para recuperar el índice cuando lo necesite para mostrar la imagen.

lParam

Valor específico del ítem. Si se usa el mensaje LVM_SORTITEMS, el control list-view pasará este valor a la función de comparación definida por la aplicación. También se puede usar el mensaje LVM_FINDITEM para buscar en un control list-view un ítem con un valor de lParam especificado.

iIndent

Versión 4.70. Número de anchos de imagen a tabular el ítem. Una tabulación equivale a la anchura de una imagen de ítem. De modo que, el valor 1 desplaza el ítem en la achura de una imagen, el valor 2 lo desplaza dos imágenes, etc. Hay que tener en cuenta que este campo sólo está soportado para ítems. Intentar asignarlo a un subítem hará que la llamada a la función falle.

iGroupId

Versión 6.0 identificador del grupo al que pertenece el ítem, o uno de los siguientes valores:

Valor	significado
I_GROUPIDCALLBACK	El control list-view envía a la ventana padre un código de notificación LVN_GETDISPINFO para recuperar el índice del grupo.
I_GROUPIDNONE	El ítem no pertenece a un grupo.

cColumns

Versión 6.0 Número de columnas de datos (subítems) a mostrar para este ítem en vista de mosaico. El valor máximo es 20. Si este valor es I_COLUMNSCALLBACK, el tamaño del array de columnas y el propio array (puColumns) son obtenidos enviando una notificación LVN_GETDISPINFO.

puColumns

Versión 6.0 Un puntero a un array de índices de columna, que especifica qué columnas serán mostradas para este ítem, y el orden de esas columnas.

piColFmt

Windows Vista: No implementado. Windows 7 y posteriores: Un puntero a un array de las banderas siguientes (solas o en combinación), que especifican el formato de cada subítem en la vista de mosaico extendida.

Valor	Significado
LVCFMT_LINE_BREAK	Hace que la columna se ajuste a la parte superior de la siguiente lista de columnas.
LVCFMT_FILL	Llena el resto del área de mosaico. Debe haber una tesela.
LVCFMT_WRAP	Permite que la columna se muestre en el espacio restante en su lista de columnas.
LVCFMT_NO_TITLE	Elimina el título del subítem.
LVCFMT_TILE_PLACEMENTMASK	Equivale a la combinación de LVCFMT_LINE_BREAK y LVCFMT_FILL.

iGroup

Windows Vista: Índice del grupo del ítem. Válido solo para datos de propietario o retrollamada (único ítem en varios grupos).

Observaciones

La estructura LVITEM es usada en varios mensajes, incluyendo LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM y LVM_DELETEITEM.

En la vista de mosaico, el nombre del ítem es mostrado a la derecha del icono. Se pueden especificar subítems adicionales (correspondientes a columnas en la vista de detalle), para que se muestren en líneas debajo del nombre del ítem. El array puColumns contiene los índices de los subítems a mostrar. Los índices deben ser mayores que 0, porque el subítem 0, el nombre del ítem, ya está mostrado. La información de columna también puede ser asignada mediante la estructura LVTILEINFO cuando se modifica el ítem de la lista.

Hay que tener en cuenta que la versión 6 de Comctl32.dll no es redistribuible pero está incluida en Windows Vista y posteriores. Para usar la versión 6 de Comctl32.dll se debe especificar en el manifiesto.

Nota: El fichero de cabecera commctrl.h define LVITEM como un alias que selecciona automáticamente la versión ANSI o Unicode de esta estructura basándose en la constante del preprocesador UNICODE. Mezclar el uso de alias de codificación neutral con código que no use esa codificación puede producir desajustes que resulten en errores de compilación o de ejecución.