Documentation for the new event handling.

The documentation contains some ideas, not all is cast in stone yet. And
the code supporting the ideas hasn't been born yet.

src/gui/auxiliary/event/dispatcher.cpp

@@ -155,3 +155,158 @@ void tdispatcher::fire(const tevent event, const tpoint& coordinate)
 
 } // namespace gui2
 
+/**
+ * @page event_dispatching Event dispatching.
+ *
+ * @section introduction Introduction
+ *
+ * This page describes how the new event handling system works, since the
+ * system is still work in progress it might be out of date with the actual
+ * code. It also contains some ideas that might change later on. Some parts are
+ * explained in the interface and will be integrated in this document later.
+ *
+ * Since the event handling code hasn't been cast in stone yet some scenarios
+ * for solving the problem are discussed first and then the solution that is
+ * chosen in more detail.
+ *
+ * @section handling_solution The implementation solutions.
+ *
+ * For the event handling we use a few use case scenarios and show the possible
+ * solutions. 
+ *
+ * @subsection sample The sample window
+ *
+ * In our samples we use this sample window with the following components; a
+ * window W, a container C and a button B. These are arranged accordingly.
+ *
+ * @code
+ *  
+ *   --------------------- 
+ *  |W                     |
+ *  |                      |
+ *  |  -----------------   |
+ *  | |C              |^|  |
+ *  | |               |-|  |
+ *  | |  ----------   |#|  |
+ *  | | |B         |  | |  | 
+ *  | |  ----------   | |  |
+ *  | |               |-|  |
+ *  | |               |v|  |
+ *  |  -----------------   |
+ *  |                      |
+ *   ---------------------
+ *
+ * @endcode
+ *
+ * @subsection scenarios Possible scenarios
+ * 
+ * The scenarios are:
+ * * An event that is wanted by none.
+ * * A mouse down event that should focus C and set the pressed state in B.
+ * * A mouse wheel event, which first should be offered to B and if not handled
+ *   by B should be handled by C.
+ *
+ * @subsection all_queues Pass the event through all queues
+ *
+ * In this solution the event will be passed through all possible queues and
+ * tries sees where the event sticks. This following sections describe how the
+ * events are tried for this usage scenario.
+ *
+ * @subsubsection unhandled Unhandled event
+ *
+ * * W pre child
+ * * C pre child
+ * * B pre child
+ * * W child
+ * * C child
+ * * B child
+ * * W post child
+ * * C post child
+ * * B post child
+ *
+ * @subsubsection mouse_down Mouse down
+ *
+ * * W pre child
+ * * C pre child -> set focus -> !handled
+ * * B pre child -> set pressed state -> handled
+ *
+ * @subsubsection mouse_wheel Mouse wheel
+ *
+ * * W pre child
+ * * C pre child
+ * * B pre child -> We can't scroll so ignore
+ * * W child
+ * * C child
+ * * B child
+ * * W post child
+ * * C post child -> Scroll -> handled
+ *
+ * @subsection chain Pass the events in a chain like fashion
+ *
+ * In this solution the events are send to the pre- and post queue of all but
+ * the last possible widget and to the child of the last widget. The pre queue
+ * will be send from top to bottom, the post queue from bottom to top.
+ *
+ * @subsubsection unhandled Unhandled event
+ *
+ * * W pre child
+ * * C pre child
+ * * B child
+ * * C post child
+ * * W post child
+ *
+ * @subsubsection mouse_down Mouse down
+ *
+ * * W pre child
+ * * C pre child -> set focus -> !handled
+ * * B child -> set pressed state -> handled
+ *
+ * @subsubsection mouse_wheel Mouse wheel
+ *
+ * * W pre child
+ * * C pre child
+ * * B child -> We can't scroll so ignore
+ * * W post child
+ * * C post child -> Scroll -> handled
+ *
+ * @section evaluation Evaluation
+ *
+ * When using the first solution it's possible to drop the child queue since
+ * everything falls in pre or post. But there is a scenario that's a bit ugly
+ * to solve with the first solution:
+ *
+ * Assume there is a listbox with toggle panels and on the panel there are a
+ * few buttons, the wanted behaviour is:
+ * * if clicked on the panel it should toggle, which may or may not be allowed.
+ * * if clicked on a button in the panel, we want to make sure the panel is
+ *   selected, which again may or may not be allowed.
+ *
+ * With solution 2 it's rather easy:
+ *
+ * Click on panel:
+ * * W pre child
+ * * C child -> Test whether we can toggle -> handled, halt = !toggled
+ *
+ * * W pre child
+ * * C pre child -> Test whether we can select -> handled = halt = !selected
+ * * B child -> do button stuff -> handled
+ *
+ * Since for the different clicks, different queues are triggered it's easy to
+ * add a different handler there.
+ *
+ * With solution 1:
+ *
+ * Click on panel:
+ * * W pre child
+ * * C pre child -> handler 1 -> if last in queue -> solution 2 C child
+ * * C pre child -> handler 2 -> if !last in queue -> solution 2 C pre child
+ * * B pre child -> do button stuff -> handled
+ *
+ * Not that different from solution 2, the two handlers are installed in the C
+ * pre event. But we need to manually check whether we're really the last,
+ * which means the code to check whether there are more handlers at a lower
+ * level is needed for both solutions. In solution 1 this test needs to be done
+ * twice versus once in solution 2. Also the fact that the queues for the
+ * events are processed in reverse order on the way back sounds more
+ * initiative.
+ */