Classe `CImageList`

Artigo
07/05/2024

Fornece a funcionalidade do controle de lista de imagens comum do Windows.

Sintaxe

class CImageList : public CObject

Membros

Construtores públicos

Nome	Descrição
`CImageList::CImageList`	Constrói um objeto `CImageList`.

Métodos públicos

Nome	Descrição
`CImageList::Add`	Adiciona uma imagem ou imagens a uma lista de imagens.
`CImageList::Attach`	Anexa uma lista de imagens a um objeto `CImageList`.
`CImageList::BeginDrag`	Começa arrastando uma imagem.
`CImageList::Copy`	Copia uma imagem dentro de um objeto `CImageList`.
`CImageList::Create`	Inicializa uma lista de imagens e a anexa a um objeto `CImageList`.
`CImageList::DeleteImageList`	Exclui uma lista de imagens.
`CImageList::DeleteTempMap`	Chamado pelo manipulador de tempo ocioso `CWinApp` para excluir qualquer objeto `CImageList` temporário criado por `FromHandle`.
`CImageList::Detach`	Desanexa um objeto da lista de imagens de um objeto `CImageList` e retorna um identificador para uma lista de imagens.
`CImageList::DragEnter`	Bloqueia atualizações durante uma operação de arrastar e exibe a imagem de arrasto em uma posição especificada.
`CImageList::DragLeave`	Desbloqueia a janela e oculta a imagem de arrasto para que a janela possa ser atualizada.
`CImageList::DragMove`	Move a imagem que está sendo arrastada durante uma operação do tipo "arrastar e soltar".
`CImageList::DragShowNolock`	Mostra ou oculta a imagem de arrastar durante uma operação de arrastar, sem bloquear a janela.
`CImageList::Draw`	Desenha a imagem que está sendo arrastada durante uma operação do tipo "arrastar e soltar".
`CImageList::DrawEx`	Desenha um item da lista de imagens no contexto do dispositivo especificado. A função usa o estilo de desenho especificado e combina a imagem com a cor especificada.
`CImageList::DrawIndirect`	Desenha uma imagem de uma lista de imagens.
`CImageList::EndDrag`	Encerra uma operação de arrastar.
`CImageList::ExtractIcon`	Cria um ícone baseado em uma imagem e máscara em uma lista de imagens.
`CImageList::FromHandle`	Retorna um ponteiro para um objeto `CImageList` quando dado um identificador para uma lista de imagens. Se um objeto `CImageList` não estiver anexado ao identificador, um objeto temporário `CImageList` será criado e anexado.
`CImageList::FromHandlePermanent`	Retorna um ponteiro para um objeto `CImageList` quando dado um identificador para uma lista de imagens. Se um objeto `CImageList` não estiver anexado ao identificador, NULL será retornado.
`CImageList::GetBkColor`	Recupera a cor da tela de fundo atual para uma lista de imagens.
`CImageList::GetDragImage`	Obtém a lista de imagens temporárias usada para arrastar.
`CImageList::GetImageCount`	Recupera o número de imagens em uma lista de imagens.
`CImageList::GetImageInfo`	Recupera informações sobre uma imagem.
`CImageList::GetSafeHandle`	Recupera `m_hImageList`.
`CImageList::Read`	Lê uma lista de imagens de um arquivo.
`CImageList::Remove`	Remove uma imagem de uma lista de imagens.
`CImageList::Replace`	Substitui uma imagem em uma lista de imagens por uma nova imagem.
`CImageList::SetBkColor`	Define a cor da tela de fundo de uma lista de imagens.
`CImageList::SetDragCursorImage`	Cria uma nova imagem de arrasto.
`CImageList::SetImageCount`	Redefine a contagem de imagens em uma lista de imagens.
`CImageList::SetOverlayImage`	Adiciona o índice baseado em zero de uma imagem à lista de imagens a serem usadas como máscaras de sobreposição.
`CImageList::Write`	Grava uma lista de imagens em um arquivo.

Operadores públicos

Nome	Descrição
`CImageList::operator HIMAGELIST`	Retorna `HIMAGELIST` anexado ao `CImageList`.

