Handling stacking contexts

Stacking Context and dw::core::StackingContextMgr

For the definition of stacking contexts, see CSS 2.1 specification,

• section 9.9.1: Specifying the stack level: the 'z-index' property and
• appendix E.

A widget establishes a stacking context when it is positioned and its style value of z-index is different from auto (see dw::core::StackingContextMgr::isEstablishingStackingContext). In this case, it is assigned an instance of dw::core::StackingContextMgr, which has also access to the widgets establishing the child contexts.

Stacking Order

The stacking order influences

1. the order in which child widgets are drawn (dw::core::Widget::draw), and
2. the order in which mouse events are dispatched to child widgets (dw::core::Widget::getWidgetAtPoint).

The first is done from bottom to top, the latter from top to bottom.

I'm here referring to the simplified description in section 9.9.1. The table shows a recommended order for the implementations of dw::core::Widget::draw and dw::core::Widget::getWidgetAtPoint (for the latter, read from bottom to top):

CSS specification	Drawing	Mouse events
1. the background and borders of the element forming the stacking context.	dw::core::Widget::drawBox	Nothing necessary.
2. the child stacking contexts with negative stack levels (most negative first).	dw::core::StackingContextMgr::drawBottom (when defined)	dw::core::StackingContextMgr::getBottomWidgetAtPoint (when defined)
3. the in-flow, non-inline-level, non-positioned descendants.	When (i) widget specific content is drawn, then (ii) dw::oof::OOFAwareWidget::drawOOF is called, this will have this effect: all in-flow elements are drawn, floats are drawn and positioned elements with z-index: auto are drawn (latter two done by dw::oof::OOFAwareWidget::drawOOF, in this order). This order differs from the specified order, but since floats and in-flow elements do not overlap, this difference has no effect. Drawing in-line elements, floats and positioned elements with z-index: auto and should avoid duplicate calls: Widgets drawn by dw::core::StackingContextMgr::drawBottom and by dw::core::StackingContextMgr::drawTop should be excluded here. This can be tested with dw::core::StackingContextMgr::handledByStackingContextMgr.	Likewise, the implementation should (i) test dw::oof::OOFAwareWidget::getWidgetOOFAtPoint, and (ii) search through the chilren. Also, duplicate calls should be avoided using dw::core::StackingContextMgr::handledByStackingContextMgr. There are already the implementations dw::core::Widget::getWidgetAtPoint (ignoring dw::oof::OutOfFlowMgr) and dw::oof::OOFAwareWidget::getWidgetAtPoint (including dw::oof::OutOfFlowMgr).
4. the non-positioned floats.
5. the in-flow, inline-level, non-positioned descendants, including inline tables and inline blocks.
(What about positioned elements with z-index: auto? Seems to be missing in section 9.9.1, but mentioned in appendix E, item 8.
6. the child stacking contexts with stack level 0 and the positioned descendants with stack level 0.	dw::core::StackingContextMgr::drawTop (when defined)	dw::core::StackingContextMgr::getTopWidgetAtPoint (when defined)
7. the child stacking contexts with positive stack levels (least positive first).

Note: This is not quite in conformance with the specification: this description refers to any widget, not only widgets establishing a stacking context. Does this make a difference?