Función LoadImageA (winuser.h)

Artículo
02/01/2024

Carga un icono, un cursor, un cursor animado o un mapa de bits.

Sintaxis

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

Identificador del módulo de un archivo DLL o ejecutable (.exe) que contiene la imagen que se va a cargar. Para obtener más información, vea GetModuleHandle. Tenga en cuenta que a partir de Windows de 32 bits, un identificador de instancia (HINSTANCE), como la instancia de aplicación que expone la llamada de función del sistema de WinMain y un identificador de módulo (HMODULE) son lo mismo.

Para cargar una imagen predefinida o un recurso independiente (icono, cursor o archivo de mapa de bits), establezca este parámetro en NULL.

[in] name

Tipo: LPCTSTR

Imagen que se va a cargar.

Si el parámetro hInst no es NULL y el parámetro fuLoad omite LR_LOADFROMFILE, name especifica el recurso de imagen en el módulo hInst .

Si el recurso de imagen se va a cargar por nombre desde el módulo, el parámetro name es un puntero a una cadena terminada en null que contiene el nombre del recurso de imagen.

Si el recurso de imagen se va a cargar mediante ordinal desde el módulo, use la macro MAKEINTRESOURCE para convertir el ordinal de imagen en un formulario que se pueda pasar a la función LoadImage .

Si el parámetro hInst es NULL y el parámetro fuLoad omite el valor de LR_LOADFROMFILE e incluye el LR_SHARED, el nombre especifica la imagen predefinida que se va a cargar.

Los identificadores de imagen predefinidos se definen en Winuser.h y tienen los prefijos siguientes:

Prefijo	Significado
OBM_	Mapas de bits oem. Use la macro MAKEINTRESOURCE para pasarlas.
OCI_	Iconos de OEM. Use la macro MAKEINTRESOURCE para pasarlas.
OCR_	Cursores oem. Use la macro MAKEINTRESOURCE para pasarlas.
IDI_	Iconos estándar
IDC_	Cursores estándar

Para pasar constantes de identificadores de imagen OEM a la función LoadImage , use la macro MAKEINTRESOURCE . Por ejemplo, para cargar el cursor de OCR_NORMAL , pase MAKEINTRESOURCE(OCR_NORMAL) como parámetro name , NULL como parámetro hInst y LR_SHARED como una de las marcas al parámetro fuLoad .

Si el parámetro hInst es NULL y el parámetro fuLoad incluye el valor de LR_LOADFROMFILE , name es el nombre del archivo que contiene el recurso independiente (icono, cursor o archivo de mapa de bits), por ejemplo, c:\myicon.ico.

Para obtener más información, vea la sección Comentarios a continuación.

[in] type

Tipo: UINT

Tipo de imagen que se va a cargar.

Este parámetro puede ser uno de los valores siguientes:

Valor	Significado
IMAGE_BITMAP	Carga un mapa de bits.
IMAGE_CURSOR	Carga un cursor.
IMAGE_ICON	Carga un icono.

[in] cx

Tipo: int

Ancho, en píxeles, del icono o cursor. Si este parámetro es cero y el parámetro fuLoad es LR_DEFAULTSIZE, la función usa el SM_CXICON o SM_CXCURSOR valor de métrica del sistema para establecer el ancho. Si este parámetro es cero y no se usa LR_DEFAULTSIZE, la función usa el ancho real del recurso.

[in] cy

Tipo: int

Alto, en píxeles, del icono o cursor. Si este parámetro es cero y el parámetro fuLoad es LR_DEFAULTSIZE, la función usa el SM_CYICON o SM_CYCURSOR valor de métrica del sistema para establecer el alto. Si este parámetro es cero y no se usa LR_DEFAULTSIZE, la función usa el alto real del recurso.

[in] fuLoad

Tipo: UINT

Este parámetro puede ser uno o más de los siguientes valores.

