ask-user-for-existing-pathname

Arguments: prompt &key initial-directory initial-name stream allowed-types multiple-p change-current-directory-p share-aware-p default-extension (buffer-size (file-selection-buffer-size (configuration *system*)))

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 notes

1. 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.
2. The file ~/.config/gtk-2.0/gtkfilechooser.ini contains some options for how the GTK file selection dialog behaves. In particular, if the end user specifies ShowHidden=true, then dot files and other hidden files and directories will be included in the dialog's list. This option does not appear to be specifiable programmatically. Alternately, the user can type the name of a hidden file even if it's not shown in the list.

See also ask-user-for-new-pathname and ask-user-for-directory. And see file-selection-buffer-size.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 8.2 release; see the Release Notes.
Created 2016.6.21.