UI phases overview

Widgets

In the Widget's perspective, the following methods are called, in this order:

1. dispatchEvent (handleEvent) for every event queued by a Driver.
2. preLayoutUpdate (handlePreLayoutUpdate), even if the layout is not dirty.
3. Assuming the top-most Widget has a dirty layout:
   1. resolveDimensions (handleResolveDimensions). This calculates the ideal dimensions (width and height).
   2. resolvePosition. This calculates the ideal coordinates (X and Y).
   3. finalizeBounds. This rounds ideal dimensions and coordinates to the nearest scale-aligned whole pixels to prevent clipping artifacts.
4. postLayoutUpdate (handlePostLayoutUpdate), even if the layout is not dirty.
5. paint. If the Widget needs to be painted (marked as dirty), then the implementation method (handlePainting) is called, otherwise, the Widget is not painted (and neither are any of its children).

Roots

In the Root's perspective, the following methods are (normally) called, in this order:

1. preLayoutUpdate, which calls update for each Driver attached to the Root, and calls preLayoutUpdate for the top-most Widget.
2. resolveLayout, which calls the resolveDimensions, resolvePosition and finalizeBounds methods of the top-most Widget.
3. postLayoutUpdate, which calls postLayoutUpdate for the top-most Widget.
4. paint, which calls paint for the top-most Widget.

Note that DOMRoot already wraps all of these calls, in this order, in the update method.

Drivers are expected to accumulate events and, when their update method is called, dispatch those events to a relevant Root they are attached to.