Tips of VC++ > ダイアログ > OPENFILENAME構造体
★ 前へ戻る ★ 次へ進む ★

OPENFILENAME構造体

以下の文章は主にMSDNの日本語訳です。 ここでは構造体の説明しかしないので、実際にコモンダイアログを使う場合は 次の章をお読みください。
とにかく長いです。読む方は覚悟して読んで下さい。

OPENFILENAME構造体はコモンダイアログボックスを 初期化するために使う情報を保持しています。 ユーザーがダイアログを閉じた後、 システムはこの構造体の中にユーザーの選択の情報を戻します。 

typedef struct tagOFN { 
  DWORD         lStructSize; 
  HWND          hwndOwner; 
  HINSTANCE     hInstance; 
  LPCTSTR       lpstrFilter; 
  LPTSTR        lpstrCustomFilter; 
  DWORD         nMaxCustFilter; 
  DWORD         nFilterIndex; 
  LPTSTR        lpstrFile; 
  DWORD         nMaxFile; 
  LPTSTR        lpstrFileTitle; 
  DWORD         nMaxFileTitle; 
  LPCTSTR       lpstrInitialDir; 
  LPCTSTR       lpstrTitle; 
  DWORD         Flags; 
  WORD          nFileOffset; 
  WORD          nFileExtension; 
  LPCTSTR       lpstrDefExt; 
  LPARAM        lCustData; 
  LPOFNHOOKPROC lpfnHook; 
  LPCTSTR       lpTemplateName; 
#if (_WIN32_WINNT >= 0x0500)
  void *        pvReserved;
  DWORD         dwReserved;
  DWORD         FlagsEx;
#endif // (_WIN32_WINNT >= 0x0500)
} OPENFILENAME, *LPOPENFILENAME;
lStructSize
構造体のサイズをバイト単位で指定します。
Windows95/98/NT4.0かつWINVERと_WIN32_WINNT>=0x0500が定義されていれば ここのメンバにはOPENFILENAME_SIZE_VERSION_400を使えと書いてあります。 ちなみに私の環境ではそんなもん定義されてないぞとコンパイラに怒られました。 と言うわけで普通にsizeofを使ってください。 （できれば使ってみたかったのですが…）
hwndOwner
ダイアログボックスを所有するウィンドウへのハンドルを指定します。 NULLを指定するとダイアログボックスはオーナー(owner)を持ちません。
hInstance
FlagsメンバにOFN_ENABLETEMPLATEHANDLEが設定されている場合、 ダイアログボックステンプレートを所有している メモリオブジェクトへのハンドルを指定します。
また、OFN_ENABLETEMPLATEが設定されている場合は lpTemplateメンバによって指定されたダイアログテンプレートを所有する モジュールへのハンドルを指定します。
さらにOFN_EXPLORERフラグが設定されている場合は システムはエクスプローラスタイルのダイアログを作成するために 指定されたテンプレートを使います。 上記の三つのフラグがいずれも設定されていない場合は、 この値はNULLに設定しておいてください。
lpstrFilter
任意の数のNULL文字で終わる文字列のペアを保持する バッファへのポインタを指定します。 バッファの最後の文字列はNULL文字を重ねてください。
それぞれのペアの最初の文字列(first string)は フィルターを記述するためにコンボボックスに 表示される文字列(display string)です。（例えば、"Text Files"みたいな感じ）
ペアのもう一つの文字列(second string)は フィルタパターン(filter pattern)を指定します。（例えば"*.txt"） 一つのdisplay stringの中で複数のfilter patternを使うときは、 セミコロン[;]で分けて使います。（例えば、"*.txt;*.doc;*.bak"というように） filter patternではアスタリスク[*]をワイルドカードとして ファイル名にも使うことができます。
filter patternには空白を含めないでください。
このメンバがNULLだった場合、ダイアログボックスにはフィルターを表示しません。
lpstrCustomFilter
ユーザーによって選ばれ(chosen)たfilter patternを保持するための NULL文字で終わる文字列の一つのペアを所有する静的(static)バッファへのポインタです。 ペアの最初の文字列(first string)は カスタムフィルタ(custom filter)を記述するdisplay stringです。 ペアのもう一つの文字列(second string)はユーザーによって選択された フィルタパターンです。
アプリケーションがダイアログボックスを最初に作成するとき、 空ではない(nonempty)文字列をfirst stringに指定してください。 ユーザーがファイルを選択したとき、ダイアログボックスはsecond stringへ 現在のフィルタパターン(current filter pattern)をコピーします。 保存されたfilter patternはlpstrFilterで指定されていたパターンの一つであるか、 もしくはユーザによって入力されたfilter patternです。 システムは次にダイアログボックスを作るとき、 ユーザ定義のフィルタ(user-defined file filter)を初期化するために文字列を使います。
もし、nFilterIndexが0だった場合、ダイアログボックスは custom filterを使っているということです。
このメンバをNULLにすると、ダイアログボックスは ユーザー定義のフィルタパターンを保存しません。
このメンバがNULLでなければ、nMaxCustFilterでサイズを指定しなければなりません。
nMaxCustFilter
lpstrCustomFilterで識別されるバッファのサイズをTCHARで指定します。 ANSI Versionではバイト数、Unicode versionでは文字数のことです 少なくともバッファは40くらい確保しておくべきです。
lpstrCustomFilterがNULLかNULL文字へのポインタだった場合、 この値は無視されます。
nFilterIndex
File Typesコンボボックスで、 表示させるフィルターのインデックスを指定します。 lpstrFilterが保持する幾つかのペアで、 最初のペアのインデックスは1、次のペアは2というふうになっています。 0というインデックスを指定すると、lpCustomFilterによって指定されている custom filterを表示します。 このメンバを設定することにより、 ダイアログボックスのコンボボックスの内容を初期化することができます。 また、ユーザがファイルを選択した後このメンバには 現在、表示されているフィルタのインデックスが返されます。
このメンバが0で、かつlpstrCustomFilterがNULLだった場合、 システムはlpstrFilterの最初のフィルターを使います。 lpstrFilterもNULLだった場合、システムはフィルターを使わず、 ダイアログのファイルリストコントロールには何もファイルは表示されません。
lpstrFile
File Nameエディットコントロールを初期化するために使う ファイル名を保持するバッファへのポインタを指定します。 エディットボックスの初期化が必要でない場合は、 このバッファの先頭の値を0にしておいてください。 GetOpenFileNameかGetSaveFileName関数が成功したとき バッファには選択されたファイルのフルパスが格納されます。
FlagsメンバにOFN_ALLOWMULTISELECTフラグが設定されていて ユーザーが複数のファイルを選択した場合、 バッファには選択されたファイルパスに従って決められる カレントディレクトリ(current directory)が格納されます。
エクスプローラスタイルのダイアログの場合、 ディレクトリとファイル名はNULLで区切られ、 最後のファイル名の後には余分なNULL文字で埋められます。
従来のスタイルのダイアログボックスの場合、 文字列は空白で区切られ、関数は空白を含むファイル名は 短いファイル名(short file name)を使います。 短いファイル名と長いファイル名を相互に変換するために、 FindFirstFile関数を使うことができます。
ユーザーが一つのファイルだけを選択した場合、 このメンバはディレクトリとファイル名の間に区切り文字を含ませません。
バッファのサイズが小さすぎた場合、関数はFALSEを返し、 CommDlgExtendedError関数を呼んだときFNERR_BUFFERTOOSMALLを返します。 この場合、バッファの最初の二バイトに必要とされるバイト数、または文字数を格納します。
nMaxFile
lpstrFileのバッファのサイズをTCHARで指定します。 ANSI Versionではバイト数、Unicode versionでは文字数のことです
バッファのサイズが末端のNULL文字も含めてパスを格納するのに 十分に余裕があるくらいでなければなりません。 バッファのサイズが小さすぎた場合、GetOpenFileName、 またはGetSaveFileName関数はFALSEを返します。 少なくとも256バイトは確保するべきです。
lpstrFileTitle
選択されたファイルのパスを含まない(without path information) ファイル名と拡張子を受け取るためのバッファへのポインタを指定します。 このメンバはNULLに設定することができます。
nMaxFileTitle
lpstrFileTitleのバッファのサイズをTCHARで指定します。 ANSI Versionではバイト数、Unicode versionでは文字数のことです。
このメンバはlpstrFileTitleがNULLのときは無視されます。
lpstrInitialDir
このメンバで初期ディレクトリ(initial directory)を指定することができます。 initial directoryを設定するアルゴリズムは プラットフォームによって違いますが、Win98の場合だけを記します。
  1. lpstrInitialDirによって初期ディレクトリが決定されます。
  2. lpstrInitialDirがNULLでlpstrFileがパスを保持している場合、 そのパスが初期ディレクトリになります。
  3. さもなければ、カレントディレクトリにフィルタタイプに合致する ファイルがある場合、初期ディレクトリがかれんとディレクトリになります。
  4. さもなければ、初期ディレクトリはカレントユーザー(current user)の マイドキュメントフォルダ(personal files directory)になります。
