API Tip

GetSaveFileName API Function       

      For this week's API Tip, we will look at one of the common dialogs You can access through Visual Basic using API functions. Of course, it's not necessary to use API since Microsoft provides ActiveX control which will load common dialogs for You. However, few common dialogs cannot be accessed using the provided control, and also, using API doesn't require ComCtl32.ocx file. That reduces installation package space!

GetSaveFileName is used to load Save  File dialog box. Using the function, You can allow the user to select the location and the name of the file which they want to save. Then, the function will return the path and filename of the file the user chose. The declaration of GetSaveFileName:

Public Declare Function GetSaveFileName Lib "comdlg32.dll" Alias "GetSaveFileNameA" (pOpenfilename As OPENFILENAME) As Long

All this code above has to be declared in one line. OPENFILENAME structure looks like this:

Public Type OPENFILENAME
   lStructSize As Long
   hwndOwner As Long
   hInstance As Long
   lpstrFilter As String
   lpstrCustomFilter As String
   nMaxCustFilter As Long
   nFilterIndex As Long
   lpstrFile As String
   nMaxFile As Long
   lpstrFileTitle As String
   nMaxFileTitle As Long
   lpstrInitialDir As String
   lpstrTitle As String
   flags As Long
   nFileOffset As Integer
   nFileExtension As Integer
   lpstrDefExt As String
   lCustData As Long
   lpfnHook As Long
   lpTemplateName As String
End Type

That's the same structure you use to call GetOpenFileName function. Don't get scared because of the size of this thing. In the example, You'll see that this function is pretty straightfoward and easy to use. Just copy the whole OPENFILENAME into the module.

 Example: Shows Save File dialog box:

      Private Sub cmdOpen_Click()

           Dim retVal As Long ' return value of the function
           Dim opfS As OPENFILENAME ' variable to hold the structure

           Const MAX_BUFFER = 255 ' the maximum length of the file name

           With opfS ' populate the structure
                 .lStructSize = Len(opfS) ' the size of the structure
                 .hwndOwner =Form1.hWnd ' the owner of the dialog (the form handle)
                 .hInstance = App.hInstance ' instance of the app, use App.hInstance
                 .lpstrTitle = "Save File..." ' the title of the dialog box
                 .lpstrInitialDir ="c:\"  ' initial directory which the user will see
                 .lpstrFilter = "All Files" & Chr$(0) & "*.*" & Chr$(0) ' what files to show
                 .nFilterIndex = 1 '
                 .lpstrDefExt = ".txt" ' the default extention of the file to be saved
                 .lpstrFile = String(MAX_BUFFER+1, 0) ' initialize empty string to get 'filename
                 .nMaxFile = MAX_BUFFER ' the maximum length of the filename
                 .lpstrFileTitle = .lpstrFile '
                 .nMaxFileTitle = MAX_BUFFER
           End With

           retVal = GetSaveFileName(opfS)

           If rc Then msgbox opfS.lpstrFile ' show what the user picked

End Sub

Once You obtain the path of the file the user selected, You can use it to save data on the hard disk.

Next bonus TIP!!!: How present a dialog for selecting a folder using just Win API!!!