Win32 API 日本語リファレンス
ホームUI.Shell › IExplorerBrowser

IExplorerBrowser

COM
IIDdfd3b6b5-c10c-4be9-85f6-a66969f402f6継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

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 定数として一覧表示される既定のペインは次のとおりです。

詳細については、IExplorerPaneVisibility::GetPaneState を参照してください。

ExplorerBrowser オブジェクトのクライアントは、ICommDlgBrowserICommDlgBrowser2、または 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。

vtbl 3 HRESULT Initialize(HWND hwndParent, RECT* prc, FOLDERSETTINGS* pfs)

ブラウザーをナビゲーション可能な状態に準備します。

hwndParentHWNDin所有者ウィンドウまたはコントロールへのハンドル。
prcRECT*inブラウザーが占有する境界矩形の座標を含む RECT へのポインター。座標は hwndParent を基準とします。
pfsFOLDERSETTINGS*inoptionalフォルダーをビュー内でどのように表示するかを決定する FOLDERSETTINGS 構造体へのポインター。このパラメーターが NULL の場合は、IExplorerBrowser::SetFolderSettings を呼び出す必要があります。そうでない場合は、フォルダーの既定のビュー設定が使用されます。

戻り値

型: HRESULT

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

解説(Remarks)

Initialize メソッドを呼び出した後は、ブラウザーを破棄し、ブラウザーに関連付けられたメモリとウィンドウリソースを解放するために Destroy メソッドを呼び出すことが呼び出し元の責任となります。

vtbl 4 HRESULT Destroy()

ブラウザーを破棄します。

戻り値

型: HRESULT

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

解説(Remarks)

IExplorerBrowser::Initialize メソッドを呼び出した場合は、リソースを解放するために IExplorerBrowser::Destroy メソッドを呼び出す必要があります。IExplorerBrowser::Destroy を呼び出さないと、メモリリークが発生する可能性があります。

vtbl 5 HRESULT SetRect(HDWP* phdwp, RECT rcBrowser)

ブラウザーが作成するビューウィンドウのサイズと位置を設定します。

phdwpHDWP*inoutoptionalDeferWindowPos ハンドルへのポインター。このパラメーターは NULL にできます。
rcBrowserRECTinブラウザーが占有する座標。

戻り値

型: HRESULT

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

解説(Remarks)

座標は、IExplorerBrowser::Initialize に渡された hwndParent を基準とします。

vtbl 6 HRESULT SetPropertyBag(LPWSTR pszPropertyBag)

プロパティバッグの名前を設定します。

pszPropertyBagLPWSTRinプロパティバッグの名前を含む、定数の null 終端 Unicode 文字列へのポインター。 クライアントのアプリケーション固有のビュー状態情報は、この名前を使用して格納(永続化)されます。

戻り値

型: HRESULT

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

解説(Remarks)

ExplorerBrowser は、関数 SHGetViewStatePropertyBag を呼び出すことで、プロパティバッグに格納されたプロパティを取得できます。 ExplorerBrowser はこのプロパティバッグに書き込みを行い、その内容はレジストリにも格納(永続化)されます。永続化は、ExplorerBrowser が現在のビューを破棄したとき、ナビゲーションを開始したとき、または破棄されたときに自動的に行われます。これらのイベントのいずれかが発生した後、ユーザーによって変更されている可能性を考慮して、ビュー状態に関する情報を書き込みます。

プロパティが格納されていない場合は、ExplorerBrowser の既定のビュー状態が使用されます。既定のビュー状態とは、ユーザーが特定の場所に対して設定したビュー状態です。ある場所のビュー状態が設定されていない場合(ユーザーによって一度も変更されていない場合)、既定のビュー状態は、その場所にあるファイルの種類(たとえばドキュメント、音楽、画像)のテンプレートに基づきます。すべてのエクスプローラーウィンドウは、既定のビュー状態を決定するために同じ手順を使用します。

vtbl 7 HRESULT SetEmptyText(LPWSTR pszEmptyText)

既定の空テキストを設定します。

