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). This function is intended to display the underlying windowing system's directory-selecting dialog with its native look-and-feel, and on the Windows platform it does just that. On GTK it simply calls ask-user-for-new-or-existing-directory, which is a platform-independent function written in Common Graphics. It is probably better to call the other function directly on GTK, to use its additional arguments, or on all platforms if the native behavior is not needed on Windows.

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: 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). This argument was added in release 9.0.
• 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. This argument was added in release 9.0.

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-2012, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 9.0. The object described on this page has been modified in the 9.0 release; see the Release Notes.
Created 2010.1.21.