Compartir a través de

Acerca de los cuadros de lista

  • Artículo

Un control de cuadro de lista contiene una lista simple de la que el usuario puede seleccionar uno o varios elementos. Los cuadros de lista proporcionan flexibilidad limitada en comparación con los controles vista de lista .

Los elementos del cuadro de lista se pueden representar mediante cadenas de texto, mapas de bits o ambos. Si el cuadro de lista no es lo suficientemente grande como para mostrar todos los elementos del cuadro de lista a la vez, el cuadro de lista proporciona una barra de desplazamiento. El usuario se desplaza por los elementos del cuadro de lista y aplica o quita el estado de selección según sea necesario. Al seleccionar un elemento de cuadro de lista se cambia su apariencia visual, normalmente cambiando el texto y los colores de fondo a los especificados por las métricas de sistema operativo pertinentes. Cuando el usuario selecciona o anula la selección de un elemento, el sistema envía un mensaje de notificación a la ventana primaria del cuadro de lista.

Para una aplicación ANSI, el sistema convierte el texto de un cuadro de lista en Unicode mediante la página de códigos CP_ACP . Esto puede causar problemas. Por ejemplo, los caracteres romanos acentuados en un cuadro de lista que no sea Unicode en Windows, la versión japonesa aparecerá ensangrada. Para corregirlo, compile la aplicación como Unicode o use un cuadro de lista dibujado por el propietario.

En esta sección se describen los temas siguientes:

Crear un cuadro de lista

La manera más fácil de crear un cuadro de lista en un cuadro de diálogo es arrastrarlo desde el Cuadro de herramientas de Microsoft Visual Studio al recurso de diálogo. Para crear un cuadro de lista dinámicamente o para crear un cuadro de lista en una ventana distinta de un cuadro de diálogo, use la función CreateWindowEx , especificando la clase de ventana WC_LISTBOX y los estilos de cuadro de lista adecuados.

Tipos y estilos de cuadro de lista

Hay dos tipos de cuadros de lista: selección única (valor predeterminado) y selección múltiple. En un cuadro de lista de selección única, el usuario solo puede seleccionar un elemento a la vez. En un cuadro de lista de selección múltiple, el usuario puede seleccionar más de un elemento a la vez. Para crear un cuadro de lista de selección múltiple, especifique el LBS_MULTIPLESEL o el estilo de LBS_EXTENDEDSEL .

La apariencia y operación de un cuadro de lista se controla mediante estilos de cuadro de lista y estilos de ventana. Estos estilos indican si la lista está ordenada, organizada en varias columnas, dibujada por la aplicación, etc. Las dimensiones y los estilos de un cuadro de lista se definen normalmente en una plantilla de cuadro de diálogo que se incluye en los recursos de una aplicación.

Nota

Para usar estilos visuales con estos controles, una aplicación debe incluir un manifiesto y debe llamar a InitCommonControls al principio del programa. Para obtener información sobre los estilos visuales, vea Estilos visuales. Para obtener información sobre los manifiestos, vea Habilitación de estilos visuales.

Funciones de cuadro de lista

La función DlgDirList reemplaza el contenido de un cuadro de lista por los nombres de unidades, directorios y archivos que coinciden con un conjunto de criterios especificado. La función DlgDirSelectEx recupera la selección actual en un cuadro de lista inicializado por DlgDirList. Estas funciones permiten al usuario seleccionar una unidad, un directorio o un archivo de un cuadro de lista sin escribir la ubicación y el nombre del archivo.

Además, la función GetListBoxInfo devuelve el número de elementos por columna en un cuadro de lista especificado.

Mensajes de notificación de cuadros de lista

Cuando se produce un evento en un cuadro de lista, el cuadro de lista envía un código de notificación, en forma de mensaje de WM_COMMAND , al procedimiento del cuadro de diálogo de la ventana del propietario. Los códigos de notificación del cuadro de lista se envían cuando un usuario selecciona, hace doble clic o cancela un elemento de cuadro de lista; cuando el cuadro de lista recibe o pierde el foco del teclado; y cuando el sistema no puede asignar suficiente memoria para una solicitud de cuadro de lista. Un mensaje de WM_COMMAND contiene el identificador del cuadro de lista en la palabra de orden bajo del parámetro wParam y el código de notificación en la palabra de orden superior. El parámetro lParam contiene el identificador de la ventana de control.

