ホーム › System.Ole › IPropertyPage

IPropertyPage

COM

📘 Microsoft Learn (日本語) · English

IIDb196b28d-bab4-101a-b69c-00aa00341d07継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

プロパティシート内の特定のページを管理するプロパティページオブジェクトの主要機能を提供します。

メソッド 11

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

vtbl 3 HRESULT SetPageSite(IPropertyPageSite* pPageSite)

プロパティページを初期化し、プロパティページがプロパティフレームと通信するための IPropertyPageSite インターフェースへのポインターをページに提供します。

pPageSite

IPropertyPageSite*

プロパティシート全体の中でこのプロパティページを管理し、サービスを提供するページサイトの IPropertyPageSite インターフェースへのポインター。

戻り値

このメソッドは、標準的な戻り値 E_INVALIDARG、E_OUTOFMEMORY、および S_OK を返すことがあります。

解説(Remarks)

実装者への注意

pPageSite パラメーターが NULL の場合、このメソッドは、このメソッドの以前の呼び出しで渡された IPropertyPageSite ポインターに対して Release を呼び出す必要があります。NULL 以外の場合、このメソッドは IPropertyPageSite ポインターの値を保存し、AddRef を呼び出す必要があります。NULL 以外のサイトポインターでこのメソッドを連続して 2 回呼び出すことは許可されておらず、その場合はプロパティページが E_UNEXPECTED を返すようにする必要があります。

E_NOTIMPL は有効な戻り値ではありません。すべてのプロパティページはこのメソッドを実装する必要があります。

vtbl 4 HRESULT Activate(HWND hWndParent, RECT* pRect, BOOL bModal)

プロパティページのダイアログボックスウィンドウを作成します。

hWndParent	HWND	in	作成されるダイアログボックスの親ウィンドウのウィンドウハンドル。
pRect	RECT*	in	ダイアログボックスの配置情報を含む RECT 構造体へのポインター。このメソッドは、この構造体で示された配置および寸法でダイアログボックスを作成する必要があります。
bModal	BOOL	in	ダイアログボックスフレームがモーダル(TRUE)かモードレス(FALSE)かを示します。

戻り値

このメソッドは、標準的な戻り値 E_OUTOFMEMORY および E_UNEXPECTED に加えて、以下の値を返すことがあります。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_POINTER	prc のアドレスが有効ではありません。たとえば NULL である可能性があります。

解説(Remarks)

プロパティページは、この処理で作成されたウィンドウハンドルを保持し、IPropertyPage::Deactivate 内でダイアログボックスを破棄するためにそれを使用します。

実装者への注意

E_NOTIMPL は有効な戻り値ではありません。

vtbl 5 HRESULT Deactivate()

IPropertyPage::Activate で作成されたウィンドウを破棄します。

戻り値

このメソッドは、標準的な戻り値 E_UNEXPECTED および S_OK を返すことがあります。

解説(Remarks)

実装者への注意

最適化のために、プロパティページがダイアログボックスを保持し続けないことが重要です。多数のプロパティページを持つプロパティシートでは、すべてのプロパティページが常にダイアログボックスを作成したまま保持すると、メモリ消費が過大になります。ダイアログボックスを破棄することで、ダイアログボックス内に非常に多数のコントロールが作成されることによる過大なメモリ消費を防ぎます。フレームがページを非表示の間も存続させたい場合は、その目的のために IPropertyPage::Show を使用できます。最終的な判断はフレームに委ねられます。

E_NOTIMPL は有効な戻り値ではありません。

vtbl 6 HRESULT GetPageInfo(PROPPAGEINFO* pPageInfo)

プロパティページに関する情報を取得します。

pPageInfo

PROPPAGEINFO*

out

プロパティページがそのページ情報を格納する、呼び出し側が割り当てた PROPPAGEINFO 構造体へのポインター。この構造体に格納されたすべての割り当ては、呼び出し側の責任となります。

戻り値

このメソッドは、標準的な戻り値 E_OUTOFMEMORY および E_UNEXPECTED に加えて、以下の値を返すことがあります。

戻り値	説明
S_OK	構造体が正常に格納されました。
E_POINTER	pPageInfo のアドレスが有効ではありません。たとえば NULL である可能性があります。

解説(Remarks)

実装者への注意

E_NOTIMPL は有効な戻り値ではありません。

vtbl 7 HRESULT SetObjects(DWORD cObjects, IUnknown** ppUnk)

このプロパティページに関連付けられたオブジェクトへのポインターの配列をプロパティページに提供します。

cObjects	DWORD	in	ppUnk が指す配列内のポインターの数。このパラメーターが 0 の場合、プロパティページはこのメソッドに以前渡されたすべてのポインターを解放する必要があります。
ppUnk	IUnknown**	in	IUnknown インターフェースポインターの配列へのポインター。各ポインターは、このプロパティページ(および場合によっては他のプロパティページ)が表示されるプロパティシートの影響を受ける一意のオブジェクトを識別します。プロパティページは、その時点で各ポインターに対して AddRef を呼び出して、これらのポインターをキャッシュする必要があります。このポインターの配列は、プロパティシートを起動するために OleCreatePropertyFrame または OleCreatePropertyFrameIndirect に渡されたものと同じです。

