ask-user-for-directory

Arguments: &key prompt stream root dont-go-below-domain browse-include-files

Displays a dialog showing directories. 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 currently selected top-level window if any, and otherwise to the screen. The screen is the value returned by (screen *system*). See screen and *system*.
• root: 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. Note that if a namestring is passed, backslashes must be used rather than forward slashes. 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.

The similar function ask-user-for-new-or-existing-directory invokes a dialog that has more options than this function does. But this function invokes the directory dialog that is provided by the operating system and therefore may be more familiar to users of that operating system.

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

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page has had minimal revisions compared to the 6.1 page.
Created 2002.2.26.