Improved 'Event propagation' section.

docs/data/diagrams.tex

@@ -204,11 +204,16 @@
 \def\eventpropagationfigure{
     \begin{figure}[h!]
         \center
-        \subfigure[An event is triggered in the white area. The event is first
-        delegated to the white area from te gray area (2). After gesture
-        detection, it is propagated back to the gray area (6) \emph{unless}
-        propagation has been stopped in the rotation detection component
-        between (3) and (4).]{
+        \subfigure[
+            An event is triggered in the white area. The event driver
+            delegates the event to the event area tree (1) and the gray root
+            area delegates it to the white area (2). The white area delegates
+            it to drag tracker for gesture detection (3), which may trigger a
+            gesture in the application (4-5). If propagation has not been
+            stopped by the drag tracker, the event is propagated to the gray
+            event area (6) which also detects drag gestures that may be
+            triggered in the application (7-9).
+        ]{
             \begin{tikzpicture}[node distance=5.5em]
                 \draw node[draw=black, minimum width=190, minimum height=140] (screen) at (0,0) {};
                 \draw node[fill=gray!50, draw=black!70, minimum height=100, minimum width=100] (screen) at (-0.1,-0.1) {};
@@ -221,10 +226,10 @@
                 \draw node[block, below of=gray] (white) {White event area}
                     edge[linefrom, bend left=15] node[left] {2} (gray)
                     edge[lineto, bend right=15] node[right] {6} (gray);
-                \draw node[block, right of=white, xshift=4em] {rotation detection}
+                \draw node[block, right of=white, xshift=4em] {drag tracker}
                     edge[linefrom, bend right=15] node[above] {3} (white)
                     edge[lineto, dotted, bend left=15] node[below] {4} (white);
-                \draw node[block, right of=gray, xshift=4em] {rotation detection}
+                \draw node[block, right of=gray, xshift=4em] {drag tracker}
                     edge[linefrom, bend right=15] node[above] {7} (gray)
                     edge[lineto, dotted, bend left=15] node[below] {8} (gray);
                 \draw node[block, below of=white] {Application}
@@ -233,8 +238,14 @@
             \end{tikzpicture}
         }
         \quad
-        \subfigure[An event is triggered in the gray event area, it does not even
-        reach the white event area.]{
+        \subfigure[
+            An event is triggered in the gray area, but outside the white area.
+            The event driver delegates the event to the gray event area (1).
+            Since the white area does not contain the event, delegation stops
+            and the event is passed on to the drag tracker of the gray event
+            area (2). If a gesture is detected (3), the event area triggers the
+            corresponding handler in the application (4).
+        ]{
             \begin{tikzpicture}[node distance=5.5em]
                 \draw node[draw=black, minimum width=190, minimum height=140] (screen) at (0,0) {};
                 \draw node[fill=gray!50, draw=black!70, minimum height=100, minimum width=100] (screen) at (-0.1,-0.1) {};
@@ -245,8 +256,8 @@
                 \draw node[block, below of=driver] (gray) {Gray event area}
                     edge[linefrom] node[left] {1} (driver);
                 \draw node[block, below of=gray] (white) {White event area};
-                \draw node[block, right of=white, xshift=4em] {rotation detection};
-                \draw node[block, right of=gray, xshift=4em] {rotation detection}
+                \draw node[block, right of=white, xshift=4em] {drag tracker};
+                \draw node[block, right of=gray, xshift=4em] {drag tracker}
                     edge[linefrom, bend right=15] node[above] {2} (gray)
                     edge[lineto, dotted, bend left=15] node[below] {3} (gray);
                 \draw node[block, below of=white] {Application}
@@ -254,11 +265,13 @@
             \end{tikzpicture}
         }
         \caption{
-            Two nested squares both listen to ``tap'' gestures. The two figures
-            both show a touch object triggering an event, represented by a
-            black dot. The event is delegated through the event area tree in
-            the order indicated by the numbered arrow labels. Dotted arrows
-            represent a flow of gestures, regular arrows represent events.
+            Two nested squares both respond to ``drag'' gestures. When the
+            white square is dragged, the gray square stays at its current
+            position. The two figures both show a touch object triggering an
+            event, represented by a black dot. The event is delegated and
+            propagated through the event area tree in the order indicated by
+            the numbered arrow labels.  Dotted arrows represent a flow of
+            gestures, regular arrows represent events.
         }
         \label{fig:eventpropagation}
     \end{figure}

docs/report.tex

@@ -352,9 +352,9 @@ detection for every new gesture-based application.
     \label{sec:eventpropagation}
 
     Another problem occurs when event areas overlap, as shown by figure
-    \ref{fig:eventpropagation}. When the white square is rotated, the gray
-    square should keep its current orientation. This means that events that are
-    used for rotation of the white square, should not be used for rotation of
+    \ref{fig:eventpropagation}. When the white square is dragged, the gray
+    square should stay at its current position. This means that events that are
+    used for dragging of the white square, should not be used for dragging of
     the gray square. The use of event areas alone does not provide a solution
     here, since both the gray and the white event area accept an event that
     occurs within the white square.
@@ -363,24 +363,24 @@ detection for every new gesture-based application.
     there is a common solution (used by GTK \cite{gtkeventpropagation}, among
     others). An event is passed to an ``event handler''. If the handler returns
     \texttt{true}, the event is considered ``handled'' and is not
-    ``propagated'' to other widgets.
-
-    Applied to the example of the rotating squares, the rotation detection
-    component of the white square should stop the propagation of events to the
-    event area of the gray square. This is illustrated in figure
-    \ref{fig:eventpropagation}.
+    ``propagated'' to other widgets. Applied to the example of the draggable
+    squares, the rotation detection component of the white square should stop
+    the propagation of events to the event area of the gray square.
 
     In the example, rotation of the white square has priority over rotation of
     the gray square because the white area is the widget actually being touched
     at the screen surface. In general, events should be delegated to event
     areas according to the order in which the event areas are positioned over
     each other. The tree structure in which event areas are arranged, is an
-    ideal tool to determine the order in which an event is delegated. Event
-    areas in deeper layers of the tree are positioned on top of their parent.
-    An object touching the screen is essentially touching the deepest event
-    area in the tree that contains the triggered event. A gesture detection
-    component can stop the propagation of the event by its corresponding event
-    area.
+    ideal tool to determine the order in which an event is delegated.  An
+    object touching the screen is essentially touching the deepest event area
+    in the tree that contains the triggered event, which must be the first to
+    receive the event. When the gesture trackers of the event area are
+    finished with the event, it is propagated to the siblings and parent in the
+    event area tree. Optionally, a gesture tracker can stop the propagation of
+    the event by its corresponding event area. Figure
+    \ref{fig:eventpropagation} demonstrates event propagation in the example of
+    the draggable squares.
 
     \eventpropagationfigure