pszEmptyTextLPWSTRin空テキストを含む、定数の null 終端 Unicode 文字列へのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

設定したテキストは、エクスプローラーブラウザービューが空のときに表示されます。

このメソッドは、空テキスト文字列を現在のビューに適用するとともに、別の場所へナビゲーションする際に使用される既定の空テキスト文字列を設定します。

このメソッドが呼び出されない場合、空テキストは、ナビゲーション先のフォルダーが提供するテキストが既定として使用されます。

vtbl 8 HRESULT SetFolderSettings(FOLDERSETTINGS* pfs)

現在のビューのフォルダー設定を設定します。

pfsFOLDERSETTINGS*in適用するフォルダー設定を含む FOLDERSETTINGS 構造体へのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、別の場所へナビゲーションする際に適用される既定値も変更します。

セッション間でビュー状態が保持されるようにするには、IExplorerBrowser::SetPropertyBag を使用して永続化名を指定してください。

vtbl 9 HRESULT Advise(IExplorerBrowserEvents* psbe, DWORD* pdwCookie)

イベントコールバックのために IExplorerBrowser との接続を開始します。

psbeIExplorerBrowserEvents*inIExplorerBrowser イベントの通知を受けるオブジェクトの IExplorerBrowserEvents インターフェイスへのポインター。
pdwCookieDWORD*outこのメソッドが返るとき、イベントリスナーを一意に識別するトークンが格納されます。これにより、複数のイベントリスナーを同時に登録できます。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、IExplorerBrowserEvents の実装者によって呼び出されます。実装者(リスナー)は、IExplorerBrowserEvents のメソッドのコールバックによって、ExplorerBrowser のビューイベントおよびナビゲーションイベントの通知を受けます。

最初の IExplorerBrowser ナビゲーションより前に、アドバイザリ接続を開始するために IExplorerBrowser::Advise を呼び出してください。イベントリスナーへのコールバックは、ブラウザーが参照処理を行う際に発生します。

最初の参照処理は、IExplorerBrowser::BrowseToObject などの呼び出しに対して同期的に行われます。以降のコールバックは、ブラウザーが参照処理を行うにつれて非同期に発生します。

接続が不要になったら、IExplorerBrowser::Unadvise メソッドを呼び出して接続を終了してください。

vtbl 10 HRESULT Unadvise(DWORD dwCookie)

アドバイザリ接続を終了します。(IExplorerBrowser.Unadvise)

dwCookieDWORDin以前に IExplorerBrowser::Advise から返された接続トークン。終了する接続を識別します。

戻り値

型: HRESULT

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

解説(Remarks)

以前に IExplorerBrowser::Advise メソッドを通じて確立されたアドバイザリ接続を終了します。dwCookie パラメーターは、終了する接続を識別します。IExplorerBrowser::Unadvise を呼び出さないと、メモリリークが発生する可能性があります。

vtbl 11 HRESULT SetOptions(EXPLORER_BROWSER_OPTIONS dwFlag)

現在のブラウザーオプションを設定します。

dwFlagEXPLORER_BROWSER_OPTIONSin設定する 1 つ以上の EXPLORER_BROWSER_OPTIONS フラグ。

戻り値

型: HRESULT

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

解説(Remarks)

この操作は、以前のオプションをすべて上書きします。

フレームは既定で無効になっています。フレームを有効にして既定のペインセットを取得するには、SetOptions メソッドを使用して EBO_SHOWFRAMES フラグを設定します。IExplorerPaneVisibility 定数として一覧表示される既定のペインは次のとおりです。

詳細については、IExplorerPaneVisibility::GetPaneState を参照してください。
vtbl 12 HRESULT GetOptions(EXPLORER_BROWSER_OPTIONS* pdwFlag)

現在のブラウザーオプションを取得します。

pdwFlagEXPLORER_BROWSER_OPTIONS*outこのメソッドが返るとき、ブラウザーの現在の EXPLORER_BROWSER_OPTIONS が格納されます。

戻り値

型: HRESULT

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

