ホーム › UI.Shell › IFileSaveDialog

IFileSaveDialog

COM

📘 Microsoft Learn (日本語) · English

IID84bccd23-5fde-4cdb-aea4-af64b83d78ab継承元IFileDialog自前メソッド開始 vtbl27

公式ドキュメント

IFileDialog インターフェースを拡張し、保存ダイアログ固有のメソッドを追加します。これには、ファイルとともに永続化されるメタデータの収集をサポートするメソッドが含まれます。

解説(Remarks)

実装するタイミング

IFileSaveDialog は、共通ファイル保存ダイアログ (CLSID_FileSaveDialog) によって実装されます。

このインターフェースは、継承元である IFileDialog インターフェースのメソッドも提供します。

メソッド 5

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 27 HRESULT SetSaveAsItem(IShellItem* psi)

名前を付けて保存ダイアログの初期エントリとして使用する項目を設定します。

psi

IShellItem*

項目を表す IShellItem へのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

項目の名前がファイル名編集ボックスに表示され、それを含むフォルダーがビューで開かれます。これは通常、アプリケーションが既存の項目を保存する場合に使用されます。新規の項目には IFileDialog::SetFileName を使用してください。

vtbl 28 HRESULT SetProperties(IPropertyStore* pStore)

保存対象の項目に使用する既定値を定義するプロパティストアを提供します。

pStore

IPropertyStore*

関連するメタデータを含むプロパティストアを表すインターフェースへのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、ダイアログが開かれる前の任意のタイミング、またはダイアログの表示中に呼び出すことができます。項目に固有のプロパティがある場合は、ダイアログを表示する前にそれらのプロパティを指定してこのメソッドを呼び出す必要があります。

名前を付けて保存 を使用する場合、アプリケーションは保存対象の項目のプロパティを保存ダイアログに提供する必要があります。それらのプロパティは、GPS_HANDLERPROPERTIESONLY フラグを指定して GetPropertyStore を呼び出すことで、元の項目から取得する必要があります。

ダイアログが閉じた後に保存された項目のプロパティ (ユーザーによって変更されている可能性があります) を取得するには、IFileSaveDialog::GetProperties を呼び出します。

プロパティ収集を有効にし、保存ダイアログに表示するプロパティを指定するには、IFileSaveDialog::SetCollectedProperties を使用します。

vtbl 29 HRESULT SetCollectedProperties(IPropertyDescriptionList* pList, BOOL fAppendDefault)

保存ダイアログで収集するプロパティを指定します。

pList	IPropertyDescriptionList*	in	収集するプロパティのリストを表すインターフェースへのポインター。このパラメーターは NULL にすることができます。
fAppendDefault	BOOL	in	pList で指定したプロパティに加えて、現在選択されているファイルタイプの既定のプロパティを表示する場合は TRUE。pList で指定したプロパティのみを表示する場合は FALSE。

戻り値

型: HRESULT

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

解説(Remarks)

呼び出し元のアプリケーションは、PSGetPropertyDescriptionListFromString 関数を使用して、"prop:Comments;Subject;" のような文字列から IPropertyDescriptionList を構築できます。

プロパティスキーマの詳細については、 Property Schemas を参照してください。

IFileSaveDialog::SetCollectedProperties は、ダイアログが表示される前の任意のタイミング、またはダイアログの表示中に呼び出すことができます。選択されたファイルタイプに応じて異なるプロパティを収集する場合は、OnTypeChange への応答として IFileSaveDialog::SetCollectedProperties を呼び出すことができます。

注意既定では、保存ダイアログでプロパティは収集されません。

vtbl 30 HRESULT GetProperties(IPropertyStore** ppStore)

保存された項目、または保存処理中の項目のプロパティ値のセットを取得します。

ppStore

IPropertyStore**

out

プロパティ値を受け取る IPropertyStore へのポインターのアドレス。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、ダイアログの表示中に呼び出してメタデータ収集ペインの現在の値のセットを取得できます。また、ダイアログが閉じた後に呼び出して、最終的な値のセットを取得することもできます。

このメソッドの呼び出しは、IFileSaveDialog::SetCollectedProperties の呼び出しによってプロパティ収集が有効になっていない限り失敗します。

vtbl 31 HRESULT ApplyProperties(IShellItem* psi, IPropertyStore* pStore, HWND hwnd, IFileOperationProgressSink* pSink)

シェルのコピーエンジンを使用して、一連のプロパティを項目に適用します。

psi	IShellItem*	in	保存されるファイルを表す IShellItem へのポインター。通常、これは GetResult によって取得される項目です。
pStore	IPropertyStore*	in	ファイルに適用するプロパティ値を表す IPropertyStore へのポインター。これは IFileSaveDialog::GetProperties によって返されたプロパティストアにすることができます。
hwnd	HWND	in	アプリケーションウィンドウのハンドル。
pSink	IFileOperationProgressSink*	in	プロパティの書き込みの進行状況の通知を受け取りたい場合に呼び出し元のアプリケーションが使用できる、省略可能な IFileOperationProgressSink へのポインター。この値は NULL にすることができます。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、アプリケーションがプロパティ収集を有効にしている (IFileSaveDialog::SetCollectedProperties) が、プロパティ自体を保存されるファイルに永続化しない場合に使用する必要があります。

注意 psi で指定される項目が表すファイルは、IFileSaveDialog::ApplyProperties を呼び出す前に物理ストレージ上に存在している必要があります。そのため、事前にどこかの時点で保存されている必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IFileSaveDialog "{84BCCD23-5FDE-4CDB-AEA4-AF64B83D78AB}"
#usecom global IFileSaveDialog IID_IFileSaveDialog "{C0B4E2F3-BA21-4773-8DBA-335EC946EB8B}"
#comfunc global IFileSaveDialog_SetSaveAsItem           27 sptr
#comfunc global IFileSaveDialog_SetProperties           28 sptr
#comfunc global IFileSaveDialog_SetCollectedProperties  29 sptr,int
#comfunc global IFileSaveDialog_GetProperties           30 sptr
#comfunc global IFileSaveDialog_ApplyProperties         31 sptr,sptr,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。