Clase `CListBox`

Artículo
06/16/2023

Proporciona la funcionalidad de un cuadro de lista de Windows.

Sintaxis

class CListBox : public CWnd

Miembros

Constructores públicos

Nombre	Descripción
`CListBox::CListBox`	Construye un objeto `CListBox`.

Métodos públicos

Nombre	Descripción
`CListBox::AddString`	Agrega una cadena a un cuadro de lista.
`CListBox::CharToItem`	Invalide para proporcionar un control personalizado de `WM_CHAR` para los cuadros de lista dibujados por el propietario que no tienen cadenas.
`CListBox::CompareItem`	Lo llama el marco para determinar la posición de un nuevo elemento en un cuadro de lista ordenado dibujado por el propietario.
`CListBox::Create`	Crea el cuadro de lista de Windows y lo adjunta al objeto `CListBox`.
`CListBox::DeleteItem`	Lo llama el marco cuando el usuario elimina un elemento de un cuadro de lista dibujado por el propietario.
`CListBox::DeleteString`	Elimina una cadena de un cuadro de lista.
`CListBox::Dir`	Agrega nombres de archivo, unidades o ambos desde el directorio actual a un cuadro de lista.
`CListBox::DrawItem`	Lo llama el marco cuando cambia un aspecto visual de un cuadro de lista dibujado por el propietario.
`CListBox::FindString`	Busca una cadena en un cuadro de lista.
`CListBox::FindStringExact`	Busca la primera cadena de cuadro de lista que coincide con una cadena especificada.
`CListBox::GetAnchorIndex`	Recupera el índice de base cero del elemento de anclaje actual en un cuadro de lista.
`CListBox::GetCaretIndex`	Determina el índice del elemento que tiene el rectángulo de foco en un cuadro de lista de selección múltiple.
`CListBox::GetCount`	Devuelve el número de cadenas de un cuadro de lista.
`CListBox::GetCurSel`	Devuelve el índice de base cero de la cadena seleccionada actualmente en un cuadro de lista.
`CListBox::GetHorizontalExtent`	Devuelve el ancho en píxeles que un cuadro de lista puede desplazar horizontalmente.
`CListBox::GetItemData`	Devuelve un valor asociado al elemento de cuadro de lista.
`CListBox::GetItemDataPtr`	Devuelve un puntero a un elemento de cuadro de lista.
`CListBox::GetItemHeight`	Determina el alto de los elementos de un cuadro de lista.
`CListBox::GetItemRect`	Devuelve el rectángulo delimitador del elemento de cuadro de lista tal y como se muestra actualmente.
`CListBox::GetListBoxInfo`	Recupera el número de elementos por columna.
`CListBox::GetLocale`	Recupera el identificador de configuración regional de un cuadro de lista.
`CListBox::GetSel`	Devuelve el estado de selección de un elemento de cuadro de lista.
`CListBox::GetSelCount`	Devuelve el número de cadenas seleccionadas actualmente en un cuadro de lista de selección múltiple.
`CListBox::GetSelItems`	Devuelve los índices de las cadenas seleccionadas actualmente en un cuadro de lista.
`CListBox::GetText`	Copia un elemento de cuadro de lista en un búfer.
`CListBox::GetTextLen`	Devuelve la longitud en bytes de un elemento de cuadro de lista.
`CListBox::GetTopIndex`	Devuelve el índice de la primera cadena visible en un cuadro de lista.
`CListBox::InitStorage`	Preasigna bloques de memoria para los elementos y cadenas del cuadro de lista.
`CListBox::InsertString`	Inserta una cadena en una ubicación específica en un cuadro de lista.
`CListBox::ItemFromPoint`	Devuelve el índice del elemento de cuadro de lista más próximo a un punto.
`CListBox::MeasureItem`	Lo llama el marco cuando se crea un cuadro de lista dibujado por el propietario para determinar las dimensiones del cuadro de lista.
`CListBox::ResetContent`	Borra todas las entradas de un cuadro de lista.
`CListBox::SelectString`	Busca y selecciona una cadena en un cuadro de lista de selección única.
`CListBox::SelItemRange`	Selecciona o anula la selección de un rango de cadenas en un cuadro de lista de selección múltiple.
`CListBox::SetAnchorIndex`	Establece el delimitador en un cuadro de lista de selección múltiple para comenzar una selección extendida.
`CListBox::SetCaretIndex`	Establece el rectángulo de foco en el elemento del índice especificado en un cuadro de lista de selección múltiple.
`CListBox::SetColumnWidth`	Establece el ancho de columna de un cuadro de lista de columnas múltiples.
`CListBox::SetCurSel`	Selecciona una cadena de cuadro de lista.
`CListBox::SetHorizontalExtent`	Establece el ancho en píxeles que un cuadro de lista puede desplazar horizontalmente.
`CListBox::SetItemData`	Establece un valor asociado al elemento de cuadro de lista.
`CListBox::SetItemDataPtr`	Establece un puntero al elemento de cuadro de lista.
`CListBox::SetItemHeight`	Establece el alto de los elementos de un cuadro de lista.
`CListBox::SetLocale`	Establece el identificador de configuración regional de un cuadro de lista.
`CListBox::SetSel`	Selecciona o anula la selección de un elemento de cuadro de lista en un cuadro de lista de selección múltiple.
`CListBox::SetTabStops`	Establece las posiciones de tabulación en un cuadro de lista.
`CListBox::SetTopIndex`	Establece el índice de base cero de la primera cadena visible en un cuadro de lista.
`CListBox::VKeyToItem`	Invalide para proporcionar un control personalizado de `WM_KEYDOWN` para los cuadros de lista con el conjunto de estilos `LBS_WANTKEYBOARDINPUT`.

Comentarios

Un cuadro de lista muestra una lista de elementos, como nombres de archivo, que el usuario puede ver y seleccionar.

En un cuadro de lista de selección única, el usuario solo puede seleccionar un elemento. En un cuadro de lista de selección múltiple, se puede seleccionar un rango de elementos. Cuando el usuario selecciona un elemento, se resalta y el cuadro de lista envía un mensaje de notificación a la ventana primaria.

Puede crear un cuadro de lista a partir de una plantilla de diálogo o directamente en el código. Para crearlo directamente, construya el objeto CListBox y, a continuación, llame a la función miembro Create para crear el control de cuadro de lista de Windows y adjuntarlo al objeto CListBox. Para usar un cuadro de lista en una plantilla de diálogo, declare una variable de cuadro de lista en la clase de cuadro de diálogo y, a continuación, use DDX_Control en la función DoDataExchange de la clase del cuadro de diálogo para conectar la variable miembro al control. (Esto se hace automáticamente al agregar una variable de control a la clase de cuadro de diálogo).

La construcción puede ser un proceso de un solo paso en una clase derivada de CListBox. Escriba un constructor para la clase derivada y llame a Create desde dentro del constructor.

Si desea controlar los mensajes de notificación de Windows enviados por un cuadro de lista a su elemento primario (normalmente una clase derivada de CDialog), agregue una entrada de mapa de mensajes y una función miembro del controlador de mensajes a la clase primaria para cada mensaje.

Cada entrada de asignación de mensajes tiene la siguiente forma:

ON_Notification( id, memberFxn )

donde id especifica el id. de ventana secundario del control de cuadro de lista que envía la notificación y memberFxn es el nombre de la función miembro primaria que ha escrito para controlar la notificación.

El prototipo de función principal es el siguiente:

afx_msg void memberFxn( );

A continuación se muestra una lista de posibles entradas de mapa de mensajes y una descripción de los casos en los que se enviarían al elemento primario:

