Classe CBitmap

Encapsula um bitmap de GDI (Graphics Device Interface) do Windows e fornece funções de membro para manipular o bitmap.

Sintaxe

class CBitmap : public CGdiObject

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
CBitmap::CreateBitmap	Inicializa o objeto com um bitmap de memória dependente do dispositivo, que tem um padrão de largura, altura e bit especificado.
CBitmap::CreateBitmapIndirect	Inicializa o objeto com um bitmap com o padrão de largura, altura e bit (se especificado) fornecido em uma estrutura BITMAP.
CBitmap::CreateCompatibleBitmap	Inicializa o objeto com um bitmap para que seja compatível com um dispositivo especificado.
CBitmap::CreateDiscardableBitmap	Inicializa o objeto com um bitmap descartável que seja compatível com um dispositivo especificado.
CBitmap::FromHandle	Retorna um ponteiro para um objeto CBitmap quando é determinado um identificador para um bitmap HBITMAP do Windows.
CBitmap::GetBitmap	Preenche uma estrutura BITMAP com informações sobre o bitmap.
CBitmap::GetBitmapBits	Copia os bits do bitmap especificado no buffer especificado.
CBitmap::GetBitmapDimension	Retorna a largura e a altura do bitmap. Presume-se que a altura e a largura foram definidas anteriormente pela função de membro SetBitmapDimension.
CBitmap::LoadBitmap	Inicializa o objeto carregando um recurso de bitmap nomeado do arquivo executável do aplicativo e anexando o bitmap ao objeto.
CBitmap::LoadMappedBitmap	Carrega um bitmap e mapeia as cores de acordo com as cores atuais do sistema.
CBitmap::LoadOEMBitmap	Inicializa o objeto carregando um bitmap predefinido do Windows e anexando o bitmap ao objeto.
CBitmap::SetBitmapBits	Define os bits de um bitmap para os valores de bit especificados.
CBitmap::SetBitmapDimension	Atribui uma largura e uma altura a um bitmap em unidades de 0,1 milímetro.

Operadores públicos

Nome	Descrição
CBitmap::operator HBITMAP	Retorna o identificador do Windows anexado ao objeto CBitmap.

Comentários

Para usar um objeto CBitmap, crie o objeto, anexe um identificador de bitmap a ele com uma das funções de membro de inicialização e chame as funções de membro do objeto.

Para obter mais informações sobre como usar objetos gráficos, como CBitmap, confira Objetos Gráficos.

Hierarquia de herança

CObject

CGdiObject

CBitmap

Requisitos

Cabeçalho: afxwin.h

CBitmap::CBitmap

Constrói um objeto CBitmap.

CBitmap();

Comentários

O objeto resultante deve ser inicializado com uma das funções de membro de inicialização.

CBitmap::CreateBitmap

Inicializa um bitmap de memória dependente do dispositivo, que tem um padrão de largura, altura e bit especificado.

BOOL CreateBitmap(
    int nWidth,
    int nHeight,
    UINT nPlanes,
    UINT nBitcount,
    const void* lpBits);

Parâmetros

nWidth
Especifica a largura (em pixels) do bitmap.

nHeight
Especifica a altura (em pixels) do bitmap.

nPlanes
Especifica o número de painéis coloridos no bitmap.

nBitcount
Especifica o número de bits coloridos por pixel de exibição.

lpBits
Aponta para uma matriz de bytes que contém os valores de bitmap iniciais. Se for NULL, o novo bitmap será deixado sem inicialização.

Valor de retorno

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

Comentários

Para um bitmap colorido, o parâmetro nPlanes ou nBitcount deve ser definido como 1. Se ambos os parâmetros forem definidos como 1, CreateBitmap criará um bitmap monocromático.

Embora um bitmap não possa ser selecionado diretamente para um dispositivo de exibição, ele pode ser selecionado como o bitmap atual para um "contexto de dispositivo de memória" usando CDC::SelectObject e copiado para qualquer contexto de dispositivo compatível usando a função CDC::BitBlt.

Quando terminar com o objeto CBitmap criado pela função CreateBitmap, primeiro selecione o bitmap fora do contexto de dispositivo e exclua o objeto CBitmap.

