Canvas

Represents a surface that can be drawn inside a viewport:

To create a canvas use Canvas::new method (with 3 parameters: a size, a layout and initialization flags).

let b = Canvas::new(Size::new(30,10), layout!("x:10,y:5,w:15"),canvas::Flags::None);

or the macro canvas!

let b1 = canvas!("30x10,x:10,y:5,w:15");
let b2 = canvas!("'30,10',x:10,y:5,w:15");

A canvas supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

Parameter name	Type	Positional parameter	Purpose
`size` or `sz` or `surface`	Size	Yes (first positional parameter)	The size of the surface within the canvas
`flags`	String	No	canvas initialization flags
`back` or `backgroud`	char! format	No	A character as describes in Macro Builds - the same as with the `char!` macro format
`lsm` or `left-scroll-margin`	Numeric	No	The left margin of the bottom scroll bar in characters. If not provided the default value is 0. This should be a positive number and it only has an effect if the flag `Scrollbars` was set up.
`tsm` or `top-scroll-margin`	Numeric	No	The top margin of the right scroll bar in characters. If not provided the default value is 0. This should be a positive number and it only has an effect if the flag `Scrollbars` was set up.

A canvas supports the following initialization flags:

canvas::Flags::ScrollBars or ScrollBars (for macro initialization) - this enable a set of scrollbars that can be used to change the view of the inner surface, but only when the control has focus, as described in Components section.

Some examples that uses these paramateres:

A canvas with a backgroud that consists in the character X in with Aqua and DarkBlue colors.
```
let c = canvas!("size:10x5,x:10,y:5,w:15,back={X,fore:aqua,back:darkblue}");
```

A canvas with scrollbars with different margins

let c = canvas!("sz:'10 x 5',x:10,y:5,w:15,flags:Scrollbars,lsm:5,tsm:1");

Events

A canvas emits no events.

Methods

Besides the Common methods for all Controls a canvas also has the following additional methods:

Method	Purpose
`drawing_surface_mut(...)`	Returns the inner surface that can be dranw into the canvas
`resize_surface(...)`	Resizes the inner surface of the canvas
`set_backgound(...)`	Sets the character used for background
`clear_background()`	Remove the background character making the background transparent.

Key association

The following keys are processed by a canvas control if it has focus:

Key	Purpose
`Left`,`Right`,`Up`,`Down`	Move the viewport to a specified direction by one character.
`Shift+Left`	Moves the horizontal viewport coordinate to 0
`Shift+Up`	Moves the vertical viewport coordinate to 0
`Shift+Right`	Moves the horizontal viewport coordinate so that the right side of the inner surface is displayed
`Shift+Down`	Moves the vertical viewport coordinate so that the bottom side of the inner surface is displayed
`Ctrl`+{`Left`,`Right`,`Up`,`Down`}	Move the viewport to a specified direction by a number of characters that is equal to the width for Left/Right or height for Up/Down.
`PageUp`, `PageDown`	has the same effect as `Ctrl`+{`Up` or `Down`}
`Home`	Moves the viewport to the coordinates (0,0)
`End`	Moves the viewport so that the bottom-right part of the inner surface is visible

Example

The following code uses a canvas to create a viewer over the Rust language definition from wikipedia:

use appcui::prelude::*;

static text: &str = r"--- From Wiki ----
Rust is a multi-paradigm, general-purpose 
programming language that emphasizes performance, 
type safety, and concurrency. It enforces memory 
safety—meaning that all references point to valid 
memory—without a garbage collector. To 
simultaneously enforce memory safety and prevent 
data races, its 'borrow checker' tracks the object 
lifetime of all references in a program during 
compilation. Rust was influenced by ideas from 
functional programming, including immutability, 
higher-order functions, and algebraic data types. 
It is popular for systems programming.

From: https://en.wikipedia.org/wiki/Rust_(programming_language)
";
fn main() -> Result<(), appcui::system::Error> {
    let mut a = App::new().size(Size::new(60,20)).build()?;
    let mut w = window!("Title,a:c,w:40,h:8,flags:Sizeable");
    let mut c = canvas!("'60x15',d:f,flags=ScrollBars,lsm:3,tsm:1");
    let s = c.drawing_surface_mut();
    s.write_string(0, 0, text, CharAttribute::with_color(Color::White, Color::Black), true);
    w.add(c);
    a.add_window(w);
    a.run();
    Ok(())
}