Struct Plane 

pub struct Plane { /* private fields */ }

A drawable text surface, composed of Cells.

Implementations

impl Plane

constructors

pub fn from_cli(notcurses: &Notcurses) -> Result<Plane>

Returns the cli Plane for the provided notcurses instance.

Returns an error if there’s already one cli plane instantiated.

pub fn from_ncplane(ncplane: &mut NcPlane, notcurses: &Notcurses) -> Plane

Returns a new Plane from an NcPlane, associated to the notcurses context.

pub fn builder() -> PlaneBuilder

Returns a new PlaneBuilder.

pub fn new(nc: &Notcurses) -> Result<Self>

Returns a new root plane with default options.

The plane will be positioned at (0, 0) and have the size of the terminal.

pub fn new_at(nc: &Notcurses, position: impl Into<Position>) -> Result<Self>

Returns a new root plane at a specific position.

The plane will have the size of the terminal.

pub fn new_sized(nc: &Notcurses, size: impl Into<Size>) -> Result<Self>

Returns a new root plane with a specific size.

• size must be greater than 0 in both dimensions.
• The plane will be positioned at (0, 0).

pub fn new_sized_at( nc: &Notcurses, size: impl Into<Size>, position: impl Into<Position>, ) -> Result<Self>

Returns a new root plane with a specific size and position.

size must be greater than 0 in both dimensions.

pub fn new_child(&mut self) -> Result<Plane>

Returns a new child plane with default options.

The plane will be positioned at (0, 0) and have the size of the terminal.

pub fn new_child_at(&mut self, position: impl Into<Position>) -> Result<Plane>

Returns a new child plane at a specific position.

The plane will be terminal sized.

pub fn new_child_sized(&mut self, size: impl Into<Size>) -> Result<Plane>

Returns a new child plane with a specific size.

• size must be greater than 0 in both dimensions.
• The plane will be positioned at (0, 0).

pub fn new_child_sized_at( &mut self, size: impl Into<Size>, position: impl Into<Position>, ) -> Result<Self>

Returns a new child plane with a specific position and size.

size must be greater than 0 in both dimensions.

pub fn duplicate(&self) -> Plane

Duplicates this Plane.

The new plane will have the same geometry, the same rendering state, and all the same duplicated content.

The new plane will be immediately above the old one on the z-axis.

The new plane will be bound to the same parent, but since child planes are not duplicated, it will not have any children planes.

pub fn into_ref(&self) -> &NcPlane

Returns a shared reference to the inner NcPlane.

pub fn into_ref_mut(&mut self) -> &mut NcPlane

Returns an exclusive reference to the inner NcPlane.

impl Plane

the CLI plane

pub fn is_cli(&self) -> bool

Is this plane the CLI plane?

There can only be one.

impl Plane

rendering

pub fn render(&mut self) -> Result<()>

Renders and rasterizes the pile of which this Plane is part.

pub fn render_only(&mut self) -> Result<()>

Just renders the pile of which this Plane is part, without rasterizing.

Rendering this pile again will blow away the render. To actually write out the render, call rasterize afterwards.

pub fn rasterize(&mut self) -> Result<()>

Makes the physical screen match the last rendered frame from the pile of which this Plane is part.

This is a blocking call. Don’t call this before the pile has been rendered (doing so will likely result in a blank screen).

impl Plane

size, geometry

pub fn geometry_best(&self) -> PlaneGeometry

Returns the geometry of the plane, using the best blitter available.

pub fn geometry_with(&self, blitter: Blitter) -> PlaneGeometry

Returns the geometry of the plane, using the provided blitter.

pub fn size(&self) -> Size

Returns the size of the plane.

pub fn resize( &mut self, size: impl Into<Size>, keep: impl Into<Position>, keep_size: impl Into<Size>, offset: impl Into<Position>, ) -> Result<()>

Resizes the plane to a new size.

An area of the plane to keep unchanged is defined by keep and keep_len.

Note that

• keep position is relative to the plane.
• offset position is relative to keep, placing the upper-left-corner of the resized plane.

Errors

• if keep falls outside of the plane.
• if keep_size is zero in just one dimension.
• if size is smaller than keep_size in any dimension.

pub fn resize_simple(&mut self, size: impl Into<Size>) -> Result<()>

Resizes this NcPlane, retaining what data we can (everything, unless we’re shrinking in some dimension). Keeps the origin where it is.

impl Plane

area positioning

pub fn position(&self) -> Position

Returns the current position of this plane, relative to its parent.

In the case of a root (parentless) plane, it will be the same as root_position.

pub fn root_position(&self) -> Position

Returns the root position of this plane, which is relative to the root of the pile this plane is part of.

