wijjit.layout.frames.Frame

class wijjit.layout.frames.Frame(width, height, style=None, id=None, style_prefix='frame')[source]

Renders a frame with borders and content.

Parameters:

width (int or str) – Total frame width (including borders). Can be int or string (“fill”, “auto”, “50%”)
height (int or str) – Total frame height (including borders). Can be int or string (“fill”, “auto”, “50%”)
style (FrameStyle, optional) – Frame style configuration
id (str | None)
style_prefix (str)

Variables:

width (int or str) – Total frame width (resolved to int during layout calculation)
height (int or str) – Total frame height (resolved to int during layout calculation)
style (FrameStyle) – Frame style
content (list) – Content lines

__init__(width, height, style=None, id=None, style_prefix='frame')[source]

Initialize scrollable element.

Parameters:

id (str, optional) – Element identifier
classes (str or list of str or set of str, optional) – CSS class names for styling
tab_index (int, optional) – Tab order for focus navigation
width (int | str)
height (int | str)
style (FrameStyle | None)
style_prefix (str)

Return type:

None

Methods

`__init__`(width, height[, style, id, ...])	Initialize scrollable element.
`add_class`(class_name)	Add a CSS class to this element.
`apply_props`(props)	Apply props from a VNode, skipping ephemeral props.
`can_scroll`(direction)	Check if the frame can scroll vertically in the given direction.
`can_scroll_horizontal`(direction)	Check if the frame can scroll horizontally in the given direction.
`get_ephemeral_state`()	Get ephemeral state for reconciliation.
`get_hardware_cursor_position`()	Absolute screen cell where the hardware terminal cursor should park.
`get_height_for_width`(width)	Return the height this element needs when laid out at `width`.
`get_intrinsic_size`()	Get the intrinsic (preferred) size of the element.
`get_scroll_offset`()	Get the current scroll offset for rendering children.
`get_scroll_offset_x`()	Get the current horizontal scroll offset for rendering.
`handle_key`(key)	Handle keyboard input for scrolling.
`handle_mouse`(event)	Handle mouse events (scrolling).
`handle_scroll`(direction)	Handle mouse wheel scrolling.
`handle_scroll_horizontal`(direction)	Handle horizontal scrolling.
`has_class`(class_name)	Check if element has a CSS class.
`on_blur`()	Called when frame loses focus.
`on_focus`()	Called when frame gains focus.
`on_hover_enter`()	Called when mouse enters frame.
`on_hover_exit`()	Called when mouse exits frame.
`on_mount`()	Called when element is first added to the element tree.
`on_unmount`()	Called when element is removed from the element tree.
`on_update`(changed_props)	Called when element props are updated during reconciliation.
`remove_class`(class_name)	Remove a CSS class from this element.
`render`()	Render the frame to a plain string.
`render_signature`()	Hashable/comparable capture of everything `render_to()` reads.
`render_to`(ctx)	Render frame using cell-based rendering (NEW API).
`restore_ephemeral_state`(state)	Restore ephemeral state after reconciliation.
`restore_scroll_position`(position)	Restore scroll position from saved state.
`restore_scroll_position_x`(position)	Restore horizontal scroll position from saved state.
`scroll_to_make_visible`(target_top_y, ...)	Adjust the vertical scroll position so a rectangle is visible.
`set_bounds`(bounds)	Set the element's screen bounds.
`set_child_content_height`(child_height)	Set the total height of child elements for scrolling calculations.
`set_content`(text)	Set the frame content from a string.
`toggle_class`(class_name)	Toggle a CSS class on this element.
`update_viewport_for_current_size`()	Update scroll manager viewport size based on current frame dimensions.

Attributes

`captures_tab`	Whether this element wants the Tab key instead of focus movement.
`parent_frame`	Get the parent Frame if this element is inside a scrollable frame.
`scroll_position`	Get the current scroll position (required by ScrollableElement ABC).
`scroll_position_x`	Get the current horizontal scroll position.
`scroll_state_key`	Get the state key for vertical scroll position.
`scroll_state_key_x`	Get the state key for horizontal scroll position.
`supports_dynamic_sizing`	Whether this element supports dynamic sizing.

set_content(text)[source]

Set the frame content from a string.

Parameters:: text (str) – Content text (may contain newlines)
Return type:: None

Notes

If the frame is scrollable, this method will create or update the ScrollManager based on content height and viewport size.

If overflow_x=”wrap”, content lines will be wrapped to fit the frame’s inner width, potentially expanding the number of content lines.

If overflow_x=”scroll” or “auto”, horizontal scrolling is enabled and a horizontal ScrollManager is created based on max content width.

set_child_content_height(child_height)[source]

Set the total height of child elements for scrolling calculations.

Parameters:: child_height (int) – Total height of all child elements combined
Return type:: None

Notes

This method is called by the layout engine when a frame contains child elements instead of text content. It sets up the ScrollManager to enable scrolling of the composite child content.

get_scroll_offset()[source]

Get the current scroll offset for rendering children.

Returns:: Number of lines scrolled from the top (0 if not scrolling)
Return type:: int

Notes

This is used by the renderer to adjust child element positions when the frame is scrollable and has been scrolled.

update_viewport_for_current_size()[source]

Update scroll manager viewport size based on current frame dimensions.

This should be called after changing frame width/height to ensure the scroll manager calculates scrollability correctly.

Notes

This method only updates the viewport size, not the content size. It’s useful when frame dimensions are changed after set_content() was called (e.g., during layout or rendering).

Return type:: None

property scroll_position: int

Get the current scroll position (required by ScrollableElement ABC).

