wiki:EasyGuiEvents

This section is obsolete and provided for reference only

TODO: This was the design for Carbon. A more agnostic design is needed

Carbon Events

Carbon supports a vast number of events which can be used to customize view behavior. We provide an interface that allows you to specify Carbon event callbacks through initargs when creating a view.

(define-carbon-event event-keyword event-class event-kind) [macro]

This macros establishes event-keyword as the keyword for the Carbon event identified in Carbon by the two values event-class and event-kind. It allows event-keyword to be used as an initarg in creating views to specify a callback for the event (or equivalently the callback can be set later with set-carbon-event-handler). Example:

(define-carbon-event :click-grow-box-event kEventClassWindow kEventWindowClickResizeRgn)

(make-instance 'my-window
 :click-grow-box-event #'(lambda (window) …) …)

It is acceptable to define multiple event keywords for the same Carbon signature. Doing so allows specifying multiple handlers for the event (which will be executed in LIFO order).

(define-carbon-command-event event-keyword command-id) [macro]

As a special case, we provide a default handler for kEventClassCommand/kEventProcessCommand that does an extra level of dispatch on the command id. Therefore you can define an event-keyword for a specific command-id, and it will be treated just like any other kind of event, for example:

(define-carbon-command-event :check-spelling-command kHICommandCheckSpelling)

(make-instance 'my-view :check-spelling-command #'(lambda (view) …) …)

(carbon-event-class event-keyword) [function]

Returns the event class of event-keyword, or nil if event-keyword is not a defined carbon event.

(carbon-event-kind event-keyword) [function]

Returns the event kind of event-keyword, or nil if event-keyword is not a defined carbon event.

(find-carbon-events event-class event-kind) [function]

Returns a list of all the event keywords defined for the Carbon event event-class/event-kind.

(set-carbon-event-handler view event-spec handler) [method]

Sets handler as the handler for event-%%spec%% in view. Any previous handler for event-%%spec%% in view is removed. event-%%spec%% can be either an event keyword as defined by define-carbon-event or define-carbon-command-event, or it can be an ostype representing a command id. handler should be nil or a funcallable object (function or symbol). If non-nil, it will be called with one argument, the view. The handler can call exit-event-handler to exit. Exiting normally is equivalent to calling (exit-event-handler t).

(carbon-event-handler view event-spec) [method]

Returns the handler registered for event-%%spec%% in view, or nil if view doesn't have a handler registered for event-%%spec%%.

(exit-event-handler &optional error) [method]

An error if called outside the context of an event handler. If called from a handler, does a non--local exit out of the handler. If error is nil or unspecified, the event is assumed to have been handled and no other handlers will be invoked. Otherwise, error should be either t (which is equivalent to eventNotHandledErr), or a Carbon error code, and event handling will continue normally,

The following event keywords are predefined (we'll define more, but these are supposedly the most common)

(define-carbon-event :window-activated-event "wind" kEventWindowActivated)
(define-carbon-event :window-deactivated-event "wind" kEventWindowDeactivated)
(define-carbon-event :window-bounds-changed-event "wind" kEventWindowBoundsChanged)
(define-carbon-event :window-bounds-changing-event "wind" kEventWindowBoundsChanging)
(define-carbon-event :window-draw-content-event "wind" kEventWindowDrawContent)
(define-carbon-event :window-content-click-event "wind" kEventWindowContentClick)
(define-carbon-event :window-close-event "wind" kEventWindowClose)
(define-carbon-event :window-closed-event "wind" kEventWindowClosed)
(define-carbon-event :control-activate-event "cntl" kEventControlActivate)
(define-carbon-event :control-deactivate-event "cntl" kEventControlDeactivate)
(define-carbon-event :control-hit-event "cntl" kEventControlHit)
(define-carbon-event :control-track-event "cntl" kEventControlTrack)
(define-carbon-event :control-draw-event "cntl" kEventControlDraw)
(define-carbon-event :control-bounds-changed-event "cntl" kEventControlBoundsChanged)

Unlike the above, this is actually the complete set of predefined Carbon command ids:

(define-carbon-command-event :ok-command-event "ok")
(define-carbon-command-event :cancel-command-event "not!")
(define-carbon-command-event :quit-command-event "quit")
(define-carbon-command-event :undo-command-event "undo")
(define-carbon-command-event :redo-command-event "redo")
(define-carbon-command-event :cut-command-event "cut ")
(define-carbon-command-event :copy-command-event "copy")
(define-carbon-command-event :paste-command-event "past")
(define-carbon-command-event :clear-command-event "clea")
(define-carbon-command-event :select-all-command-event "sall")
(define-carbon-command-event :hide-command-event "hide")
(define-carbon-command-event :hide-others-command-event "hido")
(define-carbon-command-event :show-all-command-event "shal")
(define-carbon-command-event :preferences-command-event "pref")
(define-carbon-command-event :zoom-window-command-event "zoom")
(define-carbon-command-event :minimize-window-command-event "mini")
(define-carbon-command-event :minimize-all-command-event "mina")
(define-carbon-command-event :maximize-window-command-event "maxi")
(define-carbon-command-event :maximize-all-command-event "maxa")
(define-carbon-command-event :arrange-in-front-command-event "frnt")
(define-carbon-command-event :bring-all-to-front-command-event "bfrt")
(define-carbon-command-event :window-list-separator-command-event "wldv")
(define-carbon-command-event :window-list-terminator-command-event "wlst")
(define-carbon-command-event :select-window-command-event "swin")
(define-carbon-command-event :rotate-windows-forward-command-event "rotw")
(define-carbon-command-event :rotate-windows-backward-command-event "rotb")
(define-carbon-command-event :rotate-floating-windows-forward-command-event "rtfw")
(define-carbon-command-event :rotate-floating-windows-backward-command-event "rtfb")
(define-carbon-command-event :about-command-event "abou")
(define-carbon-command-event :new-command-event "new ")
(define-carbon-command-event :open-command-event "open")
(define-carbon-command-event :close-command-event "clos")
(define-carbon-command-event :save-command-event "save")
(define-carbon-command-event :save-as-command-event "svas")
(define-carbon-command-event :revert-command-event "rvrt")
(define-carbon-command-event :print-command-event "prnt")
(define-carbon-command-event :page-setup-command-event "page")
(define-carbon-command-event :app-help-command-event "ahlp")
(define-carbon-command-event :show-character-palette-command-event "chrp")
(define-carbon-command-event :show-spelling-panel-command-event "shsp")
(define-carbon-command-event :check-spelling-command-event "cksp")
(define-carbon-command-event :change-spelling-command-event "chsp")
(define-carbon-command-event :check-spelling-as-you-type-command-event "chsp")
(define-carbon-command-event :ignore-spelling-command-event "igsp")
(define-carbon-command-event :learn-word-command-event "lrwd")