Acerca de los controles de List-View

Consulte el ejemplo de control listview virtual.

Un control de vista de lista es una ventana que muestra una colección de elementos. Los controles de vista de lista proporcionan varias maneras de organizar y mostrar elementos y son mucho más flexibles que los cuadros de lista simples. Por ejemplo, se puede mostrar información adicional sobre cada elemento en columnas a la derecha del icono y la etiqueta.

estilos y vistas de List-View

Los controles de vista de lista pueden mostrar elementos en cinco vistas diferentes. El estilo de ventana del control especifica la vista predeterminada. Los estilos de ventana adicionales especifican la alineación de elementos y características específicas del control. En la tabla siguiente se describen las vistas.

Nombre de vista Descripción
Vista de icono Especificado por el estilo de ventana de LVS_ICON o pasando LV_VIEW_ICON con el mensaje LVM_SETVIEW . Cada elemento aparece como un icono de tamaño normal debajo del cual figura una etiqueta. El usuario puede arrastrar los elementos a cualquier ubicación de la ventana de vista de lista.
Vista de icono pequeño Especificado por el estilo de ventana de LVS_SMALLICON o pasando LV_VIEW_SMALLICON con LVM_SETVIEW. Cada elemento aparece como un icono pequeño con la etiqueta a la derecha. El usuario puede arrastrar los elementos a cualquier ubicación.
Vista de lista Especificado por el estilo de ventana de LVS_LIST o pasando LV_VIEW_LIST con LVM_SETVIEW. Cada elemento aparece como un icono pequeño con una etiqueta a la derecha. Los elementos se organizan en columnas y el usuario no puede arrastrarlos a una ubicación arbitraria.
Vista Informe (detalles) Especificado por el estilo de ventana de LVS_REPORT o pasando LV_VIEW_DETAILS con LVM_SETVIEW. Cada elemento aparece en su propia línea, con información organizada en columnas. La columna situada más a la izquierda siempre está justificada y contiene el pequeño icono y la etiqueta. Las columnas posteriores contienen subelementos según lo especificado por la aplicación. Cada columna tiene un encabezado, a menos que también especifique el estilo de ventana LVS_NOCOLUMNHEADER .
Vista de mosaico Versión 6 y posteriores. Se especifica pasando LV_VIEW_TILE con LVM_SETVIEW. Cada elemento aparece como un icono de tamaño completo con una etiqueta de una o varias líneas junto a él.

 

Las capturas de pantalla siguientes usan vistas para mostrar diferentes cantidades de información sobre cada una de las siete mascotas. Las vistas muestran cómo puede aparecer la información en Windows Vista. Los estilos visuales del control se han establecido en el tema "Explorer" mediante SetWindowTheme.

En la captura de pantalla siguiente se muestra la vista de detalles.

captura de pantalla que muestra información en cinco columnas y siete filas

En la captura de pantalla siguiente se muestra la vista de icono.

captura de pantalla que muestra solo el nombre de cada mascota y un icono que indica la especie

En la captura de pantalla siguiente se muestra la vista de lista.

captura de pantalla que muestra, para cada mascota, un icono grande junto al texto del nombre, la raza y el precio de la mascota

En la captura de pantalla siguiente se muestra la vista de mosaico.

vista de mosaico.

Puede cambiar el tipo de vista después de crear un control de vista de lista. Para recuperar y cambiar el estilo de ventana, use las funciones GetWindowLong y SetWindowLong . Para determinar los estilos de ventana de la vista actual, use el valor LVS_TYPEMASK .

Puede controlar la forma en que los elementos se organizan en la vista icono o icono pequeño especificando el estilo de ventana de LVS_ALIGNTOP (predeterminado) o LVS_ALIGNLEFT .

Puede cambiar la alineación después de crear un control de vista de lista. Para determinar la alineación actual, use el valor LVS_ALIGNMASK .

Los estilos de ventana adicionales proporcionan otras opciones, como si un usuario puede editar etiquetas o seleccionar más de un elemento a la vez. Para obtener una lista completa, vea Estilos de ventana de vista de lista.

Estilos de List-View extendidos

Los estilos de control de vista de lista extendidos proporcionan opciones como casillas, barras de desplazamiento planas, líneas de cuadrícula y seguimiento activo. Para obtener una lista completa, consulte Estilos de List-View extendidos. No se accede a los estilos de vista de lista extendidos de la misma manera que los estilos de ventana estándar. No se usan las funciones GetWindowLong y SetWindowLong para realizar cambios de estilo extendidos.

Hay dos mensajes que establecen y recuperan información de estilo extendida, LVM_SETEXTENDEDLISTVIEWSTYLE y LVM_GETEXTENDEDLISTVIEWSTYLE. En lugar de enviar los mensajes explícitamente, puede usar las siguientes macros correspondientes: ListView_SetExtendedListViewStyle, ListView_SetExtendedListViewStyleEx y ListView_GetExtendedListViewStyle.

Estilo de List-View virtual

Una vista de lista virtual es un control de vista de lista que tiene el estilo LVS_OWNERDATA . Este estilo permite que el control control controle millones de elementos porque el propietario recibe la carga de administrar los datos del elemento. Esto le permite usar el control de vista de lista virtual con grandes bases de datos de información, donde ya existen métodos específicos de acceso a datos.

