IPicture

COM

IID7bf80980-bf32-101a-8bbb-00aa00300cab継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ピクチャオブジェクトとそのプロパティを管理します。ピクチャオブジェクトは、ビットマップ、アイコン、メタファイルに対する言語非依存の抽象化を提供します。

解説(Remarks)

IPicture インターフェイスの各プロパティには、プロパティが読み取りアクセスをサポートする場合は get_PropertyName メソッドが、書き込みアクセスをサポートする場合は put_PropertyName メソッドが含まれます。

プロパティ	型	アクセス	説明
Handle	OLE_HANDLE (int)	R	ピクチャの Windows GDI ハンドル
hPal	OLE_HANDLE (int)	RW	ピクチャが使用するパレットの Windows ハンドル。
Type	short	R	ピクチャの種類（PICTYPE を参照）。
Width	OLE_XSIZE_HIMETRIC (long)	R	ピクチャの幅。
Height	OLE_YSIZE_HIMETRIC (long)	R	ピクチャの高さ。
CurDC	HDC	R	現在のデバイスコンテキスト。
KeepOriginalFormat	BOOL	RW	TRUE の場合、ピクチャオブジェクトはピクチャの元の状態全体をメモリ内に保持します。FALSE の場合、ユーザーのコンピューターに該当しない状態はすべて破棄されます。
Attributes	DWORD	R	ピクチャのその他のビット属性。

OLE 実装

ピクチャオブジェクトは、ビットマップ、アイコン、メタファイルに対する言語非依存の抽象化を提供します。標準のフォントオブジェクトと同様に、システムはピクチャオブジェクトの標準実装を提供します。その主要なインターフェイスは IPicture と IPictureDisp です。ピクチャオブジェクトは OleCreatePictureIndirect で作成され、IPicture インターフェイスと IPictureDisp インターフェイスの両方をサポートします。

OLE が提供するピクチャオブジェクトは、IPicture インターフェイスと IPictureDisp インターフェイスの完全なセマンティクスを実装します。

メソッド 14

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT get_Handle(OLE_HANDLE* pHandle)

このピクチャオブジェクトが管理するピクチャのハンドルを、指定した場所へ取得します。

pHandle

OLE_HANDLE*

out

ハンドルを受け取る変数へのポインター。正常に返された後は、このハンドルは呼び出し元の責任となります。失敗した場合、変数は NULL に設定されます。

戻り値

このメソッドは、標準の戻り値 E_FAIL および E_OUTOFMEMORY に加えて、次の値をサポートします。

戻り値	説明
S_OK	ハンドルが正常に返されました。
E_POINTER	phandle の値が無効です。たとえば NULL である可能性があります。

解説(Remarks)

呼び出し元への注意

ピクチャオブジェクトはピクチャの所有権を保持したままにすることがあります。ただし、呼び出し元が明示的にピクチャを破棄するか、またはピクチャオブジェクト自体が破棄されるまで、ピクチャが有効なまま保たれることは保証されます。ピクチャオブジェクトが作成されるときの所有権は、OleCreatePictureIndirect の fOwn パラメーターによって決まります。OleLoadPicture は fOwn を強制的に TRUE にします。

vtbl 4 HRESULT get_hPal(OLE_HANDLE* phPal)

ピクチャオブジェクトが現在使用しているパレットのコピーを取得します。

phPal

OLE_HANDLE*

out

パレットハンドルを受け取る変数へのポインター。失敗した場合、変数は NULL に設定されます。

戻り値

このメソッドは、標準の戻り値 E_FAIL および E_OUTOFMEMORY に加えて、次の値をサポートします。

戻り値	説明
S_OK	高さが正常に返されました。
S_FALSE	このピクチャにはパレットがありません。phpal が指す変数は NULL に設定されました。
E_POINTER	phPal の値が無効です。たとえば NULL である可能性があります。

解説(Remarks)

呼び出し元への注意

ピクチャオブジェクトがピクチャの所有権を持っている場合、パレットの所有権も持ち、オブジェクト自体が破棄されるときにパレットを破棄します。それ以外の場合は、呼び出し元がパレットを所有します。所有権は OleCreatePictureIndirect の fOwn パラメーターによって決まります。OleLoadPicture は fOwn を TRUE に設定し、ピクチャオブジェクトがパレットを所有することを示します。

