Clase CListCtrl

Encapsula la funcionalidad de un "control de vista de lista", que muestra una colección de elementos cada uno de los cuales consta de un icono (de una lista de imágenes) y una etiqueta.

Sintaxis

class CListCtrl : public CWnd

Miembros

Constructores públicos

Nombre	Descripción
CListCtrl::CListCtrl	Construye un objeto CListCtrl.

Métodos públicos

Nombre	Descripción
CListCtrl::ApproximateViewRect	Determina el ancho y el alto necesarios para mostrar los elementos de un control de vista de lista.
CListCtrl::Arrange	Alinea los elementos de una cuadrícula.
CListCtrl::CancelEditLabel	Cancela la operación de edición de texto del elemento.
CListCtrl::Create	Crea un control de lista y lo asocia a un objeto CListCtrl.
CListCtrl::CreateDragImage	Crea una lista de imágenes de arrastre para un elemento especificado.
CListCtrl::CreateEx	Crea un control de lista con los estilos extendidos de Windows especificados y lo asocia a un objeto CListCtrl.
CListCtrl::DeleteAllItems	Elimina todos los elementos del control.
CListCtrl::DeleteColumn	Elimina una columna del control de vista de lista.
CListCtrl::DeleteItem	Elimina un elemento del control.
CListCtrl::DrawItem	Se llama cuando cambia la apariencia de un control dibujado por el propietario.
CListCtrl::EditLabel	Comienza la edición en contexto del texto de un elemento.
CListCtrl::EnableGroupView	Habilita o deshabilita si los elementos de un control de vista de lista se muestran como un grupo.
CListCtrl::EnsureVisible	Garantiza que un elemento esté visible.
CListCtrl::FindItem	Busca un elemento de vista de lista con características especificadas.
CListCtrl::GetBkColor	Recupera el color de fondo de un control de vista de lista.
CListCtrl::GetBkImage	Recupera la imagen de fondo actual de un control de vista de lista.
CListCtrl::GetCallbackMask	Recupera la máscara de devolución de llamada de un control de vista de lista.
CListCtrl::GetCheck	Recupera el estado de presentación actual de la imagen de estado asociada a un elemento.
CListCtrl::GetColumn	Recupera los atributos de la columna de un control.
CListCtrl::GetColumnOrderArray	Recupera el orden de columna (de izquierda a derecha) de un control de vista de lista.
CListCtrl::GetColumnWidth	Recupera el ancho de una columna en la vista de informe o vista de lista.
CListCtrl::GetCountPerPage	Calcula el número de elementos que pueden caber verticalmente en un control de vista de lista.
CListCtrl::GetEditControl	Recupera el manipulador del control de edición usado para editar el texto de un elemento.
CListCtrl::GetEmptyText	Recupera la cadena que se va a mostrar si el control de vista de lista actual está vacío.
CListCtrl::GetExtendedStyle	Recupera los estilos extendidos actuales de un control de vista de lista.
CListCtrl::GetFirstSelectedItemPosition	Recupera la posición del primer elemento de vista de lista seleccionado de un control de vista de lista.
CListCtrl::GetFocusedGroup	Recupera el grupo que tiene el foco del teclado en el control de vista de lista actual.
CListCtrl::GetGroupCount	Recupera el número de grupos del control de vista de lista actual.
CListCtrl::GetGroupInfo	Obtiene la información de un grupo especificado del control de vista de lista.
CListCtrl::GetGroupInfoByIndex	Recupera la información sobre un grupo especificado del control de vista de lista actual.
CListCtrl::GetGroupMetrics	Recupera las métricas de un grupo.
CListCtrl::GetGroupRect	Recupera el rectángulo delimitador de un grupo especificado del control de vista de lista actual.
CListCtrl::GetGroupState	Recupera el estado de un grupo especificado del control de vista de lista actual.
CListCtrl::GetHeaderCtrl	Recupera el control de encabezado de un control de vista de lista.
CListCtrl::GetHotCursor	Recupera el cursor utilizado cuando el seguimiento activo está habilitado para un control de vista de lista.
CListCtrl::GetHotItem	Recupera el elemento de vista de lista actualmente bajo el cursor.
CListCtrl::GetHoverTime	Recupera el tiempo actual del movimiento del mouse de un control de vista de lista.
CListCtrl::GetImageList	Recupera el manipulador de una lista de imágenes utilizada para dibujar elementos de vista de lista.
CListCtrl::GetInsertMark	Recupera la posición actual de la marca de inserción.
CListCtrl::GetInsertMarkColor	Recupera el color actual de la marca de inserción.
CListCtrl::GetInsertMarkRect	Recupera el rectángulo que enlaza el punto de inserción.
CListCtrl::GetItem	Recupera los atributos de un elemento de vista de lista.
CListCtrl::GetItemCount	Recupera el número de elementos de un control de vista de lista.
CListCtrl::GetItemData	Recupera el valor específico de la aplicación asociado a un elemento.
CListCtrl::GetItemIndexRect	Recupera el rectángulo delimitador para todo un subelemento o parte de este en el control de vista de lista actual.
CListCtrl::GetItemPosition	Recupera la posición de un elemento de vista de lista.
CListCtrl::GetItemRect	Recupera el rectángulo delimitador de un elemento.
CListCtrl::GetItemSpacing	Calcula el espaciado entre los elementos del control de vista de lista actual.
CListCtrl::GetItemState	Recupera el estado de un elemento de vista de lista.
CListCtrl::GetItemText	Recupera el texto de un elemento o subelemento de vista de lista.
CListCtrl::GetNextItem	Busca un elemento de vista de lista con propiedades especificadas y con la relación especificada con un elemento determinado.
CListCtrl::GetNextItemIndex	Recupera el índice del elemento del control de vista de lista actual que tiene un conjunto especificado de propiedades.
CListCtrl::GetNextSelectedItem	Recupera el índice de una posición de elemento de vista de lista y la posición del siguiente elemento de vista de lista seleccionado para iterar.
CListCtrl::GetNumberOfWorkAreas	Recupera el número actual de áreas de trabajo de un control de vista de lista.
CListCtrl::GetOrigin	Recupera el origen de la vista actual de un control de vista de lista.
CListCtrl::GetOutlineColor	Recupera el color del borde de un control de vista de lista.
CListCtrl::GetSelectedColumn	Recupera el índice de la columna seleccionada actualmente en el control de lista.
CListCtrl::GetSelectedCount	Recupera el número de elementos seleccionados en el control de vista de lista.
CListCtrl::GetSelectionMark	Recupera la marca de selección de un control de vista de lista.
CListCtrl::GetStringWidth	Determina el ancho de columna mínimo necesario para mostrar toda una cadena determinada.
CListCtrl::GetSubItemRect	Recupera el rectángulo delimitador de un elemento de un control de vista de lista.
CListCtrl::GetTextBkColor	Recupera el color de fondo del texto de un control de vista de lista.
CListCtrl::GetTextColor	Recupera el color de texto de un control de vista de lista.
CListCtrl::GetTileInfo	Recupera información sobre un mosaico de un control de vista de lista.
CListCtrl::GetTileViewInfo	Recupera información sobre un control de vista de lista en la vista de mosaico.
CListCtrl::GetToolTips	Recupera el control de información sobre herramientas que usa el control de vista de lista para mostrar información sobre herramientas.
CListCtrl::GetTopIndex	Recupera el índice del elemento visible de nivel superior.
CListCtrl::GetView	Obtiene la vista del control de vista de lista.
CListCtrl::GetViewRect	Recupera el rectángulo delimitador de todos los elementos del control de vista de lista.
CListCtrl::GetWorkAreas	Recupera las áreas de trabajo actuales de un control de vista de lista.
CListCtrl::HasGroup	Determina si el control de vista de lista tiene el grupo especificado.
CListCtrl::HitTest	Determina qué elemento de vista de lista está en una posición especificada.
CListCtrl::InsertColumn	Inserta una columna nueva en un control de vista de lista.
CListCtrl::InsertGroup	Inserta un grupo en el control de vista de lista.
CListCtrl::InsertGroupSorted	Inserta el grupo especificado en una lista ordenada de grupos.
CListCtrl::InsertItem	Inserta un elemento nuevo en un control de vista de lista.
CListCtrl::InsertMarkHitTest	Recupera el punto de inserción más cercano a un punto especificado.
CListCtrl::IsGroupViewEnabled	Determina si la vista de grupo está habilitada para un control de vista de lista.
CListCtrl::IsItemVisible	Indica si un elemento especificado en el control de vista de lista actual está visible.
CListCtrl::MapIDToIndex	Asigna el identificador único de un elemento del control de vista de lista actual a un índice.
CListCtrl::MapIndexToID	Asigna el índice de un elemento del control de vista de lista actual a un identificador único.
CListCtrl::MoveGroup	Mueve el grupo especificado.
CListCtrl::MoveItemToGroup	Mueve el grupo especificado al índice de base cero especificado del control de vista de lista.
CListCtrl::RedrawItems	Fuerza un control de vista de lista para volver a dibujar un intervalo de elementos.
CListCtrl::RemoveAllGroups	Quita todos los grupos de un control de vista de lista.
CListCtrl::RemoveGroup	Quita el grupo especificado del control de vista de lista.
CListCtrl::Scroll	Desplaza el contenido de un control de vista de lista.
CListCtrl::SetBkColor	Establece el color de fondo del control de vista de lista.
CListCtrl::SetBkImage	Establece la imagen de fondo actual de un control de vista de lista.
CListCtrl::SetCallbackMask	Establece la máscara de devolución de llamada de un control de vista de lista.
CListCtrl::SetCheck	Establece el estado de presentación actual de la imagen de estado asociada a un elemento.
CListCtrl::SetColumn	Establece los atributos de una columna de vista de lista.
CListCtrl::SetColumnOrderArray	Establece el orden de columna (de izquierda a derecha) de un control de vista de lista.
CListCtrl::SetColumnWidth	Cambia el ancho de una columna en la vista de informe o vista de lista.
CListCtrl::SetExtendedStyle	Establece los estilos extendidos actuales de un control de vista de lista.
CListCtrl::SetGroupInfo	Establece la información del grupo especificado de un control de vista de lista.
CListCtrl::SetGroupMetrics	Establece las métricas de grupo de un control de vista de lista.
CListCtrl::SetHotCursor	Establece el cursor utilizado cuando el seguimiento activo está habilitado para un control de vista de lista.
CListCtrl::SetHotItem	Establece el elemento activo actual de un control de vista de lista.
CListCtrl::SetHoverTime	Establece el tiempo actual del movimiento del mouse de un control de vista de lista.
CListCtrl::SetIconSpacing	Establece el espaciado entre iconos de un control de vista de lista.
CListCtrl::SetImageList	Asigna una lista de imágenes a un control de vista de lista.
CListCtrl::SetInfoTip	Establece el texto de la información sobre herramientas.
CListCtrl::SetInsertMark	Establece el punto de inserción en la posición definida.
CListCtrl::SetInsertMarkColor	Establece el color del punto de inserción.
CListCtrl::SetItem	Establece algunos o todos los atributos de un elemento de vista de lista.
CListCtrl::SetItemCount	Prepara un control de vista de lista para agregar una gran cantidad de elementos.
CListCtrl::SetItemCountEx	Establece el recuento de elementos de un control de vista de lista virtual.
CListCtrl::SetItemData	Establece el valor específico de la aplicación del elemento.
CListCtrl::SetItemIndexState	Establece el estado de un elemento del control de vista de lista actual.
CListCtrl::SetItemPosition	Mueve un elemento a una posición especificada en un control de vista de lista.
CListCtrl::SetItemState	Cambia el estado de un elemento en un control de vista de lista.
CListCtrl::SetItemText	Cambia el texto de un elemento de vista de lista o subelemento.
CListCtrl::SetOutlineColor	Establece el color del borde de un control de vista de lista.
CListCtrl::SetSelectedColumn	Establece la columna seleccionada del control de vista de lista.
CListCtrl::SetSelectionMark	Establece la marca de selección de un control de vista de lista.
CListCtrl::SetTextBkColor	Establece el color de fondo del texto en un control de vista de lista.
CListCtrl::SetTextColor	Establece el color de texto de un control de vista de lista.
CListCtrl::SetTileInfo	Establece la información de un mosaico del control de vista de lista.
CListCtrl::SetTileViewInfo	Establece la información que usa un control de vista de lista en la vista de mosaico.
CListCtrl::SetToolTips	Establece el control de la información sobre herramientas que usará el control de vista de lista para mostrar información sobre herramientas.
CListCtrl::SetView	Establece la vista del control de vista de lista.
CListCtrl::SetWorkAreas	Establece el área donde se pueden mostrar los iconos en un control de vista de lista.
CListCtrl::SortGroups	Ordena los grupos de un control de vista de lista con una función definida por el usuario.
CListCtrl::SortItems	Ordena los elementos de vista de lista mediante una función de comparación definida por la aplicación.
CListCtrl::SortItemsEx	Ordena los elementos de vista de lista mediante una función de comparación definida por la aplicación.
CListCtrl::SubItemHitTest	Determina qué elemento de vista de lista, si existe, está en una posición determinada.
CListCtrl::Update	Fuerza al control a volver a dibujar un elemento especificado.

Comentarios

Además de un icono y una etiqueta, cada elemento puede tener información mostrada en columnas a la derecha del icono y la etiqueta. Este control (y, por tanto, la clase CListCtrl) solo está disponible para los programas que se ejecutan en Windows 95/98 y Windows NT 3.51 y posteriores.

A continuación, se muestra una breve introducción a la clase CListCtrl. Para obtener una explicación detallada de los conceptos, consulte Uso de CListCtrl y Controles.

Vistas

Los controles de vista de lista pueden mostrar su contenido de cuatro maneras diferentes, denominadas "vistas".

• Vista de icono

  Cada elemento aparece como un icono de tamaño completo (32 x 32 píxeles) con una etiqueta debajo. El usuario puede arrastrar los elementos a cualquier ubicación de la ventana de vista de lista.

• Vista de icono pequeño

  Cada elemento aparece como un icono pequeño (16 x 16 píxeles) con la etiqueta situada a la derecha. El usuario puede arrastrar los elementos a cualquier ubicación de la ventana de vista de lista.

• Vista de lista

  Cada elemento aparece como un icono pequeño con una etiqueta a la derecha. Los elementos se organizan en columnas y no se pueden arrastrar a ninguna ubicación de la ventana de vista de lista.

