define-command Macro

Summary

Defines an alias for a mouse or keyboard gesture that can be used in the input model of an output pane.

Package

capi

Signature

define-command name gesture &key translator host library

Arguments

Description

The macro define-command defines an alias for an input gesture that can then be used in the input model of an output-pane.

name is the name of the alias, which should be a symbol.

gesture is one of the gestures accepted by output-pane. For a full description of the gesture syntax and arguments for the callback, see 12.2.1 Detailed description of the input model. It is possible to specify multiple gestures by passing as gesture a list of the form:

(:one-off gesture1 gesture2 ...)

If translator is supplied it needs to be a function that takes the same arguments that a callback for the gesture would take (not including the extra-callback-args), and returns a list which is used after pane instead of the gesture callback arguments. When there is a translator, the callbacks for commands in the models are invoked by:

(apply callback pane 
       (append (apply translator gesture-callback-args)
               extra-callback-args))

library specifies which library this mapping is applicable to. It is possible to have distinct definitions for different libraries, but redefinition with the same library overrides the previous definition. The default value of library is nil, which means all libraries. host is recognised an alias library for backwards compatibility.

Examples

Firstly, here is an example of defining a command which maps onto a gesture.

(defun gesture-callback (output-pane x y)
  (capi:display-message 
   "Pressed ~S at (~S,~S)"
   output-pane x y))
 
(capi:define-command :select (:button-1 :press))
 
(capi:contain (make-instance
               'capi:output-pane
               :input-model '((:select 
                               gesture-callback))))

Here is a more complicated example demonstrating the use of translator to affect the arguments passed to a callback.

(capi:define-command
  :select-object (:button-1 :press)
  :translator #'(lambda (output-pane x y)
                  (let ((object
                        (capi:pinboard-object-at-position
                                        output-pane x y)))
                                  (when object
                                    (list object)))))

(defun object-select-callback (output-pane
                               &optional object)
  (when object (capi:display-message 
                "Pressed on ~S in ~S"
                object output-pane)))

(setq pinboard
      (capi:contain (make-instance
                    'capi:pinboard-layout
                    :input-model '((:select-object
                               object-select-callback)))))

(make-instance 'capi:item-pinboard-object
               :text "Press Me!"
               :parent pinboard
               :x 10 :y 20)

(make-instance 'capi:line-pinboard-object
               :parent pinboard
               :start-x 20 :start-y 50
               :end-x 120 :end-y 150)

Here is a further example:

(example-edit-file "capi/output-panes/commands")

See also

output-pane
invoke-command
invoke-untranslated-command
12.2.2 Commands - aliases