Clase CImageList

Proporciona la funcionalidad del control de lista de imágenes común de Windows.

Sintaxis

class CImageList : public CObject

Miembros

Constructores públicos

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

Métodos públicos

Nombre	Descripción
CImageList::Add	Agrega una imagen o imágenes a una lista de imágenes.
CImageList::Attach	Adjunta una lista de imágenes a un objeto CImageList.
CImageList::BeginDrag	Comienza a arrastrar una imagen.
CImageList::Copy	Copia una imagen dentro de un objeto CImageList.
CImageList::Create	Inicializa una lista de imágenes y la adjunta a un objeto CImageList.
CImageList::DeleteImageList	Elimina una lista de imágenes.
CImageList::DeleteTempMap	Llamado por el controlador de tiempo de inactividad de CWinApp para eliminar cualquier objeto temporal CImageList creado por FromHandle.
CImageList::Detach	Desasocia un objeto de lista de imágenes de un objeto CImageList y devuelve un manipulador de una lista de imágenes.
CImageList::DragEnter	Bloquea las actualizaciones durante una operación de arrastre y muestra la imagen de arrastre en una posición especificada.
CImageList::DragLeave	Desbloquea la ventana y oculta la imagen de arrastre para que la ventana se pueda actualizar.
CImageList::DragMove	Mueve la imagen que se arrastra durante una operación de arrastrar y colocar.
CImageList::DragShowNolock	Muestra u oculta la imagen de arrastre durante una operación de arrastre, sin bloquear la ventana.
CImageList::Draw	Dibuja la imagen que se arrastra durante una operación de arrastrar y colocar.
CImageList::DrawEx	Dibuja un elemento de lista de imágenes en el contexto de dispositivo especificado. La función usa el estilo de dibujo especificado y combina la imagen con el color especificado.
CImageList::DrawIndirect	Dibuja una imagen de una lista de imágenes.
CImageList::EndDrag	Finaliza una operación de arrastre.
CImageList::ExtractIcon	Crea un icono basado en una imagen y una máscara en una lista de imágenes.
CImageList::FromHandle	Devuelve un puntero a un objeto CImageList cuando se especifica un manipulador a una lista de imágenes. Si no hay un objeto CImageList asociado al identificador, se crea y asocia un objeto CImageList temporal.
CImageList::FromHandlePermanent	Devuelve un puntero a un objeto CImageList cuando se especifica un manipulador a una lista de imágenes. Si no se ha asociado un objeto CImageList al manipulador, se devuelve NULL.
CImageList::GetBkColor	Recupera el color de fondo actual de una lista de imágenes.
CImageList::GetDragImage	Obtiene la lista de imágenes temporales que se usa para arrastrar.
CImageList::GetImageCount	Recupera el número de imágenes de una lista de imágenes.
CImageList::GetImageInfo	Recupera información sobre una imagen.
CImageList::GetSafeHandle	Recupera m_hImageList.
CImageList::Read	Lee una lista de imágenes de un archivo.
CImageList::Remove	Quita una imagen de una lista de imágenes.
CImageList::Replace	Reemplaza una imagen de una lista de imágenes por una nueva imagen.
CImageList::SetBkColor	Establece el color de fondo de una lista de imágenes.
CImageList::SetDragCursorImage	Crea una nueva imagen de arrastre.
CImageList::SetImageCount	Restablece el recuento de imágenes de una lista de imágenes.
CImageList::SetOverlayImage	Agrega el índice de base cero de una imagen a la lista de imágenes que se van a usar como máscaras de superposición.
CImageList::Write	Escribe una lista de imágenes en un archivo.

Operadores públicos

Nombre	Descripción
CImageList::operator HIMAGELIST	Devuelve el objeto HIMAGELIST adjunto al objeto CImageList.

Miembros de datos públicos

Nombre	Descripción
CImageList::m_hImageList	Manipulador que contiene la lista de imágenes adjunta a este objeto.

Comentarios

Una "lista de imágenes" es una colección de imágenes del mismo tamaño, a las que puede hacer referencia mediante su índice de base cero. Las listas de imágenes se usan para administrar eficazmente grandes conjuntos de iconos o mapas de bits. Todas las imágenes de una lista de imágenes están contenidas en un único mapa de bits ancho en formato de dispositivo de pantalla. Una lista de imágenes también puede incluir un mapa de bits monocromo que contiene máscaras usadas para dibujar imágenes de forma transparente (estilo de icono). La interfaz de programación de aplicaciones (API) de Microsoft Win32 proporciona funciones de lista de imágenes que permiten dibujar imágenes, crear y destruir listas de imágenes, agregar y quitar imágenes, reemplazar imágenes, combinar imágenes y arrastrar imágenes.

Este control (y, por tanto, la clase CImageList) solo está disponible para los programas que se ejecutan en Windows 95/98 y Windows NT 3.51 y posteriores.

