對話盒(4)通用對話盒

from http://home.educities.edu.tw/wanker742126/win32asm/w32asm_ch11.html

 

GetOpenFileName 的用法

GetOpenFileName API 將會顯示一個系統預先定義好的通用對話盒 ( 如上面圖一、圖二 )，供使用者在清單控件選定檔名或是在編輯框中輸入檔名。當使用者選好檔名或由編輯框輸入檔名並按下『開啟舊檔』下壓式按鈕控件後，GetOpenFileName 傳回 TRUE，並在 OPENFILENAME 結構體的 lpstrFile 欄位所指定位址內，填入被選定的檔名；如果使用者按下『取消』下壓式按鈕，則傳回 FALSE。至於接下來的工作，如開啟檔案、讀取檔案、寫入檔案、關閉檔案……等工作，必須由其他程式負責，GetOpenFileName 不做開啟、讀取、寫入…檔案等工作。GetOpenFileName 之原型為：

BOOL GetOpenFileName(
   LPOPENFILENAME   lpofn   // address of structure with initialization data
   );

lpofn 是一個指標，指向一個稱為 OPENFILENAME 的結構體，這個結構體的欄位如下：

OPENFILENAME      struc
lStructSize       DWORD          ?    ;結構體大小
hwndOwner         HWND           ?    ;父視窗代碼
hInstance         HINSTANCE      ?    ;執行實例代碼
lpstrFilter       LPCTSTR        ?    ;指向檔名篩選字串位址
lpstrCustomFilter LPTSTR         ?    ;指向自訂檔名篩選字串位址
nMaxCustFilter    DWORD          ?    ;自訂檔名篩選字串大小
nFilterIndex      DWORD          ?    ;顯示於檔案類型的檔名篩選字串
lpstrFile         LPTSTR         ?    ;完整檔名位址
nMaxFile          DWORD          ?    ;完整檔名大小
lpstrFileTitle    LPTSTR         ?    ;主檔名位址
nMaxFileTitle     DWORD          ?    ;主檔名大小
lpstrInitialDir   LPCTSTR        ?    ;起始子目錄
lpstrTitle        LPCTSTR        ?    ;對話盒標題
Flags             DWORD          ?    ;建立對話盒時的各項設定
nFileOffset       WORD           ?    ;主檔名在完整檔名的第幾個位址
nFileExtension    WORD           ?    ;副檔名在完整檔名的第幾個位址
lpstrDefExt       LPCTSTR        ?    ;預設的副檔名
lCustData         DWORD          ?    ;傳給攔截函式的資料
lpfnHook          LPOFNHOOKPROC  ?    ;攔截函式位址
lpTemplateName    LPCTSTR        ?    ;自訂對話盒模版名
OPENFILENAME      ends

OPENFILENAME 的欄位說明如下：

• lStructSize：OPENFILENAME 結構體長度，以位元組為單位，這是為了往後的擴充性。當 COMDLG32.DLL 版本改變時，系統檢查此欄位就可以得知正確的版本。
  
• hwndOwner：擁有『開啟舊檔』或『另存新檔』通用對話盒的視窗。此欄位可填入該視窗之視窗代碼，也可填入 NULL，表示不屬任何視窗。
  
• hInstance：如果 Flags 被設為 OFN_ENABLETEMPLATE，則 hInstance 為擁有 lpTemplateName 所指對話盒模版的模組代碼；如果 Flags 被設為 OFN_ENABLETEMPLATEHANDLE，則 hInstance 為擁有此對話盒模版的記憶體物件 ( memory object ) 代碼；如果 Flags 都沒有設定 OFN_ENABLETEMPLATE 或 OFN_ENABLETEMPLATEHANDLE 的話，則系統忽略 hInstance。
  
• lpstrFilter：指向檔名篩選字串之位址。此字串將會填入圖一或圖二的『檔案類型』右邊的複合控件裏，表示要選擇的檔案類型，符合此類型的檔案將會顯示在圖一或圖二裏最大的清單控件裏。檔名篩選字串是以兩個字串為一組，前一個字串表示類型，將顯示於複合控件的編輯框內；後一個字串表示篩選依據，系統將以此字串篩選符合的檔名，顯示於最大的清單內，此字串可以包含萬用字元，若同一類型有兩種篩選依據時，可用『;』隔開。兩字串中間以 0 隔開，每組字串也以 0 相隔。當檔名篩選字串結束時，必須以兩個 0 結尾。例如檔案類型有 *.EXE 檔及 *.DLL 檔時，可以用

  strFNFilter   db    '可執行檔(*.EXE)',0,'*.EXE',0
                db    '動態連結庫(*.DLL)',0,'*.DLL',0,0

  來表示。
  
• lpstrCustomFilter：指向一個記憶體位址，此記憶體將儲存使用者自訂的檔名篩選字串。如果不需要，則可以設為 NULL，而下一個欄位，nMaxCustFilter 會被系統忽略。
  
• nMaxCustFilter：自訂檔名篩選字串大小，ANSI 版以位元組為單位，萬國碼版本以字元為單位 ( Win9x、Me 屬 ANSI，NT、2K、XP 屬萬國碼 )。見上一個欄位 lpstrCustomFilter。
  
