diff options
| -rw-r--r-- | doc/dw-interrupted-drawing.doc | 24 | ||||
| -rw-r--r-- | doc/dw-miscellaneous.doc | 25 | ||||
| -rw-r--r-- | dw/types.hh | 3 | ||||
| -rw-r--r-- | dw/widget.cc | 17 |
4 files changed, 58 insertions, 11 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 ====== diff --git a/dw/types.hh b/dw/types.hh index 0b2d7a0e..c68ad781 100644 --- a/dw/types.hh +++ b/dw/types.hh @@ -237,6 +237,9 @@ struct Content static void printMask (Type mask); }; +/** + * Set at the top when drawing. See \ref dw-interrupted-drawing for details. + */ class DrawingContext { private: diff --git a/dw/widget.cc b/dw/widget.cc index 2197e6d1..9188f997 100644 --- a/dw/widget.cc +++ b/dw/widget.cc @@ -122,11 +122,13 @@ Widget::~Widget () /** - * \brief Calculates the intersection of widget->allocation and area, returned - * in intersection (in widget coordinates!). + * \brief Calculates the intersection of the visible allocation + * (i. e. the intersection with the visible parent allocation) and + * "area" (in widget coordinates referring to "refWidget"), + * returned in intersection (in widget coordinates). * - * Typically used by containers when drawing their children. Returns whether - * intersection is not empty. + * Typically used by containers when drawing their children (passing + * "this" as "refWidget"). Returns whether intersection is not empty. */ bool Widget::intersects (Widget *refWidget, Rectangle *area, Rectangle *intersection) @@ -141,7 +143,9 @@ bool Widget::intersects (Widget *refWidget, Rectangle *area, intersection->y += refWidget->allocation.y; r = true; - for (Widget *widget = this; r && widget != refWidget->parent; + // "RefWidget" is excluded; it is assumed that "area" its already within + // its allocation. + for (Widget *widget = this; r && widget != refWidget; widget = widget->parent) { assert (widget != NULL); // refWidget must be ancestor. @@ -186,6 +190,9 @@ bool Widget::intersects (Widget *refWidget, Rectangle *area, return r; } +/** + * See \ref dw-interrupted-drawing for details. + */ void Widget::drawInterruption (View *view, Rectangle *area, DrawingContext *context) { |