Para obtener más información sobre el uso de la clase CImageList, consulte Controles y Uso de CImageList.

Jerarquía de herencia

CObject

CImageList

Requisitos

Encabezado: afxcmn.h

CImageList::Add

Llame a esta función para agregar una o varias imágenes, o un icono, a una lista de imágenes.

int Add(
    CBitmap* pbmImage,
    CBitmap* pbmMask);

int Add(
    CBitmap* pbmImage,
    COLORREF crMask);

int Add(HICON hIcon);

Parámetros

pbmImage
Puntero al mapa de bits que contiene la imagen o las imágenes. El número de imágenes se deduce del ancho del mapa de bits.

pbmMask
Puntero al mapa de bits que contiene la máscara. Si no se usa ninguna máscara con la lista de imágenes, este parámetro se omite.

crMask
Color utilizado para generar la máscara. Cada píxel de este color del mapa de bits especificado se cambia a negro y el bit correspondiente de la máscara se establece en uno.

hIcon
Manipulador del icono que contiene el mapa de bits y la máscara de la nueva imagen.

Valor devuelto

Índice de base cero de la primera imagen nueva si se realiza correctamente; de lo contrario, -1.

Comentarios

Usted es responsable de liberar el manipulador del icono cuando haya terminado.

Ejemplo

// Add my icons.
m_myImageList.Add(AfxGetApp()->LoadIcon(IDI_ICON1));
m_myImageList.Add(AfxGetApp()->LoadIcon(IDI_ICON2));

// Add my bitmap, make all black pixels transparent.
CBitmap bm;
bm.LoadBitmap(IDB_BITMAP1);
m_myImageList.Add(&bm, RGB(0, 0, 0));

CImageList::Attach

Llame a esta función para adjuntar una lista de imágenes a un objeto CImageList.

BOOL Attach(HIMAGELIST hImageList);

Parámetros

hImageList
Manipulador de un objeto de lista de imágenes.

Valor devuelto

Distinto de cero si la asociación se ha realizado correctamente; de lo contrario, 0.

Ejemplo

void AddQuestion(HIMAGELIST hmyImageList)
{
   CImageList imgList;

   // Attach the image list handle to the CImageList object.
   imgList.Attach(hmyImageList);

   // Add a new icon to the image list.
   imgList.Add(AfxGetApp()->LoadStandardIcon(IDI_QUESTION));

   // Detach the handle from the CImageList object.
   imgList.Detach();
}

CImageList::BeginDrag

Llame a esta función para empezar a arrastrar una imagen.

BOOL BeginDrag(
    int nImage,
    CPoint ptHotSpot);

Parámetros

nImage
Índice de base cero de la imagen que se va a arrastrar.

ptHotSpot
Coordenadas de la posición de arrastre inicial (normalmente, la posición del cursor). Las coordenadas son relativas a la esquina superior izquierda de la imagen.

Valor devuelto

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

Comentarios

Esta función crea una lista de imágenes temporales que se usa para arrastrar. La imagen combina la imagen especificada y su máscara con el cursor actual. En respuesta a los mensajes WM_MOUSEMOVE posteriores, puede mover la imagen de arrastre mediante la función miembro DragMove. Para finalizar la operación de arrastrar, puede usar la función miembro EndDrag.

Ejemplo

void CImageListDlg::OnLButtonDown(UINT nFlags, CPoint point)
{
   // Initialize the drag image (usually called from WM_LBUTTONDOWN).
   m_myImageList.BeginDrag(0, CPoint(0, 0));
   m_myImageList.DragEnter(this, point);

   CDialog::OnLButtonDown(nFlags, point);
}

CImageList::CImageList

Construye un objeto CImageList.

CImageList();

CImageList::Copy

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

BOOL Copy(
    int iDst,
    int iSrc,
    UINT uFlags = ILCF_MOVE);

BOOL Copy(
    int iDst,
    CImageList* pSrc,
    int iSrc,
    UINT uFlags = ILCF_MOVE);

Parámetros

iDst
Índice de base cero de la imagen que se va a usar como destino de la operación de copia.

iSrc
Índice de base cero de la imagen que se va a usar como origen de la operación de copia.

uFlags
Valor de marca de bits que especifica el tipo de operación de copia que se va a realizar. Este parámetro puede establecerse con uno de los siguientes valores:

Valor	Significado
ILCF_MOVE	La imagen de origen se copia en el índice de la imagen de destino. Esta operación da como resultado varias instancias de una imagen especificada. ILCF_MOVE es el valor predeterminado.
ILCF_SWAP	Las imágenes de origen y destino intercambian posiciones dentro de la lista de imágenes.

pSrc
Puntero a un objeto CImageList que es el destino de la operación de copia.

Valor devuelto

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

Ejemplo

CImageList myImageList2;
myImageList2.Create(32, 32, ILC_COLOR8, 0, 4);

