diff --git a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-event.xml b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-event.xml
index 1e542f6b..11871205 100644
--- a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-event.xml
+++ b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-event.xml
@@ -4,8 +4,67 @@
id="bcc3c7a6-df1c-4dc8-8263-2364630db64a"
title="Events">
-
- An event...
-
+
+
+ Events
+ are the primary means by which the
+ jsycamore
+ package accepts input from external code, and by which it publishes notifications on state changes.
+
+
+ Events are divided into input events and
+ output events.
+
+
+
+
+
+
+ Input events
+ are events that represent input to the UI. In order to remain fully platform-independent, the
+ jsycamore
+ package does not directly read from the keyboard and mouse. Instead, users are expected to be running
+ jsycamore
+ inside an existing system such as
+ AWT, or perhaps
+ embedded in a GPU context via
+ GLFW, and are therefore responsible for translating
+ input events coming from those systems into method calls defined on the
+ SyScreenMouseEventsType
+ and
+ SyScreenKeyEventsType
+ interfaces. When these methods are called, the screen will
+ dispatch
+ input events internally to any relevant
+ components.
+
+
+
+
+
+ Mouse events...
+
+
+
+
+
+ Keyboard events...
+
+
+
+
+
+
+ Output events
+ are events that indicate state changes that have occurred. For example, closing a window will publish
+ an event.
+
+
+ Users may obtain access to a stream of output events from each
+ screen.
+
+
diff --git a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-screen.xml b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-screen.xml
index b19bb6b3..e4b06ab8 100644
--- a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-screen.xml
+++ b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-screen.xml
@@ -57,14 +57,85 @@
-
-
- A screen provides an
-
- observable stream of events
- to which external code may subscribe.
-
+
+
+
+ A screen provides an
+
+ observable stream of output events
+ to which external code may subscribe.
+
+
+
+
+
+ When any of the methods on the
+ SyScreenMouseEventsType
+ and
+ SyScreenKeyEventsType
+ interfaces are called, the screen will dispatch appropriate events to
+ components
+ inside
+ windows
+ that are visible on the screen.
+
+
+
+
+ When dispatching mouse events, the process
+ is as follows for an arbitrary mouse event e:
+
+
+
+
+ Get a list of the visible windows in
+ order such that the frontmost windows
+ are at the start of the list, and the rearmost windows are at the end of the list.
+
+
+ For each window w in the list of visible windows:
+
+
+ If the viewport-space position
+ of the mouse event (the cursor position) falls within the viewport-space bounds of
+ w, then ask w for the
+ component
+ c that is overlapped by the cursor. The window implementation
+ is required to return the most specific component for the given position; the component that
+ is deepest within the tree of components for the given position. If there is no
+ appropriate c, then continue on to the next window.
+
+
+ Assuming there was an existing component c,
+ call the eventSend method on c, passing
+ it the event e. The method will return a value that indicates
+ whether the component consumed the event. If the event was consumed,
+ execution stops here. Otherwise, if the event was not consumed, then the
+ eventSend method is called on each recursively selected ancestor
+ of c until either one of the ancestors consumes the event, or
+ there are no more ancestors. If the event is consumed, execution stops here. If there are
+ no more ancestors, we return to the first step and try the next visible window.
+
+
+ If no component in any of the examined windows consumes e, then
+ e is discarded.
+
+
+
+
+
+
+ Typically, successfully dispatching a mouse event to a window will result in that window
+ becoming focused.
+
+
+
+
+ Keyboard events...
+
+
+
diff --git a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-window.xml b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-window.xml
index 0f33d31d..d9b2ef20 100644
--- a/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-window.xml
+++ b/com.io7m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-window.xml
@@ -143,7 +143,7 @@
-
+
When a window is closed, an event of type SyWindowClosed will be published.