Surface

A surface is a two-dimensional array of Characters that can be displayed on the screen. It is the basic building block of the UI system. Surfaces can be created and manipulated using the Surface class.

A surface has the following properties:

• a clipper area that restricts the drawing operations to a specific region of the surface
• an origin point that is used as the reference point for all drawing operations
• a cursor (that can be moved, enabled or disabled)
• an array (vector) of characters that represent the content of the surface

Remarks: A screen is in fact a surface that covers the entire console visible space and it is created automatically when the application starts.

Creating a Surface

To create a new surface, you can use the method Surface::new() - with two parameters, width and height - that returns a new surface with the specified dimensions. Both width and height must be greater than zero and smaller than 10000. Any value outside this range will be clamped to the nearest valid value.

The surface will be filled with the space character ' ' with a 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 cursor associated with the surface will be disabled.

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface};
let mut surface = Surface::new(100, 50);
}

You can also create a surface from a string with Surface::from_string(). The string is written from position (0, 0) using a White foreground and Black background. New line characters start a new row. If the string is longer than the surface, it is truncated; if it is shorter, the remaining cells stay filled with spaces.

#![allow(unused)]
fn main() {
use appcui::graphics::{Surface, Size};
let surface = Surface::from_string("Hello World!", Size::new(20, 5));
}

The size of a surface (width and height) can be read with size(), which returns a Size object.

Remarks: Creating a surface is rarely needed, as the library will create the main screen surface automatically when the application starts and will provide a mutable reference to that surface whenever the on_paint event is called for a control.

Saving and loading

A surface can be serialized to a compact binary format (magic number SRF) and later restored. This is useful for snapshots, tests, and offline assets.

#![allow(unused)]
fn main() {
use appcui::graphics::Surface;
use std::path::Path;

let surface = Surface::new(40, 12);
surface.save(Path::new("snapshot.srf")).unwrap();
let loaded = Surface::from_file(Path::new("snapshot.srf")).unwrap();
}