Module _authoring 

Authoring guide: the two public tiers of the UI API.

Authoring GPUI

UI is written at one of two levels: composing the built-in elements into components, or writing a custom element when nothing built in emits what you need. Both levels are public, so code written against them today should keep compiling across minor releases.

Composing components

Most UI is built from div() and the other element constructors, refined with style and interaction builders:

• Styled for layout and appearance: .p_4(), .bg(), .w_full(), and the rest of the utility-style methods.
• InteractiveElement for listeners: .on_click(), .on_mouse_down(), .on_key_down().
• Render and RenderOnce to turn your own types into elements.
• Entity and Context for the state that drives them.

This level composes; it does not draw. Painting is decided by the elements being composed.

Writing custom elements

When nothing built in draws what you need, implement Element. Its lifecycle runs in three phases:

1. Element::request_layout asks the layout engine for a LayoutId, through Window::request_layout or, for leaf content whose size only its own measurements know, Window::request_measured_layout.
2. Element::prepaint runs once the element’s Bounds are known. This is where you register hitboxes with Window::insert_hitbox and stash whatever state painting will need.
3. Element::paint emits the drawing:
   • Window::paint_quad draws a PaintQuad, the same primitive a div() uses for its background, border and corner radii.
   • Window::paint_path draws arbitrary vector geometry, built with PathBuilder into an engine-level Path.
   • Window::paint_drop_shadows and Window::paint_inset_shadows draw BoxShadows, before and after the element’s fill respectively.
   • Window::paint_image draws an image.
   • Window::layout_bounds reads a child’s computed bounds.

None of these name a GPU API or an operating system. Each call appends a record to the frame’s scene, and the engine’s SceneRenderer turns those records into whatever the backend draws, so a custom element keeps working when the renderer is replaced. LayoutId is likewise an opaque token, so a custom element keeps working when the layout engine is replaced.

Compositing pixels produced outside GPUI is the one place a platform-specific payload reaches the window. It goes through gpu_canvas, whose callback receives a GpuCanvasContext: the context’s paint_surface takes a CoreVideo buffer, a Direct3D texture or view, or a dma-buf, and its paint_texture takes a texture made on the window renderer’s own device.

What is not authoring API

Part of Window’s public surface exists for the runtime and for test harnesses rather than for elements:

• Frame orchestration: compute_layout, present_if_needed, damage diffing and draw. draw stays public because the visual test harnesses render frames with it, and is hidden from these docs.
• Element storage: the erased ElementObject, the element arena, and the stack-safety wrapper around it.
• Frame double-buffering and the retained hit-test tree.
• The inspector: the runtime publishes the identity of the element it is laying out or painting, so elements never handle it themselves.

Depend on the authoring surface instead. If something in that list is the only way to express what you need, that is a gap worth reporting.

The rest of Window is runtime API

The remaining methods on Window are public on purpose, and they are not authoring API: window management, input, focus, event subscriptions, element state and assets. Whether a component or an element needs them is a judgement each call site makes, so they are neither hidden here nor treated as a frozen contract.