pub fn move_to(&mut self, position: impl Into<Position>) -> Result<()>

Moves this plane relative to its parent (or to its pile, if it’s a root plane).

pub fn move_rel(&mut self, offset: impl Into<Position>) -> Result<()>

Moves this plane relative to its current position.

• Negative values move up and left, respectively.
• Pass 0 to hold an axis constant.

pub fn place_within(&mut self) -> Result<()>

Moves the plane such that it is entirely within its parent, if possible.

No resizing is performed.

pub fn translate( &self, position: impl Into<Position>, target: &Plane, ) -> Position

Translates a position relative to this plane, into a position relative to the target plane.

Example

    assert_eq![
        Plane::new(&mut nc)?
            .translate((0, 0), &Plane::new_at(&mut nc, (1, 0))?),
        Position::new(-1, 0),
    ];

pub fn translate_root(&self, position: impl Into<Position>) -> (Position, bool)

Translates a position relative to the root, into a position relative to this plane, and checks if it falls inside.

Fields of the returned tuple:

• .0: The translated position, from root to self,
• .1: Is true when position is inside this plane, or false otherwise.

Example

assert_eq![
    Plane::new_at(&mut nc, (8, 8))?.translate_root(Position::new(7, 7)),
    (Position::new(-1, -1), false),
];

impl Plane

z-buffer positioning

pub fn is_top(&mut self) -> bool

Returns true if this plane is at the top of the pile.

pub fn move_top(&mut self)

Relocates this plane at the top of the z-buffer of its pile.

pub fn move_family_top(&mut self)

Relocates this plane and its children at the top of the z-buffer.

Relative order will be maintained between the reinserted planes.

For a plane E bound to C, with z-ordering A B C D E, moving the C family to the top results in C E A B D.

pub fn is_bottom(&mut self) -> bool

Returns true if this plane is at the bottom of the pile.

pub fn move_bottom(&mut self)

Relocates this plane at the bottom of the z-buffer of its pile.

pub fn move_family_bottom(&mut self)

Relocates this plane and its children at the bottom of the z-buffer.

Relative order will be maintained between the reinserted planes.

For a plane E bound to C, with z-ordering A B C D E, moving the C family to the bottom results in A B D C E.

pub fn move_above(&mut self, other: &mut Plane) -> Result<()>

Relocates this plane above other plane, in the z-buffer.

Errors if the current plane is already in the desired location, or if both planes are the same.

pub fn move_family_above(&mut self, other: &mut Plane) -> Result<()>

Relocates this plane and its children above other plane, in the z-buffer.

Errors if the current plane is already in the desired location, or if both planes are the same.

pub fn move_below(&mut self, other: &mut Plane) -> Result<()>

Relocates this plane below other plane, in the z-buffer.

Errors if the current plane is already in the desired location, or if both planes are the same.

pub fn move_family_below(&mut self, other: &mut Plane) -> Result<()>

Relocates this plane abnd its children below the other plane, in the z-buffer.

Errors if the current plane is already in the desired location, or if both planes are the same.

pub fn reparent(&mut self, new_parent: &mut Plane)

Unbounds this plane from its parent and makes it a child of new_parent.

Any child planes of this plane are reparented to the previous parent.

If this plane is equal to new_parent it becomes the root of a new pile, unless it’s already the root of a pile, in which case this is a no-op.

pub fn reparent_family(&mut self, new_parent: &mut Plane)

Unbounds this plane from its parent and makes it a child of new_parent, including its child planes, maintaining their z-order.

If this plane is equal to new_parent it becomes the root of a new pile, unless it’s already the root of a pile, in which case this is a no-op.

impl Plane

alignment, scrolling and growing

pub fn halign(&self, horizontal: Align, width: u32) -> Result<u32>

Returns the column at which width columns ought start in order to be aligned according to h alignment within this plane.

Returns u32::MAX if Align::Unaligned.

pub fn valign(&self, vertical: Align, height: u32) -> Result<u32>

Returns the row at which rows rows ought start in order to be aligned according to v alignment within this plane.

pub fn center_abs(&self) -> (u32, u32)

Finds the center coordinate of a plane.

In the case of an even number of rows/columns the top/left is preferred (in such a case, there will be one more cell to the bottom/right of the center than the top/left). The center is then modified relative to the plane’s origin.

pub fn is_autogrow(&self) -> bool

Returns true if this plane has autogrow enabled, or false otherwise.

pub fn set_autogrow(&mut self, autogrow: bool) -> bool

(Un)Sets the autogrow behaviour of this plane.

Returns true if scrolling was previously enabled or false otherwise.

By default, planes are created with autogrow disabled.