• Vista de informe

  Cada elemento aparece en su propia línea, con información adicional organizada en columnas a la derecha. La columna situada más a la izquierda contiene el icono pequeño y una etiqueta, y las columnas siguientes contienen los subelementos especificados por la aplicación. Un control de encabezado incrustado (clase CHeaderCtrl) implementa estas columnas. Para más información sobre el control de encabezado y columnas de una vista de informe, consulte Uso de CListCtrl: Adición de columnas al control (vista de informe).

El estilo de la vista de lista actual del control determina la vista actual. Para más información sobre estos estilos y su uso, consulte Uso de CListCtrl: Cambio de estilos del control de lista.

Estilos extendidos

Además de los estilos de lista estándar, la clase CListCtrl admite un gran conjunto de estilos extendidos, lo que proporciona funcionalidad enriquecida. Algunos ejemplos de esta funcionalidad incluyen:

• Selección mediante movimiento del mouse

  Cuando se habilita, permite la selección automática de un elemento cuando el cursor permanece sobre el elemento durante un período determinado.

• Vistas de lista virtual

  Cuando se habilita, permite que el control admita hasta elementos DWORD. Esto es posible al colocar la sobrecarga de administrar los datos de elementos en la aplicación. Excepto para la selección de elementos e información de foco, la aplicación debe administrar toda la información del elemento. Para más información, consulte Uso de CListCtrl: Controles de lista virtual.

• Activación de uno y dos clics

  Cuando se habilita, permite el seguimiento activo (resaltado automático del texto del elemento) y la activación de uno o dos clics del elemento resaltado.

• Ordenación de columnas mediante arrastrar y colocar

  Cuando se habilita, permite el reordenamiento de columnas mediante arrastrar y colocar en un control de vista de lista. Solo está disponible en la vista de informe.

Para información sobre el uso de estos nuevos estilos extendidos, consulte Uso de CListCtrl: Cambio de estilos de control de lista.

Elementos y subelementos

Cada elemento de un control de vista de lista consta de un icono (de una lista de imágenes), una etiqueta, un estado actual y un valor definido por la aplicación (denominados "datos de elemento"). Uno o varios subelementos también se pueden asociar a cada elemento. Un "subelemento" es una cadena que, en la vista de informe, se puede mostrar en una columna a la derecha del icono y la etiqueta de un elemento. Todos los elementos de un control de vista de lista deben tener el mismo número de subelementos.

La clase CListCtrl proporciona varias funciones para insertar, eliminar, buscar y modificar estos elementos. Para más información, consulte CListCtrl::GetItem, CListCtrl::InsertItem y CListCtrl::FindItem, Agregar elementos al control y Desplazamiento, organización, ordenación y búsqueda en los controles de lista.

De forma predeterminada, el control de vista de lista es responsable de almacenar los atributos de texto e icono de un elemento. Sin embargo, además de estos tipos de elementos, la clase CListCtrl admite "elementos de devolución de llamada". Un "elemento de devolución de llamada" es un elemento de vista de lista para el que la aplicación, en lugar del control, almacena el texto, el icono o ambos. Se usa una máscara de devolución de llamada para especificar qué atributos de elemento (texto o icono) proporciona la aplicación. Si una aplicación usa elementos de devolución de llamada, debe poder proporcionar los atributos de texto o icono a petición. Los elementos de devolución de llamada son útiles cuando la aplicación ya mantiene parte de esta información. Para más información, consulte Uso de CListCtrl: Elementos de devolución de llamada y máscara de devolución de llamada.

Listas de imágenes

Los iconos, las imágenes de elementos de encabezado y los estados definidos por la aplicación de los elementos de vista de lista se encuentran en varias listas de imágenes (implementadas por la clase CImageList), que se crean y asignan al control de vista de lista. Cada control de vista de lista puede tener hasta cuatro tipos diferentes de listas de imágenes:

• Icono grande

  Se usa en la vista de iconos para iconos de tamaño completo.

• Icono pequeño

  Se usa en las vistas de icono pequeño, lista e informe para versiones más pequeñas de los iconos usados en la vista de iconos.

• Estado definido por la aplicación

  Contiene imágenes de estado que se muestran junto al icono de un elemento para indicar un estado definido por la aplicación.

• Elemento de encabezado

  Se usa en la vista de informe para imágenes pequeñas que aparecen en cada elemento de control de encabezado.

De forma predeterminada, un control de vista de lista destruye las listas de imágenes asignadas cuando se destruye, sin embargo, el desarrollador puede personalizar este comportamiento al destruir cada lista de imágenes cuando ya no se usa, según lo determinado por la aplicación. Para más información, consulte Uso de CListCtrl: Elementos de lista y listas de imágenes.

Jerarquía de herencia

CObject

CCmdTarget

CWnd

CListCtrl

Requisitos

Encabezado: afxcmn.h

CListCtrl::ApproximateViewRect

Determina el ancho y el alto necesarios para mostrar los elementos de un control de vista de lista.

CSize ApproximateViewRect(
    CSize sz = CSize(-1, -1),
    int iCount = -1) const;

Parámetros

sz
Dimensiones propuestas del control, en píxeles. Si no se especifican las dimensiones, el marco usa los valores de ancho o alto actuales del control.

iCount
Cantidad de elementos que se mostrarán en el control. Pase -1 para usar el número total de elementos que se encuentran actualmente en el control.

Valor devuelto

Objeto CSize que contiene el ancho y alto aproximados necesarios para mostrar los elementos, en píxeles.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_ApproximateViewRect, tal y como se describe en Windows SDK.

CListCtrl::Arrange

Cambia la posición de los elementos de una vista de icono para que se alineen en una cuadrícula.

BOOL Arrange(UINT nCode);

Parámetros

nCode
Especifica el estilo de alineación de los elementos. Puede ser uno de los siguientes valores:

• LVA_ALIGNLEFT Alinea los elementos a lo largo del borde izquierdo de la ventana.
• LVA_ALIGNTOP Alinea los elementos a lo largo del borde superior de la ventana.
• LVA_DEFAULT Alinea los elementos según los estilos de alineación actuales de la vista de lista (el valor predeterminado).
• LVA_SNAPTOGRID Ajusta todos los iconos a la posición de cuadrícula más cercana.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

El parámetro nCode especifica el estilo de alineación.

Ejemplo

// Align all of the list view control items along the top
// of the window (the list view control must be in icon or
// small icon mode).
m_myListCtrl.Arrange(LVA_ALIGNTOP);

CListCtrl::CancelEditLabel

Cancela la operación de edición de texto del elemento.

void CancelEditLabel();

Comentarios

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

CListCtrl::CListCtrl

Construye un objeto CListCtrl.

CListCtrl();

CListCtrl::Create

Crea un control de lista y lo asocia a un objeto CListCtrl.

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

Parámetros

dwStyle
Especifica el estilo del control de lista. Aplique al control cualquier combinación de estilos de control de lista. Consulte Estilos de la ventana de vista de lista en Windows SDK para obtener una lista completa de estos estilos. Establece estilos extendidos específicos de un control mediante SetExtendedStyle.

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

pParentWnd
Especifica la ventana primaria del control de lista, normalmente CDialog. No debe ser NULL.

nID
Especifica el identificador del control de lista.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

El proceso de construcción de un elemento CListCtrl se divide en dos pasos. En primer lugar, llame al constructor y, luego, a Create, lo que crea el control de vista de lista y lo asocia al objeto CListCtrl.

Para aplicar estilos extendidos de Windows al objeto de control de lista, llame a CreateEx en lugar de Create.

Ejemplo

m_myListCtrl.Create(
    WS_CHILD|WS_VISIBLE|WS_BORDER|LVS_REPORT|LVS_EDITLABELS,
    CRect(10,10,400,200), pParentWnd, IDD_MYLISTCTRL);

CListCtrl::CreateEx

Esta función puede usarse para crear un control (una ventana secundaria) y asociarlo con el objeto CListCtrl.

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

Parámetros

dwExStyle
El valor de este parámetro se usa para especificar el estilo extendido del control que se va a crear. Para obtener una lista de estilos extendidos de Windows, consulte el parámetro dwExStyle de la función CreateWindowEx en Windows SDK.

dwStyle
Especifica el estilo del control de lista. Aplique al control cualquier combinación de estilos de control de lista. Para obtener una lista completa de estos estilos, consulte Estilos de la ventana de vista de lista en Windows SDK.

rect
Una referencia a una estructura RECT describiendo el tamaño y la posición de la ventana a crear, en las coordenadas cliente de pParentWnd.

pParentWnd
Un puntero a la ventana que constituye el elemento primario del control.

nID
El identificador de ventana secundaria del control.

Valor devuelto

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

Comentarios

Usa la función CreateEx, en lugar de Create, para aplicar estilos extendidos de Windows. Estos se especifican en el prefacio de estilo extendido WS_EX_ de Windows.

CreateEx crea el control con los estilos de extendidos de Windows especificados por dwExStyle. Para establecer estilos extendidos específicos de un control, llame a SetExtendedStyle. Por ejemplo, use CreateEx para establecer estilos como WS_EX_CONTEXTHELP, pero use SetExtendedStyle para establecer estilos como LVS_EX_FULLROWSELECT. Para más información, consulte los estilos descritos en el artículo Estilos extendidos de vista de lista en Windows SDK.

CListCtrl::CreateDragImage

Crea una lista de imágenes de arrastre para el elemento especificado por nItem.

CImageList* CreateDragImage(
    int nItem,
    LPPOINT lpPoint);

Parámetros

*nItem*
Índice del elemento cuya lista de imágenes de arrastre se va a crear.

lpPoint
Dirección de una estructura POINT que recibe la ubicación inicial de la esquina superior izquierda de la imagen, en coordenadas de vista.

Valor devuelto

Puntero que apunta a la lista de imágenes de arrastre si se ejecuta correctamente; de lo contrario, NULL.

Comentarios

El objeto CImageList es permanente y debe eliminarlo cuando termine. Por ejemplo:

CImageList* pImageList = m_myListCtrl.CreateDragImage(nItem, &point);

// do something

delete pImageList;

CListCtrl::DeleteAllItems

Elimina todos los elementos del control de vista de lista.

BOOL DeleteAllItems();

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

// Delete all of the items from the list view control.
m_myListCtrl.DeleteAllItems();
ASSERT(m_myListCtrl.GetItemCount() == 0);

CListCtrl::DeleteColumn

Elimina una columna del control de vista de lista.

BOOL DeleteColumn(int nCol);

Parámetros

nCol
Índice de la columna que se va a eliminar.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

// Delete all of the columns.
for (int i=0; i < nColumnCount; i++)
{
    m_myListCtrl.DeleteColumn(0);
}

CListCtrl::DeleteItem

Elimina un elemento de un control de vista de lista.

BOOL DeleteItem(int nItem);

Parámetros

nItem
Especifica el índice del elemento de lista que se va a eliminar.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

int nCount = m_myListCtrl.GetItemCount();

// Delete all of the items from the list view control.
for (int i=0; i < nCount; i++)
{
    m_myListCtrl.DeleteItem(0);
}

CListCtrl::DrawItem

Lo llama el marco de trabajo cuando cambia un aspecto visual de un control de vista 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

El miembro itemAction de la estructura DRAWITEMSTRUCT define la acción de dibujo que se realizará.

De manera predeterminada, esta función miembro no hace nada. Invalida esta función miembro para implementar el dibujo de un objeto CListCtrl 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.

CListCtrl::EditLabel

Comienza la edición en contexto del texto de un elemento.

CEdit* EditLabel(int nItem);

Parámetros

nItem
Índice del elemento de vista de lista que se va a editar.

Valor devuelto

Si se ejecuta correctamente, un puntero apunta al objeto CEdit que se usa para editar el texto del elemento, de lo contrario NULL.

Comentarios

Un control de vista de lista que tiene el estilo de ventana LVS_EDITLABELS permite a un usuario editar etiquetas de elementos en contexto. El usuario comienza a editar al hacer clic en la etiqueta de un elemento que tiene el foco.

Use esta función para comenzar la edición en contexto del texto del elemento de vista de lista especificado.

Ejemplo

// Make sure the focus is set to the list view control.
m_myListCtrl.SetFocus();

// Show the edit control on the label of the first
// item in the list view control.
CEdit* pmyEdit = m_myListCtrl.EditLabel(1);
ASSERT(pmyEdit != NULL);

CListCtrl::EnableGroupView

Habilita o deshabilita si los elementos de un control de vista de lista se muestran como un grupo.

LRESULT EnableGroupView(BOOL fEnable);

Parámetros

fEnable
Indica si se va a habilitar un control de vista de lista para agrupar los elementos mostrados. TRUE para habilitar la agrupación; FALSE para deshabilitarla.

Valor devuelto

Devuelve uno de los valores siguientes:

• 0 La capacidad de mostrar elementos de vista de lista como un grupo ya está habilitada o deshabilitada.
• 1 El estado del control se cambió correctamente.
• -1 Error en la operación.

Comentarios

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

CListCtrl::EnsureVisible

Garantiza que un elemento de vista de lista sea al menos visible parcialmente.

BOOL EnsureVisible(
    int nItem,
    BOOL bPartialOK);

Parámetros

nItem
Índice del elemento de vista de lista que se va a ver.

bPartialOK
Especifica si la visibilidad parcial es aceptable.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

El control de vista de lista se desplaza si es necesario. Si el parámetro bPartialOK no es cero, no se produce ningún desplazamiento si el elemento está parcialmente visible.

Ejemplo

// Ensure that the last item is visible.
int nCount = m_myListCtrl.GetItemCount();
if (nCount > 0)
    m_myListCtrl.EnsureVisible(nCount-1, FALSE);

CListCtrl::FindItem

Busca un elemento de vista de lista con características especificadas.

int FindItem(
    LVFINDINFO* pFindInfo,
    int nStart = -1) const;

Parámetros

pFindInfo
Puntero que apunta a una estructura LVFINDINFO que contiene información sobre el elemento que se va a buscar.

nStart
Índice del elemento con el que se va a comenzar la búsqueda o -1 para empezar desde el principio. El elemento en nStart se excluye de la búsqueda si nStart no es igual a -1.

Valor devuelto

Índice del elemento si se ejecuta correctamente o -1 en caso contrario.

Comentarios

El parámetro pFindInfo apunta a una estructura LVFINDINFO, que contiene información utilizada para buscar un elemento de vista de lista.

Ejemplo

LVFINDINFO info;
int nIndex;

info.flags = LVFI_PARTIAL|LVFI_STRING;
info.psz = _T("item");

// Delete all of the items that begin with the string.
while ((nIndex = m_myListCtrl.FindItem(&info)) != -1)
{
    m_myListCtrl.DeleteItem(nIndex);
}

