Struct Surface 

pub struct Surface { /* private fields */ }

A structure that represents a 2D surface for drawing characters and images. The surface is defined as a matrix (width x height) of characters, where each character is of type Character. The surface has a size, an origin point, a clip area, and a cursor position. The size of the surface is maximum 10000 x 10000 characters.

Implementations

impl Surface

pub fn new(width: u32, height: u32) -> Surface

Creates a new surface with the specified width and height. The surface will be filled with space (empty) character with White foreground and Black background. The surface will have the origin set to (0,0) and the clip area will be the entire surface. The width and height of the surface will be clamped between 1 and 10000.

Example:

use appcui::graphics::{Surface};
let mut surface = Surface::new(100, 50);

pub fn from_string(text: &str, size: Size) -> Surface

Creates a new surface from a string with the specified size. The string will be written to the surface starting at position (0, 0). All characters will have white foreground and black background. If the string is longer than the surface area, it will be truncated. If the string is shorter than the surface area, the remaining area will be filled with spaces.

Arguments

• text - The string to render on the surface
• size - The size of the surface to create

Example

use appcui::graphics::{Surface, Size};

let surface = Surface::from_string("Hello World!", Size::new(20, 5));

pub fn size(&self) -> Size

Returns the size of the surface (width and height).

pub fn set_origin(&mut self, x: i32, y: i32)

Sets the origin of the surface. The origin is used to draw text and images relative to a specific point.

Example:

use appcui::graphics::{Surface};
let mut surface = Surface::new(100, 50);
surface.set_origin(10, 10);

pub fn reset_origin(&mut self)

Resets the origin of the surface to the base origin.

pub fn set_relative_clip( &mut self, left: i32, top: i32, right: i32, bottom: i32, )

pub fn set_clip(&mut self, left: i32, top: i32, right: i32, bottom: i32)

Sets the clip area of the surface. The clip area is used to restrict the drawing operations to a specific area of the surface.

Example:

use appcui::graphics::{Surface};
let mut surface = Surface::new(100, 50);
surface.set_clip(10, 10, 20, 20);

pub fn reduce_clip_by( &mut self, left_margin: u32, top_margin: u32, right_margin: u32, bottom_margin: u32, )

Reduces the clip area of the surface by the specified margins. This is useful when you want to draw a border around the surface.

Example:

use appcui::graphics::{Surface};
let mut surface = Surface::new(100, 50);
surface.set_clip(10, 10, 20, 20);
// draw a border from (10,10) to (20,20)
// reduce the clip area by one character to make sure
// the border will not be overwritten by other drawing
// operations
surface.reduce_clip_by(1, 1, 1, 1);

pub fn reset_clip(&mut self)

Resets the clip area of the surface to the base clip area.

pub fn set_cursor(&mut self, x: i32, y: i32)

Sets the position of the cursor relativ to the origin point. If the cursor is within the clip area, it will be visible. Otherwise it will be hidden.

Example:

use appcui::graphics::{Surface};
let mut surface = Surface::new(100, 50);
surface.set_cursor(10, 10);

pub fn hide_cursor(&mut self)

Hides the cursor.

pub fn write_char(&mut self, x: i32, y: i32, ch: Character)

Writes a character at the specified position. If the position is outside the clip area, the character will not be drawn.

Example:

use appcui::graphics::{Surface, Character, Color, CharFlags};
let mut surface = Surface::new(100, 50);
surface.write_char(10, 10, Character::new('A', Color::White, Color::Black, CharFlags::None));

pub fn char(&self, x: i32, y: i32) -> Option<&Character>

Returns the character at the specified position. If the position is outside the clip area, None will be returned.

pub fn clear(&mut self, ch: Character)

Clears/Fills the entire clip area with the specified character. If the clip area is not visible, the surface will not be cleared.

pub fn reset(&mut self, ch: Character)

Resets the entire surface by filling it with a provided character and by resetting the coordinates and the clip area. You can use this method method if you want to fill a surface with a transparent character (e.g. if you want that surface to be printed on another surface via draw_surface method)

pub fn fill_horizontal_line( &mut self, left: i32, y: i32, right: i32, ch: Character, )

Fills a horizontal line with the specified character type, color and attributes. If the line is outside the clip area, it will not be drawn.

Example:

use appcui::graphics::{Surface, Character, Color, CharFlags};
let mut surface = Surface::new(100, 50);
surface.fill_horizontal_line(10, 10, 20, Character::new('-', Color::White, Color::Black, CharFlags::None));

