Função LoadImageW (winuser.h)

Artigo
02/01/2024

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

Sintaxe

HANDLE LoadImageW(
  [in, optional] HINSTANCE hInst,
  [in]           LPCWSTR   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)