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>,
pub a11y: Option<&'a mut A11yTreeBuilder>,
/* private fields */
}Expand description
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: BufferThe cell grid for this render pass.
pool: &'a mut GraphemePoolReference 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: WidgetBudgetWidget 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: boolWhether cursor should be visible.
degradation: DegradationLevelCurrent 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.
a11y: Option<&'a mut A11yTreeBuilder>Accessibility tree builder for this frame, when the runtime collects
one (see Frame::push_a11y). None makes every a11y call a no-op.
Implementations§
Source§impl<'a> Frame<'a>
impl<'a> Frame<'a>
Sourcepub fn new(width: u16, height: u16, pool: &'a mut GraphemePool) -> Self
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.
Sourcepub fn from_buffer(buffer: Buffer, pool: &'a mut GraphemePool) -> Self
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.
Sourcepub fn with_links(
width: u16,
height: u16,
pool: &'a mut GraphemePool,
links: &'a mut LinkRegistry,
) -> Self
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.
Sourcepub fn with_hit_grid(
width: u16,
height: u16,
pool: &'a mut GraphemePool,
) -> Self
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.
Sourcepub fn set_links(&mut self, links: &'a mut LinkRegistry)
pub fn set_links(&mut self, links: &'a mut LinkRegistry)
Set the link registry for this frame.
Sourcepub fn set_arena(&mut self, arena: &'a FrameArena)
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.
Sourcepub fn arena(&self) -> Option<&FrameArena>
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.
Sourcepub fn register_link(&mut self, url: &str) -> u32
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.
Sourcepub fn set_widget_budget(&mut self, budget: WidgetBudget)
pub fn set_widget_budget(&mut self, budget: WidgetBudget)
Set the widget render budget for this frame.
Sourcepub fn should_render_widget(&self, widget_id: u64, essential: bool) -> bool
pub fn should_render_widget(&self, widget_id: u64, essential: bool) -> bool
Check whether a widget should be rendered under the current budget.
Sourcepub fn register_widget_signal(&mut self, signal: WidgetSignal)
pub fn register_widget_signal(&mut self, signal: WidgetSignal)
Register a widget scheduling signal for this frame.
Sourcepub fn widget_signals(&self) -> &[WidgetSignal]
pub fn widget_signals(&self) -> &[WidgetSignal]
Borrow the collected widget signals.
Sourcepub fn take_widget_signals(&mut self) -> Vec<WidgetSignal>
pub fn take_widget_signals(&mut self) -> Vec<WidgetSignal>
Take the collected widget signals, leaving an empty list.
Sourcepub fn intern(&mut self, text: &str) -> GraphemeId
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 exceeds GraphemeId::MAX_WIDTH.
Sourcepub fn intern_with_width(&mut self, text: &str, width: u8) -> GraphemeId
pub fn intern_with_width(&mut self, text: &str, width: u8) -> GraphemeId
Intern a string with explicit width.
Sourcepub fn enable_hit_testing(&mut self)
pub fn enable_hit_testing(&mut self)
Enable hit testing on an existing frame.
Sourcepub fn clear(&mut self)
pub fn clear(&mut self)
Clear frame for next render.
Resets both the buffer and hit grid (if present).
Sourcepub fn set_cursor(&mut self, position: Option<(u16, u16)>)
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.
Sourcepub fn set_cursor_visible(&mut self, visible: bool)
pub fn set_cursor_visible(&mut self, visible: bool)
Set cursor visibility.
Sourcepub fn set_degradation(&mut self, level: DegradationLevel)
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.
Sourcepub fn area(&self) -> Rect
pub fn area(&self) -> Rect
The full drawable area of the frame ((0, 0) to (width, height)).
Same as Frame::bounds; this is the name layout code reads best
(Flex::horizontal().constraints(..).split(frame.area())).
Sourcepub fn register_hit(
&mut self,
rect: Rect,
id: HitId,
region: HitRegion,
data: HitData,
) -> bool
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.
Sourcepub fn with_hit_owner<R>(
&mut self,
owner: HitOwner,
f: impl FnOnce(&mut Self) -> R,
) -> R
pub fn with_hit_owner<R>( &mut self, owner: HitOwner, f: impl FnOnce(&mut Self) -> R, ) -> R
Temporarily attach ownership provenance to hit regions registered in f.
Sourcepub fn a11y_enabled(&self) -> bool
pub fn a11y_enabled(&self) -> bool
Whether an accessibility tree builder is attached to this frame.
Sourcepub fn set_a11y(&mut self, builder: &'a mut A11yTreeBuilder)
pub fn set_a11y(&mut self, builder: &'a mut A11yTreeBuilder)
Attach the builder that collects this frame’s accessibility nodes (the runtime does this once per frame when accessibility is on).
Sourcepub fn push_a11y(&mut self, node: A11yNodeInfo)
pub fn push_a11y(&mut self, node: A11yNodeInfo)
Push one accessibility node. A no-op without a builder.
The node’s parent defaults to the enclosing Frame::with_a11y_scope
container; a parent the widget set itself is kept. Ids must be stable
across frames so the tree can be diffed and changes announced: reuse
a hit id or widget id where one exists, otherwise
A11yNodeInfo::stable_id_for.
Sourcepub fn push_a11y_nodes(&mut self, nodes: impl IntoIterator<Item = A11yNodeInfo>)
pub fn push_a11y_nodes(&mut self, nodes: impl IntoIterator<Item = A11yNodeInfo>)
Push every node a widget reports
(ftui_a11y::Accessible::accessibility_nodes).
Sourcepub fn with_a11y_scope<R>(
&mut self,
container: A11yNodeInfo,
f: impl FnOnce(&mut Self) -> R,
) -> R
pub fn with_a11y_scope<R>( &mut self, container: A11yNodeInfo, f: impl FnOnce(&mut Self) -> R, ) -> R
Push container and make it the parent of every node pushed while
f runs (containers such as Block wrap their children with this).
Without a builder f simply runs.
Sourcepub fn a11y_order(&self) -> &[u64]
pub fn a11y_order(&self) -> &[u64]
Node ids in push (document) order.
Sourcepub fn take_a11y_order(&mut self) -> Vec<u64>
pub fn take_a11y_order(&mut self) -> Vec<u64>
Move the push order out (the runtime keeps it beside the built tree).
Sourcepub fn finish_a11y(&mut self)
pub fn finish_a11y(&mut self)
Apply the collected parent/child links to the builder and, when no root was set, make the first parentless node the root. Call once after the view has rendered and before the tree is built; a no-op without a builder.
Sourcepub fn hit_test(&self, x: u16, y: u16) -> Option<(HitId, HitRegion, HitData)>
pub fn hit_test(&self, x: u16, y: u16) -> Option<(HitId, HitRegion, HitData)>
Hit test at the given position (if hit grid is enabled).
Sourcepub fn hit_test_detailed(&self, x: u16, y: u16) -> Option<HitTestResult>
pub fn hit_test_detailed(&self, x: u16, y: u16) -> Option<HitTestResult>
Hit test at the given position, preserving owner provenance.
Sourcepub fn register_hit_region(&mut self, rect: Rect, id: HitId) -> bool
pub fn register_hit_region(&mut self, rect: Rect, id: HitId) -> bool
Register a hit region with default metadata (Content, data=0).