ホーム › UI.Shell › IFileDialogCustomize

IFileDialogCustomize

COM

📘 Microsoft Learn (日本語) · English

IIDe6fdd21a-163f-4975-9c8c-a69f1ba37034継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

アプリケーションがコモンファイルダイアログにコントロールを追加できるようにするメソッドを公開します。

解説(Remarks)

実装するタイミング

IFileDialogControlEvents は、コモンファイルオープンダイアログ (CLSID_FileOpenDialog) およびファイル保存ダイアログ (CLSID_FileSaveDialog) によって実装されます。

コントロールは、ダイアログが表示される前にダイアログへ追加されます。そのレイアウトは、追加された順序によって決まります。ダイアログが表示された後は、コントロールを追加または削除することはできませんが、既存のコントロールはいつでも非表示にしたり無効にしたりできます。ラベルもいつでも変更できます。

コンテナーコントロールとは、項目を追加できるコントロールです。コンテナーコントロールには、コンボボックス、メニュー、Open ボタンに付属するドロップダウンリスト、およびオプションボタングループが含まれます。項目がコンテナー内に表示される順序は、追加された順序です。項目を並べ替える機能はありません。ID は親コントロールのスコープに限定されます。コンテナーコントロールには、メニューを除き、選択された項目があります。

コンテナーコントロール内の項目は、作成後に変更することはできません。ただし、有効状態と表示状態は例外です。とはいえ、項目自体はいつでも追加および削除できます。たとえば、メニューのテキストを変更する必要がある場合は、現在のメニューを削除し、正しいテキストを持つ別のメニューを追加する必要があります。

メソッド 27

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

vtbl 3 HRESULT EnableOpenDropDown(DWORD dwIDCtl)

ダイアログの Open または Save ボタンにドロップダウンリストを有効化します。

dwIDCtl

DWORD

ドロップダウンリストの ID。

戻り値

型: HRESULT

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

解説(Remarks)

Open または Save ボタンのラベルには、ドロップダウンの最初の項目のテキストが使用されます。これは IFileDialog::SetOkButtonLabel で設定されたラベルを上書きします。

ドロップダウンに項目を追加するには IFileDialogCustomize::AddControlItem を使用してください。

vtbl 4 HRESULT AddMenu(DWORD dwIDCtl, LPWSTR pszLabel)

ダイアログにメニューを追加します。

dwIDCtl	DWORD	in	追加するメニューの ID。
pszLabel	LPWSTR	in	メニュー名を null 終端の Unicode 文字列として格納するバッファーへのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

このコントロールの既定の状態は、有効かつ表示です。

このコントロールに項目を追加するには IFileDialogCustomize::AddControlItem を使用してください。

vtbl 5 HRESULT AddPushButton(DWORD dwIDCtl, LPWSTR pszLabel)

ダイアログにボタンを追加します。

dwIDCtl	DWORD	in	追加するボタンの ID。
pszLabel	LPWSTR	in	ボタンのテキストを null 終端の Unicode 文字列として格納するバッファーへのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

このコントロールの既定の状態は、有効かつ表示です。

vtbl 6 HRESULT AddComboBox(DWORD dwIDCtl)

ダイアログにコンボボックスを追加します。

dwIDCtl

DWORD

追加するコンボボックスの ID。

戻り値

型: HRESULT

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

解説(Remarks)

このコントロールの既定の状態は、有効かつ表示です。

vtbl 7 HRESULT AddRadioButtonList(DWORD dwIDCtl)

ダイアログにオプションボタン(ラジオボタンとも呼ばれます)グループを追加します。

dwIDCtl

DWORD

追加するオプションボタングループの ID。

戻り値

型: HRESULT

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

解説(Remarks)

このコントロールの既定の状態は、有効かつ表示です。

vtbl 8 HRESULT AddCheckButton(DWORD dwIDCtl, LPWSTR pszLabel, BOOL bChecked)

ダイアログにチェックボタン(チェックボックス)を追加します。

