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 controlada por la llamada de función del sistema de WinMainy 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 de

Imagen que se va a cargar.

Si el parámetro hInst no esNULL y el parámetro fuLoad omite LR_LOADFROMFILE, nombre 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 nombre nombre parámetro 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 siguientes prefijos:

Prefijo	Significado
OBM_	Mapas de bits de OEM. Use la macro MAKEINTRESOURCE para pasarlas.
OIC_	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 de , use la macro MAKEINTRESOURCE . Por ejemplo, para cargar el cursor de OCR_NORMAL, pase como parámetro nombre de , 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, nombre 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 siguientes valores:

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 valor de métrica del sistema SM_CXICON o SM_CXCURSOR 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 varios 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 de 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. Dk Gray, 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 en 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 colores 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 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 imágenes que tengan 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 del recurso solicitado, independientemente del tamaño solicitado.
LR_VGACOLOR 0x00000080	Usa colores VGA verdaderos.

Valor devuelto

Tipo: HANDLE de

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

Si se produce un error en la función, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Observaciones

Si IS_INTRESOURCE(nombre) es TRUE, 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 cargado 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
Mapa de bits	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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winuser.h (incluya Windows.h)
biblioteca de	User32.lib
DLL de	User32.dll
conjunto de API de	ext-ms-win-ntuser-gui-l1-1-0 (introducido en Windows 8)

Consulte también

conceptual de

copyImage

GetSystemMetrics

LoadBitmap

loadCursor

LoadIcon

otros recursos

de referencia de

recursos de