No es necesario un procedimiento de cuadro de diálogo para procesar estos mensajes; el procedimiento de ventana predeterminado los procesa.

Una aplicación debe supervisar y procesar los siguientes códigos de notificación del cuadro de lista.

Código de notificación Descripción
LBN_DBLCLK El usuario hace doble clic en un elemento en el cuadro de lista.
LBN_ERRSPACE El cuadro de lista no puede asignar memoria suficiente para satisfacer una solicitud.
LBN_KILLFOCUS El cuadro de lista pierde el foco del teclado.
LBN_SELCANCEL El usuario cancela la selección de un elemento en el cuadro de lista.
LBN_SELCHANGE La selección de un cuadro de lista está a punto de cambiar.
LBN_SETFOCUS El cuadro de lista recibe el foco del teclado.

Mensajes a cuadros de lista

Un procedimiento de cuadro de diálogo puede enviar mensajes a un cuadro de lista para agregar, eliminar, examinar y cambiar elementos del cuadro de lista. Por ejemplo, un procedimiento de cuadro de diálogo podría enviar un mensaje de LB_ADDSTRING a un cuadro de lista para agregar un elemento y un mensaje de LB_GETSEL para determinar si el elemento está seleccionado. Otros mensajes establecen y recuperan información sobre el tamaño, la apariencia y el comportamiento del cuadro de lista. Por ejemplo, el mensaje de LB_SETHORIZONTALEXTENT establece el ancho desplazable de un cuadro de lista. Un procedimiento de cuadro de diálogo puede enviar cualquier mensaje a un cuadro de lista mediante la función SendMessage o SendDlgItemMessage .

A menudo, su índice hace referencia a un elemento de cuadro de lista, un entero que representa la posición del elemento en el cuadro de lista. El índice del primer elemento de un cuadro de lista es 0, el índice del segundo elemento es 1, etc.

En la tabla siguiente se describe cómo responde el procedimiento de cuadro de lista predefinido a los mensajes del cuadro de lista.

