Frame and PresShell

Two layout primitives appear across nearly every layout-related code path.

PresShell

A PresShell (layout/base/PresShell.h) is the per-document presentation shell. It owns:

• The viewport size and zoom.
• The PresContext (style and font cache for this document).
• The frame tree root.
• Event dispatch for mouse/touch/keyboard.
• Reflow scheduling.
• Focus and selection state.
• Painting orchestration.

Each Document has zero or one PresShell. A document loaded but not displayed (e.g., a service-worker importScripts) has no PresShell.

nsIFrame

A frame (layout/generic/nsIFrame.h) is Gecko's name for what other engines call a "render box" or "layout object": the unit of CSS box-model computation. Each frame:

• Has a parent and zero or more children (forming the frame tree).
• Holds a reference to the styled DOM content (nsIContent*).
• Has computed style (ComputedStyle*).
• Implements Reflow(...), BuildDisplayList(...), HitTest(...), …
• Has a frame type identifier (mozilla::LayoutFrameType::Block, Inline, Flex, Grid, …).

Frames live in the per-document arena (PresArena) and are destroyed when the frame tree is rebuilt.

Frame classes

A non-exhaustive list:

Class	Use
nsBlockFrame	Block-formatting context
nsInlineFrame	Inline boxes
nsTextFrame	Text run
nsFlexContainerFrame	Flexbox container
nsGridContainerFrame	Grid container
nsTableFrame, nsTableCellFrame, nsTableRowFrame	Tables
nsImageFrame	<img>
nsHTMLCanvasFrame	<canvas>
nsVideoFrame	<video>
nsPlaceholderFrame	Anchor for absolutely-positioned descendants
nsContainerFrame	Generic container base

Construction and destruction

The nsCSSFrameConstructor builds frames from styled DOM. Mutations to the DOM cause frame reconstruction (which can be expensive); many DOM mutations only invalidate without rebuilding.

Related

• Layout
• DOM