ON_LBN_DBLCLK El usuario hace doble clic en una cadena en un cuadro de lista. Solo un cuadro de lista que tenga el estilo LBS_NOTIFY enviará este mensaje de notificación.
ON_LBN_ERRSPACE El cuadro de lista no puede asignar memoria suficiente para satisfacer la solicitud.
ON_LBN_KILLFOCUS El cuadro de lista pierde el foco de entrada.
ON_LBN_SELCANCEL Se cancela la selección del cuadro de lista actual. Este mensaje solo se envía cuando un cuadro de lista tiene el estilo LBS_NOTIFY.
ON_LBN_SELCHANGE La selección en el cuadro de lista ha cambiado. Esta notificación no se envía si la función miembro CListBox::SetCurSel cambia la selección. Esta notificación solo se aplica a un cuadro de lista que tenga el estilo LBS_NOTIFY. El mensaje de notificación LBN_SELCHANGE se envía para un cuadro de lista de selección múltiple cada vez que el usuario presiona una tecla de dirección, incluso si la selección no cambia.
ON_LBN_SETFOCUS El cuadro de lista recibe el foco de entrada.
ON_WM_CHARTOITEM Un cuadro de lista dibujado por el propietario que no tiene ninguna cadena recibe un mensaje WM_CHAR.
ON_WM_VKEYTOITEM Un cuadro de lista con el estilo LBS_WANTKEYBOARDINPUT recibe un mensaje WM_KEYDOWN.

Si crea un objeto CListBox dentro de un cuadro de diálogo (mediante un recurso de diálogo), el objeto CListBox se destruye automáticamente cuando el usuario cierra el cuadro de diálogo.

Si crea un objeto CListBox dentro de una ventana, es posible que deba destruir el objeto CListBox. Si crea el objeto CListBox en la pila, se destruye automáticamente. Si crea el objeto CListBox en el montón mediante la función new, debe llamar a delete en el objeto para destruirlo cuando el usuario cierre la ventana primaria.

Si asigna cualquier memoria en el objeto CListBox, invalide el destructor CListBoxpara eliminar la asignación.

Jerarquía de herencia

CObject

CCmdTarget

CWnd

CListBox

Requisitos

Encabezado: afxwin.h

`CListBox::AddString`

Agrega una cadena a un cuadro de lista.

int AddString(LPCTSTR lpszItem);

Parámetros

lpszItem
Apunta a la cadena terminada en null que se va a agregar.

Valor devuelto

Índice de base cero de la cadena en el cuadro de lista. El valor devuelto es LB_ERR si se produce un error; el valor devuelto es LB_ERRSPACE si no hay suficiente espacio disponible para almacenar la nueva cadena.

Comentarios

Si el cuadro de lista no se creó con el estilo LBS_SORT, la cadena se agrega al final de la lista. De lo contrario, la cadena se inserta en la lista y la lista se ordena. Si el cuadro de lista se creó con el estilo LBS_SORT, pero no con el estilo LBS_HASSTRINGS, el marco ordena la lista por una o varias llamadas a la función miembro CompareItem.

Use InsertString para insertar una cadena en una ubicación específica dentro del cuadro de lista.

Ejemplo

// Add 10 items to the list box.
CString str;
for (int i = 0; i < 10; i++)
{
   str.Format(_T("item string %d"), i);
   m_myListBox.AddString(str);
}

`CListBox::CharToItem`

Lo llama el marco cuando la ventana primaria del cuadro de lista recibe un mensaje WM_CHARTOITEM del cuadro de lista.

virtual int CharToItem(
    UINT nKey,
    UINT nIndex);

Parámetros

nKey
Código ANSI del carácter que el usuario ha escrito.

nIndex
Posición actual del símbolo de intercalación del cuadro de lista.

Valor devuelto

Devuelve -1 o -2 para ninguna acción adicional o un número no negativo para especificar un índice de un elemento de cuadro de lista en el que se va a realizar la acción predeterminada para la pulsación de tecla. La implementación predeterminada devuelve -1.

Comentarios

El cuadro de lista envía el mensaje WM_CHARTOITEM cuando recibe un mensaje WM_CHAR, pero solo si el cuadro de lista cumple todos estos criterios:

Es un cuadro de lista dibujado por el propietario.
No tiene el estilo LBS_HASSTRINGS establecido.
Tiene al menos un elemento.

Nunca debe llamar a esta función usted mismo. Invalide esta función para proporcionar su propio control personalizado de los mensajes de teclado.

En la invalidación, debe devolver un valor para indicar al marco qué acción ha realizado. Un valor devuelto de -1 o -2 indica que ha controlado todos los aspectos de la selección del elemento y no quiere ninguna acción adicional por parte del cuadro de lista. Antes de devolver -1 o -2, puede establecer la selección o mover el símbolo de intercalación o ambos. Para establecer la selección, use SetCurSel o SetSel. Para mover el símbolo de intercalación, use SetCaretIndex.

Un valor devuelto de 0 o superior especifica el índice de un elemento en el cuadro de lista e indica que el cuadro de lista debe realizar la acción predeterminada para la pulsación de teclas en el elemento especificado.

Ejemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example moves the caret down one item on a numeric key and up one item
// on an alphabetic key. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::CharToItem(UINT nChar, UINT nIndex)
{
   // On a numeric key, move the caret up one item.
   if (isdigit(nChar) && (nIndex > 0))
   {
      SetCaretIndex(nIndex - 1);
   }
   // On an alphabetic key, move the caret down one item.
   else if (isalpha(nChar) && (nIndex < (UINT)GetCount()))
   {
      SetCaretIndex(nIndex + 1);
   }

   // Do not perform any default processing.
   return -1;
}

`CListBox::CListBox`

Construye un objeto CListBox.

CListBox();

Comentarios

El objeto CListBox se construye en dos pasos. En primer lugar, llame al constructor ClistBox y, a continuación, llame a Create, que inicializa el cuadro de lista de Windows y lo adjunta a CListBox.

Ejemplo

// Declare a local CListBox object.
CListBox myListBox;

// Declare a dynamic CListBox object.
CListBox *pmyListBox = new CListBox;

`CListBox::CompareItem`

Lo llama el marco para determinar la posición relativa de un nuevo elemento en un cuadro de lista ordenado dibujado por el propietario.

virtual int CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct);

Parámetros

lpCompareItemStruct
Puntero largo a una estructura COMPAREITEMSTRUCT.

Valor devuelto

Indica la posición relativa de los dos elementos descritos en la estructura COMPAREITEMSTRUCT. Puede ser cualquiera de los siguientes valores:

Valor	Significado
-1	El elemento 1 se sitúa antes del elemento 2.
0	El elemento 1 y el elemento 2 se ordenan igual.
1	El elemento 1 se ordena después del elemento 2.

Consulte CWnd::OnCompareItem para obtener una descripción de la estructura COMPAREITEMSTRUCT.

Comentarios

De manera predeterminada, esta función miembro no hace nada. Si crea un cuadro de lista dibujado por el propietario con el estilo LBS_SORT, debe invalidar esta función miembro para ayudar al marco a ordenar los nuevos elementos agregados al cuadro de lista.

Ejemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example compares two items using _tcscmp to sort items in reverse
// alphabetical order. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct)
{
   ASSERT(lpCompareItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText1 = (LPCTSTR)lpCompareItemStruct->itemData1;
   ASSERT(lpszText1 != NULL);
   LPCTSTR lpszText2 = (LPCTSTR)lpCompareItemStruct->itemData2;
   ASSERT(lpszText2 != NULL);

   return _tcscmp(lpszText2, lpszText1);
}

`CListBox::Create`

Crea el cuadro de lista de Windows y lo adjunta al objeto CListBox.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parámetros

dwStyle
Especifica el estilo del cuadro de lista. Aplique cualquier combinación de estilos de cuadro de lista al cuadro.

rect
Especifica el tamaño y la posición del cuadro de lista. Puede ser un objeto CRect o una estructura RECT.

pParentWnd
Especifica la ventana primaria del cuadro de lista (normalmente un objeto CDialog). Este valor no debe ser NULL.

nID
Especifica el id. de control del cuadro de lista.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

El objeto CListBox se construye en dos pasos. En primer lugar, llame al constructor y, a continuación, llame a Create, que inicializa el cuadro de lista de Windows y lo adjunta al objeto CListBox.

Cuando Create se ejecuta, Windows envía los mensajes WM_NCCREATE, WM_CREATE, WM_NCCALCSIZE y WM_GETMINMAXINFO al control de cuadro de lista.

Estos mensajes se controlan de forma predeterminada mediante las funciones miembro OnNcCreate, OnCreate, OnNcCalcSize y OnGetMinMaxInfo de la clase base CWnd. Para ampliar el control de mensajes predeterminado, derive una clase de CListBox, agregue una asignación de mensajes a la nueva clase e invalide las funciones miembro del controlador de mensajes anteriores. Invalide OnCreate, por ejemplo, para realizar la inicialización necesaria para una nueva clase.

Aplique los siguientes estilos de ventana a un control de cuadro de lista.

WS_CHILD Siempre
WS_VISIBLE Normalmente
WS_DISABLED Raramente
WS_VSCROLL Para agregar una barra de desplazamiento vertical
WS_HSCROLL Para agregar una barra de desplazamiento horizontal
WS_GROUP Para agrupar controles
WS_TABSTOP Para permitir el tabulador a este control

Ejemplo

// pParentWnd is a pointer to the parent window.
m_myListBox.Create(WS_CHILD | WS_VISIBLE | LBS_STANDARD | WS_HSCROLL,
                   CRect(10, 10, 200, 200), pParentWnd, IDC_MYLISTBOX);

`CListBox::DeleteItem`

Lo llama el marco cuando el usuario elimina un elemento de un objeto CListBox dibujado por el propietario o destruye el cuadro de lista.

virtual void DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct);

Parámetros

lpDeleteItemStruct
Puntero largo a una estructura de Windows DELETEITEMSTRUCT que contiene información sobre el elemento eliminado.

Comentarios

La implementación predeterminada de esta función no hace nada. Invalide esta función para volver a dibujar un cuadro de lista dibujado por el propietario según sea necesario.

Consulte CWnd::OnDeleteItem para obtener una descripción de la estructura DELETEITEMSTRUCT.

Ejemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example simply frees the item's text. The list box control was created
// with the following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct)
{
   ASSERT(lpDeleteItemStruct->CtlType == ODT_LISTBOX);
   LPVOID lpszText = (LPVOID)lpDeleteItemStruct->itemData;
   ASSERT(lpszText != NULL);

   free(lpszText);

   CListBox::DeleteItem(lpDeleteItemStruct);
}

`CListBox::DeleteString`

Elimina el elemento en posición nIndex del cuadro de lista.

int DeleteString(UINT nIndex);

Parámetros

nIndex
Especifica el índice de base cero de la cadena que se va a eliminar.

Valor devuelto

Recuento de las cadenas restantes en la lista. El valor devuelto es LB_ERR si nIndex especifica un índice mayor que el número de elementos de la lista.

Comentarios

Todos los elementos siguientes a nIndex ahora bajan una posición. Por ejemplo, si un cuadro de lista contiene dos elementos, la eliminación del primer elemento hará que el elemento restante esté ahora en la primera posición. nIndex=0 para el elemento en la primera posición.

Ejemplo

// Delete every other item from the list box.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.DeleteString(i);
}

`CListBox::Dir`

Agrega una lista de nombres de archivo, unidades o ambos a un cuadro de lista.

int Dir(
    UINT attr,
    LPCTSTR lpszWildCard);

Parámetros

attr
Puede ser cualquier combinación de los valores enum descritos en CFile::GetStatus o cualquier combinación de los valores siguientes:

Valor	Significado
0x0000	Es posible leer el archivo o escribir en él.
0x0001	Es posible leer el archivo pero no escribir en él.
0x0002	El archivo está oculto y no aparece en una lista de directorios.
0x0004	El archivo es un archivo del sistema.
0x0010	El nombre especificado por `lpszWildCard` especifica un directorio.
0x0020	El archivo se ha archivado.
0x4000	Incluya todas las unidades que coincidan con el nombre especificado por `lpszWildCard`.
0x8000	Marca exclusiva. Si se establece la marca exclusiva, solo se enumeran los archivos del tipo especificado. De lo contrario, los archivos del tipo especificado se enumeran además de los archivos “normales”.

lpszWildCard
Apunta a una cadena de especificación de archivo. La cadena puede contener caracteres comodín (por ejemplo, *.*).

Valor devuelto

Índice de base cero del último nombre de archivo agregado a la lista. El valor devuelto es LB_ERR si se produce un error; el valor devuelto es LB_ERRSPACE si no hay suficiente espacio disponible para almacenar las nuevas cadenas.

Ejemplo

// Add all the files and directories in the windows directory.
TCHAR lpszWinPath[MAX_PATH], lpszOldPath[MAX_PATH];
::GetWindowsDirectory(lpszWinPath, MAX_PATH);

::GetCurrentDirectory(MAX_PATH, lpszOldPath);
::SetCurrentDirectory(lpszWinPath);

m_myListBox.ResetContent();
m_myListBox.Dir(DDL_READWRITE | DDL_DIRECTORY, _T("*.*"));

::SetCurrentDirectory(lpszOldPath);

`CListBox::DrawItem`

Lo llama el marco cuando cambia un aspecto visual de un cuadro de lista dibujado por el propietario.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parámetros

lpDrawItemStruct
Puntero largo a una estructura DRAWITEMSTRUCT que contiene información sobre el tipo de dibujo necesario.

Comentarios

Los miembros itemAction y itemState de la estructura DRAWITEMSTRUCT definen la acción de dibujo que se va a realizar.

De manera predeterminada, esta función miembro no hace nada. Invalida esta función miembro para implementar el dibujo de un objeto CListBox dibujado por el propietario. La aplicación debe restaurar todos los objetos de interfaz de dispositivo gráfico (GDI) seleccionados para el contexto de presentación proporcionado en lpDrawItemStruct antes de que finalice esta función miembro.

Consulte CWnd::OnDrawItem para obtener una descripción de la estructura DRAWITEMSTRUCT.

Ejemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example draws an item's text centered vertically and horizontally. The
// list box control was created with the following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct)
{
   ASSERT(lpDrawItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText = (LPCTSTR)lpDrawItemStruct->itemData;
   ASSERT(lpszText != NULL);
   CDC dc;

   dc.Attach(lpDrawItemStruct->hDC);

   // Save these value to restore them when done drawing.
   COLORREF crOldTextColor = dc.GetTextColor();
   COLORREF crOldBkColor = dc.GetBkColor();

   // If this item is selected, set the background color
   // and the text color to appropriate values. Also, erase
   // rect by filling it with the background color.
   if ((lpDrawItemStruct->itemAction | ODA_SELECT) &&
       (lpDrawItemStruct->itemState & ODS_SELECTED))
   {
      dc.SetTextColor(::GetSysColor(COLOR_HIGHLIGHTTEXT));
      dc.SetBkColor(::GetSysColor(COLOR_HIGHLIGHT));
      dc.FillSolidRect(&lpDrawItemStruct->rcItem,
                       ::GetSysColor(COLOR_HIGHLIGHT));
   }
   else
   {
      dc.FillSolidRect(&lpDrawItemStruct->rcItem, crOldBkColor);
   }

   // If this item has the focus, draw a red frame around the
   // item's rect.
   if ((lpDrawItemStruct->itemAction | ODA_FOCUS) &&
       (lpDrawItemStruct->itemState & ODS_FOCUS))
   {
      CBrush br(RGB(255, 0, 0));
      dc.FrameRect(&lpDrawItemStruct->rcItem, &br);
   }

   // Draw the text.
   dc.DrawText(
       lpszText,
       (int)_tcslen(lpszText),
       &lpDrawItemStruct->rcItem,
       DT_CENTER | DT_SINGLELINE | DT_VCENTER);

   // Reset the background color and the text color back to their
   // original values.
   dc.SetTextColor(crOldTextColor);
   dc.SetBkColor(crOldBkColor);

   dc.Detach();
}

`CListBox::FindString`

Busca la primera cadena en un cuadro de lista que contiene el prefijo especificado sin cambiar la selección del cuadro de lista.

int FindString(
    int nStartAfter,
    LPCTSTR lpszItem) const;

Parámetros

nStartAfter
Contiene el índice de base cero del elemento situado delante del primer elemento que se va a buscar. Cuando la búsqueda llega a la parte inferior del cuadro de lista, continúa de nuevo desde la parte superior del cuadro de lista al elemento especificado por nStartAfter. Si nStartAfter es -1, se busca en todo el cuadro de lista desde el principio.

lpszItem
Apunta a la cadena terminada en null que contiene el prefijo que se va a buscar. La búsqueda es independiente de mayúsculas y minúsculas, por lo que esta cadena puede contener cualquier combinación de letras mayúsculas y minúsculas.

Valor devuelto

Índice de base cero del elemento coincidente o LB_ERR si la búsqueda no se realizó correctamente.

Comentarios

Use la función miembro SelectString para buscar y seleccionar una cadena.

Ejemplo

// The string to match.
LPCTSTR lpszmyString = _T("item");

// Delete all items that begin with the specified string.
int nIndex = 0;
while ((nIndex = m_myListBox.FindString(nIndex, lpszmyString)) != LB_ERR)
{
   m_myListBox.DeleteString(nIndex);
}

`CListBox::FindStringExact`

Busca la primera cadena de cuadro de lista que coincide con la cadena especificada en lpszFind.

int FindStringExact(
    int nIndexStart,
    LPCTSTR lpszFind) const;

Parámetros

nIndexStart
Especifica el índice de base cero del elemento situado delante del primer elemento que se va a buscar. Cuando la búsqueda llega a la parte inferior del cuadro de lista, continúa de nuevo desde la parte superior del cuadro de lista al elemento especificado por nIndexStart. Si nIndexStart es -1, se busca en todo el cuadro de lista desde el principio.

lpszFind
Apunta a la cadena terminada en null que se va a buscar. Esta cadena puede contener un nombre de archivo completo, incluida la extensión. La búsqueda no distingue entre mayúsculas y minúsculas, por lo que la cadena puede contener cualquier combinación de letras mayúsculas y minúsculas.

Valor devuelto

Índice del elemento coincidente o LB_ERR si la búsqueda no se realizó correctamente.

Comentarios

Si el cuadro de lista se creó con un estilo dibujado por el propietario, pero sin el estilo LBS_HASSTRINGS, la función miembro FindStringExact intenta hacer coincidir el valor de doble palabra con el valor de lpszFind.

Ejemplo

// The string to match.
LPCTSTR lpszmyString = _T("item string 3");

// Delete all items that exactly match the specified string.
int nIndex = 0;
while ((nIndex = m_myListBox.FindStringExact(nIndex, lpszmyString)) != LB_ERR)
{
   m_myListBox.DeleteString(nIndex);
}

`CListBox::GetAnchorIndex`

Recupera el índice de base cero del elemento de delimitador actual en el cuadro de lista.

int GetAnchorIndex() const;

Valor devuelto

Índice del elemento de delimitador actual, si se ejecuta correctamente; de lo contrario, LB_ERR.

Comentarios

En un cuadro de lista de selección múltiple, el elemento de delimitador es el primer o último elemento de un bloque de elementos seleccionados contiguos.

Ejemplo

Vea el ejemplo de CListBox::SetAnchorIndex.

`CListBox::GetCaretIndex`

Determina el índice del elemento que tiene el rectángulo de foco en un cuadro de lista de selección múltiple.

int GetCaretIndex() const;

Valor devuelto

Índice de base cero del elemento que tiene el rectángulo de foco en un cuadro de lista. Si el cuadro de lista es un cuadro de lista de selección única, el valor devuelto es el índice del elemento seleccionado, si existe.

Comentarios

El elemento puede o no estar seleccionado.

Ejemplo

Vea el ejemplo de CListBox::SetCaretIndex.

`CListBox::GetCount`

Recupera el número de elementos de un cuadro de lista.

int GetCount() const;

Valor devuelto

Número de elementos del cuadro de lista o LB_ERR si se produce un error.

Comentarios

El recuento devuelto es mayor que el valor de índice del último elemento (el índice es de base cero).

Ejemplo

// Add 10 items to the list box.
CString str;
for (int i = 0; i < 10; i++)
{
   str.Format(_T("item %d"), i);
   m_myListBox.AddString(str);
}

// Verify that 10 items were added to the list box.
ASSERT(m_myListBox.GetCount() == 10);

`CListBox::GetCurSel`

Recupera el índice de base cero del elemento seleccionado actualmente, si existe, en un cuadro de lista de selección única.

int GetCurSel() const;

Valor devuelto

Índice de base cero del elemento seleccionado actualmente si es un cuadro de lista de selección única. Es LB_ERR si no hay ningún elemento seleccionado actualmente.

En un cuadro de lista de selección múltiple, el índice del elemento que tiene el foco.

Comentarios

No llame a GetCurSel para un cuadro de lista de selección múltiple. En su lugar, use CListBox::GetSelItems.

Ejemplo

// Select the next item of the currently selected one.
int nIndex = m_myListBox.GetCurSel();
int nCount = m_myListBox.GetCount();
if ((nIndex != LB_ERR) && (nCount > 1))
{
   if (++nIndex < nCount)
      m_myListBox.SetCurSel(nIndex);
   else
      m_myListBox.SetCurSel(0);
}

`CListBox::GetHorizontalExtent`

Recupera del cuadro de lista el ancho en píxeles por el que se puede desplazar horizontalmente.

int GetHorizontalExtent() const;

Valor devuelto

Ancho desplazable del cuadro de lista, en píxeles.

Comentarios

Esto solo es aplicable si el cuadro de lista tiene una barra de desplazamiento horizontal.

Ejemplo

// Find the longest string in the list box.
CString str;
CSize sz;
int dx = 0;
CDC *pDC = m_myListBox.GetDC();
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
m_myListBox.ReleaseDC(pDC);

// Set the horizontal extent only if the current extent is not large enough.
if (m_myListBox.GetHorizontalExtent() < dx)
{
   m_myListBox.SetHorizontalExtent(dx);
   ASSERT(m_myListBox.GetHorizontalExtent() == dx);
}

`CListBox::GetItemData`

Recupera el valor de doble palabra proporcionado por la aplicación asociado al elemento de cuadro de lista especificado.

DWORD_PTR GetItemData(int nIndex) const;

Parámetros

nIndex
Especifica el índice de base cero del elemento en el cuadro de lista.

Valor devuelto

Valor asociado al elemento o LB_ERR si se produce un error.

Comentarios

El valor de la palabra doble era el parámetro dwItemData de una llamada SetItemData.

Ejemplo

// If any item's data is equal to zero then reset it to -1.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   if (m_myListBox.GetItemData(i) == 0)
   {
      m_myListBox.SetItemData(i, (DWORD)-1);
   }
}

`CListBox::GetItemDataPtr`

Recupera el valor de 32 bits proporcionado por la aplicación asociado al elemento de cuadro de lista especificado como puntero (void *).

void* GetItemDataPtr(int nIndex) const;

Parámetros

nIndex
Especifica el índice de base cero del elemento en el cuadro de lista.

Valor devuelto

Recupera un puntero o -1 si se produce un error.

Ejemplo

LPVOID lpmyPtr = pParentWnd;

// Check all the items in the list box; if an item's
// data pointer is equal to my pointer then reset it to NULL.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   if (m_myListBox.GetItemDataPtr(i) == lpmyPtr)
   {
      m_myListBox.SetItemDataPtr(i, NULL);
   }
}

`CListBox::GetItemHeight`

Determina el alto de los elementos de un cuadro de lista.

int GetItemHeight(int nIndex) const;

Parámetros

nIndex
Especifica el índice de base cero del elemento en el cuadro de lista. Este parámetro solo se usa si el cuadro de lista tiene el estilo LBS_OWNERDRAWVARIABLE; de lo contrario, debe establecerse en 0.