Normally, once output reaches the right boundary of a plane, it is impossible to place more output unless the cursor is first moved.

If scrolling is enabled, the cursor will automatically move down and to the left in this case, but upon reaching the bottom right corner of the plane, it is impossible to place more output without a scrolling event.

If autogrow is in play, the plane will automatically be enlarged to accommodate output. If scrolling is disabled, growth takes place to the right; it otherwise takes place at the bottom.

The plane only grows in one dimension.

pub fn is_scrolling(&self) -> bool

Returns true if this plane has scrolling enabled or false otherwise.

pub fn set_scrolling(&mut self, scrolling: bool) -> bool

Sets the scrolling behaviour of this plane. Returns true if scrolling was previously enabled or false otherwise.

pub fn scroll(&mut self, scroll: u32) -> Result<u32>

Sends a number of scroll events to the current plane.

Returns an error if the current plane is not a scrolling plane, and otherwise returns the number of lines scrolled.

pub fn scroll_child(&mut self, child: &Plane) -> Result<u32>

Scrolls the current plane until child is no longer hidden beneath it.

Returns an error if child is not a child of this plane, or if this plane is not scrolling, or child is fixed.

Returns the number of scrolling events otherwise (might be 0).

impl Plane

cursor related methods

pub fn cursor(&self) -> Position

Returns the current cursor position within this plane.

pub fn cursor_home(&mut self)

Moves the cursor to the home position (0, 0).

pub fn cursor_move_to(&mut self, position: impl Into<Position>) -> Result<()>

Moves the cursor to the specified position within this plane.

The cursor doesn’t need to be visible.

Errors if the coordinates exceed the plane’s dimensions, and the cursor will remain unchanged in that case.

pub fn cursor_move_to_row(&mut self, row: u32) -> Result<()>

Moves the cursor to the specified row within this plane.

The cursor doesn’t need to be visible.

Errors if the row number exceed the plane’s rows, and the cursor will remain unchanged in that case.

pub fn cursor_move_to_col(&mut self, column: u32) -> Result<()>

Moves the cursor to the specified column within this plane.

The cursor doesn’t need to be visible.

Errors if the column number exceed the plane’s columns, and the cursor will remain unchanged in that case.

impl Plane

text and cells

pub fn erase(&mut self)

Erases every Cell in this plane.

The cursor is homed. Resets all attributes to normal, all colors to the default color, and all cells to undrawn.

pub fn erase_region( &mut self, beg_x: Option<u32>, beg_y: Option<u32>, len_x: i32, len_y: i32, ) -> Result<()>

Erases every Cell in the region beginning at some (beg_x, beg_y) and having some size (len_x, len_y) for non-zero lengths.

If beg_x and/or beg_y are None, the current cursor position along that axis is used.

• A negative len_x means to move left from the origin, a positive len_x moves right.
• A negative len_y means to move up from the origin, and a positive len_y moves down.

A value of 0 for the length erases everything along that dimension.

Errors

It is an error if the starting coordinate is not in the plane, but the ending coordinate may be outside the plane.

pub fn contents(&mut self) -> Result<String>

Returns a String from all the plane graphemes.

pub fn contents_region( &mut self, beg_x: Option<u32>, beg_y: Option<u32>, len_x: Option<u32>, len_y: Option<u32>, ) -> Result<String>

Returns a String from the graphemes of the selected region of the plane.

Starts at the plane’s beg_x * beg_y coordinates (which must lie on the plane), continuing for len_x x len_y cells.

Use None for either or all of beg_y and beg_x in order to use the current cursor position along that axis.

Use None for either or both of len_y and len_x in order to go through the boundary of the plane in that axis (same as 0).

pub fn putstr(&mut self, string: &str) -> Result<u32>

Writes a string to the current cursor position, using the current style.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

Example

assert_eq![11, plane.putstr("hello world")?];

pub fn putstrln(&mut self, string: &str) -> Result<u32>

Writes a string to the current cursor position, ending in newline, and using the current style.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

Example

plane.set_scrolling(true);
assert_eq![12, plane.putstrln("hello world")?];

pub fn putln(&mut self) -> Result<u32>

Writes a newline to the current cursor position.

A newline counts as 1 column advanced.

pub fn putstr_aligned( &mut self, y: Option<u32>, horizontal: Align, string: &str, ) -> Result<u32>

Writes a string to some y, and a horizontal alignment, using the current style.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn putstr_stained(&mut self, string: &str) -> Result<u32>

Writes a string to the current position, using the pre-existing style.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn putstr_aligned_stained( &mut self, y: Option<u32>, horizontal: Align, string: &str, ) -> Result<u32>