Membros de Dados Públicos

Nome	Descrição
`CImageList::m_hImageList`	Um identificador que contém a lista de imagens anexada a esse objeto.

Comentários

Uma "lista de imagens" é uma coleção de imagens do mesmo tamanho, cada uma delas pode ser referenciada por seu índice baseado em zero. As listas de imagens são usadas para gerenciar com eficiência grandes conjuntos de ícones ou bitmaps. Todas as imagens em uma lista de imagens estão contidas em um único bitmap largo no formato de dispositivo de tela. Uma lista de imagens também pode incluir um bitmap monocromático que contém máscaras usadas para desenhar imagens de forma transparente (estilo de ícone). A API (interface de programação de aplicativos) do Microsoft Win32 fornece funções de membro que permitem desenhar imagens, criar e destruir listas de imagens, adicionar e remover imagens, substituir imagens, mesclar imagens e arrastar imagens.

Esse controle (e, portanto, a classe CImageList) está disponível apenas para programas em execução no Windows 95/98 e Windows NT versão 3.51 e posteriores.

Para obter mais informações sobre como usar CImageList, consulte Controles e Usar CImageList.

Hierarquia de herança

CObject

CImageList

Requisitos

Cabeçalho: afxcmn.h

`CImageList::Add`

Chame essa função para adicionar uma ou mais imagens ou um ícone a uma lista de imagens.

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

int Add(
    CBitmap* pbmImage,
    COLORREF crMask);

int Add(HICON hIcon);

Parâmetros

pbmImage
Ponteiro para o bitmap que contém a imagem ou as imagens. O número de imagens é inferido da largura do bitmap.

pbmMask
Ponteiro para o bitmap que contém a máscara. Se nenhuma máscara for usada com a lista de imagens, esse parâmetro será ignorado.

crMask
Cor usada para gerar a máscara. Cada pixel dessa cor no bitmap determinado é alterado para preto e o bit correspondente na máscara é definido como um.

hIcon
Identificador do ícone que contém o bitmap e a máscara para a nova imagem.

Valor de retorno

Índice baseado em zero da primeira nova imagem, se bem-sucedido; caso contrário, - 1.

Comentários

Você é responsável por liberar o identificador de ícone quando terminar de usá-lo.

Exemplo

// 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`

Chame essa função para anexar uma lista de imagens a um objeto CImageList.

BOOL Attach(HIMAGELIST hImageList);

Parâmetros

hImageList
Um identificador para um objeto da lista de imagens.

Valor de retorno

Diferente de zero se o anexo foi bem-sucedido; caso contrário, 0.

Exemplo

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`

Chame essa função para começar a arrastar uma imagem.

BOOL BeginDrag(
    int nImage,
    CPoint ptHotSpot);

Parâmetros

nImage
Índice de base zero da imagem a ser arrastada.

ptHotSpot
Coordenadas da posição de arrastar inicial (normalmente, a posição do cursor). As coordenadas são relativas ao canto superior esquerdo da imagem.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função cria uma lista de imagens temporária usada para arrastar. A imagem combina a imagem especificada e sua máscara com o cursor atual. Em resposta às mensagens WM_MOUSEMOVE subsequentes, você pode mover a imagem de arrasto usando a função membro DragMove. Para encerrar a operação de arrastar, você pode usar a função membro EndDrag.

Exemplo

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`

Constrói um objeto CImageList.

CImageList();

`CImageList::Copy`

Essa função membro implementa o comportamento da função do Win32 ImageList_Copy, conforme descrito no SDK do Windows.

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
O índice baseado em zero da imagem a ser usada como o destino da operação de cópia.

iSrc
O índice baseado em zero da imagem a ser usada como a fonte da operação de cópia.

uFlags
O valor do sinalizador de bit que especifica o tipo de operação de cópia a ser feita. Esse parâmetro pode usar um dos valores a seguir:

Valor	Significado
`ILCF_MOVE`	A imagem de origem é copiada para o índice da imagem de destino. Essa operação resulta em várias instâncias de uma determinada imagem. `ILCF_MOVE` é o padrão.
`ILCF_SWAP`	As imagens de origem e de destino trocam posições na lista de imagens.

