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.

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.

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 the filter argument 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 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 the "Prompting for Input" chapter in the LispWorks CAPI User Guide for details.

If continuation is non-nil, then it must be a function with a lambda list that accepts three arguments. The continuation function 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.

Example

(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

popup-confirmer
prompt-for-string
prompt-for-directory