# Function Reference

# _WinAPI_GetSaveFileName

Creates a Save dialog box that lets the user specify the drive, directory, and name of a file to save

#include <WinAPIDlg.au3>
_WinAPI_GetSaveFileName ( [$sTitle = "" [, $sFilter = "All files (*.*)" [, $sInitalDir = "." [, $sDefaultFile = "" [, $sDefaultExt = "" [, $iFilterIndex = 1 [, $iFlags = 0 [, $iFlagsEx = 0 [, $hWndOwner = 0]]]]]]]]] )

## Parameters

$sTitle | [optional] string to be placed in the title bar of the dialog box
$sFilter | [optional] Pairs of filter strings (for example "Text Files (*.txt)|All Files (*.*)") The first string in each pair is a display string that describes the filter (for example, "Text Files") The second string specifies the filter pattern (for example, "*.TXT") To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (for example, "*.TXT;*.DOC;*.BAK") A pattern string can be a combination of valid file name characters and the asterisk (*) wildcard character Do not include spaces in the pattern string.
$sInitalDir | [optional] String that can specify the initial directory
$sDefaultFile | [optional] A file name used to initialize the File Name edit control
$sDefaultExt | [optional] String that contains the default extension
$iFilterIndex | [optional] Specifies the index of the currently selected filter in the File Types control
$iFlags | [optional] See Flags in $tagOPENFILENAME information
$iFlagsEx | [optional] See FlagEx in $tagOPENFILENAME information
$hWndOwner | [optional] Handle to the window that owns the dialog box. This member can be any valid window handle, or it can be 0 if the dialog box has no owner

## Return Value

Success: | an array in the following format: [0] - Contains the number of strings (2) [1] - Contains the path selected [2] - Contains file selected
Failure: | sets the @error flag to non-zero, call _WinAPI_CommDlgExtendedError() to get extended error information.

## Remarks

The dialog "Save as type" combo will allow user selection of multiple filter pattern(s) set in $sFilter - the first of these is set as default.
The $sDefaultExt parameter is of vital importance.
- If this parameter is left blank then NO file extension is appended to the returned filename regardless of the setting in the dialog "Save as type" combo, although if the user adds an extension to the filename in the dialog "File name" input then that extension is appended to the return.
- But if this parameter is set to any string value then the extension displayed in the dialog "Save as type" combo is automatically appended.

## Related

$tagOPENFILENAME, _WinAPI_CommDlgExtendedError, _WinAPI_GetOpenFileName

## See Also

Search GetSaveFileName in MSDN Library.

