LoadImageA 函式 (winuser.h)

  • 發行項

載入圖示、游標、動畫游標或點陣圖。

語法

HANDLE LoadImageA(
  [in, optional] HINSTANCE hInst,
  [in]           LPCSTR    name,
  [in]           UINT      type,
  [in]           int       cx,
  [in]           int       cy,
  [in]           UINT      fuLoad
);

參數

[in, optional] hInst

類型： HINSTANCE

DLL 或可執行檔 (.exe) 模組的句柄，其中包含要載入的映射。 如需詳細資訊，請參閱 GetModuleHandle。 請注意，從 32 位 Windows 起，實例句柄 (HINSTANCE) ，例如 WinMain 系統函式呼叫所公開的應用程式實例句柄，以及模組句柄 (HMODULE) 相同。

若要載入預先定義的影像或獨立資源 (圖示、游標或位圖檔案) ，請將此參數設定為 NULL。

[in] name

類型： LPCTSTR

要載入的映像。

如果 hInst 參數不是 NULL ，且 fuLoad 參數省略 LR_LOADFROMFILE， 則 name 會指定 hInst 模組中的映像資源。

如果要依名稱從模組載入映像資源， name 參數是包含映像資源名稱之 Null 終止字串的指標。

如果要以序數從模組載入影像資源，請使用 MAKEINTRESOURCE 宏，將影像序數轉換成可傳遞至 LoadImage 函式的表單。

如果 hInst 參數為 NULL ，且 fuLoad 參數省略 LR_LOADFROMFILE 值， 則名稱 會指定要載入的預先定義影像。

預先定義的影像標識碼定義於 Winuser.h 中，並具有下列前置詞：

前置詞 意義
OBM_ OEM 位圖。 使用 MAKEINTRESOURCE 宏來傳遞這些宏。
OIC_ OEM 圖示。 使用 MAKEINTRESOURCE 宏來傳遞這些宏。
Ocr_ OEM 數據指標。 使用 MAKEINTRESOURCE 宏來傳遞這些宏。
IDI_ 標準圖示
Idc_ 標準數據指標

若要將 OEM 映射標識符常數傳遞至 LoadImage 函式，請使用 MAKEINTRESOURCE 宏。 例如，若要載入 OCR_NORMAL 數據指標，請傳遞 MAKEINTRESOURCE(OCR_NORMAL) 為 name 參數、 NULL 作為 hInst 參數，並將 LR_SHARED 做為 fuLoad 參數的其中一個旗標。

如果 hInst 參數為 NULL 且 fuLoad 參數包含LR_LOADFROMFILE值，則 name 是包含獨立資源 (圖示、游標或點陣圖檔案) 的檔名，例如。 c:\myicon.ico

如需詳細資訊，請參閱下面的＜備註＞一節。

[in] type

類型： UINT

要載入的影像類型。

此參數可以是下列其中一個值：

值 意義
IMAGE_BITMAP 載入點圖。
IMAGE_CURSOR 載入數據指標。
IMAGE_ICON 載入圖示。

[in] cx

類型： int

圖示或游標的寬度，以像素為單位。 如果此參數為零，且 fuLoad 參數 LR_DEFAULTSIZE，則函式會使用 SM_CXICON 或 SM_CXCURSOR 系統計量值來設定寬度。 如果此參數為零，且未使用 LR_DEFAULTSIZE ，則函式會使用實際的資源寬度。

[in] cy

類型： int

圖示或游標的高度，以像素為單位。 如果此參數為零，且 fuLoad 參數 LR_DEFAULTSIZE，則函式會使用 SM_CYICON 或 SM_CYCURSOR 系統計量值來設定高度。 如果此參數為零，且未使用 LR_DEFAULTSIZE ，則函式會使用實際的資源高度。

[in] fuLoad

類型： UINT

此參數可以是下列一或多個值。

值 意義
LR_CREATEDIBSECTION
0x00002000
 當 uType 參數指定 IMAGE_BITMAP時，會導致函式傳回 DIB 區段位圖，而不是相容的位圖。 此旗標適用於載入點陣圖，而不將它對應至顯示裝置的色彩。
