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
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
.
One of
:open
or
:save
.
An owner window.
A function or
nil
.
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" "*.*")
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.
(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)