wijjit.elements.display.logview.LogView

class wijjit.elements.display.logview.LogView(id=None, classes=None, lines=None, width=80, height=20, auto_scroll=True, soft_wrap=False, show_line_numbers=False, line_number_start=1, detect_log_levels=True, show_scrollbar=True, border_style='single', title=None, tab_index=None, bind=True)

LogView element for displaying logs with automatic coloring and scrolling.

This element provides a display for log files with support for: - Automatic log level detection and coloring (ERROR, WARNING, INFO, DEBUG, TRACE) - ANSI passthrough - preserves existing ANSI codes in log lines - Auto-scroll mode - automatically scrolls to bottom when new lines are added - Soft-wrap - optional line wrapping for long lines - Line numbers - optional display of line numbers - Scrolling for large log files (optimized for 10k+ lines) - Borders with optional titles - Mouse and keyboard interaction for scrolling

Parameters:

• id (str, optional) – Element identifier

• lines (list of str, optional) – Log lines (default: [])

• width (int, optional) – Display width in columns (default: 80)

• height (int, optional) – Display height in rows (default: 20)

• auto_scroll (bool, optional) – Automatically scroll to bottom when new lines added (default: True)

• soft_wrap (bool, optional) – Wrap long lines instead of clipping (default: False)

• show_line_numbers (bool, optional) – Display line numbers on the left (default: False)

• line_number_start (int, optional) – Starting line number (default: 1)

• detect_log_levels (bool, optional) – Automatically detect and color log levels (default: True)

• show_scrollbar (bool, optional) – Whether to show vertical scrollbar (default: True)

• border_style (str, optional) – Border style: “single”, “double”, “rounded”, or “none” (default: “single”)

• title (str, optional) – Title to display in top border (default: None)

• classes (str | list[str] | set[str] | None)

• tab_index (int | None)

• bind (bool | str)

Variables:

• lines (list of str) – Raw log lines

• width (int) – Display width

• height (int) – Display height

• auto_scroll (bool) – Auto-scroll enabled flag

• soft_wrap (bool) – Soft-wrap enabled flag

• show_line_numbers (bool) – Line numbers display flag

• line_number_start (int) – Starting line number

• detect_log_levels (bool) – Log level detection flag

• show_scrollbar (bool) – Whether scrollbar is visible

• border_style (str) – Border style

• title (str or None) – Border title

• scroll_manager (ScrollManager) – Manages scrolling of content

• rendered_lines (list of str) – Cached rendered content lines

Notes

Log level detection uses regex patterns to identify common log levels: - ERROR/FATAL/CRITICAL → Red + Bold - WARNING/WARN → Yellow - INFO → Cyan - DEBUG → Dim - TRACE → Dim

Auto-scroll behavior: - When enabled, automatically scrolls to bottom when new lines are added - Disabled when user manually scrolls up from bottom - Re-enabled when user scrolls back to bottom or presses End key

Examples

Basic log view: >>> logview = LogView(lines=[“INFO: App started”, “ERROR: Connection failed”])

With auto-scroll and soft-wrap: >>> logview = LogView( … lines=logs, … auto_scroll=True, … soft_wrap=True, … width=80, … height=20 … )

With line numbers: >>> logview = LogView( … lines=logs, … show_line_numbers=True, … line_number_start=1 … )

__init__(id=None, classes=None, lines=None, width=80, height=20, auto_scroll=True, soft_wrap=False, show_line_numbers=False, line_number_start=1, detect_log_levels=True, show_scrollbar=True, border_style='single', title=None, tab_index=None, bind=True)

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

• lines (list[str] | None)

• width (int)

• height (int)

• auto_scroll (bool)

• soft_wrap (bool)

• show_line_numbers (bool)

• line_number_start (int)

• detect_log_levels (bool)

• show_scrollbar (bool)

• border_style (str)

• title (str | None)

• bind (bool | str)

Return type:

None

Methods