LR_DEFAULTCOLOR
0x00000000
 默認旗標;它不會執行任何動作。 這表示「不是 LR_MONOCHROME」。
LR_DEFAULTSIZE
0x00000040
 如果 cxDesired 或 cyDesired 值設定為零，則會使用系統計量值所指定的寬度或高度。 如果未指定此旗標，且 cxDesired 和 cyDesired 設定為零，函式會使用實際的資源大小。 如果資源包含多個影像，函式會使用第一個影像的大小。
LR_LOADFROMFILE
0x00000010
 從 名稱 指定的檔案載入獨立影像， (圖示、游標或點陣圖檔案) 。
LR_LOADMAP3DCOLORS
0x00001000
 搜尋色彩表格中的影像，並以對應的 3D 色彩取代下列灰色陰影。
  • Dk Gray、RGB (128,128,128) 搭配 COLOR_3DSHADOW
  • 灰色、RGB (192,192,192) 與 COLOR_3DFACE
  • Lt Gray，RGB (223,223,223) 搭配 COLOR_3DLIGHT
如果您要載入色彩深度大於 8bpp 的點陣圖，請勿使用此選項。
LR_LOADTRANSPARENT
0x00000020
 擷取影像中第一個像素的色彩值，並將色彩數據表中的對應專案取代為默認視窗色彩 (COLOR_WINDOW) 。 使用該專案之影像中的所有像素都會成為預設視窗色彩。 此值僅適用於具有對應色彩數據表的影像。

如果您要載入色彩深度大於 8bpp 的點陣圖，請勿使用此選項。

如果 fuLoad 同時包含 LR_LOADTRANSPARENT 和 LR_LOADMAP3DCOLORS 值， 則LR_LOADTRANSPARENT 優先。 不過，色彩數據表專案會取代為 COLOR_3DFACE ，而不是 COLOR_WINDOW。
LR_MONOCHROME
0x00000001
 以黑色和白色載入影像。
LR_SHARED
0x00008000
 如果多次載入映像，請共用映像句柄。 如果未 設定LR_SHARED ，則相同資源的 LoadImage 第二次呼叫會再次載入映像，並傳回不同的句柄。

當您使用此旗標時，系統會在不再需要資源時終結資源。

請勿將 LR_SHARED 用於具有非標準大小的影像、可能會在載入之後變更，或是從檔案載入的影像。

載入系統圖示或游標時，您必須使用 LR_SHARED ，否則函式將無法載入資源。

不論所要求的大小為何，此函式都會尋找快取中具有要求資源名稱的第一個映像。
LR_VGACOLOR
0x00000080
 使用真正的 VGA 色彩。

傳回值

類型： HANDLE

如果函式成功，傳回值就是新載入影像的句柄。

如果函式失敗，傳回值為 NULL。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

如果 IS_INTRESOURCE (名稱) 為 TRUE， 則 name 會指定指定資源的整數標識符。 否則，它是 Null 終止字串的指標。 如果字串的第一個字元是井字元號 (#) ，則其餘字元代表指定資源的整數標識符的十進位數。 例如，字串 “#258” 代表標識碼 258。

當您使用點陣圖、游標或圖示完成載入但未指定 LR_SHARED 旗標時，您可以呼叫下表中的其中一個函式來釋放其相關聯的記憶體。

資源 Release 函式
點陣圖 DeleteObject
資料指標 DestroyCursor
圖示 DestroyIcon
 

當建立這些資源的進程終止時，系統會自動刪除這些資源;不過，呼叫適當的函式會儲存記憶體，並減少進程的工作集大小。

範例

如需範例，請參閱 使用窗口類別。

注意

winuser.h 標頭會將 LoadImage 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

   
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 winuser.h (包含 Windows.h)
程式庫 User32.lib
Dll User32.dll
API 集合 ext-ms-win-ntuser-gui-l1-1-0 (在 Windows 8) 中引進

另請參閱

概念

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

其他資源

參考

資源