Class

Summary

An output pane is a pane whose display and input behavior can be controlled by the programmer.

Package

capi

Superclasses

titled-object
simple-pane
gp:graphics-port-mixin

Subclasses

pinboard-layout
editor-pane

Initargs

:display-callback

A function that knows how to redisplay the pane.

:input-model

A list of input specifications, otherwise known as a command table.

:scroll-callback

A function called when the pane is scrolled, or nil . The default is nil .

:pane-can-scroll

A generalized boolean specifying whether the pane itself is responsible for drawing into the visible area.

:focus-callback

A function called when the pane gets or loses the input focus, or nil . The default is nil .

:resize-callback

A function called when the pane is resized, or nil . The default is nil .

:create-callback

A function called just after the pane is created.

:destroy-callback

A function called just before the pane is destroyed.

:graphics-options

A platform-specific plist of options controlling how graphics are drawn.

:draw-with-buffer

A boolean controlling whether output is buffered, on Windows and Motif.

Accessors

output-pane-display-callback
output-pane-focus-callback
output-pane-resize-callback
output-pane-scroll-callback
output-pane-create-callback
output-pane-destroy-callback

Readers

output-pane-input-model
output-pane-graphics-options

Description

The class output-pane is a subclass of gp:graphics-port-mixin which means that it supports many of the graphics ports drawing operations. When the CAPI needs to redisplay a region of the output pane, the display-callback gets called with the output-pane and the x , y , width and height of the region that needs redrawing. The display-callback should then use graphics port operations to redisplay that area. To force an area to be re-displayed, use the function invalidate-rectangle.

The input-model provides a means to get callbacks on mouse and keyboard gestures. An input-model is a list of mappings from gesture to callback, where each mapping is a list

( gesture callback . extra-callback-args )

gesture specifies the type of gesture, which can be Gesture Spec, character, button, key, command or motion.

In a Gesture Spec mapping, gesture can be simply the keyword :gesture-spec , which matches any keyboard input. For specific mappings, gesture is a list

(:gesture-spec data [modifier]* )

in which data is a character object or an integer between 0 and char-code-limit (interpreted as the character object obtained by code-char ), or a keyword naming a function key, and each modifier is one of the keywords :shift , :control and :meta . Note that the :meta modifier is received only when the keys style is :emacs (see interface-keys-style).

Also data can be a string which is interpreted as a Gesture Spec as if by sys:coerce-to-gesture-spec . See the LispWorks User Guide and Reference Manual for a description of this and other functions for manipulating Gesture Spec objects.

Note: on Cocoa you cannot receive Command key gestures via Gesture Spec mapping in input-model . To receive Command key gestures you should add corresponding menu items with accelerators. See menu-item for information about accelerators.

In a character mapping, gesture can be simply the keyword :character , which matches any character input. For specific mappings, gesture can be a list containing a single character object char , or a list

( char )

Note: where input would match both a Gesture Spec mapping and a character mapping, the Gesture Spec mapping takes precedence.

In a button mapping, gesture should be list

( button action [modifiers]* )

where button is one of :button-1 , :button-2 or :button-3 denoting the mouse buttons. action is one of :press , :release , :second-press , :third-press , :nth-press and :motion , and each modifier is one of the keywords :shift , :control , :meta and :hyper . The :meta modifier will be the Alt key on most keyboards. On Cocoa, the :hyper modifier is interpreted as the Command key for button and motion gestures. On Windows, the :hyper modifier is currently never generated, so gestures mappings using it will never be invoked. :third-press and :nth-press are supported only on Cocoa and Motif.

Key mappings are intended for detecting low-level keyboard input. In a key mapping, gesture should be a list

(:key [ keyname ] action [ modifiers ]*)

where the optional keyname is a character naming a key (no modifiers) or one of the valid Gesture Spec keywords, action is one of :press or :release and each modifier is one of the keywords :shift , :control and :meta . The callback will receive a Gesture Spec object, with its data set to an integer ASCII code or a keyword representing the primary item on the key and its modifiers representing the set of modifiers pressed. The :meta modifier will be the Alt key on most keyboards. On Cocoa, the :hyper modifier is interpreted as the Command key for :key input.

In a motion mapping, gesture can either be defined in terms of dragging a button (in which case it is defined as a button gesture with action :motion ), or it can be defined for motions whilst no button is down by just specifying the keyword :motion with no additional arguments.

In a command mapping, gesture should be a command which is defined using define-command, and provides an alias for a gesture. The following commands are predefined:

:post-menu

(:button-3 :release) on Microsoft Windows.

(:button-3 :press) on Motif.

(:button-1 :press :control) on Mac OS X.

:control-post-menu

(:button-3 :press :control) on Microsoft Windows, Motif and Mac OS X.

:keyboard-post-menu

(:gesture-spec :f10 :shift) on Microsoft Windows, Motif and Mac OS X.

Note that it is recommended you follow the style guidelines and conventions of the platform you are developing for when mapping gestures to results.

When user input matches gesture , callback is called with standard arguments and any extra-callback-args as extra arguments. The standard arguments are the output-pane , the x cursor position, the y cursor position, and in the case of Gesture Spec, character or key mappings, the input object that matched.