Un control de vista de lista virtual mantiene muy poca información de elementos. Excepto para la selección de elementos y la información de foco, el propietario del control debe administrar toda la información del elemento. Otros procesos solicitan información de elemento del propietario mediante LVN_GETDISPINFO códigos de notificación.

Dado que este tipo de control de lista está pensado para grandes conjuntos de datos, se recomienda almacenar en caché los datos de elementos solicitados para mejorar el rendimiento de recuperación. La vista de lista proporciona un mecanismo de sugerencias de caché para ayudar a optimizar la memoria caché. La sugerencia se implementa en forma de un código de notificación de LVN_ODCACHEHINT .

Creación de un control de List-View virtual

Puede crear controles de vista de lista virtual mediante la función CreateWindow o CreateWindowEx , especificando el estilo de ventana de LVS_OWNERDATA como parte del parámetro de función dwStyle . No se admite el cambio dinámico hacia y desde el estilo de LVS_OWNERDATA .

Puede usar el estilo de LVS_OWNERDATA en combinación con la mayoría de los demás estilos de ventana, excepto el estilo LVS_SORTASCENDING o LVS_SORTDESCENDING . Todos los controles de vista de lista virtual están de forma predeterminada en el estilo de LVS_AUTOARRANGE .

Para permitir que los elementos se muestren en la lista, primero debe enviar el mensaje LVM_SETITEMCOUNT , ya sea explícitamente o mediante la macro ListView_SetItemCountEx .

Los siguientes mensajes no se admiten en el estilo LVS_OWNERDATA : LVM_ENABLEGROUPVIEW, LVM_GETITEMTEXT, LVM_SETTILEINFO y LVM_MAPIDTOINDEX.

Problemas de compatibilidad

Los cuatro estilos de vista de lista (icono, icono pequeño, lista y vista de informe) admiten el estilo LVS_OWNERDATA . Los controles de vista de lista que tienen el estilo LVS_OWNERDATA no almacenan ninguna información específica del elemento. Por lo tanto, las únicas marcas de estado de elemento válidas que se pueden aplicar a un elemento se LVIS_SELECTED y LVIS_FOCUSED. No se almacena ninguna otra información de estado. En concreto, el control de vista de lista no mantiene imágenes de estado ni superposición para cada elemento. Sin embargo, puede hacer que el control de vista de lista consulte la aplicación para estas imágenes mediante el envío de un mensaje LVM_SETCALLBACKMASK .

La mayoría de los mensajes de control de vista de lista y las macros asociadas son totalmente compatibles. Sin embargo, algunos mensajes tienen limitaciones o no se admiten al usar el estilo LVS_OWNERDATA . En la tabla siguiente se resumen los mensajes afectados.

Message Limitación
LVM_ARRANGE No admite el estilo LVA_SNAPTOGRID .
LVM_DELETEALLITEMS Establece el recuento de elementos en cero y borra todas las variables de selección internas, pero en realidad no elimina ningún elemento. Realiza una devolución de llamada de notificación.
LVM_DELETEITEM Solo se admite para la integridad de la selección y no elimina realmente un elemento.
LVM_GETITEMSTATE Devuelve solo los estados de foco y selección (es decir, los estados almacenados por el control de vista de lista).
LVM_GETNEXTITEM No admite los criterios de búsqueda de vista de lista LVNI_CUT, LVNI_HIDDEN o LVNI_DROPHILITED. Se admiten todos los demás criterios.
LVM_GETWORKAREAS No se admite.
LVM_INSERTITEM Solo se admite para la integridad de la selección.
LVM_SETITEM No se admite. Para establecer el estado del elemento, use el mensaje ListView_SetItemState .
LVM_SETITEMCOUNT Establece el número de elementos que se encuentran actualmente en la lista. Si el control de vista de lista envía una notificación que solicita datos para cualquier elemento hasta el conjunto máximo, el propietario debe estar preparado para proporcionar esos datos. Los parámetros de mensaje admiten controles de vista de lista virtual.
LVM_SETITEMPOSITION No se admite.
LVM_SETITEMSTATE Permite cambiar solo los estados de selección y enfoque para el elemento.
LVM_SETITEMTEXT No se admite. Es responsabilidad de la aplicación mantener los textos del punto.
LVM_SETWORKAREAS No se admite.
LVM_SORTITEMS No se admite. Es responsabilidad de la aplicación presentar los elementos en el orden deseado.

 

Control de códigos de notificación de control de List-View virtual

Los controles de vista de lista con el estilo LVS_OWNERDATA envían los mismos códigos de notificación que otros controles de vista de lista y dos adicionales: LVN_ODCACHEHINT y LVN_ODFINDITEM. A continuación se muestran las notificaciones más comunes que envía el control de vista de lista con el estilo LVS_OWNERDATA .