// Copy the first image from myImageList2 and make it
// the first image of m_myImageList.
m_myImageList.Copy(0, &myImageList2, 0, ILCF_MOVE);

// Recopy the image to make it also the last image in m_myImageList.
m_myImageList.Copy(m_myImageList.GetImageCount() - 1, (int)0,
                   (UINT)ILCF_MOVE);

CImageList::Create

Inicializa una lista de imágenes y la adjunta a un objeto CImageList.

BOOL Create(
    int cx,
    int cy,
    UINT nFlags,
    int nInitial,
    int nGrow);

BOOL Create(
    UINT nBitmapID,
    int cx,
    int nGrow,
    COLORREF crMask);

BOOL Create(
    LPCTSTR lpszBitmapID,
    int cx,
    int nGrow,
    COLORREF crMask);

BOOL Create(
    CImageList& imagelist1,
    int nImage1,
    CImageList& imagelist2,
    int nImage2,
    int dx,
    int dy);

BOOL Create(CImageList* pImageList);

Parámetros

cx
Dimensiones de cada imagen, en píxeles.

cy
Dimensiones de cada imagen, en píxeles.

nFlags
Especifica el tipo de lista de imágenes que se va a crear. Este parámetro puede ser una combinación de los valores siguientes, pero solo puede incluir uno de los valores ILC_COLOR.

Valor	Significado
ILC_COLOR	Use el comportamiento predeterminado si no se especifica ninguna de las otras marcas ILC_COLOR*. Normalmente, el valor predeterminado es ILC_COLOR4; pero para los controladores de presentación más antiguos, el valor predeterminado es ILC_COLORDDB.
ILC_COLOR4	Use una sección de mapa de bits independiente del dispositivo (DIB) de 4 bits (16 colores) como mapa de bits de la lista de imágenes.
ILC_COLOR8	Use una sección de DIB de 8 bits. Los colores usados para la tabla de colores son los mismos que la paleta de tonos medios.
ILC_COLOR16	Use una sección de DIB de 16 bits (color de 32/64 k).
ILC_COLOR24	Use una sección de DIB de 24 bits.
ILC_COLOR32	Use una sección de DIB de 32 bits.
ILC_COLORDDB	Use un mapa de bits dependiente del dispositivo.
ILC_MASK	Usa una máscara. La lista de imágenes contiene dos mapas de bits, uno de los cuales es un mapa de bits monocromo que se usa como máscara. Si no se incluye este valor, la lista de imágenes contiene solo un mapa de bits. Consulte Dibujo de imágenes de una lista de imágenes para obtener información adicional sobre las imágenes con máscara.

nInitial
Número de imágenes que contiene inicialmente la lista de imágenes.

nGrow
Número de imágenes que puede crecer la lista de imágenes cuando el sistema tiene que cambiar el tamaño de la lista para dejar espacio para las nuevas imágenes. Este parámetro representa el número de imágenes nuevas que puede contener la lista de imágenes una vez cambiado el tamaño.

nBitmapID
Identificadores de recurso del mapa de bits que se van a asociar a la lista de imágenes.

crMask
Color utilizado para generar una máscara. Cada píxel de este color del mapa de bits especificado se cambia a negro y el bit correspondiente de la máscara se establece en uno.

lpszBitmapID
Cadena que contiene los identificadores de recurso de las imágenes.

imagelist1
Referencia a un objeto CImageList.

nImage1
Índice de la primera imagen existente.

imagelist2
Referencia a un objeto CImageList.

nImage2
Índice de la segunda imagen existente.

dx
Desplazamiento del eje X de la segunda imagen en relación con la primera imagen, en píxeles.

dy
Desplazamiento del eje Y de la segunda imagen en relación con la primera imagen, en píxeles.

pImageList
Puntero a un objeto CImageList .

Valor devuelto

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

Comentarios

El proceso de construcción de un elemento CImageList se divide en dos pasos. En primer lugar, llame al constructor y, luego, a Create, que crea la lista de imágenes y la asocia al objeto CImageList.

Ejemplo

m_myImageList.Create(32, 32, ILC_COLOR8, 0, 4);

CImageList::DeleteImageList

Llame a esta función para eliminar una lista de imágenes.

BOOL DeleteImageList();

Valor devuelto

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

Ejemplo

// Delete the image list and verify.
myImageList2.DeleteImageList();
ASSERT(myImageList2.GetSafeHandle() == NULL);

CImageList::DeleteTempMap

Llamado automáticamente por el controlador de tiempo de inactividad de CWinApp, DeleteTempMap elimina los objetos CImageList temporales creados por FromHandle, pero no destruye ningún manipulador (hImageList) asociado temporalmente a los objetos ImageList.

static void PASCAL DeleteTempMap();

Ejemplo

