|Allegro CL version 9.0|
Object described on page has changed in 9.0.
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
nil, indicating whether the directory is a
new one (that is,
nil if there already was a
directory at the specified path, and
there was not).
The arguments are:
: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.
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.
nil, then the text-entry widget will be included when the type argument is
: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
nilmust be passed explicitly to retain the 8.1 behavior. This argument was added in release 9.0.
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.
nilto 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.
nilto 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.
: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.
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 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")))
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.
nil, then it will not be. The default value is true. This argument was added in release 9.0.
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.
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.
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
nilcase will show a plus icon to indicate that it has more children in addition to the one that it's already showing.
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.
nil, then a simple beep indicates when the user may not open a network share.
: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.
nilfor each call.
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.
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
(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
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.
Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 9.0 release; see the Release Notes.
|Allegro CL version 9.0|
Object described on page has changed in 9.0.