Valor devuelto

El alto, en píxeles, de los elementos del cuadro de lista. Si el cuadro de lista tiene el estilo LBS_OWNERDRAWVARIABLE, el valor devuelto es el alto del elemento especificado por nIndex. El valor devuelto es LB_ERR si se produce un error.

Ejemplo

// Set the height of every item so the item
// is completely visible.
CString str;
CSize sz;
CDC *pDC = m_myListBox.GetDC();
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   // Only want to set the item height if the current height
   // is not big enough.
   if (m_myListBox.GetItemHeight(i) < sz.cy)
      m_myListBox.SetItemHeight(i, sz.cy);
}
m_myListBox.ReleaseDC(pDC);

`CListBox::GetItemRect`

Recupera las dimensiones del rectángulo que enlaza un elemento de cuadro de lista tal y como se muestra actualmente en la ventana de cuadro de lista.

int GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parámetros

nIndex
Especifica el índice de base cero del elemento.

lpRect
Especifica un puntero largo a una RECT estructura que recibe las coordenadas cliente de cuadro de lista del elemento.

Valor devuelto

LB_ERR se produce un error.

Ejemplo

// Dump all of the items bounds.
CString str;
RECT r;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetItemRect(i, &r);

   str.Format(_T("item %d: left = %d, top = %d, right = %d, ")
              _T("bottom = %d\r\n"),
              i,
              r.left,
              r.top,
              r.right,
              r.bottom);
   AFXDUMP(str);
}

`CListBox::GetListBoxInfo`

Recupera el número de elementos por columna.

DWORD GetListBoxInfo() const;

Valor devuelto

Número de elementos por columna del objeto CListBox.

Comentarios

Esta función miembro se usa para emular la funcionalidad del mensaje LB_GETLISTBOXINFO, tal como se describe en Windows SDK.

`CListBox::GetLocale`

Recupera la configuración regional usada por el cuadro de lista.

LCID GetLocale() const;

Valor devuelto

Valor del identificador de configuración regional (LCID) de las cadenas del cuadro de lista.

Comentarios

La configuración regional se usa, por ejemplo, para determinar el criterio de ordenación de las cadenas en un cuadro de lista ordenado.

Ejemplo

Vea el ejemplo de CListBox::SetLocale.

`CListBox::GetSel`

Recupera el estado de selección de un elemento.

int GetSel(int nIndex) const;

Parámetros

nIndex
Especifica el índice de base cero del elemento.

Valor devuelto

Número positivo si se selecciona el elemento especificado; de lo contrario, es 0. El valor devuelto es LB_ERR si se produce un error.

Comentarios

Esta función miembro funciona con cuadros de lista de selección única y múltiple.

Para recuperar el índice del elemento del cuadro de lista seleccionado actualmente, use CListBox::GetCurSel.

Ejemplo

// Dump all of the items select state.
CString str;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   str.Format(_T("item %d: select state is %s\r\n"),
              i,
              m_myListBox.GetSel(i) > 0 ? _T("true") : _T("false"));
   AFXDUMP(str);
}

`CListBox::GetSelCount`

Recupera el número total de elementos seleccionados en un cuadro de lista de selección múltiple.

int GetSelCount() const;

Valor devuelto

Recuento de elementos seleccionados en un cuadro de lista. Si el cuadro de lista es un cuadro de lista de selección única, el valor devuelto es LB_ERR.

Ejemplo

Vea el ejemplo de CListBox::GetSelItems.

`CListBox::GetSelItems`

Rellena un búfer con una matriz de enteros que especifica los números de elementos seleccionados en un cuadro de lista de selección múltiple.

int GetSelItems(
    int nMaxItems,
    LPINT rgIndex) const;

Parámetros

nMaxItems
Especifica el número máximo de elementos seleccionados cuyos números de elemento se van a colocar en el búfer.

rgIndex
Especifica un puntero a un búfer lo suficientemente grande como para el número de enteros especificados por nMaxItems.

Valor devuelto

Número real de elementos colocados en el búfer. Si el cuadro de lista es un cuadro de lista de selección única, el valor devuelto es LB_ERR.

Ejemplo

// Get the indexes of all the selected items.
int nCount = m_myODListBox.GetSelCount();
CArray<int, int> aryListBoxSel;

aryListBoxSel.SetSize(nCount);
m_myODListBox.GetSelItems(nCount, aryListBoxSel.GetData());

// Dump the selection array.
AFXDUMP(aryListBoxSel);

`CListBox::GetText`

Obtiene una cadena de un cuadro de lista.

int GetText(
    int nIndex,
    LPTSTR lpszBuffer) const;

void GetText(
    int nIndex,
    CString& rString) const;

Parámetros

nIndex
Especifica el índice de base cero de la cadena que se va a recuperar.

lpszBuffer
Apunta al búfer que recibe la cadena. El búfer debe tener suficiente espacio para la cadena y un carácter nulo de terminación. El tamaño de la cadena se puede determinar con antelación llamando a la función miembro GetTextLen.

rString
Referencia a un objeto CString.

Valor devuelto

Longitud (en bytes) de la cadena, excepto el carácter nulo de terminación. Si nIndex no especifica un índice válido, el valor devuelto es LB_ERR.

Comentarios

La segunda forma de esta función miembro rellena un objeto CString con el texto de cadena.

Ejemplo

// Dump all of the items in the list box.
CString str, str2;
int n;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   n = m_myListBox.GetTextLen(i);
   m_myListBox.GetText(i, str.GetBuffer(n));
   str.ReleaseBuffer();

   str2.Format(_T("item %d: %s\r\n"), i, str.GetBuffer(0));
   AFXDUMP(str2);
}

`CListBox::GetTextLen`

Obtiene la longitud de una cadena en un elemento de cuadro de lista.

int GetTextLen(int nIndex) const;

Parámetros

nIndex
Especifica el índice de base cero de la cadena.

Valor devuelto

Longitud de la cadena en caracteres, excepto el carácter nulo de terminación. Si nIndex no especifica un índice válido, el valor devuelto es LB_ERR.

Ejemplo

Vea el ejemplo de CListBox::GetText.

`CListBox::GetTopIndex`

Recupera el índice de base cero del primer elemento visible en un cuadro de lista.

int GetTopIndex() const;

Valor devuelto

Índice de base cero del primer elemento visible en un cuadro de lista si se ejecuta correctamente; de lo contrario LB_ERR.

Comentarios

Inicialmente, el elemento 0 está en la parte superior del cuadro de lista, pero si se desplaza el cuadro de lista, otro elemento puede estar en la parte superior.

Ejemplo

// Want an item in the bottom half to be the first visible item.
int n = m_myListBox.GetCount() / 2;
if (m_myListBox.GetTopIndex() < n)
{
   m_myListBox.SetTopIndex(n);
   ASSERT(m_myListBox.GetTopIndex() == n);
}

`CListBox::InitStorage`

Asigna memoria para almacenar elementos de cuadro de lista.

int InitStorage(
    int nItems,
    UINT nBytes);

Parámetros

nItems
Especifica el número de elementos que se agregarán.

nBytes
Especifica la cantidad de memoria, en bytes, que se va a asignar para las cadenas de elementos.

Valor devuelto

Si se ejecuta correctamente, el número máximo de elementos que el cuadro de lista puede almacenar antes de que se necesite una reasignación de memoria; de lo contrario LB_ERRSPACE, que significa que no hay suficiente memoria disponible.

Comentarios

Llame a esta función antes de agregar un gran número de elementos a CListBox.

Esta función ayuda a acelerar la inicialización de cuadros de lista que tienen un gran número de elementos (más de 100). Preasigna la cantidad de memoria especificada para que las funciones posteriores AddString, InsertString y Dir tarden el menor tiempo posible. Puede usar estimaciones para los parámetros. Si sobrestima, se asigna memoria adicional; si subestima, se usa la asignación normal para los elementos que superan la cantidad preasignada.

