Displays a text input pane and prompts the user for a string.
capi
prompt-for-string message &key pane-args popup-args ok-check value-function text initial-value print-function history-symbol history-function continuation => result, okp
message⇩ |
A string. |
pane-args⇩ |
Arguments to pass to the pane. |
popup-args⇩ |
Arguments to pass to the confirmer. |
ok-check⇩ |
A function or nil . |
value-function⇩ |
A function or nil . |
text⇩ |
A string or nil . |
initial-value⇩ |
A string or nil . |
print-function⇩ |
A function or nil . |
history-symbol⇩ |
A symbol. |
history-function⇩ |
A function or nil . |
continuation⇩ |
A function or nil . |
result⇩ |
A string or nil . |
okp⇩ |
A boolean. |
The function prompt-for-string
prompts the user for a string and returns that string in result and a flag okp indicating that the dialog was not cancelled. The initial string can either be supplied directly as a string using text, or by passing initial-value and a print-function for that value. print-function defaults to princ-to-string. The value returned can be converted into a different value by passing a value-function, which by default is the identity function. This value-function gets passed the text that was entered into the pane, and should return both the value to return and a flag that should be non-nil if the value that was entered is not acceptable. If an ok-check is passed, then it should return non-nil if the value about to be returned is acceptable.
prompt-for-string
creates an instance of text-input-pane or text-input-choice depending on the value of history-function. Arguments can be passed to the make-instance of this pane using pane-args. prompt-for-string
then passes this pane to popup-confirmer. Arguments can be passed to the call to popup-confirmer using popup-args.
message supplies a title for the dialog.
history-symbol, if non-nil, provides a symbol whose value is used to store an input history, when history-function is not supplied. The default value of history-symbol is nil
.
history-function, if supplied, should be a function designator for a function with signature:
history-function &optional push-value
history-function is called with no argument to obtain the history which is used as the items of the text-input-choice, and with the latest input to update the history.
The default value of history-function is nil
. In this case, if history-symbol is non-nil then a history function is constructed which stores its history in the value of that symbol.
If continuation is non-nil, then it must be a function with a lambda list that accepts two arguments. continuation is called with the values that would normally be returned by prompt-for-string
. On Cocoa, passing continuation causes the dialog to be made as a window-modal sheet and prompt-for-string
returns immediately, leaving the dialog on the screen. The with-dialog-results macro provides a convenient way to create a continuation function.
(capi:prompt-for-string "Enter a string:")
(capi:prompt-for-string "Enter an integer:" :initial-value 10 :value-function #'(lambda (x) (let ((integer (ignore-errors (read-from-string x)))) (values integer (not (integerp integer)) ))))
popup-confirmer
text-input-pane
10 Dialogs: Prompting for Input
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:32:42