CListCtrl::GetBkColor

Recupera el color de fondo de un control de vista de lista.

COLORREF GetBkColor() const;

Valor devuelto

Valor de 32 bits usado para especificar un color RGB.

Ejemplo

Vea el ejemplo de CListCtrl::SetBkColor.

CListCtrl::GetBkImage

Recupera la imagen de fondo actual de un control de vista de lista.

BOOL GetBkImage(LVBKIMAGE* plvbkImage) const;

Parámetros

plvbkImage
Puntero que apunta a una estructura LVBKIMAGE que contiene la imagen de fondo actual de la vista de lista.

Valor devuelto

Devuelve un valor distinto de cero si se ejecuta correctamente o cero en caso contrario.

Comentarios

Este método, implementa el comportamiento de la macro de Win32, ListView_GetBkImage, tal y como se describe en Windows SDK.

Ejemplo

LVBKIMAGE bki;

// If no background image is set for the list view control use
// the Microsoft homepage image as the background image.
if (m_myListCtrl.GetBkImage(&bki) && (bki.ulFlags == LVBKIF_SOURCE_NONE))
{
    m_myListCtrl.SetBkImage(
        _T("https://www.microsoft.com/library/images/gifs/homepage/microsoft.gif"),
        TRUE);
}

CListCtrl::GetCallbackMask

Recupera la máscara de devolución de llamada de un control de vista de lista.

UINT GetCallbackMask() const;

Valor devuelto

Máscara de devolución de llamada del control de vista de lista.

Comentarios

Un "elemento de devolución de llamada" es un elemento de vista de lista para el que la aplicación, en lugar del control, almacena el texto, el icono o ambos. Aunque un control de vista de lista puede almacenar estos atributos, es posible que desee usar elementos de devolución de llamada si la aplicación ya mantiene parte de esta información. La máscara de devolución de llamada especifica qué bits de estado de elemento mantiene la aplicación y se aplica a todo el control en lugar de a un elemento específico. La máscara de devolución de llamada es cero de forma predeterminada, lo que significa que el control hace un seguimiento de todos los estados del elemento. Si una aplicación usa elementos de devolución de llamada o especifica una máscara de devolución de llamada distinto de cero, debe poder proporcionar atributos de elemento de vista de lista a petición.

Ejemplo

Vea el ejemplo de CListCtrl::SetCallbackMask.

CListCtrl::GetCheck

Recupera el estado de presentación actual de la imagen de estado asociada a un elemento.

BOOL GetCheck(int nItem) const;

Parámetros

nItem
Índice de base cero de un elemento de control de lista.

Valor devuelto

Distinto de cero si el elemento está seleccionado; de lo contrario, 0.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetCheckState, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CListCtrl::SetCheck.

CListCtrl::GetColumn

Recupera los atributos de la columna de un control de vista de lista.

BOOL GetColumn(
    int nCol,
    LVCOLUMN* pColumn) const;

Parámetros

nCol
Índice de la columna cuyos atributos se van a recuperar.

pColumn
Dirección de una estructura LVCOLUMN que especifica la información que se va a recuperar y recibe información sobre la columna. El miembro mask especifica qué atributos de la columna se van a recuperar. Si el miembro mask especifica el valor LVCF_TEXT, el miembro pszText debe contener la dirección del búfer que recibe el texto del elemento y el miembro cchTextMax debe especificar el tamaño del búfer.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

La estructura LVCOLUMN contiene información sobre una columna en la vista de informe.

Ejemplo

LVCOLUMN col;

col.mask = LVCF_WIDTH;

// Double the column width of the first column.
if (m_myListCtrl.GetColumn(0, &col))
{
    col.cx *= 2;
    m_myListCtrl.SetColumn(0, &col);
}

CListCtrl::GetColumnOrderArray

Recupera el orden de columna (de izquierda a derecha) de un control de vista de lista.

BOOL GetColumnOrderArray(
    LPINT piArray,
    int iCount = -1);

Parámetros

piArray
Puntero que apunta a un búfer que contendrá los valores de índice de las columnas del control de vista de lista. El búfer debe ser lo suficientemente grande como para contener la cantidad total de columnas del control de vista de lista.

iCount
Número de columnas del control de vista de lista. Si este parámetro es -1, el marco recupera automáticamente el número de columnas.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetColumnOrderArray, tal y como se describe en Windows SDK.

Ejemplo

// Reverse the order of the columns in the list view control
// (i.e. make the first column the last, the last column
// the first, and so on...).
CHeaderCtrl* pHeaderCtrl = m_myListCtrl.GetHeaderCtrl();

if (pHeaderCtrl != NULL)
{
    int  nColumnCount = pHeaderCtrl->GetItemCount();
    LPINT pnOrder = (LPINT) malloc(nColumnCount*sizeof(int));
    ASSERT(pnOrder != NULL);
    m_myListCtrl.GetColumnOrderArray(pnOrder, nColumnCount);

    int i, j, nTemp;
    for (i = 0, j = nColumnCount-1; i < j; i++, j--)
    {
        nTemp = pnOrder[i];
        pnOrder[i] = pnOrder[j];
        pnOrder[j] = nTemp;
    }

    m_myListCtrl.SetColumnOrderArray(nColumnCount, pnOrder);
    free(pnOrder);
}

CListCtrl::GetColumnWidth

Recupera el ancho de una columna en la vista de informe o vista de lista.

int GetColumnWidth(int nCol) const;

Parámetros

nCol
Especifica el índice de la columna cuyo ancho se va a recuperar.

Valor devuelto

Ancho en píxeles de la columna especificada por nCol.

Ejemplo

// Increase the column width of the second column by 20.
int nWidth = m_myListCtrl.GetColumnWidth(1);
m_myListCtrl.SetColumnWidth(1, 20 + nWidth);

CListCtrl::GetCountPerPage

Calcula la cantidad de elementos que pueden caber verticalmente en el área visible de un control de vista de lista cuando se encuentran en la vista de lista o en la vista de informe.

int GetCountPerPage() const;

Valor devuelto

Cantidad de elementos que pueden caber verticalmente en el área visible de un control de vista de lista cuando se encuentran en la vista de lista o en la vista de informe.

Ejemplo

Vea el ejemplo de CListCtrl::GetTopIndex.

CListCtrl::GetEditControl

Recupera el manipulador del control de edición usado para editar el texto de un elemento de vista de lista.

CEdit* GetEditControl() const;

Valor devuelto

Si se ejecuta correctamente, un puntero apunta al objeto CEdit que se usa para editar el texto del elemento, de lo contrario NULL.

Ejemplo

// The string replacing the text in the edit control.
LPCTSTR lpszmyString = _T("custom label!");

// If possible, replace the text in the label edit control.
CEdit* pEdit = m_myListCtrl.GetEditControl();

if (pEdit != NULL)
{
    pEdit->SetWindowText(lpszmyString);
}

CListCtrl::GetEmptyText

Recupera la cadena que se va a mostrar si el control de vista de lista actual está vacío.

CString GetEmptyText() const;

Valor devuelto

CString que contiene el texto que se va a mostrar si el control está vacío.

Comentarios

Al usar este método, se envía el mensaje LVM_GETEMPTYTEXT, que se describe en Windows SDK.

CListCtrl::GetExtendedStyle

Recupera los estilos extendidos actuales de un control de vista de lista.

DWORD GetExtendedStyle();

Valor devuelto

Combinación de los estilos extendidos que actualmente usa el control de vista de lista. Para obtener una lista descriptiva de estos estilos extendidos, consulte el artículo Estilos extendidos de la vista de lista en Windows SDK.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetExtendedListViewStyle, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CListCtrl::SetExtendedStyle.

CListCtrl::GetFirstSelectedItemPosition

Obtiene la posición del primer elemento seleccionado en el control de vista de lista.

POSITION GetFirstSelectedItemPosition() const;

Valor devuelto

Valor POSITION que se puede usar para la recuperación de puntero de objeto o iteración; NULL si ningún elemento está seleccionado.

Ejemplo

En el ejemplo de código siguiente se muestra el uso de esta función.

POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
if (pos == NULL)
{
    TRACE(_T("No items were selected!\n"));
}
else
{
    while (pos)
    {
        int nItem = m_myListCtrl.GetNextSelectedItem(pos);
        TRACE(_T("Item %d was selected!\n"), nItem);
        // you could do your own processing on nItem here
    }
}

CListCtrl::GetFocusedGroup

Recupera el grupo que tiene el foco del teclado en el control de vista de lista actual.

int GetFocusedGroup() const;

Valor devuelto

Índice del grupo cuyo estado es LVGS_FOCUSED, si hay un grupo de este tipo, de lo contrario, -1.

Comentarios

Al usar este método, se envía el mensaje LVM_GETFOCUSEDGROUP, que se describe en Windows SDK. Para más información, consulte el valor LVGS_FOCUSED del miembro statede la estructura LVGROUP.

CListCtrl::GetGroupCount

Recupera el número de grupos del control de vista de lista actual.

int GetGroupCount()const;

Valor devuelto

Número de grupos del control de vista de lista.

Comentarios

Al usar este método, se envía el mensaje LVM_GETGROUPCOUNT, que se describe en Windows SDK -->.

CListCtrl::GetGroupInfo

Obtiene la información de un grupo especificado del control de vista de lista.

int GetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp) const;

Parámetros

iGroupId
Identificador del grupo cuya información se va a recuperar.

pgrp
Puntero que apunta a la información contenedora de LVGROUP del grupo especificado.

Valor devuelto

Devuelve el identificador del grupo si se ejecuta correctamente, de lo contrario, -1.

Comentarios

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

CListCtrl::GetGroupInfoByIndex

Recupera la información sobre un grupo especificado del control de vista de lista actual.

BOOL GetGroupInfoByIndex(
    int iIndex,
    PLVGROUP pGroup) const;

Parámetros

iIndex
[Entrada] Índice de base cero de un grupo.

pGroup
[salida] Puntero que apunta a una estructura LVGROUP que recibe información sobre el grupo especificado por el parámetro iIndex. El autor de la llamada es responsable de inicializar los miembros de la estructura LVGROUP. Establezca el miembro cbSize en el tamaño de la estructura y las marcas del miembro mask para especificar la información que se va a recuperar.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Al usar este método, se envía el mensaje LVM_GETGROUPINFOBYINDEX, que se describe en Windows SDK -->.

Ejemplo

En el primer ejemplo de código se define una variable, m_listCtrl, que se usa para acceder al control de vista de lista actual. Esta variable se utiliza en el siguiente ejemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

En el siguiente código de ejemplo se muestra el método GetGroupInfoByIndex. En una sección anterior de este ejemplo de código, creamos un control de vista de lista que muestra dos columnas tituladas "ClientID" y "Grade" en una vista de informe. En el ejemplo de código siguiente se recupera información sobre el grupo cuyo índice es 0, si existe dicho grupo.

// GetGroupInfoByIndex
const int GROUP_HEADER_BUFFER_SIZE = 40;

// Initialize the structure
LVGROUP gInfo = {0};
gInfo.cbSize = sizeof(LVGROUP);
wchar_t wstrHeadGet[GROUP_HEADER_BUFFER_SIZE] = {0};
gInfo.cchHeader = GROUP_HEADER_BUFFER_SIZE;
gInfo.pszHeader = wstrHeadGet;
gInfo.mask = (LVGF_ALIGN | LVGF_STATE | LVGF_HEADER | LVGF_GROUPID);
gInfo.state = LVGS_NORMAL;
gInfo.uAlign  = LVGA_HEADER_LEFT;

BOOL bRet = m_listCtrl.GetGroupInfoByIndex( 0, &gInfo );
if (bRet == TRUE) {
    CString strHeader = CString( gInfo.pszHeader );
    CString str;
    str.Format(_T("Header: '%s'"), strHeader);
    AfxMessageBox(str, MB_ICONINFORMATION);
}
else
{
    AfxMessageBox(_T("No group information was retrieved."));
}

CListCtrl::GetGroupMetrics

Recupera las métricas de un grupo.

void GetGroupMetrics(PLVGROUPMETRICS pGroupMetrics) const;

Parámetros

pGroupMetrics
Puntero que apunta a un objeto LVGROUPMETRICS que contiene la información de métricas de grupo.

Comentarios

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

CListCtrl::GetGroupRect

Recupera el rectángulo delimitador de un grupo especificado del control de vista de lista actual.

BOOL GetGroupRect(
    int iGroupId,
    LPRECT lpRect,
    int iCoords = LVGGR_GROUP) const;

Parámetros

iGroupId
[entrada] Especifica un grupo.

lpRect
[entrada, salida] Puntero que apunta a una estructura RECT. Si este método se ejecuta correctamente, la estructura recibe las coordenadas del rectángulo del grupo especificado por iGroupId.

iCoords
[entrada] Especifica las coordenadas del rectángulo que se van a recuperar. Utilice uno de estos valores:

• LVGGR_GROUP: (valor predeterminado) Coordenadas de todo el grupo expandido.
• LVGGR_HEADER: Coordenadas de solo el encabezado (grupo contraído).
• LVGGR_SUBSETLINK: Coordenadas de solo el vínculo de subconjunto (subconjunto de marcado).

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

El autor de la llamada es responsable de asignar la estructura RECT a la que apunta el parámetro pRect.

Al usar este método, se envía el mensaje LVM_GETGROUPRECT, que se describe en Windows SDK.

Ejemplo

En el primer ejemplo de código se define una variable, m_listCtrl, que se usa para acceder al control de vista de lista actual. Esta variable se utiliza en el siguiente ejemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

En el siguiente código de ejemplo se muestra el método GetGroupRect. En una sección anterior de este ejemplo de código, creamos un control de vista de lista que muestra dos columnas tituladas "ClientID" y "Grade" en una vista de informe. En el ejemplo de código siguiente se dibuja un rectángulo 3D alrededor del grupo cuyo índice es 0, si existe dicho grupo.

// GetGroupRect

// Get the graphics rectangle that surrounds group 0.
CRect rect;
BOOL bRet = m_listCtrl.GetGroupRect( 0, &rect, LVGGR_GROUP);
// Draw a blue rectangle around group 0.
if (bRet == TRUE) {
    m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(0, 0, 255), RGB(0, 0, 255));
}
else {
    AfxMessageBox(_T("No group information was retrieved."), MB_ICONINFORMATION);
}

CListCtrl::GetGroupState

Recupera el estado de un grupo especificado del control de vista de lista actual.

UINT GetGroupState(
    int iGroupId,
    DWORD dwMask) const;

Parámetros

iGroupId
[Entrada] Índice de base cero de un grupo.