Button mappings with action :press are matched on the first button click, and they pass the standard arguments to their callback . Button mappings with action :second-press and :third-press are matched on the second and third button click made in quick succession, and again they pass the standard arguments to their callback . Button mappings with action :nth-press are matched on the n th button click made in quick succession when there is not a more specific match with :press , :second-press or :third-press . Then the integer n is also passed as the fourth argument to callback , representing the number of times that the button has been pressed in quick succession. If there is a :press , :second-press or :third-press handler then that is invoked instead of :nth-press for the corresponding number of presses.

Note: mouse gestures with :press , :second-press , :third-press and :nth-press actions can each be expected to be followed by a :release action.

Note: In some circumstances :motion events can be received even when the output-pane does not have the input focus. See window style :motion-events-without-focus under interface for details.

If pane-can-scroll is true then the pane is responsible for handling scrolling, by redrawing. It should draw into the visible area according to the scroll parameters. This is known as internal scrolling and an example is editor-pane. If pane-can-scroll is nil , then the CAPI is responsible for scrolling over the data range. The default value is nil . This is known as ordinary scrolling and there is an example in output-panes/scroll-test.lisp .

When the output pane is scrolled, the CAPI calls the scroll-callback if this is non-nil. The arguments of the scroll callback are the output-pane, the direction ( :vertical , :horizontal or :pan ), the scroll operation ( :move , :drag , :step or :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:

output-panes/scroll-test.lisp

output-panes/scrolling-without-bar.lisp

graphics/scrolling-test.lisp

focus-callback , 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, focus-callback is called with second argument t , and when the output-pane loses the focus, focus-callback is called with second argument nil .

resize-callback , 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: x , y , width and height .

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).

graphics-options is currently only used by the Mac OS X Cocoa implementation. The single option defined is :text-rendering , with allowed values:

:glyph

Draw glyphs directly using Core Graphics. This only draws characters with glyphs in the chosen font.

:atsui

Draw using ATSUI APIs where possible.This is slower but can handle more characters.

When draw-with-buffer is true, display of the output-pane (that is drawing the background and calling the display-callback ) 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 draw-with-buffer is nil .

Notes

1. draw-with-buffer is typically useful for a pinboard-layout with large number of pinboard objects, or any other feature that may cause it to flicker.
2. The GTK+ and Cocoa libraries always buffer, so draw-with-buffer is ignored on these platforms.

Example

Firstly, here is an example that draws a circle in an output pane.

(defun display-circle (self x y width height)

  (declare (ignore x y width height))

  (gp:draw-circle self 200 200 200 :filled t))

(capi:contain (make-instance

               'capi:output-pane

               :display-callback 'display-circle)

              :best-width 200 :best-height 200)

Here is an example that shows how to use a button gesture.

(defun test-callback (self x y)

  (capi:display-message

   "Pressed button 1 at (~S,~S) in ~S" x y self))

(capi:contain 

 (make-instance

  'capi:output-pane

  :title "Press button 1:"

  :input-model `(((:button-1 :press)

                  test-callback)))

 :best-width 200 :best-height 200)

This example illustrates Gesture Spec mappings.

(defun draw-input (self x y gspec)

  (let ((data (sys:gesture-spec-data gspec))

        (mods (sys:gesture-spec-modifiers gspec)))

    (gp:draw-string

     self 

     (with-output-to-string (ss) 

       (sys:print-pretty-gesture-spec

        gspec ss :force-shift-for-upcase nil))

     x y)))

(capi:contain 

 (make-instance

  'capi:output-pane

  :title "Press keys in the pane..."

  :input-model '((:gesture-spec

                  draw-input)))

 :best-width 200 :best-height 200)

(capi:contain 

 (make-instance

  'capi:output-pane

  :title "Press Control-a in the pane..."

  :input-model '(((:gesture-spec "Control-a")

                  draw-input)))

 :best-width 200 :best-height 200)

Here is a simple example that draws the character typed at the cursor point.

(defun draw-character (self x y character)

  (gp:draw-character self character x y))

(capi:contain 

 (make-instance

  'capi:output-pane

  :title "Press keys in the pane..."

  :input-model '((:character draw-character)))

 :best-width 200 :best-height 200)

This example shows how to use the motion gesture.

(defun draw-red-blob (self x y)

  (gp:draw-circle self x y 3 

                  :filled t 

                  :foreground :red))

(capi:contain 

 (make-instance

  'capi:output-pane

  :title "Drag button-1 across this pane."

  :input-model '(((:button-1 :motion)

                  gp:draw-point)

                 ((:button-1 :motion :control)

                  draw-red-blob)))

 :best-width 200 :best-height 200)

This example illustrates the use of focus-callback :

(capi:contain 

 (make-instance 

  'capi:output-pane

  :focus-callback 

  #'(lambda (x y)

      (format t 

              "Pane ~a ~:[lost~;got~] the focus~%" 

              x y))))

This example illustrates the use of graphics-options to specify ATSUI drawing on Cocoa:

(defvar *string* 

  (coerce (loop for i from 0 below 60

                collect (code-char (* 5 i))) 

          'text-string))

(capi:contain 

 (make-instance 'capi:output-pane 

                :visible-min-width 400 

                :visible-max-height 50

                :display-callback 

                #'(lambda (pane x y w h)  

                    (gp:draw-string pane 

                                    *string* 

                                    10 10)) 

                :graphics-options 

                '(:text-rendering :atsui)))

There are further examples in the directory examples/capi/output-panes/ .

See also

define-command
pinboard-object
scroll