dwIDCtl	DWORD	in	追加するチェックボタンの ID。
pszLabel	LPWSTR	in	ボタンのテキストを null 終端の Unicode 文字列として格納するバッファーへのポインター。
bChecked	BOOL	in	チェックボタンの現在の状態を示す BOOL。チェックされている場合は TRUE、それ以外の場合は FALSE。

戻り値

型: HRESULT

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

解説(Remarks)

このコントロールの既定の状態は、有効かつ表示です。

vtbl 9 HRESULT AddEditBox(DWORD dwIDCtl, LPWSTR pszText)

ダイアログにエディットボックスコントロールを追加します。

dwIDCtl	DWORD	in	追加するエディットボックスの ID。
pszText	LPWSTR	in	エディットボックスに表示される既定のテキストを提供する null 終端の Unicode 文字列へのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

このコントロールの既定の状態は、有効かつ表示です。

エディットボックスの隣にラベルを配置するには、IFileDialogCustomize::StartVisualGroup でビジュアルグループ内に配置してください。

vtbl 10 HRESULT AddSeparator(DWORD dwIDCtl)

ダイアログに区切り線を追加し、コントロールを視覚的に区切ります。

dwIDCtl

DWORD

区切り線のコントロール ID。

戻り値

型: HRESULT

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

解説(Remarks)

このコントロールの既定の状態は、有効かつ表示です。

vtbl 11 HRESULT AddText(DWORD dwIDCtl, LPWSTR pszText)

ダイアログにテキストコンテンツを追加します。

dwIDCtl	DWORD	in	追加するテキストの ID。
pszText	LPWSTR	in	テキストを null 終端の Unicode 文字列として格納するバッファーへのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

このコントロールの既定の状態は、有効かつ表示です。

vtbl 12 HRESULT SetControlLabel(DWORD dwIDCtl, LPWSTR pszLabel)

ボタンテキストやエディットボックスのラベルなど、コントロールに関連付けられたテキストを設定します。

dwIDCtl	DWORD	in	テキストを変更するコントロールの ID。
pszLabel	LPWSTR	in	テキストを null 終端の Unicode 文字列として格納するバッファーへのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

コントロールのラベルは、ダイアログが表示されているときも含め、いつでも変更できます。

vtbl 13 HRESULT GetControlState(DWORD dwIDCtl, CDCONTROLSTATEF* pdwState)

指定したコントロールの現在の表示状態および有効状態を取得します。

dwIDCtl	DWORD	in	対象となるコントロールの ID。
pdwState	CDCONTROLSTATEF*	out	コントロールの現在の状態を示す CDCONTROLSTATE 列挙型の 1 つ以上の値を受け取る変数へのポインター。

戻り値

型: HRESULT

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

vtbl 14 HRESULT SetControlState(DWORD dwIDCtl, CDCONTROLSTATEF dwState)

指定したコントロールの現在の表示状態および有効状態を設定します。

dwIDCtl	DWORD	in	対象となるコントロールの ID。
dwState	CDCONTROLSTATEF	in	コントロールの現在の状態を示す CDCONTROLSTATE 列挙型の 1 つ以上の値。

戻り値

型: HRESULT

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

解説(Remarks)

ダイアログが表示されると、コントロールを追加または削除することはできませんが、既存のコントロールはいつでも非表示にしたり無効にしたりできます。

vtbl 15 HRESULT GetEditBoxText(DWORD dwIDCtl, WORD** ppszText)

エディットボックスコントロールの現在のテキストを取得します。

dwIDCtl	DWORD	in	エディットボックスの ID。
ppszText	WORD**	out	テキストを null 終端の Unicode 文字列として受け取るバッファーへのポインターのアドレス。

戻り値

型: HRESULT

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

解説(Remarks)

ppszText が参照するバッファーが不要になったときに解放するのは、呼び出し側アプリケーションの責任です。バッファーを解放するには CoTaskMemFree を使用してください。

vtbl 16 HRESULT SetEditBoxText(DWORD dwIDCtl, LPWSTR pszText)

ダイアログ内のエディットボックスコントロールにテキストを設定します。