// Note that this is a static member so an instantiated CImageList
// object is unnecessary.
CImageList::DeleteTempMap();

CImageList::Detach

Llame a esta función para desasociar un objeto de lista de imágenes de un objeto CImageList.

HIMAGELIST Detach();

Valor devuelto

Manipulador de un objeto de lista de imágenes.

Comentarios

Esta función devuelve un manipulador del objeto de lista de imágenes.

Ejemplo

Vea el ejemplo de CImageList::Attach.

CImageList::DragEnter

Durante una operación de arrastrar, bloquea las actualizaciones de la ventana especificada por pWndLock y muestra la imagen de arrastre en la posición especificada por point.

static BOOL PASCAL DragEnter(
    CWnd* pWndLock,
    CPoint point);

Parámetros

pWndLock
Puntero a la ventana que posee la imagen de arrastre.

point
Posición en la que se va a mostrar la imagen de arrastre. Las coordenadas son relativas a la esquina superior izquierda de la ventana (no al área cliente).

Valor devuelto

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

Comentarios

Las coordenadas son relativas a la esquina superior izquierda de la ventana, por lo que debe compensar los anchos de los elementos de la ventana, como el borde, la barra de título y la barra de menús, al especificar las coordenadas.

Si pWndLock es NULL, esta función dibuja la imagen en el contexto de visualización asociado a la ventana del escritorio y las coordenadas son relativas a la esquina superior izquierda de la pantalla.

Esta función bloquea todas las demás actualizaciones de la ventana especificada durante la operación de arrastre. Si necesita realizar algún dibujo durante una operación de arrastre, como resaltar el destino de una operación de arrastrar y colocar, puede ocultar temporalmente la imagen arrastrada mediante la función CImageList::DragLeave.

Ejemplo

Vea el ejemplo de CImageList::BeginDrag.

CImageList::DragLeave

Desbloquea la ventana especificada por pWndLock y oculta la imagen de arrastre, lo que permite actualizar la ventana.

static BOOL PASCAL DragLeave(CWnd* pWndLock);

Parámetros

pWndLock
Puntero a la ventana que posee la imagen de arrastre.

Valor devuelto

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

Ejemplo

Vea el ejemplo de CImageList::EndDrag.

CImageList::DragMove

Llame a esta función para mover la imagen que se está arrastrando durante una operación de arrastrar y colocar.

static BOOL PASCAL DragMove(CPoint pt);

Parámetros

pt
Nueva posición de arrastre.

Valor devuelto

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

Comentarios

Normalmente, se llama a esta función en respuesta a un mensaje WM_MOUSEMOVE. Para iniciar una operación de arrastre, use la función miembro BeginDrag.

Ejemplo

void CImageListDlg::OnMouseMove(UINT nFlags, CPoint point)
{
   m_myImageList.DragMove(point);

   CDialog::OnMouseMove(nFlags, point);
}

CImageList::DragShowNolock

Muestra u oculta la imagen de arrastre durante una operación de arrastre, sin bloquear la ventana.

static BOOL PASCAL DragShowNolock(BOOL bShow);

Parámetros

bShow
Especifica si se va a mostrar la imagen de arrastre.

Valor devuelto

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

Comentarios

La función CImageList::DragEnter bloquea todas las actualizaciones de la ventana durante una operación de arrastrar. Sin embargo, esta función no bloquea la ventana.

CImageList::Draw

Llame a esta función para mover la imagen que se está arrastrando durante una operación de arrastrar y colocar.

BOOL Draw(
    CDC* pDC,
    int nImage,
    POINT pt,
    UINT nStyle);

Parámetros

pDC
Puntero al contexto del dispositivo de destino.

nImage
Índice de base cero de la imagen que se va a dibujar.

pt
Ubicación en la que se va a dibujar dentro del contexto de dispositivo especificado.

nStyle
Marca que especifica el estilo de dibujo. Puede ser uno o varios de estos valores:

Valor	Significado
ILD_BLEND25, ILD_FOCUS	Dibuja la imagen, mezclando el 25 por ciento con el color de resaltado del sistema. Este valor no tiene ningún efecto si la lista de imágenes no contiene una máscara.
ILD_BLEND50, ILD_SELECTED, ILD_BLEND	Dibuja la imagen, mezclando el 50 por ciento con el color de resaltado del sistema. Este valor no tiene ningún efecto si la lista de imágenes no contiene una máscara.
ILD_MASK	Dibuja la máscara.
ILD_NORMAL	Dibuja la imagen con el color de fondo de la lista de imágenes. Si el color de fondo es el valor CLR_NONE, la imagen se dibuja de forma transparente mediante la máscara.
ILD_TRANSPARENT	Dibuja la imagen de forma transparente mediante la máscara, independientemente del color de fondo.

Valor devuelto

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

Ejemplo

Vea el ejemplo de CImageList::SetOverlayImage.

CImageList::DrawEx

