accepting-values [Macro]
Arguments: (
&optional
stream
&key
own-window exit-boxes initially-select-query-identifier resynchronize-every-pass label scroll-bars x-position y-position frame-class)
&body
body
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-identifier '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 .
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]
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]
Summary: Causes accepting-values to resynchronizes the dialog once on the accepting values stream stream before it restarts the dialog loop.
accept-values-command-button [Macro]
Arguments: (
&optional
stream
&key
documentation query-identifier cache-value cache-test resynchronize) prompt
&body
body
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.
invoke-accept-values-command-button[Generic Function]
Arguments: stream continuation view prompt
&key
documentation query-identifier cache-value cache-test resynchronize
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]
Summary: Returns the view used by default for accepting-values when mediated by frame-manager .
(setf frame-manager-dialog-view) [Generic Function]
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+ .
Common Lisp Interface Manager 2.0 User's Guide - 3 Mar 2015