Solo Windows 95/98: el parámetro nItems está limitado a valores de 16 bits. Esto significa que los cuadros de lista no pueden contener más de 32 767 elementos. Aunque el número de elementos está restringido, el tamaño total de los elementos de un cuadro de lista solo está limitado por la memoria disponible.

Ejemplo

// Initialize the storage of the list box to be 256 strings with
// about 10 characters per string, performance improvement.
int n = m_myListBox.InitStorage(256, 16 * sizeof(TCHAR));
ASSERT(n != LB_ERRSPACE);

// Add 256 items to the list box.
CString str;
for (int i = 0; i < 256; i++)
{
   str.Format(_T("item string %d"), i);
   m_myListBox.AddString(str);
}

`CListBox::InsertString`

Inserta una cadena en el cuadro de lista.

int InsertString(
    int nIndex,
    LPCTSTR lpszItem);

Parámetros

nIndex
Especifica el índice de base cero de la posición en que se va a insertar la cadena. Si este parámetro es -1, la cadena se agrega al final de la lista.

lpszItem
Apunta a la cadena terminada en null que se va a insertar.

Valor devuelto

Índice de base cero de la posición donde se insertó la cadena. El valor devuelto es LB_ERR si se produce un error; el valor devuelto es LB_ERRSPACE si no hay suficiente espacio disponible para almacenar la nueva cadena.

Comentarios

A diferencia de la función miembro AddString, InsertString no provoca una lista con el estilo LBS_SORT que se va a ordenar.

Ejemplo

// Insert items in between existing items.
CString str;
int n = m_myListBox.GetCount();
for (int i = 0; i < n; i++)
{
   str.Format(_T("item string %c"), (char)('A' + i));
   m_myListBox.InsertString(2 * i, str);
}

`CListBox::ItemFromPoint`

Determina el elemento de cuadro de lista más cercano al punto especificado en pt.

UINT ItemFromPoint(
    CPoint pt,
    BOOL& bOutside) const;

Parámetros

pt
Punto para el que se va a buscar el elemento más cercano, especificado en relación con la esquina superior izquierda del área cliente del cuadro de lista.

bOutside
Referencia a una variable BOOL que se establecerá en TRUE si pt está fuera del área cliente del cuadro de lista, FALSE si pt está dentro del área cliente del cuadro de lista.

Valor devuelto

Índice del elemento más cercano al punto especificado en pt.

Comentarios

Puede usar esta función para determinar sobre qué elemento de cuadro de lista se mueve el cursor del mouse.

Ejemplo

Vea el ejemplo de CListBox::SetAnchorIndex.

`CListBox::MeasureItem`

El marco llama a este método cuando se crea un cuadro de lista con un estilo dibujado por el propietario.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Parámetros

lpMeasureItemStruct
Puntero largo a una estructura MEASUREITEMSTRUCT.

Comentarios

De manera predeterminada, esta función miembro no hace nada. Invalide esta función miembro y rellene la estructura MEASUREITEMSTRUCT para informar a Windows de las dimensiones del cuadro de lista. Si el cuadro de lista se crea con el estilo LBS_OWNERDRAWVARIABLE, el marco llama a esta función miembro para cada elemento del cuadro de lista. De lo contrario, solo se llama a este miembro una vez.

Para obtener más información sobre el uso del estilo LBS_OWNERDRAWFIXED en un cuadro de lista dibujado por el propietario creado con la función miembro SubclassDlgItem de CWnd, consulte la explicación de la Nota técnica 14.

Consulte CWnd::OnMeasureItem para obtener una descripción de la estructura MEASUREITEMSTRUCT.

Ejemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example measures an item and sets the height of the item to twice the
// vertical extent of its text. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct)
{
   ASSERT(lpMeasureItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText = (LPCTSTR)lpMeasureItemStruct->itemData;
   ASSERT(lpszText != NULL);
   CSize sz;
   CDC *pDC = GetDC();

   sz = pDC->GetTextExtent(lpszText);

   ReleaseDC(pDC);

   lpMeasureItemStruct->itemHeight = 2 * sz.cy;
}

`CListBox::ResetContent`

Quita todos los elementos de un cuadro de lista.

void ResetContent();

Ejemplo

// Delete all the items from the list box.
m_myListBox.ResetContent();
ASSERT(m_myListBox.GetCount() == 0);

`CListBox::SelectString`

Busca un elemento de cuadro de lista que coincida con la cadena especificada y, si se encuentra un elemento coincidente, selecciona el elemento.

int SelectString(
    int nStartAfter,
    LPCTSTR lpszItem);

Parámetros

Valor devuelto

Índice del elemento seleccionado si la búsqueda se realizó correctamente. Si la búsqueda no se realizó correctamente, el valor devuelto es LB_ERR y la selección actual no cambia.

Comentarios

El cuadro de lista se desplaza, si es necesario, para mostrar el elemento seleccionado.

Esta función miembro no se puede usar con un cuadro de lista que tenga el estilo LBS_MULTIPLESEL.

Solo se selecciona un elemento si sus caracteres iniciales (desde el punto inicial) coinciden con los caracteres de la cadena especificada por lpszItem.

Use la función miembro FindString para buscar una cadena sin seleccionar el elemento.

Ejemplo

// The string to match.
LPCTSTR lpszmyString = _T("item 5");

// Select the item that begins with the specified string.
int nIndex = m_myListBox.SelectString(0, lpszmyString);
ASSERT(nIndex != LB_ERR);

`CListBox::SelItemRange`

Selecciona varios elementos consecutivos en un cuadro de lista de selección múltiple.

int SelItemRange(
    BOOL bSelect,
    int nFirstItem,
    int nLastItem);

Parámetros

bSelect
Especifica cómo establecer la selección. Si bSelect es TRUE, la cadena está seleccionada y resaltada; si FALSE, se quita el resaltado y la cadena ya no está seleccionada.

nFirstItem
Especifica el índice de base cero del primer elemento que se va a establecer.

nLastItem
Especifica el índice de base cero del último elemento que se va a establecer.

Valor devuelto

LB_ERR se produce un error.

Comentarios

Use esta función miembro solo con cuadros de lista de selección múltiple. Si necesita seleccionar solo un elemento en un cuadro de lista de selección múltiple, es decir, si nFirstItem es igual a nLastItem, llame a la función miembro SetSelen su lugar.

Ejemplo

// Select half of the items.
m_myODListBox.SelItemRange(TRUE, 0, m_myODListBox.GetCount() / 2);

`CListBox::SetAnchorIndex`

Establece el delimitador en un cuadro de lista de selección múltiple para comenzar una selección extendida.

void SetAnchorIndex(int nIndex);

Parámetros

nIndex
Especifica el índice de base cero del elemento de cuadro de lista que será el delimitador.

Comentarios

En un cuadro de lista de selección múltiple, el elemento de delimitador es el primer o último elemento de un bloque de elementos seleccionados contiguos.

Ejemplo

void CMyODListBox::OnLButtonDown(UINT nFlags, CPoint point)
{
   BOOL bOutside = TRUE;
   UINT uItem = ItemFromPoint(point, bOutside);

   if (!bOutside)
   {
      // Set the anchor to be the middle item.
      SetAnchorIndex(uItem);
      ASSERT((UINT)GetAnchorIndex() == uItem);
   }

   CListBox::OnLButtonDown(nFlags, point);
}

`CListBox::SetCaretIndex`

Establece el rectángulo de foco en el elemento del índice especificado en un cuadro de lista de selección múltiple.

int SetCaretIndex(
    int nIndex,
    BOOL bScroll = TRUE);

Parámetros

nIndex
Especifica el índice de base cero del elemento que recibirá el rectángulo de foco en el cuadro de lista.

bScroll
Si este valor es 0, el elemento se desplaza hasta que está totalmente visible. Si este valor no es 0, el elemento se desplaza hasta que sea al menos parcialmente visible.

Valor devuelto

LB_ERR se produce un error.

Comentarios

Si el elemento no está visible, se desplaza hacia la vista.

Ejemplo

// Set the caret to be the middle item.
m_myListBox.SetCaretIndex(m_myListBox.GetCount() / 2);
ASSERT(m_myListBox.GetCaretIndex() == m_myListBox.GetCount() / 2);

`CListBox::SetColumnWidth`

Establece el ancho en píxeles de todas las columnas de un cuadro de lista de varias columnas (creado con el estilo LBS_MULTICOLUMN).

void SetColumnWidth(int cxWidth);

Parámetros

cxWidth
Especifica el ancho en píxeles de todas las columnas.

Ejemplo

// Find the pixel width of the largest item.
CString str;
CSize   sz;
int     dx = 0;
CDC* pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
myListBox.ReleaseDC(pDC);

// Set the column width of the first column to be one and 1/3 units
// of the largest string. 
myListBox.SetColumnWidth(dx * 4 / 3);

`CListBox::SetCurSel`

Selecciona una cadena y la desplaza a la vista, si es necesario.

int SetCurSel(int nSelect);

Parámetros

nSelect
Especifica el índice de base cero de la cadena que se va a seleccionar. Si nSelect es -1, el cuadro de lista se establece para que no tenga ninguna selección.

Valor devuelto

LB_ERR se produce un error.

Comentarios

Cuando se selecciona la nueva cadena, el cuadro de lista quita el resaltado de la cadena seleccionada anteriormente.

Use esta función miembro solo con cuadros de lista de selección única.

Para establecer o quitar una selección en un cuadro de lista de selección múltiple, use CListBox::SetSel.

Ejemplo

// Select the last item in the list box.
int nCount = m_myListBox.GetCount();
if (nCount > 0)
   m_myListBox.SetCurSel(nCount - 1);

`CListBox::SetHorizontalExtent`

Establece el ancho, en píxeles, por el que se puede desplazar horizontalmente un cuadro de lista.

void SetHorizontalExtent(int cxExtent);

Parámetros

cxExtent
Especifica el número de píxeles por los que se puede desplazar horizontalmente el cuadro de lista.

Comentarios

Si el tamaño del cuadro de lista es menor que este valor, la barra de desplazamiento horizontal desplazará horizontalmente los elementos del cuadro de lista. Si el cuadro de lista es tan grande como este valor o mayor que este, se oculta la barra de desplazamiento horizontal.

Para responder a una llamada a SetHorizontalExtent, el cuadro de lista debe haberse definido con el estilo WS_HSCROLL.

Esta función miembro no es útil para los cuadros de lista de varias columnas. Para los cuadros de lista de varias columnas, llame a la función miembro SetColumnWidth.

Ejemplo

// Find the longest string in the list box.
CString str;
CSize sz;
int dx = 0;
TEXTMETRIC tm;
CDC *pDC = m_myListBox.GetDC();
CFont *pFont = m_myListBox.GetFont();

// Select the listbox font, save the old font
CFont *pOldFont = pDC->SelectObject(pFont);
// Get the text metrics for avg char width
pDC->GetTextMetrics(&tm);

for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   // Add the avg width to prevent clipping
   sz.cx += tm.tmAveCharWidth;

   if (sz.cx > dx)
      dx = sz.cx;
}
// Select the old font back into the DC
pDC->SelectObject(pOldFont);
m_myListBox.ReleaseDC(pDC);