## Example

    #include "Extras\HelpFileInternals.au3"

    #include <GUIConstantsEx.au3>
    #include <WinAPIConstants.au3>
    #include <WinAPIDlg.au3>
    #include <WindowsStylesConstants.au3>

    _Example_Defaults()
    _Example_ExplorerStyle()
    _Example_OldStyle()
    _Example_ExplorerStyle_NoPlaceBar()

    Func _Example_Defaults()
        Local $hGui, $idBtn_Dialog, $aFile, $sError

        ; Create GUI
        $hGui = GUICreate("GetSaveFileName use defaults", 400, 296)
        _MemoCreate(2, 32, 396, 226, $WS_HSCROLL)
        $idBtn_Dialog = GUICtrlCreateButton("Save Dialog", 155, 270, 90, 20)
        GUISetState(@SW_SHOW)

        While 1
            Switch GUIGetMsg()
                Case $idBtn_Dialog
                    $aFile = _WinAPI_GetSaveFileName() ; use defaults
                    If @error Then
                        Local $iError = @error
                        Local $iExtended = @extended
                        $sError = _WinAPI_CommDlgExtendedError()
                        _MemoWrite("CommDlgExtendedError (" & $iError & "/" & $iExtended & "): " & $sError)
                    Else
                        For $x = 1 To $aFile[0]
                            _MemoWrite($aFile[$x])
                        Next
                    EndIf
                Case $GUI_EVENT_CLOSE
                    ExitLoop
            EndSwitch
        WEnd
        GUIDelete($hGui)
    EndFunc   ;==>_Example_Defaults

    Func _Example_ExplorerStyle()
        Local $hGui, $idBtn_Dialog, $aFile, $sError

        ; Create GUI
        $hGui = GUICreate("GetSaveFileName use Explorer Style", 400, 296)
        _MemoCreate(2, 32, 396, 226, $WS_HSCROLL)
        $idBtn_Dialog = GUICtrlCreateButton("Save Dialog", 155, 270, 90, 20)
        GUISetState(@SW_SHOW)

        While 1
            Switch GUIGetMsg()
                Case $idBtn_Dialog
                    $aFile = _WinAPI_GetSaveFileName("My Save File Dialog", _
                            "Text File (*.txt)|AutoIt File (*.au3)", ".", _
                            "", "au3", 2, 0, 0, $hGui)
                    If @error Then
                        Local $iError = @error
                        Local $iExtended = @extended
                        $sError = _WinAPI_CommDlgExtendedError()
                        _MemoWrite("CommDlgExtendedError (" & $iError & "/" & $iExtended & "): " & $sError)
                    Else
                        For $x = 1 To $aFile[0]
                            _MemoWrite($aFile[$x])
                        Next
                    EndIf
                Case $GUI_EVENT_CLOSE
                    ExitLoop
            EndSwitch
        WEnd
        GUIDelete($hGui)
    EndFunc   ;==>_Example_ExplorerStyle

    Func _Example_OldStyle()
        Local $hGui, $idBtn_Dialog, $aFile, $sError

        ; Create GUI
        $hGui = GUICreate("GetSaveFileName use Old Style", 400, 296)
        _MemoCreate(2, 32, 396, 226, $WS_HSCROLL)
        $idBtn_Dialog = GUICtrlCreateButton("Save Dialog", 155, 270, 90, 20)
        GUISetState(@SW_SHOW)

        While 1
            Switch GUIGetMsg()
                Case $idBtn_Dialog
                    $aFile = _WinAPI_GetSaveFileName("My Save File Dialog", _
                            "Text File (*.txt)|AutoIt File (*.au3)", ".", "", _
                            "", 2, $OFN_ALLOWMULTISELECT, 0, $hGui)
                    If @error Then
                        Local $iError = @error
                        Local $iExtended = @extended
                        $sError = _WinAPI_CommDlgExtendedError()
                        _MemoWrite("CommDlgExtendedError (" & $iError & "/" & $iExtended & "): " & $sError)
                    Else
                        For $x = 1 To $aFile[0]
                            _MemoWrite($aFile[$x])
                        Next
                    EndIf
                Case $GUI_EVENT_CLOSE
                    ExitLoop
            EndSwitch
        WEnd
        GUIDelete($hGui)
    EndFunc   ;==>_Example_OldStyle

    Func _Example_ExplorerStyle_NoPlaceBar()
        Local $hGui, $idBtn_Dialog, $aFile, $sError

        ; Create GUI
        $hGui = GUICreate("GetSaveFileName use Explorer Style No Place Bar", 400, 296)
        _MemoCreate(2, 32, 396, 226, $WS_HSCROLL)
        $idBtn_Dialog = GUICtrlCreateButton("Save Dialog", 155, 270, 90, 20)
        GUISetState(@SW_SHOW)

        While 1
            Switch GUIGetMsg()
                Case $idBtn_Dialog
                    $aFile = _WinAPI_GetSaveFileName("My Save File Dialog", _
                            "Text File (*.txt)|AutoIt File (*.au3)", ".", "", _
                            "", 2, 0, $OFN_EX_NOPLACESBAR, $hGui)
                    If @error Then
                        Local $iError = @error
                        Local $iExtended = @extended
                        $sError = _WinAPI_CommDlgExtendedError()
                        _MemoWrite("CommDlgExtendedError (" & $iError & "/" & $iExtended & "): " & $sError)
                    Else
                        For $x = 1 To $aFile[0]
                            _MemoWrite($aFile[$x])
                        Next
                    EndIf
                Case $GUI_EVENT_CLOSE
                    ExitLoop
            EndSwitch
        WEnd
        GUIDelete($hGui)
    EndFunc   ;==>_Example_ExplorerStyle_NoPlaceBar