OPENFILENAMEA 構造体 (commdlg.h)

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

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

構文

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

メンバー

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 マクロによって返される値を指定できます。 flags メンバーで 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 または次のフラグを指定できます。

解説

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

要件

関連項目

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

概念

GetOpenFileName

GetSaveFileName

その他のリソース

リファレンス

SHGetSpecialFolderLocation