ask-user-for-string

Arguments: prompt string1 option1 option2 &optional prompt2 string2 title stream cursor-at-end

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.

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.

Example

(ask-user-for-string
 "Enter the correct answer and win a beautiful lounge suite."
 "default answer" :~OK :~cancel nil nil "Answer Box"
 (selected-window (screen *system*)))

A typical usage of the returned string or strings would be to pass them to string-search or string-replace.

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.
Created 2019.8.20.