ask-user-for-new-or-existing-directory

Arguments: &key (owner (screen *system*)) (type :either) title prompt position width height (scope :all) (create-if-new t) initial-directory initial-subdirectory show-initial-directory-siblings look-ahead (prompt-for-password-if-needed t) (focus-on-new-subdirectory (eq type :new)) close-subtrees-on-close show-initial-directory-children search-network-globally

This function displays a modal dialog that allows the user either to select an existing directory or to specify a new subdirectory of an existing directory. Directories on local disk drives and on network shares are displayed in an outline control; the user selects one of these directories, and optionally (if a new directory is being specified) types the name for a new subdirectory of the selected directory into a text control below the outline.

Two values are returned: (1) A pathname for the directory that was specified by the user (or nil if the user cancels the dialog), and (2) either t or nil, indicating whether the directory is a new one (that is, nil if there already was a directory at the specified path, and t if there was not).

The arguments are:

• owner: either the screen or a window. Defaults to the stream returned by selected-window-or-screen. If a window, then the modal dialog will be owned by this window (and therefore will stay in front of it) and will be modal with respect to this window (meaning that interactive gestures are disabled in all other windows of the window hierarchy that has this window as its root).
• type: a keyword indicating whether a new or existing directory (or either) is being requested. The value must be one of the following three symbols:
  • :either (the default), meaning the user may specify either a new or an existing directory.
  • :new, meaning only a new directory may be specified.
  • :existing, meaning only an existing directory may be specified.

  For either :new or :either, a text control will appear below the outline for entering a new subdirectory name. For :existing, this control will be hidden.

• title: a string to display in the title-bar of the dialog. The default string depends on the type argument.
• prompt: a string to display in the body of the dialog to instruct the user what to do. This string can be fairly long, though the space for it is not adjusted to handle any length. The default string depends on the type argument.
• position: either a position object (see make-position) indicating the screen position of the upper-left exterior corner of the dialog, or nil (the default) to use a default position. The default position is determined by center-modal-children and center-all-modal-dialogs-on-screen, as with the other built-in utility dialogs.
• width: either a positive integer indicating the exterior pixel width of the dialog, or nil to use the width that was used most recently with the specified owner, including interactive resizing that the user may have done. Initially a moderate default width is used.
• height: either a positive integer indicating the exterior pixel height of the dialog, or nil to use the height that was used most recently with the specified owner, including interactive resizing that the user may have done. Initially a moderate default height is used.
• scope: a keyword indicating whether local disks or network shares (or both) are to be included in the outline. The value must one of the following symbols:
  • :all (the default), meaning both local disks and network shares are included.
  • :local, meaning only local disks are included.
  • :remote, meaning only network shares are included.
• create-if-new: this argument is used only if the user specifies a new subdirectory. In that case, if create-if-new is true (the default), then the specified subdirectory is created automatically before its pathname is returned, and otherwise it is not. In any case, the second returned value will be true if and only if a new subdirectory was specified.
• initial-directory: either nil (the default) or a pathname or namestring indicating the directory to which the outline will initially be opened. The specified directory (if any) will also be initially selected. This option is useful for suggesting the area of the directory hierarchy in which the user may want to select a directory, and for making it easier for the user to browse to the probable desired directory. When this argument is nil, the outline is always opened to show only the local disks and/or the network shares, and the topmost outline-item will initially be selected.

  If this argument is a namestring rather than a pathname, it does not matter whether the namestring contains a final slash. Also, if the specified directory does not exist, the outline will still initially be opened to any upper levels of the specified directory that do exist. It is also OK to pass in the full pathname of a file that is (or could be) in the desired directory; the pathname name and type will be ignored.

• initial-subdirectory: either nil (the default) or a string to display initially in the text control where the user may enter a new subdirectory name. This argument is ignored if the type argument is :existing (in which case the text control for a new subdirectory will not appear at all). When nil, this control will be empty initially.
• show-initial-directory-siblings: this argument is used only when an initial-directory argument is specified. If nil (the default), then each level of the outline that is opened in order to display the initial-directory will show only the single child item that leads to the specified initial-directory. If true, then all siblings of each opened item will also be shown initially. The advantages of each choice are that the first shows less clutter, while the second provides more initial context. The user can navigate to any directory in either case, and a "partially open" outline-item in the nil case will show a plus icon to indicate that it has more children in addition to the one that it's already showing.
• look-ahead: if nil (the default), then whenever an outline-item is opened to show its subitems, the icons for each subitem will always initially indicate that the subitem may be opened to show further subitems, even if in fact there are no further subdirectories for some or all of the newly-displayed directories. If true, then whenever new subitems are shown, the dialog will "look ahead" to see if each of the newly displayed subdirectories has any further subdirectories, and will display appropriate icons for each item to inform the user whether there will be anything further to see if each displayed item is opened. The advantages of each choice are that the first is faster, while the second provides additional useful information to the user. This option may be particularly slow for network shares.
• prompt-for-password-if-needed: if true (the default), then if the user attempts to open a network share but the user's default username and password are not correct for that share, than a dialog is shown to allow the user to enter a different username and password. If nil, then a simple beep indicates when the user may not open a network share.
• focus-on-new-subdirectory: if this argument is true and a valid initial-directory argument was specified, then the keyboard focus will be initially in the text control for typing in a new subdirectory name. Otherwise the keyboard focus will be initially in the outline control of the dialog. The default for this argument is true if the type argument is :new, and is otherwise nil. This option may be useful if the application is asking the user for a new subdirectory when the probable parent directory is known (and passed as the initial-directory argument); in this case the user can typically type in the new subdirectory name immediately and return.
• close-subtrees-on-close: the close-subtrees-on-close property of the outline control will be set to the value of this argument for this call. The default is nil for each call.
• show-initial-directory-children: this argument is used only when an initial-directory argument is specified. If nil (the default), then no children of the outline-item for the initial directory are visible when the dialog appears. If true, then that outline-item is opened to reveal any immediate subdirectories of the initial directory.
• search-network-globally: to find the networked machines to list, a true argument will search the network "globally", whereas nil (the default) will search only "in the current context". The default is nil. This argument is passed (as the value of the global keyword argument) to win:network-machines; see that function for more information. This argument applies to Microsoft Windows only.

Other notes

The dialog displays a file folder for each outline-item that represents an actual directory that may be returned. This excludes the two root items for all "Local Disks" and "Network Machines" plus each network share (because only the descendent items of each share represent actual directories). These non-directory items will display a simple triangle icon instead of a file folder.

The OK button on the dialog will be disabled if no directory that may be returned is currently specified. This includes whenever a non-directory outline-item is selected. And if the type argument is :new, this also includes when the text control for the new subdirectory name is empty. At these times, the user may not exit the dialog by pressing the OK button or by pressing ENTER, but they may always exit by canceling the dialog (as usual, by pressing the ESCAPE key or the Cancel button or clicking the small close button in the frame).

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

Copyright (c) 1998-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. The object described on this page has been modified in the 8.1 release; see the Release Notes.
Created 2007.4.30.