Compartir a través de


Estructura LVITEMA (commctrl.h)

Especifica o recibe los atributos de un elemento de vista de lista. Esta estructura se ha actualizado para admitir un nuevo valor de máscara (LVIF_INDENT) que habilita la sangría de elementos. Esta estructura sustituye a la estructura LV_ITEM .

Sintaxis

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;

Miembros

mask

Tipo: UINT

Conjunto de marcas que especifican qué miembros de esta estructura contienen datos que se van a establecer o qué miembros se solicitan. Este miembro puede tener uno o varios de los siguientes indicadores establecidos:

Valor Significado
LVIF_COLFMT
Windows Vista y versiones posteriores. El miembro piColFmt es válido o debe establecerse. Si se usa esta marca, el miembro cColumns es válido o debe establecerse.
LVIF_COLUMNS
El miembro cColumns es válido o debe establecerse.
LVIF_DI_SETITEM
El sistema operativo debe almacenar la información del elemento de lista solicitada y no volver a solicitarlo. Esta marca solo se usa con el código de notificación de LVN_GETDISPINFO .
LVIF_GROUPID
El miembro iGroupId es válido o debe establecerse. Si no se establece esta marca cuando se envía un mensaje de LVM_INSERTITEM , se supone que el valor de iGroupId se I_GROUPIDCALLBACK.
LVIF_IMAGE
El miembro iImage es válido o debe establecerse.
LVIF_INDENT
El miembro iIndent es válido o debe establecerse.
LVIF_NORECOMPUTE
El control no generará LVN_GETDISPINFO para recuperar información de texto si recibe un mensaje de LVM_GETITEM . En su lugar, el miembro pszText contendrá LPSTR_TEXTCALLBACK.
LVIF_PARAM
El miembro lParam es válido o debe establecerse.
LVIF_STATE
El miembro de estado es válido o debe establecerse.
LVIF_TEXT
El miembro pszText es válido o debe establecerse.

iItem

Tipo: int

Índice de base cero del elemento al que hace referencia esta estructura.

iSubItem

Tipo: int

Índice basado en uno del subelemento al que hace referencia esta estructura, o cero si esta estructura hace referencia a un elemento en lugar de a un subelemento.

state

Tipo: UINT

Indica el estado, la imagen de estado y la imagen de superposición del elemento. El miembro stateMask indica los bits válidos de este miembro.

Los bits de 0 a 7 de este miembro contienen las marcas de estado del elemento. Puede ser uno o varios de los valores de estado del elemento .

Los bits de 8 a 11 de este miembro especifican el índice de imagen de superposición basado en uno. Tanto la lista de imágenes de icono de tamaño completo como la lista de imágenes de icono pequeño pueden tener imágenes superpuestas. La imagen superpuesta se superpone sobre la imagen de icono del elemento. Si estos bits son cero, el elemento no tiene ninguna imagen superpuesta. Para aislar estos bits, use la máscara de LVIS_OVERLAYMASK . Para establecer el índice de imagen de superposición en este miembro, debe usar la macro INDEXTOOVERLAYMASK . Las imágenes superpuestas de la lista de imágenes se establecen con la función ImageList_SetOverlayImage .

Los bits de 12 a 15 de este miembro especifican el índice de imagen de estado. La imagen de estado se muestra junto al icono de un elemento para indicar un estado definido por la aplicación. Si estos bits son cero, el elemento no tiene ninguna imagen de estado. Para aislar estos bits, use la máscara de LVIS_STATEIMAGEMASK . Para establecer el índice de imagen de estado, use la macro INDEXTOSTATEIMAGEMASK . El índice de imagen de estado especifica el índice de la imagen en la lista de imágenes de estado que se debe dibujar. La lista de imágenes de estado se especifica con el mensaje LVM_SETIMAGELIST .

stateMask

Tipo: UINT

Valor que especifica qué bits del miembro de estado se recuperarán o modificarán. Por ejemplo, establecer este miembro en LVIS_SELECTED hará que solo se recupere el estado de selección del elemento.

Este miembro permite modificar uno o varios estados de elemento sin tener que recuperar primero todos los estados del elemento. Por ejemplo, establecer este miembro en LVIS_SELECTED y el estado en cero hará que se borre el estado de selección del elemento, pero ninguno de los demás estados se verá afectado.

Para recuperar o modificar todos los estados, establezca este miembro en (UINT)-1.

Puede usar la macro ListView_SetItemState para establecer y borrar bits.

pszText

Tipo: LPTSTR

Si la estructura especifica atributos de elemento, pszText es un puntero a una cadena terminada en null que contiene el texto del elemento. Al responder a una notificación de LVN_GETDISPINFO , asegúrese de que este puntero permanece válido hasta después de recibir la siguiente notificación.

Si la estructura recibe atributos de elemento, pszText es un puntero a un búfer que recibe el texto del elemento. Tenga en cuenta que aunque el control de vista de lista permite almacenar cualquier cadena de longitud como texto de elemento, solo se muestran los primeros 259 TCHAR.

Si el valor de pszText es LPSTR_TEXTCALLBACK, el elemento es un elemento de devolución de llamada. Si cambia el texto de devolución de llamada, debe establecer explícitamente pszText en LPSTR_TEXTCALLBACK y notificar al control de vista de lista el cambio enviando un mensaje de LVM_SETITEM o LVM_SETITEMTEXT .

No establezca pszText en LPSTR_TEXTCALLBACK si el control de vista de lista tiene el estilo LVS_SORTASCENDING o LVS_SORTDESCENDING .

cchTextMax

Tipo: int

Número de TCHARen el búfer al que apunta pszText, incluido el valor NULL de terminación.

Este miembro solo se usa cuando la estructura recibe atributos de elemento. Se omite cuando la estructura especifica atributos de elemento. Por ejemplo, cchTextMax se omite durante LVM_SETITEM y LVM_INSERTITEM. Es de solo lectura durante LVN_GETDISPINFO y otras notificaciones de LVN_.

Nota Nunca copie más de cchTextMaxTCHARs (donde cchTextMax incluye el valor NULL de terminación) en pszText durante una notificación de LVN_; de lo contrario, el programa puede producir un error.
 

iImage

Tipo: int

Índice del icono del elemento en la lista de imágenes del control. Esto se aplica a la lista de imágenes grandes y pequeñas. Si este miembro es el valor de I_IMAGECALLBACK, la ventana primaria es responsable de almacenar el índice. En este caso, el control de vista de lista envía al elemento primario un código de notificación de LVN_GETDISPINFO para recuperar el índice cuando necesite mostrar la imagen.

lParam

Tipo: LPARAM

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

iIndent

Tipo: int

Versión 4.70. Número de anchos de imagen para sangr el elemento. Una sola sangría es igual al ancho de una imagen de elemento. Por lo tanto, el valor 1 sangría el elemento por el ancho de una imagen, el valor 2 sangrías por dos imágenes, etc. Tenga en cuenta que este campo solo se admite para los elementos. Si se intenta establecer la sangría del subelemento, se producirá un error en la función de llamada.

iGroupId

Tipo: int

Versión 6.0 Identificador del grupo al que pertenece el elemento o uno de los siguientes valores.

Valor Significado
I_GROUPIDCALLBACK
El control listview envía al elemento primario un código de notificación de LVN_GETDISPINFO para recuperar el índice del grupo.
I_GROUPIDNONE
El elemento no pertenece a un grupo.

cColumns

Tipo: UINT

Versión 6.0 Número de columnas de datos (subelementos) que se mostrarán para este elemento en la vista de mosaico. El valor máximo es 20. Si este valor es I_COLUMNSCALLBACK, el tamaño de la matriz de columnas y la propia matriz (puColumns) se obtienen enviando una notificación de LVN_GETDISPINFO .

puColumns

Tipo: PUINT

Versión 6.0 Puntero a una matriz de índices de columna, especificando qué columnas se muestran para este elemento y el orden de esas columnas.

piColFmt

Tipo: int*

Windows Vista: No implementado. Windows 7 y versiones posteriores: Puntero a una matriz de las marcas siguientes (solas o combinadas), especificando el formato de cada subelemento en la vista de mosaico extendida.

Valor Significado
LVCFMT_LINE_BREAK
Obliga a que la columna se ajuste a la parte superior de la siguiente lista de columnas.
LVCFMT_FILL
Rellena el resto del área de mosaico. Podría tener un título.
LVCFMT_WRAP
Permite que la columna se ajuste dentro del espacio restante en su lista de columnas.
LVCFMT_NO_TITLE
Quita el título del subelemento.
LVCFMT_TILE_PLACEMENTMASK
Equivalente a una combinación de LVCFMT_LINE_BREAK y LVCFMT_FILL.

iGroup

Tipo: int

Windows Vista: índice de grupo del elemento. Válido solo para datos de propietario o devolución de llamada (un solo elemento en varios grupos).

Comentarios

La estructura LVITEM se usa con varios mensajes, incluidos LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM y LVM_DELETEITEM.

En la vista de mosaico, el nombre del elemento se muestra a la derecha del icono. Puede especificar subelementos adicionales (correspondientes a las columnas de la vista de detalles), que se mostrarán en líneas debajo del nombre del elemento. La matriz puColumns contiene los índices de subelementos que se van a mostrar. Los índices deben ser mayores que 0, ya que el subelemento 0, el nombre del elemento, ya se muestra. La información de columna también se puede establecer en la estructura LVTILEINFO al modificar el elemento de lista.

Para obtener código de ejemplo, consulte Uso de controles List-View.

Nota Comctl32.dll versión 6 no se puede redistribuir, pero se incluye en Windows o versiones posteriores. Para usar Comctl32.dll versión 6, especifíquelo en un manifiesto. Para obtener más información sobre los manifiestos, consulte Habilitación de estilos visuales.
 

Nota:

El encabezado commctrl.h define LVITEM como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

   
Cliente mínimo compatible Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Encabezado commctrl.h