OPENFILENAMEW 構造体 (commdlg.h)

[Windows Vista 以降、 共通のダイアログ ボックスと [名前を付けて保存 ] ダイアログ ボックスは、[ 共通アイテム] ダイアログボックスに置き換えられていた。 共通ダイアログ ボックス ライブラリのこれらのダイアログ ボックスの代わりに、共通項目ダイアログ API を使用することをお勧めします。

GetOpenFileName 関数と GetSaveFileName 関数が [開く] ダイアログ ボックスまたは [名前を付けて保存] ダイアログ ボックスを初期化するために使用する情報を格納します。 ユーザーがダイアログ ボックスを閉じると、この構造のユーザーの選択に関する情報が返されます。

構文

typedef struct tagOFNW {
  DWORD         lStructSize;
  HWND          hwndOwner;
  HINSTANCE     hInstance;
  LPCWSTR       lpstrFilter;
  LPWSTR        lpstrCustomFilter;
  DWORD         nMaxCustFilter;
  DWORD         nFilterIndex;
  LPWSTR        lpstrFile;
  DWORD         nMaxFile;
  LPWSTR        lpstrFileTitle;
  DWORD         nMaxFileTitle;
  LPCWSTR       lpstrInitialDir;
  LPCWSTR       lpstrTitle;
  DWORD         Flags;
  WORD          nFileOffset;
  WORD          nFileExtension;
  LPCWSTR       lpstrDefExt;
  LPARAM        lCustData;
  LPOFNHOOKPROC lpfnHook;
  LPCWSTR       lpTemplateName;
  LPEDITMENU    lpEditInfo;
  LPCSTR        lpstrPrompt;
  void          *pvReserved;
  DWORD         dwReserved;
  DWORD         FlagsEx;
} OPENFILENAMEW, *LPOPENFILENAMEW;

メンバー

lStructSize

型: DWORD

構造体の長さ (バイト単位)。 このパラメーターには を使用 sizeof (OPENFILENAME) します。

hwndOwner

型: HWND

ダイアログ ボックスを所有するウィンドウへのハンドル。 このメンバーは、任意の有効なウィンドウ ハンドルにすることも、ダイアログ ボックスに所有者がいない場合は NULL にすることもできます。

hInstance

種類: HINSTANCE

OFN_ENABLETEMPLATEHANDLE フラグが Flags メンバーで設定されている場合、hInstance はダイアログ ボックス テンプレートを含むメモリ オブジェクトへのハンドルです。 OFN_ENABLETEMPLATE フラグが設定されている場合、hInstance は lpTemplateName メンバーによって名前付けされたダイアログ ボックス テンプレートを含むモジュールへのハンドルです。 どちらのフラグも設定されていない場合、このメンバーは無視されます。 OFN_EXPLORER フラグが設定されている場合、システムは指定されたテンプレートを使用して、既定のエクスプローラー スタイルのダイアログ ボックスの子であるダイアログ ボックスを作成します。 OFN_EXPLORER フラグが設定されていない場合、システムはテンプレートを使用して、既定のダイアログ ボックスを置き換える古いスタイルのダイアログ ボックスを作成します。

lpstrFilter

種類: LPCTSTR

null で終わるフィルター文字列のペアを含むバッファー。 バッファー内の最後の文字列は、2 つの NULL 文字で終わる必要があります。

各ペアの最初の文字列は、フィルター ("Text Files" など) を記述する表示文字列であり、2 番目の文字列はフィルター パターン (".TXT" など) を指定します。1 つの表示文字列に複数のフィルター パターンを指定するには、セミコロンを使用してパターンを区切ります (例: ".TXT;.DOC;.BAK")。 パターン文字列には、有効なファイル名文字とアスタリスク (*) ワイルドカード文字の組み合わせを指定できます。 パターン文字列にスペースを含めないでください。

システムは、フィルターの順序を変更しません。 lpstrFilter で指定された順序で [ファイルの種類] コンボ ボックスに表示されます。

lpstrFilter が NULL の場合、ダイアログ ボックスにはフィルターは表示されません。

ショートカットの場合、フィルターが設定されていない場合、 GetOpenFileName と GetSaveFileName はターゲットではなく、.lnk ファイルの名前を取得します。 この動作は、Flags メンバーでOFN_NODEREFERENCELINKS フラグを設定する場合と同じです。 フィルター処理を行わずにショートカットのターゲットを取得するには、文字列 を使用します "All Files\0*.*\0\0"。

lpstrCustomFilter

種類: LPTSTR

ユーザーが選択したフィルター パターンを保持するための null で終わるフィルター文字列のペアを含む静的バッファー。 最初の文字列はカスタム フィルターを記述する表示文字列で、2 番目の文字列はユーザーが選択したフィルター パターンです。 アプリケーションで初めてダイアログ ボックスを作成するときは、最初の文字列を指定します。この文字列は、空でない文字列でもかまいません。 ユーザーがファイルを選択すると、ダイアログ ボックスは現在のフィルター パターンを 2 番目の文字列にコピーします。 保持されるフィルター パターンには、 lpstrFilter バッファーで指定されたパターンの 1 つを指定することも、ユーザーが入力したフィルター パターンを指定することもできます。 システムは、次にダイアログ ボックスが作成されるときに、文字列を使用してユーザー定義ファイル フィルターを初期化します。 nFilterIndex メンバーが 0 の場合、ダイアログ ボックスではカスタム フィルターが使用されます。

このメンバーが NULL の場合、ダイアログ ボックスはユーザー定義のフィルター パターンを保持しません。

このメンバーが NULL でない場合、 nMaxCustFilter メンバーの値は、 lpstrCustomFilter バッファーのサイズを文字数で指定する必要があります。

nMaxCustFilter

型: DWORD

lpstrCustomFilter によって識別されるバッファーのサイズ (文字数)。 このバッファーの長さが 40 文字以上である必要があります。 lpstrCustomFilter が NULL であるか、NULL文字列を指している場合、このメンバーは無視されます。

nFilterIndex

型: DWORD

[ファイルの種類] コントロールで現在選択されているフィルターのインデックス。 lpstrFilter によって指されるバッファーには、フィルターを定義する文字列のペアが含まれています。 文字列の最初のペアのインデックス値は 1、2 番目のペアは 2 です。 インデックス 0 は、 lpstrCustomFilter で指定されたカスタム フィルターを示します。 入力時にインデックスを指定して、ダイアログ ボックスの初期フィルターの説明とフィルター パターンを示すことができます。 ユーザーがファイルを選択すると、 nFilterIndex は現在表示されているフィルターのインデックスを返します。 nFilterIndex が 0 で lpstrCustomFilter が NULL の場合、システムは lpstrFilter バッファー内の最初のフィルターを使用します。 3 つのメンバーがすべて 0 または NULL の場合、システムはフィルターを使用せず、ダイアログ ボックスのファイル リスト コントロールにファイルを表示しません。

lpstrFile

種類: LPTSTR

ファイル名編集コントロールの初期化に使用される ファイル名 。 初期化が必要ない場合、このバッファーの最初の文字は NULL である必要があります。 GetOpenFileName または GetSaveFileName 関数が正常に返されると、このバッファーには、選択したファイルのドライブ指定子、パス、ファイル名、および拡張子が含まれます。

OFN_ALLOWMULTISELECT フラグが設定され、ユーザーが複数のファイルを選択した場合、バッファーには現在のディレクトリと、選択したファイルのファイル名が含まれます。 エクスプローラースタイルのダイアログ ボックスでは、ディレクトリとファイル名の文字列は NULL で区切られ、最後のファイル名の後に追加の NULL 文字が付きます。 古いスタイルのダイアログ ボックスの場合、文字列はスペースで区切られ、関数はスペースを含むファイル名に短いファイル名を使用します。 FindFirstFile 関数を使用して、長いファイル名と短いファイル名を変換できます。 ユーザーが 1 つのファイルのみを選択した場合、 lpstrFile 文字列にはパスとファイル名の間に区切り記号はありません。

バッファーが小さすぎる場合、関数は FALSE を 返し、 CommDlgExtendedError 関数は FNERR_BUFFERTOOSMALLを返します。 この場合、 lpstrFile バッファーの最初の 2 バイトには、必要なサイズ (バイトまたは文字) が含まれます。

nMaxFile

型: DWORD

lpstrFile が指すバッファーのサイズ (文字数)。 バッファーは、パスとファイル名の文字列または文字列 (終端 の NULL 文字を含む) を格納するのに十分な大きさにする必要があります。 バッファーが小さすぎてファイル情報が格納されていない場合、 GetOpenFileName 関数と GetSaveFileName 関数は FALSE を 返します。 バッファーの長さが 256 文字以上である必要があります。

lpstrFileTitle

種類: LPTSTR

選択したファイルのファイル名と拡張子 (パス情報なし)。 このメンバーには NULL を指定できます。

nMaxFileTitle

型: DWORD

lpstrFileTitle が指すバッファーのサイズ (文字数)。 lpstrFileTitle が NULL の場合、このメンバーは無視されます。

lpstrInitialDir

種類: LPCTSTR

初期ディレクトリ。 初期ディレクトリを選択するためのアルゴリズムは、プラットフォームによって異なります。

Windows 7:

1. lpstrInitialDir の値が、アプリケーションで [開く] または [名前を付けて保存] ダイアログ ボックスを初めて使用した場合に渡された値と同じ場合、ユーザーが最後に選択したパスが初期ディレクトリとして使用されます。
2. それ以外の場合、 lpstrFile に パスが含まれている場合、そのパスは初期ディレクトリになります。
3. それ以外の場合、 lpstrInitialDir が NULL でない場合は、初期ディレクトリを指定します。
4. lpstrInitialDir が NULL で、現在のディレクトリに指定されたフィルターの種類のファイルが含まれている場合、初期ディレクトリは現在のディレクトリです。
5. それ以外の場合、初期ディレクトリは現在のユーザーの個人用ファイル ディレクトリです。
6. それ以外の場合、初期ディレクトリは Desktop フォルダーです。

1. lpstrFile にパスが含まれている場合、そのパスは初期ディレクトリです。
2. それ以外の場合、 lpstrInitialDir は初期ディレクトリを指定します。
3. それ以外の場合、アプリケーションで過去に [開く ] または [名前を付けて保存] ダイアログ ボックスを使用した場合は、最後に使用したパスが初期ディレクトリとして選択されます。 ただし、アプリケーションが長時間実行されない場合、保存された選択したパスは破棄されます。
4. lpstrInitialDir が NULL で、現在のディレクトリに指定されたフィルターの種類のファイルが含まれている場合、初期ディレクトリは現在のディレクトリです。
5. それ以外の場合、初期ディレクトリは現在のユーザーの個人用ファイル ディレクトリです。
6. それ以外の場合、初期ディレクトリは Desktop フォルダーです。

lpstrTitle

種類: LPCTSTR

ダイアログ ボックスのタイトル バーに配置する文字列。 このメンバーが NULL の場合、システムは既定のタイトル (名前を 付けて保存 または 開く) を使用します。

Flags

型: DWORD

ダイアログ ボックスの初期化に使用できるビット フラグのセット。 ダイアログ ボックスが戻ると、ユーザーの入力を示すようにこれらのフラグが設定されます。 このメンバーには、次のフラグを組み合わせて使用できます。

nFileOffset

種類: WORD

パスの先頭から lpstrFile が指す文字列内のファイル名までの 0 から始まるオフセット (文字数)。 ANSI バージョンの場合、これはバイト数です。Unicode バージョンの場合、これは文字数です。 たとえば、 lpstrFile が "c:\dir1\dir2\file.ext" という文字列を指している場合、このメンバーには"file.ext" 文字列のオフセットを示す値 13 が含まれます。 ユーザーが複数のファイルを選択した場合、 nFileOffset は最初のファイル名へのオフセットです。

nFileExtension

種類: WORD

パスの先頭から lpstrFile が指す文字列内のファイル名拡張子までの 0 から始まるオフセット (文字数)。 ANSI バージョンの場合、これはバイト数です。Unicode バージョンの場合、これは文字数です。 通常、ファイル名の拡張子は、ドット (".") 文字が最後に出現した後の部分文字列です。 たとえば、txt はファイル名 readme.txt の拡張子で、html は readme.txt.html の拡張子です。 したがって、 lpstrFile が 文字列 "c:\dir1\dir2\readme.txt" を指している場合、このメンバーには値 20 が含まれます。 lpstrFile が文字列 "c:\dir1\dir2\readme.txt.html" を指している場合、このメンバーには値 24 が含まれます。 lpstrFile が文字列 "c:\dir1\dir2\readme.txt.html." を指している場合、このメンバーには値 29 が含まれます。 lpstrFile が "c:\dir1\dir2\readme" などの "." 文字を含まない文字列を指している場合、このメンバーには 0 が含まれます。

lpstrDefExt

種類: LPCTSTR

既定の拡張機能。 GetOpenFileName と GetSaveFileName は、ユーザーが拡張子の入力に失敗した場合に、この拡張子をファイル名に追加します。 この文字列は任意の長さにできますが、最初の 3 文字のみが追加されます。 文字列にピリオド (.) を含めないようにしてください。 このメンバーが NULL で、ユーザーが拡張機能の入力に失敗した場合、拡張子は追加されません。

lCustData

型: LPARAM

システムが lpfnHook メンバーによって識別されるフック・プロシージャーに渡すアプリケーション定義データ。 システムが WM_INITDIALOG メッセージをフック・プロシージャーに送信する場合、メッセージの lParam パラメーターは、ダイアログ・ボックスの作成時に指定された OPENFILENAME 構造体へのポインターです。 フック プロシージャでは、このポインターを使用して lCustData 値を取得できます。

lpfnHook

種類: LPOFNHOOKPROC

フック プロシージャへのポインター。 Flags メンバーに OFN_ENABLEHOOK フラグが含まれていない限り、このメンバーは無視されます。

OFN_EXPLORER フラグが Flags メンバーに設定されていない場合、lpfnHook は、ダイアログ ボックス用のメッセージを受信する OFNHookProcOldStyle フック プロシージャへのポインターです。 フック プロシージャは 、既定 のダイアログ ボックス プロシージャにメッセージを渡す場合は FALSE を返し、メッセージを破棄するには TRUE を 返します。

OFN_EXPLORERが設定されている場合、lpfnHook は OFNHookProc フック プロシージャへのポインターです。 フック プロシージャは、ダイアログ ボックスから送信された通知メッセージを受信します。 フック プロシージャは、子ダイアログ テンプレートを指定して定義した追加のコントロールのメッセージも受信します。 フック プロシージャは、既定のダイアログ ボックスの標準コントロールを対象としたメッセージを受信しません。

lpTemplateName

種類: LPCTSTR

hInstance メンバーによって識別されるモジュール内のダイアログ テンプレート リソースの名前。 番号付きダイアログ ボックス リソースの場合、 MAKEINTRESOURCE マクロによって返される値を指定できます。 フラグ メンバーで OFN_ENABLETEMPLATE フラグが設定されていない限 り、この メンバーは無視されます。 OFN_EXPLORER フラグが設定されている場合、システムは指定されたテンプレートを使用して、既定のエクスプローラー スタイルのダイアログ ボックスの子であるダイアログ ボックスを作成します。 OFN_EXPLORER フラグが設定されていない場合、システムはテンプレートを使用して、既定のダイアログ ボックスを置き換える古いスタイルのダイアログ ボックスを作成します。

lpEditInfo

このメンバーは条件付きでコンパイルされ (を使用) #ifdef _MAC、Motorola 68K Macintosh コンピューターにのみ適用され、Windows クライアント オペレーティング システムには適用されません。

lpstrPrompt

このメンバーは条件付きでコンパイルされ (を使用) #ifdef _MAC、Motorola 68K Macintosh コンピューターにのみ適用され、Windows クライアント オペレーティング システムには適用されません。

pvReserved

型: void*

このメンバーは予約されています。

dwReserved

型: DWORD

このメンバーは予約されています。

FlagsEx

型: DWORD

ダイアログ ボックスの初期化に使用できるビット フラグのセット。 現在、このメンバーには 0 または次のフラグを指定できます。

注釈

互換性上の理由から、フラグが OFN_ENABLEHOOK に設定され、lStructSize がOPENFILENAME_SIZE_VERSION_400されている場合、Places バーは非表示になります。

要件

こちらもご覧ください

共通ダイアログ ボックス ライブラリ

概念

GetOpenFileName

GetSaveFileName

その他のリソース

リファレンス

SHGetSpecialFolderLocation