dwIDCtl	DWORD	in	エディットボックスの ID。
pszText	LPWSTR	in	テキストを null 終端の Unicode 文字列として格納するバッファーへのポインター。

戻り値

型: HRESULT

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

vtbl 17 HRESULT GetCheckButtonState(DWORD dwIDCtl, BOOL* pbChecked)

ダイアログ内のチェックボタン(チェックボックス)の現在の状態を取得します。

dwIDCtl	DWORD	in	チェックボックスの ID。
pbChecked	BOOL*	out	ボックスがチェックされているかどうかを示す BOOL 値のアドレス。TRUE はチェック済み、FALSE は未チェックを意味します。

戻り値

型: HRESULT

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

vtbl 18 HRESULT SetCheckButtonState(DWORD dwIDCtl, BOOL bChecked)

ダイアログ内のチェックボタン(チェックボックス)の状態を設定します。

dwIDCtl	DWORD	in	チェックボックスの ID。
bChecked	BOOL	in	ボックスがチェックされているかどうかを示す BOOL 値。TRUE はチェック済み、FALSE は未チェックを意味します。

戻り値

型: HRESULT

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

vtbl 19 HRESULT AddControlItem(DWORD dwIDCtl, DWORD dwIDItem, LPWSTR pszLabel)

ダイアログ内のコンテナーコントロールに項目を追加します。

dwIDCtl	DWORD	in	項目を追加するコンテナーコントロールの ID。
dwIDItem	DWORD	in	項目の ID。
pszLabel	LPWSTR	in	項目のテキストを格納するバッファーへのポインター。これはラベルか、ドロップダウンリストの場合は項目そのものになります。このテキストは null 終端の Unicode 文字列です。

戻り値

型: HRESULT

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

解説(Remarks)

この項目の既定の状態は、有効かつ表示です。コントロールグループ内の項目は、作成後に変更することはできません。ただし、有効状態と表示状態は例外です。

コンテナーコントロールには、オプションボタングループ、コンボボックス、Open または Save ボタンのドロップダウンリスト、およびメニューが含まれます。

vtbl 20 HRESULT RemoveControlItem(DWORD dwIDCtl, DWORD dwIDItem)

ダイアログ内のコンテナーコントロールから項目を削除します。

dwIDCtl	DWORD	in	項目を削除するコンテナーコントロールの ID。
dwIDItem	DWORD	in	項目の ID。

戻り値

型: HRESULT

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

解説(Remarks)

vtbl 21 HRESULT RemoveAllControlItems(DWORD dwIDCtl)

実装されていません。(IFileDialogCustomize.RemoveAllControlItems)

dwIDCtl

DWORD

項目を削除するコンテナーコントロールの ID。

戻り値

型: HRESULT

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

vtbl 22 HRESULT GetControlItemState(DWORD dwIDCtl, DWORD dwIDItem, CDCONTROLSTATEF* pdwState)

ダイアログ内のコンテナーコントロールにある項目の現在の状態を取得します。

dwIDCtl	DWORD	in	コンテナーコントロールの ID。
dwIDItem	DWORD	in	項目の ID。
pdwState	CDCONTROLSTATEF*	out	コントロールの現在の状態を示す CDCONTROLSTATE 列挙型の 1 つ以上の値を受け取る変数へのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

コントロール項目の既定の状態は、有効かつ表示です。コントロールグループ内の項目は、作成後に変更することはできません。ただし、有効状態と表示状態は例外です。

vtbl 23 HRESULT SetControlItemState(DWORD dwIDCtl, DWORD dwIDItem, CDCONTROLSTATEF dwState)

ダイアログ内のコンテナーコントロールにある項目の現在の状態を設定します。

dwIDCtl	DWORD	in	コンテナーコントロールの ID。
dwIDItem	DWORD	in	項目の ID。
dwState	CDCONTROLSTATEF	in	コントロールの新しい状態を示す CDCONTROLSTATE 列挙型の 1 つ以上の値。

戻り値

型: HRESULT

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

解説(Remarks)

vtbl 24 HRESULT GetSelectedControlItem(DWORD dwIDCtl, DWORD* pdwIDItem)