pSrc
Um ponteiro para um objeto CImageList que é o destino da operação de cópia.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

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 uma lista de imagens e a anexa a um 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
Dimensões de cada imagem, em pixels.

cy
Dimensões de cada imagem, em pixels.

nFlags
Especifica o tipo de lista de imagens a ser criada. Esse parâmetro pode ser uma combinação dos valores a seguir, mas pode incluir apenas um dos valores ILC_COLOR.

Valor	Significado
`ILC_COLOR`	Use o comportamento padrão se nenhum dos outros sinalizadores `ILC_COLOR*` for especificado. Normalmente, o padrão é `ILC_COLOR4`; mas para drivers de exibição mais antigos, o padrão é `ILC_COLORDDB`.
`ILC_COLOR4`	Use uma seção DIB (bitmap) independente do dispositivo de 4 bits (16 cores) como o bitmap para a lista de imagens.
`ILC_COLOR8`	Use uma seção DIB de 8 bits. As cores usadas para a tabela de cores são as mesmas cores que a paleta de meio-tom.
`ILC_COLOR16`	Use uma seção DIB de 16 bits (cor 32/64k).
`ILC_COLOR24`	Use uma seção DIB de 24 bits.
`ILC_COLOR32`	Use uma seção DIB de 32 bits.
`ILC_COLORDDB`	Use um bitmap dependente do dispositivo.
`ILC_MASK`	Usa uma máscara. A lista de imagens contém dois bitmaps, um sendo um bitmap monocromático usado como máscara. Se esse valor não estiver incluído, a lista de imagens conterá apenas um bitmap. Consulte Desenhando imagens a partir de uma lista de imagens para obter informações adicionais sobre imagens mascaradas.

nInitial
Número de imagens que a lista de imagens contém inicialmente.

nGrow
Número de imagens pelas quais a lista de imagens pode crescer quando o sistema precisar redimensionar a lista para abrir espaço para novas imagens. Esse parâmetro representa o número de novas imagens que a lista de imagens redimensionadas pode conter.

nBitmapID
IDs de recurso do bitmap a ser associado à lista de imagens.

crMask
Cor usada para gerar uma máscara. Cada pixel dessa cor no bitmap especificado é alterado para preto e o bit correspondente na máscara é definido como um.

lpszBitmapID
Uma cadeia de caracteres que contém as IDs do recurso das imagens.

imagelist1
Uma referência a um objeto CImageList.

nImage1
Índice da primeira imagem existente.

imagelist2
Uma referência a um objeto CImageList.

nImage2
Índice da segunda imagem existente.

dx
Deslocamento do eixo x da segunda imagem em relação à primeira imagem, em pixels.

dy
Deslocamento do eixo y da segunda imagem em relação à primeira imagem, em pixels.

pImageList
Um ponteiro para um objeto CImageList.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

O CImageList é construído em duas etapas. Primeiro, chame o construtor e, em seguida, chame Create, que cria a lista de imagens e a anexa ao objeto CImageList.

Exemplo

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

`CImageList::DeleteImageList`

Chame essa função para excluir uma lista de imagens.

BOOL DeleteImageList();

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

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

`CImageList::DeleteTempMap`

Chamado automaticamente pelo manipulador de tempo ocioso CWinApp, DeleteTempMap exclui todos os objetos CImageList temporários criados pelo FromHandle, mas não destrói identificadores ( hImageList) temporariamente associados aos objetos ImageList.

static void PASCAL DeleteTempMap();

Exemplo

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

`CImageList::Detach`

Chame essa função para desanexar um objeto da lista de imagens de um objeto CImageList.

HIMAGELIST Detach();

Valor de retorno

Um identificador para um objeto da lista de imagens.

Comentários

Essa função retorna um identificador para o objeto de lista de imagens.

Exemplo

Confira o exemplo de CImageList::Attach.

`CImageList::DragEnter`

Durante uma operação de arrastar, bloqueia as atualizações para a janela especificada por pWndLock e exibe a imagem de arrastar na posição especificada por point.

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

Parâmetros