vtbl 13 HRESULT BrowseToIDList(ITEMIDLIST* pidl, DWORD uFlags)

項目識別子リスト(PIDL)へのポインターを指定してナビゲーションします。

pidlITEMIDLIST*inナビゲーション先としてオブジェクトの場所を指定する const ITEMIDLIST(項目識別子リスト)へのポインター。このパラメーターは NULL にできます。詳細については「解説」を参照してください。
uFlagsDWORDin

pidl のカテゴリを指定するフラグ。これはナビゲーションの実行方法に影響します。値は 0 か、次の値のビットごとの組み合わせでなければなりません。

SBSP_ABSOLUTE

デスクトップを基準とする絶対 PIDL。

SBSP_RELATIVE

現在のフォルダーを基準とする相対 PIDL。

SBSP_PARENT

親フォルダーへナビゲーションし、PIDL は無視します。

SBSP_NAVIGATEBACK

戻る方向へナビゲーションし、PIDL は無視します。

SBSP_NAVIGATEFORWARD

進む方向へナビゲーションし、PIDL は無視します。

SBSP_KEEPWORDWHEELTEXT

Windows Vista 以降。このフラグは、WordWheel(Windows エクスプローラーの検索ボックス)に入力された検索テキストをこのナビゲーション中に保持し、新しい場所の項目が以前の場所と同じ方法でフィルターされるようにすることを示します。

戻り値

型: HRESULT

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

解説(Remarks)

uFlags に指定されたフラグが組み込みの TravelLog を通じたナビゲーション(すなわち SBSP_NAVIGATEBACK または SBSP_NAVIGATEFORWARD)を示す場合、パラメーター pidlNULL にできます。

このメソッドは、shobjidl.h ファイルに列挙されている SBSP フラグの一部のみをサポートします。したがって、uFlagsSBSP_NEWBROWSER または SBSP_EXPLOREMODE が指定された場合、このメソッドは E_INVALIDARG を返します。

vtbl 14 HRESULT BrowseToObject(IUnknown* punk, DWORD uFlags)

オブジェクトへナビゲーションします。

punkIUnknown*inナビゲーション先のオブジェクトへのポインター。オブジェクトを参照できない場合は、エラー値が返されます。
uFlagsDWORDin

pidl のカテゴリを指定するフラグ。これはナビゲーションの実行方法に影響します。値は 0 か、次の値のビットごとの組み合わせでなければなりません。

SBSP_ABSOLUTE

デスクトップを基準とする絶対 PIDL。

SBSP_RELATIVE

現在のフォルダーを基準とする相対 PIDL。

SBSP_PARENT

親フォルダーを参照し、PIDL は無視します。

SBSP_NAVIGATEBACK

戻る方向へナビゲーションし、PIDL は無視します。

SBSP_NAVIGATEFORWARD

進む方向へナビゲーションし、PIDL は無視します。

SBSP_KEEPWORDWHEELTEXT

Windows Vista 以降。このフラグは、WordWheel(Windows エクスプローラーの検索ボックス)に入力された検索テキストをこのナビゲーション中に保持し、新しい場所の項目が以前の場所と同じ方法でフィルターされるようにすることを示します。

戻り値

型: HRESULT

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

解説(Remarks)

uFlags には、EXPLORER_BROWSER_FILL_FLAGS のいずれか、または BrowseObjectwFlags パラメーターで定義されているフラグ(ナビゲーションを示すフラグを除く)のいずれかを指定できます。

このメソッドは GetIDList を呼び出し、返された pidl へナビゲーションします。punkNULL にできない点を除き、IExplorerBrowser::BrowseToIDList と同じように動作します。標準的な使い方は、IShellFolder または IShellItem へナビゲーションすることです。渡されたオブジェクトを参照できない場合はエラーが返されます。参照可能なオブジェクトは、IPersistFolder2 または IPersistIDList のいずれかを実装しています。

