ssCore.App.showFileSave

Display the Windows File Save dialog to allow the user to select a target file name and path. This does not actually create or save a file, it just returns the selected file name and path which you can use in future file operations.


Availability:

First available in version 3.0 build 2039.


Input Parameters:

caption - [Optional] - Text that should be displayed in the title bar of the file save dialog. If not supplied, a default title of 'Save' will be used.

path - [Optional] - The initial directory displayed in the file save dialog. If you leave this parameter blank Windows will choose the default directory. This parameter supports monikers.

filter - [Optional] - A filter to restrict the types of files that will be displayed in the dialog.

filename - [Optional] - A default file name that will be used to populate the File Name field on the file save dialog. The user can override this setting.

style - [Optional] - The initial style for the list view in the dialog. Valid values include: largeicons, smallicons, iconlist, details, thumbnails, tiles, and vista.


Output Parameters:

filterIndex - The index of the selected filter from the input filter list. Index values start at 1. The index value will be -1 in the case of an error or if the user cancels the dialog without selecting a file.

filterName - The name portion of the selected filter e.g. 'Text Files'. The filter name will be an empty string in the case of an error.

filterMask - The pattern portion of the selected filter e.g. '*.txt'. The filter mask will be an empty string in the case of an error.

result - A fully qualified file selected by the user. The file save dialog does not check to deteremine whether the file exists or not, you will have to do this yourself.


Asynchronous Mode:

When this method is called asynchronously, a return object containing the output parameters is passed to the specified callback function.

ssCore.App.showFileSave( paramsObject [, callbackParamsObject] [, errorParamsObject] );


Synchronous Mode:

When this method is called synchronously, a return object containing the output parameters is returned to the caller immediately.

var returnObject = ssCore.App.showFileSave( paramsObject );


Notes:

The filter is just a string containing pairs of values delimited by "|" characters. The last string in the buffer must be terminated by two "|" characters. If you leave the filter blank the default filter includes all files.

The first string in each pair is a display string that describes the filter (for example, "Text Files"), and 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.

The explicit filter for all files is "All Files|*.*||". If you wanted to list more than one type of file you would use "Word Documents|*.doc|Excel Documents|*.xls||". If you wanted to include just HTML documents (which have multiple extensions like HTM and HTML) you would use a filter like this "HTML Documents|*.htm;*.html||".

On XP "smallicons" is the same as "iconlist" and "tiles" is the same as "largeicons".

On Vista you can use the "vista" style to use the new Vista style file dialog. Once you do this, the other list styles can't be used and the position of the dialog may not be centered on the application (it will remember the last location instead.


Examples:

// Make sure the window is visible.
ssCore.Win.show();

var return_obj = ssCore.App.showFileSave({caption:"Save file", filter:"Text files|*.txt||", filename:"default.txt"});

ssDebug.trace(return_obj.result);