ask-user-for-string

Function

Package: common-graphics

Arguments: prompt string1 option1 option2 &optional prompt2 string2 title stream

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.

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 (new in release 6.0) 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.

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.

The position of the dialog when displayed is controlled by position-utility-dialog.

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.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.