lpstrTitle
ダイアログボックスのタイトルバーに表示される文字列を指定します。 このメンバがNULLだった場合、システムが標準のタイトル(default title)をつけます。
Flags
ダイアログボックスを初期化するために フラグの組み合わせを利用することができます。 柿のフラグの組み合わせを利用することができます。 （フラグの一覧はこのページの一番下）
nFileOffset
lpstrFileで指定されるファイルパスの文字列の先頭から ファイル名までを0を基準とするオフセットで表します。 ANSI Versionではバイト数、Unicode versionでは文字数のことです。
例えばlpstrFileが"c:\dir1\dir2\file.ext"だった場合、 このメンバは13になります。 この値は'f'の相対位置を表しています。
ユーザーが複数のファイルを選択している場合は、 最初のファイル名へのオフセットが格納されます。
nFileExtension
lpstrFileで指定されるファイルパスの文字列の先頭から 拡張子までを0を基準とするオフセットで指定します。 ANSI Versionではバイト数、Unicode versionでは文字数のことです。
例えばlpstrFileが"c:\dir1\dir2\file.ext"だった場合、 このメンバは18になります。 この値は'e'の相対位置を表しています。
ユーザーが拡張子を入力せず、かつlpstrDefExtメンバがNULLだった場合、 このメンバは末端のNULL文字へのオフセットを保持しています。
ユーザーがファイル名の末端に"."を入力した場合、このメンバは0になります。
lpstrDefExt
標準の拡張子(default extension)を保持するバッファへのポインタを指定します。 ユーザーが拡張子を入力しなかった場合、 GetOpenFileNameやGetSaveFileName関数は ファイル名にこの拡張子を追加します。 この文字列は任意の長さを取ることができますが、先端の三文字だけが追加されます。 この文字列はピリオド[.]を含むべきではありません。
このメンバがNULLで、かつユーザーが拡張子を入力しなかった場合、 拡張子は何も追加されません。
lCustData
lpfnHookメンバによって識別されるプロシージャ(hook procedure)に システムが渡すアプリケーション定義(application-defined)のデータを指定します。 システムがプロシージャにWM_INITDIALOGメッセージを送ったとき、 そのときのlParam（第四引数）の値がダイアログボックスが作成されたときの OPENFILENAME構造体へのポインタになっています。 プロシージャの中でこのメンバが指すポインタを取得することができます。
lpfnHook
フックプロシージャ(hook procedure)へのポインタです。 FlagsメンバにOFN_ENABLEHOOKフラグが設定されてない場合、 このメンバは無視されます。
OFN_EXPLORERが設定されていなければ、このメンバは OFNHookProcOldStyleプロシージャへのポインタとなります。 そのプロシージャは標準のダイアログボックスプロシージャ (default dialogbox procedure)に制御を移すためにはFALSEを、 また、そこでメッセージを破棄するにはTRUEを返す必要があります。
OFN_EXPLORERが設定されていれば、このメンバは OFNHookProcプロシージャへのポインタとなります。
プロシージャはダイアログボックスから送られた メッセージ(notification message)を受け取ります。 また、プロシージャはダイアログテンプレートを使うことによって 追加されたコントロールのメッセージも受け取ります。 しかし、ダイアログボックスの標準のコントロールに 意図されるメッセージは受け取りません。
lpTemplateName
hInstanceメンバで識別されるモジュールのダイアログテンプレートリソースを示す NULLで終わる文字列へのポインタを指定します。 ダイアログリソースを示すIDのときはMAKEINTRESOURCEマクロを使うことができます。 FlagsメンバにOFN_ENABLETEMPLATEが設定されていなければ、 この値は無視されます。
OFN_EXPLORERが設定されている場合、システムは 標準のエクスプローラスタイルのダイアログを作成するために ここで指定されるテンプレートを使います。 OFN_EXPLORERフラグが設定されてない場合、 システムは従来のスタイルのダイアログボックスを作成するために このテンプレートを使います。
pvReserved
予約されています。
dwReserved
予約されています。
FlagsEx
Windows2kだけで使われるメンバなので、記述しません。

