ask-user-for-directory

Arguments: &key (prompt "Select a folder.") (stream (selected-window-or-screen)) root dont-go-below-domain browse-include-files include-edit-box new-dialog-style

Displays a dialog where the user can select an existing directory (also known as a folder).

The newer function ask-user-for-new-or-existing-directory has more options than this one and works the same on all platforms, and so may be a better choice in most cases. On the other hand, on the Windows platform this function will show the dialog that is provided by Microsoft, with its native look and feel. On GTK, this function simply calls ask-user-for-new-or-existing-directory.

The chosen directory is returned as a pathname object. Note that the pathname of the directory is stored in a buffer and if the buffer is too small, an error will be signaled. The buffer size is determined by file-selection-buffer-size. The default size is large enough to hold at least 12 pathnames so this should not be a problem for this function, which returns one pathname only.

Note too that it is not possible to specify the initially-selected directory or which subdirectories are initially open in the hierarchy that is presented.

The arguments are:

• prompt: an informational string explaining to the end user what they need to choose. The string appears in the body of the dialog. If unspecified or nil, the prompt "Select a folder." is used.
• stream: the window or screen that will serve as the owner of the dialog while it is present. The dialog will be modal with respect to this owner window and all of its child windows and owned windows (that is, the user will not be able to access these windows while the dialog is present). Defaults to the stream returned by selected-window-or-screen.
• root: This argument is no longer working for undetermined reasons. We recommend using the more versatile function ask-user-for-new-or-existing-directory instead, specifying the initial-directory argument, which is the equivalent of root for that function. When this argument is working, the value should be a pathname, path namestring, or nil, indicating the directory that will appear as the root node in the dialog's directory tree. Only this directory and its subdirectory descendents will be presented for selection by the end user. nil means to include all available file systems. The final slash is optional when either a pathname or namestring is passed.
• dont-go-below-domain: if true, then network folders below the domain level, (as defined by MSDN), will be excluded from the tree of choices (though network folders above the actual directories may still be viewed). If nil, directories on both the local computer and networked computers are accessible. .
• browse-include-files: if true, the dialog will display regular files in addition to directories, and either a directory or other file may be chosen by the end user and returned.
• include-edit-box: if true, then a text-entry widget will be included on the dialog. If the absolute (complete) path namestring of an existing folder (with or without the final backslash) is typed or pasted here, it will be used instead of the folder that's selected in the outline widget (if any).
• new-dialog-style: if true, then Microsoft's "newer style" is used, where the dialog is resizable, is centered on the screen, and has a "Make new folder" button for creating a new directory. The new style also provides a right-click menu in the outline widget for doing things such as renaming a folder. These features used together allow the user to create and then rename a new folder, though more awkwardly than with ask-user-for-new-or-existing-directory.

See also ask-user-for-existing-pathname and ask-user-for-new-pathname.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.