pWndLock
Ponteiro para a janela que possui a imagem de arrastar.

point
Posição na qual a imagem de arrasto deve ser exibida. As coordenadas são relativas ao canto superior esquerdo da janela (não da área do cliente).

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

As coordenadas são relativas ao canto superior esquerdo da janela, portanto, é necessário compensar as larguras dos elementos da janela, como a borda, a barra de título e a barra de menus, ao especificar as coordenadas.

Se pWndLock for NULL, essa função desenha a imagem no contexto de exibição associado à janela da área de trabalho e as coordenadas são relativas ao canto superior esquerdo da tela.

Essa função bloqueia todas as outras atualizações para a janela fornecida durante a operação de arrastar. Se você precisar fazer qualquer desenho durante uma operação de arrastar, como realçar o destino de uma operação do tipo "arrastar e soltar", será possível ocultar temporariamente a imagem arrastada usando a função CImageList::DragLeave.

Exemplo

Confira o exemplo de CImageList::BeginDrag.

`CImageList::DragLeave`

Desbloqueia a janela especificada por pWndLock e oculta a imagem de arrasto, permitindo que a janela seja atualizada.

static BOOL PASCAL DragLeave(CWnd* pWndLock);

Parâmetros

pWndLock
Ponteiro para a janela que possui a imagem de arrastar.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

Confira o exemplo de CImageList::EndDrag.

`CImageList::DragMove`

Chame essa função para mover a imagem que está sendo arrastada durante uma operação do tipo "arrastar e soltar".

static BOOL PASCAL DragMove(CPoint pt);

Parâmetros

pt
Nova posição de arrastar.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função normalmente é chamada em resposta a uma mensagem WM_MOUSEMOVE. Para iniciar uma operação de arrastar, use a função membro BeginDrag.

Exemplo

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

   CDialog::OnMouseMove(nFlags, point);
}

`CImageList::DragShowNolock`

Mostra ou oculta a imagem de arrastar durante uma operação de arrastar, sem bloquear a janela.

static BOOL PASCAL DragShowNolock(BOOL bShow);

Parâmetros

bShow
Especifica se a imagem de arrasto deve ser exibida.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A função CImageList::DragEnter bloqueia todas as atualizações na janela durante uma operação de arrastar. Essa função, no entanto, não bloqueia a janela.

`CImageList::Draw`

Chame essa função para desenhar a imagem que está sendo arrastada durante uma operação do tipo "arrastar e soltar".

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

Parâmetros

pDC
Ponteiro para o contexto do dispositivo de destino.

nImage
Índice de base zero da imagem a ser desenhada.

pt
Local para desenhar no contexto do dispositivo especificado.

nStyle
Sinalizador especificando o estilo de desenho. Poderá ser um ou mais desses valores:

Valor	Significado
`ILD_BLEND25`, `ILD_FOCUS`	Desenha a imagem, combinando 25% com a cor de realce do sistema. Esse valor não terá efeito se a lista de imagens não contiver uma máscara.
`ILD_BLEND50`, `ILD_SELECTED`, `ILD_BLEND`	Desenha a imagem, combinando 50% com a cor de realce do sistema. Esse valor não terá efeito se a lista de imagens não contiver uma máscara.
`ILD_MASK`	Desenha a máscara.
`ILD_NORMAL`	Desenha a imagem usando a cor da tela de fundo da lista de imagens. Se a cor da tela de fundo for o valor `CLR_NONE`, a imagem será desenhada de forma transparente usando a máscara.
`ILD_TRANSPARENT`	Desenha a imagem de forma transparente usando a máscara, independentemente da cor da tela de fundo.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

Confira o exemplo de CImageList::SetOverlayImage.

`CImageList::DrawEx`

Desenha um item da lista de imagens no contexto do dispositivo especificado.

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

Parâmetros

pDC
Ponteiro para o contexto do dispositivo de destino.

nImage
Índice de base zero da imagem a ser desenhada.

pt
Local para desenhar no contexto do dispositivo especificado.

sz
Tamanho da parte da imagem a ser desenhada em relação ao canto superior esquerdo da imagem. Veja dx e dy no ImageList_DrawEx no SDK do Windows.

