ssCore.App.showFileOpen

Display the Windows File Open dialog to allow the user to select a file (or files) to open. This does not actually open a file, it just returns the selected file name(s) and path(s).


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 open dialog. If not supplied, a default title of 'Open' will be used.

path - [Optional] - The initial directory displayed in the file open 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.

multipleSelect - [Optional] - A boolean value the indicates whether you want the user to be able to select multiple files or just one file. Valid values include: true and false.

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 - The file or file(s) selected by the user. When the multipleSelect option is enabled and multiple files are returned, the list of files will be separated by carriage return ('\r') characters.


Asynchronous Mode:

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

ssCore.App.showFileOpen( 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.showFileOpen( 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||".

Enabling multiple file selection changes the format of the return value from a fully qualified file name to a list of fully qualified file names separated by '\r' characters. So when you enable multiple file selection you will have to split the result string and count the number of returned files.

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:

The following example displays a dialog to let the user select an XML file. The result is displayed in the SWF Studio Trace tab.

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

var return_obj = ssCore.App.showFileOpen({caption:"Select a file", filter:"XML files|*.xml||"});

ssDebug.trace(return_obj.result);