Message Response
LB_ADDFILE Inserta un archivo en un cuadro de lista de directorios rellenado por la función DlgDirList y recupera el índice del cuadro de lista del elemento insertado.
LB_ADDSTRING Agrega una cadena a un cuadro de lista y devuelve su índice.
LB_DELETESTRING Quita una cadena de un cuadro de lista y devuelve el número de cadenas que permanecen en la lista.
LB_DIR Agrega una lista de nombres de archivo a un cuadro de lista y devuelve el índice del último nombre de archivo agregado.
LB_FINDSTRING Devuelve el índice de la primera cadena del cuadro de lista que comienza por una cadena especificada.
LB_FINDSTRINGEXACT Devuelve el índice de la cadena en el cuadro de lista que es igual a una cadena especificada.
LB_GETANCHORINDEX Devuelve el índice del elemento que el mouse seleccionó por última vez.
LB_GETCARETINDEX Devuelve el índice del elemento que tiene el rectángulo de foco.
LB_GETCOUNT Devuelve el número de elementos en el cuadro de lista.
LB_GETCURSEL Devuelve el índice del elemento seleccionado actualmente.
LB_GETHORIZONTALEXTENT Devuelve el ancho desplazable, en píxeles, de un cuadro de lista.
LB_GETITEMDATA Devuelve el valor asociado al elemento especificado.
LB_GETITEMHEIGHT Devuelve el alto, en píxeles, de un elemento de un cuadro de lista.
LB_GETITEMRECT Recupera las coordenadas de cliente del elemento de cuadro de lista especificado.
LB_GETLOCALE Recupera la configuración regional del cuadro de lista. La palabra de orden superior contiene el código de país o región y la palabra de orden bajo contiene el identificador de idioma.
LB_GETSEL Devuelve el estado de selección de un elemento de cuadro de lista.
LB_GETSELCOUNT Devuelve el número de elementos seleccionados en un cuadro de lista de selección múltiple.
LB_GETSELITEMS Crea una matriz de los índices de todos los elementos seleccionados en un cuadro de lista de selección múltiple y devuelve el número total de elementos seleccionados.
LB_GETTEXT Recupera la cadena asociada a un elemento especificado y la longitud de la cadena.
LB_GETTEXTLEN Devuelve la longitud, en caracteres, de la cadena asociada a un elemento especificado.
LB_GETTOPINDEX Devuelve el índice del primer elemento visible en un cuadro de lista.
LB_INITSTORAGE Asigna memoria para el número especificado de elementos y sus cadenas asociadas.
LB_INSERTSTRING Inserta una cadena en un índice especificado en un cuadro de lista.
LB_ITEMFROMPOINT Recupera el índice de base cero del elemento más cercano al punto especificado en un cuadro de lista.
LB_RESETCONTENT Quita todos los elementos de un cuadro de lista.
LB_SELECTSTRING Selecciona la primera cadena que encuentra que coincide con un prefijo especificado.
LB_SELITEMRANGE Selecciona un intervalo de elementos especificado en un cuadro de lista.
LB_SELITEMRANGEEX Selecciona un intervalo de elementos especificado si el índice del primer elemento del intervalo es menor que el índice del último elemento del intervalo. Cancela la selección en el intervalo si el índice del primer elemento es mayor que el último.
LB_SETANCHORINDEX Establece el elemento que el mouse seleccionó por última vez en un elemento especificado.
LB_SETCARETINDEX Establece el rectángulo de foco en un elemento de cuadro de lista especificado.
LB_SETCOLUMNWIDTH Establece el ancho, en píxeles, de todas las columnas de un cuadro de lista.
LB_SETCOUNT Establece el número de elementos de un cuadro de lista.
LB_SETCURSEL Selecciona un elemento de cuadro de lista especificado.
LB_SETHORIZONTALEXTENT Establece el ancho desplazable, en píxeles, de un cuadro de lista.
LB_SETITEMDATA Asocia un valor a un elemento de cuadro de lista.
LB_SETITEMHEIGHT Establece el alto, en píxeles, de un elemento o elementos de un cuadro de lista.
LB_SETLOCALE Establece la configuración regional de un cuadro de lista y devuelve el identificador de configuración regional anterior.
LB_SETSEL Selecciona un elemento en un cuadro de lista de selección múltiple.
LB_SETTABSTOPS Establece las tabulaciones en las especificadas en una matriz especificada.
LB_SETTOPINDEX Desplaza el cuadro de lista para que el elemento especificado esté en la parte superior del intervalo visible.

Procesamiento de mensajes de ventana predeterminado

El procedimiento de ventana de la clase de ventana de cuadro de lista predefinido lleva a cabo el procesamiento predeterminado de todos los mensajes que el cuadro de lista no procesa. Cuando el procedimiento de cuadro de lista devuelve FALSE para un mensaje, el procedimiento de ventana predefinido comprueba el mensaje y realiza acciones predeterminadas, como se muestra en la tabla siguiente.