Para obter mais informações, confira a descrição do campo bmBits na estrutura BITMAP. A estrutura BITMAP é descrita na função de membro CBitmap::CreateBitmapIndirect.

CBitmap::CreateBitmapIndirect

Inicializa um bitmap que tem o padrão de largura, altura e bit (se especificado) fornecido na estrutura apontada por lpBitmap.

BOOL CreateBitmapIndirect(LPBITMAP lpBitmap);

Parâmetros

lpBitmap
Aponta para uma estrutura BITMAP que contém informações sobre o bitmap.

Valor de retorno

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

Comentários

Embora um bitmap não possa ser selecionado diretamente para um dispositivo de exibição, ele pode ser selecionado como o bitmap atual para um contexto de dispositivo de memória usando CDC::SelectObject e copiado para qualquer contexto de dispositivo compatível usando a função CDC::BitBlt ou CDC::StretchBlt. (A função CDC::PatBlt pode copiar o bitmap para o pincel atual diretamente no contexto de dispositivo de exibição.)

Se a estrutura BITMAP apontada pelo parâmetro lpBitmap tiver sido preenchida usando a função GetObject, os bits do bitmap não serão especificados e o bitmap não será inicializado. Para inicializar o bitmap, um aplicativo pode usar uma função, como CDC::BitBlt ou SetDIBits, para copiar os bits do bitmap identificado pelo primeiro parâmetro de CGdiObject::GetObject para o bitmap criado por CreateBitmapIndirect.

Quando terminar com o objeto CBitmap criado com a função CreateBitmapIndirect, primeiro selecione o bitmap fora do contexto de dispositivo e exclua o objeto CBitmap.

CBitmap::CreateCompatibleBitmap

Inicializa um bitmap compatível com o dispositivo especificado por pDC.

BOOL CreateCompatibleBitmap(
    CDC* pDC,
    int nWidth,
    int nHeight);

Parâmetros

pDC
Especifica o contexto de dispositivo.

nWidth
Especifica a largura (em pixels) do bitmap.

nHeight
Especifica a altura (em pixels) do bitmap.

Valor de retorno

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

Comentários

O bitmap tem o mesmo número de painéis coloridos ou o mesmo formato de bits por pixel que o contexto de dispositivo especificado. Pode ser selecionado como o bitmap atual para qualquer dispositivo de memória compatível com o especificado por pDC.

Se pDC for um contexto de dispositivo de memória, o bitmap retornado terá o mesmo formato que o bitmap selecionado no momento no contexto desse dispositivo. Um "contexto de dispositivo de memória" é um bloco de memória que representa uma superfície de exibição. Ele pode ser usado para preparar imagens na memória antes de copiá-las para a superfície de exibição real do dispositivo compatível.

Quando um contexto de dispositivo de memória é criado, o GDI seleciona automaticamente um bitmap de estoque monocromático para ele.

Como um contexto de dispositivo de memória de cor pode ter bitmaps coloridos ou monocromáticos selecionados, o formato do bitmap retornado pela função CreateCompatibleBitmap nem sempre é o mesmo. No entanto, o formato de um bitmap compatível para um contexto de dispositivo sem memória está sempre no formato do dispositivo.

Quando terminar com o objeto CBitmap criado com a função CreateCompatibleBitmap, primeiro selecione o bitmap fora do contexto de dispositivo e exclua o objeto CBitmap.

CBitmap::CreateDiscardableBitmap

Inicializa um bitmap descartável, compatível com o contexto de dispositivo identificado por pDC.

BOOL CreateDiscardableBitmap(
    CDC* pDC,
    int nWidth,
    int nHeight);

Parâmetros

pDC
Especifica um contexto de dispositivo.

nWidth
Especifica a largura (em bits) do bitmap.

nHeight
Especifica a altura (em bits) do bitmap.

Valor de retorno

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

Comentários

O bitmap tem o mesmo número de painéis coloridos ou o mesmo formato de bits por pixel que o contexto de dispositivo especificado. Um aplicativo pode selecionar esse bitmap como o bitmap atual para um dispositivo de memória compatível com o especificado por pDC.

