From ff91597716189688f314e5ffe4ba0cb8b92a7c56 Mon Sep 17 00:00:00 2001
From: Colin Okay <colin@cicadas.surf>
Date: Sat, 9 Jul 2022 09:15:20 -0500
Subject: [doc] added stuff about event handling

---
 README.org | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/README.org b/README.org
index ba9af16..a25d704 100644
--- a/README.org
+++ b/README.org
@@ -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 
-- 
cgit v1.2.3