Struct textcanvas::textcanvas::TextCanvas
source · pub struct TextCanvas {
pub output: Surface,
pub screen: Surface,
pub buffer: PixelBuffer,
pub color_buffer: ColorBuffer,
pub text_buffer: TextBuffer,
/* private fields */
}Expand description
Draw to the terminal like an HTML Canvas.
§Examples
use textcanvas::textcanvas::TextCanvas;
let mut canvas = TextCanvas::new(15, 5).unwrap();
assert_eq!(
canvas.repr(),
"Canvas(output=(15×5), screen=(30×20)))"
);
assert_eq!(
(canvas.w(), canvas.h(), canvas.cx(), canvas.cy()),
(29, 19, 15, 10),
);
canvas.stroke_line(0, 0, canvas.w(), canvas.h());
canvas.draw_text(1, 2, "hello, world");
assert_eq!(
canvas.to_string(),
"\
⠑⠢⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠑⠢⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀hello,⠢world⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠢⢄⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠢⢄
"
)§Todo
move_to(),line_to(),stroke()and other JS Canvas primitives.
Fields§
§output: SurfaceProperties of the output surface, whose size is given as parameter to the constructor. One unit in width and in height represents exactly one character on the terminal.
screen: SurfaceProperties of the virtual output surface. This surface benefits from the increase in resolution. One unit in width and in height represents one Braille dot. There are 2 dots per character in width, and 4 per character in height. So this surface is 2× wider and 4× higher than the output surface.
buffer: PixelBufferThe in-memory pixel buffer. This maps 1-to-1 to the virtual screen. Each pixel is this buffer is either on or off.
color_buffer: ColorBufferThe in-memory color buffer. This maps 1-to-1 to the output
buffer (and so to the physical screen). This contains color data
for characters. Screen dots, being part of one output character,
cannot be colored individually. Color is thus less precise than
screen pixels. Note that a call to set_color() is valid for
both pixels and text, but text embeds color in its own buffer,
and does not use this buffer at all. Note also that this buffer
is empty until the first call to set_color(). The first call
to set_color() initializes the buffer and sets
is_colorized() to true.
text_buffer: TextBufferThe in-memory text buffer. This maps 1-to-1 to the output buffer
(and so to the physical screen). This contains regular text
characters. Text is drawn on top of the pixel buffer on a
separate layer. Drawing text does not affect pixels. Pixels and
text do not share the same color buffer either. Color info is
embedded in the text buffer with each character directly. Note
also that this buffer is empty until the first call to
draw_text(). The first call to draw_text() initializes the
buffer and sets is_textual() to True.
Implementations§
source§impl TextCanvas
impl TextCanvas
sourcepub fn new(width: i32, height: i32) -> Result<Self, &'static str>
pub fn new(width: i32, height: i32) -> Result<Self, &'static str>
Create new TextCanvas.
§Errors
If width and height of canvas are < 1×1.
Also, if the pixel resolution of width or height is larger than
65_535 (realistically, should not happen). This is because we
let the user interact with the canvas with i32s. i32 is a
more likely user-type (maths, etc.), and allows for negative
values. Even though they are never displayed, allowing negative
values makes for a nicer API. We handle the complexity for the
user.
sourcepub fn repr(&self) -> String
pub fn repr(&self) -> String
High-level string representation of the canvas.
§Examples
use textcanvas::textcanvas::TextCanvas;
let mut canvas = TextCanvas::new(15, 5).unwrap();
assert_eq!(
canvas.repr(),
"Canvas(output=(15×5), screen=(30×20)))"
);sourcepub fn clear(&mut self)
pub fn clear(&mut self)
Turn all pixels off and remove color and text.
Note: This method does not drop the color and text buffers, it only clears them. No memory is freed, and all references remain valid (buffers are cleared in-place, not replaced).
sourcepub fn is_colorized(&self) -> bool
pub fn is_colorized(&self) -> bool
Whether the canvas can contain colors.
Note: This does not mean that any colors are displayed. This only means the color buffer is active.
§Examples
use textcanvas::textcanvas::{Color, TextCanvas};
let mut canvas = TextCanvas::new(15, 5).unwrap();
assert!(!canvas.is_colorized());
canvas.set_color(&Color::new().to_owned()); // Buffer is initialized.
assert!(canvas.is_colorized());sourcepub fn is_textual(&self) -> bool
pub fn is_textual(&self) -> bool
Whether the canvas can contain text.
Note: This does not mean that any text is displayed. This only means the text buffer is active.
§Examples
use textcanvas::textcanvas::TextCanvas;
let mut canvas = TextCanvas::new(15, 5).unwrap();
assert!(!canvas.is_textual());
canvas.draw_text(0, 0, ""); // Buffer is initialized.
assert!(canvas.is_textual());sourcepub fn set_color(&mut self, color: &Color)
pub fn set_color(&mut self, color: &Color)
Set context color.
§Examples
use textcanvas::textcanvas::{Color, TextCanvas};
let mut canvas = TextCanvas::new(3, 1).unwrap();
let green = Color::new().bright_green().to_owned();
canvas.set_color(&green);
assert!(canvas.is_colorized());
canvas.draw_text(0, 0, "foo");
assert_eq!(
canvas.to_string(),
"\x1b[0;92mf\x1b[0m\x1b[0;92mo\x1b[0m\x1b[0;92mo\x1b[0m\n"
);sourcepub fn get_pixel(&self, x: i32, y: i32) -> Option<bool>
pub fn get_pixel(&self, x: i32, y: i32) -> Option<bool>
Get the state of a screen pixel.
Some(true) if the pixel is turned on, Some(false) if it is
turned off, and None if the coordinates are outside the
bounds of the buffer.
§Arguments
x- Screen X (high resolution).y- Screen Y (high resolution).
sourcepub fn set_pixel(&mut self, x: i32, y: i32, state: bool)
pub fn set_pixel(&mut self, x: i32, y: i32, state: bool)
Set the state of a screen pixel.
Note: Coordinates outside the screen bounds are ignored.
Note: Turning a pixel off also removes color. This side effect does not affect text, as text has a separate color buffer.
§Arguments
x- Screen X (high resolution).y- Screen Y (high resolution).state-truemeans on,falsemeans off.
sourcepub fn draw_text(&mut self, x: i32, y: i32, text: &str)
pub fn draw_text(&mut self, x: i32, y: i32, text: &str)
Draw text onto the canvas.
Note: Coordinates outside the screen bounds are ignored.
Note: Text is rendered on top of pixels, as a separate layer.
Note: set_color() works for text as well, but text does not
share its color buffer with pixels. Rather, color data is stored
with the text characters themselves.
§Arguments
x- Output X (true resolution).y- Output Y (true resolution).text- The text to draw. Spaces are transparent (you see pixels through), and can be used to erase previously drawn characters.
sourcepub fn iter_buffer(&self) -> IterPixelBuffer ⓘ
pub fn iter_buffer(&self) -> IterPixelBuffer ⓘ
Iterate over all cells of the pixel buffer.
Yields all X/Y coordinates, left-right, top-bottom.