Summary: Builds a dialog for user interaction based on calls to
accept
within
body
. The user can select the values and change them, or use defaults if they are supplied. The dialog will also contain some sort of "end" and "abort" choices. If "end" is selected, then
accepting-values
returns whatever values the body returns. If "abort" is selected,
accepting-values
will invoke the
abort
restart.

stream
is an interactive stream that
accepting-values
will use to build up the dialog. The
stream
argument is not evaluated, and must be a symbol that is bound to a stream. If
stream
is
t
(the default),
*query-io*
is used.

body
is the body of the dialog, which contains calls to
accept
that will be intercepted by
accepting-values
and used to build up the dialog.
body
may have zero or more declarations as its first forms.

An
accepting-values
dialog is a looping structure. First,
body
is evaluated in order to collect the output. During the evaluation, all calls to
accept
call the
accept-present-default
presentation methods instead of calling the
accept
presentation methods. The output is displayed with incremental redisplay.
accepting-values
awaits a user gesture, such as clicking on one of the fields of the dialog. When that happens,
accepting-values
reads a new value for that field using
accept
and replaces the old value with the new value. The loop is started again, until the user either exits or aborts from the dialog.

Because of this looping structure,
accepting-values
uses the
query identifier
to uniquely identify each call to
accept
in the body of the dialog. The query identifier is computed on each loop through the dialog, and should therefore be free of side-effects. Query identifiers are compared using
equal
. Inside of
accepting-values
, the
:query-identifier
argument should be supplied to each call to
accept
. If it is not explicitly supplied, the prompt for that call to
accept
is used as the query identifier. Thus, if
:query-identifier
is not supplied, programmers must ensure that all of the prompts are different. If there is more than one call to
accept
with the same query identifier, the behavior of
accepting-values
is unspecified.

While inside
accepting-values
, calls to
accept
return a third value, the boolean
changed-p
that indicates whether the object is the result of new input by the user, or is just the previously supplied default. The third value will be
t
in the former case,
nil
in the latter.

When
own-window
is non-
nil
, the dialog will appear in its own "popped-up" window. In this case the initial value of
stream
is a window with which the dialog is associated. (This is similar to the
associated-window
argument to
menu-choose
.) Within the
body
, the value of
stream
will be the "popped-up" window.
own-window
is either
t
or a list of alternating keyword options and values. The accepted options are
:right-margin
and
:bottom-margin
; their values control the amount of extra space to the right of and below the dialog (useful if the user's responses to the dialog take up more space than the initially displayed defaults). The allowed values for
:right-margin
are the same as for the
:x-spacing
option to
formatting-table
; the allowed values for
:bottom-margin
are the same as for the
:y-spacing
option.

exit-boxes
specifies what the exit boxes should look like. The default behavior is though the following were supplied:

'((:exit "Control-] uses these values")

(:abort "Control-z aborts"))

initially-select-query-identifier
specifies that a particular field in the dialog should be pre-selected when the user interaction begins. The field to be selected is tagged by the
:query-identifier
option to
accept
; use this tag as the value for the
:initially-select-query-identifier
keyword, as in this example:

(defun avv ()

(let (a b c)

(accepting-values

(*query-io* :initially-select-query-identifier 'the-tag)

(setq a (accept 'pathname :prompt "A pathname"))

(terpri *query-io*)

(setq b (accept 'integer :prompt "A number"

:query-indentifier 'the-tag))

(terpri *query-io*)

(setq c (accept 'string :prompt "A string")))

(values a b c)))

When the initial display is output, the input editor cursor appears after the prompt of the tagged field, just as if the user had selected that field by clicking on it. The default value, if any, for the selected field is not displayed.

resynchronize-every-pass
is a boolean option specifying whether earlier queries depend on later values; the default is
nil
. When it is
t
, the contents of the dialog are redisplayed an additional time after each user interaction. This has the effect of ensuring that, when the value of some field of a dialog depends on the value of another field, all of the displayed fields will be up to date.

You can use this option to alter the dialog dynamically. The following example initially displays an integer field that disappears if a value other than 1 is entered; a two-field display appears in its place.

(defun alter-multiple-accept ()

(let ((flag 2))

(accepting-values

(*query-io* :resynchronize-every-pass t)

(setq flag (accept 'integer :default flag :prompt "Number"))

(when (= flag 1)

(terpri *query-io*)

(accept 'string :prompt "String"

(terpri *query-io*)

(accept 'pathname :prompt "Pathname"))))))

label
is as for
menu-choose
.
scroll-bars
controls what and whether scroll-bars appear on the dialog. The value is one of:
:vertical
,
:horizontal
,
:both
, and
nil
(the default).
x-position
and
y-position
are as for
menu-choose-from-drawer
.

accept-values

Summary:
accepting-values
is a CLIM application frame that uses
accept-values
as the name of the frame class.

accept-values-pane-displayer [Function]

Arguments: frame pane
&key
displayer resynchronize-every-pass

Summary: When you use an
:accept-values
pane, the display function must use
accept-values-pane-displayer
.
displayer
is a function that is the body of an
accepting-values
dialog. It takes two arguments, the frame and a stream. The display function does not need to call
accepting-values
itself, since that is done by
accept-values-pane-displayer
.
resynchronize-every-pass
is as for
accepting-values
.

display-exit-boxes [Generic Function]

Arguments: frame stream view

Summary: Displays the exits boxes for the
accepting-values
frame
frame
on the stream
stream,
in the view
view
. The exit boxes specification is not passed in directly, but is a slot in the frame. The default method (on
accept-values
) simply writes a line of text associating the Exit and Abort strings with presentations that either exit or abort from the dialog.

The
frame
,
stream
, and
view
arguments may be specialized to provide a different look-and-feel for different host window systems.

accept-values-resynchronize [Generic Function]

Arguments: stream

Summary: Causes
accepting-values
to resynchronizes the dialog once on the accepting values stream
stream
before it restarts the dialog loop.

Summary: The prompt
prompt
creates the button area by writing to the appropriate
accepting-values
stream
stream
.
prompt
should not produce a string itself. When a pointer button is clicked in this area at runtime,
body
will be evaluated.

accept-values-command-button
expands into a call to
invoke-accept-values-command-button
, supplying a function that executes
body
as the
continuation
argument to
invoke-accept-values-command-button
.

The
stream
argument is not evaluated, and must be a symbol that is bound to a stream. If
stream
is
t
(the default),
*query-io*
is used.
body
may have zero or more declarations as its first forms.

Summary: Displays the prompt
prompt
on the stream
stream
and creates the button areas. When a pointer button is clicked in this area at runtime, the continuation will be called.
continuation
is a function that takes no arguments.
view
is a view.

prompt
may be either a string (which will be displayed via
write-string
), or a form that will be evaluated to draw the button.

documentation
is an object that will be used to produce pointer documentation for the button. It defaults to
prompt
. If it is a string, the string itself will be used as the pointer documentation. Otherwise it must be a function of one argument, the stream to which the documentation should be written.

When
resynchronize
is
t
, the dialog will be redisplayed an additional time whenever the command button is clicked on. See the
resynchronize-every-pass
argument to
accepting-values
.

cache-value a
nd
cache-test
are as for
updating-output
. That is,
cache-value
should evaluate to the same value if and only if the output produced by
prompt
does not ever change.
cache-test
is a function of two arguments that is used to compare cache values.
cache-value
defaults to
t
and
cache-test
defaults to
eql
.

This function may only be used inside the dynamic context of an
accepting-values
.

frame-manager-dialog-view [Generic Function]

Arguments: frame-manager

Summary: Returns the view used by default for
accepting-values
when mediated by
frame-manager
.

(setf frame-manager-dialog-view) [Generic Function]

Arguments: frame-manager view

Summary: Sets the view used by default for
accepting-values
when mediated by
frame-manager
. Useful values for
view
are
+gadget-dialog-view+
and
+textual-dialog-view+
.