ダイアログ内の指定したコンテナーコントロールから特定の項目を取得します。

dwIDCtl	DWORD	in	コンテナーコントロールの ID。
pdwIDItem	DWORD*	out	ユーザーがコントロール内で選択した項目の ID。

戻り値

型: HRESULT

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

解説(Remarks)

ユーザーの最終的な選択を判定するために、ダイアログが閉じた後、このメソッドをオプションボタングループ、コンボボックス、および Open または Save ボタンのドロップダウンリストに対して呼び出すことができます。このメソッドはメニューに対しては呼び出せません。

オプションボタングループおよびコンボボックスの場合、このメソッドは現在の選択を判定するために、ダイアログが表示されている間に呼び出すこともできます。

vtbl 25 HRESULT SetSelectedControlItem(DWORD dwIDCtl, DWORD dwIDItem)

ダイアログ内のオプションボタングループまたはコンボボックスにある特定の項目の選択状態を設定します。

dwIDCtl	DWORD	in	コンテナーコントロールの ID。
dwIDItem	DWORD	in	コントロール内で選択済みとして表示する項目の ID。

戻り値

型: HRESULT

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

vtbl 26 HRESULT StartVisualGroup(DWORD dwIDCtl, LPWSTR pszLabel)

ダイアログ内にビジュアルグループを宣言します。以降の各「add」メソッドの呼び出しは、それらの要素をこのグループに追加します。

dwIDCtl	DWORD	in	ビジュアルグループの ID。
pszLabel	LPWSTR	in	ビジュアルグループの隣に表示されるテキストを null 終端の Unicode 文字列として格納するバッファーへのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

IFileDialogCustomize::EndVisualGroup を呼び出すまで、コントロールはこのビジュアルグループに追加され続けます。

ビジュアルグループは、他のコントロールと同様に非表示にしたり無効にしたりできますが、その場合はグループ内のすべてのコントロールに影響します。ビジュアルグループの個々のメンバーを単独で非表示にしたり無効にしたりすることもできます。

vtbl 27 HRESULT EndVisualGroup()

ダイアログ内のビジュアルグループへの要素の追加を停止します。

戻り値

型: HRESULT

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

vtbl 28 HRESULT MakeProminent(DWORD dwIDCtl)

追加された他のコントロールと比べて目立つように、ダイアログ内にコントロールを配置します。

dwIDCtl

DWORD

コントロールの ID。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、コントロールを他のカスタムコントロールとグループ化する代わりに、Open または Save ボタンの近くに配置します。

目立たせることができるのは、チェックボタン(チェックボックス)、プッシュボタン、コンボボックス、およびメニュー、またはそれらの型のいずれか 1 つだけを含むビジュアルグループのみです。

この方法でマークできるコントロールは 1 つだけです。ダイアログに追加されたコントロールが 1 つだけの場合、そのコントロールは既定で目立つものとしてマークされます。

vtbl 29 HRESULT SetControlItemText(DWORD dwIDCtl, DWORD dwIDItem, LPWSTR pszLabel)

コントロール項目のテキストを設定します。たとえば、ラジオボタンやメニュー内の項目に付随するテキストなどです。

