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 の時点では、WinMain のシステム関数呼び出しによって公開されるアプリケーション インスタンス ハンドルやモジュール ハンドル (HMODULE) などのインスタンス ハンドル (HINSTANCE) も同じであることに注意してください。

定義済みのイメージまたはスタンドアロン リソース (アイコン、カーソル、またはビットマップ ファイル) を読み込むには、このパラメーターを NULL に設定 します。

[in] name

型: LPCTSTR

読み込むイメージ。

hInst パラメーターが NULL 以外で、fuLoad パラメーターがLR_LOADFROMFILEを省略した場合、name は hInst モジュール内のイメージ リソースを指定します。

イメージ リソースをモジュールの名前で読み込む場合、 name パラメーターは、イメージ リソースの名前を含む null で終わる文字列へのポインターです。

イメージ リソースをモジュールから序数で読み込む場合は、 MAKEINTRESOURCE マクロを使用して、イメージ序数を LoadImage 関数に渡すことができる形式に変換します。

hInst パラメーターが NULL で、fuLoad パラメーターがLR_LOADFROMFILE値を省略し、LR_SHAREDを含む場合、名前は読み込む定義済みのイメージを指定します。

定義済みのイメージ識別子は で Winuser.h 定義され、次のプレフィックスがあります。

Prefix 説明
OBM_ OEM ビットマップ。 これらを渡すには 、MAKEINTRESOURCE マクロを使用します。
Oic_ OEM アイコン。 これらを渡すには 、MAKEINTRESOURCE マクロを使用します。
Ocr_ OEM カーソル。 これらを渡すには 、MAKEINTRESOURCE マクロを使用します。
IDI_ 標準アイコン
Idc_ 標準カーソル

OEM イメージ識別子の定数を LoadImage 関数に渡すには、 MAKEINTRESOURCE マクロを使用します。 たとえば、OCR_NORMAL カーソルを読み込むには、name パラメーターとして、hInst パラメーターとして NULL を渡MAKEINTRESOURCE(OCR_NORMAL)し、fuLoad パラメーターにフラグの 1 つとしてLR_SHAREDします。

hInst パラメーターが NULL で、fuLoad パラメーターにLR_LOADFROMFILE値が含まれている場合、name はスタンドアロン リソース (アイコン、カーソル、またはビットマップ ファイル) を含むファイルの名前です (例: c:\myicon.ico)。

詳細については、以下の「解説」セクションを参照してください。

[in] type

型: UINT

読み込むイメージの種類。

このパラメーターには、次のいずれかの値を指定できます。

値 意味
IMAGE_BITMAP ビットマップを読み込みます。
IMAGE_CURSOR カーソルを読み込みます。
IMAGE_ICON アイコンを読み込みます。

[in] cx

型: int

アイコンまたはカーソルの幅 (ピクセル単位)。 このパラメーターが 0 で 、fuLoad パラメーターが LR_DEFAULTSIZEされている場合、関数は SM_CXICON またはシステム メトリック値 SM_CXCURSOR 使用して幅を設定します。 このパラメーターが 0 で 、LR_DEFAULTSIZE が使用されていない場合、関数は実際のリソース幅を使用します。

[in] cy

型: int

アイコンまたはカーソルの高さ (ピクセル単位)。 このパラメーターが 0 で 、fuLoad パラメーターが LR_DEFAULTSIZE場合、関数は SM_CYICON または SM_CYCURSOR システム メトリック値を使用して高さを設定します。 このパラメーターが 0 で 、LR_DEFAULTSIZE が使用されていない場合、関数は実際のリソースの高さを使用します。

[in] fuLoad

型: UINT

このパラメーターには、次の 1 つ以上の値を指定できます。

値 意味
LR_CREATEDIBSECTION
0x00002000
 uType パラメーターでIMAGE_BITMAPを指定すると、関数は互換性のあるビットマップではなく DIB セクション ビットマップを返します。 このフラグは、ビットマップをディスプレイ デバイスの色にマッピングせずに読み込む場合に便利です。
LR_DEFAULTCOLOR
0x00000000
 既定のフラグ。それは何もしません。 " LR_MONOCHROMEではない" という意味です。
