All Manuals > CAPI User Guide and Reference Manual > 21 CAPI Reference Entries

prompt-for-file Function


Displays a dialog prompting the user for a filename.




prompt-for-file message &key pathname ok-check filter filters if-exists if-does-not-exist file-package-is-directory operation owner pane-args popup-args continuation => filename, successp, filter-name

A string or nil.
A pathname designator or nil.
A function or nil.
A string or nil.
A property list.
One of :ok or :prompt.
One of :ok, :prompt or :error.
A generalized boolean.
One of :open or :save.
An owner window.
Arguments to pass to the pane.
Arguments to pass to the confirmer.
A function or nil.
A pathname or nil.
A boolean.
A string.

The function prompt-for-file prompts the user for a file using a dialog box.

message is shown in the dialog box.

pathname, if non-nil, is a pathname designator providing a default filename for the dialog.

ok-check, if non-nil, should be a function which takes a pathname designator argument and returns a true value if the pathname is valid.

filter specifies the initial filter expression. The default value is "*.*". An example filter expression with multiple filters is "*.LISP;*.LSP".

filter is used on all platforms. However on Motif, if filter contains multiple file types, only the first of these is used.

On Cocoa prompt-for-file supports the selection of application bundles as files if they match the filter. For example, they will match if the filter expression contains *.app or *.*.

filters is a property list of filter names and filter expressions, presenting filters which the user can select in the dialog. If filter is not one of the expressions in filters, an extra filter called "Files" is added for this expression.

On Microsoft Windows the default value of filters is:

("Lisp Source Files" "*.LISP;*.LSP"
 "Lisp Fasls" "*.OFASL"
 "Text Documents" "*.DOC;*.TXT"
 "Image Files" "*.BMP;*.DIB;*.ICO;*.CUR"
 "All Files" "*.*")

The "Lisp Fasls" extension may vary depending on the implementation.

On Cocoa and GTK+ the default value of filters is:

("Lisp Source Files" "*.lisp;*.lsp"
 "Text Documents" "*.txt;*.text"
 "All Files" "*.*")

filters is ignored on Motif.

When if-exists is :ok, an existing file can be returned. Otherwise the user is prompted about whether the file can be overwritten. The default for if-exists is :ok when operation is :open and :prompt when operation is :save.

When if-does-not-exist is :ok, a non-existent file can be chosen. When it is :prompt, the user is prompted if a non-existent file is chosen. When it is :error, the user cannot choose a non-existent file. The default for if-does-not-exist is :prompt if operation is :open and :ok if operation is :save.

operation chooses the style of dialog used, in LispWorks for Windows only. The default value is :open.

owner, if non-nil, specifies an owner window for the dialog. See 10 Dialogs: Prompting for Input for details.

If continuation is non-nil, then it must be a function with a lambda list that accepts three arguments. continuation is called with the values that would normally be returned by prompt-for-file. On Cocoa, passing continuation causes the dialog to be made as a window-modal sheet and prompt-for-file returns immediately, leaving the dialog on the screen. The with-dialog-results macro provides a convenient way to create a continuation function.

On Motif, the prompt itself is created by passing an appropriate pane to popup-confirmer. Arguments can be passed to the make-instance of the pane and the call to popup-confirmer using pane-args and popup-args respectively. Currently, the pane used to create the file prompter is internal to the CAPI. pane-args and popup-args are ignored on Microsoft Windows.

filename is the full pathname of the file selected, or nil if the dialog was cancelled.

successp is a flag which is nil if the dialog was cancelled, and t otherwise.

On Microsoft Windows prompt-for-file returns a third value: filter-name is the name of the filter that was selected in the dialog.

file-package-is-directory controls how to treat file packages on Cocoa. By default it is nil, which means that a file package is treated as file. If file-package-is-directory is non-nil, the a file package is treated as a directory. file-package-is-directory corresponds to the treatsFilePackagesAsDirectories method of NSSavePanel in Cocoa. It has no effect on other platforms.

(capi:prompt-for-file "Enter a filename:")
(capi:prompt-for-file "Enter a filename:"
                      :pathname "/usr/bin/cal")
(capi:prompt-for-file "Enter a filename:"
                      :ok-check 'probe-file)
See also

10 Dialogs: Prompting for Input

CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:27