setSize

Draw at another size for the rest of the call, and read what the engine measures there.

The drawing surface is resized and every reader of it follows within a frame, so the UI tree is rebuilt from the new size rather than scaled from the old one. That is what makes a second shape a real reading: the branch a layout takes on its aspect ratio, and every absolute number it computes from the short edge, are the ones the new shape produces.

capture { width, height } does not answer the same question. It re-runs layout at the size it encodes, so the shot looks like a render of the other shape — but the widget tree was built a frame earlier from the live size, so its font sizes, padding and orientation branch all belong to the old one.

The call waits until the surface reports the size and returns the reading viewport.size() gives there: the surface in pixels, the logical space a screen is laid out in, and the factor between them.

The size is held for the call that asked for it. When the call ends, however it ends, the surface goes back to the size it had before, so the window or browser canvas a person is looking at is handed back as it was. Measure a layout (ui.getLayoutInfo) or capture it at the new shape in the same execute that sets the size.

The logical UI space is normalised to about 1280 points wide, so a resize to a size of the same aspect moves pixelRatio and leaves ui.screenSize() where it was, while a resize that changes the aspect changes that shape too. Both resize the surface; the second is the one an orientation branch reacts to.

Who honours the size depends on who owns the surface. A headless engine and a browser canvas own theirs and take the size exactly; a browser page that lays its canvas out at a new size meanwhile ends the hold with its own size. Where an OS window owns it, the window manager is asked and has the last word: a tiled or maximized window keeps the size it has. The reading reports what was realized.

A size larger than this device draws is refused at the call, naming the bound; viewport.size().maxExtent reports it.