dwMask
[entrada] Máscara que especifica el valor de estado que se va a recuperar para grupo especificado. Para obtener más información, consulte el miembro mask de la estructura LVGROUP.

Valor devuelto

Estado solicitado del grupo especificado o 0 si no se encuentra el grupo.

Comentarios

El valor devuelto es el resultado de una operación AND bit a bit en el parámetro dwMask y el valor del miembro state de una estructura LVGROUP que representa el control de vista de lista actual.

Al usar este método, se envía el mensaje LVM_GETGROUPSTATE, que se describe en Windows SDK. Para más información, consulte la macro ListView_GetGroupState.

CListCtrl::GetHeaderCtrl

Recupera el control de encabezado de un control de vista de lista.

CHeaderCtrl* GetHeaderCtrl();

Valor devuelto

Puntero que apunta al control de encabezado, utilizado por el control de vista de lista.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetHeader, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CListCtrl::GetColumnOrderArray.

CListCtrl::GetHotCursor

Recupera el cursor utilizado cuando el seguimiento activo está habilitado para un control de vista de lista.

HCURSOR GetHotCursor();

Valor devuelto

Manipulador del recurso de cursor activo actual que usa el control de vista de lista.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetHotCursor, tal y como se describe en Windows SDK. El cursor activo, solo visible cuando se habilita la selección mediante movimiento del mouse, aparece cuando el cursor pasa sobre cualquier elemento de vista de lista. La selección mediante movimiento del mouse se habilita al establecer el estilo extendido LVS_EX_TRACKSELECT.

Ejemplo

// Set the hot cursor to be the system app starting cursor.
HCURSOR hCursor = ::LoadCursor(NULL, IDC_APPSTARTING);
m_myListCtrl.SetHotCursor(hCursor);
ASSERT(m_myListCtrl.GetHotCursor() == hCursor);

CListCtrl::GetHotItem

Recupera el elemento de vista de lista actualmente bajo el cursor.

int GetHotItem();

Valor devuelto

Índice del elemento activo actual del control de vista de lista.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetHotItem, tal y como se describe en Windows SDK. El elemento activo se define como el elemento seleccionado actualmente cuando se habilita el seguimiento activo (y la selección mediante movimiento del mouse).

Si el seguimiento activo está habilitado, cuando un usuario se detiene sobre un elemento de la vista de lista, la etiqueta del elemento se resalta automáticamente sin usar un botón del mouse.

Ejemplo

// Set the hot item to the first item only if no other item is
// highlighted.
if (m_myListCtrl.GetHotItem() == -1)
    m_myListCtrl.SetHotItem(0);

CListCtrl::GetHoverTime

Recupera el tiempo actual del movimiento del mouse de un control de vista de lista.

DWORD GetHoverTime() const;

Valor devuelto

Devuelve el retraso, en milisegundos, que el cursor del mouse debe mantener el puntero sobre un elemento antes de seleccionarlo. Si el valor devuelto es -1, el tiempo del movimiento del mouse es el predeterminado.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetHoverTime, tal y como se describe en Windows SDK.

Ejemplo

// If the hover time is the default set to 1 sec.
DWORD dwTime = m_myListCtrl.GetHoverTime();
if (dwTime == -1)
    m_myListCtrl.SetHoverTime(1000);

CListCtrl::GetImageList

Recupera el manipulador de una lista de imágenes utilizada para dibujar elementos de vista de lista.

CImageList* GetImageList(int nImageList) const;

Parámetros

nImageList
Valor que especifica qué lista de imágenes se va a recuperar. Puede ser uno de estos valores:

• LVSIL_NORMAL Lista de imágenes con iconos grandes.
• LVSIL_SMALL Lista de imágenes con iconos pequeños.
• LVSIL_STATE Lista de imágenes con imágenes de estado.

Valor devuelto

Puntero que apunta a la lista de imágenes usada para los elementos de vista de lista de dibujo.

Ejemplo

ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == NULL);
m_myListCtrl.SetImageList(&m_lcImageList, LVSIL_NORMAL);
ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == &m_lcImageList);

CListCtrl::GetInsertMark

Recupera la posición actual de la marca de inserción.

BOOL GetInsertMark(LPLVINSERTMARK plvim) const;

Parámetros

plvim
Puntero que apunta a una estructura LVINSERTMARK que contiene la información de la marca de inserción.

Valor devuelto

Devuelve TRUE si se realizó correctamente; de lo contrario, FALSE. FALSE se devuelve si el tamaño del miembro cbSize de la estructura LVINSERTMARK no es igual al tamaño real de la estructura.

Comentarios

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

CListCtrl::GetInsertMarkColor

Recupera el color actual de la marca de inserción.

COLORREF GetInsertMarkColor() const;

Valor devuelto

Devuelve una estructura COLORREF que contiene el color del punto de inserción.

Comentarios

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

CListCtrl::GetInsertMarkRect

Recupera el rectángulo que enlaza el punto de inserción.

int GetInsertMarkRect(LPRECT pRect) const;

Parámetros

pRect
Puntero que apunta a una estructura RECT que contiene las coordenadas de un rectángulo que enlaza el punto de inserción.

Valor devuelto

Devuelve uno de los valores siguientes:

• 0 No se encontró ningún punto de inserción.
• 1 Se encontró el punto de inserción.

Comentarios

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

CListCtrl::GetItem

Recupera algunos o todos los atributos de un elemento de vista de lista.

BOOL GetItem(LVITEM* pItem) const;

Parámetros

pItem
Puntero que apunta a una estructura LVITEM que recibe los atributos del elemento.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

La estructura LVITEM especifica o recibe los atributos de un elemento de vista de lista.

CListCtrl::GetItemCount

Recupera el número de elementos de un control de vista de lista.

int GetItemCount() const;

Valor devuelto

Número de elementos del control de vista de lista.

Ejemplo

Vea el ejemplo de CListCtrl::DeleteItem.

CListCtrl::GetItemData

Recupera el valor específico de la aplicación de 32 bits (64 bits si compila para x64) asociado al elemento especificado por nItem.

DWORD_PTR GetItemData(int nItem) const;

Parámetros

nItem
Índice del elemento de lista cuyos datos se van a recuperar.

Valor devuelto

Valor específico de la aplicación de 32 bits (64 bits si compila para x64) asociado al elemento especificado.

Comentarios

Este valor es el miembro lParam de la estructura LVITEM, como se describe en Windows SDK.

Ejemplo

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

CListCtrl::GetItemIndexRect

Recupera el rectángulo delimitador para todo un subelemento o parte de este en el control de vista de lista actual.

BOOL GetItemIndexRect(
    PLVITEMINDEX pItemIndex,
    int iColumn,
    int rectType,
    LPRECT pRect) const;

Parámetros

pItemIndex
[entrada] Puntero que apunta a una estructura LVITEMINDEX para el elemento primario del subelemento. El autor de la llamada es responsable de asignar y establecer los miembros de la estructura LVITEMINDEX. Este parámetro no puede ser NULL.

iColumn
[entrada] Índice de base cero de una columna en el control.

rectType
[entrada] Parte del subelemento de vista de lista para el que se recupera el rectángulo delimitador. Especifique uno de los siguientes valores:

• LVIR_BOUNDS: devuelve el rectángulo delimitador de todo el subelemento, incluido el icono y la etiqueta.
• LVIR_ICON: devuelve el rectángulo delimitador del icono o icono pequeño del subelemento.
• LVIR_LABEL: devuelve el rectángulo delimitador del texto del subelemento.

pRect
[salida] Puntero que apunta a una estructura RECT que recibe información sobre el rectángulo delimitador del subelemento. El autor de la llamada es responsable de asignar la estructura RECT. Este parámetro no puede ser NULL.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Al usar este método, se envía el mensaje LVM_GETITEMINDEXRECT, que se describe en Windows SDK. Para más información, consulte Macro ListView_GetItemIndexRect.

Ejemplo

En el primer ejemplo de código se define una variable, m_listCtrl, que se usa para acceder al control de vista de lista actual. Esta variable se utiliza en el siguiente ejemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

En el siguiente código de ejemplo se muestra el método GetGroupRect. Antes de escribir este ejemplo de código, se ha creado un control de vista de lista que muestra dos columnas tituladas "ClientID" y "Grade" en una vista de informe. En el ejemplo de código siguiente se dibuja un rectángulo 3D alrededor del segundo subelemento en ambas columnas.

// GetItemIndexRect
// Get the rectangle that bounds the second item in the first group.
LVITEMINDEX lvItemIndex;
lvItemIndex.iGroup = 0;
lvItemIndex.iItem = 1;
CRect rect;
BOOL bRet = m_listCtrl.GetItemIndexRect(
    &lvItemIndex, 0, LVIR_BOUNDS, &rect);

// Draw a red rectangle around the item.
m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(255, 0, 0), RGB(255, 0, 0) );

CListCtrl::GetItemPosition

Recupera la posición de un elemento de vista de lista.

BOOL GetItemPosition(
    int nItem,
    LPPOINT lpPoint) const;

Parámetros

nItem
Índice del elemento cuya posición se va a recuperar.

lpPoint
Dirección de una estructura POINT que recibe la posición de la esquina superior izquierda del elemento, en coordenadas de vista.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

POINT pt;

// Move all items in the list control 100 pixels to the right.
UINT i, nCount = m_myListCtrl.GetItemCount();

for (i=0; i < nCount; i++)
{
    m_myListCtrl.GetItemPosition(i, &pt);
    pt.x += 100;
    m_myListCtrl.SetItemPosition(i, pt);
}

CListCtrl::GetItemRect

Recupera el rectángulo delimitador de todo un elemento o parte de este de la vista actual.

BOOL GetItemRect(
    int nItem,
    LPRECT lpRect,
    UINT nCode) const;

Parámetros

nItem
Índice del elemento cuya posición se va a recuperar.

lpRect
Dirección de una estructura RECT que recibe el rectángulo delimitador.

nCode
Parte del elemento de vista de lista para el que se va a recuperar el rectángulo delimitador. Puede ser uno de estos valores:

• LVIR_BOUNDS: devuelve el rectángulo delimitador de todo el elemento, incluido el icono y la etiqueta.
• LVIR_ICON: devuelve el rectángulo delimitador del icono o icono pequeño.
• LVIR_LABEL: devuelve el rectángulo delimitador del texto del elemento.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

// OnClick is the handler for the NM_CLICK notification
void CListCtrlDlg::OnClick(NMHDR* pNMHDR, LRESULT* pResult)
{
    UNREFERENCED_PARAMETER(pResult);
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;

    // Get the current mouse location and convert it to client
    // coordinates.
    CPoint pos( ::GetMessagePos() );
    ScreenToClient(&pos);

    // Get indexes of the first and last visible items in
    // the listview control.
    int index = m_myListCtrl.GetTopIndex();
    int last_visible_index = index + m_myListCtrl.GetCountPerPage();
    if (last_visible_index > m_myListCtrl.GetItemCount())
        last_visible_index = m_myListCtrl.GetItemCount();

    // Loop until number visible items has been reached.
    while (index <= last_visible_index)
    {
        // Get the bounding rectangle of an item. If the mouse
        // location is within the bounding rectangle of the item,
        // you know you have found the item that was being clicked.
        CRect r;
        m_myListCtrl.GetItemRect(index, &r, LVIR_BOUNDS);
        if (r.PtInRect(pia->ptAction))
        {
            UINT flag = LVIS_SELECTED | LVIS_FOCUSED;
            m_myListCtrl.SetItemState(index, flag, flag);
            break;
        }

        // Get the next item in listview control.
        index++;
    }
}

CListCtrl::GetItemSpacing

Calcula el espaciado entre los elementos del control de vista de lista actual.

BOOL GetItemSpacing(
    BOOL fSmall,
    int* pnHorzSpacing,
    int* pnVertSpacing) const;

Parámetros

fSmall
[entrada] Vista para la que se va a recuperar el espaciado de elementos. Especifique TRUE para la vista de icono pequeño o FALSE para la vista de icono.

pnHorzSpacing
[salida] Contiene el espaciado horizontal entre elementos.

pnVertSpacing
[salida] Contiene el espaciado vertical entre elementos.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Al usar este método, se envía el mensaje LVM_GETITEMSPACING, que se describe en Windows SDK.

CListCtrl::GetItemState

Recupera el estado de un elemento de vista de lista.

UINT GetItemState(
    int nItem,
    UINT nMask) const;

Parámetros

nItem
Índice del elemento cuyo estado se va a recuperar.

nMask
Máscara que especifica cuál de las marcas de estado del elemento se van a devolver.

Valor devuelto

Marcas de estado del elemento de vista de lista especificado.

Comentarios

El miembro state de la estructura LVITEM especifica el estado de un elemento, como se describe en Windows SDK. Al especificar o cambiar el estado de un elemento, el miembro stateMask indica qué bits de estado quiere cambiar.

Ejemplo

Vea el ejemplo de CListCtrl::GetTopIndex.

CListCtrl::GetItemText

Recupera el texto de un elemento o subelemento de vista de lista.

int GetItemText(
    int nItem,
    int nSubItem,
    LPTSTR lpszText,
    int nLen) const;

CString GetItemText(
    int nItem,
    int nSubItem) const;

Parámetros

nItem
Índice del elemento cuyo texto se va a recuperar.

nSubItem
Especifica el subelemento cuyo texto se va a recuperar.

lpszText
Puntero que apunta a una cadena que va a recibir el texto del elemento.

nLen
Longitud del búfer al que apunta lpszText.

Valor devuelto

La versión que devuelve int devuelve la longitud de la cadena recuperada.

La versión que devuelve una clase CString devuelve el texto del elemento.

Comentarios

Si nSubItem es cero, esta función recupera la etiqueta del elemento; si nSubItem no es cero, recupera el texto del subelemento. Para más información sobre el argumento del subelemento, consulte la explicación de la estructura LVITEM en Windows SDK.

CListCtrl::GetNextItem

Busca un elemento de vista de lista que tenga las propiedades especificadas y que contenga la relación especificada con un elemento determinado.

int GetNextItem(
    int nItem,
    int nFlags) const;

Parámetros

nItem
Índice del elemento con el que se va a comenzar la búsqueda o -1 para buscar el primer elemento que coincida con las marcas especificadas. El propio elemento especificado se excluye de la búsqueda.

nFlags
Relación geométrica del elemento solicitado con el elemento especificado y el estado del elemento solicitado. La relación geométrica puede ser uno de estos valores:

