Função LoadImageA (winuser.h)

Carrega um ícone, cursor, cursor animado ou bitmap.

Sintaxe

HANDLE LoadImageA(
  [in, optional] HINSTANCE hInst,
  [in]           LPCSTR    name,
  [in]           UINT      type,
  [in]           int       cx,
  [in]           int       cy,
  [in]           UINT      fuLoad
);

Parâmetros

[in, optional] hInst

Tipo: HINSTANCE

Um identificador para o módulo de uma DLL ou executável (.exe) que contém a imagem a ser carregada. Para obter mais informações, consulte GetModuleHandle. Observe que, a partir do Windows de 32 bits, um identificador de instância (HINSTANCE), como o identificador de instância do aplicativo exposto pela chamada de função do sistema do WinMain e um identificador de módulo (HMODULE) são a mesma coisa.

Para carregar uma imagem predefinida ou um recurso autônomo (ícone, cursor ou arquivo bitmap), defina esse parâmetro como NULL.

[in] name

Tipo: LPCTSTR

A imagem a ser carregada.

Se o parâmetro hInst não for NULL e o parâmetro fuLoad omitir LR_LOADFROMFILE, name especificará o recurso de imagem no módulo hInst .

Se o recurso de imagem for carregado pelo nome do módulo, o parâmetro name será um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome do recurso de imagem.

Se o recurso de imagem for carregado por ordinal do módulo, use a macro MAKEINTRESOURCE para converter a imagem ordinal em um formulário que pode ser passado para a função LoadImage .

Se o parâmetro hInst for NULL e o parâmetro fuLoad omitir o valor LR_LOADFROMFILE e incluir o LR_SHARED, o nome especificará a imagem predefinida a ser carregada.

Os identificadores de imagem predefinidos são definidos em Winuser.h e têm os seguintes prefixos:

Prefixo Significado
OBM_ Bitmaps OEM. Use a macro MAKEINTRESOURCE para passá-las.
OIC_ Ícones OEM. Use a macro MAKEINTRESOURCE para passá-las.
OCR_ Cursores OEM. Use a macro MAKEINTRESOURCE para passá-las.
IDI_ Ícones padrão
IDC_ Cursores padrão

Para passar constantes de identificadores de imagem OEM para a função LoadImage , use a macro MAKEINTRESOURCE . Por exemplo, para carregar o cursor OCR_NORMAL , passe MAKEINTRESOURCE(OCR_NORMAL) como o parâmetro name , NULL como o parâmetro hInst e LR_SHARED como um dos sinalizadores para o parâmetro fuLoad .

Se o parâmetro hInst for NULL e o parâmetro fuLoad incluir o valor LR_LOADFROMFILE , name será o nome do arquivo que contém o recurso autônomo (ícone, cursor ou arquivo bitmap), por exemplo, c:\myicon.ico.

Para obter mais informações, consulte a seção Comentários abaixo.

[in] type

Tipo: UINT

O tipo de imagem a ser carregada.

Esse parâmetro pode usar um dos valores a seguir:

Valor Significado
IMAGE_BITMAP Carrega um bitmap.
IMAGE_CURSOR Carrega um cursor.
IMAGE_ICON Carrega um ícone.

[in] cx

Tipo: int

A largura, em pixels, do ícone ou cursor. Se esse parâmetro for zero e o parâmetro fuLoad for LR_DEFAULTSIZE, a função usará o valor de métrica do sistema SM_CXICON ou SM_CXCURSOR para definir a largura. Se esse parâmetro for zero e LR_DEFAULTSIZE não for usado, a função usará a largura real do recurso.

[in] cy

Tipo: int

A altura, em pixels, do ícone ou cursor. Se esse parâmetro for zero e o parâmetro fuLoad for LR_DEFAULTSIZE, a função usará o valor de métrica do sistema SM_CYICON ou SM_CYCURSOR para definir a altura. Se esse parâmetro for zero e LR_DEFAULTSIZE não for usado, a função usará a altura real do recurso.

[in] fuLoad

