A list of input specifications, otherwise known as a command table.
When the CAPI needs to redisplay a region of the output pane, the
gets called with the
output-pane and the
of the region that needs redrawing. The
should then use Graphics Ports functions to redisplay that area. To force an area to be re-displayed, use the function invalidate-rectangle.
Note: if you need to temporarily prevent the display-callback from running, for example because it is slow, then use the Cached Display interface so that the pane still redraws. See output-pane-cache-display for the details.
should be either
:compatible which causes drawing to be the same as in LispWorks 6.0, or
:quality which causes all the drawing to be transformed properly, and allows control over anti-aliasing on Microsoft Windows and GTK+. The default value of
For more information about drawing-mode , see The drawing mode and anti-aliasing.
Draw glyphs directly using Core Graphics. This only draws characters with glyphs in the chosen font.
Draw using ATSUI APIs where possible.This is slower but can handle more characters.
is true, display of the
output-pane (that is drawing the background and calling the
) is done by first drawing to a pixmap buffer, and then drawing from that buffer. This is useful to avoid flickering if the display is complex. The default value of
( gesture callback . extra-callback-args )
gesture specifies the type of gesture, which can be Gesture Spec (representing keyboard input), character, mouse button (including multiple clicks made in quick succession), modifier change, key, command or cursor motion. On Microsoft Windows and Cocoa gesture can also specify multi-touch gestures that come from trackpad or touchscreen devices, including zoom, rotate, pan and more.
can be set before the pane is displayed, but changes after that are ignored.
cl:initialize-instance is the natural place for subclasses to modify the existing
, using the output-pane accessor
output-pane-input-model. Note that since the mappings are processed in order, prepending to an existing
overrides it when there are clashes, while appending affects only gestures for which the original
did not have a match.
For all the details of input-model syntax and the precedence and interpretation of the various gesture types, see Detailed description of the input model.
:scrolled, which is the default, then the CAPI is responsible for scrolling over the scroll range, and the origin for all the coordinates in callbacks and drawing is scrolling when the user scrolls the pane. This is known as ordinary scrolling, and is what you normally use.
:fixed, then the user code is responsible for handling scrolling inside the
output-pane, and the origin for all coordinates is fixed relative to the top left of the visible area.
:fixed-graphics, the behavior is like
:fixed, except that the origin for all CAPI callbacks and function is scrolled (like the ordinary case). Note that in this case, the CAPI coordinates do not match the coordinates used when drawing.
:fixed-graphics is more complex, but is also much more flexible. See output-pane scrolling for full details.
When the output pane is scrolled, the CAPI calls the
if this is non-nil. The arguments of the scroll callback are the
output-pane, the direction (
:pan), the scroll operation (
:page), the amount of scrolling (an integer), and a keyword argument
:interactive. This has value
t if the scroll was invoked interactively, and value
nil if the scroll was programmatic, such as via the function scroll. In the Mac OS X Cocoa implementation the direction is always
:pan. See the following CAPI example files:
, if non-nil, is a function of two arguments. The first argument is the
output-pane itself, and the second is a boolean. When the
output-pane gets the focus,
is called with second argument
t, and when the
output-pane loses the focus,
is called with second argument
, if non-nil, is a function of five arguments called when the
output-pane is resized. The first argument is the
output-pane itself, and the rest are its new geometry:
create-callback , if non-nil, is a function of one argument which is called just after the pane is created (but before it becomes visible). The argument is the pane itself. This function can perform initialization such as loading images.
destroy-callback , if non-nil, is a function of one argument which is called just before the pane is destroyed, for example when the window is closed or the pane is removed from its layout. The argument is the pane itself. This function can perform cleanup operations (though note that images associated with the pane are automatically freed).
is not supplied, or is
:default, the default is used, which is controlled by set-default-use-native-input-method. The default setting is always to use native input methods.
The composition operation is starting.
The composition ends.
A plist describing the "preedit" string, which is a string containing the partial input that should be displayed while the composition is ongoing. These calls with a plist occur only when the underlying system does not display the partial input itself. Currently on Microsoft Windows the system always displays the preedit string itself, so these calls occur only on GTK+ and Cocoa.
During composition there will be repeated calls with a list, in general each time that the preedit string changes. Each call is a complete description of what needs to be displayed. The data from previous calls should be ignored.
The value is a list where each element is itself a list, where the first element is a string and the second a plist describing a face (a face plist). The strings are the strings that need to be displayed, and the face plist describing the face that the underlying GUI thinks that each string needs to be displayed. The face plist may contain any of the following keywords:
:underline-p. The argument
nil, which means display nothing.
The argument is an integer describing where the "cursor" should be displayed. The index is into the string that is concatenation of the strings in string-face-lists .
The editor uses the
:start call to position the composition window at the cursor by using set-composition-placement and the calls with a list to display the partial composition string.
:startshould typically use set-composition-placement to tell the system where the interaction should happen. The calls to composition-callback with a list do not always happen, the underlying system may do it all itself.
:endcalls are not reliable.
In LispWorks 7.0 and earlier versions, the initarg
:pane-can-scroll was used instead of
:pane-can-scroll can still be used, but it is deprecated.
:pane-can-scroll nil is the same as
:pane-can-scroll t is the same as
:coordinate-origin :fixed-graphics. There was no documented equivalent to
See also Self-contained examples.
Programming with CAPI Windows
Popup menus for panes
Creating Panes with Your Own Drawing and Input
Drawing - Graphics Ports
Printing from the CAPI—the Hardcopy API
Drag and Drop
CAPI User Guide and Reference Manual (Windows version) - 3 Aug 2017