• LVNI_ABOVE Busca un elemento situado encima del elemento especificado.
• LVNI_ALL Busca un elemento posterior por índice (el valor predeterminado).
• LVNI_BELOW Busca un elemento situado debajo del elemento especificado.
• LVNI_TOLEFT Busca un elemento a la izquierda del elemento especificado.
• LVNI_TORIGHT Busca un elemento a la derecha del elemento especificado.

El estado puede ser cero o puede ser uno o varios de estos valores:

• LVNI_DROPHILITED El elemento tiene la marca de estado LVIS_DROPHILITED establecida.
• LVNI_FOCUSED El elemento tiene la marca de estado LVIS_FOCUSED establecida.
• LVNI_SELECTED El elemento tiene la marca de estado LVIS_SELECTED establecida.

Si un elemento no tiene establecidas todas las marcas de estado especificadas, la búsqueda continúa con el siguiente elemento.

Valor devuelto

Índice del siguiente elemento si se ejecuta correctamente o -1 de lo contrario.

CListCtrl::GetNextItemIndex

Recupera el índice del elemento del control de vista de lista actual que tiene un conjunto especificado de propiedades.

BOOL GetNextItemIndex(
    PLVITEMINDEX pItemIndex,
    int nFlags) const;

Parámetros

pItemIndex
[entrada, salida] Puntero que apunta a la estructura LVITEMINDEX que describe el elemento donde comienza la búsqueda o -1 para buscar el primer elemento que coincida con las marcas en el parámetro nFlags. Si este método se ejecuta correctamente, la estructura LVITEMINDEX describe el elemento encontrado por la búsqueda.

nFlags
[entrada] Combinación bit a bit (OR) de marcas que especifican cómo hacer la búsqueda. La búsqueda puede depender del índice, el estado o la apariencia del elemento de destino, o la posición física del elemento de destino en relación con el elemento especificado por el parámetro pItemIndex. Para más información, consulte el parámetro flags del mensaje LVM_GETNEXTITEMINDEX.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

El autor de la llamada es responsable de asignar y establecer los miembros de la estructura LVITEMINDEX a los que apunta el parámetro pItemIndex.

Al usar este método, se envía el mensaje LVM_GETNEXTITEMINDEX, que se describe en Windows SDK.

CListCtrl::GetNextSelectedItem

Obtiene el índice del elemento de lista identificado por posy, luego, establece pos en el valor POSITION.

int GetNextSelectedItem(POSITION& pos) const;

Parámetros

pos
Referencia a un valor POSITION devuelto por una llamada anterior a GetNextSelectedItem o GetFirstSelectedItemPosition. Esta llamada actualiza el valor a la siguiente posición.

Valor devuelto

Índice del elemento de lista identificado por pos.

Comentarios

Puede usar GetNextSelectedItem en un bucle de iteración hacia delante si establece la posición inicial con una llamada a GetFirstSelectedItemPosition.

Debe asegurarse de que el valor POSITION es válido. Si no es válida, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class).

Ejemplo

En el ejemplo de código siguiente se muestra el uso de esta función.

POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
if (pos == NULL)
{
    TRACE(_T("No items were selected!\n"));
}
else
{
    while (pos)
    {
        int nItem = m_myListCtrl.GetNextSelectedItem(pos);
        TRACE(_T("Item %d was selected!\n"), nItem);
        // you could do your own processing on nItem here
    }
}

CListCtrl::GetNumberOfWorkAreas

Recupera el número actual de áreas de trabajo de un control de vista de lista.

UINT GetNumberOfWorkAreas() const;

Valor devuelto

No se usa en este momento.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetNumberOfWorkAreas, tal y como se describe en Windows SDK.

Ejemplo

UINT i, uCount = m_myListCtrl.GetNumberOfWorkAreas();
LPRECT lpRects = (LPRECT) malloc(uCount*sizeof(RECT));

if (lpRects != NULL)
{
    // Dump all of the work area dimensions.
    m_myListCtrl.GetWorkAreas(uCount, lpRects);

    for (i=0; i < uCount; i++)
    {
        TRACE(_T("Work area %d; left = %d, top = %d, right = %d, ")
            _T("bottom = %d\r\n"),
            i, lpRects[i].left, lpRects[i].top, lpRects[i].right,
            lpRects[i].bottom);
    }

    free(lpRects);
}
else
{
    TRACE(_T("Couldn't allocate enough memory!"));
}

CListCtrl::GetOutlineColor

Recupera el color del borde de un control de vista de lista.

COLORREF GetOutlineColor() const;

Valor devuelto

Devuelve una estructura COLORREF que contiene el color del contorno.

Comentarios

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

CListCtrl::GetOrigin

Recupera el origen de la vista actual de un control de vista de lista.

BOOL GetOrigin(LPPOINT lpPoint) const;

Parámetros

lpPoint
Dirección de una estructura POINT que recibe el origen de la vista.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero. Sin embargo, si el control está en la vista de informe, el valor devuelto siempre es cero.

CListCtrl::GetSelectedColumn

Recupera el índice de la columna seleccionada actualmente en el control de lista.

UINT GetSelectedColumn() const;

Valor devuelto

Índice de la columna seleccionada.

Comentarios

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

CListCtrl::GetSelectedCount

Recupera el número de elementos seleccionados en el control de vista de lista.

UINT GetSelectedCount() const;

Valor devuelto

Número de elementos seleccionados en el control de vista de lista.

Ejemplo

UINT i, uSelectedCount = m_myListCtrl.GetSelectedCount();
int  nItem = -1;

// Update all of the selected items.
if (uSelectedCount > 0)
{
    for (i=0; i < uSelectedCount; i++)
    {
        nItem = m_myListCtrl.GetNextItem(nItem, LVNI_SELECTED);
        ASSERT(nItem != -1);
        m_myListCtrl.Update(nItem);
    }
}

CListCtrl::GetSelectionMark

Recupera la marca de selección de un control de vista de lista.

int GetSelectionMark();

Valor devuelto

Marca de selección de base cero o -1 si no hay ninguna marca de selección.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetSelectionMark, tal y como se describe en Windows SDK.

Ejemplo

// Set the selection mark to the first item only if no other item is
// selected.
if (m_myListCtrl.GetSelectionMark() == -1)
    m_myListCtrl.SetSelectionMark(0);

CListCtrl::GetStringWidth

Determina el ancho de columna mínimo necesario para mostrar toda una cadena determinada.

int GetStringWidth(LPCTSTR lpsz) const;

Parámetros

lpsz
Dirección de una cadena terminada en un valor null cuyo ancho se va a determinar.

Valor devuelto

Ancho, en píxeles, de la cadena a la que lpsz apunta.

Comentarios

El ancho devuelto toma en cuenta los márgenes actuales de fuente y columna del control, pero no el ancho de un icono pequeño.

Ejemplo

CString strColumn;
int nWidth;

// Insert six columns in the list view control. Make the width of
// the column be the width of the column header plus 50%.
for (int i = 0; i < 6; i++)
{
    strColumn.Format(_T("column %d"), i);
    nWidth = 3*m_myListCtrl.GetStringWidth(strColumn)/2;
    m_myListCtrl.InsertColumn(i, strColumn, LVCFMT_LEFT, nWidth);
}

CListCtrl::GetSubItemRect

Recupera el rectángulo delimitador de un elemento de un control de vista de lista.

BOOL GetSubItemRect(
    int iItem,
    int iSubItem,
    int nArea,
    CRect& ref);

Parámetros

iItem
Índice del elemento primario del subelemento.

iSubItem
Índice basado en uno del subelemento.

nArea
Determina la parte del rectángulo delimitador (del subelemento de vista de lista) que se va a recuperar. La parte (icono, etiqueta o ambos) del rectángulo delimitador se especifica al aplicar el operador OR bit a bit a uno o varios de los valores siguientes:

• LVIR_BOUNDS: devuelve el rectángulo delimitador de todo el elemento, incluido el icono y la etiqueta.
• LVIR_ICON: devuelve el rectángulo delimitador del icono o icono pequeño.
• LVIR_LABEL: devuelve el rectángulo delimitador de todo el elemento, incluido el icono y la etiqueta. Esto es idéntico a LVIR_BOUNDS.

ref
Referencia a un objeto CRect que contiene las coordenadas del rectángulo delimitador del subelemento.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetSubItemRect, tal y como se describe en Windows SDK.

CListCtrl::GetTextBkColor

Recupera el color de fondo del texto de un control de vista de lista.

COLORREF GetTextBkColor() const;

Valor devuelto

Valor de 32 bits usado para especificar un color RGB.

Ejemplo

Vea el ejemplo de CListCtrl::SetTextBkColor.

CListCtrl::GetTextColor

Recupera el color de texto de un control de vista de lista.

COLORREF GetTextColor() const;

Valor devuelto

Valor de 32 bits usado para especificar un color RGB.

Ejemplo

Vea el ejemplo de CListCtrl::SetTextColor.

CListCtrl::GetTileInfo

Recupera información sobre un mosaico de un control de vista de lista.

BOOL GetTileInfo(PLVTILEINFO plvti) const;

Parámetros

plvti
Un puntero que apunta a una estructura LVTILEINFO que recibe la información del mosaico.

Valor devuelto

No se usa el valor devuelto.

Comentarios

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

CListCtrl::GetTileViewInfo

Recupera información sobre un control de vista de lista en la vista de mosaico.

BOOL GetTileViewInfo(PLVTILEVIEWINFO ptvi) const;

Parámetros

ptvi
Un puntero que apunta a una estructura LVTILEVIEWINFO que recibe la información recuperada.

Valor devuelto

No se usa el valor devuelto.

Comentarios

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

CListCtrl::GetToolTips

Recupera el control de información sobre herramientas que usa el control de vista de lista para mostrar información sobre herramientas.

CToolTipCtrl* GetToolTips() const;

Valor devuelto

Puntero que apunta a un objeto CToolTipCtrl que va a usar el control de lista. Si la función miembro Create usa el estilo LVS_NOTOOLTIPS, no se usa ninguna información sobre herramientas y se devuelve el valor NULL.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje LVM_GETTOOLTIPS de Win32, tal y como se describe en Windows SDK. La implementación de MFC de GetToolTips devuelve un objeto CToolTipCtrl, que usa el control de lista, en lugar de un manipulador para un control de información sobre herramientas.

Ejemplo

CToolTipCtrl* pTip = m_myListCtrl.GetToolTips();
if (NULL != pTip)
{
    pTip->UpdateTipText(_T("I'm a list view!"), &m_myListCtrl,
        IDD_MYLISTCTRL);
}

CListCtrl::GetTopIndex

Recupera el índice del elemento visible más de nivel superior cuando está en la vista de lista o en la vista de informe.

int GetTopIndex() const;

Valor devuelto

Índice del elemento visible de nivel superior.

Ejemplo

// Make sure the focus is set to the list view control.
m_myListCtrl.SetFocus();

// Select all of the items that are completely visible.
int n = m_myListCtrl.GetTopIndex();
int nLast = n + m_myListCtrl.GetCountPerPage();

for (; n < nLast; n++)
{
    m_myListCtrl.SetItemState(n, LVIS_SELECTED, LVIS_SELECTED);
    ASSERT(m_myListCtrl.GetItemState(n, LVIS_SELECTED) == LVIS_SELECTED);
}

CListCtrl::GetView

Obtiene la vista del control de vista de lista.

DWORD GetView() const;

Valor devuelto

Vista actual del control de vista de lista.

Comentarios

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

CListCtrl::GetViewRect

Recupera el rectángulo delimitador de todos los elementos del control de vista de lista.

BOOL GetViewRect(LPRECT lpRect) const;

Parámetros

lpRect
Dirección de una estructura RECT.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

La vista de lista debe estar en la vista de icono o en la vista de icono pequeño.

CListCtrl::GetWorkAreas

Recupera las áreas de trabajo actuales de un control de vista de lista.

void GetWorkAreas(
    int nWorkAreas,
    LPRECT pRect) const;

Parámetros

nWorkAreas
Número de estructuras RECT contenidas en la matriz pRect.

pRect
Puntero que apunta a una matriz de estructuras RECT (u objetos CRect) que reciben las áreas de trabajo del control de vista de lista. Los valores de estas estructuras están en las coordenadas cliente.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_GetWorkAreas, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CListCtrl::GetNumberOfWorkAreas.

CListCtrl::HasGroup

Determina si el control de vista de lista tiene el grupo especificado.

BOOL HasGroup(int iGroupId) const;

Parámetros

iGroupId
Identificador del grupo que se solicita.

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

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

CListCtrl::HitTest

Determina qué elemento de vista de lista, si existe, está en una posición especificada.

int HitTest(LVHITTESTINFO* pHitTestInfo) const;

int HitTest(
    CPoint pt,
    UINT* pFlags = NULL) const;

Parámetros

pHitTestInfo
Dirección de una estructura LVHITTESTINFO que contiene la posición de la prueba de posicionamiento y que recibe información sobre los resultados de la prueba de posicionamiento.

pt
Apunte a probar.

pFlags
Puntero que apunta a un entero que recibe información sobre los resultados de la prueba. Vea la explicación del miembro flags de la estructura LVHITTESTINFO en Windows SDK.

Valor devuelto

Índice del elemento en la posición especificada por pHitTestInfo, si existe o -1 en caso contrario.

Comentarios

Puede usar los valores LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFT y LVHT_TORIGHT del miembro flag de la estructura para determinar si se va a desplazar el contenido de un control de vista de lista. Se pueden combinar dos de estas marcas, por ejemplo, si la posición está por encima y a la izquierda del área cliente.

Puede probar el valor LVHT_ONITEM del miembro flag de la estructura para determinar si una posición determinada se encuentra sobre un elemento de vista de lista. Este valor es una operación OR bit a bit en los valores LVHT_ONITEMICON, LVHT_ONITEMLABEL y LVHT_ONITEMSTATEICON del miembro flag de la estructura.

Ejemplo

void CListCtrlDlg::OnRClick(NMHDR* pNMHDR, LRESULT* pResult)
{
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
    CPoint point(pia->ptAction);

    // Select the item the user clicked on.
    UINT uFlags;
    int nItem = m_myListCtrl.HitTest(point, &uFlags);

    if (uFlags & LVHT_ONITEMLABEL)
    {
        m_myListCtrl.SetItem(nItem, 0, LVIF_STATE, NULL, 0, LVIS_SELECTED,
            LVIS_SELECTED, 0);
    }

    *pResult = 0;
}

CListCtrl::InsertColumn

Inserta una columna nueva en un control de vista de lista.

int InsertColumn(
    int nCol,
    const LVCOLUMN* pColumn);

