The primary means for getting input from the end user is accept . Characters typed in at the keyboard in response to a call to accept are parsed, and the application object they represent is returned to the calling function. (The parsing is done by the accept method for the presentation type.) Alternatively, if a presentation of the type specified by the accept call has previously been displayed, the user can click on it with the pointer and accept returns it directly (that is, no parsing is required).
Enter a string [default abracadabra]: abracadabra
In the first call to accept , abracadabra was typed at the keyboard. In the second call to accept , the user clicked on the keyboard-entered string of the first function. In both cases, the string object "abracadabra" was returned.
Typically, not all objects are acceptable as input. Only an object of the presentation type specified in the current accept function (or one of its subtypes) can be input. In other words, the accept function establishes the current input context. For example, if the call to accept specifies an integer presentation type, only an entered or displayed integer is acceptable. Numbers displayed as integer presentations would, in this input context, be sensitive, but those displayed as part of some other kind of presentation, such as a file pathname, would not. In this manner, accept controls the input context and the sensitivity of displayed presentations.
It is possible, however, to click on a presentation of a type different from the current input context and invoke a presentation translator that would produce a type acceptable to the input context. For example, you could make a presentation of a file pathname translate to an integer--say, its length--if you want. It is very common to translate to a command that operates on a presented object. For more information on presentation translators, see 6.5, Predefined Presentation Types.
We said previously that the range of acceptable input is typically restricted, but how restricted is up to you, the programmer. Using compound presentation types like and and or , as well as other predefined or specially devised presentation types, gives you a high degree of flexibility and control over the input context.
CLIM provides the following top-level operators for accepting typed input. The most general operator is with-input-context , and accept and accept-from-string support common idioms.
Note that, in general, CLIM accept operators do not insert newlines. If you want each call to accept to appear on a new line, use terpri .
*input-context*
Summary: The current input context. This will be a list, each element of which corresponds to a single call to with-input-context . The first element of the list is the context established by the most recent call to with-input-context , and the last element is the least recent call to with-input-context . This ordering of input contexts is called "nesting."
The exact format of the elements in the list is unspecified, but will typically be a list of a presentation type and a tag that corresponds to the point in the control structure of CLIM at which the input context was established. *input-context* and the elements in it may have dynamic extent.
with-input-context [Macro]
Arguments: (type &key override) ( &optional object-var type-var event-var options-var) form &body pointer-cases
Summary: Establishes an input context of presentation type type ; this is done by binding *input-context* to reflect the new input context. When the boolean override is nil (the default), this invocation of with-input-context adds its context presentation type to the current context. In this way an application can solicit more than one type of input at the same time. Alternatively, when override is t , it overrides the current input context rather than nesting inside the current input context.
type can be a presentation type abbreviation.
After establishing the new input context, form is evaluated. If no pointer gestures are made by the user during the evaluation of form , the values of form are returned. Otherwise, one of the pointer-cases is executed (based on the presentation type of the object that was clicked on) and its value is returned. (See the descriptions of call-presentation-menu and throw-highlighted-presentation .) pointer-cases is constructed like a typecase statement clause list whose keys are presentation types; the first clause whose key satisfies the condition ( presentation-subtypep type key ) is the one that is chosen.
During the execution of one of the pointer-cases , object-var is bound to the object that was clicked on (the first returned value from the presentation translator that was invoked), type-var is bound to its presentation type (the second returned value from the translator), and event-var is bound to the pointer button event that was used. options-var is bound to any options that a presentation translator might have returned (the third value from the translator), and will be either nil or a list of keyword-value pairs. object-var , type-var , event-var , and options-var must all be symbols.
type , stream , and override are evaluated, but the others are not:
(with-input-context ('pathname)(path)
(read)
(pathname
(format t
"~&The pathname ~A was clicked on."
path)))
accept [Function]
Arguments: type &key stream view default default-type provide-default insert-default replace-input history prompt prompt-mode display-default query-identifier activation-gestures additional-activation-gestures delimiter-gestures additional-delimiter-gestures
Summary: Requests input of type type from the stream stream , which defaults to *query-io* . accept returns two values, the object representing the input and its presentation type. type is a presentation type specifier, and can be an abbreviation. The other arguments and overall behavior of accept are as for accept-1 .
accept first expands any presentation type abbreviations ( type , default-type , and history ), handles the interactions between the default, default type, and presentation history, prompts the user by calling prompt-for-accept , and then calls stream-accept on stream , type , and the remaining keyword arguments.
The reason accept is specified as a three-function "trampoline" is to allow close tailoring of the behavior of accept . accept itself is the function that should be called by application programmers. stream-accept exists so that CLIM implementors can specialize on a per-stream basis. (For example, the behavior of accepting-values can be implemented by creating a special class of stream that turns calls to accept into fields of a dialog.) accept-1 is provided as a convenient function for the stream-accept methods to call when they require the default behavior.
stream-accept [Generic Function]
Arguments: stream type &key view default default-type provide-default insert-default replace-input history prompt prompt-mode display-default query-identifier activation-gestures additional-activation-gestures delimiter-gestures additional-delimiter-gestures
Summary: stream-accept is the per-stream implementation of accept , analogous to the relationship between read-char and stream-read-char . All extended input streams implement a method for stream-accept . The default method (on standard-extended-input-stream ) simply calls accept-1 .
The arguments and overall behavior of stream-accept are as for accept-1 .
accept-1 [Function]
Arguments: stream type &key view default default-type provide-default insert-default replace-input history prompt prompt-mode display-default query-identifier activation-gestures additional-activation-gestures delimiter-gestures additional-delimiter-gestures
Summary: Requests input of type type from the stream stream . type must be a presentation type specifier. view is a view object that defaults to stream-default-view of stream . accept-1 returns two values, the object representing the input and its presentation type. (If frame-maintain-presentation-histories is true for the current frame, then the returned object is also pushed on to the presentation history for that object.)
accept-1 establishes an input context via with-input-context , and then calls the accept presentation method for type and view . accept allows input editing when called on an interactive stream; see 16.1, Input Editing for a discussion of input editing. The call to accept will be terminated when the accept method returns or the user clicks on a sensitive presentation. The typing of an activation and delimiter character is typically one way in which a call to an accept method is terminated.
A top-level accept satisfied by keyboard input discards the terminating keyboard gesture (which will be either a delimiter or an activation gesture). A nested call to accept leaves the terminating gesture unread.
If the user clicked on a matching presentation, accept-1 will insert the object into the input buffer by calling presentation-replace-input on the object and type returned by the presentation translator, unless either the boolean replace-input is nil or the presentation translator returned an :echo option of nil . replace-input defaults to t , but this default is overridden by the translator explicitly returning an :echo option of nil .
If default is supplied, then it and default-type are returned as values from accept-1 when the input is empty. default-type must be a presentation type specifier. If default is not supplied and provide-default is t (the default is nil ), then the default is determined by taking the most recent item from the presentation type history specified by history . If insert-default is t and there is a default, the default will be inserted into the input stream by calling presentation-replace-input . It will be editable.
history must be either nil , meaning that no presentation type history will be used, or a presentation type (or abbreviation) that names a history to be used for the call to accept . history defaults to type .
prompt can be t , which prompts by describing the type, nil , which suppresses prompting, or a string, which is displayed as a prompt (via write-string ). The default is t , which produces Enter a type: in a top-level call to accept or "( type )" in a nested call to accept .
If the boolean display-default is t , the default is displayed (if one was supplied). If display-default is nil , the default is not displayed. display-default defaults to t if prompt was provided; otherwise, it defaults to nil .
prompt-mode can be :normal (the default) or :raw , which suppresses putting a colon after the prompt and/or default in a top-level accept and suppresses putting parentheses around the prompt and/or default in a nested accept .
query-identifier is used within accepting-values to identify the field within the dialog.
activation-gestures is a list of gesture names that will override the current activation gestures, which are stored in *activation-gestures* . additional-activation-gestures can be supplied to add activation gestures without overriding the current ones. See 16.2, Activation and Delimiter Gestures for a discussion of activation gestures.
delimiter-gestures is a list of gesture names that will override the current delimiter gestures, which are stored in *delimiter-gestures* . additional-delimiter-gestures can be supplied to add delimiter gestures without overriding the current ones. See 16.2, Activation and Delimiter Gestures for a discussion of delimiter gestures.
accept-from-string [Function]
Arguments: type string &key view default default-type start end
Summary: Like accept , except that the input is taken from string , starting at the position specified by start and ending at end . view , default , and default-type are as for accept .
accept-from-string returns an object and a presentation type (as in accept ), but also returns a third value, the index at which input terminated.
prompt-for-accept [Generic Function]
Arguments: stream type view &rest accept-args &allow-other-keys
Summary: Called by accept to prompt the user for input of presentation type type on the stream stream for the view view . accept-args are all of the keyword arguments supplied to accept . The default method (on standard-extended-input-stream ) simply calls prompt-for-accept-1 .
prompt-for-accept-1 [Function]
Arguments: stream type &key default default-type display-default prompt prompt-mode &allow-other-keys
Summary: Prompts the user for input of presentation type type on the stream stream .
If the boolean display-default is t , then the default is displayed; otherwise it is not. When the default is being displayed, default and default-type are taken as the object and presentation type of the default to display. display-default defaults to t if prompt is non- nil ; otherwise, it defaults to nil .
If prompt is nil , no prompt is displayed. If it is a string, that string is displayed as the prompt. If prompt is t (the default), the prompt is generated by calling describe-presentation-type to produce a prompt of the form Enter a type: in a top-level call to accept , or "( type )" in a nested call to accept .
prompt-mode can be :normal (the default) or :raw , which suppresses putting a colon after the prompt and/or default in a top-level accept and suppresses putting parentheses around the prompt and/or default in a nested accept .