dwIDCtl	DWORD	in	コンテナーコントロールの ID。
dwIDItem	DWORD	in	項目の ID。
pszLabel	LPWSTR	in	テキストを含む Unicode 文字列を格納する null 終端のバッファーへのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IFileDialogCustomize "{E6FDD21A-163F-4975-9C8C-A69F1BA37034}"
#usecom global IFileDialogCustomize IID_IFileDialogCustomize "{}"
#comfunc global IFileDialogCustomize_EnableOpenDropDown      3 int
#comfunc global IFileDialogCustomize_AddMenu                 4 int,wstr
#comfunc global IFileDialogCustomize_AddPushButton           5 int,wstr
#comfunc global IFileDialogCustomize_AddComboBox             6 int
#comfunc global IFileDialogCustomize_AddRadioButtonList      7 int
#comfunc global IFileDialogCustomize_AddCheckButton          8 int,wstr,int
#comfunc global IFileDialogCustomize_AddEditBox              9 int,wstr
#comfunc global IFileDialogCustomize_AddSeparator            10 int
#comfunc global IFileDialogCustomize_AddText                 11 int,wstr
#comfunc global IFileDialogCustomize_SetControlLabel         12 int,wstr
#comfunc global IFileDialogCustomize_GetControlState         13 int,var
#comfunc global IFileDialogCustomize_SetControlState         14 int,int
#comfunc global IFileDialogCustomize_GetEditBoxText          15 int,var
#comfunc global IFileDialogCustomize_SetEditBoxText          16 int,wstr
#comfunc global IFileDialogCustomize_GetCheckButtonState     17 int,var
#comfunc global IFileDialogCustomize_SetCheckButtonState     18 int,int
#comfunc global IFileDialogCustomize_AddControlItem          19 int,int,wstr
#comfunc global IFileDialogCustomize_RemoveControlItem       20 int,int
#comfunc global IFileDialogCustomize_RemoveAllControlItems   21 int
#comfunc global IFileDialogCustomize_GetControlItemState     22 int,int,var
#comfunc global IFileDialogCustomize_SetControlItemState     23 int,int,int
#comfunc global IFileDialogCustomize_GetSelectedControlItem  24 int,var
#comfunc global IFileDialogCustomize_SetSelectedControlItem  25 int,int
#comfunc global IFileDialogCustomize_StartVisualGroup        26 int,wstr
#comfunc global IFileDialogCustomize_EndVisualGroup          27
#comfunc global IFileDialogCustomize_MakeProminent           28 int
#comfunc global IFileDialogCustomize_SetControlItemText      29 int,int,wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IFileDialogCustomize "{E6FDD21A-163F-4975-9C8C-A69F1BA37034}"
#usecom global IFileDialogCustomize IID_IFileDialogCustomize "{}"
#comfunc global IFileDialogCustomize_EnableOpenDropDown      3 int
#comfunc global IFileDialogCustomize_AddMenu                 4 int,wstr
#comfunc global IFileDialogCustomize_AddPushButton           5 int,wstr
#comfunc global IFileDialogCustomize_AddComboBox             6 int
#comfunc global IFileDialogCustomize_AddRadioButtonList      7 int
#comfunc global IFileDialogCustomize_AddCheckButton          8 int,wstr,int
#comfunc global IFileDialogCustomize_AddEditBox              9 int,wstr
#comfunc global IFileDialogCustomize_AddSeparator            10 int
#comfunc global IFileDialogCustomize_AddText                 11 int,wstr
#comfunc global IFileDialogCustomize_SetControlLabel         12 int,wstr
#comfunc global IFileDialogCustomize_GetControlState         13 int,sptr
#comfunc global IFileDialogCustomize_SetControlState         14 int,int
#comfunc global IFileDialogCustomize_GetEditBoxText          15 int,sptr
#comfunc global IFileDialogCustomize_SetEditBoxText          16 int,wstr
#comfunc global IFileDialogCustomize_GetCheckButtonState     17 int,sptr
#comfunc global IFileDialogCustomize_SetCheckButtonState     18 int,int
#comfunc global IFileDialogCustomize_AddControlItem          19 int,int,wstr
#comfunc global IFileDialogCustomize_RemoveControlItem       20 int,int
#comfunc global IFileDialogCustomize_RemoveAllControlItems   21 int
#comfunc global IFileDialogCustomize_GetControlItemState     22 int,int,sptr
#comfunc global IFileDialogCustomize_SetControlItemState     23 int,int,int
#comfunc global IFileDialogCustomize_GetSelectedControlItem  24 int,sptr
#comfunc global IFileDialogCustomize_SetSelectedControlItem  25 int,int
#comfunc global IFileDialogCustomize_StartVisualGroup        26 int,wstr
#comfunc global IFileDialogCustomize_EndVisualGroup          27
#comfunc global IFileDialogCustomize_MakeProminent           28 int
#comfunc global IFileDialogCustomize_SetControlItemText      29 int,int,wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。