Dibuja un elemento de lista de imágenes en el contexto de dispositivo especificado.

BOOL DrawEx(
    CDC* pDC,
    int nImage,
    POINT pt,
    SIZE sz,
    COLORREF clrBk,
    COLORREF clrFg,
    UINT nStyle);

Parámetros

pDC
Puntero al contexto del dispositivo de destino.

nImage
Índice de base cero de la imagen que se va a dibujar.

pt
Ubicación en la que se va a dibujar dentro del contexto de dispositivo especificado.

sz
Tamaño de la parte de la imagen que se va a dibujar en relación con la esquina superior izquierda de la imagen. Consulte dx y dy en ImageList_DrawEx en Windows SDK.

clrBk
Color de fondo de la imagen. Consulte rgbBk en ImageList_DrawEx de Windows SDK.

clrFg
Color de primer plano de la imagen. Consulte rgbFg en ImageList_DrawEx de Windows SDK.

nStyle
Marca que especifica el estilo de dibujo. Consulte fStyle en ImageList_DrawEx de Windows SDK.

Valor devuelto

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

Comentarios

La función usa el estilo de dibujo especificado y combina la imagen con el color especificado.

Ejemplo

m_myImageList.DrawEx(&dc, 0, CPoint(0, 0), CSize(16, 16), CLR_DEFAULT,
                     CLR_DEFAULT, ILD_IMAGE);

CImageList::DrawIndirect

Llame a esta función miembro para dibujar una imagen de una lista de imágenes.

BOOL DrawIndirect(IMAGELISTDRAWPARAMS* pimldp);

BOOL DrawIndirect(
    CDC* pDC,
    int nImage,
    POINT pt,
    SIZE sz,
    POINT ptOrigin,
    UINT fStyle = ILD_NORMAL,
    DWORD dwRop = SRCCOPY,
    COLORREF rgbBack = CLR_DEFAULT,
    COLORREF rgbFore = CLR_DEFAULT,
    DWORD fState = ILS_NORMAL,
    DWORD Frame = 0,
    COLORREF crEffect = CLR_DEFAULT);

Parámetros

pimldp
Puntero a una estructura IMAGELISTDRAWPARAMS que contiene información sobre la operación de dibujo.

pDC
Puntero al contexto del dispositivo de destino. Debe eliminar este objeto CDC cuando haya terminado con él.

nImage
Índice de base cero de la imagen que se va a dibujar.

pt
Estructura POINT que contiene las coordenadas X e Y en las que se dibujará la imagen.

sz
Estructura SIZE que indica el tamaño de la imagen que se va a dibujar.

ptOrigin
Estructura POINT que contiene las coordenadas X e Y que especifican la esquina superior izquierda de la operación de dibujo con respecto a la propia imagen. Los píxeles de la imagen que se encuentran a la izquierda de la coordenada X y por encima de la coordenada Y no se dibujan.

fStyle
Marca que especifica el estilo de dibujo y, opcionalmente, la imagen de superposición. Para obtener información sobre la imagen de superposición, consulte la sección Comentarios. La implementación predeterminada de MFC, ILD_NORMAL, dibuja la imagen con el color de fondo de la lista de imágenes. Si el color de fondo es el valor CLR_NONE, la imagen se dibuja de forma transparente mediante una máscara.

Otros estilos posibles se describen en el miembro fStyle de la estructura IMAGELISTDRAWPARAMS.

dwRop
Valor que especifica un código de operación de trama. Estos códigos definen cómo se combinarán los datos de color del rectángulo de origen con los datos de color del rectángulo de destino para lograr el color final. La implementación predeterminada de MFC, SRCCOPY, copia el rectángulo de origen directamente en el rectángulo de destino. Este parámetro se omite si el parámetro fStyle no incluye la marca ILD_ROP.

Otros valores posibles se describen en el miembro dwRop de la estructura IMAGELISTDRAWPARAMS.

rgbBack
Color de fondo de la imagen, de forma predeterminada, CLR_DEFAULT. Este parámetro puede ser un valor RGB definido por la aplicación o uno de los valores siguientes:

Valor	Significado
CLR_DEFAULT	Color de fondo predeterminado. La imagen se dibuja con el color de fondo de la lista de imágenes.
CLR_NONE	Ningún color de fondo. La imagen se dibuja de forma transparente.

rgbFore
Color de primer plano de la imagen, de forma predeterminada, CLR_DEFAULT. Este parámetro puede ser un valor RGB definido por la aplicación o uno de los valores siguientes:

Valor	Significado
CLR_DEFAULT	Color de primer plano predeterminado. La imagen se dibuja con el color de resaltado del sistema como color de primer plano.
CLR_NONE	Ningún color de mezcla. La imagen se combina con el color del contexto del dispositivo de destino.

Este parámetro solo se usa si fStyle incluye la marca ILD_BLEND25 o ILD_BLEND50.

