savedialog
savedialog
PATH
,
OPTION
,
VALUE

The savedialog statement displays a modal dialog that allows a user to specify the name and location of a new file.

Parameters

This statement has three parameters:

path – is a field or variable that will contain the path and filename selected by the user (see Files and Folders. If the user presses the Cancel button, this field or variable will be set to an empty string.

option – The name of an option that modifies the dialogs appearance and/or operation. See below for descriptions of each available option. The option can be specified in either upper or lower case.

value – The option value.

Description

The savedialog statement pauses a procedure and displays the standard system dialog for creating a new file. Once the user has made a choice the procedure resumes and can process the users choice. (Note: The program can determine whether the user pressed the Ok or Cancel button by checking the info(“dialogtrigger”) function. In addition, if the Cancel button is pressed the path parameter will be set to `""` (empty).)

This example allows the user to choose any location and filename for a newly exported file.

    local fileChoice
    savedialog fileChoice
    export fileChoice,exportline()

#### Dialog Options

The appearance and operation of the save dialog can be modified by adding one or more pairs of option/value parameters to the savedialog statement, like this:

    savedialog path,option1,value1,option2,value2,option3,value3,option4,value4

Each of the available options are described below.

##### InitialPath

This option specifies the folder that appears when the dialog first opens. See Files and Folders to learn more about setting up paths. This example initially opens the dialog to the Pictures folder.

    local fileChoice
    savedialog fileChoice,"InitialPath","~/Pictures"

This example initially opens the dialog to the folder containing the current database.

    local fileChoice
    savedialog fileChoice,"InitialPath",dbfolder()

If the path option is omitted, the dialog will open to the last folder accessed.

##### FileName

This option specifies the initial name that appears when the dialog first opens. Of course this is just a default, the user can edit the name once the dialog appears. This example will create a default filename based on today’s date, for example Daily Image 2014–06–04.

    savedialog fileChoice,
        "InitialPath","~/Pictures",
        "FileName","Daily Image "+datepattern(today(),"YYYY-MM-DD")+".jpg"

The default can be set based on database data. This statement will create default filenames like Mary Wilson Headshot.jpg.

    savedialog fileChoice,
        "InitialPath",dbsubfolder("Images"),
        "FileName",First+" "+Last+" Headshot.jpg"

If one or more filetypes are specified (see below), the extension can be omitted. It will automatically be supplied based on the first filetype listed. In this example, the default filename will actually be NewImage.png, not NewImage.

    savedialog fileChoice,"FileName","NewImage","FileTypes",".png.jpg"

However, if you specify a default filename with extension, that extension will be used. In this example the default is NewImage.jpg, not NewImage.jpg.png.

    savedialog fileChoice,"FileName","NewImage.jpg","FileTypes",".png.jpg"

If the filename parameter is omitted, the default filename is simply an empty name.

##### FileTypes

This option specifies one or more types of files that can be specified with the dialog. If the user attempts to type in a filename of a different type, a warning alert will appear and they will not be allowed to close the dialog. In this example, only filenames ending with .html or .css will be allowed.

    savedialog fileChoice,"FileTypes",".html.css"

If the user attempts to enter a filename with an extension that is not listed (for example stuff.csv), the dialog will not allow the save operation to continue. (However, this can be overridden with the allowanyfiletype option, see below.)

If one or more filetypes is specified, the first filetype specified will be the default extension. For example, consider the example above. If the user simply types in the name index, the statement will automatically add the .html extension, so the returned filename will be index.html. The user would also be allowed to type in the extension, so for example index.css could be entered to create a CSS file.

Legacy Support for Type/Creator Codes – The filetypes parameter also supports the older, legacy, 4 character file type codes (see typecreatorcode() in addition to file extensions. Here is an example that allows JPEG, GIF or PNG image files to be created. If you use file types then the filetypes parameter must contain a multiple of 4 characters (4, 8, 12, etc.) and must not start with a period.

    saveDialog fileChoice,"FileTypes","JPEGGIFfPNGf"

##### AllowAnyFileType

This option works with the filetypes option described above. Normally, if one or more filetypes are specified, the user is not allowed to enter an extension that is not listed. However, if this option is set to true, the user is allowed to enter any extension, even one not on the list. Why would you want to do that? Consider this example:

    saveDialog fileChoice,"FileTypes",".html","AllowAnyFileType",true()

With this statement, the saved filename will default to .html if no extension is specified. However, the user would be allowed to enter any other extension she wanted to, allowing her to create files like stuff.css, list.txt, etc.

Note: Even though this option allows the user to type in any extension he or she wants, the dialog will still ask the user to confirm the extension before completing the save operation. Because of this, it’s usually best to include all of the extensions that would commonly be used, even if you wanted to allow any extension.

    saveDialog fileChoice,"FileTypes",".html.css.txt.csv","AllowAnyFileType",true()

##### Title

This option specifies the title of the Save dialog. The title appears at the very top of the dialog, in the drag bar.

    saveDialog fileChoice,"FileTypes",".html","Title","Save New Web Page"

If this option is omitted the default name is simply Save.

##### Button

This option specifies the name of the Save button. This button appears at the lower right corner of the dialog. Within reason, the button dimensions will expand to accommodate the name you specify.

    saveDialog fileChoice,"FileTypes",".html","Button","Save New Web Page"

If this option is omitted the default button name is simply Save.

##### Prompt

This option specifies the text that appears just to the left of the filename, at the top of dialog.

    saveDialog fileChoice,"FileTypes",".html","Prompt","Web Page:"

Note: Even though their appears to be plenty of room for long prompts, OS X does not display more than about a dozen characters in the prompt area. This may be fixed in future versions of OS X.

If this option is omitted the default prompt is Save As:.

##### CanCreateFolders

The Save dialog normally has a button at the bottom left that allows the user to create new folders. This option allows you to remove this button, removing the ability to create new folders.

    saveDialog fileChoice,"FileTypes",".html","CanCreateFolders",false()

##### ShowHidden

This option allows the dialog to display files that are normally hidden, for example files that start with a period.

    saveDialog fileChoice,"FileTypes",".html","ShowHidden",true()

If this option is omitted, hidden files will not be displayed.

##### OpenPackages

This option allows the dialog to open package files as if they were regular folders. Use this option if you want to give the user the option to save a file inside a package (only very advanced users, like developers, would ever need this option).

    saveDialog fileChoice,"FileTypes",".html","OpenPackages",true()

If this option is omitted, package files are treated like regular files.

See Also

- aliaspath( -- returns the path an alias points to (or an error if the specified file isn't an alias).
- archivecontents( -- lists the contents of a compressed archive in *.zip*, *.tar.gz* or *.tar.bz2* format.
- bookmarkpath( -- converts saved bookmark data (from the filebookmark( function) into a standard file path.
- bundleresourcepath( -- returns the file path and name of a specified item in the Panorama application bundle.
- choosefiledialog -- displays a modal dialog allowing selection of files or folders.
- choosefolderdialog -- pauses and displays the standard “choose folder” dialog.
- commonpath( -- returns the path for common folders (desktop, library, documents, pictures, etc.).
- compress -- compresses a file or an entire folder.
- copyfile -- copies a file (or folder).
- copyfolder -- copies an entire folder full of files (and subfolders, if any).
- copynewerfile -- copies a file to another name or location. However, the file is only copied if it is newer than the old file, otherwise the destination is not touched.
- copynewerfile( -- copies a file to another name or location. However, the file is only copied if it is newer than the old file, otherwise the destination is not touched.
- copynewerfolder -- copies an entire folder full of files, but only copies newer files.
- dbfolder( -- returns the folder path of the folder the current database is located in.
- dbname( -- returns the name of the current database.
- dbpath( -- returns the HFS path of the folder the current database is located in.
- dbsubfolder( -- returns the path of a subfolder within the same folder as the current database.
- dropfromfinder -- processes any files or folders that have been dropped on a form from the finder.
- dropimagesfromfinder -- processes images that have been dropped on a form from the Finder. The images may be added to new records in the database or put in the current record.
- enclosingfolder( -- takes a full path and filename and returns the name of the folder that contains the file.
- enclosingpath( -- takes a full path and filename and returns the path of the folder that contains the file.
- fileappend -- appends new data to an existing disk file.
- fileattributes( -- returns attributes of the specified file or folder (date, owner, permissions, etc.).
- filebookmark( -- converts a file or folder path into a binary data value that persistently links to the file, even if it is later moved or renamed.
- filecatalog( -- builds a text array listing the files in a folder, including any subfolders of that folder.
- filedate( -- returns the modification date of a file.
- filedisplayname( -- returns the display name for the specified file or folder.
- fileerase -- erases a disk file or a folder, removing it from the hard disk.
- fileexists( -- returns true if a file exists, false if it does not.
- fileexistspath( -- tests to see if a file exists.
- fileextension( -- extracts the extension (if any) from a partial or complete path and filename.
- filefolder( -- returns the folder ID of the folder that contains the specified file.
- fileidnumber( -- returns the id number for the specified file or folder.
- fileinfo( -- returns information about a file (or folder) on the disk, including the size, creation and modification date and time, type, creator and lock status.
- fileload( -- reads the entire contents of any file on disk.
- fileloadpartial( -- reads a portion of the contents of any file on disk.
- filename( -- extracts the filename from a complete path and filename.
- filepath( -- extracts the path from a combined path and filename.
- filerename -- renames and/or moves a file or folder.
- Files and Folders -- organization of files and folders
- filesave -- saves data directly into a disk file.
- filesize( -- determines the size of any file on disk.
- filesuperdate( -- returns the modification date and time of a file.
- filetime( -- returns the modification time of a file.
- filetypecreator( -- returns the type and creator code of the specified file (if any).
- folder( -- creates a *Folder ID* that unambiguously describes the location of a folder on the hard disk.
- foldercontains( -- checks to see if a folder contains a specified file. See also the pathcontains( function.
- foldercontents( -- returns a list of all of the contents of a folder.
- foldercount( -- returns the total number of files within a folder (including any subfolders).
- folderexists( -- returns true if a folder exists, false if it does not.
- folderpath( -- converts a Folder ID into the HFS path of that folder.
- foldersepchar( -- returns the separator character used between folders.
- foldersize( -- calculates the size of a folder (in bytes).
- fullpath( -- converts a filename or relative path (starting with the : or / symbol) into a full HFS path, including the disk name.
- hfspath( -- converts a UNIX path into an HFS path.
- homepath( -- returns the HFS path of a subfolder of the current users home folder.
- homesubfolder( -- returns the folder id of a subfolder of the current user's home folder.
- hostedfiles( -- returns a list of open databases associated with a specified host (server).
- info("applicationsfolder") -- returns the path to the current user's Applications folder.
- info("applicationsupportfolder") -- returns the path to the current user's Application Support folder (inside the Library folder).
- info("cachefolder") -- returns the path to the current user's Cache folder (in the Library folder).
- info("desktopfolder") -- returns the path to the user's desktop folder.
- info("documentsfolder") -- returns the path to the current user's Documents folder.
- info("downloadsfolder") -- returns the path to the current user's Downloads folder.
- info("dropfiles") -- returns a list of files dragged onto a *Drag Receiver* form object (see Drag and Drop).
- info("foldersepchar") -- returns the separator character used between folders.
- info("libraryfolder") -- returns the path to the current user's Library folder.
- info("moviesfolder") -- returns the path to the current user's Movies folder.
- info("musicfolder") -- returns the path to the current user's Music folder.
- info("panoramafolder") -- returns the location of the folder containing the currently running copy of Panorama.
- info("picturesfolder") -- returns the path to the current user's Pictures folder.
- info("publicfolder") -- returns the path to the current user's Public folder.
- info("tempfolder") -- returns the path to the current user's temporary folder (for files you plan to use only for a short time).
- info("userfolder") -- returns the path to the current user's home folder.
- info("volumes") -- returns a list of all of the currently mounted volumes (disks) on the computer.
- listfiles( -- builds a text array listing the files in a folder.
- listpanoramafiles( -- returns a list of panorama database files in the specified folder.
- listtextfiles( -- returns a list of text files in the specified folder.
- makefolder -- creates a new folder, and if necessary, also creates any enclosing folders needed to create the specified new folder.
- makepackage -- creates a new package, and if necessary, also creates any enclosing folders needed to create the specified new package.
- modifyfileattributes -- modifies one or more attributes of a file (or folder).
- openanything -- opens a document or application.
- openfiledialog -- pauses and displays the standard “open file” dialog.
- openwith -- opens a document with a specific application.
- openwithterminal -- opens an application in a new Terminal.app window (useful for debugging).
- pathcontains( -- checks to see if a folder contains a specified file (or folder).
- pathcontents( -- lists the contents of a folder (specified by a path)
- pathexists( -- checks to see if a path exists.
- pathseparator( -- returns the type of separator character used in a file path (either / or :).
- posixpath( -- converts a path and filename into a POSIX path that can be used as a parameter to a shell command.
- revealinfinder -- reveals a file or folder in the Finder.
- revealmultipleinfinder -- reveals one or more files or folders in the Finder.
- savefiledialog -- pauses a procedure and displays the standard “save file” dialog.
- subfolder( -- returns the folder id of a subfolder of a specified folder
- subpath( -- returns the HFS path of a subfolder of a specified folder.
- tempfolder( -- returns the path to the current user's temporary folder (for files you plan to use only for a short time).
- tildepath( -- converts a path in the current user's folder to tilde (~) notation.
- typecreatorcode( -- returns the 8 character TYPE and CREATOR codes for a filename (if any).
- uncompress -- uncompresses a `.zip`, `.tar.gz` or `.tar.bz2` file into a file or an entire folder.
- unixpath( -- converts an HFS path into a UNIX path.
- unixshellpath( -- converts a path and filename into a POSIX path that can be embedded within the shellscript statement.
- zipcompress -- compresses a file or an entire folder into a zip file (using ditto shell tool).
- zipuncompress -- uncompresses a file or an entire folder from a zip file (using ditto shell tool).

History

Version | Status | Notes
10.0 | New | New in this release.