clrBk
Cor da tela de fundo da imagem. Consulte rgbBk em ImageList_DrawEx no SDK do Windows.

clrFg
Cor de primeiro plano da imagem. Consulte rgbFg em ImageList_DrawEx no SDK do Windows.

nStyle
Sinalizador especificando o estilo de desenho. Consulte fStyle em ImageList_DrawEx no SDK do Windows.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A função usa o estilo de desenho especificado e combina a imagem com a cor especificada.

Exemplo

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

`CImageList::DrawIndirect`

Chame essa função membro para desenhar uma imagem de uma lista de imagens.

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
Um ponteiro para uma estrutura IMAGELISTDRAWPARAMS que contém informações sobre a operação de desenho.

pDC
Um ponteiro para o contexto do dispositivo de destino. Você deve excluir esse objeto CDC quando terminar de usá-lo.

nImage
O índice de base zero da imagem a ser desenhada.

pt
Uma estrutura POINT que contém as coordenadas x e y em que a imagem será desenhada.

sz
Uma estrutura SIZE que indica o tamanho da imagem a ser desenhada.

ptOrigin
Uma estrutura POINT que contém as coordenadas x e y especificando o canto superior esquerdo da operação de desenho em relação à própria imagem. Os pixels da imagem à esquerda da coordenada x e acima da coordenada y não são desenhados.

fStyle
Sinalizador especificando o estilo do desenho e, opcionalmente, a imagem de sobreposição. Consulte a seção Comentários para obter informações sobre a imagem de sobreposição. A implementação padrão do MFC ILD_NORMAL desenha a imagem usando a cor da tela de fundo para a lista de imagens. Se a cor da tela de fundo for o valor CLR_NONE, a imagem será desenhada de forma transparente usando uma máscara.

Outros estilos possíveis estão descritos sob o membro fStyle da estrutura IMAGELISTDRAWPARAMS.

dwRop
Valor que especifica um código da operação de varredura. Esses códigos definem como os dados de cor do retângulo de origem serão combinados com os dados de cor do retângulo de destino para alcançar a cor final. A implementação padrão do MFC SRCCOPY copia o retângulo de origem diretamente para o retângulo de destino. Esse parâmetro será ignorado se o parâmetro fStyle não incluir o sinalizador ILD_ROP.

Outros valores possíveis estão descritos sob o membro dwRop da estrutura IMAGELISTDRAWPARAMS.

rgbBack
A cor da tela de fundo da imagem, por padrão CLR_DEFAULT. Esse parâmetro pode ser um valor RGB definido pelo aplicativo ou um dos seguintes valores:

Valor	Significado
`CLR_DEFAULT`	Cor da tela de fundo padrão. A imagem é desenhada usando a cor da tela de fundo da lista de imagens.
`CLR_NONE`	Sem cor da tela de fundo. A imagem é desenhada de forma transparente.

rgbFore
Cor de primeiro plano da imagem, por padrão CLR_DEFAULT. Esse parâmetro pode ser um valor RGB definido pelo aplicativo ou um dos seguintes valores:

Valor	Significado
`CLR_DEFAULT`	Cor de primeiro plano padrão. A imagem é desenhada usando a cor de realce do sistema como a cor de primeiro plano.
`CLR_NONE`	Sem mistura de cores. A imagem é misturada com a cor do contexto do dispositivo de destino.

Esse parâmetro será usado somente se fStyle incluir o sinalizador ILD_BLEND25 ou ILD_BLEND50.

fState
Sinalizador especificando o estado do desenho. Esse membro pode conter um ou mais sinalizadores de estado da lista de imagens.

Frame
Afeta o comportamento de efeitos de saturação e combinação alfa.

Quando usado com ILS_SATURATE, esse membro contém o valor que é adicionado a cada componente de cor do tripleto RGB para cada pixel no ícone.

Quando usado com ILS_APLHA, esse membro mantém o valor para o canal alfa. Esse valor pode variar de 0 a 255, sendo 0 completamente transparente e 255 completamente opaco.

crEffect
Um valor COLORREF usado para efeitos de brilho e sombra.

