1 CAPI Reference Entries

prompt-for-file

Function

Summary
: The functionprompt-for-file pops up a dialog prompting the user for a file name.
Syntax

prompt-for-file message &key pathname ok-check pane-args popup-args filter filters if-exists if-does-not-exist operation owner

Description
: The functionprompt-for-file prompts the user for a file using a dialog box, optionally defaulting to pathname. Like all the prompters,prompt-for-file returns two values: the file and a flag indicating success. The success flag will returnnil if the dialog was cancelled, andt otherwise. An ok-check function can be specified, which should return non-nil if a given pathname is valid.
: filter specifies the initial filter expression (defaults to "*.*"). 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" "*.*")

: if-exists is one of:ok or:prompt. When set to:ok, the an existing file can be returned. Otherwise the user is prompted about whether the file can be overwritten. The default is:ok when operation is:open and:prompt when operation is :save.
: if-does-not-exist is one of:ok,:prompt or:error. When set to:ok, a nonexistent file can be chosen. When set to:prompt, the user is prompted if a non existent file is chosen. When set to:error, the user cannot choose a non existent file. The default is:prompt if operation is:open and:ok if operation is:save. operation is one of:open or:save. This chooses the style of dialog used. The default is:open. owner is a capi top-level interface which becomes the owner of the dialog. In a CAPI callback, this defaults to current interface. Otherwise an interface is chosen for the current thread.
: Finally, as with all of the prompting functions, the prompt itself is created by passing an appropriate pane topopup-confirmer. Arguments can be passed to themake-instance of the pane and the call topopup-confirmer using pane-args and popup-args respectively. Currently, the pane used to create the file prompter is internal to the CAPI.
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