Compartir a través de


Función LoadImageA (winuser.h)

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)

Consulte también

Conceptual

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

Otros recursos

Referencia

Recursos