diff options
| -rw-r--r-- | README.org | 51 |
1 files changed, 51 insertions, 0 deletions
@@ -203,6 +203,57 @@ Frame events See the documentation for the ~on-*~ forms for these events to get a sense of how to handle them. +**** Defining event handlers + +Event handlers can be defined with ~ww:defhandler~ and ~ww:on-EVENTTYPE~ macros. For example in, + +#+begin_src lisp + +(ww::defhandler thing-clicked + (ww::on-mousedown (target x y) + (format t "~a was clicked at ~a,~a!~%" target x y))) +#+end_src + +The ~on-mousedown~ form creates the event handler, and the ~defhandler~ form assigns it to a name in the function namespace. It has been written this way to allow you to redefine ~thing-clicked~ while your application is running in order to experiment with handlers - i.e. in order to support interactive development. + +Another reason that the ~defhandler~ form is separate from the ~on-EVENTNAME~ forms is that each of the ~on-*~ forms accept different arguments, all optional, depending on the event they are handling. + +For example, ~on-mousedown~ is a macro. The above could have been written + +#+begin_src lisp +(ww::defhandler thing-clicked + ;; lambda list variable names are all optional. + (ww::on-mousedown () + (format t "~a was clicked at ~a,~a!~%" target x y))) +#+end_src + +Or it could hav been written + +#+begin_src lisp +(ww::defhandler thing-clicked + ;; lambda list variable names are all optional. + (ww::on-mousedown (my-unit my-x my-y) + (format t "~a was clicked at ~a,~a!~%" my-unit my-x my-y))) +#+end_src + +See the docstrings for each ~on-*~ form for specifics. + +The upshot is, if you are using SLIME, you will get hints about what arguments your handler code expects. + +**** Handling Events + +To get an object (either a unit or the application itself) to handle an event, you add a handler to that object. Handlers know what event they are meant to handle, so you just need to call: + +: (ww:add-handler my-unit my-handler) + +Where ~my-handler~ is either an ~event-handler~ instance. + +Likewise you can drop an event handler + +: (ww:remove-handler my-unit handler-or-event-type) + +If ~handler-or-event-type~ is an event handler instance, it is removed if present. If ~handler-or-event-type~ is symbol whose ~symbol-name~ is the name of an event (e.g. ~:mousedown~ or ~'perframe~), then all handlers of that type are removed from the unit. + *** The Asset Protocol |