pub fn fill_horizontal_line_with_size( &mut self, x: i32, y: i32, width: u32, ch: Character, )

Fills a horizontal line with the specified character type, color and attributes. If the line is outside the clip area, it will not be drawn. if the width is bigger than 0, this method will call fill_horizontal_line method

pub fn fill_vertical_line( &mut self, x: i32, top: i32, bottom: i32, ch: Character, )

Fills a vertical line with the specified character type, color and attributes. If the line is outside the clip area, it will not be drawn.

Example:

use appcui::graphics::{Surface, Character, Color, CharFlags};
let mut surface = Surface::new(100, 50);
surface.fill_vertical_line(10, 10, 20, Character::new('|', Color::White, Color::Black, CharFlags::None));

pub fn fill_vertical_line_with_size( &mut self, x: i32, y: i32, height: u32, ch: Character, )

Fills a vertical line with the specified character type, color and attributes. If the line is outside the clip area, it will not be drawn. if the height is bigger than 0, this method will call fill_vertical_line method

pub fn draw_vertical_line( &mut self, x: i32, top: i32, bottom: i32, line_type: LineType, attr: CharAttribute, )

Draws a vertical line with the specified character type, color and attributes. If the line is outside the clip area, it will not be drawn.

Example:

use appcui::graphics::{Surface, LineType, CharAttribute, Color};
let mut surface = Surface::new(100, 50);
surface.draw_vertical_line(10, 10, 20,
                           LineType::Single,
                           CharAttribute::with_color(Color::White, Color::Black));

pub fn draw_vertical_line_with_size( &mut self, x: i32, y: i32, height: u32, line_type: LineType, attr: CharAttribute, )

Draws a vertical line with the specified character type, color and attributes. If the line is outside the clip area, it will not be drawn.
if the height is bigger than 0, this method will call draw_vertical_line method

pub fn draw_horizontal_line( &mut self, left: i32, y: i32, right: i32, line_type: LineType, attr: CharAttribute, )

Draws a horizontal line with the specified character type, color and attributes. If the line is outside the clip area, it will not be drawn.

Example:

use appcui::graphics::{Surface, LineType, CharAttribute, Color};
let mut surface = Surface::new(100, 50);
surface.draw_horizontal_line(10, 10, 20,
                             LineType::Single,
                             CharAttribute::with_color(Color::White, Color::Black));

pub fn draw_horizontal_line_with_size( &mut self, x: i32, y: i32, width: u32, line_type: LineType, attr: CharAttribute, )

Draws a horizontal line with the specified character type, color and attributes. If the line is outside the clip area, it will not be drawn.
if the height is bigger than 0, this method will call draw_horizontal_line method

pub fn draw_braille_line( &mut self, x1: i32, y1: i32, x2: i32, y2: i32, attr: CharAttribute, )

pub fn draw_line( &mut self, x1: i32, y1: i32, x2: i32, y2: i32, line_type: LineType, attr: CharAttribute, )

Draws a straight line between two points (x1, y1) and (x2, y2) using the specified line style (LineType) and character attributes.

This method is similar to fill_line, but instead of filling the line with a single Character, it automatically chooses the appropriate glyphs for each segment based on the given LineType (e.g., single, double, thick, ASCII, rounded) and applies the specified CharAttribute (e.g., color, boldness, underline).

Parameters

• x1, y1: Starting point coordinates.
• x2, y2: Ending point coordinates.
• line_type: The LineType variant to use for rendering the line.
• attr: The CharAttribute to apply to each segment of the line.

Examples

use appcui::prelude::*;

let mut surface = Surface::new(100, 50);

// Draw a horizontal single-line border in bold
surface.draw_line(0, 0, 10, 0, LineType::Single, charattr!("white,black"));

// Draw a vertical double-line in red
surface.draw_line(5, 2, 5, 8, LineType::Double, charattr!("red,black"));

pub fn draw_orthogonal_line( &mut self, x1: i32, y1: i32, x2: i32, y2: i32, line_type: LineType, dir: OrthogonalDirection, attr: CharAttribute, )

pub fn fill_line(&mut self, x1: i32, y1: i32, x2: i32, y2: i32, ch: Character)

Draws a straight line between two points (x1, y1) and (x2, y2) on the surface, filling each point along the path with the given character.