Returns:: Current scroll offset (0-based)
Return type:: int

can_scroll(direction)[source]

Check if the frame can scroll vertically in the given direction.

Parameters:: direction (int) – Scroll direction: negative for up, positive for down
Returns:: True if scrolling in the given direction is possible
Return type:: bool

property scroll_position_x: int

Get the current horizontal scroll position.

Returns:: Current horizontal scroll offset (0-based)
Return type:: int

can_scroll_horizontal(direction)[source]

Check if the frame can scroll horizontally in the given direction.

Parameters:: direction (int) – Scroll direction: negative for left, positive for right
Returns:: True if scrolling in the given direction is possible
Return type:: bool

get_scroll_offset_x()[source]

Get the current horizontal scroll offset for rendering.

Returns:: Number of columns scrolled from the left (0 if not scrolling)
Return type:: int

handle_scroll_horizontal(direction)[source]

Handle horizontal scrolling.

Parameters:: direction (int) – Scroll direction: -1 for left, 1 for right
Returns:: True if scroll was handled, False otherwise
Return type:: bool

restore_scroll_position_x(position)[source]

Restore horizontal scroll position from saved state.

Parameters:: position (int) – Horizontal scroll position to restore
Return type:: None

render()[source]

Render the frame to a plain string.

Notes

This is the standalone string path, for drawing a frame without the app’s render pipeline – writing straight to a ScreenManager, or inspecting a frame in a test or REPL. examples/advanced/scroll_demo.py uses it that way.

Inside a Wijjit app, frames are painted by render_to(ctx) instead: that is the cell-based path, and the only one that participates in clipping, diff rendering, and wide-character handling. Prefer it for anything that draws into a PaintContext.

Returns:: Rendered frame with borders and content
Return type:: str

Notes

If the frame is scrollable and content exceeds viewport, only the visible portion of content (based on scroll position) will be rendered, along with a scrollbar if enabled.

When a scrollable frame has children, it renders borders and scrollbar, but children render themselves at their scrolled positions.

handle_key(key)[source]

Handle keyboard input for scrolling.

Parameters:: key (Key) – The key that was pressed
Returns:: True if key was handled (caused scrolling), False otherwise
Return type:: bool

Notes

Handles the following keys for vertical scrolling: - up/down: Scroll by one line - pageup/pagedown: Scroll by one viewport - home/end: Scroll to top/bottom

Handles the following keys for horizontal scrolling: - left/right: Scroll by one column - shift+left/shift+right: Scroll by one viewport width

handle_scroll(direction)[source]

Handle mouse wheel scrolling.

Parameters:: direction (int) – Scroll direction: -1 for up, 1 for down
Returns:: True if scroll was handled, False otherwise
Return type:: bool

async handle_mouse(event)[source]

Handle mouse events (scrolling).

Parameters:: event (MouseEvent) – The mouse event
Returns:: True if event was handled, False otherwise
Return type:: bool

Notes

Supports both vertical and horizontal scrolling: - Normal scroll wheel: vertical scrolling - Shift+scroll wheel: horizontal scrolling - Scroll over horizontal scrollbar area: horizontal scrolling

on_focus()[source]

Called when frame gains focus.

Notes

Sets the focused flag to True. Used by focus manager.

Return type:: None

on_blur()[source]

Called when frame loses focus.

Notes

Sets the focused flag to False. Used by focus manager.

Return type:: None

on_hover_enter()[source]

Called when mouse enters frame.

Notes

Sets the hovered flag to True. Used by hover manager.

Return type:: None

on_hover_exit()[source]

Called when mouse exits frame.

Notes

Sets the hovered flag to False. Used by hover manager.

Return type:: None

restore_scroll_position(position)[source]

Restore scroll position from saved state.

Parameters:: position (int) – Scroll position to restore
Return type:: None

Notes

This method is called by the framework to restore scroll state when the element is recreated.

scroll_to_make_visible(target_top_y, target_bottom_y)[source]

Adjust the vertical scroll position so a rectangle is visible.

Given the natural (pre-scroll) screen-space y range of a descendant, scroll the frame just enough that the range lies inside the frame’s content viewport. Scrolls down to reveal a descendant that is below the viewport, or up to reveal one that is above. No-op if the frame is not scrollable, has no scroll manager, or the descendant already fits.

Parameters:

target_top_y (int) – Natural screen-space y of the top of the descendant (i.e. element.bounds.y before scroll is applied).
target_bottom_y (int) – Natural screen-space y of the bottom of the descendant (exclusive, i.e. element.bounds.y + element.bounds.height).

Returns:

True if the scroll position changed, False otherwise.

Return type:

bool

render_to(ctx)[source]

Render frame using cell-based rendering (NEW API).

Parameters:: ctx (PaintContext) – Paint context with buffer, style resolver, and bounds
Return type:: None

Notes

This method implements cell-based rendering for frames, supporting: - Multiple border styles (single, double, rounded) - Optional titles in borders - Padding and content alignment - Vertical and horizontal scrolling with scrollbar rendering - Corner cell when both scrollbars are visible - Theme-based styling

Theme styles:

This element uses the following theme style classes: - frame: Base frame style for content - frame:focus: When frame has focus - frame.border: For border characters - frame.title: For title text in border

get_ephemeral_state()[source]

Get ephemeral state for reconciliation.

Returns:: Scroll state that should survive re-renders
Return type:: dict

restore_ephemeral_state(state)[source]

Restore ephemeral state after reconciliation.

Parameters:: state (dict) – State from get_ephemeral_state()
Return type:: None