O Windows só poderá descartar um bitmap criado por essa função, se ele não foi selecionado por um aplicativo em um contexto de exibição. Se o Windows descartar o bitmap quando não estiver selecionado e o aplicativo tentar selecioná-lo mais tarde, a função CDC::SelectObject retornará NULL.

Quando terminar com o objeto CBitmap criado com a função CreateDiscardableBitmap, primeiro selecione o bitmap fora do contexto de dispositivo e exclua o objeto CBitmap.

CBitmap::FromHandle

Retorna um ponteiro para um objeto CBitmap quando é determinado um identificador para um bitmap do Windows GDI.

static CBitmap* PASCAL FromHandle(HBITMAP hBitmap);

Parâmetros

hBitmap
Especifica um bitmap do Windows GDI.

Valor de retorno

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

Comentários

Se um objeto CBitmap não estiver anexado ao identificador, um objeto temporário CBitmap será criado e anexado. Esse objeto temporário CBitmap é 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 gráficos temporários são excluídos. Outra maneira de dizer isso é que o objeto temporário é válido somente durante o processamento de uma mensagem de janela.

CBitmap::GetBitmap

Recupera as propriedades da imagem para o bitmap anexado.

int GetBitmap(BITMAP* pBitMap);

Parâmetros

pBitMap
Ponteiro para uma estrutura BITMAP que receberá as propriedades da imagem. Esse parâmetro não deve ser NULL.

Valor de retorno

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

Comentários

CBitmap::GetBitmapBits

Copia o padrão de bit do bitmap anexado no buffer especificado.

DWORD GetBitmapBits(
    DWORD dwCount,
    LPVOID lpBits) const;

Parâmetros

dwCount
O número de bytes a serem copiados no buffer.

lpBits
Ponteiro para o buffer que receberá o bitmap.

Valor de retorno

O número de bytes copiados para o buffer, se o método tiver êxito. Caso contrário, 0.

Comentários

Use CBitmap::GetBitmap para determinar o tamanho do buffer necessário.

CBitmap::GetBitmapDimension

Retorna a largura e a altura do bitmap.

CSize GetBitmapDimension() const;

Valor de retorno

A largura e a altura do bitmap, medidas em unidades de 0,1 milímetro. A altura está no membro cy do objeto CSize e a largura está no membro cx. Se a largura e a altura do bitmap não tiverem sido definidas usando SetBitmapDimension, o valor retornado será 0.

Comentários

Presume-se que a altura e a largura foram definidas anteriormente usando a função de membro SetBitmapDimension.

CBitmap::LoadBitmap

Carrega o recurso de bitmap nomeado por lpszResourceName ou identificado pelo número de ID no nIDResource a partir do arquivo executável do aplicativo.

BOOL LoadBitmap(LPCTSTR lpszResourceName);
BOOL LoadBitmap(UINT nIDResource);

Parâmetros

lpszResourceName
Aponta para uma cadeia de caracteres terminada em nulo que contém o nome do recurso de bitmap.

nIDResource
Especifica o número da ID do recurso de bitmap.

Valor de retorno

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

Comentários

O bitmap carregado é anexado ao objeto CBitmap.

Se o bitmap identificado por lpszResourceName não existir ou se não houver memória suficiente para carregar o bitmap, a função retornará 0.

Você pode usar a função CGdiObject::DeleteObject para excluir o bitmap carregado pela função LoadBitmap ou o destruidor CBitmap excluirá o objeto para você.

Cuidado

Antes de excluir o objeto, verifique se ele não está selecionado em um contexto de dispositivo.

Os bitmaps a seguir foram adicionados ao Windows versão 3.1 e posteriores:

OBM_UPARRROWIOBM_DNARROWIOBM_RGARROWIOBM_LFARROWI

Esses bitmaps não são encontrados em drivers de dispositivo para Windows versão 3.0 e anteriores. Para obter uma lista completa de bitmaps e uma exibição da aparência, confira o SDK do Windows.

CBitmap::LoadMappedBitmap

Chame essa função de membro para carregar um bitmap e mapear as cores de acordo com as cores atuais do sistema.

BOOL LoadMappedBitmap(
    UINT nIDBitmap,
    UINT nFlags = 0,
    LPCOLORMAP lpColorMap = NULL,
    int nMapSize = 0);

Parâmetros

nIDBitmap
A ID de recursos de bitmap.