Notification Descripción
LVN_GETDISPINFO Un control de vista de lista virtual mantiene muy poca información de elementos por sí sola. Como resultado, a menudo envía el código de notificación LVN_GETDISPINFO para solicitar información de elemento. Este mensaje se controla de la misma manera que los elementos de devolución de llamada en un control de lista estándar. Dado que el número de elementos admitidos por el control puede ser muy grande, el almacenamiento en caché de datos de elementos mejora el rendimiento. Al controlar LVN_GETDISPINFO, el propietario del control primero intenta proporcionar información de elementos solicitada desde la memoria caché (para obtener más información, vea Administración de caché). Si el elemento solicitado no se almacena en caché, el propietario debe estar preparado para proporcionar la información por otros medios.
LVN_ODCACHEHINT Una vista de lista virtual envía el código de notificación de LVN_ODCACHEHINT para ayudar a optimizar la memoria caché. El código de notificación proporciona valores de índice inclusivos para un intervalo de elementos que recomienda almacenar en caché. Al recibir el código de notificación, el propietario debe estar preparado para cargar la memoria caché con información de elemento para el intervalo solicitado para que la información esté disponible fácilmente cuando se envíe un mensaje de LVN_GETDISPINFO .
LVN_ODFINDITEM El LVN_ODFINDITEM código de notificación se envía mediante un control de vista de lista virtual cuando el control necesita que el propietario encuentre un elemento de devolución de llamada determinado. El código de notificación se envía cuando el control de vista de lista recibe acceso rápido a la clave o cuando recibe un mensaje de LVM_FINDITEM . La información de búsqueda se envía en forma de una estructura LVFINDINFO , que es un miembro de la estructura NMLVFINDITEM . El propietario debe estar preparado para buscar un elemento que coincida con la información que proporciona el control de vista de lista. El propietario devuelve el índice del elemento si se ejecuta correctamente o -1 si no se encuentra ningún elemento coincidente.

 

Administración de la memoria caché

Un control de vista de lista con el estilo LVS_OWNERDATA genera un gran número de códigos de notificación de LVN_GETDISPINFO y, para ayudar a optimizar la memoria caché, un mensaje de LVN_ODCACHEHINT . LVN_ODCACHEHINT mensajes proporcionan información sobre los elementos recomendados que se incluirán en la memoria caché. Estos mensajes se envían como mensajes WM_NOTIFY , con el valor lParam que actúa como la dirección de una estructura NMLVCACHEHINT .

La estructura NMLVCACHEHINT incluye dos miembros enteros, iFrom e iTo, que representan los puntos de conexión inclusivos de un intervalo de elementos que probablemente serán necesarios. El propietario debe estar preparado para cargar la memoria caché con la información del elemento para cada uno de los elementos dentro del intervalo recomendado.

El control de lista a menudo necesita información de elementos para el primer elemento (desplazamiento 0). Es posible que el código de notificación de LVN_ODCACHEHINT no incluya siempre el elemento 0, pero siempre debe incluirse en la memoria caché.

A menudo se accede a los últimos elementos de la lista. Por lo tanto, es posible que el propietario quiera conservar una segunda memoria caché que incluya los elementos al final de la lista. El intervalo solicitado de LVN_ODCACHEHINT se puede comprobar en la memoria caché final para que esté disponible automáticamente en lugar de volver a cargar el mismo intervalo de finalización cada vez.

áreas de trabajo de List-View

Los controles de vista de lista admiten áreas de trabajo, que son áreas virtuales rectangulares que usa el control de vista de lista para organizar sus elementos. Un área de trabajo no es una ventana y no puede tener un borde visible. De forma predeterminada, el control de vista de lista no tiene áreas de trabajo. Al crear un área de trabajo, puede crear un borde vacío a la izquierda, arriba o derecha de los elementos o hacer que se muestre una barra de desplazamiento horizontal cuando normalmente no hubiera uno.

Cuando se crea un área de trabajo, los elementos que se encuentran dentro del área de trabajo se convierten en miembros del área de trabajo. De forma similar, si un elemento se mueve a un área de trabajo, el elemento se convierte en miembro de ese área de trabajo. Si un elemento no se encuentra dentro de ningún área de trabajo, se convierte automáticamente en miembro de la primera (índice 0). Para colocar un nuevo elemento dentro de un área de trabajo específica, primero debe crear el elemento y, a continuación, usar el LVM_SETITEMPOSITION o el mensaje LVM_SETITEMPOSITION32 para moverlo al área de trabajo deseada.

La ilustración siguiente es un ejemplo de un control de vista de lista que contiene cuatro áreas de trabajo, cada una en un cuadrante diferente del área de cliente.

captura de pantalla de un control de vista de lista con un área de trabajo en cada cuadrante del área de cliente

Se pueden usar varias áreas de trabajo para crear diferentes áreas dentro de una vista. Puede crear áreas en una sola vista que tengan significados diferentes. Por ejemplo, una vista de un sistema de archivos podría tener un área para archivos de lectura y escritura y otra área para archivos de solo lectura. El usuario puede clasificar los elementos colocándolos en diferentes áreas de trabajo. Si un archivo se mueve al área de solo lectura, se convertirá automáticamente en de solo lectura.

Varias áreas de trabajo pueden intersecrse, pero los elementos que se encuentran dentro de la intersección se convierten en miembros del área con el índice inferior; por lo tanto, es mejor evitar esta situación. Al ordenar varias áreas de trabajo, los elementos se ordenan en comparación con los demás elementos del mismo área de trabajo.

