Raxol.Terminal.Buffer.ScrollRegion (Raxol v0.5.0)
View SourceHandles 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
@spec clear(Raxol.Terminal.ScreenBuffer.t()) :: Raxol.Terminal.ScreenBuffer.t()
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
@spec get_boundaries(Raxol.Terminal.ScreenBuffer.t()) :: {non_neg_integer(), non_neg_integer()}
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}
@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}
@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 bufferstart_line
- The starting line of the region to replaceend_line
- The ending line of the region to replacenew_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"}]]
@spec scroll_down( Raxol.Terminal.ScreenBuffer.t(), non_neg_integer(), {non_neg_integer(), non_neg_integer()} | nil ) :: Raxol.Terminal.ScreenBuffer.t()
Scrolls the content down within the scroll region.
Parameters
buffer
- The screen buffer to modifylines
- The number of lines to scroll downscroll_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
@spec scroll_up( Raxol.Terminal.ScreenBuffer.t(), non_neg_integer(), {non_neg_integer(), non_neg_integer()} | nil ) :: Raxol.Terminal.ScreenBuffer.t()
Scrolls the content up within the scroll region.
Parameters
buffer
- The screen buffer to modifylines
- The number of lines to scroll upscroll_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
@spec set_region( Raxol.Terminal.ScreenBuffer.t(), non_neg_integer(), non_neg_integer() ) :: Raxol.Terminal.ScreenBuffer.t()
Sets the scroll region boundaries. The region must be valid (top < bottom) and within screen bounds.
Parameters
buffer
- The screen buffer to modifytop
- The top boundary of the scroll regionbottom
- 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