IFileDialog

共通ファイルダイアログの初期化、表示、および結果の取得を行うメソッドを公開します。

実装するタイミング

ダイアログで開くまたは保存できるファイルの種類を設定します。

型: HRESULT

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

開くダイアログを使用する場合、そこで宣言されたファイルの種類はビューをフィルターするために使用されます。保存ダイアログを使用する場合、これらの値はファイル名にどの拡張子が付加されるかを決定します。

このメソッドはダイアログを表示する前に呼び出す必要があり、各ダイアログインスタンスに対して 1 回だけ呼び出すことができます。ファイルの種類は、共通アイテムダイアログボックスが表示された後は変更できません。

例

次のコード例は、このメソッドのコンテキストにおける COMDLG_FILTERSPEC 構造体の配列の使用方法を示しています。この例の配列は 3 つの COMDLG_FILTERSPEC 構造体で構成されています。1 つ目はダイアログフィルターに対して 2 つのパターンを宣言し、2 つ目は単一のパターンを宣言し、最後のものはすべての種類のファイルを表示します。変数 szJPG、szBMP、および szAll は、各フィルターにわかりやすい名前を提供する、事前に宣言された文字列であると想定します。

COMDLG_FILTERSPEC rgSpec[] =
{ 
    { szJPG, L"*.jpg;*.jpeg" },
    { szBMP, L"*.bmp" },
    { szAll, L"*.*" },
};

ダイアログで選択された状態として表示されるファイルの種類を設定します。

型: HRESULT

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

このメソッドはダイアログを表示する前に呼び出す必要があります。

現在選択されているファイルの種類を取得します。

型: HRESULT

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

IFileDialog::GetFileTypeIndex は、ダイアログが開いている間、または閉じた後のいずれでも呼び出すことができます。

ダイアログから発生するイベントをリッスンするイベントハンドラーを割り当てます。

型: HRESULT

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

IFileDialog::Advise メソッドを通じてアタッチされたイベントハンドラーを削除します。

型: HRESULT

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

ダイアログの動作を制御するフラグを設定します。

型: HRESULT

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

一般に、このメソッドには IFileDialog::GetOptions で取得した値を渡し、適切なフラグを設定してオプションを追加または除外するように変更する必要があります。

ダイアログの動作を制御するために設定されている現在のフラグを取得します。

型: HRESULT

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

最近使用したフォルダーの値が利用できない場合に、既定として使用されるフォルダーを設定します。

型: HRESULT

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

以前のユーザー操作に関係なく、ダイアログを開いたときに常に選択されるフォルダーを設定します。

型: HRESULT

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

このフォルダーは、あらゆる「最近使用した」フォルダーよりも優先されます。このメソッドがダイアログの表示中に呼び出された場合、ダイアログは指定されたフォルダーに移動します。

一般に、このメソッドの使用は推奨されません。ダイアログボックスを表示する前に SetFolder を呼び出すと、ユーザーが最後に保存または開いた場所が表示されなくなります。この動作に非常に特殊な理由がない限り、良好で期待される操作体験とは言えないため、避けるべきです。ほとんどすべての場合において、IFileDialog::SetDefaultFolder の方が適切なメソッドです。

Windows 7 以降では、psi を通じて指定されたフォルダーのパスが既知のフォルダーの既定のパスである場合、その既知のフォルダーの現在のパスがダイアログで使用されます。そのパスは、psi で指定されたパスと同じでない場合があります。たとえば、既知のフォルダーがリダイレクトされている場合などです。既知のフォルダーがライブラリ (仮想フォルダーのドキュメント、ミュージック、ピクチャ、ビデオ) である場合、ライブラリのパスがダイアログで使用されます。指定されたライブラリが非表示になっている場合 (Windows 8.1 以降では既定で非表示です)、ライブラリの既定の保存場所 (たとえばドキュメントライブラリの場合は Microsoft OneDrive のドキュメントフォルダー) がダイアログで使用されます。これらのマッピングにより、ダイアログで使用されるフォルダーの場所は、このメソッドを呼び出したときに指定したものと正確には一致しない場合があります。

ダイアログで現在選択されているフォルダー、またはダイアログが現在表示されていない場合はダイアログを開いたときに選択されるフォルダーを取得します。

型: HRESULT

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

