ask-user-for-string

Displays a modal dialog prompting for one or two strings. Prompts for
one string if the prompt2 and
string2 optional arguments are not
supplied or are supplied as nil. Prompts for
two strings if prompt2
and string2 are supplied and are true. The string
arguments are copied so string1 and (if
supplied)
string2 will be unchanged after this function
returns.

The option1
and option2 arguments provide titles for
buttons that appear on the dialog. Clicking a button causes the dialog
to exit and the function to return. Each of these values may be either
a string or a symbol, and a tilde character (~) in the string or
symbol name indicates that the next character should be an underlined
access character for the button.

This function returns four values. The first two are the strings as
modified by the user except that the second value will be nil when the optional prompt2
and string2 arguments are not passed or are
nil. As the third value, ask-user-for-string returns the
string which is the value of the selected button argument (that is,
option1 or option2 depending on which button the user clicks).

The fourth value indicates whether the user
accepted or canceled the dialog. The value is t if the user either
clicked the option1 button or pressed the ENTER key, and nil if the
user either clicked the option2 button or pressed the ESCAPE key to
cancel the dialog. In a sense, this repeats the information in the
third returned value, since a string comparison such as

(when (string= third-value "~OK")
<process-the-string>)

The fourth value allows a simpler test such as:

(when fourth-value <process-the-string>)

This also removes the need to hardcode the button label twice or to
let bind it.

The title argument (if supplied) should be
a string and provides the title of the dialog. The
prompt, string1,
option1,
and option2 arguments should also be
strings.

The stream argument indicates the owner
window for the dialog. It defaults to the stream returned
by selected-window-or-screen.

If cursor-at-end is true, then the text
cursor will initially be at the end of the initial string, to
facilitate extending the suggested string.
If nil, then the entire string will initially
be selected, to facilitate replacing the string. This argument is
new in version 9.0.

Note several things:

The names of the buttons (provided by the option1 and option2
arguments) do not have effect in themselves. Even though the button
named "Cancel" is clicked, nothing is canceled. The string "Cancel" is
returned as the third value and the program must interpret the
returned value to act appropriately

Pressing ENTER has the same effect as clicking on the button
associated with option1. Pressing ESC has the same effect as clicking
on the button associated with option2. Pressing the space bar is not
equivalent to pressing ENTER (as it often is with dialogs) because the
space is interpreted as a character in one of the strings.

Even if a string is unmodified by the user, a copy rather than the
original argument is returned.

See also pop-up-string-dialog and pop-up-strings-dialog. Their return
values include the number of the button pressed and thus it may be
easier to know what the user did using those functions rather than
this one.

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