fState
Marca que especifica el estado del dibujo. Este miembro puede contener una o varias marcas de estado de la lista de imágenes.

Frame
Afecta al comportamiento de los efectos de saturación y de combinación alfa.

Cuando se usa con ILS_SATURATE, este miembro contiene el valor que se agrega a cada componente de color de la terna RGB para cada píxel del icono.

Cuando se usa con ILS_APLHA, este miembro contiene el valor del canal alfa. Este valor puede ir de 0 a 255, donde 0 es completamente transparente y 255 es completamente opaco.

crEffect
Valor COLORREF utilizado para efectos de brillo y sombra.

Valor devuelto

TRUE si la imagen se dibuja correctamente; de lo contrario, FALSE.

Comentarios

Use la primera versión si quiere rellenar la estructura de Win32 usted mismo. Use la segunda versión si desea aprovechar uno o varios de los argumentos predeterminados de MFC, o evitar administrar la estructura.

Una imagen de superposición es una imagen que se dibuja encima de la imagen principal, especificada en esta función miembro por el parámetro nImage. Dibuje una máscara de superposición mediante la función miembro Draw con el índice de base uno de la máscara de superposición especificada mediante la macro INDEXTOOVERLAYMASK.

Ejemplo

int i, dx, cx, cy, nCount = m_myImageList.GetImageCount();

::ImageList_GetIconSize(m_myImageList, &cx, &cy);

// Draw the images of the image list on the DC.
for (dx = 0, i = 0; i < nCount; i++)
{
   m_myImageList.DrawIndirect(&dc, i, CPoint(dx, 0),
                              CSize(cx, cy), CPoint(0, 0));
   dx += cx;
}

CImageList::EndDrag

Llame a esta función para finalizar una operación de arrastre.

static void PASCAL EndDrag();

Comentarios

Para iniciar una operación de arrastre, use la función miembro BeginDrag.

Ejemplo

void CImageListDlg::OnLButtonUp(UINT nFlags, CPoint point)
{
   // Terminate the drag image (usually called from WM_LBUTTONUP).
   m_myImageList.DragLeave(this);
   m_myImageList.EndDrag();

   CDialog::OnLButtonUp(nFlags, point);
}

CImageList::ExtractIcon

Llame a esta función para crear un icono basado en una imagen y su máscara relacionada de una lista de imágenes.

HICON ExtractIcon(int nImage);

Parámetros

nImage
Índice de base cero de la imagen.

Valor devuelto

Manipulador del icono si se realiza correctamente; de lo contrario, NULL.

Comentarios

Este método se basa en el comportamiento de la macro ImageList_ExtractIcon para crear el icono. Consulte la macro ImageList_ExtractIcon para obtener más información sobre la creación y limpieza de iconos.

Ejemplo

int i, dx, cx, cy, nCount = m_myImageList.GetImageCount();
HICON hIcon;

::ImageList_GetIconSize(m_myImageList, &cx, &cy);

// Draw the images of the image list on the DC.
for (dx = 0, i = 0; i < nCount; i++)
{
   hIcon = m_myImageList.ExtractIcon(i);

   dc.DrawIcon(dx, 0, hIcon);
   dx += cx;
}

CImageList::FromHandle

Devuelve un puntero a un objeto CImageList cuando se especifica un manipulador a una lista de imágenes.

static CImageList* PASCAL FromHandle(HIMAGELIST hImageList);

Parámetros

hImageList
Especifica la lista de imágenes.

Valor devuelto

Un puntero a un objeto CImageList si se realiza correctamente; de lo contrario, NULL.

Comentarios

Si no hay un elemento CImageList ya asociado al manipulador, se crea y asocia un objeto CImageList temporal. Este objeto CImageList temporal solo es válido hasta la próxima vez que la aplicación tenga tiempo de inactividad en su bucle de eventos, momento en el que se eliminan todos los objetos temporales.

Ejemplo

CImageList *ConvertHandle(HIMAGELIST hmyImageList)
{
   // Convert the HIMAGELIST to a CImageList*.
   ASSERT(hmyImageList != NULL);
   CImageList *pmyImageList = CImageList::FromHandle(hmyImageList);
   ASSERT(pmyImageList != NULL);

   return pmyImageList;
}

CImageList::FromHandlePermanent

Devuelve un puntero a un objeto CImageList cuando se especifica un manipulador a una lista de imágenes.

static CImageList* PASCAL FromHandlePermanent(HIMAGELIST hImageList);

Parámetros

hImageList
Especifica la lista de imágenes.

Valor devuelto

Un puntero a un objeto CImageList si se realiza correctamente; de lo contrario, NULL.

Comentarios

Si no se ha asociado un objeto CImageList al manipulador, se devuelve NULL.

Ejemplo

