ask-user-for-existing-pathname

Function

Package: common-graphics

Arguments: prompt &key initial-directory initial-name stream allowed-types multiple-p change-current-directory-p share-aware-p default-extension

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 " ".
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 is 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 (cg::selected-window-or-screen).
allowed-types: a list of file extensions to limit the types of files to select from. The default value shows the format of the value -- a list of conses of (1) a string describing the files (the description appears in the list box) and (2) a string of the form "*.foo" identifying the extension. The first selection in the list will be the types of files that first appear, since only files with the currently-selected extension are displayed. The default is:'(("Lisp files" . "*.cl") ("All files" . "*.*"))
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.
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. (The default buffer is sufficient to hold 12 pathnames of maximum length.) The size of the buffer can be increased. See file-selection-buffer-size.
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. :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.
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.

This function uses the standard Common Dialog supplied by Windows for file selection. Internal Allegro CL file selection dialogs use this function. See also ask-user-for-new-pathname and ask-user-for-directory. And see 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.

Created 2000.10.5.