Struct Frame 

pub struct Frame<'a> {
    pub buffer: Buffer,
    pub pool: &'a mut GraphemePool,
    pub links: Option<&'a mut LinkRegistry>,
    pub hit_grid: Option<HitGrid>,
    pub widget_budget: WidgetBudget,
    pub widget_signals: Vec<WidgetSignal>,
    pub cursor_position: Option<(u16, u16)>,
    pub cursor_visible: bool,
    pub degradation: DegradationLevel,
    pub arena: Option<&'a FrameArena>,
}

Frame = Buffer + metadata for a render pass.

The Frame is passed to Model::view() and contains everything needed to render a single frame. The Buffer holds cells; metadata controls cursor and enables mouse hit testing.

Lifetime

The frame borrows the GraphemePool from the runtime, so it cannot outlive the render pass. This is correct because frames are ephemeral render targets.

Fields

buffer: Buffer

The cell grid for this render pass.

pool: &'a mut GraphemePool

Reference to the grapheme pool for interning strings.

links: Option<&'a mut LinkRegistry>

Optional reference to link registry for hyperlinks.

hit_grid: Option<HitGrid>

Optional hit grid for mouse hit testing.

When Some, widgets can register clickable regions.

widget_budget: WidgetBudget

Widget render budget policy for this frame.

widget_signals: Vec<WidgetSignal>

Collected per-widget scheduling signals for this frame.

cursor_position: Option<(u16, u16)>

Cursor position (if app wants to show cursor).

Coordinates are relative to buffer (0-indexed).

cursor_visible: bool

Whether cursor should be visible.

degradation: DegradationLevel

Current degradation level from the render budget.

Widgets can read this to skip expensive operations when the budget is constrained (e.g., use ASCII borders instead of Unicode, skip decorative rendering, etc.).

arena: Option<&'a FrameArena>

Optional per-frame bump arena for temporary allocations.

When set, widgets can use this arena for scratch allocations that only live for the current frame (e.g., formatted strings, temporary slices). The arena is reset at frame boundaries, eliminating allocator churn on the hot render path.

Implementations

impl<'a> Frame<'a>

pub fn new(width: u16, height: u16, pool: &'a mut GraphemePool) -> Self

Create a new frame with given dimensions and grapheme pool.

The frame starts with no hit grid and visible cursor at no position.

pub fn from_buffer(buffer: Buffer, pool: &'a mut GraphemePool) -> Self

Create a frame from an existing buffer.

This avoids per-frame buffer allocation when callers reuse buffers.

pub fn with_links( width: u16, height: u16, pool: &'a mut GraphemePool, links: &'a mut LinkRegistry, ) -> Self

Create a new frame with grapheme pool and link registry.

This avoids double-borrowing issues when both pool and links come from the same parent struct.

pub fn with_hit_grid( width: u16, height: u16, pool: &'a mut GraphemePool, ) -> Self

Create a frame with hit testing enabled.

The hit grid allows widgets to register clickable regions.

pub fn set_links(&mut self, links: &'a mut LinkRegistry)

Set the link registry for this frame.

pub fn set_arena(&mut self, arena: &'a FrameArena)

Set the per-frame bump arena for temporary allocations.

Widgets can access the arena via arena() to perform scratch allocations that only live for the current frame.

pub fn arena(&self) -> Option<&FrameArena>

Returns the per-frame bump arena, if set.

Widgets should use this for temporary allocations (formatted strings, scratch slices) to avoid per-frame allocator churn.

pub fn register_link(&mut self, url: &str) -> u32

Register a hyperlink URL and return its ID.

Returns 0 if link registry is not available or full.

pub fn set_widget_budget(&mut self, budget: WidgetBudget)

Set the widget render budget for this frame.

pub fn should_render_widget(&self, widget_id: u64, essential: bool) -> bool

Check whether a widget should be rendered under the current budget.

pub fn register_widget_signal(&mut self, signal: WidgetSignal)

Register a widget scheduling signal for this frame.

pub fn widget_signals(&self) -> &[WidgetSignal]

Borrow the collected widget signals.

pub fn take_widget_signals(&mut self) -> Vec<WidgetSignal>

Take the collected widget signals, leaving an empty list.

pub fn intern(&mut self, text: &str) -> GraphemeId

Intern a string in the grapheme pool.

Returns a GraphemeId that can be used to create a Cell. The width is calculated automatically or can be provided if already known.

Panics

Panics if width > 127.

pub fn intern_with_width(&mut self, text: &str, width: u8) -> GraphemeId

Intern a string with explicit width.

pub fn enable_hit_testing(&mut self)

Enable hit testing on an existing frame.

pub fn width(&self) -> u16

Frame width in cells.

pub fn height(&self) -> u16

Frame height in cells.

pub fn clear(&mut self)

Clear frame for next render.

Resets both the buffer and hit grid (if present).

pub fn set_cursor(&mut self, position: Option<(u16, u16)>)

Set cursor position.

Pass None to indicate no cursor should be shown at a specific position.

pub fn set_cursor_visible(&mut self, visible: bool)

Set cursor visibility.

pub fn set_degradation(&mut self, level: DegradationLevel)

Set the degradation level for this frame.

Propagates to the buffer so widgets can read buf.degradation during rendering without needing access to the full Frame.

pub fn bounds(&self) -> Rect

Get the bounding rectangle of the frame.

pub fn register_hit( &mut self, rect: Rect, id: HitId, region: HitRegion, data: HitData, ) -> bool

Register a hit region (if hit grid is enabled).

Returns true if the region was registered, false if no hit grid.

Clipping

The region is intersected with the current scissor stack of the internal buffer. Parts of the region outside the scissor are ignored.

pub fn hit_test(&self, x: u16, y: u16) -> Option<(HitId, HitRegion, HitData)>

Hit test at the given position (if hit grid is enabled).

pub fn register_hit_region(&mut self, rect: Rect, id: HitId) -> bool

Register a hit region with default metadata (Content, data=0).

Trait Implementations

impl<'a> Debug for Frame<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Draw for Frame<'a>

fn draw_horizontal_line(&mut self, x: u16, y: u16, width: u16, cell: Cell)

Draw a horizontal line of cells.

fn draw_vertical_line(&mut self, x: u16, y: u16, height: u16, cell: Cell)

Draw a vertical line of cells.

fn draw_rect_filled(&mut self, rect: Rect, cell: Cell)

Draw a filled rectangle.

fn draw_rect_outline(&mut self, rect: Rect, cell: Cell)

Draw a rectangle outline using a single cell character.

fn print_text(&mut self, x: u16, y: u16, text: &str, base_cell: Cell) -> u16

Print text at the given coordinates using the cell’s colors/attrs.

fn print_text_clipped( &mut self, x: u16, y: u16, text: &str, base_cell: Cell, max_x: u16, ) -> u16

Print text with a right-side clipping boundary.

fn draw_border(&mut self, rect: Rect, chars: BorderChars, base_cell: Cell)

Draw a border around a rectangle using the given characters.

fn draw_box( &mut self, rect: Rect, chars: BorderChars, border_cell: Cell, fill_cell: Cell, )

Draw a border and fill the interior.

fn paint_area( &mut self, rect: Rect, fg: Option<PackedRgba>, bg: Option<PackedRgba>, )

Set all cells in a rectangular area to the given fg/bg/attrs without changing cell content.