loadImageW 函式 (winuser.h)

發行項
05/30/2024

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

語法

HANDLE LoadImageW(
  [in, optional] HINSTANCE hInst,
  [in]           LPCWSTR   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 值，並包含 LR_SHARED， 則名稱 會指定要載入的預先定義映像。

預先定義的映射識別元定義於 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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-gui-l1-1-0 (在 Windows 8)