Valor	Significado
LR_CREATEDIBSECTION 0x00002000	Cuando el parámetro uType especifica IMAGE_BITMAP, hace que la función devuelva un mapa de bits de sección DIB en lugar de un mapa de bits compatible. Esta marca es útil para cargar un mapa de bits sin asignarlo a los colores del dispositivo de visualización.
LR_DEFAULTCOLOR 0x00000000	Marca predeterminada; no hace nada. Todo lo que significa es "no LR_MONOCHROME".
LR_DEFAULTSIZE 0x00000040	Usa el ancho o alto especificado por los valores de métrica del sistema para cursores o iconos, si los valores cxDesired o cyDesired se establecen en cero. Si no se especifica esta marca y cxDesired y cyDesired se establecen en cero, la función usa el tamaño real del recurso. Si el recurso contiene varias imágenes, la función usa el tamaño de la primera imagen.
LR_LOADFROMFILE 0x00000010	Carga la imagen independiente del archivo especificado por nombre (icono, cursor o archivo de mapa de bits).
LR_LOADMAP3DCOLORS 0x00001000	Busca en la tabla de colores la imagen y reemplaza los siguientes tonos de gris por el color 3D correspondiente. Gris Dk, RGB(128,128,128) con COLOR_3DSHADOW Gris, RGB(192,192,192) con COLOR_3DFACE Lt Gray, RGB(223,223,223) con COLOR_3DLIGHT No use esta opción si va a cargar un mapa de bits con una profundidad de color mayor que 8bpp.
LR_LOADTRANSPARENT 0x00000020	Recupera el valor de color del primer píxel de la imagen y reemplaza la entrada correspondiente de la tabla de colores por el color de ventana predeterminado (COLOR_WINDOW). Todos los píxeles de la imagen que usan esa entrada se convierten en el color predeterminado de la ventana. Este valor solo se aplica a las imágenes que tienen tablas de color correspondientes. No use esta opción si va a cargar un mapa de bits con una profundidad de color mayor que 8bpp. Si fuLoad incluye los valores de LR_LOADTRANSPARENT y LR_LOADMAP3DCOLORS , LR_LOADTRANSPARENT tiene prioridad. Sin embargo, la entrada de la tabla de colores se reemplaza por COLOR_3DFACE en lugar de COLOR_WINDOW.
LR_MONOCHROME 0x00000001	Carga la imagen en blanco y negro.
LR_SHARED 0x00008000	Comparte el identificador de imagen si la imagen se carga varias veces. Si no se establece LR_SHARED, una segunda llamada a LoadImage para el mismo recurso volverá a cargar la imagen y devolverá un identificador diferente. Al usar esta marca, el sistema destruirá el recurso cuando ya no sea necesario. No use LR_SHARED para las imágenes que tienen tamaños no estándar, que pueden cambiar después de la carga o que se cargan desde un archivo. Al cargar un icono o cursor del sistema, debe usar LR_SHARED o la función no podrá cargar el recurso. Esta función busca la primera imagen de la memoria caché con el nombre de recurso solicitado, independientemente del tamaño solicitado.
LR_VGACOLOR 0x00000080	Usa colores VGA verdaderos.

Valor devuelto

Tipo: HANDLE

Si la función se ejecuta correctamente, el valor devuelto es el identificador de la imagen recién cargada.

Si la función no se realiza correctamente, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Si IS_INTRESOURCE(name) es TRUE, el nombre especifica el identificador entero del recurso especificado. De lo contrario, es un puntero a una cadena terminada en null. Si el primer carácter de la cadena es un signo de libra (#), los caracteres restantes representan un número decimal que especifica el identificador entero del recurso. Por ejemplo, la cadena "#258" representa el identificador 258.

Cuando haya terminado de usar un mapa de bits, un cursor o un icono que cargó sin especificar la marca LR_SHARED , puede liberar su memoria asociada llamando a una de las funciones de la tabla siguiente.

Recurso	Función Release
Bitmap	DeleteObject
Cursor	DestroyCursor
Icono	Destroyicon

El sistema elimina automáticamente estos recursos cuando finaliza el proceso que los creó; Sin embargo, al llamar a la función adecuada, se ahorra memoria y se reduce el tamaño del conjunto de trabajo del proceso.

Ejemplos

Para obtener un ejemplo, vea Uso de clases de ventana.

Nota

El encabezado winuser.h define LoadImage como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluya Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-gui-l1-1-0 (introducido en Windows 8)