Valor de retorno

TRUE se a imagem for desenhada com êxito; caso contrário FALSE.

Comentários

Use a primeira versão se quiser preencher a estrutura do Win32 por conta própria. Use a segunda versão se quiser aproveitar um ou mais argumentos padrão do MFC ou evitar o gerenciamento da estrutura.

Uma imagem de sobreposição é uma imagem desenhada na parte superior da imagem primária, especificada nesta função membro pelo parâmetro nImage. Desenhe uma máscara de sobreposição usando a função membro Draw com o índice baseado em um da máscara de sobreposição especificado usando a macro INDEXTOOVERLAYMASK.

Exemplo

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`

Chame essa função para encerrar uma operação de arrastar.

static void PASCAL EndDrag();

Comentários

Para iniciar uma operação de arrastar, use a função membro BeginDrag.

Exemplo

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`

Chame essa função para criar um ícone com base em uma imagem e sua máscara relacionada em uma lista de imagens.

HICON ExtractIcon(int nImage);

Parâmetros

nImage
Índice de base zero da imagem.

Valor de retorno

Identificador do ícone se tiver êxito; caso contrário, NULL.

Comentários

Esse método depende do comportamento da macro ImageList_ExtractIcon para criar o ícone. Consulte a macro ImageList_ExtractIcon para obter mais informações sobre criação e limpeza de ícones.

Exemplo

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`

Retorna um ponteiro para um objeto CImageList quando dado um identificador para uma lista de imagens.

static CImageList* PASCAL FromHandle(HIMAGELIST hImageList);

Parâmetros

hImageList
Especifica a lista de imagens.

Valor de retorno

Um ponteiro para um objeto CImageList se tiver êxito; caso contrário, NULL.

Comentários

Se CImageList não estiver anexado ao identificador, um objeto temporário CImageList será criado e anexado. Esse objeto temporário CImageList é válido somente até a próxima vez que o aplicativo tiver tempo ocioso em seu loop de eventos, momento em que todos os objetos temporários são excluídos.

Exemplo

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`

Retorna um ponteiro para um objeto CImageList quando dado um identificador para uma lista de imagens.

static CImageList* PASCAL FromHandlePermanent(HIMAGELIST hImageList);

Parâmetros

hImageList
Especifica a lista de imagens.

Valor de retorno

Um ponteiro para um objeto CImageList se tiver êxito; caso contrário, NULL.

Comentários

Se um objeto CImageList não estiver anexado ao identificador, NULL será retornado.

Exemplo

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`

Chame essa função para recuperar a cor da tela de fundo atual de uma lista de imagens.

COLORREF GetBkColor() const;

Valor de retorno

O valor de cores RGB da cor da tela de fundo do objeto CImageList.

Exemplo

Confira o exemplo de CImageList::SetBkColor.

`CImageList::GetDragImage`

Obtém a lista de imagens temporárias usada para arrastar.

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

Parâmetros

lpPoint
Endereço de uma estrutura POINT que recebe a posição de arrastar atual.

lpPointHotSpot
Endereço de uma estrutura POINT que recebe o deslocamento da imagem de arrasto em relação à posição de arrastar.

Valor de retorno

Se tiver êxito, um ponteiro para a lista de imagens temporárias usada para arrastar; caso contrário, NULL.

`CImageList::GetImageCount`

Chame essa função para recuperar o número de imagens em uma lista de imagens.

int GetImageCount() const;

Valor de retorno

O número de imagens.

Exemplo

Confira o exemplo de CImageList::ExtractIcon.

`CImageList::GetImageInfo`

Chamar essa função para recuperar informações sobre uma imagem.

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

Parâmetros

nImage
Índice de base zero da imagem.

pImageInfo
Ponteiro para uma estrutura IMAGEINFO que recebe informações sobre a imagem. As informações nessa estrutura podem ser usadas para manipular diretamente os bitmaps para a imagem.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A estrutura IMAGEINFO contém informações sobre uma imagem em uma lista de imagens.

`CImageList::GetSafeHandle`

Chame essa função para recuperar o membro de dados m_hImageList.

HIMAGELIST GetSafeHandle() const;

Valor de retorno

Um identificador para a lista de imagens anexadas; caso contrário NULL, se nenhum objeto estiver anexado.

Exemplo

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

`CImageList::m_hImageList`

Um identificador da lista de imagens anexada a esse objeto.

HIMAGELIST m_hImageList;

Comentários

Esse membro de dados m_hImageList é uma variável pública do tipo HIMAGELIST.

Exemplo

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

`CImageList::operator HIMAGELIST`

Use esse operador para obter o identificador anexado do objeto CImageList.

operator HIMAGELIST() const;

Valor de retorno

Se tiver êxito, um identificador para a lista de imagens representada pelo objeto CImageList; caso contrário, NULL.

Comentários

Esse operador é um operador de conversão, que dá suporte ao uso direto de um objeto HIMAGELIST.

Exemplo

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

`CImageList::Read`

Chame essa função para ler uma lista de imagens de um arquivo.

BOOL Read(CArchive* pArchive);

Parâmetros

pArchive
Um ponteiro para um objeto CArchive do qual a lista de imagens deve ser lida.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

// 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`