Tipo: UINT

Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
LR_CREATEDIBSECTION
0x00002000
Quando o parâmetro uType especifica IMAGE_BITMAP, faz com que a função retorne um bitmap de seção DIB em vez de um bitmap compatível. Esse sinalizador é útil para carregar um bitmap sem mapeá-lo para as cores do dispositivo de exibição.
LR_DEFAULTCOLOR
0x00000000
O sinalizador padrão; não faz nada. Tudo o que significa é "não LR_MONOCHROME".
LR_DEFAULTSIZE
0x00000040
Usa a largura ou a altura especificada pelos valores de métrica do sistema para cursores ou ícones, se os valores cxDesired ou cyDesired forem definidos como zero. Se esse sinalizador não for especificado e cxDesired e cyDesired forem definidos como zero, a função usará o tamanho real do recurso. Se o recurso contiver várias imagens, a função usará o tamanho da primeira imagem.
LR_LOADFROMFILE
0x00000010
Carrega a imagem autônoma do arquivo especificado pelo nome (ícone, cursor ou arquivo bitmap).
LR_LOADMAP3DCOLORS
0x00001000
Pesquisa a tabela de cores da imagem e substitui os seguintes tons de cinza pela cor 3D correspondente.
  • Dk Gray, RGB(128.128.128) com COLOR_3DSHADOW
  • Cinza, RGB(192.192.192) com COLOR_3DFACE
  • Lt Gray, RGB(223.223.223) com COLOR_3DLIGHT
Não use essa opção se você estiver carregando um bitmap com uma profundidade de cor maior que 8bpp.
LR_LOADTRANSPARENT
0x00000020
Recupera o valor de cor do primeiro pixel na imagem e substitui a entrada correspondente na tabela de cores pela cor da janela padrão (COLOR_WINDOW). Todos os pixels na imagem que usam essa entrada se tornam a cor da janela padrão. Esse valor se aplica somente a imagens que têm tabelas de cores correspondentes.

Não use essa opção se você estiver carregando um bitmap com uma profundidade de cor maior que 8bpp.

Se fuLoad incluir os valores LR_LOADTRANSPARENT e LR_LOADMAP3DCOLORS , LR_LOADTRANSPARENT terá precedência. No entanto, a entrada da tabela de cores é substituída por COLOR_3DFACE em vez de COLOR_WINDOW.

LR_MONOCHROME
0x00000001
Carrega a imagem em preto e branco.
LR_SHARED
0x00008000
Compartilhará o identificador da imagem se a imagem for carregada várias vezes. Se LR_SHARED não estiver definido, uma segunda chamada para LoadImage para o mesmo recurso carregará a imagem novamente e retornará um identificador diferente.

Quando você usar esse sinalizador, o sistema destruirá o recurso quando ele não for mais necessário.

Não use LR_SHARED para imagens que têm tamanhos não padrão, que podem ser alteradas após o carregamento ou carregadas de um arquivo.

Ao carregar um ícone ou cursor do sistema, você deve usar LR_SHARED ou a função não carregará o recurso.

Essa função localiza a primeira imagem no cache com o nome do recurso solicitado, independentemente do tamanho solicitado.

LR_VGACOLOR
0x00000080
Usa cores VGA verdadeiras.

Retornar valor

Tipo: HANDLE

Se a função for bem-sucedida, o valor retornado será o identificador da imagem recém-carregada.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Se IS_INTRESOURCE(name) for TRUE, o nome especificará o identificador inteiro do recurso fornecido. Caso contrário, ele é um ponteiro para uma cadeia de caracteres terminada em nulo. Se o primeiro caractere da cadeia de caracteres for um sinal de libra (#), os caracteres restantes representarão um número decimal que especifica o identificador inteiro do recurso. Por exemplo, a cadeia de caracteres "#258" representa o identificador 258.

Quando terminar de usar um bitmap, cursor ou ícone carregado sem especificar o sinalizador LR_SHARED , você poderá liberar sua memória associada chamando uma das funções na tabela a seguir.

Recurso Função Release
Bitmap DeleteObject
Cursor DestroyCursor
ícone Destroyicon
 

O sistema exclui automaticamente esses recursos quando o processo que os criou é encerrado; no entanto, chamar a função apropriada salva memória e diminui o tamanho do conjunto de trabalho do processo.

Exemplos

Para obter um exemplo, consulte Usando classes de janela.

Observação

O cabeçalho winuser.h define LoadImage como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winuser.h (inclua Windows.h)
Biblioteca User32.lib
DLL User32.dll
Conjunto de APIs ext-ms-win-ntuser-gui-l1-1-0 (introduzido no Windows 8)

Confira também

Conceitual

CopyImage

GetSystemMetrics

Loadbitmap

Loadcursor

Loadicon

Outros recursos

Referência

Recursos