CImageList *ConvertHandlePermanent(HIMAGELIST hmyImageList)
{
   // Convert the HIMAGELIST to a CImageList*.
   ASSERT(hmyImageList != NULL);
   CImageList *pmyImageList = CImageList::FromHandlePermanent(hmyImageList);
   ASSERT(pmyImageList != NULL);

   return pmyImageList;
}

CImageList::GetBkColor

Llame a esta función para recuperar el color de fondo actual de una lista de imágenes.

COLORREF GetBkColor() const;

Valor devuelto

Valor de color RGB del color de fondo del objeto CImageList.

Ejemplo

Vea el ejemplo de CImageList::SetBkColor.

CImageList::GetDragImage

Obtiene la lista de imágenes temporales que se usa para arrastrar.

static CImageList* PASCAL GetDragImage(
    LPPOINT lpPoint,
    LPPOINT lpPointHotSpot);

Parámetros

lpPoint
Dirección de una estructura POINT que recibe la posición de arrastre actual.

lpPointHotSpot
Dirección de una estructura POINT que recibe el desplazamiento de la imagen de arrastre en relación con la posición de arrastre.

Valor devuelto

Si se ejecuta correctamente, un puntero a la lista de imágenes temporales que se usa para arrastrar; de lo contrario, NULL.

CImageList::GetImageCount

Llame a esta función para recuperar el número de imágenes de una lista de imágenes.

int GetImageCount() const;

Valor devuelto

Número de imágenes.

Ejemplo

Vea el ejemplo de CImageList::ExtractIcon.

CImageList::GetImageInfo

Llame a esta función para recuperar información sobre una imagen.

BOOL GetImageInfo(
    int nImage,
    IMAGEINFO* pImageInfo) const;

Parámetros

nImage
Índice de base cero de la imagen.

pImageInfo
Puntero a una estructura IMAGEINFO que recibe la información sobre la imagen. La información de esta estructura se puede usar para manipular directamente los mapas de bits de la imagen.

Valor devuelto

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

Comentarios

La estructura IMAGEINFO contiene información sobre una imagen de una lista de imágenes.

CImageList::GetSafeHandle

Llame a esta función para recuperar el miembro de datos m_hImageList.

HIMAGELIST GetSafeHandle() const;

Valor devuelto

Manipulador de la lista de imágenes asociada; de lo contrario, NULL si no hay ningún objeto adjunto.

Ejemplo

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList.GetSafeHandle();

CImageList::m_hImageList

Manipulador de la lista de imágenes adjunta a este objeto.

HIMAGELIST m_hImageList;

Comentarios

El miembro de datos m_hImageList es una variable pública de tipo HIMAGELIST.

Ejemplo

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList.m_hImageList;

CImageList::operator HIMAGELIST

Use este operador para obtener el manipulador asociado al objeto CImageList.

operator HIMAGELIST() const;

Valor devuelto

Si se ejecuta correctamente, un manipulador de la lista de imágenes representada por el objeto CImageList; de lo contrario, NULL.

Comentarios

Este operador es un operador de conversión que admite el uso directo de un objeto HIMAGELIST.

Ejemplo

// Get the safe handle to the image list.
HIMAGELIST hImageList = m_myImageList;

CImageList::Read

Llame a esta función para leer una lista de imágenes de un archivo.

BOOL Read(CArchive* pArchive);

Parámetros

pArchive
Puntero a un objeto CArchive desde el que se va a leer la lista de imágenes.

Valor devuelto

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

Ejemplo

// Open the archive to load the image list from.
CFile myFile(_T("myfile.data"), CFile::modeRead);
CArchive ar(&myFile, CArchive::load);
CImageList myImgList;

// Load the image list from the archive.
myImgList.Read(&ar);

CImageList::Remove

Llame a esta función para quitar una imagen de un objeto de lista de imágenes.

BOOL Remove(int nImage);

Parámetros

nImage
Índice de base cero de la imagen que se va a quitar.

Valor devuelto

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

Comentarios

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

Ejemplo

// Remove every other image from the image list.
for (int i = 0; i < m_myImageList.GetImageCount(); i++)
{
   m_myImageList.Remove(i);
}

CImageList::Replace

Llame a esta función para reemplazar una imagen de una lista de imágenes por una nueva imagen.

BOOL Replace(
    int nImage,
    CBitmap* pbmImage,
    CBitmap* pbmMask);

int Replace(
    int nImage,
    HICON hIcon);

Parámetros

nImage
Índice de base cero de la imagen que se va a reemplazar.

pbmImage
Puntero al mapa de bits que contiene la imagen.

pbmMask
Puntero al mapa de bits que contiene la máscara. Si no se usa ninguna máscara con la lista de imágenes, este parámetro se omite.

hIcon
Manipulador del icono que contiene el mapa de bits y la máscara de la nueva imagen.

Valor devuelto

