prompt-for-file

prompt-for-file Function

Summary

Displays a dialog prompting the user for a filename.

Package

capi

Signature

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

Arguments

`message`⇩	A string or `nil`.
`pathname`⇩	A pathname designator or `nil`.
`ok-check`⇩	A function or `nil`.
`filter`⇩	A string or `nil`.
`filters`⇩	A property list.
`if-exists`⇩	One of `:ok` or `:prompt`.
`if-does-not-exist`⇩	One of `:ok`, `:prompt` or `:error`.
`file-package-is-directory`⇩
	A generalized boolean.
`operation`⇩	One of `:open` or `:save`.
`owner`⇩	An owner window.
`pane-args`⇩	Arguments to pass to the pane.
`popup-args`⇩	Arguments to pass to the confirmer.
`continuation`⇩	A function or `nil`.

Values

`filename`⇩	A pathname or `nil`.
`successp`⇩	A boolean.
`filter-name`⇩	A string.

Description

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.

Examples

(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)