nFlags
Um sinalizador de um bitmap. Pode ser zero ou CMB_MASKED.

lpColorMap
Um ponteiro para uma estrutura COLORMAP que contém as informações sobre cores necessárias para mapear os bitmaps. Se esse parâmetro for NULL, a função usará o mapa de cores padrão.

nMapSize
O número de mapas de cores apontados por lpColorMap.

Valor de retorno

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

Comentários

Por padrão, LoadMappedBitmap mapeará as cores mais comuns em glifos de botão.

Para obter informações sobre como criar um bitmap mapeado, confira a função do Windows CreateMappedBitmap e a estrutura COLORMAP no SDK do Windows.

CBitmap::LoadOEMBitmap

Carrega um bitmap predefinido usado pelo Windows.

BOOL LoadOEMBitmap(UINT nIDBitmap);

Parâmetros

nIDBitmap
Número de ID do bitmap predefinido do Windows. Os valores possíveis são listados abaixo de WINDOWS.H:

OBM_BTNCORNERS
OBM_BTSIZE
OBM_CHECK
OBM_CHECKBOXES
OBM_CLOSE
OBM_COMBO
OBM_DNARROW
OBM_DNARROWD
OBM_DNARROWI
OBM_LFARROW
OBM_LFARROWD
OBM_LFARROWI

OBM_MNARROW
OBM_OLD_CLOSE
OBM_OLD_DNARROW
OBM_OLD_LFARROW
OBM_OLD_REDUCE
OBM_OLD_RESTORE
OBM_OLD_RGARROW
OBM_OLD_UPARROW
OBM_OLD_ZOOM
OBM_REDUCE
OBM_REDUCED

OBM_RESTORE
OBM_RESTORED
OBM_RGARROW
OBM_RGARROWD
OBM_RGARROWI
OBM_SIZE
OBM_UPARROW
OBM_UPARROW
OBM_UPARROWD
OBM_ZOOM
OBM_ZOOMD

Valor de retorno

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

Comentários

Os nomes de bitmap que começam com OBM_OLD representam os bitmaps usados pelas versões do Windows anteriores a 3.0.

Observe que a constante OEMRESOURCE deve ser definida, antes de incluir WINDOWS.H, para usar qualquer uma das constantes OBM_.

CBitmap::operator HBITMAP

Use esse operador para obter o identificador GDI do Windows anexado do objeto CBitmap.

operator HBITMAP() const;

Valor de retorno

Se tiver êxito, um identificador para o objeto GDI do Windows representado pelo objeto CBitmap; caso contrário, NULL.

Comentários

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

Para obter mais informações sobre como usar objetos gráficos, confira Objetos Gráficos no SDK do Windows.

CBitmap::SetBitmapBits

Define os bits de um bitmap para os valores de bit especificados por lpBits.

DWORD SetBitmapBits(
    DWORD dwCount,
    const void* lpBits);

Parâmetros

dwCount
Especifica o número de bytes para o qual lpBitsapontou.

lpBits
Aponta para a matriz BYTE que contém os valores de pixel a serem copiados para o objeto CBitmap. Para que o bitmap possa renderizar a imagem corretamente, os valores devem ser formatados de acordo com os valores de altura, largura e profundidade de cor especificados quando a instância CBitmap foi criada. Para obter mais informações, consulte CBitmap::CreateBitmap.

Valor de retorno

O número de bytes usados na configuração dos bits de bitmap. 0, se a função falhar.

CBitmap::SetBitmapDimension

Atribui uma largura e uma altura a um bitmap em unidades de 0,1 milímetro.

CSize SetBitmapDimension(
    int nWidth,
    int nHeight);

Parâmetros

nWidth
Especifica a largura do bitmap (em unidades de 0,1 milímetro).

nHeight
Especifica a altura do bitmap (em unidades de 0,1 milímetro).

Valor de retorno

As dimensões anteriores do bitmap. A altura está na variável de membro cy do objeto CSize e a largura está na variável de membro cx.

Comentários

O GDI não usa esses valores, exceto para devolvê-los quando um aplicativo chama a função de membro GetBitmapDimension.

Confira também

MDI de exemplo do MFC
Classe CGdiObject
Gráfico da hierarquia