/** \page dw-size-request-pos Size requisitions depending on positions

<div style="border: 2px solid #ffff00; margin: 1em 0;
  padding: 0.5em 1em; background-color: #ffffe0">The complex "widget
  sizes" is currently divided into three documents: \ref
  dw-widget-sizes, \ref dw-grows, and **Size requisitions depending on
  positions** (this document).</div>

<div style="border: 2px solid #ff4040; margin: 1em 0;
  padding: 0.5em 1em; background-color: #fff0f0"><b>Info:</b>
  May not be up to date, needs a review.</div>

Motivation
==========

As described in \ref dw-out-of-flow (*The sizeRequest/sizeAllocate
problem*), the principle that the size of a widget depends only on the
sizes of its children causes some problems with floats; the current
solution is a frequent correction by calling
dw::core::Widget::queueResize. In this document, an alternative
approach is presented.


General Idea
============

A widget size may depend on the position relative to an anchestor
widget. If a widget wants to get the size of a child widget, it should

1. call the new methods dw::core::Widget::numSizeRequestReferences and
   dw::core::Widget::sizeRequestReference, which return all widgets
   relative to which the child's position must be calculated;
2. call dw::core::Widget::sizeRequest with the positions relative to
   these widgets.

<div style="border: 2px solid #ffff00; margin: 1em 0;
  padding: 0.5em 1em; background-color: #ffffe0">It is not sufficient
  to work with *absolute* positions, since there may be an
  interruption passing the positions so that absolute positions are
  often not known.</div>

All positions passed to dw::core::Widget::sizeRequest must constitute
the position at which this child will be allocated.

There are situations where the parent widget is unable to determine
these positions before the size is known. An example: a textblock
widget cannot determine the positions of an inline widget (like an
image, or an inline block) before the line is finished; on the other
hand, finishing the line depends on knowing the sizes of the inline
widgets.

This may result in a conflict, when the size of an inline widget
depends on positions. Generally, the only widget whose size depends on
positions is dw::Textblock (the size will depend on the positions
within its oof container, see \ref dw-out-of-flow), so this conflict
occurs with inline blocks.

This conflict is handled in different ways:

1. Fortunately, this case is irrelevat for floats: an inline blocks
   constitute its own floats container, so that there is no dependance
   on a position within another widget.

2. For positioned elements, this case is relevant, since an inline
   block is in most cases not a container for positioned element. In
   this case, a generator will call the methods
   dw::oof::OutOfFlowMgr::tellIncompletePosition1 and
   dw::oof::OutOfFlowMgr::tellIncompletePosition2, instead of
   dw::oof::OutOfFlowMgr::tellPosition and
   dw::oof::OutOfFlowMgr::tellPosition2, respectively. (Since this
   case is irrelevant for floats,
   dw::oof::OOFFloatsMgr::tellIncompletePosition1 and
   dw::oof::OOFFloatsMgr::tellIncompletePosition2 are not implemented but
   simply abort.)

(This is not (yet) considered for borders: borders are only relevant
for floats, but conflicts do not occur for floats.)


Extremes
--------
Extremes may depend on the position in an analogue way, see:

- dw::core::Widget::numGetExtremesReferences,
- dw::core::Widget::getExtremesReference, and
- dw::core::Widget::getExtremes.

Resizing
--------
Currently, the size of a widget has to be recalculated, when

1. it has called dw::core::Widget::queueResize, or
2. the size of a child widget has to be recalculated.

Since for this new approach, the size does not only depend on the size
of the children, the second condition must be modified. However,
regarding changes of the position is not sufficient. Consider this
example, where a float size changes as soon as the image is loaded:

\image html dw-size-request-pos-01.png

The second paragraph ("A longer paragraph" ...) stays at the same
position, both absolute and relative to the float container, but has
to be rewrapped because of the float.

(TODO: A detailed design is yet to de developed.)


Plan
====

1. General design (dw::core::Widget::sizeRequestReference, changes to
   dw::core::Widget::sizeRequest). Completed.

2. Implementation for dw::Textblock. Completed.

3. Change interface of dw::oof::OutOfFlowMgr (this affects mostly
   only comments). Completed.

   Affects methods dw::oof::OutOfFlowMgr::tellPosition1,
   dw::oof::OutOfFlowMgr::tellPosition2,
   dw::oof::OutOfFlowMgr::getLeftBorder,
   dw::oof::OutOfFlowMgr::getRightBorder,
   dw::oof::OutOfFlowMgr::hasFloatLeft,
   dw::oof::OutOfFlowMgr::hasFloatRight,
   dw::oof::OutOfFlowMgr::getLeftFloatHeight, and
   dw::oof::OutOfFlowMgr::getRightFloatHeight.

4. Apply step 3 to calls within dw::Textblock. Completed.

   <b>Attention:</b> After this step, and before completing the next
   steps, the code is inconsistend and so incorrect.

5. Implement step 3 for floats (affects dw::oof:OOFFloatsMgr). **INCOMPLETE.**

6. Implement step 3 for positioned elements (affects only
   dw::oof:OOFPositionedMgr). **INCOMPLETE.**


Issues
======

- Since the signature of dw::core::Widget::sizeRequestImpl changes
  quite often during the development of *size requisitions depending
  on positions*, a simpler option dw::core::Widget::sizeRequestSimpl
  has been added. May be removed again, after the design is stable.


*/