TermUI.Widgets.Viewport (TermUI v0.2.0)

View Source

Viewport widget for scrollable content.

Viewport displays a scrollable view of content larger than the viewport area. It tracks scroll position, clips content to bounds, and optionally shows scroll bars for visual feedback and interaction.

Usage

Viewport.new(
  content: large_content_tree(),
  width: 40,
  height: 20,
  scroll_bars: :both
)

Features

  • Scrollable view of larger content
  • Automatic content clipping to viewport bounds
  • Optional vertical and horizontal scroll bars
  • Keyboard navigation (arrow keys, Page Up/Down, Home/End)
  • Mouse wheel scrolling
  • Scroll bar drag interaction

Keyboard Navigation

  • Arrow keys: Scroll by one line/column
  • Page Up/Down: Scroll by viewport height
  • Home/End: Scroll to top/bottom
  • Ctrl+Home/End: Scroll to start/end horizontally

Summary

Functions

can_scroll_horizontal?(state)

Checks if content is scrollable horizontally.

can_scroll_vertical?(state)

Checks if content is scrollable vertically.

get_scroll(state)

Gets the current scroll position.

new(opts)

Creates new Viewport widget props.

scroll_into_view(state, x, y)

Scrolls to make a position visible.

set_content(state, content)

Updates the content.

set_content_size(state, width, height)

Updates the content dimensions.

set_scroll(state, x, y)

Sets the scroll position.

visible_fraction_horizontal(state)

Gets the visible fraction (0.0 - 1.0) for horizontal scrolling.

visible_fraction_vertical(state)

Gets the visible fraction (0.0 - 1.0) for vertical scrolling.

Functions

can_scroll_horizontal?(state)

@spec can_scroll_horizontal?(map()) :: boolean()

Checks if content is scrollable horizontally.

can_scroll_vertical?(state)

@spec can_scroll_vertical?(map()) :: boolean()

Checks if content is scrollable vertically.

get_scroll(state)

@spec get_scroll(map()) :: {integer(), integer()}

Gets the current scroll position.

new(opts)

@spec new(keyword()) :: map()

Creates new Viewport widget props.

Options

  • :content - Content to display (render node)
  • :content_width - Width of content (for horizontal scrolling)
  • :content_height - Height of content (for vertical scrolling)
  • :width - Viewport width (default: 40)
  • :height - Viewport height (default: 20)
  • :scroll_x - Initial horizontal scroll position (default: 0)
  • :scroll_y - Initial vertical scroll position (default: 0)
  • :scroll_bars - Scroll bar display: :none, :vertical, :horizontal, :both (default: :both)
  • :on_scroll - Callback when scroll position changes
  • :scroll_step - Lines to scroll per step (default: 1)
  • :page_step - Lines to scroll per page (default: viewport height)

scroll_into_view(state, x, y)

@spec scroll_into_view(map(), integer(), integer()) :: map()

Scrolls to make a position visible.

set_content(state, content)

@spec set_content(map(), term()) :: map()

Updates the content.

set_content_size(state, width, height)

@spec set_content_size(map(), integer(), integer()) :: map()

Updates the content dimensions.

set_scroll(state, x, y)

@spec set_scroll(map(), integer(), integer()) :: map()

Sets the scroll position.

visible_fraction_horizontal(state)

@spec visible_fraction_horizontal(map()) :: float()

Gets the visible fraction (0.0 - 1.0) for horizontal scrolling.

visible_fraction_vertical(state)

@spec visible_fraction_vertical(map()) :: float()

Gets the visible fraction (0.0 - 1.0) for vertical scrolling.