vtbl 5 HRESULT get_Type(PICTYPE* pType)

ピクチャオブジェクトに含まれるピクチャの現在の種類を取得します。

pType

PICTYPE*

out

ピクチャの種類を受け取る変数へのポインター。Type プロパティは、PICTYPE 列挙体に含まれるいずれかの値を取ることができます。

戻り値

このメソッドは、標準の戻り値 E_FAIL に加えて、次の値をサポートします。

戻り値	説明
S_OK	種類が正常に返されました。
E_POINTER	pType の値が無効です。たとえば NULL である可能性があります。

vtbl 6 HRESULT get_Width(INT* pWidth)

ピクチャオブジェクト内のピクチャの現在の幅を取得します。

pWidth

INT*

out

幅を受け取る変数へのポインター。

戻り値

このメソッドは、標準の戻り値 E_FAIL に加えて、次の値をサポートします。

戻り値	説明
S_OK	幅が正常に返されました。
E_POINTER	pWidth の値が無効です。たとえば NULL である可能性があります。

vtbl 7 HRESULT get_Height(INT* pHeight)

ピクチャオブジェクト内のピクチャの現在の高さを取得します。

pHeight

INT*

out

高さを受け取る変数へのポインター。

戻り値

このメソッドは、標準の戻り値 E_FAIL に加えて、次の値をサポートします。

戻り値	説明
S_OK	高さが正常に返されました。
E_POINTER	pHeight の値が無効です。たとえば NULL である可能性があります。

vtbl 8 HRESULT Render(HDC hDC, INT x, INT y, INT cx, INT cy, INT xSrc, INT ySrc, INT cxSrc, INT cySrc, RECT* pRcWBounds)

ソースピクチャのオフセット (xSrc,ySrc) とコピーする寸法 (cxSrc,xySrc) で定義される、ピクチャの指定した部分をレンダリング（描画）します。

hDC	HDC	in	イメージをレンダリングするデバイスコンテキストのハンドル。
x	INT	in	レンダリングしたイメージを配置する hdc 内の水平座標。
y	INT	in	レンダリングしたイメージを配置する hdc 内の垂直座標。
cx	INT	in	コピー先の四角形の水平方向の寸法（幅）。
cy	INT	in	コピー先の四角形の垂直方向の寸法（高さ）
xSrc	INT	in	コピーを開始するソースピクチャ内の水平オフセット。
ySrc	INT	in	コピーを開始するソースピクチャ内の垂直オフセット。
cxSrc	INT	in	ソースピクチャからコピーする水平方向の範囲。
cySrc	INT	in	ソースピクチャからコピーする垂直方向の範囲。
pRcWBounds	RECT*	in	hdc がメタファイル DC である場合に、メタファイルデバイスコンテキスト内のコピー先の位置を含む四角形へのポインター。その場合、NULL にすることはできません。

戻り値

このメソッドは、標準の戻り値 E_FAIL、E_INVALIDARG、E_OUTOFMEMORY に加えて、次の値をサポートします。

戻り値	説明
S_OK	ピクチャが正常にレンダリングされました。
E_POINTER	hdc にメタファイルデバイスコンテキストが含まれている場合に、prcWBounds のアドレスが無効です。
CTL_E_INVALIDPROPERTYVALUE	パラメーター cx、cy、cxSrc、cySrc のいずれかの値が 0 です。

vtbl 9 HRESULT set_hPal(OLE_HANDLE hPal)

ピクチャオブジェクトに含まれるピクチャに GDI パレットを割り当てます。

hPal

OLE_HANDLE

ピクチャに割り当てる GDI パレットのハンドル。

戻り値

このメソッドは、標準の戻り値 E_FAIL、E_INVALIDARG、E_OUTOFMEMORY、S_OK をサポートします。

解説(Remarks)

実装者への注意

このメソッドに渡されるパレットの所有権は、OleCreatePictureIndirect の fOwn パラメーターで指定される、ピクチャオブジェクトの作成方法に依存します。OleLoadPicture は fOwn を強制的に TRUE にします。オブジェクトがピクチャを所有している場合、このパレットの所有権も引き継ぎます。