int InsertColumn(
    int nCol,
    LPCTSTR lpszColumnHeading,
    int nFormat = LVCFMT_LEFT,
    int nWidth = -1,
    int nSubItem = -1);

Parámetros

nCol
Índice de la nueva columna.

pColumn
Dirección de una estructura LVCOLUMN que contiene los atributos de la nueva columna.

lpszColumnHeading
Dirección de una cadena que contiene el título de la columna.

nFormat
Entero que especifica la alineación de la columna. Puede ser uno de estos valores: LVCFMT_LEFT, LVCFMT_RIGHT o LVCFMT_CENTER.

nWidth
Ancho de la columna, expresado en píxeles. Si este parámetro es -1, no se establece el ancho de columna.

nSubItem
Índice del subelemento asociado a la columna. Si este parámetro es -1, no hay ningún subelemento asociado a la columna.

Valor devuelto

Índice de la nueva columna si se ejecuta correctamente o -1 en caso contrario.

Comentarios

La columna situada en el extremo izquierdo de un control de vista de lista debe estar alineada a la izquierda.

La estructura LVCOLUMN contiene los atributos de una columna en la vista de informe. También se usa para recibir información sobre una columna. Esta estructura se describe en Windows SDK.

CListCtrl::InsertGroup

Inserta un grupo en el control de vista de lista.

LRESULT InsertGroup(
    int index,
    PLVGROUP pgrp);

Parámetros

index
Índice del elemento donde se va a insertar el grupo.

pgrp
Puntero que apunta a una estructura LVGROUP que contiene el grupo que se va a agregar.

Valor devuelto

Devuelve el índice del elemento al que se agregó el grupo o -1 si se produjo un error en la operación.

Comentarios

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

CListCtrl::InsertGroupSorted

Inserta el grupo especificado en una lista ordenada de grupos.

LRESULT InsertGroupSorted(PLVINSERTGROUPSORTED pStructInsert);

Parámetros

pStructInsert
Puntero que apunta a una estructura LVINSERTGROUPSORTED que contiene el grupo que se va a insertar.

Valor devuelto

No se usa el valor devuelto.

Comentarios

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

CListCtrl::InsertItem

Inserta un elemento en el control de vista de lista.

int InsertItem(const LVITEM* pItem);

int InsertItem(
    int nItem,
    LPCTSTR lpszItem);

int InsertItem(
    int nItem,
    LPCTSTR lpszItem,
    int nImage);

int InsertItem(
    UINT nMask,
    int nItem,
    LPCTSTR lpszItem,
    UINT nState,
    UINT nStateMask,
    int nImage,
    LPARAM lParam);

Parámetros

pItem
Puntero que apunta a una estructura LVITEM que especifica los atributos del elemento, como se describe en Windows SDK.

nItem
Índice del elemento que se va a insertar.

lpszItem
Dirección de una cadena que contiene la etiqueta del elemento o LPSTR_TEXTCALLBACK si el elemento es de devolución de llamada. Para obtener información sobre los elementos de devolución de llamada, consulte CListCtrl::GetCallbackMask.

nImage
Índice de la imagen del elemento o I_IMAGECALLBACK si el elemento es de devolución de llamada. Para obtener información sobre los elementos de devolución de llamada, consulte CListCtrl::GetCallbackMask.

nMask
El parámetro nMask especifica qué atributos de elemento pasados como parámetros son válidos. Puede ser uno o varios de los valores de máscara descritos en Estructura LVITEM en Windows SDK. Los valores válidos se pueden combinar con el operador OR bit a bit.

nState
Indica el estado, la imagen de estado y la imagen de superposición del elemento. Para más información, consulte los temas Estructura LVITEM y Estados de elementos de vista de lista en Windows SDK para obtener una lista de marcas válidas.

nStateMask
Indica qué bits del miembro de estado se recuperarán o modificarán. Para más información, consulte Estructura LVITEM en Windows SDK.

lParam
Valor específico de la aplicación de 32 bits (64 bits si compila para x64) asociado al elemento. Si se especifica este parámetro, debe establecer el elemento LVIF_PARAM del atributo nMask.

Valor devuelto

Índice del nuevo elemento si se realiza correctamente o -1 en caso contrario.

Comentarios

Llamar a este método puede hacer que el mensaje LVM_INSERTITEM se envíe a la ventana de control. Es posible que el controlador de mensajes asociado del control no pueda establecer el texto del elemento en condiciones determinadas (como el uso de estilos de ventana como LVS_OWNERDRAW). Para más información sobre estas condiciones, consulte LVM_INSERTITEM en Windows SDK.

Ejemplo

CString strText;
int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

// Insert 10 items in the list view control.
for (int i = 0; i < 10; i++)
{
    strText.Format(TEXT("item %d"), i);

    // Insert the item, select every other item.
    m_myListCtrl.InsertItem(LVIF_TEXT | LVIF_STATE, i, strText,
        (i % 2) == 0 ? LVIS_SELECTED : 0, LVIS_SELECTED, 0, 0);

    // Initialize the text of the subitems.
    for (int j = 1; j < nColumnCount; j++)
    {
        strText.Format(TEXT("sub-item %d %d"), i, j);
        m_myListCtrl.SetItemText(i, j, strText);
    }
}

CListCtrl::InsertMarkHitTest

Recupera el punto de inserción más cercano a un punto especificado.

int InsertMarkHitTest(
    LPPOINT pPoint,
    LPLVINSERTMARK plvim) const;

Parámetros

pPoint
Puntero que apunta a una estructura POINT que contiene las coordenadas de la prueba de posicionamiento, en relación con el área cliente del control de lista.

plvim
Puntero que apunta a una estructura LVINSERTMARK que especifica el punto de inserción más cercano a las coordenadas definidas por el parámetro point.

Valor devuelto

Punto de inserción más cercano al punto especificado.

Comentarios

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

CListCtrl::IsGroupViewEnabled

Determina si la vista de grupo está habilitada para un control de vista de lista.

BOOL IsGroupViewEnabled() const;

Valor devuelto

Devuelve TRUE si la vista de grupo está habilitada o FALSE en caso contrario.

Comentarios

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

CListCtrl::IsItemVisible

Indica si un elemento especificado en el control de vista de lista actual está visible.

BOOL IsItemVisible(int index) const;

Parámetros

index
[entrada] Índice de base cero de un elemento en el control de vista de lista actual.

Valor devuelto

TRUE si el elemento especificado es visible; de lo contrario, FALSE.

Comentarios

Al usar este método, se envía el mensaje LVM_ISITEMVISIBLE, que se describe en Windows SDK.

CListCtrl::MapIDToIndex

Asigna el identificador único de un elemento del control de vista de lista actual a un índice.

UINT MapIDToIndex(UINT id) const;

Parámetros

id
[entrada] Identificador único de un elemento.

Valor devuelto

Índice actual del identificador especificado.

Comentarios

Un control de vista de lista hace un seguimiento interno de los elementos por índice. Esto puede presentar problemas porque los índices pueden cambiar durante la duración del control. El control de vista de lista puede etiquetar un elemento con un identificador cuando se crea el elemento y se puede usar este identificador para garantizar la unicidad durante la vigencia del control de vista de lista.

En un entorno multiproceso, el índice solo se garantiza en el subproceso que hospeda el control de vista de lista, no en subprocesos en segundo plano.

Al usar este método, se envía el mensaje LVM_MAPIDTOINDEX, que se describe en Windows SDK.

CListCtrl::MapIndexToID

Asigna el índice de un elemento del control de vista de lista actual a un identificador único.

UINT MapIndexToID(UINT index) const;

Parámetros

index
[entrada] Índice de base cero de un elemento.

Valor devuelto

Identificador único del elemento especificado.

Comentarios

Un control de vista de lista hace un seguimiento interno de los elementos por índice. Esto puede presentar problemas porque los índices pueden cambiar durante la duración del control. El control de vista de lista puede etiquetar un elemento con un identificador cuando se crea el elemento. Puede usar este identificador para acceder a un elemento específico durante la vigencia del control de vista de lista.

En un entorno multiproceso, el índice solo se garantiza en el subproceso que hospeda el control de vista de lista, no en subprocesos en segundo plano.

Al usar este método, se envía el mensaje LVM_MAPINDEXTOID, que se describe en Windows SDK.

Ejemplo

En el primer ejemplo de código se define una variable, m_listCtrl, que se usa para acceder al control de vista de lista actual. Esta variable se utiliza en el siguiente ejemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

En el siguiente código de ejemplo se muestra el método MapIndexToID. En una sección anterior de este ejemplo de código, creamos un control de vista de lista que muestra dos columnas tituladas "ClientID" y "Grade" en una vista de informe. En el ejemplo siguiente se asigna el índice de cada elemento de vista de lista a un número de identificación y, luego, se recupera el índice de cada número de identificación. Por último, el ejemplo informa de si se recuperaron los índices originales.

// MapIndexToID
int iCount = m_listCtrl.GetItemCount();
UINT nId = 0;
UINT nIndex = 0;
for (int iIndexOriginal = 0; iIndexOriginal < iCount; iIndexOriginal++)
{
    // Map index to ID.
    nId = m_listCtrl.MapIndexToID((UINT)iIndexOriginal);

    // Map ID to index.
    nIndex = m_listCtrl.MapIDToIndex(nId);

    if (nIndex != (UINT)(iIndexOriginal))
    {
        CString str;
        str.Format(_T("Mapped index (%d) is not equal to original index (%d)"),
            nIndex, (UINT)(iIndexOriginal));
        AfxMessageBox(str);
        return;
    }
}
AfxMessageBox(_T("The mapped indexes and original indexes are equal."),
    MB_ICONINFORMATION);

CListCtrl::MoveGroup

Mueve el grupo especificado al índice de base cero especificado del control de vista de lista.

LRESULT MoveGroup(
    int iGroupId,
    int toIndex);

Parámetros

iGroupId
Identificador del grupo que se va a mover.

toIndex
Índice de base cero donde se va a mover el grupo.

Valor devuelto

No se usa el valor devuelto.

Comentarios

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

CListCtrl::MoveItemToGroup

Mueve el elemento especificado al grupo especificado.

void MoveItemToGroup(
    int idItemFrom,
    int idGroupTo);

Parámetros

idItemFrom
[entrada] Índice del elemento que se va a mover.

idGroupTo
[entrada] Identificador del grupo al que se moverá el elemento.

Comentarios

Nota:

Este método no está implementado actualmente.

Este método emula la funcionalidad del mensaje LVM_MOVEITEMTOGROUP, tal y como se describe en Windows SDK.

CListCtrl::RedrawItems

Fuerza un control de vista de lista para volver a dibujar un intervalo de elementos.

BOOL RedrawItems(
    int nFirst,
    int nLast);

Parámetros

nFirst
Índice del primer elemento que se va a volver a pintar.

nLast
Índice del último elemento que se va a volver a pintar.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

Los elementos especificados no se vuelven a pintar hasta que la ventana de vista de lista recibe un mensaje de WM_PAINT. Para volver a pintar inmediatamente, llame a la función UpdateWindow de Windows después de usar esta función.

CListCtrl::RemoveAllGroups

Quita todos los grupos de un control de vista de lista.

void RemoveAllGroups();

Comentarios

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

CListCtrl::RemoveGroup

Quita el grupo especificado del control de vista de lista.

LRESULT RemoveGroup(int iGroupId);

Parámetros

iGroupId
Identificador del grupo que se va a quitar.

Valor devuelto

Devuelve el índice del grupo si se ejecuta correctamente o -1 de lo contrario.

Comentarios

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

CListCtrl::Scroll

Desplaza el contenido de un control de vista de lista.

BOOL Scroll(CSize size);

Parámetros

size
Objeto CSize que especifica la cantidad de desplazamiento horizontal y vertical, en píxeles. El miembro y de size se divide por el alto, en píxeles, de la línea del control de vista de lista y el control se desplaza por el número resultante de líneas.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

CListCtrl::SetBkColor

Establece el color de fondo del control de vista de lista.

BOOL SetBkColor(COLORREF cr);

Parámetros

cr
Color de fondo que se va a establecer o el valor CLR_NONE de ningún color de fondo. Los controles de vista de lista con colores de fondo se vuelven a pintar significativamente más rápido que los que no tienen colores de fondo. Para obtener información, consulte COLORREF en Windows SDK.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

// Use the 3D button face color for the background.
COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
m_myListCtrl.SetBkColor(crBkColor);
ASSERT(m_myListCtrl.GetBkColor() == crBkColor);

CListCtrl::SetBkImage

Establece la imagen de fondo de un control de vista de lista.

BOOL SetBkImage(LVBKIMAGE* plvbkImage);

BOOL SetBkImage(
    HBITMAP hBitmap,
    BOOL fTile = TRUE,
    int xOffsetPercent = 0,
    int yOffsetPercent = 0);

BOOL SetBkImage(
    LPTSTR pszUrl,
    BOOL fTile = TRUE,
    int xOffsetPercent = 0,
    int yOffsetPercent = 0);

Parámetros

plvbkImage
Dirección de una estructura LVBKIMAGE que contiene la nueva información de imagen de fondo.

hBitmap
Manipulador de un mapa de bits.

pszUrl
Cadena terminada en NULL que contiene la dirección URL de la imagen de fondo.

fTile
Distinto de cero si la imagen se va a crear en mosaico en el fondo del control de vista de lista; de lo contrario, 0.

xOffsetPercent
Desplazamiento en píxeles del borde izquierdo de la imagen, desde el origen del control de vista de lista.

yOffsetPercent
Desplazamiento en píxeles del borde superior de la imagen, desde el origen del control de vista de lista.

Valor devuelto

Devuelve un valor distinto de cero si se ejecuta correctamente o cero en caso contrario.

Comentarios

Nota:

Dado que CListCtrl::SetBkImage usa la funcionalidad OLE y COM, las bibliotecas OLE deben inicializarse antes de usar SetBkImage. Es mejor inicializar las bibliotecas COM cuando la aplicación se inicializa y anula la inicialización de las bibliotecas cuando finaliza la aplicación. Esto se hace automáticamente en las aplicaciones MFC que usan la tecnología ActiveX, la automatización OLE, la vinculación e inserción OLE o las operaciones ODBC y DAO.

Ejemplo

Vea el ejemplo de CListCtrl::GetBkImage.

CListCtrl::SetCallbackMask

Establece la máscara de devolución de llamada de un control de vista de lista.

BOOL SetCallbackMask(UINT nMask);

Parámetros

nMask
Nuevo valor de la máscara de devolución de llamada.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