LR_DEFAULTSIZE
0x00000040
 cxDesired 値または cyDesired 値が 0 に設定されている場合は、カーソルまたはアイコンのシステム メトリック値で指定された幅または高さを使用します。 このフラグが指定されておらず、 cxDesired と cyDesired が 0 に設定されている場合、関数は実際のリソース サイズを使用します。 リソースに複数のイメージが含まれている場合、関数は最初のイメージのサイズを使用します。
LR_LOADFROMFILE
0x00000010
 名前で指定されたファイル (アイコン、カーソル、またはビットマップ ファイル) からスタンドアロン イメージを読み込みます。
LR_LOADMAP3DCOLORS
0x00001000
 カラー テーブルで画像を検索し、次の灰色の網掛けを対応する 3-D 色に置き換えます。
  • Dk Gray、RGB(128,128,128) with COLOR_3DSHADOW
  • 灰色、RGB(192,192,192) とCOLOR_3DFACE
  • Lt Gray、RGB(223,223,223) with COLOR_3DLIGHT
色深度が 8bpp を超えるビットマップを読み込む場合は、このオプションを使用しないでください。
LR_LOADTRANSPARENT
0x00000020
 画像の最初のピクセルの色値を取得し、カラー テーブル内の対応するエントリを既定のウィンドウの色 (COLOR_WINDOW) に置き換えます。 そのエントリを使用するイメージ内のすべてのピクセルが既定のウィンドウの色になります。 この値は、対応するカラー テーブルを持つイメージにのみ適用されます。

色深度が 8bpp を超えるビットマップを読み込む場合は、このオプションを使用しないでください。

fuLoad にLR_LOADTRANSPARENTとLR_LOADMAP3DCOLORSの両方の値が含まれている場合は、LR_LOADTRANSPARENTが優先されます。 ただし、カラー テーブルエントリは、COLOR_WINDOWではなくCOLOR_3DFACEに置き換えられます。
LR_MONOCHROME
0x00000001
 イメージを白黒で読み込みます。
LR_SHARED
0x00008000
 イメージが複数回読み込まれる場合は、イメージ ハンドルを共有します。 LR_SHAREDが設定されていない場合、同じリソースに対して LoadImage を 2 回目に呼び出すと、イメージが再度読み込まれると、別のハンドルが返されます。

このフラグを使用すると、不要になったときにシステムによってリソースが破棄されます。

標準以外のサイズのイメージ、読み込み後に変更される可能性があるイメージ、またはファイルから読み込まれるイメージには、 LR_SHARED を使用しないでください。

システム アイコンまたはカーソルを読み込むときは、 LR_SHARED を使用する必要があります。または、関数がリソースの読み込みに失敗します。

この関数は、要求されたサイズに関係なく、要求されたリソース名を持つキャッシュ内の最初のイメージを検索します。
LR_VGACOLOR
0x00000080
 真の VGA 色を使用します。

戻り値

型: HANDLE

関数が成功した場合、戻り値は新しく読み込まれたイメージのハンドルです。

関数が失敗した場合は、返される値は NULL です。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

IS_INTRESOURCE(name) が TRUE の場合、name は指定されたリソースの整数識別子を指定します。 それ以外の場合は、null で終わる文字列へのポインターです。

文字列の最初の文字がシャープ記号 (#) の場合、残りの文字は、リソースの整数識別子を指定する 10 進数を表します。 たとえば、文字列 "#258" は識別子 258 を表します。

LR_SHARED フラグを指定せずに読み込んだビットマップ、カーソル、またはアイコンの使用が完了したら、次の表のいずれかの関数を呼び出すことで、関連付けられているメモリを解放できます。

リソース Release 関数
Bitmap DeleteObject
カーソル DestroyCursor
アイコン DestroyIcon
 

これらのリソースを作成したプロセスが終了すると、これらのリソースは自動的に削除されます。ただし、適切な関数を呼び出すとメモリが節約され、プロセスのワーキング セットのサイズが小さくなります。

例

例については、「 ウィンドウ クラスの使用」を参照してください。

注意

winuser.h ヘッダーは、LoadImage をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winuser.h (Windows.h を含む)
Library User32.lib
[DLL] User32.dll
API セット ext-ms-win-ntuser-gui-l1-1-0 (Windows 8 で導入)

関連項目

概念

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

その他のリソース

リファレンス

リソース