define-presentation-translator supports presentation translators in general, and define-presentation-to-command-translator supports a common idiom.
define-presentation-translator[Macro]
Arguments: name (from-type to-type command-table &key gesture tester tester-definitive documentation pointer-documentation menu priority) arglist &body body
Summary: Defines a presentation translator named name that translates from objects of type from-type to objects of type to-type . from-type and to-type are presentation type specifiers, but must not include any presentation type options. from-type and to-type may be presentation type abbreviations.
command-table is a command table designator. The translator created by this invocation of define-presentation-translator will be stored in the command table command-table .
gesture is a gesture name that names a pointer gesture (described in 15.3, Gestures and Gesture Names). The body of the translator will be run only if the translator is applicable and gesture used by the user matches the gesture name in the translator. gesture defaults to :select .
tester is either a function or a list of the form (tester-arglist . tester-body) where tester-arglist takes the same form as arglist and tester-body is the body of the tester. The tester must return either t or nil . If it returns nil , then the translator is definitely not applicable. If it returns t , then the translator might be applicable, and the body of the translator might be run (if tester-definitive is nil ) in order to decide definitively whether the translator is applicable. If no tester is supplied, CLIM supplies a tester that always returns t .
When the boolean tester-definitive is t , the body of the translator is not run in order to decide whether the translator is applicable; that is, the tester is assumed to definitively decide whether the translator applies. The default is nil .
Both documentation and pointer-documentation are objects that will be used for documenting the translator. pointer-documentation will be used to generate documentation for the pointer documentation window; the documentation generated by pointer-documentation should be very brief, and computing it should be very fast and preferably not cons. documentation is used to generate such things as items in the :menu -gesture menu. If the object is a string, the string itself will be used as the documentation. Otherwise, the object must be the name of a function or a list of the form (doc-arglist . doc-body) where doc-arglist takes the same form as arglist , but includes a named (keyword) stream argument as well, and doc-body is the body of the documentation function. The body of the documentation function should write the documentation to stream . The default for documentation is nil , meaning that there is no explicitly supplied documentation; in this case, CLIM is free to generate the documentation in other ways. The default for pointer-documentation is documentation .
menu must be t or nil . When it is t , the translator will be included in the :menu-gesture menu if it matches. When it is nil , the translator will not be included in the :menu-gesture menu. Other non- nil values are reserved for future extensions to allow multiple presentation translator menus.
priority is either nil (the default, which corresponds to 1) or an integer that represents the priority of the translator. When there are several translators that match for the same gesture, the one with the highest priority is chosen.
arglist , tester-arglist , and doc-arglist are argument lists that must "match" the "canonical" argument list (object &key presentation context-type frame event window x y) . In order to do so, there must be a single positional argument that corresponds to the presentation's object, and several named arguments that must match the canonical names listed previously (using string-equal to do the comparison).
In the body of the translator (or the tester), the positional object argument will be bound to the presentation's object. The named arguments presentation will be bound to the presentation that was clicked on, context-type will be bound to the presentation type of the context that actually matched, frame will be bound to the application frame that is currently active (usually *application-frame* ), event will be bound to the pointer button event that the user used, window will be bound to the window stream from which the event came, and x and y will be bound to the x and y positions within window that the pointer was at when the event occurred. The special variable *input-context* will be bound to the current input context. Note that context-type and *input-context* will have dynamic extent, so programmers should not store without first copying them.
body is the body of the translator, and is run in the context of the application. body may have zero or more declarations as its first forms. It returns either one, two, or three values. The first value is an object that must be presentation-typep of to-type . The second value is a presentation type that must be presentation-subtypep of to-type . The first two returned values of body are in effect used as the returned values for the call to accept that established the matching input context.
The third value returned by body must either be nil or a list of options (as keyword-value pairs) that will be interpreted by accept . The only option defined so far is :echo , whose value must be either t (the default) or nil . If it is t , the object returned by the translator will be "echoed" by accept , which will use presentation-replace-input to insert the textual representation of the object into the input buffer. If it is nil , the object will not be echoed.
None of define-presentation-translator 's arguments are evaluated.
define-presentation-to-command-translator [Macro]
Arguments: name (from-type command-name command-table &key gesture tester documentation pointer-documentation menu priority echo) arglist &body body
Summary: This resembles define-presentation-translator , except that the to-type will be derived to be the command named by command-name in the command table command-table . command-name is the name of the command that this translator will translate to.
The echo option is a boolean value (the default is t ) that indicates whether the command line should be echoed when a user invokes the translator.
The other arguments to define-presentation-to-command-translator are the same as for define-presentation-translator . Note that the tester for command translators is always assumed to be definitive, so there is no :tester-definitive option. The default for pointer-documentation is the string command-name with dash characters replaced by spaces, and each word capitalized (as in add-command-to-command-table ).
The body of the translator returns a list of the arguments to the command named by command-name . body is run in the context of the application. The returned value of the body, appended to the command name, is passed to execute-frame-command . body may have zero or more declarations as its first forms.
None of this macro's arguments are evaluated.
define-presentation-action [Macro]
Arguments: name (from-type to-type command-table &key gesture tester documentation pointer-documentation menu priority) arglist &body body
Summary: define-presentation-action is similar to define-presentation-translator , except that the body of the action is not intended to return a value, but instead affects some sort of application state.
A presentation action does not satisfy a request for input the way an ordinary translator does. Instead, an action is something that happens while waiting for input. After the action has been executed, the program continues to wait for the same input that it was waiting for prior to executing the action.
The other arguments to define-presentation-action are the same as for define-presentation-translator . Note that the tester for presentation actions is always assumed to be definitive.
None of define-presentation-action 's arguments are evaluated.
define-drag-and-drop-translator [Macro]
Arguments: name from-type to-type destination-type command-table &key gesture tester before-drag-tester documentation pointer-documentation menu priority feedback highlighting arglist &body body
Summary: Defines a presentation translator named name that will be run when a presentation is dragged with the mouse and dropped on top of another presentation. The presentation types of the "dragged" ( from-type ) and "dropped on" ( to-type ) presentations are used to determine which translator ( destination-type ) is invoked. from-type , to-type , and destination-type are presentation type specifiers, but must not include any presentation type options. from-type , to-type and destination-type may be presentation type abbreviations.
The interaction style used by these translators is that a user points to a "from presentation" with the pointer, picks it up by pressing a pointer button matching gesture , drags the "from presentation" to a "to presentation" by moving the pointer, and then drops the "from presentation" onto the "to presentation." The dropping might be accomplished by either releasing the pointer button or clicking again, depending on the frame manager. When the pointer button is released, the translator whose destination-type matches the presentation type of the "to presentation" is chosen. For example, dragging a file to the TrashCan on a Macintosh could be implemented by a drag and drop translator.
When the user drags a "from presentation" over potential targets, the function or list specified by tester is invoked. This tester is identical to tester for define-presentation-translator except that it can take two additional arguments: destination-object and destination-presentation .
When the user points at a potential "from presentation" to drag, the function or list specified by before-drag-tester is invoked. The before-drag-tester takes the same arguments as tester for define-presentation-translator .
While the pointer is being dragged, the function specified by feedback is invoked to provide feedback to the user. The function is called with eight arguments: the application frame object, the "from presentation," the stream, the initial x and y positions of the pointer, the current x and y positions of the pointer, and a feedback state (either :highlight to draw feedback, or :unhighlight to erase it). The feedback function is called to draw some feedback the first time pointer moves, and is then called twice each time the pointer moves thereafter (once to erase the previous feedback, and then to draw the new feedback). It is called a final time to erase the last feedback when the pointer button is released. feedback defaults to frame-drag-and-drop-feedback .
When the "from presentation" is dragged over any other presentation that has a direct manipulation translator, the function specified by highlighting is invoked to highlight that object. The function is called with four arguments: the application frame object, the "to presentation" to be highlighted or unhighlighted, the stream, and a highlighting state (either :highlight or :unhighlight ). highlighting defaults to frame-drag-and-drop-highlighting .
Note that it is possible for there to be more than one drag and drop translator that applies to the same from-type , to-type , and gesture . In this case, the exact translator that is chosen for use during the dragging phase is unspecified. If these translators have different feedback, highlighting, documentation, or pointer documentation, the exact behavior is unspecified.
The other arguments to define-drag-and-drop-translator are the same as for define-presentation-translator .