pop-up-string-dialog

Arguments: window-or-screen title prompt icon string button1 button2 &key cursor-at-end

Displays a modal dialog that prompts for one modifiable string. Returns three values. The first is the modified string, the second is nil and the third is the button number.

window-or-screen is the window with respect to which the dialog will be modal (no windows are disabled if the value is the screen). If nil, the stream returned by selected-window-or-screen will be used. title is a string to display in the title-bar of the dialog. prompt is a string to display in the body of the dialog, typically describing what the user should enter in the editable-text widget just below it.

icon is the handle of an icon to display in the dialog. Typically this is the value of one of the symbols information-icon, question-icon, warning-icon, or error-icon, but may alternately be an icon handle returned by extract-icon-from-file.

string is the string to initially display in the editable-text widget where the user enters a string. The whole string will initially be selected so that the user can easily replace it by simply typing.

button1 is a string to display on the leftmost button at the bottom of the dialog. If the user presses this button or presses the Enter key, then the third return value will be the number 1. A tilde character (~) may be included in the string to underline the next character, so that the user may press the button by holding down the Alt key and pressing the key for that character.

button2 is a string to display on the rightmost button at the bottom of the dialog. If the user presses this button or presses the Escape key, then the third return value will be the number 2. A tilde character (~) may be included in the string as with button1.

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.

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

See also pop-up-strings-dialog and ask-user-for-string.

Example

(pop-up-string-dialog (or (selected-window (screen *system*))
                          (screen *system*))
                      "Answer Box"
                      "Give me one good reason why I should go away."
                      question-icon "initial answer"
                      "~OK" "~Cancel")

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

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.