取得した IShellItem が不要になったら、それを解放する責任は呼び出し側のアプリケーションにあります。

ダイアログにおけるユーザーの現在の選択を取得します。

型: HRESULT

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

取得した IShellItem が不要になったら、それを解放する責任は呼び出し側のアプリケーションにあります。

ダイアログボックスを開いたときに [ファイル名] 編集ボックスに表示されるファイル名を設定します。

型: HRESULT

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

ダイアログの [ファイル名] 編集ボックスに現在入力されているテキストを取得します。

型: HRESULT

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

[ファイル名] 編集ボックス内のテキストは、必ずしもユーザーが選択したアイテムを反映しているとは限りません。ユーザーが選択したアイテムを取得するには、IFileDialog::GetResult を使用してください。

取得したバッファーは、CoTaskMemFree 関数を使用して解放する責任が呼び出し側のアプリケーションにあります。

ダイアログのタイトルを設定します。

型: HRESULT

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

[開く] または [保存] ボタンのテキストを設定します。

型: HRESULT

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

ファイル名編集ボックスの横にあるラベルのテキストを設定します。

型: HRESULT

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

ユーザーがダイアログで行った選択を取得します。

型: HRESULT

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

IFileDialog::GetResult は、ダイアログが閉じた後、または OnFileOk イベントの処理中に呼び出すことができます。それ以外のタイミングでこのメソッドを呼び出すと失敗します。複数のアイテムが選択された場合、このメソッドは失敗します。複数のアイテムの場合は、GetResults を呼び出してください。

IFileDialog::GetResult で結果を利用できるようにするには、Show が成功コードを返している必要があります。

ユーザーがアイテムを開くまたは保存するために利用できる場所のリストにフォルダーを追加します。

型: HRESULT

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

SHSetTemporaryPropertyForItem を使用すると、psi パラメーターで表されるアイテムに一時的な PKEY_ItemNameDisplay プロパティを設定できます。このプロパティの値は、アイテムの UI 名の代わりに使用されます。

ファイル名に付加される既定の拡張子を設定します。

型: HRESULT

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

このメソッドをダイアログを表示する前に呼び出しておくと、ユーザーが新しいファイルの種類を選択したときにダイアログが既定の拡張子を自動的に更新します (SetFileTypes を参照)。

ダイアログを閉じます。

型: HRESULT

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

アプリケーションは、ダイアログが開いている間、コールバックメソッドまたは関数からこのメソッドを呼び出すことができます。ダイアログが閉じ、Show メソッドは hr で指定された HRESULT を返します。

このメソッドが呼び出された場合、IFileDialog::GetResult または GetResults メソッドで利用できる結果はなく、これらを呼び出すと失敗します。

呼び出し側のアプリケーションが、ダイアログの永続化された状態に GUID を関連付けることを可能にします。

型: HRESULT

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

ダイアログの状態には、最後に訪れたフォルダーやダイアログの位置とサイズといった要素が含まれる場合があります。

通常、この状態は実行可能ファイルの名前に基づいて永続化されます。GUID を指定することで、アプリケーションは同一アプリケーション内の異なるバージョンのダイアログ (たとえばインポートダイアログと開くダイアログ) に対して、それぞれ異なる永続化された状態を持つことができます。

IFileDialog::SetClientGuid は、ダイアログオブジェクトの作成直後に呼び出す必要があります。

永続化されたすべての状態情報をクリアするようダイアログに指示します。

型: HRESULT

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

永続化された情報は、アプリケーションまたは GUID に関連付けることができます。IFileDialog::SetClientGuid を使用して GUID が設定されている場合、その GUID を使用して永続化された情報がクリアされます。

SetFilter は Windows 7 以降では使用できなくなりました。

型: HRESULT

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

このメソッドは、アプリケーションがダイアログボックスのビューから一部のアイテムを除外するために特別なフィルター処理を実行する必要がある場合に使用できます。通常はビューに含まれる各アイテムに対して IncludeItem が呼び出されます。GetEnumFlagsForItem は使用されません。 ファイルの種類でフィルターするには、IFileDialog::SetFileTypes を使用してください。アイテム数が多いフォルダーでは、IShellItemFilter を適用するよりも優れたパフォーマンスが得られる場合があるためです。