Writes a string to y, and horizontal alignment, using the pre-existing style.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn putstr_at( &mut self, position: impl Into<Position>, string: &str, ) -> Result<u32>

Writes a string to position, using the current style.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn putstr_at_xy( &mut self, x: Option<u32>, y: Option<u32>, string: &str, ) -> Result<u32>

Writes a string to some y, some x, or both, using the current style.

Returns the number of columns the cursor has advanced.

It wont move over a axis that is set to None.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn putstr_len(&mut self, len: usize, string: &str) -> Result<u32>

Writes a string to the current cursor position, using the current style, and no more than len bytes will be written.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn putstr_len_at( &mut self, position: impl Into<Position>, len: usize, string: &str, ) -> Result<u32>

Writes a string to some position, using the current style, and no more than len bytes will be written.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn putstr_len_at_xy( &mut self, x: Option<u32>, y: Option<u32>, len: usize, string: &str, ) -> Result<u32>

Writes a string to some y, some x, using the current style, and no more than len bytes will be written.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn putstr_len_aligned( &mut self, y: Option<u32>, horizontal: Align, len: usize, string: &str, ) -> Result<u32>

Writes a string to some y, and a horizontal alignment, using the current style, and no more than len bytes will be written.

Returns the number of columns the cursor has advanced.

Errors

• if the position falls outside the plane’s area.
• if a glyph can’t fit in the current line, unless scrolling is enabled.

pub fn polyfill_xy( &mut self, position: impl Into<Position>, cell: &Cell, ) -> Result<usize>

Considers the glyph at position as the fill target, and copies cell to it and to all cardinally-connected cells.

Returns the number of cells polyfilled.

Errors if the position falls outside the plane’s area.

pub fn cell_at(&mut self, position: impl Into<Position>) -> Result<Cell>

Returns the cell at position.

impl Plane

colors, palette & styles

pub fn channels(&self) -> Channels

Gets the channels.

pub fn fg(&self) -> Channel

Gets the foreground channel.

pub fn bg(&self) -> Channel

Gets the foreground channel.

pub fn set_channels(&mut self, channels: impl Into<Channels>)

Sets the channels.

pub fn set_fg(&mut self, foreground: impl Into<Channel>) -> Channels

Sets the foreground channel. Returns the updated channels.

pub fn set_bg(&mut self, background: impl Into<Channel>) -> Channels

Sets the background channel. Returns the updated channels.

pub fn unset_bg(&mut self) -> Channels

Sets the background channel to the default. Returns the updated channels.

pub fn unset_fg(&mut self) -> Channels

Sets the foreground channel to the default. Returns the updated channels.

pub fn set_fg_palindex(&mut self, palindex: impl Into<u8>)

Sets this Plane’s foreground Palette index.

Also sets the foreground palette index bit, sets it foreground-opaque, and clears the foreground default color bit.

pub fn set_bg_palindex(&mut self, palindex: impl Into<u8>)

Sets this Plane’s background Palette index.

Also sets the background palette index bit, sets it foreground-opaque, and clears the foreground default color bit.

pub fn styles(&self) -> Style

Returns the current styles for this Plane.

pub fn off_styles(&mut self, styles: impl Into<Style>)

Removes the specified styles from this Plane’s existing spec.

pub fn on_styles(&mut self, styles: impl Into<Style>)

Adds the specified styles to this NcPlane’s existing spec.

pub fn set_styles(&mut self, styles: impl Into<Style>)

Sets just the specified styles for this NcPlane.

impl Plane

base cell

pub fn base(&mut self) -> Result<Cell>

Returns this plane’s base Cell.

pub fn set_base( &mut self, egc: &str, style: Style, channels: impl Into<Channels>, ) -> Result<usize>

Sets the plane’s base Cell from its components.

Returns the number of bytes copied out of egc.

The base cell shows anywhere in the plane with an empty egc.

Note that erasing the plane does not reset the base cell.

pub fn set_base_styles(&mut self, styles: Style) -> Result<Style>

Sets the plane’s base cell’s styles,

Returns the previous value.

pub fn set_base_channels( &mut self, channels: impl Into<Channels>, ) -> Result<Channels>

Sets the plane’s base cell’s foreground & background channels.

Returns the previous value.

pub fn set_base_fg(&mut self, foreground: impl Into<Channel>) -> Result<Channel>

Sets the plane’s base cell’s foreground channel.

Returns the previous value.

pub fn set_base_bg(&mut self, background: impl Into<Channel>) -> Result<Channel>

Sets the plane’s base cell’s background channel.

Returns the previous value.

Trait Implementations

impl Clone for Plane

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Plane

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Plane

fn drop(&mut self)

Executes the destructor for this type.