Chame essa função para remover uma imagem de um objeto da lista de imagens.

BOOL Remove(int nImage);

Parâmetros

nImage
Índice baseado em zero da imagem a ser removida.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Todos os itens após nImage agora se movem para baixo em uma posição. Por exemplo, se uma lista de imagens contiver dois itens, excluir o primeiro item fará com que o item restante esteja agora na primeira posição. nImage=0 para o item na primeira posição.

Exemplo

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

`CImageList::Replace`

Chame essa função para substituir uma imagem em uma lista de imagens por uma nova imagem.

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

int Replace(
    int nImage,
    HICON hIcon);

Parâmetros

nImage
Índice de base zero da imagem a ser substituída.

pbmImage
Um ponteiro para o bitmap que contém a imagem.

pbmMask
Um ponteiro para o bitmap que contém a máscara. Se nenhuma máscara for usada com a lista de imagens, esse parâmetro será ignorado.

hIcon
Um identificador do ícone que contém o bitmap e a máscara para a nova imagem.

Valor de retorno

A versão retornando BOOL retorna diferente de zero se tiver êxito; caso contrário, 0.

A versão retornando int retorna o índice baseado em zero da imagem se tiver êxito; caso contrário, 1.

Comentários

Chame essa função membro depois de chamar SetImageCount para atribuir as novas imagens válidas aos números de índice da imagem do espaço reservado.

Exemplo

Confira o exemplo de CImageList::SetImageCount.

`CImageList::SetBkColor`

Chame essa função para definir a cor da tela de fundo para uma lista de imagens.

COLORREF SetBkColor(COLORREF cr);

Parâmetros

cr
Cor da tela de fundo a ser definida. Pode ser CLR_NONE. Nesse caso, as imagens são desenhadas de forma transparente usando a máscara.

Valor de retorno

A cor da tela de fundo anterior, se bem-sucedida; caso contrário, CLR_NONE.

Exemplo

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

`CImageList::SetDragCursorImage`

Cria uma nova imagem de arrasto combinando a imagem fornecida (normalmente uma imagem de cursor do mouse) com a imagem de arrasto atual.

BOOL SetDragCursorImage(
    int nDrag,
    CPoint ptHotSpot);

Parâmetros

nDrag
Índice da nova imagem a ser combinada com a imagem de arrasto.

ptHotSpot
Posição do ponto de acesso na nova imagem.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Como as funções de arrastar usam a nova imagem durante uma operação de arrastar, você deve usar a função ShowCursor do Windows para ocultar o cursor real do mouse depois de chamar CImageList::SetDragCursorImage. Caso contrário, o sistema pode parecer ter dois cursores do mouse durante a operação de arrastar.

`CImageList::SetImageCount`

Chame essa função membro para redefinir o número de imagens em um objeto CImageList.

BOOL SetImageCount(UINT uNewCount);

Parâmetros