戻り値

このメソッドは、標準的な戻り値 E_FAIL、E_INVALIDARG、E_OUTOFMEMORY、および E_UNEXPECTED に加えて、以下の値を返すことがあります。

戻り値	説明
S_OK	プロパティページは必要なポインターを正常に保存しました。
E_NOINTERFACE	ppUnk 内のオブジェクトの 1 つが、このプロパティページが期待するインターフェースをサポートしていないため、このプロパティページはそのオブジェクトと通信できません。
E_POINTER	ppUnk のアドレスが有効ではありません。たとえば NULL である可能性があります。

解説(Remarks)

プロパティページは、このメソッドによって返されたポインター、またはそれらを通じてクエリされた他のポインターを保持する必要があります。これらの特定の IUnknown ポインターを保持する場合、プロパティページはそれらをキャッシュするときに各ポインターを通じて AddRef を呼び出す必要があります。これは、cObjects を 0 にして SetObjects が呼び出されるまで続きます。その時点で、プロパティページは各ポインターを通じて Release を呼び出し、保持していたすべてのオブジェクトを解放する必要があります。

呼び出し側は、IPropertyPage::Activate を呼び出す前にこれらのオブジェクトをプロパティページに提供する必要があり、ページを非アクティブ化するとき、またはオブジェクトを完全に解放するときには、パラメーターを 0 にして SetObjects を呼び出す必要があります。NULL 以外の ppUnk パラメーターを指定した SetObjects の各呼び出しは、後で cObjects パラメーターを 0 にした SetObjects の呼び出しと対応させる必要があります。

実装者への注意

E_NOTIMPL は有効な戻り値ではありません。

vtbl 8 HRESULT Show(DWORD nCmdShow)

プロパティページのダイアログボックスを表示または非表示にします。ページを表示する場合、ページは自身に、具体的にはページ上の最初のプロパティにフォーカスを設定する必要があります。

nCmdShow

DWORD

表示(SW_SHOW または SW_SHOWNORMAL)にするか非表示(SW_HIDE)にするかを示すコマンド。このパラメーターにはこれ以外の値は有効ではありません。

戻り値

このメソッドは、標準的な戻り値 E_INVALIDARG、E_UNEXPECTED、および S_OK を返すことがあります。

解説(Remarks)

呼び出し側への注意

このメソッドの呼び出しは、IPropertyPage::Activate の呼び出しの後、対応する IPropertyPage::Deactivate の呼び出しの前に行う必要があります。

実装者への注意

E_NOTIMPL は有効な戻り値ではありません。このメソッドの実装ではメモリを使用しないため、E_OUTOFMEMORY も有効な戻り値ではありません。

vtbl 9 HRESULT Move(RECT* pRect)

フレーム内でプロパティページのダイアログボックスの位置を設定し、サイズを変更します。

pRect

RECT*

プロパティページのダイアログボックスの配置情報を含む RECT 構造体へのポインター。

戻り値

このメソッドは、標準的な戻り値 E_UNEXPECTED に加えて、以下の値を返すことがあります。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_POINTER	prc のアドレスが有効ではありません。たとえば NULL である可能性があります。

解説(Remarks)

prc で指定される矩形は、IPropertyPage::Activate に渡されるものと同一に扱われます。

呼び出し側への注意

このメソッドの呼び出しは、IPropertyPage::Activate の呼び出しの後、対応する IPropertyPage::Deactivate の呼び出しの前に行う必要があります。

実装者への注意

ページは、この構造体で示された配置および寸法でダイアログボックスを作成する必要があります。

vtbl 10 HRESULT IsPageDirty()

プロパティページがアクティブ化されて以降、または最後に Apply が呼び出されて以降に変更されたかどうかを示します。

戻り値

このメソッドは、プロパティページが変更されたことを示すために S_OK を返します。それ以外の場合は S_FALSE を返します。

解説(Remarks)

プロパティシートはこの情報を使用して、ダイアログボックスの適用ボタンを有効または無効にします。プロパティページ上の値が、それらの値が既に基となるオブジェクトと同期している場合は、それらの値を適用する必要はありません。

実装者への注意

ページがダーティかどうかを判断できない場合は既定として S_OK を返すべきなので、このメソッドがエラーコードを返す理由はありません。このようにすることで、ユーザーは値を更新する機会を得られます。エラーコードは S_OK と同じではなく、ページがダーティでないことを示すことになるため、ページはエラーコードを返すべきではありません。そうすると、プロパティフレームが適用ボタンを無効にしてしまい、ユーザーがプロパティ値を最新の状態にすることを許可できなくなる可能性があります。

vtbl 11 HRESULT Apply()

以前に IPropertyPage::SetObjects に渡された、プロパティページに関連付けられた基となるオブジェクトに現在の値を適用します。

戻り値

このメソッドは、標準的な戻り値 E_OUTOFMEMORY および E_UNEXPECTED に加えて、以下の値を返すことがあります。