Message Acción predeterminada
WM_CHAR Mueve la selección al primer elemento que comienza con el carácter escrito por el usuario. Si el cuadro de lista tiene el estiloL BS_OWNERDRAW , no se produce ninguna acción. Varios caracteres que se escriben en un intervalo corto se tratan como un grupo y se selecciona el primer elemento que comienza con esa serie de caracteres.
WM_CREATE Crea un cuadro de lista vacío.
WM_DESTROY Destruye el cuadro de lista y libera los recursos que usa.
Pasa el mensaje al procedimiento del cuadro de diálogo o al proceso de ventana principal.
WM_ENABLE Si el control está visible, invalida el rectángulo para que las cadenas se puedan pintar de color gris.
WM_ERASEBKGND Borra el fondo de un cuadro de lista. Si el cuadro de lista tiene el estiloL BS_OWNERDRAW , el fondo no se borra.
WM_GETDLGCODE Devuelve DLGC_WANTARROWS | DLGC_WANTCHARS, que indica que el procedimiento de cuadro de lista predeterminado procesa las teclas de dirección y WM_CHAR mensajes.
WM_GETFONT Devuelve un identificador a la fuente actual del cuadro de lista.
WM_HSCROLL Desplaza el cuadro de lista horizontalmente.
WM_KEYDOWN Procesa las claves virtuales para desplazarse. La clave virtual es el índice del elemento al que se va a mover el símbolo de intercalación. No se cambia la selección.
WM_KILLFOCUS Desactiva el símbolo de intercalación y lo destruye. Envía un código de notificación LBN_KILLFOCUS al propietario del cuadro de lista.
WM_LBUTTONDBLCLK Realiza un seguimiento del mouse en el área cliente del cuadro de lista. Esto permite al usuario cancelar una selección si el botón del mouse se libera fuera del área cliente del cuadro de lista.
WM_LBUTTONDOWN Realiza un seguimiento del mouse en el área cliente del cuadro de lista. Esto permite al usuario cancelar una selección si el botón del mouse se libera fuera del área cliente del cuadro de lista.
WM_LBUTTONUP Realiza un seguimiento del mouse en el área cliente del cuadro de lista. Esto permite al usuario cancelar una selección si el botón del mouse se suelta fuera del área cliente del cuadro de lista.
WM_MOUSEMOVE Realiza un seguimiento del mouse en el área cliente del cuadro de lista. Esto permite al usuario cancelar una selección si el botón del mouse se suelta fuera del área cliente del cuadro de lista.
WM_PAINT Realiza una operación de pintura subclase mediante el identificador de cuadro de lista para el contexto del dispositivo (DC).
WM_SETFOCUS Activa el símbolo de intercalación y envía un código de notificación LBN_SETFOCUS al propietario del cuadro de lista.
WM_SETFONT Establece una nueva fuente para el cuadro de lista.
WM_SETREDRAW Establece o borra la marca de volver a dibujar según el valor de wParam.
WM_SIZE Cambia el tamaño del cuadro de lista a un número entero de elementos.
WM_VSCROLL Desplaza verticalmente el cuadro de lista.

El procedimiento de cuadro de lista predefinido pasa todos los demás mensajes a DefWindowProc para el procesamiento predeterminado.

cuadros de lista de Owner-Drawn

Una aplicación puede crear un cuadro de lista dibujado por el propietario para asumir la responsabilidad de pintar elementos de lista. La ventana principal o el cuadro de diálogo de un cuadro de lista dibujado por el propietario (su propietario) recibe WM_DRAWITEM mensajes cuando es necesario pintar una parte del cuadro de lista. Un cuadro de lista dibujado por el propietario puede mostrar información distinta de las cadenas de texto, o además de ellas.

El propietario de un cuadro de lista dibujado por el propietario debe procesar el mensaje WM_DRAWITEM . Este mensaje se envía cada vez que se debe volver a dibujar una parte del cuadro de lista. Es posible que el propietario necesite procesar otros mensajes, en función de los estilos especificados para el cuadro de lista.

Una aplicación puede crear un cuadro de lista dibujado por el propietario especificando el estilo LBS_OWNERDRAWFIXED o LBS_OWNERDRAWVARIABLE . Si todos los elementos de lista del cuadro de lista tienen el mismo alto, como cadenas o iconos, una aplicación puede usar el estilo LBS_OWNERDRAWFIXED . Si los elementos de lista tienen un alto variable (por ejemplo, mapas de bits de tamaño diferente), una aplicación puede usar el estilo LBS_OWNERDRAWVARIABLE .

El propietario de un cuadro de lista dibujado por el propietario puede procesar un mensaje de WM_MEASUREITEM para especificar las dimensiones de los elementos de lista. Si la aplicación crea el cuadro de lista mediante el estilo LBS_OWNERDRAWFIXED , el sistema envía el mensaje WM_MEASUREITEM solo una vez. Las dimensiones especificadas por el propietario se usan para todos los elementos de lista. Si se usa el estilo LBS_OWNERDRAWVARIABLE , el sistema envía un mensaje WM_MEASUREITEM para cada elemento de lista que se agrega al cuadro de lista. El propietario puede determinar o establecer el alto de un elemento de lista en cualquier momento mediante los mensajes LB_GETITEMHEIGHT y LB_SETITEMHEIGHT , respectivamente.

Si la información que se muestra en un cuadro de lista dibujado por el propietario incluye texto, una aplicación puede realizar un seguimiento del texto de cada elemento de lista especificando el estilo LBS_HASSTRINGS . Los cuadros de lista con el estilo LBS_SORT se ordenan en función de este texto. Si se ordena un cuadro de lista, pero no es del estilo LBS_HASSTRINGS , el propietario debe procesar el mensaje de WM_COMPAREITEM .