El número de áreas de trabajo se puede recuperar con el mensaje LVM_GETNUMBEROFWORKAREAS . Las áreas de trabajo se cambian con el mensaje LVM_SETWORKAREAS y se pueden recuperar con el mensaje LVM_GETWORKAREAS . Ambos mensajes toman la dirección de una matriz de estructuras RECT como lParam y el número de estructuras RECT como wParam. Los miembros izquierdo y superior de estas estructuras especifican las coordenadas de la esquina superior izquierda (el origen) del área de trabajo, y los miembros derecho e inferior especifican la esquina inferior derecha del área de trabajo. Todas las coordenadas están en coordenadas de cliente de la vista de lista. El número máximo de áreas de trabajo permitidas se define mediante el valor de LV_MAX_WORKAREAS .

Cambiar el área de trabajo no tiene ningún efecto en los controles de vista de lista que tienen la vista de LVS_LIST o LVS_REPORT , pero las áreas de trabajo se mantendrán cuando se cambie el tipo de vista. Con las vistas LVS_ICON y LVS_SMALLICON , el área de trabajo se puede modificar para cambiar la forma en que se muestran los elementos. Hacer que el ancho del área de trabajo (derecha- izquierda) sea mayor que el ancho del cliente del control hace que los elementos se encapsulan en ese ancho y se muestre la barra de desplazamiento horizontal. Hacer que el ancho del área de trabajo sea más estrecho que el ancho del área cliente del control hace que los elementos se encapsulan dentro del área de trabajo y no en el área de cliente. Establecer el miembro izquierdo o superior en un valor positivo hace que los elementos se muestren empezando en el área de trabajo, creando un espacio vacío entre el borde del control y los elementos. También se puede crear un espacio vacío entre el borde derecho del control y los elementos haciendo que el ancho del área de trabajo sea menor que el ancho del cliente del control.

listas de imágenes de List-View

De forma predeterminada, un control de vista de lista no muestra imágenes de elementos. Para mostrar imágenes de elementos, debe crear listas de imágenes y asociarlas con el control . Un control de vista de lista puede tener tres listas de imágenes:

  • Lista de imágenes que contiene iconos de tamaño completo que se muestran cuando el control está en la vista de iconos.
  • Lista de imágenes que contiene iconos pequeños que se muestran cuando el control está en una vista de icono pequeña, vista de lista o vista de informe.
  • Lista de imágenes que contiene imágenes de estado, que se muestran a la izquierda del icono de tamaño completo o pequeño. Puede usar imágenes de estado, como casillas activadas y desactivadas, para indicar estados de elemento definidos por la aplicación. Las imágenes de estado se muestran en la vista de iconos, la vista de icono pequeña, la vista de lista y la vista de informe.

Las listas de imágenes de iconos pequeños y de tamaño completo también pueden contener imágenes superpuestas, diseñadas para dibujarse de forma transparente sobre los iconos de elementos.

Para usar imágenes superpuestas en un control de vista de lista:

  1. Llame a la función ImageList_SetOverlayImage para asignar un índice de imagen de superposición a una imagen en las listas de imágenes de icono de tamaño completo y pequeño. Una imagen de superposición se identifica mediante un índice basado en uno.
  2. Puede asociar un índice de imagen superpuesta a un elemento al llamar a la macro ListView_InsertItem o ListView_SetItem . Utilice la macro INDEXTOOVERLAYMASK para especificar un índice de imagen de superposición en el miembro de estado de la estructura LVITEM del elemento. También debe establecer los bits de LVIS_OVERLAYMASK en el miembro stateMask .

Si se especifica una lista de imágenes de estado, un control de vista de lista reserva espacio a la izquierda del icono de cada elemento para una imagen de estado.

Para asociar una imagen de estado a un elemento, use la macro INDEXTOSTATEIMAGEMASK para especificar un índice de imagen de estado en el miembro de estado de la estructura LVITEM . El índice identifica una imagen en la lista de imágenes de estado del control. Aunque los índices de lista de imágenes están basados en cero, el control usa índices basados en uno para identificar imágenes de estado. Un índice de imagen de estado de cero indica que un elemento no tiene ninguna imagen de estado.

De forma predeterminada, cuando se destruye un control de vista de lista, destruye las listas de imágenes asignadas. Sin embargo, si un control de vista de lista tiene el estilo de ventana LVS_SHAREIMAGELISTS , la aplicación es responsable de destruir las listas de imágenes cuando ya no están en uso. Debe especificar este estilo si asigna las mismas listas de imágenes a varios controles de vista de lista; de lo contrario, es posible que más de un control intente destruir la misma lista de imágenes.

List-View elementos y subelementos

Cada elemento de un control de vista de lista tiene un icono, una etiqueta, un estado actual y un valor definido por la aplicación. Mediante el uso de mensajes de vista de lista, puede agregar, modificar y eliminar elementos, así como recuperar información sobre los elementos.

