Module animation 

Thread-local draw-request and invalidation signals.

Two independent channels feed the host’s event loop:

1. Immediate draw request — request_draw / wants_draw. Any widget whose visual output just changed calls request_draw(); the next iteration of the host loop draws a frame and clears the flag. The same call advances invalidation_epoch, letting event dispatch dirty the affected retained ancestor path even when the event bubbles as ignored.

2. Scheduled draw — request_draw_after / take_next_draw_deadline. A widget that needs a draw at a future time (text-cursor blink, tooltip delay) calls request_draw_after(Duration); the host’s loop goes to sleep with ControlFlow::WaitUntil(that_instant) and draws when the deadline fires. Successive calls keep the EARLIEST deadline.

The host loop draws iff wants_draw() || now >= take_next_draw_deadline(). Between draws it idles; no frames are drawn while nothing has changed.

Structs

Tween

Smooth scalar tween between 0.0 and 1.0 (or any pair of values the caller interprets). Drives animations such as the scroll-bar hover expansion and toggle-switch on/off slide.

Functions

async_state_epoch

Current async-state epoch. Backbuffer caches store this and force a re-raster when it doesn’t match.

clear_draw_request

Reset the per-frame draw flags. The App::paint entry point calls this before delegating to the root widget so each frame starts fresh — widgets that still need a draw (animation in flight, focus blink, etc.) must re-arm during their draw, otherwise the loop goes idle.

invalidation_epoch

Monotonic draw-request epoch used to detect visual changes during dispatch.

request_draw

Request that the host schedule another draw as soon as possible.

request_draw_after

Schedule a future draw. Keeps the EARLIEST pending deadline, so multiple widgets asking for different delays will all be served by the soonest one (each widget re-arms its own deadline on the next draw anyway).

request_draw_without_invalidation

Request a frame without advancing invalidation_epoch.

signal_async_state_change

Note that an async-side state change happened (image loader finished, font loaded, etc.). Calls request_draw() so the next frame fires, AND bumps the async_state_epoch so retained backbuffers re-rasterise — without the latter, the freshly-loaded data gets drawn into whatever placeholder rect the previous layout reserved (the markdown SVG-badge “wrong scale on first frame” bug).

take_next_draw_deadline

Read-and-clear the scheduled draw deadline. The host reads this after drawing so the next frame’s scheduled wake is determined entirely by what the fresh draw registered (e.g. a text field re-arms the 500 ms blink each frame while it remains focused; losing focus means no re-arm and the loop goes idle).

wants_draw

Non-destructive read. Hosts call this after drawing to decide control-flow for the next loop iteration.