IPreviewHandler

リッチプレビューを表示するためのメソッドを公開します。

プレビューハンドラーはマネージドコードで作成できます。通常、すべてのプレビューハンドラーは prevhost.exe と呼ばれるサロゲートプロセス内でまとめてホストされます。このプロセスには、通常の整合性レベルで実行されるプレビューハンドラー用のインスタンスと、低整合性レベルで実行されるプレビューハンドラー用のインスタンスの 2 つがあります。ハンドラーをマネージドコードで実装する場合、そのハンドラーはこれら共有プロセスのいずれの内部でも実行すべきではありません。代わりに、レジストリに新しい AppID エントリを作成し(DllSurrogate 値として prevhost.exe を指定)、それをハンドラーのクラス ID のレジストリ値内の AppID 値として設定することで、ハンドラーが prevhost.exe の新しいインスタンスを取得するようにしてください。これにより、他のハンドラーが使用する共通インスタンスではなく、ハンドラー専用の一意の prevhost.exe インスタンスが作成されます。

プレビューウィンドウの親ウィンドウ、および親ウィンドウ内でプレビューウィンドウに使用する領域を設定します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

プレビューハンドラーは、prc で定義された領域全体の描画を担当します。プレビューウィンドウが既に作成されている場合、プレビューハンドラーはそのプレビューウィンドウを新しい親 hwnd に関連付け、prc で定義された領域にサイズ変更する必要があります。プレビューウィンドウがまだ作成されていない場合、プレビューハンドラーは、IPreviewHandler::DoPreview でプレビューウィンドウが作成されるときのためにこの情報を保持しておく必要があります。

親 hwnd 内でプレビューハンドラーが描画する領域を変更するようプレビューハンドラーに指示します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

プレビューハンドラーウィンドウが作成される前に呼び出された場合、新しい RECT は、以前の IPreviewHandler::SetWindow 呼び出しで受け取った RECT を置き換えます。

プレビューハンドラーウィンドウが作成された後に呼び出された場合、プレビューハンドラーウィンドウをサイズ変更する必要があります。

プレビューハンドラーが既にレンダリング中の場合、レンダリング処理を中断せずにプレビューをサイズ変更する必要があります。

以前の Initialize メソッド呼び出しで指定されたソースからデータを読み込み、プレビューウィンドウへのレンダリングを開始するようプレビューハンドラーに指示します。

型: HRESULT

このメソッドは次のいずれかの値を返すことがあります。

プレビューウィンドウがまだ作成されていない場合、このメソッドが呼び出された後に作成する必要があります。プレビューハンドラーは、IPreviewHandler::SetWindow または IPreviewHandler::SetRect で指定された領域の描画を担当します。これらのメソッドがプレビューハンドラーのレンダリング中に呼び出された場合、項目のレンダリングを停止したり再開したりせずに、ウィンドウの親の変更やサイズ変更を行う必要があります。

このメソッドは、IPreviewHandler::SetWindow が呼び出された後にのみ呼び出す必要があります。

さらに、このメソッドは、IInitializeWithItem::Initialize、IInitializeWithStream::Initialize、または IInitializeWithFile::Initialize が呼び出された後にのみ呼び出す必要があります。

プレビューのレンダリングを停止し、初期化時に渡された項目に基づいて割り当てられたすべてのリソースを解放するようプレビューハンドラーに指示します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

呼び出されると、プレビューウィンドウが破棄されます。

このメソッドは、IInitializeWithItem::Initialize、IInitializeWithStream::Initialize、または IInitializeWithFile::Initialize が呼び出された後にのみ呼び出す必要があります。この初期化に関連付けられたすべてのリソースが解放されます。IPreviewHandler::DoPreview を呼び出す前に、このプレビューハンドラーは、いずれかの初期化インターフェイスの呼び出しと IPreviewHandler::SetWindow の呼び出しによって再初期化されます。

プレビューハンドラーに、自身にフォーカスを設定するよう指示します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドは、最初のタブストップにフォーカスを設定するか、最後のタブストップにフォーカスを設定するかを決定するために、SHIFT キーの状態を照会する必要があります。これは、IPreviewHandler::SetFocus が、呼び出し元スレッドによって作成されたウィンドウにフォーカスが設定される場合にのみ成功できるために必要です。

これは、ホストからプレビューハンドラーへ渡されるアクセラレータキーの範囲のすべてであり、他のアクセラレータは渡されません。IPreviewHandler::TranslateAccelerator は、プレビューハンドラーのメッセージポンプから IPreviewHandler オブジェクトへのメッセージにのみ使用されます。

GetFocus 関数の呼び出しから得られる HWND を返すようプレビューハンドラーに指示します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドは、GetFocus 関数が、呼び出し元スレッドによって作成されたウィンドウにフォーカスがある場合にのみ成功できるために必要です。このメソッドは、タブ順序を管理し、プレビューハンドラーのウィンドウへのタブ移動およびウィンドウからのタブ移動をサポートするためにホストによって使用されます。

プレビューハンドラーが実行されているプロセスのメッセージポンプから渡されたキーストロークを処理するようプレビューハンドラーに指示します。

型: HRESULT

キーストロークメッセージがプレビューハンドラーによって処理できる場合、ハンドラーはそれを処理して S_OK を返します。プレビューハンドラーがキーストロークメッセージを処理できない場合、TranslateAccelerator を使用してホストに提供します。ホストがメッセージを処理した場合、このメソッドは S_OK を返します。ホストがメッセージを処理しない場合、このメソッドは S_FALSE を返します。

この関数は、プレビューハンドラーが実行されているプロセスのメッセージポンプからのみ呼び出されます。この関数により、TranslateAccelerator を使用して、メッセージポンプからホストへキーストロークメッセージを転送できます。

プレビューハンドラーは、そのメッセージポンプからメッセージ(キーストローク)を受け取ると、それをホストへ転送する責任があります。

プレビューハンドラーに対して IObjectWithSite::SetSite が呼び出されると、プレビューハンドラーのホストへの参照が渡されます。オブジェクトは直ちにそのサイトに対して IPreviewHandlerFrame を QueryInterface し、そのポインターを格納する必要があります。

その後、プレビューハンドラーは、キーストロークをフィルタリングするためのアクセラレータテーブルを取得するために GetWindowContext を呼び出すオプションがあります。その後、プレビューは IsAccelerator を使用してキーストロークをそのアクセラレータテーブルと比較し、一致するキーストロークについてのみ IPreviewHandler::TranslateAccelerator を呼び出すことができます。これにより、パフォーマンスがわずかに向上する場合があります。プレビューハンドラーは、DestroyAcceleratorTable 関数を使用してアクセラレータテーブルを解放する必要があります。

プレビューハンドラーがテーブルをまったく使用せず、すべてのキーストロークに対して IPreviewHandler::TranslateAccelerator を呼び出すことも許容されます。低整合性プロセスで実行されるすべてのプレビューハンドラーは、この方法を使用する必要があることに注意してください。

タブキーが押されたとき、プレビューハンドラーに複数のタブストップがある場合、それらのタブストップ内でキーボードフォーカスを移動させる責任があります。現在のキーボードフォーカスがこれらのタブストップの 1 つにあり、キーボードフォーカスを進めると別のプレビューアのタブストップに移動する場合、プレビューアは次のタブストップに対して SetFocus を呼び出す必要があります。それ以外の場合、タブキーはホストに転送され、プレビューアからのタブ移動を処理させる必要があります。