Cada elemento puede tener uno o varios subelementos. Un subelemento es una cadena que, en la vista de informe, se muestra en una columna independiente del icono y la etiqueta del elemento. Para especificar el texto de un subelemento, use el mensaje LVM_SETITEMTEXT o LVM_SETITEM . Todos los elementos de un control de vista de lista tienen el mismo número de subelementos. El número de subelementos viene determinado por el número de columnas del control de vista de lista. Al agregar una columna a un control de vista de lista, se especifica su índice de subelemento asociado.

La estructura LVITEM define un elemento o subelemento de vista de lista. El miembro iItem es el índice de base cero del elemento. El miembro iSubItem es el índice basado en uno de un subelemento o cero si la estructura contiene información sobre un elemento. Los miembros adicionales especifican el texto, el icono, el estado y los datos del elemento. Los datos de elemento son un valor definido por la aplicación asociado a un elemento de vista de lista.

Para agregar un elemento a un control de vista de lista, use el mensaje LVM_INSERTITEM , especificando la dirección de una estructura LVITEM . Antes de agregar varios elementos, puede enviar al control un mensaje de LVM_SETITEMCOUNT , especificando el número de elementos que contendrá el control en última instancia. Este mensaje permite al control de vista de lista reasignar sus estructuras de datos internas solo una vez en lugar de cada vez que se agrega un elemento. Puede determinar el número de elementos de un control de vista de lista mediante el mensaje LVM_GETITEMCOUNT . Si va a agregar un gran número de elementos a un control de vista de lista, puede acelerar el proceso si deshabilita volver a dibujar antes de agregar los elementos y, a continuación, habilitar el nuevo dibujo después de agregar los elementos. Use el mensaje WM_SETREDRAW para habilitar y deshabilitar el nuevo dibujo.

Para cambiar los atributos de un elemento de vista de lista, use el mensaje LVM_SETITEM , especificando la dirección de una estructura LVITEM . El miembro mask de esta estructura especifica los atributos de elemento que desea cambiar. Por ejemplo, para cambiar solo el texto de un elemento o un subelemento, use el mensaje LVM_SETITEMTEXT .

Para recuperar información sobre un elemento de vista de lista, use el mensaje LVM_GETITEM , especificando la dirección de la estructura LVITEM que se va a rellenar. El miembro mask de esta estructura especifica los atributos de elemento que se van a recuperar. Para recuperar solo un elemento o el texto del subelemento, use el mensaje LVM_GETITEMTEXT .

Para eliminar un elemento de vista de lista, use el mensaje LVM_DELETEITEM . Puede eliminar todos los elementos de un control de vista de lista mediante el mensaje LVM_DELETEALLITEMS .

estados de List-View elemento

El estado de un elemento es un valor que especifica la disponibilidad del elemento, indica las acciones del usuario o, de lo contrario, refleja el estado del elemento. Un control de vista de lista cambia algunos bits de estado, como cuando el usuario selecciona un elemento. Una aplicación puede cambiar otros bits de estado para deshabilitar u ocultar el elemento o especificar una imagen de superposición o imagen de estado. Para obtener más información sobre las imágenes superpuestas y las imágenes de estado, vea Listas de imágenes de vista de lista.

El estado de un elemento se especifica mediante el miembro de estado de la estructura LVITEM . Al especificar o cambiar el estado de un elemento, el miembro stateMask especifica los bits de estado que necesita cambiar. Puede cambiar el estado de un elemento mediante el mensaje LVM_SETITEMSTATE . Puede especificar el estado de un elemento al crearlo o al cambiar sus atributos mediante el mensaje LVM_SETITEM . Para determinar el estado actual de un elemento, use el mensaje LVM_GETITEMSTATE o LVM_GETITEM .

Para establecer la imagen superpuesta de un elemento, el miembro stateMask de la estructura LVITEM debe incluir el valor de LVIS_OVERLAYMASK y el miembro de estado debe incluir el índice basado en uno de la imagen de superposición desplazado 8 bits a la izquierda mediante la macro INDEXTOOVERLAYMASK . El índice puede ser cero para especificar ninguna imagen superpuesta.

Para establecer la imagen de estado de un elemento, el miembro stateMask de la estructura LVITEM debe incluir el valor de LVIS_STATEIMAGEMASK y el miembro de estado debe incluir el índice basado en uno de la imagen de estado desplazado a la izquierda 12 bits mediante la macro INDEXTOSTATEIMAGEMASK . El índice puede ser cero para especificar ninguna imagen de estado.

Elementos de devolución de llamada y máscara de devolución de llamada

Para cada uno de sus elementos, un control de vista de lista normalmente almacena el texto de la etiqueta, el índice de lista de imágenes de los iconos del elemento y un conjunto de marcas de bits para el estado del elemento. Puede definir elementos de devolución de llamada o cambiar la máscara de devolución de llamada del control para indicar que la aplicación, en lugar del control, almacena parte o toda esta información. Es posible que quiera usar devoluciones de llamada si la aplicación almacena parte de esta información.

