/** \page dw-out-of-flow-floats Handling Elements Out Of Flow: Floats (Note: Bases on work at , I plan to split the documentation on elements out of flow into different parts: general part, floats, positioned elements. In this document, informations about floats are collected.) GB lists and CB lists ===================== Floats generated by a block which is not yet allocated are initially put into a list related to the *generator*: - dw::OutOfFlowMgr::TBInfo::leftFloatsGB or - dw::OutOfFlowMgr::TBInfo::rightFloatsGB. These lists are also called GB lists. Floats of allocated generators are put into lists related to the *container* (called CB lists): - dw::OutOfFlowMgr::leftFloatsCB or - dw::OutOfFlowMgr::rightFloatsCB. As soon as the container is allocated, all floats are moved from the GB lists to the CB lists (dw::OutOfFlowMgr::sizeAllocateStart → dw::OutOfFlowMgr::moveFromGBToCB). Here, it is important to preserve the *generation order* (for reasons, see below: *Sorting floats*), i. e. the order in which floats have been added (dw::OutOfFlowMgr::addWidgetOOF). This may become a bit more complicated in a case like this:

float 1

float 2

float 3

The floats are generated in this order: - \#fl-1 (generated by \#bl-1), - \#fl-2 (generated by \#bl-2), - \#fl-3 (generated by \#bl-1). Since the floats must be moved into the CB list in this order, it becomes clear that the floats from one GB list cannot be moved at once. For this reason, each float is assigned a "mark", which is different from the last one as soon as the generator is *before* the generator of the float added before. In the example above, there are three generators: body, \#bl-1, and \#bl-2 (in this order), and floats are assigned these marks: - \#fl-1: 0, - \#fl-2: also 0, - \#fl-3 is assigned 1, since its generator (\#bl-1) lies before the last generator (\#bl-2). dw::OutOfFlowMgr::moveFromGBToCB will then iterate over all marks, so that the generation order is preserved. Sorting floats ============== Floats are sorted, to make binary search possible, in these lists: - for each generator: dw::OutOfFlowMgr::TBInfo::leftFloatsGB and dw::OutOfFlowMgr::TBInfo::rightFloatsGB; - for the container: dw::OutOfFlowMgr::leftFloatsCB and dw::OutOfFlowMgr::rightFloatsCB. The other two lists, dw::OutOfFlowMgr::leftFloatsAll and dw::OutOfFlowMgr::rightFloatsAll are not sorted at all. New floats are always added to the end of either list; this order is called *generation order*. See also above: *GB lists and CB lists*. On the other hand, there are different sorting criteria, implemented by different comparators, so that different kinds of keys may be used for searching. These sorting criteria are equivalent to the generation order. dw::OutOfFlowMgr::Float::CompareSideSpanningIndex compares *sideSpanningIndex* (used to compare floats to those on the respective other side); if you look at the definition (dw::OutOfFlowMgr::addWidgetOOF) it becomes clear that this order is equivalent to the generation order. dw::OutOfFlowMgr::Float::CompareGBAndExtIndex compares *externalIndex* for floats with same generators, otherwise: (i) if one generator (T1) is a direct anchestor of the other generator (T2), the child of T1, which is an anchestor of, or identical to, T2 is compared to the float generated by T1, using *externalIndex*, as in this example: T1 -+-> child --> ... -> T2 -> Float `-> Float Otherwise, the two blocks are compared, according to their position in dw::OutOfFlowMgr::tbInfos: common anchestor -+-> ... --> T1 -> Float `-> ... --> T2 -> Float This is equivalent to the generation order, as long it is ensured that *externalIndex* reflects the generation order within a generating block, for both floats and child blocks. dw::OutOfFlowMgr::Float::ComparePosition ... */