Arguments: prompt &key initial-name initial-directory stream allowed-types multiple-p change-current-directory-p warn-if-exists-p share-aware-p default-extension
This function provides the service of prompting for one or more new pathnames. It displays a file choice dialog which can be used to specify the directory component. Typing the new name into the File field specifies the filename.
If multiple-p is
(the default), returns the pathname of the selected file, or
nil if none was chosen. If
multiple-p is true, returns a list of pathnames
of the 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. "Select new
filename for file").
The arguments are:
nilor "" (the empty string), the initial name will appear as the currently allowed type, such as "*.cl". The default is "".
*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.
nil, the current directory is left unchanged. Default is
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
It is not clear how useful this option is but we include it because the operating system allows it. Users have to type the filenames into a dialog. Multiple filenames must be enclosed in double quotes and be space delimited ("foo.cl" "c:\tmp\bar.fasl").
Note: there is a buffer that holds the chosen pathnames. An error will be signaled if the buffer is too small to hold the multiple chosen pathnames. (Since the user must type in the filenames, we suspect this will not be a problem for this function. The default buffer is sufficient to hold 12 pathnames of maximum length, that is about 3000 characters.) The size of the buffer can be increased. See file-selection-buffer-size.
nil(the default), the file cannot be selected. If true, the file can be selected.
nil, returns the existing filename string without complaint. Default is t.
nilor 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
nilrather than the null string, just as if default-extension were
This function uses the standard Common Dialog supplied by Windows for file selection. Internal Allegro CL file selection dialogs use this function. See ask-user-for-existing-pathname and ask-user-for-directory. See also file-selection-buffer-size.
Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.
The documentation is described in introduction.htm and the index is in index.htm.
Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.