Un elemento de devolución de llamada de un control de vista de lista es un elemento para el que la aplicación almacena el índice de texto o icono, o ambos. Puede definir elementos de devolución de llamada al enviar el mensaje LVM_INSERTITEM para agregar un elemento al control de vista de lista. Si la aplicación almacena el texto del elemento o subitem, establezca el miembro pszText de la estructura LVITEM del elemento en LPSTR_TEXTCALLBACK. Si la aplicación almacena el índice de icono de un elemento, establezca el miembro iImage de la estructura LVITEM del elemento en I_IMAGECALLBACK.

La máscara de devolución de llamada de un control de vista de lista es un conjunto de marcas de bits que especifican los estados de elemento para los que la aplicación, en lugar del control, almacena los datos actuales. La máscara de devolución de llamada se aplica a todos los elementos del control, a diferencia de la designación del elemento de devolución de llamada, que se aplica a un elemento concreto. La máscara de devolución de llamada es cero de forma predeterminada, lo que significa que el control de vista de lista almacena toda la información de estado del elemento. Después de crear un control de vista de lista e inicializar sus elementos, puede enviar el mensaje LVM_SETCALLBACKMASK para cambiar la máscara de devolución de llamada. Para recuperar la máscara de devolución de llamada actual, envíe el mensaje LVM_GETCALLBACKMASK .

Cuando un control de vista de lista debe mostrar o ordenar un elemento de vista de lista para el que la aplicación almacena información de devolución de llamada, el control envía el código de notificación LVN_GETDISPINFO a la ventana primaria del control. Este mensaje especifica una estructura NMLVDISPINFO que contiene el tipo de información necesaria e identifica el elemento o subelemento que se va a recuperar. La ventana primaria debe procesar LVN_GETDISPINFO para proporcionar los datos solicitados.

Si el control de vista de lista detecta un cambio en la información de devolución de llamada de un elemento, como un cambio en el texto, el icono o la información de estado, el control envía un código de notificación de LVN_SETDISPINFO para notificarle el cambio.

Si cambia los atributos o bits de estado de un elemento de devolución de llamada, use el mensaje LVM_UPDATE para forzar que el control vuelva a dibujar el elemento. Este mensaje también hace que el control organice sus elementos si tiene el estilo LVS_AUTOARRANGE . Puede usar el mensaje de LVM_REDRAWITEMS para volver a dibujar un intervalo de elementos invalidando las partes correspondientes del área cliente del control de vista de lista.

Mediante el uso eficaz de elementos de devolución de llamada y la máscara de devolución de llamada, puede asegurarse de que cada atributo de elemento se mantiene solo en un solo lugar. Esto puede simplificar la aplicación, pero el único espacio guardado es la memoria que, de lo contrario, sería necesaria para almacenar etiquetas de elementos y texto subelemento.

posición del elemento de List-View

Cada elemento de vista de lista tiene una posición y un tamaño, que puede recuperar y establecer mediante mensajes. También puede determinar qué elemento, si existe, está en una posición especificada. La posición de los elementos de vista de lista se especifica en coordenadas de vista, que son coordenadas de cliente que se desplazan por la posición de desplazamiento.

Para recuperar y establecer la posición de un elemento, use los mensajes LVM_GETITEMPOSITION y LVM_SETITEMPOSITION . LVM_GETITEMPOSITION funciona para todas las vistas, pero LVM_SETITEMPOSITION solo funciona para las vistas de icono y icono pequeño.

Puede determinar qué elemento, si existe, está en una ubicación determinada mediante el LVM_HITTEST mensaje.

Para recuperar el rectángulo delimitador de un elemento de lista o solo para su icono o etiqueta, use el mensaje LVM_GETITEMRECT .

Organizar, ordenar y buscar elementos

Puede usar mensajes de vista de lista para organizar y ordenar elementos y buscar elementos en función de sus atributos o posiciones. Organizar los elementos para alinearlos en una cuadrícula, pero los índices de los elementos no cambian. La ordenación cambia la secuencia de elementos (y sus índices correspondientes) y, a continuación, las cambia según corresponda. Solo puede organizar los elementos en las vistas de icono y icono pequeño, pero puede ordenar los elementos en cualquier vista. Para buscar elementos, envíe mensajes de vista de lista que especifiquen una ubicación o propiedad de elemento.

Para organizar los elementos, use el mensaje LVM_ARRANGE . Puede asegurarse de que los elementos se organizan en todo momento especificando el estilo de ventana LVS_AUTOARRANGE .

Para ordenar los elementos, use el mensaje LVM_SORTITEMS . Al ordenar con este mensaje, se especifica una función de devolución de llamada definida por la aplicación que el control de vista de lista llama para comparar el orden relativo de dos elementos. El control pasa a la función de comparación los datos del elemento asociados a cada uno de los dos elementos. Los datos del elemento son el valor especificado en el miembro lParam de la estructura LVITEM del elemento cuando se insertó en la lista. Al especificar los datos de elemento adecuados y proporcionar una función de comparación adecuada, puede ordenar los elementos por su etiqueta, por cualquier subelemento o por cualquier otra propiedad. Tenga en cuenta que la ordenación de elementos no reordena los subelementos correspondientes. Cuando se reordenan los elementos, sus subelementos correspondientes se llevan con ellos; es decir, las filas enteras se mantienen juntas. Para ordenar las columnas por separado entre sí, desasociar los subelementos de sus elementos, debe volver a generar las columnas después de ordenar mediante LVM_SETITEM.