// Set the horizontal extent so every character of all strings
// can be scrolled to.
m_myListBox.SetHorizontalExtent(dx);

`CListBox::SetItemData`

Establece un valor asociado al elemento especificado en un cuadro de lista.

int SetItemData(
    int nIndex,
    DWORD_PTR dwItemData);

Parámetros

nIndex
Especifica el índice de base cero del elemento.

dwItemData
Especifica el valor que se va a asociar al elemento.

Valor devuelto

LB_ERR se produce un error.

Ejemplo

// Set the data of each item to be equal to its index.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.SetItemData(i, i);
}

`CListBox::SetItemDataPtr`

Establece el valor de 32 bits asociado al elemento especificado en un cuadro de lista para que sea el puntero especificado ( void *).

int SetItemDataPtr(
    int nIndex,
    void* pData);

Parámetros

nIndex
Especifica el índice de base cero del elemento.

pData
Especifica el puntero que se va a asociar al elemento.

Valor devuelto

LB_ERR se produce un error.

Comentarios

Este puntero sigue siendo válido para la duración del cuadro de lista, aunque la posición relativa del elemento dentro del cuadro de lista pueda cambiar a medida que se agregan o quitan elementos. Por lo tanto, el índice del elemento dentro del cuadro puede cambiar, pero el puntero sigue siendo confiable.

Ejemplo

// Set the data pointer of each item to be NULL.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.SetItemDataPtr(i, NULL);
}

`CListBox::SetItemHeight`

Establece el alto de los elementos de un cuadro de lista.

int SetItemHeight(
    int nIndex,
    UINT cyItemHeight);

Parámetros

cyItemHeight
Especifica el alto, en píxeles, del elemento.

Valor devuelto

LB_ERR si el índice o el alto no son válidos.

Comentarios

Si el cuadro de lista tiene el estilo LBS_OWNERDRAWVARIABLE, esta función establece el alto del elemento especificado por nIndex. De lo contrario, esta función establece el alto de todos los elementos del cuadro de lista.

Ejemplo

// Set the height of every item to be the
// vertical size of the item's text extent.
CString str;
CSize sz;
CDC *pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   myListBox.SetItemHeight(i, sz.cy);
}
myListBox.ReleaseDC(pDC);

`CListBox::SetLocale`

Establece el identificador de configuración regional de este cuadro de lista.

LCID SetLocale(LCID nNewLocale);

Parámetros

nNewLocale
Nuevo valor de identificador de configuración regional (LCID) que se va a establecer para el cuadro de lista.

Valor devuelto

Valor del identificador de configuración regional (LCID) anterior para este cuadro de lista.

Comentarios

Si no se llama a SetLocale, la configuración regional predeterminada se obtiene del sistema. Esta configuración regional predeterminada del sistema se puede modificar mediante la aplicación Regional (o Internacional) del Panel de control.

Ejemplo

// My LCID to use.
LCID mylcid = MAKELCID(MAKELANGID(LANG_SPANISH, SUBLANG_SPANISH_MEXICAN),
                       SORT_DEFAULT);

// Force the list box to use my locale.
m_myListBox.SetLocale(mylcid);
ASSERT(m_myListBox.GetLocale() == mylcid);

`CListBox::SetSel`

Selecciona una cadena en un cuadro de lista de selección múltiple.

int SetSel(
    int nIndex,
    BOOL bSelect = TRUE);

Parámetros

nIndex
Contiene el índice de base cero de la cadena que se va a establecer. Si es -1, la selección se agrega o se quita de todas las cadenas, según el valor de bSelect.

bSelect
Especifica cómo establecer la selección. Si bSelect es TRUE, la cadena está seleccionada y resaltada; si FALSE, se quita el resaltado y la cadena ya no está seleccionada. La cadena especificada está seleccionada y resaltada de forma predeterminada.

Valor devuelto

LB_ERR se produce un error.

Comentarios

Use esta función miembro solo con cuadros de lista de selección múltiple.

Para seleccionar un elemento de un cuadro de lista de selección única, use CListBox::SetCurSel.

Ejemplo

// Select all of the items with an even index and
// deselect all others.
for (int i = 0; i < m_myODListBox.GetCount(); i++)
{
   m_myODListBox.SetSel(i, ((i % 2) == 0));
}

`CListBox::SetTabStops`

Establece las posiciones de tabulación en un cuadro de lista.

void SetTabStops();
BOOL SetTabStops(const int& cxEachStop);

BOOL SetTabStops(
    int nTabStops,
    LPINT rgTabStops);

Parámetros

cxEachStop
Las tabulaciones se establecen en cada unidad de diálogo cxEachStop. Consulte rgTabStops para obtener una descripción de una unidad de diálogo.