vtbl 10 HRESULT get_CurDC(HDC* phDC)

現在のデバイスコンテキストのハンドルを取得します。このプロパティはビットマップのピクチャに対してのみ有効です。

phDC

HDC*

out

デバイスコンテキストを受け取る変数へのポインター。

戻り値

このメソッドは、標準の戻り値 E_FAIL に加えて、次の値をサポートします。

戻り値	説明
S_OK	属性ビットが正常に返されました。
E_POINTER	phDC の値が無効です。たとえば NULL である可能性があります。

解説(Remarks)

CurDC プロパティと IPicture::SelectPicture メソッドは、Windows の制約、具体的には、あるオブジェクトを同時に選択できるデバイスコンテキストは 1 つだけであるという制約を回避するために存在します。場合によっては、ピクチャオブジェクトが特定のデバイスコンテキストに恒久的に選択されていることがあります（たとえば、コントロールが特定のピクチャを背景に使用している場合など）。このピクチャのプロパティを別の場所で使用するには、古いデバイスコンテキストから一時的に選択解除し、操作のために新しいデバイスコンテキストへ選択したうえで、再び古いデバイスコンテキストへ選択し直す必要があります。IPicture::get_CurDC メソッドは、ピクチャが現在選択されているデバイスコンテキストのハンドルを返します。IPicture::SelectPicture メソッドは、ピクチャを新しいデバイスコンテキストへ選択し、古いデバイスコンテキストとピクチャの GDI ハンドルを返します。呼び出し元は、Windows コードで通常行うように、使用を終えたらピクチャを古いデバイスコンテキストへ選択し直す必要があります。

呼び出し元への注意

呼び出し元とピクチャオブジェクトとの間で受け渡されるデバイスコンテキストは、常に呼び出し元が所有します。ピクチャオブジェクトは HDC のコピーを保持するため、呼び出し元は画面のデバイスコンテキスト（GetDC、CreateDC、BeginPaint によるもの）ではなく、メモリデバイスコンテキスト（CreateCompatibleDC 関数で作成したもの）を使用する必要があります。画面のデバイスコンテキストは限られたシステムリソースだからです。

vtbl 11 HRESULT SelectPicture(HDC hDCIn, HDC* phDCOut, OLE_HANDLE* phBmpOut)

ビットマップのピクチャを指定したデバイスコンテキストへ選択し、そのピクチャが以前に選択されていたデバイスコンテキストと、ピクチャの GDI ハンドルを返します。このメソッドは IPicture::get_CurDC と連携して機能します。

hDCIn	HDC	in	ピクチャを選択するデバイスコンテキストのハンドル。
phDCOut	HDC*	out	以前のデバイスコンテキストを受け取る変数へのポインター。呼び出し元がこの情報を必要としない場合、このパラメーターは NULL にできます。デバイスコンテキストの所有権は常に呼び出し元の責任です。
phBmpOut	OLE_HANDLE*	out	ピクチャの GDI ハンドルを受け取る変数へのポインター。呼び出し元がハンドルを必要としない場合、このパラメーターは NULL にできます。このハンドルの所有権は、OleCreatePictureIndirect に渡される fOwn パラメーターによって決まります。ストリームから読み込まれたピクチャは、常に自身のリソースを所有します。

戻り値

このメソッドは、標準の戻り値 E_FAIL、E_INVALIDARG、E_OUTOFMEMORY、S_OK をサポートします。

vtbl 12 HRESULT get_KeepOriginalFormat(BOOL* pKeep)

ピクチャの KeepOriginalFormat プロパティの現在の値を取得します。

pKeep

BOOL*

out

プロパティの値を受け取る変数へのポインター。

戻り値

このメソッドは、標準の戻り値 E_FAIL に加えて、次の値をサポートします。

戻り値	説明
S_OK	KeepOriginalFormat プロパティの値が正常に返されました。
E_POINTER	pKeep の値が無効です。たとえば NULL である可能性があります。

vtbl 13 HRESULT put_KeepOriginalFormat(BOOL keep)

