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") 

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

Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.

Created 2000.10.5.