戻り値	説明
S_OK	変更が正常に適用され、プロパティページは基となるオブジェクトと同期しています。
S_FALSE	変更は適用されましたが、プロパティページはその状態がオブジェクトと同期しているかどうかを判断できません。

解説(Remarks)

変更対象のオブジェクトは、以前の IPropertyPage::SetObjects の呼び出しを通じて提供されます。このメソッドを呼び出す前に IPropertyPage::SetObjects を呼び出すことで、呼び出し側は、すべての基となるオブジェクトが変更を伝達するための正しいインターフェースを持っていることを保証します。したがって、このメソッドは存在しないインターフェースが原因で失敗するべきではありません。

値を適用した後、プロパティページは、 IPropertyPage::IsPageDirty を適切に実装し、S_OK と S_FALSE の両方の戻り値を提供するために、その状態がオブジェクトと同期しているかどうかを判断する必要があります。

実装者への注意

E_NOTIMPL は有効な戻り値ではありません。

vtbl 12 HRESULT Help(LPWSTR pszHelpDir)

エンドユーザーの要求に応じてプロパティページのヘルプを呼び出します。

pszHelpDir

LPWSTR

レジストリ内のプロパティページの CLSID 情報における HelpDir キーの下にある文字列へのポインター。HelpDir が存在しない場合、これは InprocServer32 エントリで見つかったパスからサーバーファイル名を除いたものになります。(ローカルのプロパティページはサポートされていないため、LocalServer32 はチェックされないことに注意してください。)

戻り値

このメソッドは、標準的な戻り値 E_OUTOFMEMORY および E_UNEXPECTED に加えて、以下の値を返すことがあります。

戻り値	説明
S_OK	ページは独自のヘルプを表示しました。
E_NOTIMPL	ヘルプは提供されないか、PROPPAGEINFO の情報を通じてのみ提供されます。

解説(Remarks)

呼び出し側への注意

このメソッドの呼び出しは、IPropertyPage::Activate と IPropertyPage::Deactivate の呼び出しの間に行う必要があります。

実装者への注意

ページがこのメソッドで失敗した場合(E_NOTIMPL など)、フレームは IPropertyPage::GetPageInfo を通じて取得した PROPPAGEINFO 構造体の pszHelpFile および dwHelpContext メンバーを使用しようとします。したがって、ページは IPropertyPage::Help を実装するか、IPropertyPage::GetPageInfo を通じてヘルプ情報を返す必要があります。

vtbl 13 HRESULT TranslateAccelerator(MSG* pMsg)

処理のためにキーストロークをプロパティページに渡します。

pMsg

MSG*

処理対象のキーストロークを記述する MSG 構造体へのポインター。

戻り値

このメソッドは、標準的な戻り値 E_UNEXPECTED に加えて、以下の値を返すことがあります。

戻り値	説明
S_OK	プロパティページはアクセラレーターを処理します。
S_FALSE	プロパティページはアクセラレーターを処理しますが、これはページにとって有用ではありませんでした。
E_NOTIMPL	プロパティページはアクセラレーターを処理しません。
E_POINTER	pMsg のアドレスが有効ではありません。たとえば NULL である可能性があります。

解説(Remarks)

呼び出し側への注意

このメソッドの呼び出しは、IPropertyPage::Activate の呼び出しの後、対応する IPropertyPage::Deactivate の呼び出しの前に行う必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPropertyPage "{B196B28D-BAB4-101A-B69C-00AA00341D07}"
#usecom global IPropertyPage IID_IPropertyPage "{}"
#comfunc global IPropertyPage_SetPageSite           3 sptr
#comfunc global IPropertyPage_Activate              4 sptr,var,int
#comfunc global IPropertyPage_Deactivate            5
#comfunc global IPropertyPage_GetPageInfo           6 var
#comfunc global IPropertyPage_SetObjects            7 int,sptr
#comfunc global IPropertyPage_Show                  8 int
#comfunc global IPropertyPage_Move                  9 var
#comfunc global IPropertyPage_IsPageDirty           10
#comfunc global IPropertyPage_Apply                 11
#comfunc global IPropertyPage_Help                  12 wstr
#comfunc global IPropertyPage_TranslateAccelerator  13 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPropertyPage "{B196B28D-BAB4-101A-B69C-00AA00341D07}"
#usecom global IPropertyPage IID_IPropertyPage "{}"
#comfunc global IPropertyPage_SetPageSite           3 sptr
#comfunc global IPropertyPage_Activate              4 sptr,sptr,int
#comfunc global IPropertyPage_Deactivate            5
#comfunc global IPropertyPage_GetPageInfo           6 sptr
#comfunc global IPropertyPage_SetObjects            7 int,sptr
#comfunc global IPropertyPage_Show                  8 int
#comfunc global IPropertyPage_Move                  9 sptr
#comfunc global IPropertyPage_IsPageDirty           10
#comfunc global IPropertyPage_Apply                 11
#comfunc global IPropertyPage_Help                  12 wstr
#comfunc global IPropertyPage_TranslateAccelerator  13 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。