The material in this section is advanced; most CLIM programmers can skip to the next chapter. This section discusses low-level functions for CLIM presentation translators.
Some applications may wish to deal directly with presentation translators, for example, if you are tracking the pointer yourself and wish to locate sensitive presentations, or want to generate a list of applicable translators for a menu. The following functions are useful for finding and calling presentation translators directly.
find-presentation-translators Function
find-presentation-translators from-type to-type command-table
Summary: Returns a list of all of the translators in the command table command-table that translate from from-type to to-type, without taking into account any type parameters or testers. from-type and to-type are presentation type specifiers, and must not be abbreviations. frame must be an application frame.
test-presentation-translator Function
test-presentation-translator translator presentation context-type frame window x y &key event modifier-state for-menu
Summary: Returns t
if the translator translator applies to the presentation presentation in input context type context-type, otherwise returns nil
. (There is no from-type argument because it is derived from presentation.) x and y are the x and y positions of the pointer within the window stream window.
event and modifier-state are a pointer button event and modifier state (see event-modifier-key-state
), and are compared against the translator's gesture. event defaults to nil
, and modifier-state defaults to 0, meaning that no modifier keys are held down. Only one of event or modifier-state may be supplied.
If for-menu is t
, the comparison against event and modifier-state is not done.
presentation, context-type, frame, window, x, y, and event are passed along to the translator's tester if and when the tester is called.
test-presentation-translator
matches type parameters and calls the translator's tester. Under some circumstances, test-presentation-translator
may also call the body of the translator to ensure that its value matches to-type.
find-applicable-translators Function
find-applicable-translators presentation input-context frame window x y &key event modifier-state for-menu fastp
Summary: Returns an object that describes the translators that definitely apply to the presentation presentation in the input context input-context. The result is a list whose elements are each of the form (translator the-presentation context-type tag) where translator is a presentation translator, the-presentation is the presentation that the translator applies to (and which can be different from presentation due to nesting of presentations), context-type is the context type in which the translator applies, and tag is a tag used internally by CLIM. translator, the-presentation, and context-type can be passed to such functions as call-presentation-translator and document-presentation-translator.
Since input contexts can be nested, find-applicable-translators
must iterate over all the contexts in input-context. window, x, and y are as for test-presentation-translator. event and modifier-state (which default to nil
and the current modifier state for window, respectively) are used to further restrict the set of applicable translators. (Only one of event or modifier-state may be supplied; it is unspecified what will happen if both are supplied.)
When for-menu is non-nil, the value of for-menu is matched against the presentation's menu specification, and only those translators that match are returned. event and modifier-state are disregarded in this case. for-menu defaults to nil
.
When the boolean fastp is t
, find-applicable-translators
will simply return t
if there are any translators. When fastp is nil
(the default), the list of translators returned by find-applicable-translators
must be in order of their "desirability"; that is, translators having more specific from-types and/or higher priorities must precede translators having less specific from-types and lower priorities.
The rules used for ordering the translators returned by find-applicable-translators
are as follows (in order):
presentation-matches-context-type Function
presentation-matches-context-type presentation context-type frame window x y &key event modifier-state
Summary: Returns t
if there are any translators that translate from the presentation presentation's type to the input context type context-type; otherwise, it returns nil
. (There is no from-type argument because it is derived from presentation.) frame, window, x, y, event, and modifier-state are as for test-presentation-translator.
If there are no applicable translators, presentation-matches-context-type
will return nil
.
call-presentation-translator Function
call-presentation-translator translator presentation context-type frame event window x y
Summary: Calls the function that implements the body of the translator translator on the presentation presentation's object, and passes presentation, context-type, frame, event, window, x, and y to the body of the translator as well.
The returned values are the same as the values returned by the body of the translator, namely, the translated object and the translated type.
document-presentation-translator Function
document-presentation-translator translator presentation context-type frame event window x y &key stream documentation-type
Summary: Computes the documentation string for the translator translator and outputs it to the stream stream, which defaults to *standard-output*. presentation, context-type, frame, event, window, x, and y are as for test-presentation-translator.
documentation-type
must be either :normal
or :pointer
. If it is :normal
, the usual translator documentation function is called. If it is :pointer
, the translator's pointer documentation is called.
call-presentation-menu Function
call-presentation-menu presentation input-context frame window x y &key for-menu label
Summary: Finds all the applicable translators for the presentation presentation in the input context input-context, creates a menu that contains all of the translators, and pops up the menu from which the user can choose a translator. After the translator is chosen, it is called with the arguments supplied to call-presentation-menu
, and the matching input context established by with-input-context is terminated.
window, x, y, and event are as for find-applicable-translators. for-menu, which defaults to t
, is used to decide which of the applicable translators will go into the menu; only those translators whose :menu
option matches menu will be included.
label is either a string to use as a label for the menu, or is nil
(the default), meaning the menu will not be labelled.
The following functions are useful for finding an application presentation in an output history:
find-innermost-applicable-presentation Function
find-innermost-applicable-presentation input-context window x y &key frame modifier-state event
Summary: Given an input context input-context, an output recording window stream window, x and y positions x and y, returns the innermost presentation whose sensitivity region contains x and y that matches the innermost input context, using the translator matching algorithm described later. If there is no such presentation, this function will return nil
.
event and modifier-state are a pointer button event and modifier state (see event-modifier-key-state
). event defaults to nil
, and modifier-state defaults to the current modifier state for window. Only one of event or modifier-state may be supplied; it is unspecified what will happen if both are supplied.
frame defaults to the current frame, *application-frame*.
The default method for frame-find-innermost-applicable-presentation will call this function.
throw-highlighted-presentation Function
throw-highlighted-presentation presentation input-context button-press-event
Summary: Given a presentation presentation, input context input-context, and a button press event (which contains the window, pointer, x and y position of the pointer within the window, the button pressed, and the modifier state), finds the translator that matches the innermost presentation in the innermost input context, then calls the translator to produce an object and a presentation type. Finally, the matching input context that was established by with-input-context will be terminated.
Note that it is possible that more than one translator having the same gesture may be applicable to presentation in the specified input context. In this case, the translator having the highest priority will be chosen. If there is more than one having the same priority, it is unspecified what translator will be chosen.
highlight-applicable-presentation Function
highlight-applicable-presentation frame stream input-context &optional prefer-pointer-window
Summary: This is the core of the "input wait" handler used by with-input-context on behalf of the application frame frame. It locates the innermost applicable presentation on stream in the input context input-context, unhighlighting presentations that are not applicable and highlighting the presentation that is applicable. Typically on entry to highlight-applicable-presentation
, input-context will be the value of *input-context* and frame will be the value of *application-frame*.
prefer-pointer-window is a boolean. If it is t
(the default), CLIM will highlight the applicable presentation on the same window that the pointer is located over. Otherwise, CLIM will highlight an applicable presentation on stream.
set-highlighted-presentation Function
set-highlighted-presentation stream presentation &optional prefer-pointer-window
Summary: Highlights the presentation presentation on stream. This must call highlight-presentation methods if that is appropriate.
unhighlight-highlighted-presentation Function
unhighlight-highlighted-presentation stream &optional prefer-pointer-window
Summary: Unhighlights any highlighted presentations on stream.
CLIM 2.0 User Guide - 01 Dec 2021 19:38:57