Puede asegurarse de que un control de vista de lista siempre se ordene especificando el estilo de ventana de LVS_SORTASCENDING o LVS_SORTDESCENDING . Los controles con estos estilos usan el texto de la etiqueta de los elementos para ordenarlos en orden ascendente o descendente. No se puede proporcionar una función de comparación al usar estos estilos de ventana. Si un control de vista de lista tiene cualquiera de estos estilos, se producirá un error en un mensaje de LVM_INSERTITEM si intenta insertar un elemento que tiene LPSTR_TEXTCALLBACK como miembro pszText de su estructura LVITEM .

Puede encontrar un elemento de vista de lista con propiedades específicas mediante el mensaje LVM_FINDITEM . Puede encontrar un elemento de vista de lista que se encuentre en un estado especificado y que tenga una relación especificada con un elemento determinado mediante el mensaje LVM_GETNEXTITEM . Por ejemplo, puede recuperar el siguiente elemento seleccionado a la derecha de un elemento especificado.

columnas de List-View

Las columnas controlan la forma en que se muestran los elementos y sus subelementos en la vista de informe. Cada columna tiene un título y un ancho y está asociado a un subelemento específico; el subelemento cero es el icono y la etiqueta del elemento. Los atributos de una columna se definen mediante una estructura LVCOLUMN .

Para agregar una columna a un control de vista de lista, use el mensaje LVM_INSERTCOLUMN . Para eliminar una columna, use el mensaje LVM_DELETECOLUMN .

Nota

La eliminación de la columna cero de un control de vista de lista solo se admite en ComCtl32.dll versión 6 y posteriores. La versión 5 también admite la eliminación de la columna cero, pero solo después de usar CCM_SETVERSION para establecer la versión en 5 o posterior. Las versiones anteriores a la versión 5 no admiten la eliminación de la columna cero.

 

Puede recuperar y cambiar las propiedades de una columna existente mediante los mensajes LVM_GETCOLUMN y LVM_SETCOLUMN . Para recuperar o cambiar el ancho de una columna, use los mensajes LVM_GETCOLUMNWIDTH y LVM_SETCOLUMNWIDTH .

A menos que se especifique el estilo de ventana LVS_NOCOLUMNHEADER , los encabezados de columna aparecen en la vista de informe. El usuario puede hacer clic en un encabezado de columna, lo que hace que se envíe un código de notificación LVN_COLUMNCLICK a la ventana primaria. Normalmente, la ventana primaria ordena el control de vista de lista por la columna especificada cuando se produce este clic. El usuario también puede arrastrar las guías de columna entre los encabezados para ajustar el tamaño de las columnas.

Los controles de vista de lista pueden mostrar imágenes junto a títulos de columna. Para implementar esta característica, especifique el valor LVCF_IMAGE y asigne el índice de la imagen al miembro iImage en la estructura LVCOLUMN .

Los controles de vista de lista pueden establecer el orden en que se muestran las columnas. Para implementar esta característica, especifique el valor LVCF_ORDER y asigne el orden de columna al miembro iOrder en la estructura LVCOLUMN . El orden de columna es de base cero y está en orden de izquierda a derecha. Por ejemplo, cero indica la columna situada más a la izquierda.

List-View posición de desplazamiento

A menos que se especifique el estilo de ventana de LVS_NOSCROLL , se puede desplazar un control de vista de lista para mostrar más elementos de los que caben en el área cliente del control. Puede recuperar la posición de desplazamiento y la información relacionada de un control de vista de lista, desplazar un control de vista de lista por una cantidad especificada o desplazar un control de vista de lista para que un elemento de lista especificado esté visible.

En la vista de icono o en la vista de icono pequeña, el origen de la vista define la posición de desplazamiento actual. El origen de la vista es el conjunto de coordenadas, en relación con el área visible del control de vista de lista, que corresponden a las coordenadas de vista (0, 0). Para recuperar el origen de la vista actual, use el mensaje LVM_GETORIGIN . Este mensaje solo debe utilizarse en la vista icono o icono pequeño; devuelve un error en la vista de lista o informe.

En la vista de lista o informe, el índice superior define la posición de desplazamiento actual. El índice superior es el índice del primer elemento visible en el control de vista de lista. Para recuperar el índice superior actual, use el mensaje LVM_GETTOPINDEX . Este mensaje devuelve un resultado válido solo en la vista de lista o informe; devuelve cero en el icono o en la vista de icono pequeño.

Puede usar el LVM_GETVIEWRECT mensaje para recuperar el rectángulo delimitador de todos los elementos de un control de vista de lista, en relación con el área visible del control.

El mensaje LVM_GETCOUNTPERPAGE devuelve el número de elementos que caben en una página del control de vista de lista. Este mensaje devuelve un resultado válido solo en las vistas de lista e informe; en las vistas de icono y icono pequeño, devuelve el número total de elementos.

Para desplazar un control de vista de lista por una cantidad específica, use el mensaje LVM_SCROLL . Con el mensaje LVM_ENSUREVISIBLE , puede desplazarse por el control de vista de lista, si es necesario, para asegurarse de que un elemento especificado esté visible.