uNewCount
O valor que especifica o novo número total de imagens na lista de imagens.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Se você chamar essa função membro para aumentar o número de imagens na lista de imagens, chame Replace para cada imagem adicional para atribuir os novos índices a imagens válidas. Se você não atribuir os índices a imagens válidas, as operações de desenho que criam as novas imagens serão imprevisíveis.

Se você diminuir o tamanho de uma lista de imagens usando essa função, as imagens truncadas serão liberadas.

Exemplo

// 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`

Chame essa função para adicionar o índice baseado em zero de uma imagem à lista de imagens a serem usadas como máscaras de sobreposição.

BOOL SetOverlayImage(
    int nImage,
    int nOverlay);

Parâmetros

nImage
Índice baseado em zero da imagem a ser usada como uma máscara de sobreposição.

nOverlay
Índice baseado em um da máscara de sobreposição.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Até quatro índices podem ser adicionados à lista.

Uma máscara de sobreposição é uma imagem desenhada de forma transparente sobre outra imagem. Desenhe uma máscara de sobreposição sobre uma imagem usando a função membro CImageList::Draw com o índice baseado em um da máscara de sobreposição especificado usando a macro INDEXTOOVERLAYMASK.

Exemplo

// 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`

Chame essa função para gravar um objeto da lista de imagens em um arquivo.

BOOL Write(CArchive* pArchive);

Parâmetros

pArchive
Um ponteiro para um objeto CArchive no qual a lista de imagens deve ser armazenada.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Exemplo

// 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);

Confira também

Classe CObject
Gráfico da hierarquia
Classe CListCtrl
Classe CTabCtrl

Compartilhar via

Classe CImageList

Sintaxe

Membros

Construtores públicos

Métodos públicos

Operadores públicos

Membros de Dados Públicos

Comentários

Hierarquia de herança

Requisitos

CImageList::Add

Parâmetros

Valor de retorno

Comentários

Exemplo

CImageList::Attach

Parâmetros

Valor de retorno

Exemplo

CImageList::BeginDrag

Parâmetros

Valor de retorno

Comentários

Exemplo

CImageList::CImageList

CImageList::Copy

Parâmetros

Valor de retorno

Exemplo

CImageList::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CImageList::DeleteImageList

Valor de retorno

Exemplo

CImageList::DeleteTempMap

Exemplo

CImageList::Detach

Valor de retorno

Comentários

Exemplo

CImageList::DragEnter

Parâmetros

Valor de retorno

Comentários

Exemplo

CImageList::DragLeave

Parâmetros

Valor de retorno

Exemplo

CImageList::DragMove

Parâmetros

Valor de retorno

Comentários

Exemplo

CImageList::DragShowNolock

Parâmetros

Valor de retorno

Comentários

CImageList::Draw

Parâmetros

Valor de retorno

Exemplo

CImageList::DrawEx

Parâmetros

Valor de retorno

Comentários

Exemplo

CImageList::DrawIndirect

Parâmetros

Valor de retorno

Comentários

Exemplo

CImageList::EndDrag

Comentários

Exemplo

CImageList::ExtractIcon

Classe `CImageList`

`CImageList::Add`

`CImageList::Attach`

`CImageList::BeginDrag`

`CImageList::CImageList`

`CImageList::Copy`

`CImageList::Create`

`CImageList::DeleteImageList`

`CImageList::DeleteTempMap`

`CImageList::Detach`

`CImageList::DragEnter`

`CImageList::DragLeave`

`CImageList::DragMove`

`CImageList::DragShowNolock`

`CImageList::Draw`

`CImageList::DrawEx`

`CImageList::DrawIndirect`

`CImageList::EndDrag`

`CImageList::ExtractIcon`

`CImageList::FromHandle`

`CImageList::FromHandlePermanent`

`CImageList::GetBkColor`

`CImageList::GetDragImage`

`CImageList::GetImageCount`

`CImageList::GetImageInfo`

`CImageList::GetSafeHandle`

`CImageList::m_hImageList`

`CImageList::operator HIMAGELIST`

`CImageList::Read`

`CImageList::Remove`

`CImageList::Replace`

`CImageList::SetBkColor`

`CImageList::SetDragCursorImage`

`CImageList::SetImageCount`

`CImageList::SetOverlayImage`