From 4aaad25c02c68130a8704b07f9544282c6f3e692 Mon Sep 17 00:00:00 2001
From: Pietro Gagliardi <pietro10@mac.com>
Date: Tue, 7 May 2019 23:05:31 -0400
Subject: [PATCH] Started writing the documentation for the new event handling
 interface. At this point I'm tempted to forego the overview sections for the
 time being, since all the contractual stuff would go in the reference.

---
 doc/00_index.md |  1 +
 doc/events.md   | 55 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 doc/events.md

diff --git a/doc/00_index.md b/doc/00_index.md
index 7f259f04..8a9352d8 100644
--- a/doc/00_index.md
+++ b/doc/00_index.md
@@ -2,3 +2,4 @@
 
 * [Using libui](using-libui.md)
 * [Initialization and the Main Loop](init-main.md)
+* [Event Handling](events.md)
diff --git a/doc/events.md b/doc/events.md
new file mode 100644
index 00000000..cd0137da
--- /dev/null
+++ b/doc/events.md
@@ -0,0 +1,55 @@
+<!-- 7 may 2019 -->
+
+# Event Handling
+
+## Overview
+
+TODO erase this and start over {
+When the user tries to interacts with your program, your program needs a way to be notified of that interaction. This is typically done by sending an *event* to the program that describes what interaction takes place and how. In turn, the operating system can interpret general events (such as "the user has pressed the primary mouse button") and send more specialized ones (such as "the user clicked on this specific checkbox on the screen"). This paragraph is super awkward and I'm not sure what to do about it, because I was about to talk about how events are *queued* and that `uiMain()` reads from that queue in `uiMain()` and since that function does not return through the lifetime of your program you'll need to use callbacks but I feel like a primary school teacher saying things this way.
+
+All events in libui are dispatched through `uiEvent` objects, and you opt into handling an event by adding a handler to a `uiEvent`. Handlers are functions with the following signature:
+}
+
+## Reference
+
+### `uiEvent`
+
+```c
+typedef struct uiEvent uiEvent;
+```
+
+`uiEvent` is an opaque type that describes an event.
+
+### `uiEventHandler`
+
+```c
+typedef void (*uiEventHandler)(uiEvent *event, void *sender, void *args, void *data);
+```
+
+`uiEventHandler` is a pointer to the type of function that all event hanlder functions must take:
+
+```c
+void eventHandler(uiEvent *event, void *sender, void *args, void *data);
+```
+
+`event` is the event that was fired to cuase this function to be called. `sender` is the object that fired this event; this should typically be the object that the event happened to. `args` is data specific to the specific invocation of the event handler that is currently active, if any; consult the documentation for the event you are interested in for info on how to interpret `args`. `data` is the data you specified when registering the given function as an event handler; it is the same for all calls to an event.
+
+### `uiNewEvent()`
+
+```c
+uiEvent *uiNewEvent(void);
+```
+
+`uiNewEvent()` creates a new `uiEvent`.
+
+### `uiEventAddHandler()`
+
+```c
+int uiEventAddHandler(uiEvent *event, uiEventHandler handler, void *sender, void *data);
+```
+
+### `uiEventFire()`
+
+```c
+void uiEventFire(uiEvent *event, void *sender, void *args);
+```