Função LoadImageW (winuser.h)

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 de aplicativo exposto pela chamada de função do sistema 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, nome especificar o recurso de imagem no módulo hInst.

Se o recurso de imagem deve ser carregado pelo nome do módulo, o nome parâmetro 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 o ordinal da imagem 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 do Standard
IDC_	de cursores Standard

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 como o parâmetro de nome , 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, nome 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 ser um dos seguintes valores:

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 ser um ou mais 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 por 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 de 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 falhará ao 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 de VGA verdadeiras.

Valor de retorno

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.

Observações

Se IS_INTRESOURCE(nome) for VERDADEIRO, nome especificar o identificador inteiro do recurso fornecido. Caso contrário, ele será 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 de LR_SHARED, você poderá liberar sua memória associada chamando uma das funções na tabela a seguir.

Recurso	Função de versão
Mapa de bits	DeleteObject
Cursor	DestroyCursor
Ícone	DestroyIcon

 

O sistema exclui automaticamente esses recursos quando o processo que os criou termina; 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winuser.h (inclua Windows.h)
biblioteca	User32.lib
de DLL	User32.dll
conjunto de API	ext-ms-win-ntuser-gui-l1-1-0 (introduzido no Windows 8)

Consulte também

Conceitual

CopyImage

GetSystemMetrics

loadBitmap

LoadCursor

loadicon

outros recursos

de referência de

Recursos