// Set the callback mask so that only the selected and focused states
// are stored for each item.
m_myListCtrl.SetCallbackMask(LVIS_SELECTED|LVIS_FOCUSED);
ASSERT(m_myListCtrl.GetCallbackMask() ==
    (LVIS_SELECTED|LVIS_FOCUSED));

CListCtrl::SetCheck

Determina si la imagen de estado de un elemento de control de lista es visible.

BOOL SetCheck(
    int nItem,
    BOOL fCheck = TRUE);

Parámetros

nItem
Índice de base cero de un elemento de control de lista.

fCheck
Especifica si la imagen de estado del elemento debe ser visible o no. De forma predeterminada, fCheck es TRUE y la imagen de estado está visible. Si fCheck es FALSE, no está visible.

Valor devuelto

Es distinto de cero si el elemento está activado; de lo contrario, es 0.

Ejemplo

int nCount = m_myListCtrl.GetItemCount();
BOOL fCheck = FALSE;

// Set the check state of every other item to TRUE and
// all others to FALSE.
for (int i = 0; i < nCount; i++)
{
    m_myListCtrl.SetCheck(i, fCheck);
    ASSERT((m_myListCtrl.GetCheck(i) && fCheck) ||
        (!m_myListCtrl.GetCheck(i) && !fCheck));
    fCheck = !fCheck;
}

CListCtrl::SetColumn

Establece los atributos de una columna de vista de lista.

BOOL SetColumn(
    int nCol,
    const LVCOLUMN* pColumn);

Parámetros

nCol
Índice de la columna cuyos atributos se van a establecer.

pColumn
Dirección de una estructura LVCOLUMN que contiene los nuevos atributos de columna, como se describe en Windows SDK. El miembro de la estructura mask especifica qué atributos de columna se van a establecer. Si el miembro mask especifica el valor LVCF_TEXT, el miembro pszText de la estructura es la dirección de una cadena terminada en NULL y se omite el miembro cchTextMax de la estructura.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

Vea el ejemplo de CListCtrl::GetColumn.

CListCtrl::SetColumnOrderArray

Establece el orden de columna (de izquierda a derecha) de un control de vista de lista.

BOOL SetColumnOrderArray(
    int iCount,
    LPINT piArray);

Parámetros

piArray
Puntero que apunta a un búfer que contiene los valores de índice de las columnas del control de vista de lista (de izquierda a derecha). El búfer debe ser lo suficientemente grande como para contener la cantidad total de columnas del control de vista de lista.

iCount
Número de columnas del control de vista de lista.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetColumnOrderArray, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CListCtrl::GetColumnOrderArray.

CListCtrl::SetColumnWidth

Cambia el ancho de una columna en la vista de informe o vista de lista.

BOOL SetColumnWidth(
    int nCol,
    int cx);

Parámetros

nCol
Índice de la columna para la que se va a establecer el ancho. En la vista de lista, este parámetro debe ser 0.

cx
Nuevo ancho de la columna. Puede ser LVSCW_AUTOSIZE o LVSCW_AUTOSIZE_USEHEADER, como se describe en LVM_SETCOLUMNWIDTH en Windows SDK.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

CListCtrl::SetExtendedStyle

Establece los estilos extendidos actuales de un control de vista de lista.

DWORD SetExtendedStyle(DWORD dwNewStyle);

Parámetros

dwNewStyle
Combinación de estilos extendidos que usará el control de vista de lista. Para obtener una lista descriptiva de estos estilos, consulte el tema Estilos extendidos de vista de lista en Windows SDK.

Valor devuelto

Combinación de los estilos extendidos anteriores usados por el control de vista de lista.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetExtendedListViewStyle, tal y como se describe en Windows SDK.

Ejemplo

// Allow the header controls item to be movable by the user.
m_myListCtrl.SetExtendedStyle
    (m_myListCtrl.GetExtendedStyle()|LVS_EX_HEADERDRAGDROP);

CListCtrl::SetGroupInfo

Establece la información que describe el grupo especificado del control de vista de lista actual.

int SetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp);

Parámetros

iGroupId
Identificador del grupo cuya información está establecida.

pgrp
Puntero que apunta a una estructura LVGROUP que contiene la información que se va a establecer. El autor de la llamada es responsable de asignar esta estructura y establecer sus miembros.

Valor devuelto

Identificador del grupo si el método es correcto; de lo contrario, -1.

Comentarios

Al usar este método, se envía el mensaje LVM_SETGROUPINFO, que se describe en Windows SDK.

CListCtrl::SetGroupMetrics

Establece las métricas de grupo de un control de vista de lista.

void SetGroupMetrics(PLVGROUPMETRICS pGroupMetrics);

Parámetros

pGroupMetrics
Puntero que apunta a una estructura LVGROUPMETRICS que contiene la información de las métricas de grupo que se va a establecer.

Comentarios

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

CListCtrl::SetHotCursor

Establece el cursor utilizado cuando el seguimiento activo está habilitado para un control de vista de lista.

HCURSOR SetHotCursor(HCURSOR hc);

Parámetros

hc
Manipulador de un recurso de cursor que se usa para representar el cursor activo.

Valor devuelto

Manipulador del recurso de cursor activo anterior que usa el control de vista de lista.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetHotCursor, tal y como se describe en Windows SDK.

El cursor activo, que solo es visible cuando se habilita la selección mediante movimiento del mouse, aparece a medida que el cursor pasa sobre cualquier elemento de vista de lista. La selección mediante movimiento del mouse se habilitada al establecer el estilo extendido de LVS_EX_TRACKSELECT.

Ejemplo

Vea el ejemplo de CListCtrl::GetHotCursor.

CListCtrl::SetHotItem

Establece el elemento activo actual de un control de vista de lista.

int SetHotItem(int iIndex);

Parámetros

iIndex
Índice de base cero del elemento que se va a establecer como elemento activo.

Valor devuelto

Índice de base cero del elemento de acceso rápido anterior.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetHotItem, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CListCtrl::GetHotItem.

CListCtrl::SetHoverTime

Establece el tiempo actual del movimiento del mouse de un control de vista de lista.

DWORD SetHoverTime(DWORD dwHoverTime = (DWORD)-1);

Parámetros

dwHoverTime
El nuevo retraso, en milisegundos, que el cursor del mouse debe mantener el puntero sobre un elemento antes de seleccionarlo. Si se pasa el valor predeterminado, la hora se establece en el tiempo de movimiento del mouse predeterminado.

Valor devuelto

Tiempo de movimiento del mouse anterior, en milisegundos.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetHoverTime, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CListCtrl::GetHoverTime.

CListCtrl::SetIconSpacing

Establece el espaciado entre iconos de un control de vista de lista.

CSize SetIconSpacing(
    int cx,
    int cy);

CSize SetIconSpacing(CSize size);

Parámetros

cx
Distancia (en píxeles) entre iconos en el eje X.

cy
Distancia (en píxeles) entre iconos en el eje Y.

size
Objeto CSize que especifica la distancia (en píxeles) entre los iconos de los ejes X e Y.

Valor devuelto

Objeto CSize que contiene los valores anteriores para el espaciado de iconos.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetIconSpacing, tal y como se describe en Windows SDK.

Ejemplo

// Leave lots of space between icons.
m_myListCtrl.SetIconSpacing(CSize(100, 100));

CListCtrl::SetImageList

Asigna una lista de imágenes a un control de vista de lista.

CImageList* SetImageList(
    CImageList* pImageList,
    int nImageListType);

Parámetros

pImageList
Puntero que apunta a la lista de imágenes que se va a asignar.

nImageListType
Tipo de lista de imágenes. Puede ser uno de estos valores:

• LVSIL_NORMAL Lista de imágenes con iconos grandes.
• LVSIL_SMALL Lista de imágenes con iconos pequeños.
• LVSIL_STATE Lista de imágenes con imágenes de estado.

Valor devuelto

Puntero que apunta a la lista de imágenes anterior.

Ejemplo

Vea el ejemplo de CListCtrl::GetImageList.

CListCtrl::SetInfoTip

Establece el texto de la información sobre herramientas.

BOOL SetInfoTip(PLVSETINFOTIP plvInfoTip);

Parámetros

plvInfoTip
Puntero que apunta a una estructura LVFSETINFOTIP que contiene la información que se va a establecer.

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

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

CListCtrl::SetInsertMark

Establece el punto de inserción en la posición definida.

BOOL SetInsertMark(LPLVINSERTMARK plvim);

Parámetros

plvim
Puntero que apunta a una estructura LVINSERTMARK que especifica dónde establecer el punto de inserción.

Valor devuelto

Devuelve TRUE si se realizó correctamente; de lo contrario, FALSE. FALSE se devuelve si el tamaño del miembro cbSize de la estructura LVINSERTMARK no es igual al tamaño real de la estructura o cuando un punto de inserción no se aplica en la vista actual.

Comentarios

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

CListCtrl::SetInsertMarkColor

Establece el color del punto de inserción.

COLORREF SetInsertMarkColor(COLORREF color);

Parámetros

color
Estructura COLORREF que especifica el color en que se va a establecer el punto de inserción.

Valor devuelto

Devuelve una estructura COLORREF que contiene el color anterior.

Comentarios

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

CListCtrl::SetItem

Establece algunos o todos los atributos de un elemento de vista de lista.

BOOL SetItem(const LVITEM* pItem);

BOOL SetItem(
    int nItem,
    int nSubItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam);

BOOL SetItem(
    int nItem,
    int nSubItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam,
    int nIndent);

Parámetros

pItem
Dirección de una estructura LVITEM que contiene los nuevos atributos de elemento, como se describe en Windows SDK. Los miembros iItem y iSubItem de la estructura identifican el elemento o subelemento, y el miembro mask de la estructura especifica los atributos que se van a establecer. Para más información sobre el miembro mask, consulte los comentarios.

nItem
Índice del elemento cuyos atributos se van a establecer.

nSubItem
Índice del subelemento cuyos atributos se van a establecer.

nMask
Especifica los atributos que se van a establecer (vea los comentarios).

lpszItem
Dirección de una cadena terminada en NULL que especifica la etiqueta del elemento.

nImage
Índice de la imagen del elemento en la lista de imágenes.

nState
Especifica los valores de los estados que se van a cambiar (vea los comentarios).

nStateMask
Especifica qué estados se van a cambiar (vea los comentarios).

lParam
Valor específico de la aplicación de 32 bits (64 bits si compila para x64) para asociarlo al elemento.

nIndent
Ancho, en píxeles, de la sangría. Si nIndent es menor que el ancho mínimo definido por el sistema, el nuevo ancho se establece en el mínimo definido por el sistema.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

Los miembros iItem y iSubItem de la estructura LVITEM y los parámetros nItem y nSubItem identifican el elemento y el subelemento cuyos atributos se van a establecer.

El miembro mask de la estructura LVITEM y el parámetro nMask especifican qué atributos de elemento se van a establecer:

• LVIF_TEXT El miembro pszText o el parámetro lpszItem es la dirección de una cadena terminada en NULL; el miembro cchTextMax se omite.
• LVIF_STATEEl miembro stateMask o el parámetro nStateMask especifica qué estados de elemento se van a cambiar y el miembro state o parámetro nState contiene los valores de esos estados.

Ejemplo

Vea el ejemplo de CListCtrl::HitTest.

CListCtrl::SetItemCount

Prepara un control de vista de lista para agregar una gran cantidad de elementos.

void SetItemCount(int nItems);

Parámetros

nItems
Número de elementos que el control contendrá en última instancia.

Comentarios

Para establecer el recuento de elementos de un control de vista de lista virtual, consulte CListCtrl::SetItemCountEx.

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetItemCount, tal y como se describe en Windows SDK.

Ejemplo

CString str;

// Add 1024 items to the list view control.
m_myListCtrl.SetItemCount(1024);

for (int i = 0; i < 1024; i++)
{
    str.Format(TEXT("item %d"), i);
    m_myListCtrl.InsertItem(i, str);
}

CListCtrl::SetItemCountEx

Establece el recuento de elementos de un control de vista de lista virtual.

BOOL SetItemCountEx(
    int iCount,
    DWORD dwFlags = LVSICF_NOINVALIDATEALL);

Parámetros

iCount
Número de elementos que el control contendrá en última instancia.

dwFlags
Especifica el comportamiento del control de vista de lista después de restablecer el recuento de elementos. Este valor puede ser una combinación de lo siguiente:

• LVSICF_NOINVALIDATEALL El control de vista de lista no se vuelve a pintar a menos que los elementos afectados se encuentren actualmente en vista. Este es el valor predeterminado.
• LVSICF_NOSCROLL El control de vista de lista no cambiará la posición de desplazamiento cuando cambie el recuento de elementos.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

En esta función miembro se implementa el comportamiento de la macro de Win32, ListView_SetItemCountEx, tal y como se describe en Windows SDK y solo se debe llamar para las vistas de lista virtuales.

Ejemplo

CString str;

// Add 1024 items to the list view control.

// Force my virtual list view control to allocate
// enough memory for my 1024 items.
m_myVirtualListCtrl.SetItemCountEx(1024, LVSICF_NOSCROLL|
    LVSICF_NOINVALIDATEALL);

for (int i = 0; i < 1024; i++)
{
    str.Format(TEXT("item %d"), i);
    m_myVirtualListCtrl.InsertItem(i, str);
}

CListCtrl::SetItemData

Establece el valor específico de la aplicación de 32 bits (64 bits si compila para x64) el valor específico de la aplicación asociado al elemento especificado por nItem.

BOOL SetItemData(int nItem, DWORD_PTR dwData);

Parámetros

nItem
Índice del elemento de lista cuyos datos se van a establecer.

dwData
Valor de 32 bits (64 bits si compila para x64) para asociarlo al elemento.

Valor devuelto

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

Comentarios

Este valor es el miembro lParam de la estructura LVITEM, como se describe en Windows SDK.

Ejemplo

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

CListCtrl::SetItemIndexState

Establece el estado de un elemento del control de vista de lista actual.

BOOL SetItemIndexState(
    PLVITEMINDEX pItemIndex,
    DWORD dwState,
    DWORD dwMask) const;

Parámetros

pItemIndex
[entrada] Puntero a una estructura LVITEMINDEX que describe un elemento. El autor de la llamada es responsable de asignar esta estructura y establecer sus miembros.

dwState
[entrada] Estado que se va a establecer el elemento, que es una combinación bit a bit de estados de elementos de vista de lista. Especifique cero para restablecer, o uno que se va a establecer, un estado.

dwMask
[entrada] Máscara de los bits válidos del estado especificado por el parámetro dwState. Especifique una combinación bit a bit (OR) de los estados de elementos de vista de lista.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Para más información sobre el parámetro dwState, consulte Estados de elementos de vista de lista.