La versión que devuelve BOOL devuelve un valor distinto de cero si se ejecuta correctamente; de lo contrario, devuelve 0.

La versión que devuelve int devuelve el índice de base cero de la imagen si se ejecuta correctamente; de lo contrario, devuelve -1.

Comentarios

Llame a esta función miembro después de llamar a SetImageCount para asignar las imágenes nuevas y válidas a los números de índice de imagen de marcador de posición.

Ejemplo

Vea el ejemplo de CImageList::SetImageCount.

CImageList::SetBkColor

Llame a esta función para establecer el color de fondo de una lista de imágenes.

COLORREF SetBkColor(COLORREF cr);

Parámetros

cr
Color de fondo que se va a establecer. Puede ser CLR_NONE. En ese caso, las imágenes se dibujan de forma transparente mediante la máscara.

Valor devuelto

Color de fondo anterior si se ejecuta correctamente; de lo contrario, CLR_NONE.

Ejemplo

// Set the background color to white.
m_myImageList.SetBkColor(RGB(255, 255, 255));
ASSERT(m_myImageList.GetBkColor() == RGB(255, 255, 255));

CImageList::SetDragCursorImage

Crea una nueva imagen de arrastre combinando la imagen dada (normalmente, una imagen de cursor del mouse) con la imagen de arrastre actual.

BOOL SetDragCursorImage(
    int nDrag,
    CPoint ptHotSpot);

Parámetros

nDrag
Índice de la nueva imagen que se va a combinar con la imagen de arrastre.

ptHotSpot
Posición de la zona activa dentro de la nueva imagen.

Valor devuelto

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

Comentarios

Dado que las funciones de arrastre usan la nueva imagen durante una operación de arrastre, debe usar la función de Windows ShowCursor para ocultar el cursor del mouse real después de llamar a CImageList::SetDragCursorImage. De lo contrario, el sistema puede parecer tener dos cursores del mouse mientras dure la operación de arrastre.

CImageList::SetImageCount

Llame a esta función miembro para restablecer el número de imágenes de un objeto CImageList.

BOOL SetImageCount(UINT uNewCount);

Parámetros

uNewCount
Valor que especifica el nuevo número total de imágenes de la lista de imágenes.

Valor devuelto

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

Comentarios

Si llama a esta función miembro para aumentar el número de imágenes de la lista de imágenes, llame a Replace para cada imagen adicional para asignar los nuevos índices a imágenes válidas. Si no puede asignar los índices a imágenes válidas, las operaciones de dibujo que crean las nuevas imágenes serán impredecibles.

Si reduce el tamaño de una lista de imágenes mediante esta función, se liberan las imágenes truncadas.

Ejemplo

// Set the image count of the image list to be 10 with
// all images being the system question mark icon.
m_myImageList.SetImageCount(10);
HICON hIcon = AfxGetApp()->LoadStandardIcon(IDI_QUESTION);

for (int i = 0; i < 10; i++)
{
   m_myImageList.Replace(i, hIcon);
}

CImageList::SetOverlayImage

Llame a esta función para agregar el índice de base cero de una imagen a la lista de imágenes que se van a usar como máscaras de superposición.

BOOL SetOverlayImage(
    int nImage,
    int nOverlay);

Parámetros

nImage
Índice de base cero de la imagen que se va a usar como máscara de superposición.

nOverlay
Índice de base uno de la máscara de superposición.

Valor devuelto

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

Comentarios

Se pueden agregar hasta cuatro índices a la lista.

Una máscara de superposición es una imagen dibujada de forma transparente sobre otra imagen. Dibuje una máscara de superposición sobre una imagen mediante la función miembro CImageList::Draw con el índice de base uno de la máscara de superposición especificada mediante la macro INDEXTOOVERLAYMASK.

Ejemplo

// Add a new image to the image list.
int nIndex = m_myImageList.Add(AfxGetApp()->LoadStandardIcon(IDI_QUESTION));

if (nIndex != -1)
{
   // Make the new image an overlay image.
   m_myImageList.SetOverlayImage(nIndex, 1);

   // Draw the first image in the image list with an overlay image.
   m_myImageList.Draw(&dc, 0, CPoint(0, 0), INDEXTOOVERLAYMASK(1));
}

CImageList::Write

Llame a esta función para escribir un objeto de lista de imágenes en un archivo.

BOOL Write(CArchive* pArchive);

Parámetros

pArchive
Puntero a un objeto CArchive en el que se va a almacenar la lista de imágenes.

Valor devuelto

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

Ejemplo

// Open the archive to store the image list in.
CFile myFile(_T("myfile.data"), CFile::modeCreate | CFile::modeWrite);
CArchive ar(&myFile, CArchive::store);

// Store the image list in the archive.
m_myImageList.Write(&ar);

Vea también

CObject (clase)
Gráfico de jerarquías
CListCtrl (clase)
CTabCtrl (clase)