En un cuadro de lista dibujado por el propietario, el propietario debe realizar un seguimiento de los elementos de lista que contengan información distinta o además del texto. Una manera cómoda de hacerlo es guardar el identificador en la información como datos de elemento mediante el mensaje LB_SETITEMDATA . Para liberar objetos de datos asociados a elementos de un cuadro de lista, el propietario puede procesar el mensaje de WM_DELETEITEM .

Para obtener un ejemplo de un cuadro de lista dibujado por el propietario, vea How to Create an Owner-Drawn List Box.

Arrastrar cuadros de lista

Un cuadro de lista de arrastrar es un tipo especial de cuadro de lista que permite al usuario arrastrar elementos de una posición a otra. Una aplicación puede usar un cuadro de lista de arrastrar para mostrar cadenas en una secuencia determinada y permitir que el usuario cambie la secuencia arrastrando los elementos a la posición.

Crear cuadros de lista de arrastrar

Los cuadros de lista de arrastrar tienen los mismos estilos de ventana y procesan los mismos mensajes que los cuadros de lista estándar. Para crear un cuadro de lista de arrastrar, primero cree un cuadro de lista estándar y, a continuación, llame a la función MakeDragList . Para convertir un cuadro de lista en un cuadro de diálogo en un cuadro de lista de arrastrar, puede llamar a MakeDragList cuando se procese el mensaje de WM_INITDIALOG.

Arrastrar mensajes de cuadro de lista

Un cuadro de lista de arrastrar notifica a la ventana primaria de los eventos de arrastre mediante el envío de un mensaje de lista de arrastre. La ventana primaria debe procesar el mensaje de lista de arrastre.

El cuadro de lista de arrastrar registra este mensaje cuando se llama a la función MakeDragList . Para recuperar el identificador de mensaje (valor numérico) del mensaje de lista de arrastre, llame a la función RegisterWindowMessage y especifique el valor DRAGLISTMSGSTRING.

El parámetro wParam del mensaje de lista de arrastre es el identificador de control del cuadro de lista de arrastrar. El parámetro lParam es la dirección de una estructura DRAGLISTINFO , que contiene el código de notificación para el evento de arrastre y otra información. El valor devuelto del mensaje depende de la notificación.

Arrastrar códigos de notificación de cuadro de lista

El código de notificación de lista de arrastre, identificado por el miembro uNotification de la estructura DRAGLISTINFO incluida con el mensaje de lista de arrastre, puede ser DL_BEGINDRAG, DL_DRAGGING, DL_CANCELDRAG o DL_DROPPED.

El código de notificación DL_BEGINDRAG se envía cuando el cursor está en un elemento de lista y el usuario hace clic en el botón izquierdo del mouse. La ventana primaria puede devolver TRUE para iniciar la operación de arrastre o FALSE para no permitir el arrastre. De este modo, la ventana primaria puede habilitar el arrastre para algunos elementos de lista y deshabilitarla para otras personas. Puede determinar qué elemento de lista se encuentra en la ubicación especificada mediante la función LBItemFromPt .

Si el arrastre está en vigor, el código de notificación de DL_DRAGGING se envía cada vez que se mueve el mouse o a intervalos regulares si el mouse no se mueve. La ventana primaria debe determinar primero el elemento de lista bajo el cursor mediante LBItemFromPt y, a continuación, dibujar el icono de inserción mediante la función DrawInsert . Al especificar TRUE para el parámetro bAutoScroll de LBItemFromPt, puede hacer que el cuadro de lista se desplácese por una línea si el cursor está por encima o por debajo de su área de cliente. El valor devuelto para esta notificación especifica el tipo de cursor del mouse que debe establecer el cuadro de lista de arrastrar.

El DL_CANCELDRAG código de notificación se envía si el usuario cancela una operación de arrastre haciendo clic en el botón derecho del mouse o presionando la tecla ESC. El código de notificación DL_DROPPED se envía si el usuario completa una operación de arrastrar liberando el botón izquierdo del mouse, incluso si el cursor no está sobre un elemento de lista. El cuadro de lista de arrastrar libera la captura del mouse antes de enviar cualquiera de las notificaciones. El valor devuelto de estas dos notificaciones se omite. Arrastrar lista