Interrupted drawing: cleanups, comments, documentation.

2 files changed, 43 insertions, 6 deletions

diff --git a/doc/dw-interrupted-drawing.doc b/doc/dw-interrupted-drawing.doc
index b9a7692f..cb84ec8b 100644
--- a/doc/dw-interrupted-drawing.doc
+++ b/doc/dw-interrupted-drawing.doc
@@ -62,7 +62,7 @@ digraph G {
 The drawing order of the four elements (represented by widgets) is:
 
 - body,
-- #sc-1 (background and text),
+- #sc-1,
 - #fl-1,
 - #sc-2.
 
@@ -73,12 +73,11 @@ Since
 3. a widget can only draw its descendants (not neccessary children,
    but drawing siblings is not allowed),
 
-#sc-2 cannot be drawn as a whole; instead drawing is **interrupted**
+#sc-1 cannot be drawn as a whole; instead drawing is **interrupted**
 by #fl-1. This means:
 
 1. the background and text of #sc-1 is drawn;
-2. drawing of #sc-1 is **interrupted** by #fl-1, which means that its
-   parent, the body, draws #fl-1;
+2. drawing of #sc-1 is **interrupted** by #fl-1 (see below for details),
 3. drawing of #sc-1 is **continued**, by drawing #sc-2.
 
 The exact control flow is described in this sequence diagram:
@@ -89,11 +88,24 @@ The exact control flow is described in this sequence diagram:
 When is drawing interrupted?
 ============================
 
-...
+A widget holding references to widgets out of flow (which are not
+necessary children) draws them as interruption if ... TODO. See
+dw::oof::OOFAwareWidget::doesWidgetOOFInterruptDrawing.
+
 
 How does interruption of drawing work?
 ======================================
 
-...
+When a widget detects that an other widget should be drawn as
+interruption (se above), it calls dw::core::Widget::drawInterruption,
+which
+
+1. draws the widget within another "context" (area and reference
+   widget); for this the original drawing area
+   (dw::core::DrawingContext::getToplevelArea) is used.
+2. Using dw::core::DrawingContext::addWidgetDrawnAsInterruption, and
+   checking later with
+   dw::core::DrawingContext::hasWidgetBeenDrawnAsInterruption prevents
+   these widgets from being drawn twice.
 
 */
diff --git a/doc/dw-miscellaneous.doc b/doc/dw-miscellaneous.doc
index a19b1fd6..596f4ce5 100644
--- a/doc/dw-miscellaneous.doc
+++ b/doc/dw-miscellaneous.doc
@@ -12,10 +12,35 @@ Widget allocation outside of parent allocation
 A widget allocation outside of the allocation of the parent is
 allowed, but the part outside is not visible.
 
+Which widgets may be drawn?
+-------------------
+
+All drawing starts with the toplevel widget
+(cf. dw::core::Widget::queueDrawArea, dw::core::Layout::queueDraw, and
+dw::core::Layout::expose), and a widget has to draw its children, in a
+way consistent with their stacking order.
+
+There are two exceptions:
+
+1. Direct descendants, which are not children, may be drawn, if the
+   parent can distinguish them and so omit drawing them a second
+   time. See dw::core::StackingContextMgr and \ref dw-stacking-context.
+   Parents should not draw children in flow for which
+   dw::core::StackingContextMgr::handledByStackingContextMgr returns
+   true.
+2. Interrupted drawing: via dw::core::Widget::drawInterruption; see
+   \ref dw-interrupted-drawing.
+
+Similar rules apply to handling mouse events
+(dw::core::Widget::getWidgetAtPoint).
+
 Interrupted drawing
 -------------------
 \ref dw-interrupted-drawing.
 
+Similar rules apply to handling mouse events
+(dw::core::Widget::getWidgetAtPoint).
+
 
 Floats
 ======