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]
Arguments: 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]
Arguments: 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]
Arguments: 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):
Translators with a higher "high order" priority precede translators with a lower "high order" priority. This allows programmers to set the priority of a translator in such a way that it always precedes all other translators.
Translators with a more specific "from type" precede translators with a less specific "from type."
Translators with a higher "low order" priority precede translators with a lower "low order" priority. This allows programmers to break ties between translators that translate from the same type.
Translators from the current command table precede translators inherited from superior command tables.
presentation-matches-context-type [Function]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: stream &optional prefer-pointer-window
Summary: Unhighlights any highlighted presentations on stream .