This method implements an integer-based Bresenham’s line algorithm, which efficiently determines the set of coordinates that best approximate a straight line between two points in a grid. It works for all line orientations — horizontal, vertical, and diagonal

Parameters

• x1, y1: Starting point coordinates.
• x2, y2: Ending point coordinates.
• ch: The Character to draw along the line.

Examples

use appcui::prelude::*;

let mut surface = Surface::new(100, 50);

// Draws a diagonal line from (0, 0) to (5, 3) using '*'
surface.fill_line(0, 0, 5, 3, Character::new('*', Color::White, Color::Black, CharFlags::None));

// Draws a vertical line from (2, 1) to (2, 5)
surface.fill_line(2, 1, 2, 5, char!("'|',white,black"));

pub fn draw_rect( &mut self, rect: Rect, line_type: LineType, attr: CharAttribute, )

Draws a rectangle with the specified character type, color and attributes. If the rectangle is outside the clip area, it will not be drawn.

Example:

use appcui::graphics::*;

let mut surface = Surface::new(100, 50);
let r = Rect::new(10, 10, 20, 20);
surface.draw_rect(r, LineType::Single, CharAttribute::with_color(Color::White, Color::Black));

pub fn draw_bevel_rect( &mut self, rect: Rect, line_type: LineType, dark: CharAttribute, light: CharAttribute, raised: bool, )

Draws a beveled rectangle with the specified character type, color and attributes. If the rectangle is outside the clip area, it will not be drawn. The raised parameter specifies if the rectangle should appear raised or sunken.

Example:

use appcui::prelude::*;

let mut surface = Surface::new(100, 50);
let r = Rect::new(10, 10, 20, 20);
surface.draw_bevel_rect(r,
                        LineType::Single,
                        charattr!("black,transparent"),
                        charattr!("white,transparent"),
                        true);

pub fn fill_rect(&mut self, rect: Rect, ch: Character)

Fills a rectangle with the specified character type, color and attributes. If the rectangle is outside the clip area, it will not be drawn.

Example:

use appcui::graphics::*;

let mut surface = Surface::new(100, 50);
let r = Rect::new(10, 10, 20, 20);
surface.fill_rect(r, Character::new(' ', Color::White, Color::Black, CharFlags::None));

pub fn write_box_junction(&mut self, x: i32, y: i32)

pub fn draw_surface(&mut self, x: i32, y: i32, surface: &Surface)

Copies all characters from another surface onto this one at the specified position. Each source character is written using write_char, so positions outside the clip area are skipped. If the clip area is not visible, nothing is drawn.

Characters with transparent foreground or background colors do not overwrite the corresponding components of the destination character, which allows layered compositing when the source surface was prepared with transparent characters (for example via reset).

Parameters

• x: The x-coordinate of the top-left corner where the source surface is placed.
• y: The y-coordinate of the top-left corner where the source surface is placed.
• surface: The source surface to copy.

Example

use appcui::graphics::{Surface, Character, Color, CharFlags};

let mut destination = Surface::new(20, 10);
let mut source = Surface::new(5, 3);
source.clear(Character::new('X', Color::Yellow, Color::Black, CharFlags::None));
destination.draw_surface(2, 2, &source);

pub fn draw_surface_with_transform<F: Fn(Character) -> Character>( &mut self, x: i32, y: i32, surface: &Surface, transform: F, )

Copies all characters from another surface onto this one at the specified position, applying a transformation to each source character before it is written. This behaves like draw_surface, but the transform callback can remap character codes, colors, or flags (for example to tint or mask the copied content). If the clip area is not visible, nothing is drawn.

Parameters

• x: The x-coordinate of the top-left corner where the source surface is placed.
• y: The y-coordinate of the top-left corner where the source surface is placed.
• surface: The source surface to copy.
• transform: A function called for each source character; its return value is written to the destination.

Example

use appcui::graphics::{Surface, Character, Color, CharFlags};

let mut destination = Surface::new(20, 10);
let mut source = Surface::new(5, 3);
source.clear(Character::new('X', Color::Yellow, Color::Black, CharFlags::None));
destination.draw_surface_with_transform(2, 2, &source, |ch| {
    Character::new(ch.code, Color::Red, ch.background, ch.flags)
});

pub fn draw_glyph(&mut self, x: i32, y: i32, glyph: &Glyph, attr: CharAttribute)