ピクチャの KeepOriginalFormat プロパティの値を設定します。

keep

BOOL

プロパティに割り当てる新しい値を指定します。

戻り値

このメソッドは、成功した場合は S_OK を、それ以外の場合は E_FAIL を返します。

vtbl 14 HRESULT PictureChanged()

ピクチャリソースが変更されたことをピクチャオブジェクトに通知します。このメソッドは、接続されているすべてのシンクに対して DISPID_PICT_HANDLE を指定して IPropertyNotifySink::OnChanged を呼び出すだけです。

戻り値

このメソッドは、成功した場合は S_OK を、ピクチャオブジェクトが未初期化の場合は E_FAIL を返します。

vtbl 15 HRESULT SaveAsFile(IStream* pStream, BOOL fSaveMemCopy, INT* pCbSize)

ピクチャのデータを、ファイルに保存する場合と同じ形式でストリームに保存します。ビットマップは BMP ファイル形式、メタファイルは WMF 形式、アイコンは ICO 形式を使用します。

pStream	IStream*	in	ピクチャがデータを書き込むストリームへのポインター。
fSaveMemCopy	BOOL	in	ピクチャのコピーをメモリに保存するかどうかを示すフラグ。
pCbSize	INT*	out	ストリームに書き込まれたバイト数を受け取る変数へのポインター。この値は NULL にでき、その場合は呼び出し元がこの情報を必要としないことを示します。

戻り値

このメソッドは、標準の戻り値 E_FAIL、E_INVALIDARG、S_OK をサポートします。

vtbl 16 HRESULT get_Attributes(DWORD* pDwAttr)

ピクチャのビット属性の現在のセットを取得します。

pDwAttr

DWORD*

out

Attributes プロパティの値を受け取る変数へのポインター。

Attributes プロパティには、PICTUREATTRIBUTES 列挙体の値の任意の組み合わせを含めることができます。

戻り値

このメソッドは、標準の戻り値 E_FAIL に加えて、次の値をサポートします。

戻り値	説明
S_OK	属性ビットが正常に返されました。
E_POINTER	pdwAttr の値が無効です。たとえば NULL である可能性があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IPicture "{7BF80980-BF32-101A-8BBB-00AA00300CAB}"
#usecom global IPicture IID_IPicture "{}"
#comfunc global IPicture_get_Handle              3 var
#comfunc global IPicture_get_hPal                4 var
#comfunc global IPicture_get_Type                5 var
#comfunc global IPicture_get_Width               6 var
#comfunc global IPicture_get_Height              7 var
#comfunc global IPicture_Render                  8 sptr,int,int,int,int,int,int,int,int,var
#comfunc global IPicture_set_hPal                9 int
#comfunc global IPicture_get_CurDC               10 sptr
#comfunc global IPicture_SelectPicture           11 sptr,sptr,var
#comfunc global IPicture_get_KeepOriginalFormat  12 var
#comfunc global IPicture_put_KeepOriginalFormat  13 int
#comfunc global IPicture_PictureChanged          14
#comfunc global IPicture_SaveAsFile              15 sptr,int,var
#comfunc global IPicture_get_Attributes          16 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPicture "{7BF80980-BF32-101A-8BBB-00AA00300CAB}"
#usecom global IPicture IID_IPicture "{}"
#comfunc global IPicture_get_Handle              3 sptr
#comfunc global IPicture_get_hPal                4 sptr
#comfunc global IPicture_get_Type                5 sptr
#comfunc global IPicture_get_Width               6 sptr
#comfunc global IPicture_get_Height              7 sptr
#comfunc global IPicture_Render                  8 sptr,int,int,int,int,int,int,int,int,sptr
#comfunc global IPicture_set_hPal                9 int
#comfunc global IPicture_get_CurDC               10 sptr
#comfunc global IPicture_SelectPicture           11 sptr,sptr,sptr
#comfunc global IPicture_get_KeepOriginalFormat  12 sptr
#comfunc global IPicture_put_KeepOriginalFormat  13 int
#comfunc global IPicture_PictureChanged          14
#comfunc global IPicture_SaveAsFile              15 sptr,int,sptr
#comfunc global IPicture_get_Attributes          16 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。