commctrl.h

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:

ValoresSingificado
LVIF_COLFMTWindows 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_COLUMNSEl miembro cColumns es válido o debe ser recuperado.
LVIF_DI_SETITEMEl 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_GROUPIDEl 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_IMAGEEl miembro iImage es válido o debe ser recuperado.
LVIF_INDENTEl miembro iIndent es válido o debe ser recuperado.
LVIF_NORECOMPUTEEl 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_PARAMEl miembro lParam es válido o debe ser recuperado.
LVIF_STATEEl miembro state es válido o debe ser recuperado.
LVIF_TEXTEl 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:

Valorsignificado
I_GROUPIDCALLBACKEl control list-view envía a la ventana padre un código de notificación LVN_GETDISPINFO para recuperar el índice del grupo.
I_GROUPIDNONEEl í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.

ValorSignificado
LVCFMT_LINE_BREAKHace que la columna se sitúe en la parte superior de la siguiente lista de columnas.
LVCFMT_FILLLlena el resto del área de mosaico. Debe haber una baldosa.
LVCFMT_WRAPPermite que la columna se muestre en el espacio restante en su lista de columnas.
LVCFMT_NO_TITLEElimina el título del subítem.
LVCFMT_TILE_PLACEMENTMASKEquivale 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.