これより、Flagsメンバで指定することができるフラグを載せます。 なにしろ量が半端じゃないのである程度短くまとめて説明したものもあります。 Windows2kでしかサポートされていないものは説明を略させていただきます。 あらかじめご了承ください。

OFN_ALLOWMULTISELECT
File Nameリストボックスで複数の選択ができるようにします。
ユーザーが複数のファイルを選択した場合、 lpstrFileのバッファは選択されたファイルに従って カレントディレクトリへのパスを返します。 nFileOffsetは最初のファイル名へのオフセットです。 nFileExtensionは使われません。
エクスプローラスタイルのダイアログボックスでは、 ディレクトリとファイル名の文字列はNULLで区切られ、 末端のファイル名の後はNULL文字で埋められます。 この形式を使うことにより、エクスプローラスタイルのダイアログでは 空白を含む長いファイル名(long file name)でも返すことができます。
従来のスタイルのダイアログでは、ディレクトリとファイル名の文字列は 空白で区切られるので、空白を含むファイル名では 短いファイル名(short file name)を使います。 本来のファイル名に変換するにはFindFirstFile関数を使ってください。
OFN_CREATEPROMPT
ユーザーが存在しないファイルを選択しようとしたとき、 確認ダイアログを表示します。
ユーザーがファイルを作るように指示したときは 関数は指定されたファイル名を返します。 そうでなければ、ダイアログは開いたままになります。
OFN_DONTADDTORECENT
Win2kでのみサポートされています。
OFN_ENABLEHOOK
lpfnHookメンバでフック関数(hook function)へのポインタを指定できるようにします。
OFN_ENABLEINCLUDENOTIFY
Win2kでのみサポートされています。
OFN_ENABLESIZING
エクスプローラスタイルのダイアログをサイズ変更可能にします。 このフラグを設定しなくても、デフォルトの設定で エクスプローラスタイルのダイアログはサイズ変更可能になっています。 したがって、このフラグを設定しなければいけない場合というのは カスタムテンプレート(custom template)を使うときか、 フックプロシージャ(hook procedure)を使うときです。
従来のスタイルのダイアログでは、もともとサイズ変更をサポートしていません。
OFN_ENABLETEMPLATE
lpTemplateNameメンバがhInstanceメンバで指定されるモジュールの ダイアログテンプレートリソースの名前へのポインタであることを示します。
OFN_ENABLETEMPLATEHANDLE
hInstaceメンバが既にロード(preloaded)されている ダイアログテンプレートを所有するデータブロック(data block)であることを示します。
OFN_EXPLORER
ダイアログがエクスプローラスタイルを使うようにします。
このフラグを設定しなくても、デフォルトでダイアログは エクスプローラスタイルのインターフェイス(Explorer-style user interface)を 使うようになっています。 このフラグはフックプロシージャ(hoook procedure)か カスタムテンプレート(custom template)を使うとき、また、 OFN_ALLOWMULTISELECTと併用するときのみ設定します。
もしエクスプローラスタイルを使いたくないのであれば、 OFN_EXPLORERフラグを省略する(omit)か、 従来のスタイルのテンプレート、またはフックプロシージャで 置き換え(replacement)てください。
OFN_EXTENSIONDIFFERENT
ユーザーの入力した拡張子がlpstrDefExtで指定された拡張子とは違うことを示します。
lpstrDefExtメンバがNULLであれば、関数はこのフラグを使いません。
OFN_FILEMUSTEXIST
ユーザーが存在するファイルしか選択できないようにします。 もし存在しないファイルを選択しようとしたときは、 システムがダイアログを表示します。
このフラグを設定すると自動的にOFN_PATHMUSTEXISTフラグも使われます。
OFN_FORCESHOWHIDDEN
Win2kでのみサポートされています。
OFN_HIDEREADONLY
Read Onlyチェックボックスを非表示にします。
OFN_LONGNAMES
従来のスタイルのダイアログボックスで、長いファイル名(long file name)を 使えるようにします。 このフラグを設定せずにOFN_ALLOWMULTISELECTを設定すると、 空白を含むファイル名のために、従来のスタイルのダイアログでは 短いファイル名(short file name - 8.3 format)を使います。
エクスプローラスタイルのダイアログでは、常に長いファイル名を使うので、 このフラグは無視されます。
OFN_NOCHANGEDIR
ユーザーがファイルを検索してディレクトリを変更しても カレントディレクトリに復帰させるようにします。
OFN_NODEREFERENCELINKS
ショートカットファイル(*.lnk)が選択された場合、 そのショートカットファイルのパスが返されます。
このフラグを指定しないとショートカット先のファイルを選択するようになります。
OFN_NOLONGNAMES
従来のスタイルのダイアログが短いファイル名 (short file name - 8.3 Format)を使うようにします。
エクスプローラスタイルのダイアログでは、 常に長いファイル名(long file name)を使うので、このフラグは無視されます。
OFN_NONETWORKBUTTON
ネットワークボタンを無効にして非表示にします。
OFN_NOREADONLYRETURN
返されるファイルが読取専用ファイルでないように設定します。 （この文の訳が間違っている可能性大）
OFN_NOTESTFILECREATE
ダイアログが閉じられるまでファイルが作成されないようにします。
OFN_NOVALIDATE
返されるファイル名の中に無効な文字を含めるのを許すようにします。
OFN_OVERWRITEPROMPT
既に存在するファイルを選択したときに、 上書きの確認が出るようにします。
OFN_PATHMUSTEXIST
ユーザーが有効なパスとディレクトリしか入力できないようにします。 このフラグを設定して、ユーザーが無効なパスやファイル名を入力すると 警告のメッセージボックスが出るようになります。
OFN_READONLY
ダイアログが作成されたときに[読取専用]チェックボックスに 既にチェックが入っているようにします。
このフラグは、ダイアログが閉じられたときのチェックボックスの状態も反映しています。
OFN_SHAREWARE
ネットワーク関連のフラグなんですが、訳がよくわかりません。 あまり使わないように思われるので、説明を省略させていただきます。（ぉぃぉぃ
OFN_SHOWHELP
ダイアログにヘルプボタンを表示させます。 ユーザーがヘルプボタンを押したときにダイアログが送るHELPMSGSTRINGメッセージを hwndOwnerで指定したウィンドウが受け取らなければなりません。