| Allegro CL version 6.2 This page is new in 6.2 |
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
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:
: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.
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) 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.
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-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page is new in the 6.2 release.
Created 2002.2.26.
| Allegro CL version 6.2 This page is new in 6.2 |