Changes between Initial Version and Version 1 of EasyGuiEvents


Ignore:
Timestamp:
08/30/08 06:38:54 (6 years ago)
Author:
zzkt
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • EasyGuiEvents

    v1 v1  
     1= This section is obsolete and provided for reference only = 
     2//TODO: This was the design for Carbon.  A more agnostic design is needed// 
     3 
     4== Carbon Events == 
     5 
     6Carbon 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. 
     7 
     8{{{(define-carbon-event event-keyword event-class event-kind) [macro]}}} 
     9 
     10This 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: 
     11 
     12{{{ 
     13(define-carbon-event :click-grow-box-event kEventClassWindow kEventWindowClickResizeRgn) 
     14 
     15(make-instance 'my-window 
     16 :click-grow-box-event #'(lambda (window) …) …) 
     17}}} 
     18 
     19It 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). 
     20 
     21{{{(define-carbon-command-event event-keyword command-id) [macro]}}} 
     22 
     23As 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: 
     24 
     25{{{ 
     26(define-carbon-command-event :check-spelling-command kHICommandCheckSpelling) 
     27 
     28(make-instance 'my-view :check-spelling-command #'(lambda (view) …) …) 
     29}}} 
     30 
     31{{{(carbon-event-class event-keyword) [function]}}} 
     32 
     33Returns the event class of event-keyword, or ''nil'' if event-keyword is not a defined carbon event. 
     34 
     35{{{(carbon-event-kind event-keyword) [function]}}} 
     36 
     37Returns the event kind of event-keyword, or ''nil'' if event-keyword is not a defined carbon event. 
     38 
     39{{{(find-carbon-events event-class event-kind) [function]}}} 
     40 
     41Returns a list of all the event keywords defined for the Carbon event event-class/event-kind. 
     42 
     43{{{(set-carbon-event-handler view event-spec handler) [method]}}} 
     44 
     45Sets 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). 
     46 
     47{{{(carbon-event-handler view event-spec) [method]}}} 
     48 
     49Returns the handler registered for event-%%spec%% in view, or ''nil'' if view doesn't have a handler registered for event-%%spec%%. 
     50 
     51{{{(exit-event-handler &optional error) [method]}}} 
     52 
     53An 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, 
     54 
     55The following event keywords are predefined (we'll define more, but these are supposedly the most common) 
     56 
     57{{{ 
     58(define-carbon-event :window-activated-event "wind" kEventWindowActivated) 
     59(define-carbon-event :window-deactivated-event "wind" kEventWindowDeactivated) 
     60(define-carbon-event :window-bounds-changed-event "wind" kEventWindowBoundsChanged) 
     61(define-carbon-event :window-bounds-changing-event "wind" kEventWindowBoundsChanging) 
     62(define-carbon-event :window-draw-content-event "wind" kEventWindowDrawContent) 
     63(define-carbon-event :window-content-click-event "wind" kEventWindowContentClick) 
     64(define-carbon-event :window-close-event "wind" kEventWindowClose) 
     65(define-carbon-event :window-closed-event "wind" kEventWindowClosed) 
     66(define-carbon-event :control-activate-event "cntl" kEventControlActivate) 
     67(define-carbon-event :control-deactivate-event "cntl" kEventControlDeactivate) 
     68(define-carbon-event :control-hit-event "cntl" kEventControlHit) 
     69(define-carbon-event :control-track-event "cntl" kEventControlTrack) 
     70(define-carbon-event :control-draw-event "cntl" kEventControlDraw) 
     71(define-carbon-event :control-bounds-changed-event "cntl" kEventControlBoundsChanged) 
     72}}} 
     73 
     74Unlike the above, this is actually the complete set of predefined Carbon command ids: 
     75{{{ 
     76(define-carbon-command-event :ok-command-event "ok") 
     77(define-carbon-command-event :cancel-command-event "not!") 
     78(define-carbon-command-event :quit-command-event "quit") 
     79(define-carbon-command-event :undo-command-event "undo") 
     80(define-carbon-command-event :redo-command-event "redo") 
     81(define-carbon-command-event :cut-command-event "cut ") 
     82(define-carbon-command-event :copy-command-event "copy") 
     83(define-carbon-command-event :paste-command-event "past") 
     84(define-carbon-command-event :clear-command-event "clea") 
     85(define-carbon-command-event :select-all-command-event "sall") 
     86(define-carbon-command-event :hide-command-event "hide") 
     87(define-carbon-command-event :hide-others-command-event "hido") 
     88(define-carbon-command-event :show-all-command-event "shal") 
     89(define-carbon-command-event :preferences-command-event "pref") 
     90(define-carbon-command-event :zoom-window-command-event "zoom") 
     91(define-carbon-command-event :minimize-window-command-event "mini") 
     92(define-carbon-command-event :minimize-all-command-event "mina") 
     93(define-carbon-command-event :maximize-window-command-event "maxi") 
     94(define-carbon-command-event :maximize-all-command-event "maxa") 
     95(define-carbon-command-event :arrange-in-front-command-event "frnt") 
     96(define-carbon-command-event :bring-all-to-front-command-event "bfrt") 
     97(define-carbon-command-event :window-list-separator-command-event "wldv") 
     98(define-carbon-command-event :window-list-terminator-command-event "wlst") 
     99(define-carbon-command-event :select-window-command-event "swin") 
     100(define-carbon-command-event :rotate-windows-forward-command-event "rotw") 
     101(define-carbon-command-event :rotate-windows-backward-command-event "rotb") 
     102(define-carbon-command-event :rotate-floating-windows-forward-command-event "rtfw") 
     103(define-carbon-command-event :rotate-floating-windows-backward-command-event "rtfb") 
     104(define-carbon-command-event :about-command-event "abou") 
     105(define-carbon-command-event :new-command-event "new ") 
     106(define-carbon-command-event :open-command-event "open") 
     107(define-carbon-command-event :close-command-event "clos") 
     108(define-carbon-command-event :save-command-event "save") 
     109(define-carbon-command-event :save-as-command-event "svas") 
     110(define-carbon-command-event :revert-command-event "rvrt") 
     111(define-carbon-command-event :print-command-event "prnt") 
     112(define-carbon-command-event :page-setup-command-event "page") 
     113(define-carbon-command-event :app-help-command-event "ahlp") 
     114(define-carbon-command-event :show-character-palette-command-event "chrp") 
     115(define-carbon-command-event :show-spelling-panel-command-event "shsp") 
     116(define-carbon-command-event :check-spelling-command-event "cksp") 
     117(define-carbon-command-event :change-spelling-command-event "chsp") 
     118(define-carbon-command-event :check-spelling-as-you-type-command-event "chsp") 
     119(define-carbon-command-event :ignore-spelling-command-event "igsp") 
     120(define-carbon-command-event :learn-word-command-event "lrwd") 
     121}}}