__init__([id, classes, lines, width, ...])	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 element can scroll 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 size of the LogView element.
handle_key(key)	Handle keyboard input for scrolling.
handle_mouse(event)	Handle mouse input for scrolling.
has_class(class_name)	Check if element has a CSS class.
on_blur()	Called when element loses focus.
on_focus()	Called when element gains focus.
on_hover_enter()	Called when mouse enters element.
on_hover_exit()	Called when mouse exits element.
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)	Handle prop updates during reconciliation.
remove_class(class_name)	Remove a CSS class from this element.
render_signature()	Hashable/comparable capture of everything render_to() reads.
render_to(ctx)	Render log view 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.
set_bounds(bounds)	Adopt the layout allocation so the painted box matches it.
set_lines(lines)	Update log lines and re-render.
toggle_class(class_name)	Toggle a CSS class on this element.

Attributes

autoscroll_state_key	Get the state key for auto-scroll state.
captures_tab	Whether this element wants the Tab key instead of focus movement.
lines	Log lines.
parent_frame	Get the parent Frame if this element is inside a scrollable frame.
scroll_position	Get the current 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.

property autoscroll_state_key: str | None

Get the state key for auto-scroll state.

Returns the explicitly set key if provided, otherwise auto-generates from the element id using the convention “{id}:autoscroll”.

Returns:

State key for autoscroll, or None if no id

Return type:

str or None

set_bounds(bounds)

Adopt the layout allocation so the painted box matches it.

The box (border included) is drawn from self.width / self.height, which under width="fill" hold the tag’s numeric defaults rather than the width the layout engine actually assigned - drawing the box short of (or past) its slot. For fixed sizes the tag already budgets the border into the layout node, so bounds match the props and this sync is a no-op.

Parameters:

bounds (Bounds) – New bounds for the element.

Return type:

None

property lines: list[str]

Log lines.

Assignment delegates to set_lines(), so logview.lines = rows re-renders and re-clamps scroll (with auto-scroll) uniformly, instead of leaving the rendered content and scroll manager stale.

set_lines(lines)

Update log lines and re-render.

Parameters:

lines (list of str) – New log lines

Return type:

None

Notes

If auto-scroll is enabled and user hasn’t manually scrolled up, this will automatically scroll to the bottom after updating.

restore_scroll_position(position)

Restore scroll position from saved state.

Parameters:

position (int) – Scroll position to restore

Return type:

None

property scroll_position: int

Get the current scroll position.

Returns:

Current scroll offset (0-based)

Return type:

int

get_intrinsic_size()

Get the intrinsic size of the LogView element.

Returns:

(width, height) based on configured dimensions

Return type:

tuple[int, int]

on_update(changed_props)

Handle prop updates during reconciliation.

Parameters:

changed_props (dict) – Map of prop_name -> (old_value, new_value)

Return type:

None

get_ephemeral_state()

Get ephemeral state for reconciliation.

Returns:

Scroll position and user scroll state to preserve across re-renders

Return type:

dict

restore_ephemeral_state(state)

Restore ephemeral state after reconciliation.

Parameters:

state (dict) – State from get_ephemeral_state()

Return type:

None

Notes

The reconciler captures scroll position before the new lines prop is applied, so restoring it verbatim would undo the auto-scroll that set_lines() performs when content grows. To keep tailing behavior working across re-renders, when auto-scroll is enabled and the user has not scrolled up we re-assert the bottom instead of the stale position. A user who has scrolled up to read history keeps their exact position.

can_scroll(direction)

Check if the element can scroll 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

handle_key(key)

Handle keyboard input for scrolling.

Parameters:

key (Key) – Key press to handle

Returns:

True if key was handled

Return type:

bool

async handle_mouse(event)

Handle mouse input for scrolling.

Parameters:

event (MouseEvent) – Mouse event to handle

Returns:

True if event was handled

Return type:

bool

render_to(ctx)

Render log view 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 log views, supporting: - Log level detection and theme-based coloring (ERROR, WARNING, INFO, DEBUG, TRACE) - Optional line numbers with theme styling - Soft-wrap for long lines - Auto-scroll behavior - Scrolling with scrollbar - Borders with titles and focus styling - Theme-based styling throughout

Theme styles:

This element uses the following theme style classes: - logview: Base logview style (for lines without detected log level) - logview:focus: When logview has focus - logview.error: For ERROR/FATAL/CRITICAL log lines - logview.warning: For WARNING/WARN log lines - logview.info: For INFO log lines - logview.debug: For DEBUG log lines - logview.trace: For TRACE log lines - logview.line_number: For line number column - logview.border: For border characters - logview.border:focus: For border when focused