Para más información sobre el parámetro dwMask, consulte el miembro stateMask de la estructura LVITEM.

Al usar este método, se envía el mensaje LVM_SETITEMINDEXSTATE, que se describe en Windows SDK.

CListCtrl::SetItemPosition

Mueve un elemento a una posición especificada en un control de vista de lista.

BOOL SetItemPosition(
    int nItem,
    POINT pt);

Parámetros

nItem
Índice del elemento cuya posición se va a establecer.

pt
Estructura POINT que especifica la nueva posición, en coordenadas de vista, de la esquina superior izquierda del elemento.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

El control debe estar en el icono o en la vista de icono pequeño.

Si el control de vista de lista tiene el estilo de LVS_AUTOARRANGE, la vista de lista se organiza después de establecer la posición del elemento.

Ejemplo

Vea el ejemplo de CListCtrl::GetItemPosition.

CListCtrl::SetItemState

Cambia el estado de un elemento en un control de vista de lista.

BOOL SetItemState(
    int nItem,
    LVITEM* pItem);

BOOL SetItemState(
    int nItem,
    UINT nState,
    UINT nMask);

Parámetros

nItem
Índice del elemento cuyo estado se va a establecer. Pase -1 para aplicar el cambio de estado a todos los elementos.

pItem
Dirección de una estructura LVITEM, como se describe en Windows SDK. El miembro stateMask de la estructura especifica los bits de estado que se van a cambiar y el miembro state de la estructura contiene los nuevos valores de esos bits. Se omiten los demás miembros.

nState
Nuevos valores para los bits de estado. Para obtener una lista de los valores posibles, consulte CListCtrl::GetNextItem y el miembro de estado LVITEM.

nMask
Máscara que especifica los bits de estado que se van a cambiar. Este valor corresponde al miembro stateMask de la estructura LVITEM.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

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 para especificar una imagen de superposición o imagen de estado.

Ejemplo

Vea el ejemplo de CListCtrl::GetTopIndex.

CListCtrl::SetItemText

Cambia el texto de un elemento de vista de lista o subelemento.

BOOL SetItemText(
    int nItem,
    int nSubItem,
    LPCTSTR lpszText);

Parámetros

nItem
Índice del elemento cuyo texto se va a establecer.

nSubItem
Índice del subelemento o cero para establecer la etiqueta del elemento.

lpszText
Puntero que apunta a una cadena que contiene el texto del nuevo elemento.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

Este método no está pensado para su uso con controles que contienen el estilo de ventana LVS_OWNERDATA (de hecho, esto provocará una aserción en compilaciones de depuración). Para más información sobre este estilo de control de lista, consulte Información general sobre los controles de vista de lista.

Ejemplo

Vea el ejemplo de CListCtrl::InsertItem.

CListCtrl::SetOutlineColor

Establece el color del borde de un control de vista de lista si se establece el estilo de ventana extendida LVS_EX_BORDERSELECT.

COLORREF SetOutlineColor(COLORREF color);

Parámetros

color
La nueva estructura COLORREF que contiene el color del contorno.

Valor devuelto

Estructura anterior COLORREF que contiene el color del contorno

Comentarios

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

CListCtrl::SetSelectedColumn

Establece la columna seleccionada del control de vista de lista.

LRESULT SetSelectedColumn(int iCol);

Parámetros

iCol
Índice de la columna que se va a seleccionar.

Valor devuelto

No se usa el valor devuelto.

Comentarios

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

CListCtrl::SetSelectionMark

Establece la marca de selección de un control de vista de lista.

int SetSelectionMark(int iIndex);

Parámetros

iIndex
Índice de base cero del primer elemento de una selección múltiple.

Valor devuelto

Marca de selección anterior o -1 si no había ninguna marca de selección.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetSelectionMark, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CListCtrl::GetSelectionMark.

CListCtrl::SetTextBkColor

Establece el color de fondo del texto en un control de vista de lista.

BOOL SetTextBkColor(COLORREF cr);

Parámetros

cr
COLORREF que especifica el nuevo color de fondo del texto. Para obtener información, consulte COLORREF en Windows SDK.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

// Use the 3D button face color for the background.
COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
m_myListCtrl.SetTextBkColor(crBkColor);
ASSERT(m_myListCtrl.GetTextBkColor() == crBkColor);

CListCtrl::SetTextColor

Establece el color de texto de un control de vista de lista.

BOOL SetTextColor(COLORREF cr);

Parámetros

cr
COLORREF que especifica el nuevo color del texto. Para obtener información, consulte COLORREF en Windows SDK.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

// Use the window text color for
// the item text of the list view control.
COLORREF crTextColor = ::GetSysColor(COLOR_WINDOWTEXT);
m_myListCtrl.SetTextColor(crTextColor);
ASSERT(m_myListCtrl.GetTextColor() == crTextColor);

CListCtrl::SetTileInfo

Establece la información de un mosaico del control de vista de lista.

BOOL SetTileInfo(PLVTILEINFO pTileInfo);

Parámetros

pTileInfo
Puntero que apunta a una estructura LVTILEINFO que contiene la información que se va a establecer.

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

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

CListCtrl::SetTileViewInfo

Establece la información que usa un control de vista de lista en la vista de mosaico.

BOOL SetTileViewInfo(PLVTILEVIEWINFO ptvi);

Parámetros

ptvi
Puntero que apunta a una estructura LVTILEVIEWINFO que contiene la información que se va a establecer.

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

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

CListCtrl::SetToolTips

Establece el control de la información sobre herramientas que usará el control de vista de lista para mostrar información sobre herramientas.

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

Parámetros

pWndTip
Puntero que apunta a un objeto CToolTipCtrl que usará el control de lista.

Valor devuelto

Puntero que apunta a un objeto CToolTipCtrl que contiene la información sobre herramientas usada anteriormente por el control o NULL si no se usó anteriormente ninguna información sobre herramientas.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje LVM_SETTOOLTIPS de Win32, tal y como se describe en Windows SDK.

Para no usar información sobre herramientas, indique el estilo LVS_NOTOOLTIPS al crear el objeto CListCtrl.

CListCtrl::SetView

Establece la vista del control de vista de lista.

DWORD SetView(int iView);

Parámetros

iView
Vista que se va a seleccionar.

Valor devuelto

Devuelve 1 si se realiza correctamente o -1 en caso contrario. Por ejemplo, se devuelve -1 si la vista no es válida.

Comentarios

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

CListCtrl::SetWorkAreas

Establece el área donde se pueden mostrar los iconos en un control de vista de lista.

void SetWorkAreas(
    int nWorkAreas,
    LPRECT lpRect);

Parámetros

nWorkAreas
Número de estructuras RECT (u objetos CRect) de la matriz a la que apunta lpRect.

lpRect
Dirección de una matriz de estructuras RECT (u objetos CRect) que especifican las nuevas áreas de trabajo del control de vista de lista. Estas áreas deben especificarse en coordenadas cliente. Si este parámetro es NULL, el área de trabajo se establecerá en el área cliente del control.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SetWorkAreas, tal y como se describe en Windows SDK.

Ejemplo

// Remove all working areas.
m_myListCtrl.SetWorkAreas(0, NULL);

CListCtrl::SortGroups

Usa una función de comparación definida por la aplicación para ordenar grupos por identificador en un control de vista de lista.

BOOL SortGroups(
    PFNLVGROUPCOMPARE _pfnGroupCompare,
    LPVOID _plv);

Parámetros

_pfnGroupCompare
Puntero que apunta a la función de comparación de grupos.

_plv
Puntero void.

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

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

CListCtrl::SortItems

Ordena los elementos de vista de lista mediante una función de comparación definida por la aplicación.

BOOL SortItems(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

Parámetros

pfnCompare
[entrada] Dirección de la función de comparación definida por la aplicación.

La operación de ordenación llama a la función de comparación cada vez que es necesario determinar el orden relativo de dos elementos de lista. La función de comparación debe ser un miembro estático de una clase o una función independiente que no sea miembro de ninguna clase.

dwData
[entrada] Valor definido por la aplicación que se pasa a la función de comparación.

Valor devuelto

TRUE si el método se ha realizado correctamente; de lo contrario, FALSE.

Comentarios

Este método cambia el índice de cada elemento para reflejar la nueva secuencia.

La función de comparación, pfnCompare, tiene la siguiente forma:

int CALLBACK CompareFunc(LPARAM lParam1,
    LPARAM lParam2,
    LPARAM lParamSort);

La función de comparación debe devolver un valor negativo si el primer elemento debe preceder al segundo, un valor positivo si el primer elemento debe seguir el segundo o cero si los dos elementos son iguales.

El parámetro lParam1 es el valor de 32 bits (64 bits si va a compilar para x64) asociado al primer elemento que se compara y el parámetro lParam2 es el valor asociado al segundo elemento. Estos son los valores que se especificaron en el miembro lParam de la estructura LVITEM de los elementos cuando se insertaron en la lista. El parámetro lParamSort es el mismo que el valor dwData.

Al usar este método, se envía el mensaje LVM_SORTITEMS, que se describe en Windows SDK.

Ejemplo

A continuación, se muestra una función de comparación simple que da como resultado que los elementos se ordenen por sus valores lParam.

// Sort items by associated lParam
int CALLBACK CListCtrlDlg::MyCompareProc(LPARAM lParam1, LPARAM lParam2,
    LPARAM lParamSort)
{
    UNREFERENCED_PARAMETER(lParamSort);
    return (int)(lParam1 - lParam2);
}

// Sort the items by passing in the comparison function.
void CListCtrlDlg::Sort()
{
    m_myListCtrl.SortItems(&CListCtrlDlg::MyCompareProc, 0);
}

CListCtrl::SortItemsEx

Ordena los elementos del control de vista de lista actual mediante una función de comparación definida por la aplicación.

BOOL SortItemsEx(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

Parámetros

pfnCompare
[entrada] Dirección de la función de comparación definida por la aplicación. La operación de ordenación llama a la función de comparación cada vez que es necesario determinar el orden relativo de dos elementos de lista. La función de comparación debe ser un miembro estático de una clase o una función independiente que no sea miembro de ninguna clase.

dwData
[entrada] Valor definido por la aplicación que se pasa a la función de comparación.

Valor devuelto

TRUE si este método es correcto; en caso contrario, FALSE.

Comentarios

Este método cambia el índice de cada elemento para reflejar la nueva secuencia.

La función de comparación, pfnCompare, tiene la siguiente forma:

int CALLBACK CompareFunc(LPARAM lParam1,
    LPARAM lParam2,
    LPARAM lParamSort);

Este mensaje es similar a LVM_SORTITEMS, excepto el tipo de información que se pasa a la función de comparación. En LVM_SORTITEMS, lParam1 y lParam2 son los valores de los elementos que se van a comparar. En LVM_SORTITEMSEX, lParam1 es el índice actual del primer elemento que se va a comparar y lParam2 es el índice actual del segundo elemento. Puede enviar un mensaje LVM_GETITEMTEXT para recuperar más información sobre un elemento.

La función de comparación debe devolver un valor negativo si el primer elemento debe preceder al segundo, un valor positivo si el primer elemento debe seguir el segundo o cero si los dos elementos son iguales.

Nota:

Durante el proceso de ordenación, el contenido de la vista de lista es inestable. Si la función de devolución de llamada envía mensajes al control de vista de lista distintos de LVM_GETITEM, los resultados son impredecibles.

Al usar este método, se envía el mensaje LVM_SORTITEMSEX, que se describe en Windows SDK.

Ejemplo

En el primer ejemplo de código se define una variable, m_listCtrl, que se usa para acceder al control de vista de lista actual. Esta variable se utiliza en el siguiente ejemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

En el siguiente código de ejemplo se muestra el método SortItemEx. En una sección anterior de este ejemplo de código, creamos un control de vista de lista que muestra dos columnas tituladas "ClientID" y "Grade" en una vista de informe. En el ejemplo de código siguiente, se ordena la tabla mediante los valores de la columna "Grade".

// The ListCompareFunc() method is a global function used by SortItemEx().
int CALLBACK ListCompareFunc(
                             LPARAM lParam1,
                             LPARAM lParam2,
                             LPARAM lParamSort)
{
    CListCtrl* pListCtrl = (CListCtrl*) lParamSort;
    CString    strItem1 = pListCtrl->GetItemText(static_cast<int>(lParam1), 1);
    CString    strItem2 = pListCtrl->GetItemText(static_cast<int>(lParam2), 1)
    int x1 = _tstoi(strItem1.GetBuffer());
    int x2 = _tstoi(strItem2.GetBuffer());
    int result = 0;
    if ((x1 - x2) < 0)
        result = -1;
    else if ((x1 - x2) == 0)
        result = 0;
    else
        result = 1;

    return result;
}

void CCListCtrl_s2Dlg::OnBnClickedButton1()
{
    // SortItemsEx
    m_listCtrl.SortItemsEx( ListCompareFunc, (LPARAM)&m_listCtrl );
}

CListCtrl::SubItemHitTest

Determina qué elemento de vista de lista, si existe, está en una posición determinada.

int SubItemHitTest(LPLVHITTESTINFO pInfo);

Parámetros

pInfo
Un puntero a la estructura LVHITTESTINFO.

Valor devuelto

Índice basado en uno del elemento o subelemento, que se va a probar (si existe), o -1 de lo contrario.

Comentarios

En esta función miembro, se implementa el comportamiento de la macro de Win32, ListView_SubItemHitTest, tal y como se describe en Windows SDK.

Ejemplo

void CListCtrlDlg::OnDblClk(NMHDR* pNMHDR, LRESULT* pResult)
{
    UNREFERENCED_PARAMETER(pResult);
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
    LVHITTESTINFO lvhti;

    // Clear the subitem text the user clicked on.
    lvhti.pt = pia->ptAction;
    m_myListCtrl.SubItemHitTest(&lvhti);

    if (lvhti.flags & LVHT_ONITEMLABEL)
    {
        m_myListCtrl.SetItemText(lvhti.iItem, lvhti.iSubItem, NULL);
    }
}

CListCtrl::Update

Obliga al control de vista de lista a volver a pintar el elemento especificado por nItem.

BOOL Update(int nItem);

Parámetros

nItem
Índice del elemento que se va a actualizar.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

Esta función también organiza el control de vista de lista si tiene el estilo LVS_AUTOARRANGE.

Ejemplo

Vea el ejemplo de CListCtrl::GetSelectedCount.

Consulte también

MFC Sample ROWLIST
CWnd (clase)
Gráfico de jerarquías
CImageList (clase)