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

Function

Package: cg

ToC

DocOverview

CGDoc

RelNotes

FAQ

Index

PermutedIndex

Allegro CL version 9.0
Object described on page has changed in 9.0.
8.2 version

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

Arguments: &key (owner (selected-window-or-screen)) (type :either) (always-show-text-box t) title prompt position width height (scope :all) (special-folders (quote ((:personal "Home")))) (create-if-new t) initial-directory initial-subdirectory show-initial-directory-siblings (show-local-file-systems t) 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 to specify a new or existing directory (also known as a folder). The directory can be specified either by selecting it in the outline widget, or entering an absolute path namestring in the text-entry widget, or by entering a relative path namestring in the text-entry widget that is relative to the directory that is selected in the outline. It does not matter whether the user types a final slash character after a directory name in the text-entry widget. Help strings at the bottom of the dialog guide the user in specifying a complete path.

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 always appear below the outline for entering a new subdirectory name. For :existing, this control will appear only if always-show-text-box is true.
always-show-text-box: if true, then the text-entry widget for specifying all or part of the path textually will be always be included on the dialog; if nil, then the text-entry widget will be included when the type argument is :new or :either, but not when it is :existing. The default value is true. Compatibility note: Through version 8.1, the behavior was always as if this new argument were nil, and so nil must be passed explicitly to retain the 8.1 behavior. This argument was added in release 9.0.
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. The height of the prompt area in the dialog will be adjusted automatically so that the prompt string fits.
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.
special-folders: a list of special directories to include as top-level items in the outline widget, alongside the usual top-level items for local and remote file systems. The value should be a list where each member is a list of at least two things: (1) one of the keyword values that can be passed to the function win:special-windows-directory, (2) a string to display for the folder in the dialog, and (3) an optional third boolean value that indicates whether the outline item for the folder should initially be open to reveal its child folders. This argument was added in release 9.0.
The default value is ((:personal #+mswindows "My Documents" #-mswindows "Home")), which will include a "My Documents" item on Windows and the home directory item on Linux. On Linux, :personal is currently the only indicator that will be used. On Windows, the indicator :personal should be used for the "My Documents" folder, because the :my-documents argument to win:special-windows-directory does not seem to work.

Compatibility note: Through version 8.1, the behavior was always as if this new argument were nil, and so nil must be passed explicitly to retain the 8.1 behavior.

Here is an example value that includes some additional possibly useful values on the Windows platform:
```
  :special-folders '((:personal #+mswindows "My Documents"
                                #-mswindows "Home"
                                t) ;; show child folders initially
                     (:recent "My Recent Documents")
                     (:app-data "Application Data")
                     (:desktop "Desktop")))
```
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. Multiple directories will be created automatically if the specified path ends with a chain a multiple subdirectories that do not yet exist.
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.
show-local-file-systems: if true, then the top-level item for local disks or file systems will initially be open to reveal the individual file systems; if nil, then it will not be. The default value is true. This argument was added in release 9.0.
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.
search-network-globally: This argument is used only on the Windows platform. 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. On Windows, 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. If the type argument is :existing (and always-show-text-box is true), this also includes when the text-entry widget contains text that does not name an existing directory. And if the type argument is :new, this also includes when the text control for the new subdirectory name is empty or contains an invalid directory name. 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).

On Windows, if the directory-selecting dialog that is provided by Microsoft is desired for its native look and feel, then the alternate function ask-user-for-directory will display that dialog. But that function has fewer options than this one, and on GTK it simply calls this function.