• nFilterIndex：一開始顯示在『開啟舊檔』對話盒中，檔案類型右邊的複合控件編輯框內的字串，由 1 開始。例如 lpstrFilter 為

  strFNFilter   db    '可執行檔(*.EXE)',0,'*.EXE',0
                db    '動態連結庫(*.DLL)',0,'*.DLL',0,0

  而 nFilterIndex 為 2 時，複合控件之編輯框會顯示『動態連結庫(*.DLL)』，而清單也會篩選出副檔名為 *.DLL 的檔案。
  
• lpstrFile：指向一檔名字串之位址。當使用者選定檔名，並按下『開啟舊檔』中的『確定』按鈕控件結束『開啟舊檔』對話盒之後，系統將會在把完整之檔名，包含磁碟機名、路徑名、主檔名、副檔名填入此檔名字串中。
  
• nMaxFile：檔名字串之大小，ANSI 版以位元組為單位，萬國碼版本以字元為單位。( Win9x、Me 屬 ANSI，NT、2K、XP 屬萬國碼 )
  
• lpstrFileTitle：指向一檔名字串位址，當使用者選定一檔名後，系統將把此主檔名及副檔名填入此字串 ( 不含磁碟機名及路徑名 )。此欄位可設為 NULL，表示不用此功能。
  
• nMaxFileTitle：上個欄位，lpstrFileTitle 之大小，如果 lpstrFileTitle 為 NULL 時，系統將忽略此欄位。ANSI 版以位元組為單位，萬國碼版本以字元為單位。
  
• lpstrInitialDir：指向子目錄字串之位址，這個子目錄是『開啟舊檔』對話盒一開始的目錄，如果設為 NULL，表示使用程式所在的目錄。
  
• lpstrTitle：指向標題欄字串位址，此字串將顯示於『開啟舊檔』或『另存新檔』對話盒的標題欄。如果使用 NULL，則視呼叫 GetOpenFileName 或 GetSaveFileName 顯示『開啟舊檔』或『另存新檔』於標題欄。
  
• Flags：此欄位決定對話盒的某些行為，下表的每個名稱都代表雙字組的某一位元，此欄位可以是這些位元之組合。常用的位元如下表：

  位元值	說　　　明
  OFN_ALLOWMULTISELECT	允許同時選擇多個檔案。
  OFN_CREATEPROMPT	如果使用者在編輯框輸入了不存在的檔案，對話盒會提示另一個『這個檔案不存在，要建立檔案嗎』的對話盒，如果使用者按下否，則仍回到原對話框；若按下是，則建立新檔。
  OFN_ENABLEHOOK	設定此位元後，才能使 lpfnHook 有作用。
  OFN_ENABLETEMPLATE	見 hInstance 欄位
  OFN_ENABLETEMPLATEHANDLE	見 hInstance 欄位
  OFN_FILEMUSTEXIST	使用者只能由清單控件中選擇檔名。當使用此位元時，同時必須設定 OFN_PATHMUSTEXIST。
  OFN_HIDEREADONLY	不顯示『以唯讀方式開啟』檢驗盒控件。
  OFN_OVERWRITEPROMPT	當呼叫 GetSaveFileName，並選擇已存在的檔案時，系統會詢問式否覆寫。
  OFN_PATHMUSTEXIST
  OFN_READONLY	顯示『以唯讀方式開啟』檢驗盒控件，並且當對話盒開啟時，此檢驗盒就已被選定。

  
  
• nFileOffset：檔名在 lpstrFile 所指字串的第幾個位址，從零開始。例如，lpstrFile 所指的檔名是『D:/HomePage/SOURCE/bless.txt』，則 nFileOffset 為 19。
  
• nFileExtension：檔名在 lpstrFile 所指字串的第幾個位址，從零開始。例如，lpstrFile 所指的檔名是『D:/HomePage/SOURCE/bless.txt』，則 nFileExtension 為 25。如果使用者在『檔案名稱：』右邊的編輯框沒有輸入副檔名且 lpstrDefExt 為 NULL 時，則傳回的 nFileExtension 為 NULL；如果使用者輸入『.』作為結尾，則不管 lpstrDefExt 是否為 NULL，傳回的 nFileExtension 都是由 lpstrFile 所指字串開始到『.』後面一位的位址數。
  
• lpstrDefExt：指向內定的副檔名字串。呼叫 GetOpenFileName 或 GetSaveFileName，使用者沒有輸入副檔名時，系統會自動地加上此欄所指的字串作為內定的副檔名。此字串雖然不限長度，但只有前三個字元會被加上。字串前不須加上『.』。如果此欄設為 NULL，則系統不會自動加上副檔名。
  
• lCustData：當設有訊息攔截函式 ( hook procedure ) 時，可以設定此欄位傳遞資料給訊息函式。系統發出 WM_INITDIALOG 訊息給訊息攔截函式時，lParam 參數為 OPENFILENAME 結構體的位址，因而能藉由設定此欄位，把資料傳給訊息攔截函式。
  
• lpfnHook：若 Flags 設定 OFN_ENABLEHOOK 時，此欄應設定訊息攔截函式位址；否則系統忽略此欄位。
  
• lpTemplateName：這個欄位只有在 Flags 設為 OFN_ENABLETEMPLATE 時，才有用。lpTemplateName 指向一個以零結尾的字串，此字串必須和在資源檔中的對話盒模版的名稱相同。