共用方式為


loadImageW 函式 (winuser.h)

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

語法

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_CXICONSM_CXCURSOR 系統計量值來設定寬度。 如果此參數為零且未使用 LR_DEFAULTSIZE ,則函式會使用實際的資源寬度。

[in] cy

類型: int

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

[in] fuLoad

類型: UINT

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

意義
LR_CREATEDIBSECTION
0x00002000
uType 參數指定 IMAGE_BITMAP時,會導致函式傳回 DIB 區段位圖,而不是相容的位圖。 此旗標適用於載入點陣圖,而不將其對應至顯示裝置的色彩。
LR_DEFAULTCOLOR
0x00000000
默認旗標;它不會執行任何動作。 這表示「不 LR_MONOCHROME」。
LR_DEFAULTSIZE
0x00000040
如果 cxDesiredcyDesired 值設定為零,則會使用系統計量值所指定的寬度或高度。 如果未指定此旗標, 而且 cxDesiredcyDesired 設定為零,則函式會使用實際的資源大小。 如果資源包含多個影像,函式會使用第一個影像的大小。
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_LOADTRANSPARENTLR_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)

另請參閱

概念

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

其他資源

參考

資源