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

if-exists

One of :ok or :prompt .

if-does-not-exist

One of :ok , :prompt or :error .

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.

filters is a plist of filter-names and filter expressions. If the filter argument is not one of the expressions in filters, an extra filter called "Files" is added for this expression. The default filters plist is:

 ("Lisp Source Files" "*.LISP;*.LSP"

   "Lisp Fasls" "*.FSL"

   "Text Documents" "*.DOC;*.TXT"

   "Image Files" "*.BMP;*.DIB;*.ICO;*.CUR"

   "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 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 Windows prompt-for-file returns a third value: filter-name is the name of the filter that was selected in the dialog.

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