IExplorerBrowser
COM公式ドキュメント
IExplorerBrowser は、ナビゲーション操作を行うことも、データオブジェクトのビューをホストすることもできるブラウザーオブジェクトです。本格的なブラウザーオブジェクトとして、自動トラベルログ機能もサポートします。
解説(Remarks)
IExplorerBrowser とそのメソッドの典型的な使用例を示すサンプルコードについては、Explorer Browser Custom Contents および Explorer Browser Custom Contents のサンプルを参照してください。
このオブジェクトの Initialize メソッドを呼び出した後は、Initialize の呼び出しで生成されたウィンドウリソースを解放するために、Destroy メソッドを呼び出す必要があります。
ExplorerBrowser オブジェクトをホストするオブジェクトは、IServiceProvider を派生元とし、サービスへの問い合わせに応答するために QueryService を実装する必要があります。たとえば、ブラウザーが表示するペインの数は、IExplorerPaneVisibility を実装し、SID_ExplorerPaneVisibility サービス要求に応答することで制御できます。
フレームは既定で無効になっています。フレームを有効にして既定のペインセットを取得するには、IExplorerBrowser::SetOptions メソッドを使用して EBO_SHOWFRAMES フラグを設定します。IExplorerPaneVisibility 定数として一覧表示される既定のペインは次のとおりです。
- EP_NavPane
- EP_Commands
- EP_Commands_Organize
- EP_Commands_View
- EP_DetailsPane
- EP_PreviewPane
- EP_QueryPane
- EP_AdvQueryPane
- EP_StatusBar
- EP_Ribbon
ExplorerBrowser オブジェクトのクライアントは、ICommDlgBrowser、ICommDlgBrowser2、または ICommDlgBrowser3 の各インターフェイスを実装し、ブラウザー上で ICommDlgBrowser インターフェイスが呼び出されたとき(通常はユーザー操作の結果としてビューから呼び出される)に呼び出される QueryService の実装内で、SID_SExplorerBrowserFrame サービス要求に応答できます。IFolderFilterSite::SetFilter の呼び出しによってブラウザーにフォルダーフィルターが設定されている場合、クライアントは ICommDlgBrowser::IncludeObject の呼び出しを受け取らない点に注意してください。
一部の古いアプリケーションとの互換性を保つため、既定のシェルビュー(DefView)は、フィルター処理(たとえば検索フォルダーによって実行される検索処理)を UI スレッド上で行います。新しいアプリケーションでは、通常これは望ましくありません。検索はバックグラウンドスレッドで実行されるべきです。UI スレッドでのフィルター処理を停止し、代わりにバックグラウンドスレッドでフィルター処理を実行するには、SID_SExplorerBrowserFrame サービス要求を通じて ICommDlgBrowser2 を提供します。ICommDlgBrowser2::GetViewFlags が呼び出されたとき、CDB2GVF_NOINCLUDEITEM を返す必要があります。たとえば、ExplorerBrowser で検索フォルダーにナビゲーションを行い、CDB2GVF_NOINCLUDEITEM を返さない場合、検索全体が完了するまでビューが応答しなくなることがあります。
シェルアーキテクチャには 3 つの主要なコンポーネントがあります。ブラウザー、ビュー、そしてデータソース(たとえば IShellFolder)です。ExplorerBrowser オブジェクトは、現在の場所と、シェル名前空間全体にわたる他の場所へのナビゲーションを管理します。また、トラベルログ(進む/戻るの履歴)も保持します。ビューで何かが起きたとき、たとえばユーザーがフォルダーをダブルクリックしたときに、ブラウザーに通知されます。それに応じて、ブラウザーはその場所へナビゲーションします。データソースは、名前空間内の項目やフォルダーを供給するオブジェクトです。データソースはまた、項目のプロパティや、ビューが要求したときにコンテキストメニューに追加すべき内容など、場所に関する情報も持っています。さらにデータソースは、ある場所で自身の項目を表すためにどのビューを作成すべきかを把握しています。ほぼすべての場合において、フォルダーはシェルの既定のビュー(DefView)を作成します。したがって、ブラウザーはナビゲーションの際、新しい場所に対応する IShellFolder オブジェクトを受け取り、どのビューを作成すべきかを問い合わせます。次にブラウザーはそのビューを作成して表示可能にし、以前の場所を表示していたビューを非表示にしてから破棄します。ビューは、現在の場所に対応する IShellFolder と通信し、項目を列挙するよう要求する責任があります。これにより、ビューはこれらの項目をユーザーに表示できます。ユーザーが項目を操作するにつれて、ビューは IShellFolder と通信し、項目の特定のプロパティや項目のコンテキストメニュー項目など、必要な追加情報を取得します。
アプリケーションが CLSID_ExplorerBrowser によって提供される既定の実装を使用し、それをアプリケーションのウィンドウに挿入してから、ある場所を参照した場合、ExplorerBrowser は参照先の場所によって指定される適切な IShellView を作成します。その後アプリケーションは、現在のビューのインターフェイスを取得するよう ExplorerBrowser に要求でき、必要に応じてビューを直接操作できます。SHCreateShellFolderViewEx によって作成されるエクスプローラービューオブジェクトの既定の実装は、IShellView インターフェイスをサポートします。既定のシェルフォルダービューオブジェクトを取得しているかどうかは、IExplorerBrowser::GetCurrentView を呼び出し、返されたオブジェクトに対してインターフェイス ID IID_CDefView を指定して QueryInterface を呼び出すことで確認できます。
Windows 7 以降。CExplorerBrowser は、サービス ID SID_SInPlaceBrowser を指定した IServiceProvider::QueryService を使用することで、インプレースナビゲーションをサポートできます。SID_SInPlaceBrowser を使用する場合、CExplorerBrowser の状態を EBO_NAVIGATEONCE に設定することはできません。
メソッド 15
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ブラウザーをナビゲーション可能な状態に準備します。
| hwndParent | HWND | in | 所有者ウィンドウまたはコントロールへのハンドル。 |
| prc | RECT* | in | ブラウザーが占有する境界矩形の座標を含む RECT へのポインター。座標は hwndParent を基準とします。 |
| pfs | FOLDERSETTINGS* | inoptional | フォルダーをビュー内でどのように表示するかを決定する FOLDERSETTINGS 構造体へのポインター。このパラメーターが NULL の場合は、IExplorerBrowser::SetFolderSettings を呼び出す必要があります。そうでない場合は、フォルダーの既定のビュー設定が使用されます。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
Initialize メソッドを呼び出した後は、ブラウザーを破棄し、ブラウザーに関連付けられたメモリとウィンドウリソースを解放するために Destroy メソッドを呼び出すことが呼び出し元の責任となります。
ブラウザーを破棄します。
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
IExplorerBrowser::Initialize メソッドを呼び出した場合は、リソースを解放するために IExplorerBrowser::Destroy メソッドを呼び出す必要があります。IExplorerBrowser::Destroy を呼び出さないと、メモリリークが発生する可能性があります。
ブラウザーが作成するビューウィンドウのサイズと位置を設定します。
| phdwp | HDWP* | inoutoptional | DeferWindowPos ハンドルへのポインター。このパラメーターは NULL にできます。 |
| rcBrowser | RECT | in | ブラウザーが占有する座標。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
座標は、IExplorerBrowser::Initialize に渡された hwndParent を基準とします。
プロパティバッグの名前を設定します。
| pszPropertyBag | LPWSTR | in | プロパティバッグの名前を含む、定数の null 終端 Unicode 文字列へのポインター。 クライアントのアプリケーション固有のビュー状態情報は、この名前を使用して格納(永続化)されます。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
ExplorerBrowser は、関数 SHGetViewStatePropertyBag を呼び出すことで、プロパティバッグに格納されたプロパティを取得できます。 ExplorerBrowser はこのプロパティバッグに書き込みを行い、その内容はレジストリにも格納(永続化)されます。永続化は、ExplorerBrowser が現在のビューを破棄したとき、ナビゲーションを開始したとき、または破棄されたときに自動的に行われます。これらのイベントのいずれかが発生した後、ユーザーによって変更されている可能性を考慮して、ビュー状態に関する情報を書き込みます。
プロパティが格納されていない場合は、ExplorerBrowser の既定のビュー状態が使用されます。既定のビュー状態とは、ユーザーが特定の場所に対して設定したビュー状態です。ある場所のビュー状態が設定されていない場合(ユーザーによって一度も変更されていない場合)、既定のビュー状態は、その場所にあるファイルの種類(たとえばドキュメント、音楽、画像)のテンプレートに基づきます。すべてのエクスプローラーウィンドウは、既定のビュー状態を決定するために同じ手順を使用します。
既定の空テキストを設定します。
| pszEmptyText | LPWSTR | in | 空テキストを含む、定数の null 終端 Unicode 文字列へのポインター。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
設定したテキストは、エクスプローラーブラウザービューが空のときに表示されます。
このメソッドは、空テキスト文字列を現在のビューに適用するとともに、別の場所へナビゲーションする際に使用される既定の空テキスト文字列を設定します。
このメソッドが呼び出されない場合、空テキストは、ナビゲーション先のフォルダーが提供するテキストが既定として使用されます。
現在のビューのフォルダー設定を設定します。
| pfs | FOLDERSETTINGS* | in | 適用するフォルダー設定を含む FOLDERSETTINGS 構造体へのポインター。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
このメソッドは、別の場所へナビゲーションする際に適用される既定値も変更します。
セッション間でビュー状態が保持されるようにするには、IExplorerBrowser::SetPropertyBag を使用して永続化名を指定してください。
イベントコールバックのために IExplorerBrowser との接続を開始します。
| psbe | IExplorerBrowserEvents* | in | IExplorerBrowser イベントの通知を受けるオブジェクトの IExplorerBrowserEvents インターフェイスへのポインター。 |
| pdwCookie | DWORD* | out | このメソッドが返るとき、イベントリスナーを一意に識別するトークンが格納されます。これにより、複数のイベントリスナーを同時に登録できます。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
このメソッドは、IExplorerBrowserEvents の実装者によって呼び出されます。実装者(リスナー)は、IExplorerBrowserEvents のメソッドのコールバックによって、ExplorerBrowser のビューイベントおよびナビゲーションイベントの通知を受けます。
最初の IExplorerBrowser ナビゲーションより前に、アドバイザリ接続を開始するために IExplorerBrowser::Advise を呼び出してください。イベントリスナーへのコールバックは、ブラウザーが参照処理を行う際に発生します。
最初の参照処理は、IExplorerBrowser::BrowseToObject などの呼び出しに対して同期的に行われます。以降のコールバックは、ブラウザーが参照処理を行うにつれて非同期に発生します。
接続が不要になったら、IExplorerBrowser::Unadvise メソッドを呼び出して接続を終了してください。
アドバイザリ接続を終了します。(IExplorerBrowser.Unadvise)
| dwCookie | DWORD | in | 以前に IExplorerBrowser::Advise から返された接続トークン。終了する接続を識別します。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
以前に IExplorerBrowser::Advise メソッドを通じて確立されたアドバイザリ接続を終了します。dwCookie パラメーターは、終了する接続を識別します。IExplorerBrowser::Unadvise を呼び出さないと、メモリリークが発生する可能性があります。
現在のブラウザーオプションを設定します。
| dwFlag | EXPLORER_BROWSER_OPTIONS | in | 設定する 1 つ以上の EXPLORER_BROWSER_OPTIONS フラグ。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
この操作は、以前のオプションをすべて上書きします。
フレームは既定で無効になっています。フレームを有効にして既定のペインセットを取得するには、SetOptions メソッドを使用して EBO_SHOWFRAMES フラグを設定します。IExplorerPaneVisibility 定数として一覧表示される既定のペインは次のとおりです。
- EP_NavPane
- EP_Commands
- EP_Commands_Organize
- EP_Commands_View
- EP_DetailsPane
- EP_PreviewPane
- EP_QueryPane
- EP_AdvQueryPane
- EP_StatusBar
- EP_Ribbon
現在のブラウザーオプションを取得します。
| pdwFlag | EXPLORER_BROWSER_OPTIONS* | out | このメソッドが返るとき、ブラウザーの現在の EXPLORER_BROWSER_OPTIONS が格納されます。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
項目識別子リスト(PIDL)へのポインターを指定してナビゲーションします。
| pidl | ITEMIDLIST* | in | ナビゲーション先としてオブジェクトの場所を指定する const ITEMIDLIST(項目識別子リスト)へのポインター。このパラメーターは NULL にできます。詳細については「解説」を参照してください。 |
| uFlags | DWORD | in | pidl のカテゴリを指定するフラグ。これはナビゲーションの実行方法に影響します。値は 0 か、次の値のビットごとの組み合わせでなければなりません。 SBSP_ABSOLUTEデスクトップを基準とする絶対 PIDL。 SBSP_RELATIVE現在のフォルダーを基準とする相対 PIDL。 SBSP_PARENT親フォルダーへナビゲーションし、PIDL は無視します。 SBSP_NAVIGATEBACK戻る方向へナビゲーションし、PIDL は無視します。 SBSP_NAVIGATEFORWARD進む方向へナビゲーションし、PIDL は無視します。 SBSP_KEEPWORDWHEELTEXTWindows Vista 以降。このフラグは、WordWheel(Windows エクスプローラーの検索ボックス)に入力された検索テキストをこのナビゲーション中に保持し、新しい場所の項目が以前の場所と同じ方法でフィルターされるようにすることを示します。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
uFlags に指定されたフラグが組み込みの TravelLog を通じたナビゲーション(すなわち SBSP_NAVIGATEBACK または SBSP_NAVIGATEFORWARD)を示す場合、パラメーター pidl は NULL にできます。
このメソッドは、shobjidl.h ファイルに列挙されている SBSP フラグの一部のみをサポートします。したがって、uFlags に SBSP_NEWBROWSER または SBSP_EXPLOREMODE が指定された場合、このメソッドは E_INVALIDARG を返します。
オブジェクトへナビゲーションします。
| punk | IUnknown* | in | ナビゲーション先のオブジェクトへのポインター。オブジェクトを参照できない場合は、エラー値が返されます。 |
| uFlags | DWORD | in | pidl のカテゴリを指定するフラグ。これはナビゲーションの実行方法に影響します。値は 0 か、次の値のビットごとの組み合わせでなければなりません。 SBSP_ABSOLUTEデスクトップを基準とする絶対 PIDL。 SBSP_RELATIVE現在のフォルダーを基準とする相対 PIDL。 SBSP_PARENT親フォルダーを参照し、PIDL は無視します。 SBSP_NAVIGATEBACK戻る方向へナビゲーションし、PIDL は無視します。 SBSP_NAVIGATEFORWARD進む方向へナビゲーションし、PIDL は無視します。 SBSP_KEEPWORDWHEELTEXTWindows Vista 以降。このフラグは、WordWheel(Windows エクスプローラーの検索ボックス)に入力された検索テキストをこのナビゲーション中に保持し、新しい場所の項目が以前の場所と同じ方法でフィルターされるようにすることを示します。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
uFlags には、EXPLORER_BROWSER_FILL_FLAGS のいずれか、または BrowseObject の wFlags パラメーターで定義されているフラグ(ナビゲーションを示すフラグを除く)のいずれかを指定できます。
このメソッドは GetIDList を呼び出し、返された pidl へナビゲーションします。punk を NULL にできない点を除き、IExplorerBrowser::BrowseToIDList と同じように動作します。標準的な使い方は、IShellFolder または IShellItem へナビゲーションすることです。渡されたオブジェクトを参照できない場合はエラーが返されます。参照可能なオブジェクトは、IPersistFolder2 または IPersistIDList のいずれかを実装しています。
IExplorerBrowser の最初のナビゲーションは同期的です。それ以降のナビゲーションはすべて非同期です。そのため、保留中のナビゲーションを正しく設定していれば IExplorerBrowser::BrowseToObject の呼び出しは成功しますが、それはナビゲーション自体の成功を保証するものではありません。成功と失敗の通知を受けるには、クライアントは IExplorerBrowserEvents を実装し、OnNavigationComplete および OnNavigationFailed で適切に応答する必要があります。
結果フォルダーを作成し、項目を格納します。
| punk | IUnknown* | in | IResultsFolder を満たすソースオブジェクトへのインターフェイスポインター。これは IDataObject、または INamespaceWalk とともに使用できる任意のオブジェクトです。 |
| dwFlags | EXPLORER_BROWSER_FILL_FLAGS | in | EXPLORER_BROWSER_FILL_FLAGS 値のいずれか 1 つ。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
インターフェイスポインター punk を介して渡されたオブジェクトが IResultsFolder を満たします。
パラメーター dwFlags には、EXPLORER_BROWSER_FILL_FLAGS のいずれか、または BrowseObject の wFlags パラメーターで定義されているフラグ(ナビゲーションを示すフラグを除く)のいずれかを指定できます。
パラメーター punk には、INamespaceWalk が処理できる任意のオブジェクトを指定できます。EBF_SELECTFROMDATAOBJECT を指定して呼び出す場合、punk は IDataObject でなければなりません。この場合、名前空間はデータオブジェクトの親レベルで走査され、すべてのピア項目が含まれますが、データオブジェクトに含まれる項目のみが選択されます。このフラグは、FOLDERSETTINGS で FWF_CHECKSELECT が有効になっているときに最もよく使用され、データオブジェクトにまとめられた一連の項目のチェック選択を可能にします。
結果フォルダー内の項目を直接操作するには、IExplorerBrowser::GetCurrentView を呼び出して ExplorerBrowser からビューを取得し、そのビューに対して GetFolder を使用して結果フォルダーを問い合わせます。こうして取得した結果フォルダーを使用すると、IExplorerBrowser が提供するメソッドよりも柔軟に、フォルダー内のデータを操作できます。
結果フォルダーからすべての項目を削除します。
戻り値
型: HRESULT
成功した場合は S_OK を返します。IExplorerBrowser::FillFromObject の呼び出し前にこのメソッドが呼び出された場合は E_UNEXPECTED を返します。
解説(Remarks)
このメソッドは、IExplorerBrowser::FillFromObject メソッドで作成された IResultsFolder からすべての結果を削除します。
ブラウザーの現在のビューのインターフェイスを取得します。
| riid | GUID* | in | 目的のインターフェイス ID への参照。 |
| ppv | void** | out | このメソッドが返るとき、riid で要求されたインターフェイスポインターが格納されます。これは通常、IShellView、IShellView2、IFolderView、またはそれらに関連するインターフェイスになります。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
IID_PPV_ARGS マクロを使用してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IExplorerBrowser "{DFD3B6B5-C10C-4BE9-85F6-A66969F402F6}" #usecom global IExplorerBrowser IID_IExplorerBrowser "{71F96385-DDD6-48D3-A0C1-AE06E8B055FB}" #comfunc global IExplorerBrowser_Initialize 3 sptr,var,var #comfunc global IExplorerBrowser_Destroy 4 #comfunc global IExplorerBrowser_SetRect 5 sptr,int #comfunc global IExplorerBrowser_SetPropertyBag 6 wstr #comfunc global IExplorerBrowser_SetEmptyText 7 wstr #comfunc global IExplorerBrowser_SetFolderSettings 8 var #comfunc global IExplorerBrowser_Advise 9 sptr,var #comfunc global IExplorerBrowser_Unadvise 10 int #comfunc global IExplorerBrowser_SetOptions 11 int #comfunc global IExplorerBrowser_GetOptions 12 var #comfunc global IExplorerBrowser_BrowseToIDList 13 var,int #comfunc global IExplorerBrowser_BrowseToObject 14 sptr,int #comfunc global IExplorerBrowser_FillFromObject 15 sptr,int #comfunc global IExplorerBrowser_RemoveAll 16 #comfunc global IExplorerBrowser_GetCurrentView 17 var,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IExplorerBrowser "{DFD3B6B5-C10C-4BE9-85F6-A66969F402F6}" #usecom global IExplorerBrowser IID_IExplorerBrowser "{71F96385-DDD6-48D3-A0C1-AE06E8B055FB}" #comfunc global IExplorerBrowser_Initialize 3 sptr,sptr,sptr #comfunc global IExplorerBrowser_Destroy 4 #comfunc global IExplorerBrowser_SetRect 5 sptr,int #comfunc global IExplorerBrowser_SetPropertyBag 6 wstr #comfunc global IExplorerBrowser_SetEmptyText 7 wstr #comfunc global IExplorerBrowser_SetFolderSettings 8 sptr #comfunc global IExplorerBrowser_Advise 9 sptr,sptr #comfunc global IExplorerBrowser_Unadvise 10 int #comfunc global IExplorerBrowser_SetOptions 11 int #comfunc global IExplorerBrowser_GetOptions 12 sptr #comfunc global IExplorerBrowser_BrowseToIDList 13 sptr,int #comfunc global IExplorerBrowser_BrowseToObject 14 sptr,int #comfunc global IExplorerBrowser_FillFromObject 15 sptr,int #comfunc global IExplorerBrowser_RemoveAll 16 #comfunc global IExplorerBrowser_GetCurrentView 17 sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。