nTabStops
Especifica el número de tabulaciones que se van a tener en el cuadro de lista.

rgTabStops
Apunta al primer miembro de una matriz de enteros que contiene las posiciones de tabulación en unidades de diálogo. Una unidad de diálogo es una distancia horizontal o vertical. Una unidad de diálogo horizontal es igual a una cuarta parte de la unidad de ancho base del diálogo actual y una unidad de diálogo vertical es igual a un octavo de la unidad de alto base del diálogo actual. Las unidades base del cuadro de diálogo se calculan en función del alto y ancho de la fuente actual del sistema. La función de Windows GetDialogBaseUnits devuelve las unidades base del cuadro de diálogo actuales en píxeles. Las tabulaciones deben ordenarse en orden creciente; no se permiten tabulaciones hacia atrás.

Valor devuelto

Distinto de cero si se establecieron todas las tabulaciones; de lo contrario, 0.

Comentarios

Para establecer tabulaciones en el tamaño predeterminado de 2 unidades de diálogo, llame a la versión sin parámetros de esta función miembro. Para establecer tabulaciones en un tamaño distinto de 2, llame a la versión con el argumento cxEachStop.

Para establecer tabulaciones en una matriz de tamaños, use la versión con los argumentos rgTabStops y nTabStops. Se establecerá una tabulación para cada valor de rgTabStops, hasta el número especificado por nTabStops.

Para responder a una llamada a la función miembro SetTabStops, el cuadro de lista debe haberse creado con el estilo LBS_USETABSTOPS.

Ejemplo

// Find the pixel width of the largest first substring.
CString str;
CSize sz;
int nIndex, dx = 0;
CDC *pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);

   if ((nIndex = str.Find('\t')) != -1)
      str = str.Right(nIndex);

   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
myListBox.ReleaseDC(pDC);

// Set tab stops at every one and 1/3 units
// of the largest string.
// NOTE: Convert pixels to dialog units.
myListBox.SetTabStops((dx * 4 / 3 * 4) / LOWORD(::GetDialogBaseUnits()));

`CListBox::SetTopIndex`

Garantiza que un elemento de cuadro de lista determinado esté visible.

int SetTopIndex(int nIndex);

Parámetros

nIndex
Especifica el índice de base cero del elemento de cuadro de lista.

Valor devuelto

Cero si se ejecuta correctamente, o LB_ERR si se produce un error.

Comentarios

El sistema desplaza el cuadro de lista hasta que el elemento especificado por nIndex aparezca en la parte superior del cuadro de lista o se alcance el rango de desplazamiento máximo.

Ejemplo

// Set the first visible item in the list box to be the middle item
m_myListBox.SetTopIndex(m_myListBox.GetCount() / 2);

`CListBox::VKeyToItem`

Lo llama el marco cuando la ventana primaria del cuadro de lista recibe un mensaje WM_VKEYTOITEM del cuadro de lista.

virtual int VKeyToItem(
    UINT nKey,
    UINT nIndex);

Parámetros

nKey
Código de clave virtual de la tecla que el usuario presionó. Para obtener una lista de códigos de tecla virtual estándar, consulte Winuser.h.

nIndex
Posición actual del símbolo de intercalación del cuadro de lista.

Valor devuelto

Devuelve -2 para ninguna acción adicional, -1 para la acción predeterminada o un número no negativo para especificar un índice de un elemento de cuadro de lista en el que se va a realizar la acción predeterminada para la pulsación de teclas.

Comentarios

El cuadro de lista envía el mensaje WM_VKEYTOITEM cuando recibe un mensaje WM_KEYDOWN, pero solo si el cuadro de lista cumple las dos condiciones siguientes:

Tiene el estilo LBS_WANTKEYBOARDINPUT establecido.
Tiene al menos un elemento.

Nunca debe llamar a esta función usted mismo. Invalide esta función para proporcionar su propio control personalizado de los mensajes de teclado.

Debe devolver un valor para indicar al marco qué acción realizó la invalidación. Un valor devuelto de -2 indica que la aplicación ha controlado todos los aspectos de la selección del elemento y no quiere ninguna acción adicional por parte del cuadro de lista. Antes de devolver -2, puede establecer la selección o mover el símbolo de intercalación o ambos. Para establecer la selección, use SetCurSel o SetSel. Para mover el símbolo de intercalación, use SetCaretIndex.

Un valor devuelto de -1 indica que el cuadro de lista debe realizar la acción predeterminada en respuesta a la pulsación de teclas. La implementación predeterminada devuelve -1.

Ejemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example moves the caret down one item on the down key and up one item
// on the up key. The list box control was created with the following
// code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::VKeyToItem(UINT nKey, UINT nIndex)
{
   // On key up, move the caret up one item.
   if ((nKey == VK_UP) && (nIndex > 0))
   {
      SetCaretIndex(nIndex - 1);
   }
   // On key down, move the caret down one item.
   else if ((nKey == VK_DOWN) && (nIndex < (UINT)GetCount()))
   {
      SetCaretIndex(nIndex + 1);
   }

   // Do not perform any default processing.
   return -2;
}

Vea también

MFC Sample CTRLTEST
CWnd (clase)
Gráfico de jerarquías
CWnd (clase)
CButton (clase)
CComboBox (clase)
CEdit (clase)
CScrollBar (clase)
CStatic (clase)

Compartir vía

Clase CListBox

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Comentarios

Jerarquía de herencia

Requisitos

CListBox::AddString

Parámetros

Valor devuelto

Comentarios

Ejemplo

CListBox::CharToItem

Parámetros

Valor devuelto

Comentarios

Ejemplo

CListBox::CListBox

Comentarios

Ejemplo

CListBox::CompareItem

Parámetros

Valor devuelto

Comentarios

Ejemplo

CListBox::Create

Parámetros

Valor devuelto

Comentarios

Ejemplo

CListBox::DeleteItem

Parámetros

Comentarios

Ejemplo

CListBox::DeleteString

Parámetros

Valor devuelto

Comentarios

Ejemplo

CListBox::Dir

Parámetros

Valor devuelto

Ejemplo

CListBox::DrawItem

Parámetros

Comentarios

Ejemplo

CListBox::FindString

Parámetros

Valor devuelto

Comentarios

Ejemplo

CListBox::FindStringExact

Parámetros

Valor devuelto

Comentarios

Ejemplo

CListBox::GetAnchorIndex

Valor devuelto

Comentarios

Ejemplo

CListBox::GetCaretIndex

Valor devuelto

Comentarios

Ejemplo

CListBox::GetCount

Valor devuelto

Comentarios

Ejemplo

CListBox::GetCurSel

Valor devuelto

Comentarios

Ejemplo

CListBox::GetHorizontalExtent

Valor devuelto

Comentarios

Ejemplo

CListBox::GetItemData

Clase `CListBox`

`CListBox::AddString`

`CListBox::CharToItem`

`CListBox::CListBox`

`CListBox::CompareItem`

`CListBox::Create`

`CListBox::DeleteItem`

`CListBox::DeleteString`

`CListBox::Dir`

`CListBox::DrawItem`

`CListBox::FindString`

`CListBox::FindStringExact`

`CListBox::GetAnchorIndex`

`CListBox::GetCaretIndex`

`CListBox::GetCount`

`CListBox::GetCurSel`

`CListBox::GetHorizontalExtent`

`CListBox::GetItemData`

`CListBox::GetItemDataPtr`

`CListBox::GetItemHeight`

`CListBox::GetItemRect`

`CListBox::GetListBoxInfo`

`CListBox::GetLocale`

`CListBox::GetSel`

`CListBox::GetSelCount`

`CListBox::GetSelItems`

`CListBox::GetText`

`CListBox::GetTextLen`

`CListBox::GetTopIndex`

`CListBox::InitStorage`

`CListBox::InsertString`

`CListBox::ItemFromPoint`

`CListBox::MeasureItem`

`CListBox::ResetContent`