Raxol.Terminal.Screen (Raxol v0.5.0)
View SourceProvides screen manipulation functions for the terminal emulator.
This module handles operations like resizing, marking damaged regions,
and clearing the screen. It works in conjunction with Raxol.Terminal.ScreenBuffer
to manage the terminal display state.
Features
- Screen resizing
- Region damage tracking
- Screen and line clearing
- Line and character insertion/deletion
- Cursor movement
- Screen scrolling
Usage
# Create a new screen buffer
buffer = ScreenBuffer.new(80, 24)
# Resize the screen
buffer = Screen.resize(buffer, 100, 30)
# Clear the screen
buffer = Screen.clear_screen(buffer)
Summary
Functions
Clears a specific line in the screen.
Clears the entire screen and resets formatting.
Deletes characters at the current cursor position.
Deletes lines at the current cursor position, pulling content up.
Erases characters at the current cursor position.
Erases the display based on the specified mode.
Inserts characters at the current cursor position, pushing existing content right.
Inserts lines at the current cursor position, pushing existing content down.
Marks a region of the screen as damaged, indicating it needs to be redrawn.
Resizes the screen buffer to new dimensions.
Scrolls the screen down by the specified number of lines.
Scrolls the screen up by the specified number of lines.
Functions
@spec clear_line(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Clears a specific line in the screen.
Parameters
buffer
- The current screen bufferline
- Line number to clear (0-based)
Returns
- Updated screen buffer with cleared line
Examples
iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = Screen.clear_line(buffer, 0)
iex> get_in(buffer.content, [0])
%{}
@spec clear_screen(Raxol.Terminal.ScreenBuffer.t()) :: Raxol.Terminal.ScreenBuffer.t()
Clears the entire screen and resets formatting.
Parameters
buffer
- The current screen buffer
Returns
- Updated screen buffer with cleared content
Examples
iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = Screen.clear_screen(buffer)
iex> buffer.content
%{}
@spec delete_chars(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Deletes characters at the current cursor position.
@spec delete_lines(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Deletes lines at the current cursor position, pulling content up.
Parameters
buffer
- The current screen buffercount
- Number of lines to delete
Returns
- Updated screen buffer with deleted lines
Examples
iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = Screen.delete_lines(buffer, 2)
iex> buffer.scroll_region
{0, 23}
@spec erase_chars(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Erases characters at the current cursor position.
@spec erase_display(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Erases the display based on the specified mode.
Mode values:
- 0 - Erase from cursor to end of screen
- 1 - Erase from start of screen to cursor
- 2 - Erase entire screen
- 3 - Erase entire screen and scrollback buffer
@spec insert_chars(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Inserts characters at the current cursor position, pushing existing content right.
Parameters
buffer
- The current screen buffercount
- Number of characters to insert
Returns
- Updated screen buffer with inserted characters
Examples
iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = Screen.insert_chars(buffer, 5)
iex> buffer.cursor
{5, 0}
@spec insert_lines(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Inserts lines at the current cursor position, pushing existing content down.
Parameters
buffer
- The current screen buffercount
- Number of lines to insert
Returns
- Updated screen buffer with inserted lines
Examples
iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = Screen.insert_lines(buffer, 2)
iex> buffer.scroll_region
{0, 23}
@spec mark_damaged( Raxol.Terminal.ScreenBuffer.t(), non_neg_integer(), non_neg_integer(), non_neg_integer(), non_neg_integer() ) :: Raxol.Terminal.ScreenBuffer.t()
Marks a region of the screen as damaged, indicating it needs to be redrawn.
Parameters
buffer
- The current screen bufferx
- Starting x coordinatey
- Starting y coordinatewidth
- Width of damaged regionheight
- Height of damaged region
Returns
- Updated screen buffer with marked damage region
Examples
iex> buffer = ScreenBuffer.new(80, 24)
iex> buffer = Screen.mark_damaged(buffer, 0, 0, 10, 5)
iex> buffer.damage_regions
[{0, 0, 10, 5}]
@spec resize(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Resizes the screen buffer to new dimensions.
Parameters
buffer
- The current screen bufferwidth
- New width in charactersheight
- New height in characters
Returns
- Updated screen buffer with new dimensions
Examples
iex> buffer = ScreenBuffer.new(80, 24)
iex> new_buffer = Screen.resize(buffer, 100, 30)
iex> {new_buffer.width, new_buffer.height}
{100, 30}
@spec scroll_down(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Scrolls the screen down by the specified number of lines.
@spec scroll_up_screen(Raxol.Terminal.ScreenBuffer.t(), non_neg_integer()) :: Raxol.Terminal.ScreenBuffer.t()
Scrolls the screen up by the specified number of lines.