choosefiledialog
choosefiledialog
PATH
,
OPTION
,
VALUE

The choosefiledialog statement displays a modal dialog allowing selection of files or folders.

Parameters

This statement has three parameters:

path – is a field or variable that will contain a carriage return delimited array of files (and/or folders) selected by the user. Files are returned as UNIX paths. 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 dialog’s 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 choosefiledialog statement pauses a procedure and displays the standard system dialog for choosing files and/or folders. The user can then select a file or folder from the disk. 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 select any kind of file.

    local fileChoice
    choosefileDialog fileChoice

This example allows only PDF files to be selected:

    local fileChoice
    choosefileDialog fileChoice,".pdf"

Note: The case does not matter, either `".pdf"` or `".PDF"` can be used.

This example allows several different kinds of image files to be selected (note that the file types are NOT separated by commas):

    local fileChoice
    choosefileDialog fileChoice,".jpg.gif.png"

This example also allows image files to be selected, but starts with the user’s Pictures directory showing.

    local fileChoice
    choosefileDialog fileChoice,".jpg.gif.png","~/Pictures"

This example allows only Panorama database files to be selected:

    local fileChoice
    choosefileDialog fileChoice,".pandb"

#### Handling the Cancel button

If you want to perform a different action if the Cancel button is pressed, there are two techniques that can be used to check for this button. If the Cancel button is pressed, the variable containing the path and file will be empty:

    local fileChoice
    choosefileDialog fileChoice
    if fileChoice=""
        return
    endif
    ...
    ... do more stuff
    ...

The other option is to use the info(“dialogtrigger”) function:

    local fileChoice
    choosefileDialog fileChoice
    if info("dialogtrigger")="Cancel"
        return
    endif
    ...
    ... do more stuff
    ...

These examples simply stop if the Cancel button is pressed, but you could add additional code to display a message, load a default file, or any other action you want.

#### Dialog Options

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

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

Each of the available options is described below.

##### FileTypes

This option specifies one or more types of files that can be selected with the dialog. Any file that is not one of the types in the list will be dim, and cannot be selected. In this example, only filenames ending with .html or .css can be selected.

    choosefiledialog fileChoice,"FileTypes",".html.css"

If the FileTypes option is ommitted, any kind of file can be selected.

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 selected. 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.

    choosefiledialog fileChoice,"FileTypes","JPEGGIFfPNGf"

Note: Current versions of Panorama do not actually check the files OS 9 type and creator code (most files in OS X do not have these codes any more). Instead Panorama uses the file’s extension to synthesize the type and creator codes. The current version of Panorama requires that all files it works with have an extension.

Tip: You can leave off the option name for the filetype parameter, like this:

    choosefiledialog fileChoice,".html.css.xml.json"
    choosefiledialog fileChoice,"JPEGGIFfPNGf"

The choosefiledialog statement automatically recognizes that this is a filetype list, either because it starts with a period, or because it is a multiple of 4 characters.

##### 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
    choosefiledialog fileChoice,"InitialPath","~/Pictures"

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

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

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

Tip: As long as your path contains one or more / or : characters, you can leave off the option name and just include the path, like this:

    choosefiledialog fileChoice,"~/Pictures"

The choosefiledialog statement automatically recognizes that this is a path because of the / or : characters. Tip within Tip: Functions like folder(, dbfolder(, and other folder related functions return a path with one or more / characters in it, so they will work also, like this:

    choosefiledialog fileChoice,dbfolder()

##### Multiple

This option enables multiple files to be selected by the dialog. If the user chooses multiple files, they will be returned as a carriage return delimited array (in other words, each filename will be on a separate line).

    choosefiledialog fileChoice,"filetypes",".jpg.gif.png","Multiple",true()

If this option is omitted, only a single file may be selected.

##### Folders

This option can be used to enable the selection of folders (normally folders cannot be selected). This example allows the user to select folders or image files.

    choosefiledialog fileChoice,"filetypes",".jpg.png.tif.gif","folders",true()

Boolean values can also be specified textually, i.e. `"true"` in addition to `true()` (see True/False Formulas).

##### Files

This option can be used to disable the selection of files. This example displays a dialog that allows the user to select a folder, but does not allow the selection of any file.

    choosefiledialog fileChoice,"folders",true(),"files",false()

If this parameter is omitted, files can be selected.

##### Title

This option specifies the title of the choose file dialog. The title appears at the very top of the dialog, in the drag bar. (Note: When running recent versions of macOS there is no drag bar, so the title is not displayed.)

    choosefiledialog fileChoice,"FileTypes",".html","Title","Choose Web Page"

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

##### Button

This option specifies the name of the Open 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.

    choosefiledialog fileChoice,"FileTypes",".html","Button","Choose Web Page"

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

##### ShowHidden

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

    choosefiledialog 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 select a file inside a package (only very advanced users, like developers, would ever need this option).

    choosefiledialog 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.
- 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.
- savedialog -- displays a modal dialog that allows a user to specify the name and location of a new file.
- 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.