Microsoft DirectX 8.0 |
フィルタにプロパティ ページを実装して、フィルタのカスタム プロパティへのアクセスを提供できる。GraphEdit はこれらのプロパティ ページを表示するので、これはフィルタの開発およびデバッグに便利である。また、Microsoft® Windows Media Player コントロールは、その下位のフィルタ グラフ内のフィルタに、サポートするプロパティ ページを問い合わせ、それをユーザーに対して公開する。この例として、プロパティ ページを使用して品質管理情報を公開するビデオ レンダラがある。
このクラスは、フィルタに関連付けられたプロパティ ページのフレームワークを提供し、IPropertyPage インターフェイスを実装する。プロパティ ページは Component Object Model (COM) オブジェクトであり、必要に応じてロードされるダイアログ ボックスのリソース ID を使用して作成する必要がある。また、作成時にタイトル文字列のリソース ID も指定しなければならない。
IPropertyPage インターフェイス メソッドの実装に加えて、このクラスは派生クラスでオーバーライドして特殊化することができるいくつかの仮想メンバ関数 (デフォルトでは NOERROR を返す) を提供する。これらの仮想メンバ関数は、特定のイベントが発生すると呼び出される。たとえば、プロパティ ページがアクティブまたは非アクティブされたとき、接続または切断されたとき、プロパティに対する変更が適用されたとき、ダイアログ ボックスへのメッセージが受信されたときなどである。
カスタム プロパティ ページを公開するフィルタは、カスタム インターフェイスを使用してアプリケーションにも同じ機能を公開する必要がある。機能を公開しないと、アプリケーションはプロパティ ページを表示せずにフィルタを制御することができない。たとえば、ビデオ レンダラは IQualProp インターフェイスをサポートして、同じ品質管理情報にアクセスする。実際、レンダラのプロパティ ページは、このインターフェイスを使用してプロパティ ページの情報を取得する。アプリケーションが容易にカスタム インターフェイスにアクセスできるように、フィルタは PID も実装する必要がある。PID は、フィルタ グラフ マネージャによって集成されたオブジェクトである。通常、PID はアプリケーションからフィルタ インターフェイスに呼び出しを渡すことによって、関連付けられたフィルタのインターフェイスを実装する。
m_bDirty 何かが変更されたかどうかを示すフラグ。 m_DialogId ダイアログ ボックスのリソース識別子。 m_Dlg プロパティ ページのダイアログ ボックス ウィンドウ ハンドル。 m_hwnd プロパティ ページのウィンドウ ハンドル。 m_pPageSite フィルタのプロパティ情報にアクセスするために使用される IPropertyPage インターフェイスのポインタ。 m_TitleId プロパティ ページのタイトルのリソース識別子。
CBasePropertyPage CBasePropetyPage オブジェクトを作成する。
OnActivate プロパティ ページがアクティブにされたときに呼び出される。 OnApplyChanges ユーザーがプロパティ ページに対する変更を適用したときに呼び出される。 OnConnect プロパティ ページがフィルタに接続されたときに呼び出される。 OnDeactivate プロパティ ページが消去されたときに呼び出される。 OnDisconnect プロパティ ページが所有するフィルタから切断されたときに呼び出される。 OnReceiveMessage メッセージがプロパティ ページのダイアログ ボックス ウィンドウに送信されたときに呼び出される。
実装される INonDelegatingUnknown メソッド
NonDelegatingAddRef デフォルトの実装は、所有するフィルタの参照カウントをインクリメントする。 NonDelegatingQueryInterface CBasePropertyPage インターフェイスを取得するために呼び出される。派生クラスで追加されるインターフェイスにポインタを渡すには、このメンバ関数をオーバーライドする。 NonDelegatingRelease デフォルトの実装は、所有するフィルタの参照カウントをデクリメントする。
Activate プロパティ ページのダイアログ ボックス ウィンドウを作成する。 Apply 現在のプロパティ ページの値を下位のオブジェクトに適用する。 Deactivate CBasePropertyPage::Activate で作成したウィンドウを破棄する。 GetPageInfo プロパティ ページに関する情報を取得する。 Help ユーザー要求に応答してヘルプを呼び出す。 IsPageDirty プロパティ ページが、アクティブにされた後、または CBasePropertyPage::Apply を最後に呼び出した後、変更されたかどうかを示す。 Move プロパティ ページのダイアログ ボックスをフレーム内に配置およびサイズ変更する。 SetObjects このプロパティ ページに関連付けられたオブジェクトの IUnknown ポインタの配列をプロパティ ページに提供する。 SetPageSite プロパティ ページを初期化し、プロパティ ページがプロパティ フレームと通信するために使用する IPropertyPageSite インターフェイスへのポインタをプロパティ ページに提供する。 Show プロパティ ページのダイアログ ボックスを表示または非表示にする。 TranslateAccelerator 処理するキーストロークを指定する MSG 構造体へのポインタを提供する。
プロパティ ページのダイアログ ボックスを作成する。
構文
HRESULT Activate( HWND hwndParent, LPCRECT prect, BOOL fModal );
パラメータ
- hwndParent
- ダイアログ ボックスの親ウィンドウのハンドル。
- prect
- ダイアログ ボックスの画面上の位置を格納する RECT 構造体へのポインタ。
- fModal
- TRUE の場合はモーダル ダイアログ ボックス、FALSE の場合はモードレス ダイアログ ボックスを指定する値。
戻り値
ダイアログ ボックスの作成に失敗した場合は E_OUTOFMEMORY、プロパティ ページが既に存在している場合は E_UNEXPECTED を返す。
注意
このメンバ関数は、COM の IPropertyPage::Active メソッドを実装する。このメソッドは、親ウィンドウとして hwndParent を、配置矩形として prect を使用して、(フレーム、キャプション、システム メニュー、またはコントロールのない) プロパティ ページのダイアログ ボックスを作成する。
プロパティ ページはこの処理で作成したウィンドウ ハンドルを保持し、CBasePropertyPage::Deactivate でこのダイアログ ボックスを破棄するときに使用する。
現在のプロパティ ページの値を下位のオブジェクトに適用する。
構文
HRESULT Apply(void);
戻り値
CBasePropertyPage::SetObjects が呼び出されていない場合、または m_pPageSite データ メンバがフィルタのプロパティ ページへのポインタを使用して初期化されていない場合は、E_UNEXPECTED を返す。
注意
このメンバ関数は、COM の IPropertyPage::Apply メソッドを実装する。変更されるオブジェクトは、CBasePropertyPage::SetObjects への以前の呼び出しによって提供される。これは、フィルタの IUnknown インターフェイスでなければならない。したがって、このメンバ関数は、インターフェイスが存在しない場合に失敗してはならない。
このメンバ関数は、m_bDirty データ メンバを FALSE に設定し、仮想メンバ関数 CBasePropertyPage::OnApplyChanges を呼び出す。プロパティに対する変更を適用するには、派生クラスでこの仮想メンバ関数をオーバーライドする必要がある。
CBasePropetyPage オブジェクトを作成する。
構文
CBasePropertyPage( TCHAR *pName, LPUNKNOWN pUnk, int DialogId, int TitleId );
パラメータ
- pName
- デバッグのために使用されるプロパティ ページ オブジェクトの名前へのポインタ。
- pUnk
- COM 委任オブジェクトへのポインタ。
- DialogId
- ダイアログ ボックスのリソース ID。
- TitleId
- ダイアログ ボックスのタイトルのリソース ID。
注意
このコンストラクタは、CBasePropertyPage データ メンバを次のように設定する。
- m_DialogId は DialogId に設定される。
- m_TitleId は TitleId に設定される。
- m_hwnd は NULL に設定される。
- m_Dlg は NULL に設定される。
- m_pPageSite は NULL に設定される。
- m_bDirty は FALSE に設定される。
CBasePropertyPage::Activate で作成したウィンドウを破棄する。
構文
HRESULT Deactivate(void);
戻り値
データ メンバ m_hwnd がプロパティ ページのウィンドウ ハンドルを含んでいない場合は、E_UNEXPECTED を返す。
注意
このメンバ関数は、COM の IPropertyPage::Deactivate メソッドを実装する。このメンバ関数は、仮想メンバ関数 CBasePropertyPage::OnDeactivate を呼び出して、プロパティ ページのダイアログ ボックスを破棄する。
プロパティ ページに関する情報を取得する。
構文
HRESULT GetPageInfo( LPPROPPAGEINFO pPageInfo );
パラメータ
- pPageInfo
- プロパティ ページがそのページ情報を格納する、呼び出し元割り当て済み PROPPAGEINFO 構造体へのポインタ。この構造体に格納されるすべての割り当ては、呼び出し元の責任になる。
戻り値
関数がプロパティ ページのタイトルにメモリを割り当てることができなかった場合は、E_OUTOFMEMORY を返す。
注意
このメンバ関数は、COM の IPropertyPage::GetPageInfo メソッドを実装する。このメンバ関数は、GetDialogSize 関数を呼び出して、ダイアログ ボックスのサイズを取得し、この呼び出しが失敗した場合はダイアログ ボックスのサイズをデフォルト値に設定する。
ユーザー要求に応答してヘルプを呼び出す。
構文
HRESULT Help( LPCWSTR lpszHelpDir );
パラメータ
- lpszHelpDir
- レジストリ内でプロパティ ページの CLSID 情報の HelpDir キーの下にある文字列へのポインタ。HelpDir が存在しない場合は、InProcServer32 エントリで見つかったパスからサーバー ファイル名を除いたものになる。
戻り値
デフォルトでは E_NOTIMPL を返す。
注意
このメンバ関数は、COM の IPropertyPage::Help メソッドを実装するが、プレースホルダとしてである。この関数は、E_NOTIMPL を返す以外は何もしない。
このメンバ関数の呼び出しは、CBasePropertyPage::Activate の呼び出しと CBasePropertyPage::Deactivate の呼び出しの間で行う必要がある。
ページがこのメンバ関数で失敗した場合 (E_NOTIMPL など)、フレームは CBasePropertyPage::GetPageInfo を使用して取得された PROPPAGEINFO 構造体の pszHelpFile および dwHelpContext フィールドを使用しようとする。したがって、派生クラスは CBasePropertyPage::Help を実装するか、CBasePropertyPage::GetPageInfo を使用してヘルプ情報を返す必要がある。
プロパティ ページが、アクティブにされた後、または CBasePropertyPage::Apply を最後に呼び出した後、変更されたかどうかを示す。
構文
HRESULT IsPageDirty(void);
戻り値
プロパティ ページの値の状態がダーティーである場合、つまり、値が変更され、オブジェクトの状態と異なる場合は、S_OK を返す。ページの値の状態が変更されておらず、オブジェクトの現在の状態と同じである場合は、S_FALSE を返す。
注意
このメンバ関数は、COM の IPropertyPage::IsPageDirty メソッドを実装する。このメンバ関数は、m_bDirty データ メンバの値を返す。
プロパティ ページのダイアログ ボックスをフレーム内に配置およびサイズ変更する。
構文
HRESULT Move( LPCRECT prect );
パラメータ
- prect
- プロパティ ページのダイアログ ボックスの位置情報を格納する RECT 構造体へのポインタ。
戻り値
データ メンバ m_hwnd がプロパティ ページのウィンドウ ハンドルを含んでいない場合は、E_UNEXPECTED を返す。
注意
このメンバ関数は、Microsoft® Win32® MoveWindow 関数を呼び出すことによって、COM の IPropertyPage::Move メソッドを実装する。このメンバ関数は、プロパティ ページのダイアログ ボックスを配置するために、CBasePropertyPage::Activate メンバ関数から呼び出される。
インターフェイスの参照カウントをインクリメントする。
構文
ULONG NonDelegatingAddRef(void);
戻り値
オブジェクトの参照カウントを返す。
注意
このメンバ関数は、INonDelegatingUnknown::NonDelegatingAddRef メソッドを実装する。所有するフィルタの参照カウントをインクリメントする。
インターフェイスを取得し、参照カウントをインクリメントする。
構文
HRESULT NonDelegatingQueryInterface( REFIID riid, void **ppv );
パラメータ
- riid
- 参照識別子。
- ppv
- インターフェイスへのポインタのアドレス。
戻り値
ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。
注意
このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装し、IPropertyPage インターフェイスへの参照を渡す。次に、基底クラスのメンバ関数 CUnknown::NonDelegatingQueryInterface を呼び出す。このクラスをオーバーライドして、派生クラスのオブジェクトのその他のインターフェイスを返す。
インターフェイスの参照カウントをデクリメントする。
構文
ULONG NonDelegatingRelease(void);
戻り値
参照カウントを返す。
注意
このメンバ関数は、INonDelegatingUnknown::NonDelegatingRelease メソッドを実装する。これは所有するフィルタへの参照カウントを解放する。
プロパティ ページがアクティブにされたときに呼び出される。
構文
virtual HRESULT OnActivate(void);
戻り値
デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。
注意
このメンバ関数は、プロパティ ページが表示されたときに派生クラスに通知するために、CBasePropertyPage::Activate メンバ関数から呼び出される。ダイアログ ボックスの値を初期化するには、このメンバ関数をオーバーライドする。この処理は、(オーバーライドされた CBasePropertyPage::OnConnect メンバ関数で) プロパティ ページが接続されたときに初期化された以前のデータ メンバの値を使用して Win32 SetDlgItemText 関数を呼び出すことによって行うことができる。
次に例を示す。
// プロパティ ページのテキスト フィールドを設定する。 HRESULT CQualityProperties::OnActivate() { SetEditFieldData(); return NOERROR; } // プロパティ ページのフィールドを初期化する。 void CQualityProperties::SetEditFieldData() { ASSERT(m_pQualProp); TCHAR buffer[50]; wsprintf(buffer,"%d", m_iDropped); SendDlgItemMessage(m_Dlg, IDD_QDROPPED, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer); wsprintf(buffer,"%d", m_iDrawn); SendDlgItemMessage(m_Dlg, IDD_QDRAWN, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer); wsprintf(buffer,"%d.%02d", m_iFrameRate/100, m_iFrameRate%100); SendDlgItemMessage(m_Dlg, IDD_QAVGFRM, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer); wsprintf(buffer,"%d", m_iFrameJitter); SendDlgItemMessage(m_Dlg, IDD_QJITTER, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer); wsprintf(buffer,"%d", m_iSyncAvg); SendDlgItemMessage(m_Dlg, IDD_QSYNCAVG, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer); wsprintf(buffer,"%d", m_iSyncDev); SendDlgItemMessage(m_Dlg, IDD_QSYNCDEV, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer); }
ユーザーがプロパティ ページに対する変更を適用したときに呼び出される。
構文
virtual HRESULT OnApplyChanges(void);
戻り値
デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。
注意
プロパティ ページでユーザーがプロパティ値を設定できる場合は、このメンバ関数をオーバーライドする。このメンバ関数が呼び出されると、変更されたプロパティが処理される。たとえば、派生クラスで適切なデータ メンバを新しい値に設定したり、フィルタでメソッドを呼び出してプロパティを設定する。このメンバ関数が終了するときに、オブジェクト内のプロパティがプロパティ ページ内のプロパティを反映しない場合は、オーバーライドするメンバ関数で CBasePropertyPage::IsPageDirty を呼び出して m_bDirty データ メンバを TRUE に設定する。
プロパティ ページがフィルタに接続されたときに呼び出される。
構文
virtual HRESULT OnConnect( IUnknown *pUnknown );
パラメータ
- pUnknown
- プロパティ ページに関連付けられたフィルタの IUnknown インターフェイスへのポインタ。
戻り値
デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。
注意
このメンバ関数は、CBasePropertyPage::SetObjects メンバ関数から ppUnk パラメータを指定して呼び出される。このパラメータはフィルタの IUnknown インターフェイスでなければならない。後で (CBasePropertyPage::OnActivate で) プロパティ ページのダイアログ ボックスに送信されるプロパティ値を取得するには、このメンバ関数をオーバーライドする。
次の例は、このメンバ関数の使用方法を示している。
// 通信するためのフィルタを指定する。 HRESULT CQualityProperties::OnConnect(IUnknown *pUnknown) { ASSERT(m_pQualProp == NULL); // レンダラに IQualProp インターフェイスを問い合わせる。 HRESULT hr = pUnknown->QueryInterface(IID_IQualProp,(void **)&m_pQualProp); if (FAILED(hr)) { return E_NOINTERFACE; } ASSERT(m_pQualProp); // ページの品質 データを取得する。 m_pQualProp->get_FramesDroppedInRenderer(&m_iDropped); m_pQualProp->get_FramesDrawn(&m_iDrawn); m_pQualProp->get_AvgFrameRate(&m_iFrameRate); m_pQualProp->get_Jitter(&m_iFrameJitter); m_pQualProp->get_AvgSyncOffset(&m_iSyncAvg); m_pQualProp->get_DevSyncOffset(&m_iSyncDev); return NOERROR; }
プロパティ ページが消去されたときに呼び出される。
構文
virtual HRESULT OnDeactivate(void);
戻り値
デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。
注意
このメンバ関数は、ユーザーがプロパティ ページを閉じたときに、CBasePropertyPage::Deactivate メンバ関数から呼び出される。その時点で特別な処理を行うには、このメンバ関数をオーバーライドする。
プロパティ ページが所有するフィルタから切断されたときに呼び出される。
構文
virtual HRESULT OnDisconnect(void);
戻り値
デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。
注意
このメンバ関数は、プロパティ ページがフィルタから切断されたときに、CBasePropertyPage::SetObjects メンバ関数から呼び出される。下位のプロパティ インターフェイスで参照カウントを解放するなど、その時点で特別な処理を行うには、このメンバ関数をオーバーライドする。
次の例は、このメンバ関数を派生クラスに実装する方法を示している。
// 保持している IQualProp インターフェイスを解放する。 HRESULT CQualityProperties::OnDisconnect() { // インターフェイスを解放する。 if (m_pQualProp == NULL) { return E_UNEXPECTED; } m_pQualProp->Release(); m_pQualProp = NULL; return NOERROR; }
メッセージがプロパティ ページのダイアログ ボックスに送信されたときに呼び出される。
構文
virtual BOOL OnReceiveMessage( HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam );
パラメータ
- hwnd
- メッセージを受信するウィンドウ プロシージャ。
- uMsg
- メッセージ。
- wParam
- 追加のメッセージ情報。このパラメータの内容は、uMsg パラメータの値によって異なる。
- lParam
- 追加のメッセージ情報。このパラメータの内容は、uMsg パラメータの値によって異なる。
戻り値
デフォルトでは、Win32 DefWindowProc 関数によって返される値を返す。
注意
このメンバ関数のデフォルトの実装は、指定されたパラメータを使用して DefWindowProc を呼び出す。メッセージに特別な処理が必要な場合は、このメンバ関数をオーバーライドする。
このプロパティ ページに関連付けられたオブジェクトの IUnknown ポインタをプロパティ ページに提供する。
構文
HRESULT SetObjects( ULONG cObjects, LPUNKNOWN *ppUnk );
パラメータ
- cObjects
- ppUnk で示される配列内の IUnknown ポインタの数。この数値は 1 または 0 でなければならない。0 の場合、プロパティは以前にこのメソッドに渡されたポインタを解放しなければならない。
- ppUnk
- このプロパティ ページ (およびその他のプロパティ ページ) が表示されるプロパティ シートによって影響を受ける一意のオブジェクトを識別する単一の IUnknown インターフェイスへのポインタのアドレス。プロパティ ページは、IUnknown::AddRef を呼び出すことによって、このポインタをキャッシュしなければならない。
戻り値
ppUnk が Null の場合は E_POINTER、cObjects が 1 よりも大きい場合は E_UNEXPECTED、それ以外の場合はこのメンバ関数が呼び出した CBasePropertyPage::OnConnect または CBasePropertyPage::OnDisconnect メンバ関数によって返された値を返す。
注意
このメンバ関数は、COM の IPropertyPage::SetObjects メソッドを実装する。このメンバ関数は、cObjects の値が 1 の場合は仮想メンバ関数 CBasePropertyPage::OnConnect を呼び出し、cObjects の値が 0 の場合は仮想メンバ関数 CBasePropertyPage::OnDisconnect を呼び出す。このプロパティ ページが適用されるインターフェイスを取得したり (IUnknown::AddRef を呼び出す)、解放する (IUnknown::Release を呼び出す) には、この仮想メンバ関数をオーバーライドする。
呼び出し元は、CBasePropertyPage::Activate を呼び出す前に、このオブジェクトをプロパティ ページに提供し、ページを非アクティブにするとき、またはオブジェクトを完全に解放するときに、パラメータとして 0-v を指定して SetObjects を呼び出す必要がある。
このメンバ関数では、オブジェクトを 1 つだけプロパティ ページに関連付けることができる。
プロパティ ページを初期化し、プロパティ ページがプロパティ フレームと通信するために使用する IPropertyPageSite インターフェイスへのポインタをプロパティ ページに提供する。
構文
HRESULT SetPageSite( LPPROPERTYPAGESITE pPageSite );
パラメータ
- pPageSite
- プロパティ シート内のこのプロパティ ページを管理し、サービスを提供するページ サイトの IPropertyPageSite インターフェイスへのポインタ。
戻り値
m_pPageSite データ メンバがフィルタのプロパティ ページへのポインタを使用して初期化されていない場合は、E_UNEXPECTED を返す。
注意
このメンバ関数は、COM の IPropertyPage::SetPageInfo メソッドを実装する。IPropertyPageSite インターフェイスが渡されると、このメンバ関数はインターフェイスへの参照をカウントし、m_pPageSite に割り当てる。Null 値が渡されると、IPropertyPageSite インターフェイスの参照カウントを解放する。
プロパティ ページのダイアログ ボックスを表示または非表示にする。
構文
HRESULT Show( UINT nCmdShow );
パラメータ
- nCmdShow
- 表示するかどうかを記述するコマンド。SW_SHOWNORMAL、SW_SHOW、および SW_HIDE のみ使用できる。
戻り値
データ メンバ m_hwnd がプロパティ ページのウィンドウ ハンドルを含んでいない場合は、E_UNEXPECTED を返す。nCmdShow パラメータが、SW_SHOW、SW_SHOWNORMAL (表示) または SW_HIDE (非表示) ではない場合は、E_INVALIDARG を返す。
注意
ページが表示に設定された場合、ページはそのページ自体にフォーカスを設定する必要がある。具体的には、ページの最初のプロパティにフォーカスを設定する。このメンバ関数は、COM の IPropertyPage::Show メソッドを実装する。このメンバ関数は、nCmdShow の値を SHOW_NORMAL にして、CBasePropertyPage::Activate メンバ関数を終了する直前に呼び出される。
処理するキーストロークを指定する MSG 構造体へのポインタを提供する。
構文
HRESULT TranslateAccelerator( LPMSG lpMsg );
パラメータ
- lpMsg
- 処理するキーストロークを記述する MSG 構造体へのポインタ。
戻り値
デフォルトでは E_NOTIMPL を返す。
注意
このメンバ関数は、COM の IPropertyPage::TranslateAccelerator メソッドを実装する。このメンバ関数の呼び出しは、CBasePropertyPage::Activate を呼び出した後、対応する CBasePropertyPage::Deactivate を呼び出す前に行う必要がある。プロパティ ページのショートカット キーを実装するには、このメンバ関数をオーバーライドする。