Draws a glyph at the specified position. If the glyph is outside the clip area, it will not be drawn.

Parameters

• x: The x-coordinate of the position to draw the glyph at.
• y: The y-coordinate of the position to draw the glyph at.
• glyph: The glyph to draw.
• attr: The character attribute to use for the glyph.

Example

use appcui::prelude::*;

let mut surface = Surface::new(100, 50);
let glyph = image::Glyph::with_str(10, 10, "Hello, world!");
surface.draw_glyph(10, 10, &glyph, CharAttribute::with_color(Color::White, Color::Black));

pub fn write_string( &mut self, x: i32, y: i32, text: &str, attr: CharAttribute, multi_line: bool, )

Writes a string at the specified position, from left to right using a specific character attribute. If the text is outside the clip area, it will not be drawn. The multi-line parameter specifices if the text should interpret new line characters as a new line or not. if set to false the code of this method is optimized to write the text faster.

Example:

use appcui::graphics::{Surface, CharAttribute, Color};

let mut surface = Surface::new(100, 50);
surface.write_string(10, 10,
                     "Hello World!",
                     CharAttribute::with_color(Color::White, Color::Black),
                     false);

pub fn write_ascii( &mut self, x: i32, y: i32, ascii_buffer: &[u8], attr: CharAttribute, multi_line: bool, )

Writes an ASCII buffer at the specified position, from left to right using a specific character attribute. If the text is outside the clip area, it will not be drawn.
The multi-line parameter specifices if the text should interpret new line characters as a new line or not. if set to false the code of this method is optimized to write the text faster.

Example:

use appcui::graphics::{Surface, CharAttribute, Color};

let mut surface = Surface::new(100, 50);
surface.write_ascii(10, 10,
                   b"Hello World!",
                   CharAttribute::with_color(Color::White, Color::Black),
                   false);

pub fn write_text(&mut self, text: &str, format: &TextFormat)

Writes a text using a specific format that allows specifying alignment, hotkey position and attributes, width, and height.

Example:

use appcui::graphics::*;

let mut surface = Surface::new(100, 50);
let format = TextFormatBuilder::new()
                .position(10, 10)
                .attribute(CharAttribute::with_color(Color::White, Color::Black))
                .align(TextAlignment::Left)
                .build();
surface.write_text("Hello World!", &format);

pub fn draw_image( &mut self, x: i32, y: i32, image: &Image, render_options: &RenderOptions, )

Draws an image at the specified position using a RenderOptions structure to decide how to paint it.

Example:

use appcui::prelude::*;
use std::str::FromStr;

let mut surface = Surface::new(100, 50);
let heart = r#"
        |..rr.rr..|
        |.rrrrrrr.|
        |.rrrrrrr.|
        |..rrrrr..|
        |...rrr...|
        |....r....|"#;
let image = Image::from_str(heart).unwrap();
let opt = RenderOptionsBuilder::new()
                               .character_set(image::CharacterSet::LargeBlocks)
                               .build();
surface.draw_image(10, 10, &image, &opt);

pub fn draw_tile<const STORAGE_BYTES: usize>( &mut self, x: i32, y: i32, tile: &BitTile<STORAGE_BYTES>, set_bit_color: Color, unset_bit_color: Color, render_method: BitTileRenderMethod, )

pub fn serialize_to_buffer(&self, output: &mut Vec<u8>)

Serializes the surface to a byte buffer. The buffer will contain the magic number, version, size, and character buffer. The format is as follows:

• Magic number: 3 bytes (SRF)
• Version: 1 byte
• Size: 8 bytes (width and height, each 4 bytes, little-endian)
• Character buffer: for each character:
  • Code: 4 bytes (u32, little-endian)
  • Flags: 2 bytes (u16, little-endian)
  • Foreground color: 1 byte (u8) - in case of RGB colors it will be 17, followed by 3 bytes for the RGB values
  • Background color: 1 byte (u8) - in case of RGB colors it will be 17, followed by 3 bytes for the RGB values

pub fn save(&self, path: &Path) -> Result<(), Error>

Serializes the surface to a byte buffer and saves it to the specified file path.

pub fn from_buffer(buffer: &[u8]) -> Result<Surface, String>

Creates a new surface from a byte buffer. The buffer must contain the magic number, version, size, and character buffer.

pub fn from_file(path: &Path) -> Result<Surface, String>

Creates a new surface from a file. The file must contain the magic number, version, size, and character buffer.