edición de etiquetas de List-View

Un control de vista de lista que tiene el estilo de ventana de LVS_EDITLABELS permite al usuario editar etiquetas de elementos en su lugar. El usuario comienza a editar al hacer clic en la etiqueta de un elemento que tiene el foco. Como alternativa, una aplicación puede empezar a editarse automáticamente mediante el mensaje LVM_EDITLABEL . El control de vista de lista notifica a la ventana primaria cuando se inicia la edición y cuando se cancela o se completa. Cuando se completa la edición, la ventana primaria es responsable de actualizar la etiqueta del elemento, si procede.

Cuando comienza la edición de etiquetas, se crea, coloca e inicializa un control de edición . Antes de que se muestre, el control de vista de lista envía a su ventana primaria un código de notificación LVN_BEGINLABELEDIT . Si necesita modificar el proceso de edición de etiquetas, puede implementar un controlador para esta notificación.

Un uso de un controlador de notificaciones de LVN_BEGINLABELEDIT es controlar qué etiquetas puede editar el usuario. Para evitar la edición de etiquetas, devuelva un valor distinto de cero. Para personalizar la edición de etiquetas, haga que el controlador de notificaciones recupere un identificador para el control de edición mediante el envío de un mensaje de LVM_GETEDITCONTROL al control de vista de lista. Una vez que tenga ese identificador, puede personalizar el control de edición enviando los mensajes de EM_XXX habituales. Por ejemplo, para limitar la cantidad de texto que puede escribir un usuario, envíe al control de edición un mensaje de EM_LIMITTEXT . Puede cambiar el texto predeterminado del control de edición con SetWindowText. Incluso puede subclase el control de edición para interceptar y descartar caracteres no válidos.

Cuando se cancela o completa la edición de etiquetas, un control de vista de lista envía a su ventana primaria un código de notificación LVN_ENDLABELEDIT . El parámetro lParam es la dirección de una estructura NMLVDISPINFO . El miembro item de esta estructura es una estructura LVITEM cuyo miembro iItem identifica el elemento. Si se cancela la edición, el miembro pszText de la estructura LVITEM es NULL; de lo contrario, pszText es la dirección del texto editado. La ventana primaria es responsable de actualizar la etiqueta del elemento si desea mantener la nueva etiqueta.

colores de List-View

Una aplicación puede recuperar y establecer tres colores para un control de vista de lista.

Color Mensajes usados para recuperar y establecer colores
Color del texto LVM_GETTEXTCOLOR, LVM_SETTEXTCOLOR
Color de fondo del texto LVM_GETTEXTBKCOLOR, LVM_SETTEXTBKCOLOR
Color de fondo de la ventana LVM_GETBKCOLOR, LVM_SETBKCOLOR

 

Para personalizar la apariencia de un control de vista de lista de forma más significativa, use NM_CUSTOMDRAW (vista de lista) o use estilos visuales ( vea Estilos visuales y Habilitar estilos visuales).

Organizar elementos de lista por grupo

Las características de agrupación del control de vista de lista permiten agrupar visualmente conjuntos de elementos relacionados lógicamente. Los grupos se pueden crear en función de las propiedades, los atributos u otras características del elemento. Normalmente, estos grupos se separan en la pantalla mediante un encabezado horizontal que contiene el nombre del grupo. En la captura de pantalla siguiente se muestran los elementos agrupados.

captura de pantalla de un control de vista de lista, con perros en un grupo y gatos en otro grupo

Use la estructura LVGROUP para almacenar información sobre un grupo, como el texto del encabezado y el pie de página, el estado actual del grupo, etc. La API de agrupación incluye mensajes que permiten administrar grupos y elementos de grupo agregando elementos a grupos, agregando grupos a vistas, ordenando elementos de grupo y consultando grupos para el tamaño del elemento y otra información. Por ejemplo, puede establecer y recuperar parámetros de visualización para cada grupo mediante las macros ListView_SetGroupMetrics y ListView_GetGroupMetrics .

La agrupación está disponible en todas las vistas excepto en la vista de lista. No está disponible en los controles que tienen el estilo LVS_OWNERDATA .

Para obtener más información, vea Uso de controles List-View.

Marcas de inserción

Las marcas de inserción muestran a los usuarios dónde se colocarán los elementos arrastrados. Las marcas de inserción se muestran actualmente cuando el usuario arrastra un elemento al menú Inicio o a la barra inicio rápido. La marca de inserción también funciona para las listas que se establecen en autoarrange. Cuando un usuario arrastra un elemento a un punto entre otros dos elementos, la marca de inserción muestra la nueva ubicación esperada del elemento. En la captura de pantalla siguiente se muestra una marca de inserción.

captura de pantalla que muestra una marca de inserción al arrastrar un archivo entre dos otros en un control de vista de lista

Los elementos de la API de marca de inserción permiten colocar las marcas de inserción proporcionando mensajes y marcas que realizan la detección de posicionamientos, que especifican la ubicación y la apariencia de la marca de inserción por elemento, y esa consulta para obtener información sobre el tamaño actual y la apariencia de la marca de inserción.

Consulte también