IExplorerBrowser の最初のナビゲーションは同期的です。それ以降のナビゲーションはすべて非同期です。そのため、保留中のナビゲーションを正しく設定していれば IExplorerBrowser::BrowseToObject の呼び出しは成功しますが、それはナビゲーション自体の成功を保証するものではありません。成功と失敗の通知を受けるには、クライアントは IExplorerBrowserEvents を実装し、OnNavigationComplete および OnNavigationFailed で適切に応答する必要があります。

vtbl 15 HRESULT FillFromObject(IUnknown* punk, EXPLORER_BROWSER_FILL_FLAGS dwFlags)

結果フォルダーを作成し、項目を格納します。

punkIUnknown*inIResultsFolder を満たすソースオブジェクトへのインターフェイスポインター。これは IDataObject、または INamespaceWalk とともに使用できる任意のオブジェクトです。
dwFlagsEXPLORER_BROWSER_FILL_FLAGSinEXPLORER_BROWSER_FILL_FLAGS 値のいずれか 1 つ。

戻り値

型: HRESULT

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

解説(Remarks)

インターフェイスポインター punk を介して渡されたオブジェクトが IResultsFolder を満たします。

パラメーター dwFlags には、EXPLORER_BROWSER_FILL_FLAGS のいずれか、または BrowseObjectwFlags パラメーターで定義されているフラグ(ナビゲーションを示すフラグを除く)のいずれかを指定できます。

パラメーター punk には、INamespaceWalk が処理できる任意のオブジェクトを指定できます。EBF_SELECTFROMDATAOBJECT を指定して呼び出す場合、punkIDataObject でなければなりません。この場合、名前空間はデータオブジェクトの親レベルで走査され、すべてのピア項目が含まれますが、データオブジェクトに含まれる項目のみが選択されます。このフラグは、FOLDERSETTINGSFWF_CHECKSELECT が有効になっているときに最もよく使用され、データオブジェクトにまとめられた一連の項目のチェック選択を可能にします。

注意 データオブジェクト内の項目識別子リスト(PIDL)へのポインターが完全修飾されている場合、デスクトップフォルダーの項目がリストに追加されてしまうため、親フォルダーを正常に走査できません。
このメソッドは複数回呼び出すことができ、呼び出すたびにビューに項目が追加されます。IExplorerBrowser::RemoveAll を呼び出すと、結果フォルダーの内容をクリアできます。この関数は、ユーザーが新しい項目をビューにドラッグ アンド ドロップするのを防ぐために EBF_NODROPTARGET を指定して呼び出すべきです(それが望ましくない場合を除く)。また、ブラウザーが ResultsFolder にとどまり、データオブジェクトに含まれる可能性のあるフォルダーへユーザーがナビゲーションするのを防ぐために、EBO_NAVIGATEONCE を設定することも推奨されます。

結果フォルダー内の項目を直接操作するには、IExplorerBrowser::GetCurrentView を呼び出して ExplorerBrowser からビューを取得し、そのビューに対して GetFolder を使用して結果フォルダーを問い合わせます。こうして取得した結果フォルダーを使用すると、IExplorerBrowser が提供するメソッドよりも柔軟に、フォルダー内のデータを操作できます。

vtbl 16 HRESULT RemoveAll()

結果フォルダーからすべての項目を削除します。

戻り値

型: HRESULT

成功した場合は S_OK を返します。IExplorerBrowser::FillFromObject の呼び出し前にこのメソッドが呼び出された場合は E_UNEXPECTED を返します。

解説(Remarks)

このメソッドは、IExplorerBrowser::FillFromObject メソッドで作成された IResultsFolder からすべての結果を削除します。

vtbl 17 HRESULT GetCurrentView(GUID* riid, void** ppv)

ブラウザーの現在のビューのインターフェイスを取得します。

riidGUID*in目的のインターフェイス ID への参照。
ppvvoid**outこのメソッドが返るとき、riid で要求されたインターフェイスポインターが格納されます。これは通常、IShellViewIShellView2IFolderView、またはそれらに関連するインターフェイスになります。

戻り値

型: HRESULT

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

解説(Remarks)

IID_PPV_ARGS マクロを使用してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_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 指定が可能。