Raxol.Terminal.Buffer.ScrollRegion (Raxol v0.5.0)

View Source

Handles scroll region operations for the screen buffer. This module manages the scroll region boundaries and provides functions for scrolling content within the defined region.

Scroll Region

A scroll region defines a subset of the screen buffer where scrolling operations are confined. The region is defined by its top and bottom boundaries, and all scrolling operations (up/down) will only affect the content within these boundaries.

Operations

  • Setting and clearing scroll regions
  • Scrolling content up and down within the region
  • Getting region boundaries
  • Validating region boundaries
  • Managing content within the region

Summary

Functions

Clears the scroll region, resetting to full screen.

Gets the current scroll region boundaries. Returns {0, height-1} if no region is set.

Gets the current scroll region boundaries.

Replaces the content of a region in the buffer with new content.

Scrolls the content down within the scroll region.

Scrolls the content up within the scroll region.

Sets the scroll region boundaries. The region must be valid (top < bottom) and within screen bounds.

Functions

clear(buffer)

Clears the scroll region, resetting to full screen.

Parameters

  • buffer - The screen buffer to modify

Returns

The updated screen buffer with scroll region cleared.

Examples

iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = ScrollRegion.set_region(buffer, 5, 15)
iex> buffer = ScrollRegion.clear(buffer)
iex> ScrollRegion.get_region(buffer)
nil

get_boundaries(screen_buffer)

Gets the current scroll region boundaries. Returns {0, height-1} if no region is set.

Parameters

  • buffer - The screen buffer to query

Returns

A tuple {top, bottom} representing the effective scroll region boundaries.

Examples

iex> buffer = ScreenBuffer.new(80, 24)
iex> ScrollRegion.get_boundaries(buffer)
{0, 23}

iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = ScrollRegion.set_region(buffer, 5, 15)
iex> ScrollRegion.get_boundaries(buffer)
{5, 15}

get_region(screen_buffer)

@spec get_region(Raxol.Terminal.ScreenBuffer.t()) ::
  {non_neg_integer(), non_neg_integer()} | nil

Gets the current scroll region boundaries.

Parameters

  • buffer - The screen buffer to query

Returns

A tuple {top, bottom} representing the scroll region boundaries, or nil if no region is set.

Examples

iex> buffer = ScreenBuffer.new(80, 24)
iex> ScrollRegion.get_region(buffer)
nil

iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = ScrollRegion.set_region(buffer, 5, 15)
iex> ScrollRegion.get_region(buffer)
{5, 15}

replace_region_content(cells, start_line, end_line, new_content)

@spec replace_region_content(
  [[Raxol.Terminal.Cell.t()]],
  non_neg_integer(),
  non_neg_integer(),
  [
    [Raxol.Terminal.Cell.t()]
  ]
) :: [[Raxol.Terminal.Cell.t()]]

Replaces the content of a region in the buffer with new content.

Parameters

  • cells - The current cells in the buffer
  • start_line - The starting line of the region to replace
  • end_line - The ending line of the region to replace
  • new_content - The new content to insert in the region

Returns

The updated cells with the region replaced.

Examples

iex> cells = [[%Cell{char: "A"}, %Cell{char: "B"}], [%Cell{char: "C"}, %Cell{char: "D"}]]
iex> new_content = [[%Cell{char: "X"}, %Cell{char: "Y"}], [%Cell{char: "Z"}, %Cell{char: "W"}]]
iex> ScrollRegion.replace_region_content(cells, 0, 1, new_content)
[[%Cell{char: "X"}, %Cell{char: "Y"}], [%Cell{char: "Z"}, %Cell{char: "W"}]]

scroll_down(buffer, lines, scroll_region_arg \\ nil)

Scrolls the content down within the scroll region.

Parameters

  • buffer - The screen buffer to modify
  • lines - The number of lines to scroll down
  • scroll_region_arg - Optional scroll region override

Returns

The updated screen buffer with content scrolled down.

Examples

iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = ScrollRegion.set_region(buffer, 5, 15)
iex> buffer = ScrollRegion.scroll_down(buffer, 1)
iex> # Content is scrolled down within region 5-15

scroll_up(buffer, lines, scroll_region_arg \\ nil)

Scrolls the content up within the scroll region.

Parameters

  • buffer - The screen buffer to modify
  • lines - The number of lines to scroll up
  • scroll_region_arg - Optional scroll region override

Returns

The updated screen buffer with content scrolled up.

Examples

iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = ScrollRegion.set_region(buffer, 5, 15)
iex> buffer = ScrollRegion.scroll_up(buffer, 1)
iex> # Content is scrolled up within region 5-15

set_region(buffer, top, bottom)

Sets the scroll region boundaries. The region must be valid (top < bottom) and within screen bounds.

Parameters

  • buffer - The screen buffer to modify
  • top - The top boundary of the scroll region
  • bottom - The bottom boundary of the scroll region

Returns

The updated screen buffer with new scroll region boundaries. If the region is invalid, the scroll region is cleared.

Examples

iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = ScrollRegion.set_region(buffer, 5, 15)
iex> ScrollRegion.get_region(buffer)
{5, 15}

iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = ScrollRegion.set_region(buffer, 15, 5)  # Invalid region
iex> ScrollRegion.get_region(buffer)
nil