プロパティ シートとプロパティ ページ
オブジェクトのプロパティは、COM インターフェイスまたはオブジェクトの IDispatch 実装を介してメソッドと同じようにクライアントに公開され、これらのメソッドを呼び出すプログラムによってプロパティを変更できます。 プロパティ ページの OLE テクノロジは、Windows ユーザー インターフェイス標準に従ってオブジェクトのプロパティのユーザー インターフェイスを構築する手段を提供します。 したがって、プロパティはエンド ユーザーに公開されます。 オブジェクトのプロパティ シートは、各タブが特定のプロパティ ページに対応するタブ付きダイアログです。 プロパティ ページを操作するための OLE モデルは、次の機能で構成されます。
- 各プロパティ ページは、IPropertyPage または IPropertyPage2 を実装するインプロセス オブジェクトによって管理されます。 各ページは、独自の一意の CLSID で識別されます。
- オブジェクトは、ISpecifyPropertyPages を実装することによって、プロパティ ページのサポートを指定します。 このインターフェイスを介して、呼び出し元は、オブジェクトがサポートする特定のプロパティ ページを識別する CLSID の一覧を取得できます。 オブジェクトがプロパティ ページ CLSID を指定する場合、オブジェクトはプロパティ ページからプロパティの変更を受け取ることができる必要があります。
- オブジェクトのプロパティ シートを表示するコード (クライアントまたはオブジェクト) は、オブジェクトの IUnknown ポインター (または複数のオブジェクトが影響を受ける場合は配列) とページ CLSID の配列を OleCreatePropertyFrame または OleCreatePropertyFrameIndirect に渡し、タブ付きダイアログ ボックスを作成します。
- プロパティ フレーム ダイアログでは、各 CLSID で CoCreateInstance を使用して、各プロパティ ページの 1 つのインスタンスがインスタンス化されます。 プロパティ フレームは、ページごとに少なくとも IPropertyPage ポインターを取得します。 さらに、フレームは、ページごとにプロパティ ページ サイト オブジェクト自体を作成します。 各サイトは IPropertyPageSite を実装し、このポインターは各ページに渡されます。 ページは、このインターフェイス ポインターを使用してサイトと通信します。
- 各ページには、呼び出されたオブジェクトも認識されます。つまり、プロパティ フレームはオブジェクトの IUnknown ポインターを各ページに渡します。 オブジェクトに変更を適用するように指示されると、各ページは適切なインターフェイス ポインターを照会し、必要な方法で新しいプロパティ値をオブジェクトに渡します。 このような通信がどのように行われるかについての規定はありません。
- オブジェクトは、IPerPropertyBrowsing インターフェイスを介したプロパティごとの参照をサポートすることもできます。これにより、プロパティ ページの表示時に初期フォーカスを受け取るプロパティを指定したり、クライアントが独自のユーザー インターフェイスで表示できる文字列と値を指定したりできます。
これらの機能を次の図に示します。
これらのインターフェイスは次のように定義されます。
interface ISpecifyPropertyPages : IUnknown
{
HRESULT GetPages([out] CAUUID *pPages);
};
interface IPropertyPage : IUnknown
{
HRESULT SetPageSite([in] IPropertyPageSite *pPageSite);
HRESULT Activate([in] HWND hWndParent, [in] LPCRECT prc
, [in] BOOL bModal);
HRESULT Deactivate(void);
HRESULT GetPageInfo([out] PROPPAGEINFO *pPageInfo);
HRESULT SetObjects([in] ULONG cObjects
, [in, max_is(cObjects)] IUnknown **ppunk);
HRESULT Show([in] UINT nCmdShow);
HRESULT Move([in] LPCRECT prc);
HRESULT IsPageDirty(void);
HRESULT Apply(void);
HRESULT Help([in] LPCOLESTR pszHelpDir);
HRESULT TranslateAccelerator([in] LPMSG pMsg);
}
interface IPropertyPageSite : IUnknown
{
HRESULT OnStatusChange([in] DWORD dwFlags);
HRESULT GetLocaleID([out] LCID *pLocaleID);
HRESULT GetPageContainer([out] IUnknown **ppUnk);
HRESULT TranslateAccelerator([in] LPMSG pMsg);
}
ISpecifyPropertyPages::GetPages メソッドは、オブジェクトが表示するプロパティ ページの CLSID を記述する UUID (GUID) 値のカウントされた配列を返します。 OleCreatePropertyFrame または OleCreatePropertyFrameIndirect でプロパティ シートを呼び出すユーザーは、この配列を関数に渡します。 呼び出し元が複数のオブジェクトのプロパティ ページを表示したい場合は、すべてのオブジェクトの CLSID リストの交差部分のみをこれらの関数に渡す必要があることに注意してください。 つまり、呼び出し元は、すべてのオブジェクトに共通のプロパティ ページのみを呼び出す必要があります。
さらに、呼び出し元は、影響を受けるオブジェクトへの IUnknown ポインターを API 関数にも渡します。 どちらの API 関数も、プロパティ フレーム ダイアログを作成し、読み込むページごとに IPropertyPageSite を使用してページ サイトをインスタンス化します。 このインターフェイスを通じて、プロパティ ページは次のことを行うことができます。
- GetLocaleID を使用して、プロパティ シートで使用されている現在の言語を取得します。
- TranslateAccelerator を使用してキー ストロークを処理するようにフレームに依頼します。
- OnStatusChange を使用して、ページ内の変更のフレームに通知します。
- GetPageContainer を使用してフレーム自体のインターフェイス ポインターを取得しますが、この関数の現時点ではフレームに対して定義されたインターフェイスはありませんが、常に E_NOTIMPL を返します。
プロパティ フレームは、各プロパティ ページ オブジェクトをインスタンス化し、各ページの IPropertyPage インターフェイスを取得します。 このインターフェイスを介して、フレームはページ サイト (SetPageSite) のページに通知し、ページのディメンションと文字列 (GetPageInfo) を取得し、影響を受けるオブジェクト (SetObjects) へのインターフェイス ポインターを渡し、コントロールを作成および破棄するタイミングをページに指示します (アクティブ化と非アクティブ化)、ページに表示または再配置を指示します (表示と移動)、影響を受けるオブジェクト (適用) に現在の値を適用するようにページに指示し、ページのダーティ状態 (IsPageDirty) のチェック、ヘルプ (Help) を呼び出し、ページにキーストロークを渡します (TranslateAccelerator)。
オブジェクトは、次のようなプロパティごとの参照もサポートできます。
- (IPerPropertyBrowsing および IPropertyPage2 を介して) プロパティ シートが最初に表示されるときに、どのプロパティ ページに最初のフォーカスを与える必要があるプロパティを指定する方法
- オブジェクトの (IPerPropertyBrowsing を介して) 定義済みの値と、クライアント独自のユーザー インターフェイスでプロパティに表示できる対応する説明文字列を指定する方法。
オブジェクトにプロパティ シートがない場合など、(1) をサポートせずに (2) サポートするようにオブジェクトを選択できます。
IPropertyPage2 インターフェイスと IPerPropertyBrowsing インターフェイスは次のように定義されています。
interface IPerPropertyBrowsing : IUnknown
{
HRESULT GetDisplayString([in] DISPID dispID, [out] BSTR *pbstr);
HRESULT MapPropertyToPage([in] DISPID dispID, [out] CLSID *pclsid);
HRESULT GetPredefinedStrings([in] DISPID dispID, [out] CALPOLESTR *pcaStringsOut, [out] CADWORD *pcaCookiesOut);
HRESULT GetPredefinedValue([in] DISPID dispID, [in] DWORD dwCookie, [out] VARIANT *pvarOut);
}
interface IPropertyPage2 : IPropertyPage
{
HRESULT EditProperty([in] DISPID dispID);
}
このような機能のサポートを指定するために、オブジェクトは IPerPropertyBrowsing を実装します。 このインターフェイスを使用して、呼び出し元は、定義済みの文字列 (GetPredefinedStrings) や値 (GetPredefinedValue) や、特定のプロパティ (GetDisplayString) の表示文字列など、参照を実現するために必要な情報を要求できます。
さらに、クライアントは、DISPID (MapPropertyToPage) で識別された特定のプロパティをユーザーが編集できるようにするプロパティ ページの CLSID を取得できます。 次に、クライアントは、CLSID と DISPID を OleCreatePropertyFrameIndirect に渡すことによって、最初にそのページをアクティブ化するようにプロパティ フレームに指示します。 フレームは最初にそのページをアクティブ化し、IPropertyPage2::EditProperty を介して DISPID をページに渡します。 ページは、そのプロパティの編集フィールドにフォーカスを設定します。 このようにして、クライアントは、独自のユーザー インターフェイスのプロパティ名から、そのプロパティを操作できるプロパティ ページにジャンプできます。
関連トピック
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示