| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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 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:
: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 be hidden.
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.
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.
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.
: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.
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
(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 nil
case 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.
nil
for 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. 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.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |