This function provides the service of prompting for one
or more existing pathnames.

If multiple-p is nil
(the default), returns the pathname of the selected file, or nil if none was chosen. If
multiple-p is true, returns a list of selected
files (even if only one is selected) or nil
if none is selected. prompt should be a string
explaining what is to be done with the selected file (e.g. "Choose
file to open").

The arguments are:

initial-name: the filename shown initially
for selection. It can be any relative filename with respect to the
initial directory (the value of
:host). If nil or " " (the empty string), the
initial name will appear as the currently allowed type, such as
"*.cl". The default is " ". A non-nil
value may be either a namestring or a pathname object.

initial-directory: the initial directory
from which to select the file or from which to change directory. If
this value is unsupplied, the default depends on the value of
the context-sensitive-default-path configuration
property, but in most cases the most recent value is used. The value
of *default-pathname-defaults* is used initially.
In earlier releases, this argument was called
host. host is
still accepted in place of initial-directory. Do
not specify both.

stream: specifies the parent window for
the dialog that pops up. Defaults to the stream returned
by selected-window-or-screen.

allowed-types: specifies what types of
files appear in the dialog's list of existing files. The value is a
list where each member specifies one of the choices in the drop-down
list of file type choices. Each list member is a cons of (1) the
string to appear in the list of file type choices and (2) a string of
the form "*.foo;*.bar;..." that indicates the file type(s) that it
represents. The first choice is the one that is initially in effect.
For example, the value (("Text Files" . "*.txt")("Pixmap
Files" . "*.bmp;*.jpg;*.jpeg")) would initially display all
files whose type is "txt", and also allow the user to select the
second choice to instead display all files of the types "bmp", "jpg",
and "jpeg". (Users can always type in some other file if desired.)
The default value of this argument is (("All files"
. "*.*")) to display all files. (In releases prior to 7.0,
the default was the value of the variable
cg:*edit-allowed-types*. That variable is no
longer supported and the default is now built in.)

multiple-p: a Boolean which, if true,
allows the user to select more than one file; the list of selected
pathname strings is returned. If nil, only
one file may be selected and the returned value is a pathname string
or nil, if the user cancels the dialog. The
default is
nil.

change-current-directory-p: a Boolean
which, if true, changes the Microsoft Windows current directory to be
the final selected directory when you exit or cancel the
dialog. If nil, the current directory is left
unchanged. Default is nil. This argument has
no effect on GTK. See GTK note below.

share-aware-p: a Boolean which controls
whether a file that is currently opened by another application can be
selected. If nil (the default), the file
cannot be selected. If true, the file can be selected. This argument
has no effect on GTK. See GTK note below.

default-extension: the value should be
either
nil or a string that names a default pathname
extension. This value is used only if the end user has selected an
allowed type such as "All Files (*.*)" on the file selection dialog
that does not specify a particular type, and they type in a filename
with no extension. In that case, the pathname returned by this
function will have default-extension as its pathname-type. An
exception is that if default-extension is the null string, it will
result in a pathname whose type is nil rather
than the null string, just as if default-extension were nil.

buffer-size: an integer specifying the
size of the buffer that's used to return the seleced pathnames. This
is used only on the Windows platform. The default value is
(file-selection-buffer-size (configuration
*system*)) (see file-selection-buffer-size, configuration, and *system*). The default should always be
sufficient when asking for new pathnames, where the filenames must be
typed in.

This function uses the standard Common Dialog supplied by the
platform's underlying windowing system for file selection. Internal
Allegro CL file selection dialogs use this function.

GTK note

The arguments change-current-directory-p and
share-aware-p have no effect on GTK because the
underlying native GTK file selection dialog does not support such
options.