Type Alias libnotcurses_sys::NcPlane
source · pub type NcPlane = ncplane;
Expand description
A drawable Nc
notcurses surface, composed of NcCell
s.
Unites a CellMatrix with an EgcPool (a matrix of NcCells
with a pool
of extended grapheme characters).
type in C: ncplane (struct)
§About planes and piles
A given notcurses context is made up of one or more piles.
A pile is made up of NcPlane
s, totally ordered on a z-axis.
You can’t manage the piles directly, but only the NcPlanes
.
A pile is destroyed when all its planes are destroyed or moved to other piles.
A pile has a top and bottom plane (this might be a single NcPlane
),
and one or more root planes (NcPlane
s which are bound to themselves).
Multiple threads can concurrently operate on distinct piles, rendering or mutating it, while another thread concurrently renders or mutates another.
Each NcPlane
is part of one and only one pile. By default, an NcPlane
is
part of the same pile that contains the NcPlane
to which it is bound.
When an NcPlane
is created without being bound to another NcPlane
, then
it becomes the root plane, top, and bottom of a new pile. As a root plane,
it is bound to itself.
A new pile can also be created by reparenting an NcPlane
to itself,
though if the plane is already a root plane, this is a no-op.
When an NcPlane
is moved to a different pile (whether new or preexisting),
any NcPlane
s which were bound to it are rebound to its previous parent.
If the NcPlane
was a root plane of some pile, any bound planes become root
planes. The new NcPlane
is placed immediately atop its new parent on its
new pile’s z-axis.
When NcPlane::reparent_family
is used, all NcPlanes
bound to the
reparented NcPlane
are moved along with it. Their relative z-order is
maintained.
Rendering reduces a pile of NcPlane
s to a single NcPlane
, proceeding
from the top to the bottom along a pile’s z-axis. The result is a matrix of
NcCell
s. Rasterizing takes this matrix, together with the
current state of the visual area, and produces a stream of optimized control
sequences and EGC
s for the terminal. By writing this stream to the
terminal, the physical display is synced to some pile’s NcPlane
s.
NcPlane.render
performs the first of these tasks for the pile of which
the plane is a part. The output is maintained internally; calling render
again on the same pile will replace this state with a fresh render.
Multiple piles can be concurrently rendered.
NcPlane.rasterize
performs rasterization, and writes the result to the
terminal. It is a blocking call, and only one rasterization operation may
proceed at a time.
It is necessary to call NcPlane.rasterize
to generate any visible output;
the various output calls only draw to the virtual NcPlane
s. Most of the
notcurses statistics
are updated as a result of a render, and screen
geometry is refreshed (similarly to Nc.refresh
) following the render.
§Methods & Associated Functions
Methods:
Aliased Type§
struct NcPlane { /* private fields */ }
Implementations§
source§impl NcPlane
impl NcPlane
§NcPlane constructors & destructors
sourcepub fn new_child<'parent, 'plane, 'opts>(
parent: &'parent mut NcPlane,
options: &'opts NcPlaneOptions
) -> NcResult<&'plane mut NcPlane>
pub fn new_child<'parent, 'plane, 'opts>( parent: &'parent mut NcPlane, options: &'opts NcPlaneOptions ) -> NcResult<&'plane mut NcPlane>
Creates a new NcPlane
child of parent
plane.
Will be placed at the offset y
×x
(relative to the origin of parent
)
and with the specified size.
The number of rows
and cols
must both be positive.
This plane is initially at the top of the z-buffer, as if move_top
had been called on it.
C style function: ncplane_create().
sourcepub fn new_pile<'nc, 'plane, 'opts>(
nc: &'nc mut Nc,
options: &'opts NcPlaneOptions
) -> NcResult<&'plane mut NcPlane>
pub fn new_pile<'nc, 'plane, 'opts>( nc: &'nc mut Nc, options: &'opts NcPlaneOptions ) -> NcResult<&'plane mut NcPlane>
Same as new_child
but creates a new pile.
The returned NcPlane
will be the top, bottom, and root of the new pile.
C style function: ncpile_create().
sourcepub fn new_child_sized<'plane>(
parent: &mut NcPlane,
y: i32,
x: i32,
rows: u32,
cols: u32
) -> NcResult<&'plane mut NcPlane>
pub fn new_child_sized<'plane>( parent: &mut NcPlane, y: i32, x: i32, rows: u32, cols: u32 ) -> NcResult<&'plane mut NcPlane>
Creates a new NcPlane
child of parent
plane.
Will be placed at the offset y
×x
(relative to the origin of parent
)
and with the specified size.
The number of rows
and cols
must both be positive.
C style function: ncplane_create().
sourcepub fn new_pile_sized<'nc, 'plane>(
nc: &'nc mut Nc,
y: i32,
x: i32,
rows: u32,
cols: u32
) -> NcResult<&'plane mut NcPlane>
pub fn new_pile_sized<'nc, 'plane>( nc: &'nc mut Nc, y: i32, x: i32, rows: u32, cols: u32 ) -> NcResult<&'plane mut NcPlane>
Same as new_child_sized
but creates a new pile.
The returned NcPlane
will be the top, bottom, and root of the new pile.
Creates a new NcPlane
child of parent
plane.
C style function: ncpile_create().
sourcepub fn destroy(&mut self) -> NcResult<()>
pub fn destroy(&mut self) -> NcResult<()>
Destroys this NcPlane
.
None of its contents will be visible after the next render call.
It is an error to attempt to destroy the standard plane.
C style function: ncplane_destroy().
source§impl NcPlane
impl NcPlane
§NcPlane methods: NcAlpha
sourcepub fn fg_alpha(&self) -> NcAlpha
pub fn fg_alpha(&self) -> NcAlpha
Gets the foreground NcAlpha
from this NcPlane
, shifted to LSBs.
C style function: ncplane_fg_alpha().
sourcepub fn bg_alpha(&self) -> NcAlpha
pub fn bg_alpha(&self) -> NcAlpha
Gets the background NcAlpha
for this NcPlane
, shifted to LSBs.
C style function: ncplane_bg_alpha().
sourcepub fn set_fg_alpha(&mut self, alpha: impl Into<NcAlpha>) -> NcResult<()>
pub fn set_fg_alpha(&mut self, alpha: impl Into<NcAlpha>) -> NcResult<()>
Sets the foreground NcAlpha
from this NcPlane
.
C style function: ncplane_set_fg_alpha().
sourcepub fn set_bg_alpha(&mut self, alpha: impl Into<NcAlpha>) -> NcResult<()>
pub fn set_bg_alpha(&mut self, alpha: impl Into<NcAlpha>) -> NcResult<()>
Sets the background NcAlpha
for this NcPlane
.
C style function: ncplane_set_bg_alpha().
source§impl NcPlane
impl NcPlane
§NcPlane methods: NcChannel
sourcepub fn channels(&self) -> NcChannels
pub fn channels(&self) -> NcChannels
Gets the current NcChannels
from this NcPlane
.
C style function: ncplane_channels().
sourcepub fn set_channels(&mut self, channels: impl Into<NcChannels>)
pub fn set_channels(&mut self, channels: impl Into<NcChannels>)
Sets the current NcChannels
for this NcPlane
.
C style function: ncplane_set_channels().
sourcepub fn fchannel(&self) -> NcChannel
pub fn fchannel(&self) -> NcChannel
Gets the foreground NcChannel
from an NcPlane
.
C style function: ncplane_fchannel().
sourcepub fn bchannel(&self) -> NcChannel
pub fn bchannel(&self) -> NcChannel
Gets the background NcChannel
from an NcPlane
.
C style function: ncplane_bchannel().
sourcepub fn set_fchannel(&mut self, channel: impl Into<NcChannel>) -> NcChannels
pub fn set_fchannel(&mut self, channel: impl Into<NcChannel>) -> NcChannels
Sets the current foreground NcChannel
for this NcPlane
.
Returns the updated NcChannels
.
C style function: ncplane_set_fchannel().
sourcepub fn set_bchannel(&mut self, channel: impl Into<NcChannel>) -> NcChannels
pub fn set_bchannel(&mut self, channel: impl Into<NcChannel>) -> NcChannels
Sets the current background NcChannel
for this NcPlane
.
Returns the updated NcChannels
.
C style function: ncplane_set_bchannel().
sourcepub fn stain(
&mut self,
y: Option<u32>,
x: Option<u32>,
len_y: Option<u32>,
len_x: Option<u32>,
ul: impl Into<NcChannels>,
ur: impl Into<NcChannels>,
ll: impl Into<NcChannels>,
lr: impl Into<NcChannels>
) -> NcResult<u32>
pub fn stain( &mut self, y: Option<u32>, x: Option<u32>, len_y: Option<u32>, len_x: Option<u32>, ul: impl Into<NcChannels>, ur: impl Into<NcChannels>, ll: impl Into<NcChannels>, lr: impl Into<NcChannels> ) -> NcResult<u32>
Sets the given NcChannels
s throughout the specified region,
keeping content and attributes unchanged.
The upper left corner is at y
, x
, and None
may be
specified to indicate the cursor’s position in that dimension.
The area is specified by ‘len_y’, ‘len_x’, and None
may be specified
to indicate everything remaining to the right and below, respectively.
It is an error for any coordinate to be outside the plane.
Returns the number of cells set, or -1 on failure.
C style function: ncplane_stain().
source§impl NcPlane
impl NcPlane
§NcPlane methods: NcRgb
, components & default color
sourcepub fn fg_rgb(&self) -> NcRgb
pub fn fg_rgb(&self) -> NcRgb
Gets the foreground NcRgb
from this NcPlane
, shifted to LSBs.
C style function: ncplane_fg_rgb().
sourcepub fn bg_rgb(&self) -> NcRgb
pub fn bg_rgb(&self) -> NcRgb
Gets the background NcRgb
from this NcPlane
, shifted to LSBs.
C style function: ncplane_bg_rgb().
sourcepub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>)
pub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>)
Sets the foreground NcRgb
for this NcPlane
.
C style function: ncplane_set_fg_rgb().
sourcepub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>)
pub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>)
Sets the background NcRgb
for this NcPlane
.
C style function: ncplane_set_bg_rgb().
sourcepub fn fg_default(&self) -> bool
pub fn fg_default(&self) -> bool
Is this NcPlane
’s foreground using the “default foreground color”?
C style function: ncplane_fg_default_p().
sourcepub fn bg_default(&self) -> bool
pub fn bg_default(&self) -> bool
Is this NcPlane
’s background using the “default background color”?
C style function: ncplane_bg_default_p().
sourcepub fn set_fg_default(&mut self)
pub fn set_fg_default(&mut self)
Uses the default color for the foreground.
C style function: ncplane_set_fg_default().
sourcepub fn set_bg_default(&mut self)
pub fn set_bg_default(&mut self)
Uses the default color for the background.
C style function: ncplane_set_bg_default().
sourcepub fn set_fg_not_default(&mut self) -> NcChannels
pub fn set_fg_not_default(&mut self) -> NcChannels
Marks the foreground as NOT using the default color.
Returns the new NcChannels
.
C style function: ncplane_set_fg_not_default().
sourcepub fn set_bg_not_default(&mut self) -> NcChannels
pub fn set_bg_not_default(&mut self) -> NcChannels
Marks the background as NOT using the default color.
Returns the new NcChannels
.
C style function: ncplane_set_bg_not_default().
sourcepub fn set_default(&mut self) -> NcChannels
pub fn set_default(&mut self) -> NcChannels
Marks both the foreground and background as using the default color.
Returns the new NcChannels
.
C style function: ncplane_set_default().
sourcepub fn set_not_default(&mut self) -> NcChannels
pub fn set_not_default(&mut self) -> NcChannels
Marks both the foreground and background as NOT using the default color.
Returns the new NcChannels
.
C style function: ncplane_set_not_default().
source§impl NcPlane
impl NcPlane
§NcPlane methods: NcStyle
& PaletteIndex
sourcepub fn format(
&mut self,
y: Option<u32>,
x: Option<u32>,
len_y: Option<u32>,
len_x: Option<u32>,
style: impl Into<NcStyle>
) -> NcResult<u32>
pub fn format( &mut self, y: Option<u32>, x: Option<u32>, len_y: Option<u32>, len_x: Option<u32>, style: impl Into<NcStyle> ) -> NcResult<u32>
Sets the given style throughout the specified region, keeping content and channels unchanged.
The upper left corner is at y
, x
, and None
may be
specified to indicate the cursor’s position in that dimension.
The area is specified by ‘len_y’, ‘len_x’, and None
may be specified
to indicate everything remaining to the right and below, respectively.
It is an error for any coordinate to be outside the plane.
Returns the number of cells set, or -1 on failure.
C style function: ncplane_format().
sourcepub fn styles(&self) -> NcStyle
pub fn styles(&self) -> NcStyle
Returns the current styles for this NcPlane
.
C style function: ncplane_styles().
sourcepub fn off_styles(&mut self, styles: impl Into<NcStyle>)
pub fn off_styles(&mut self, styles: impl Into<NcStyle>)
Removes the specified styles
from this NcPlane
’s existing spec.
C style function: ncplane_off_styles().
sourcepub fn on_styles(&mut self, styles: impl Into<NcStyle>)
pub fn on_styles(&mut self, styles: impl Into<NcStyle>)
Adds the specified styles
to this NcPlane
’s existing spec.
C style function: ncplane_on_styles().
sourcepub fn set_styles(&mut self, styles: impl Into<NcStyle>)
pub fn set_styles(&mut self, styles: impl Into<NcStyle>)
Sets just the specified styles
for this NcPlane
.
C style function: ncplane_set_styles().
sourcepub fn set_fg_palindex(&mut self, palindex: impl Into<NcPaletteIndex>)
pub fn set_fg_palindex(&mut self, palindex: impl Into<NcPaletteIndex>)
Sets this NcPlane
’s foreground NcPaletteIndex
.
Also sets the foreground palette index bit, sets it foreground-opaque, and clears the foreground default color bit.
C style function: ncplane_set_fg_palindex().
sourcepub fn set_bg_palindex(&mut self, palindex: impl Into<NcPaletteIndex>)
pub fn set_bg_palindex(&mut self, palindex: impl Into<NcPaletteIndex>)
Sets this NcPlane
’s background [impl Into<NcPaletteIndex>
].
Also sets the background palette index bit, sets it background-opaque, and clears the background default color bit.
C style function: ncplane_set_bg_palindex().
source§impl NcPlane
impl NcPlane
§NcPlane methods: NcCell
& strings
sourcepub fn at_cursor(
&mut self,
stylemask: &mut NcStyle,
channels: &mut NcChannels
) -> NcResult<String>
Available on crate feature libc
only.
pub fn at_cursor( &mut self, stylemask: &mut NcStyle, channels: &mut NcChannels ) -> NcResult<String>
libc
only.Retrieves the current contents of the NcCell
under the cursor,
returning the EGC
and writing out the NcStyle
and the NcChannels
.
C style function: ncplane_at_cursor().
sourcepub fn at_cursor_cell(&mut self, cell: &mut NcCell) -> NcResult<u32>
pub fn at_cursor_cell(&mut self, cell: &mut NcCell) -> NcResult<u32>
Retrieves the current contents of the NcCell
under the cursor
into cell
. Returns the number of bytes in the EGC
.
This NcCell is invalidated if the associated NcPlane is destroyed.
C style function: ncplane_at_cursor_cell().
sourcepub fn at_yx(
&mut self,
y: u32,
x: u32,
stylemask: &mut NcStyle,
channels: &mut NcChannels
) -> NcResult<String>
Available on crate feature libc
only.
pub fn at_yx( &mut self, y: u32, x: u32, stylemask: &mut NcStyle, channels: &mut NcChannels ) -> NcResult<String>
libc
only.Returns a copy of the current contents of the specified NcCell
.
Writes out the NcStyle
and the NcChannels
.
§Usage
The return represents how the cell will be used during rendering, and thus integrates any base cell where appropriate:
- If called upon the secondary columns of a wide glyph, the EGC will be returned (i.e. this function does not distinguish between the primary and secondary columns of a wide glyph).
- If called on a sprixel plane, its control sequence is returned for all valid locations.
C style function: ncplane_at_yx().
sourcepub fn at_yx_cell(&mut self, y: u32, x: u32, cell: &mut NcCell) -> NcResult<u32>
pub fn at_yx_cell(&mut self, y: u32, x: u32, cell: &mut NcCell) -> NcResult<u32>
Retrieves the current contents of the specified NcCell
into cell
.
Returns the number of bytes in the EGC
.
This NcCell is invalidated if the associated plane is destroyed.
C style function: ncplane_at_yx_cell().
sourcepub fn base(&mut self) -> NcResult<NcCell>
pub fn base(&mut self) -> NcResult<NcCell>
Extracts this NcPlane
’s base NcCell
.
The reference is invalidated if this NcPlane
is destroyed.
C style function: ncplane_base().
sourcepub fn set_base(
&mut self,
egc: &str,
style: impl Into<NcStyle>,
channels: impl Into<NcChannels>
) -> NcResult<u32>
pub fn set_base( &mut self, egc: &str, style: impl Into<NcStyle>, channels: impl Into<NcChannels> ) -> NcResult<u32>
Sets this NcPlane
’s base NcCell
from its components.
Returns the number of bytes copied out of egc
if succesful.
It will be used for purposes of rendering anywhere that the NcPlane
’s
gcluster is 0.
Note that erasing the NcPlane
does not reset the base cell.
C style function: ncplane_set_base().
sourcepub fn set_base_cell(&mut self, cell: &NcCell) -> NcResult<()>
pub fn set_base_cell(&mut self, cell: &NcCell) -> NcResult<()>
Sets this NcPlane
’s base NcCell
.
It will be used for purposes of rendering anywhere that the NcPlane
’s
gcluster is 0.
Note that erasing the NcPlane
does not reset the base cell.
C style function: ncplane_set_base_cell().
sourcepub fn contents(
&mut self,
beg_y: Option<u32>,
beg_x: Option<u32>,
len_y: Option<u32>,
len_x: Option<u32>
) -> NcResult<String>
pub fn contents( &mut self, beg_y: Option<u32>, beg_x: Option<u32>, len_y: Option<u32>, len_x: Option<u32> ) -> NcResult<String>
Creates a flat string from the EGC
’s of the selected region of the
NcPlane
.
Starts at the plane’s beg_y
* beg_x
coordinates (which must lie on
the plane), continuing for len_y
x len_x
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
).
§Errors
If either len_y
or len_x
fall outside the plane’s boundaries.
C style function: ncplane_contents().
sourcepub fn erase(&mut self)
pub fn erase(&mut self)
Erases every NcCell
in this NcPlane
, resetting all attributes to
normal, all colors to the default color, and all cells to undrawn.
All cells associated with this NcPlane
are invalidated, and must not
be used after the call, excluding the base cell. The cursor is homed.
C style function: ncplane_erase().
sourcepub fn erase_region(
&mut self,
beg_y: Option<u32>,
beg_x: Option<u32>,
len_y: i32,
len_x: i32
) -> NcResult<()>
pub fn erase_region( &mut self, beg_y: Option<u32>, beg_x: Option<u32>, len_y: i32, len_x: i32 ) -> NcResult<()>
Erases every cell in the region beginning at (beg_y
, beg_x
) and
having a size (len_y
× len_x
) for non-zero lengths.
If beg_y
and/or beg_x
are None
, the current cursor position
along that axis is used.
A negative len_y
means to move up from the origin, and a negative
len_x
means to move left from the origin. A positive len_y
moves down,
and a positive len_x
moves right.
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.
// For example, on a plane of 20 rows and 10 columns, with the cursor at
// row 10 and column 5, the following would hold:
(None, None, 0, 1) // clears the column to the right of the cursor (col 6)
(None, None, 0, -1) // clears the column to the left of the cursor (col 4)
(None, None, i32::MAX, 0) // clears all rows with or below the cursor (rows 10..19)
(None, None, i32::MIN, 0) // clears all rows with or above the cursor (rows 0..10)
(None, 4, 3, 3) // clears from [row 5, col 4] through [row 7, col 6]
(None, 4, -3, -3) // clears from [row 5, col 4] through [row 3, col 2]
(4, None, 0, 3) // clears columns 5, 6, and 7
(None, None, 0, 0) // clears the plane *if the cursor is in a legal position*
(0, 0, 0, 0) // clears the plane in all cases
See also the erase_region
example.
C style function: ncplane_erase_region().
sourcepub fn putc_yx(&mut self, y: u32, x: u32, cell: &NcCell) -> NcResult<u32>
pub fn putc_yx(&mut self, y: u32, x: u32, cell: &NcCell) -> NcResult<u32>
Replaces the NcCell
at the specified coordinates with the provided
NcCell
, advancing the cursor by its width (but not past the end of
the plane).
The new NcCell
must already be associated with this NcPlane
.
On success, returns the number of columns the cursor was advanced.
If the glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putc_yx().
sourcepub fn putc(&mut self, cell: &NcCell) -> NcResult<u32>
pub fn putc(&mut self, cell: &NcCell) -> NcResult<u32>
Replaces the NcCell
at the current coordinates with the provided
NcCell
, advancing the cursor by its width (but not past the end of
the plane).
The new NcCell
must already be associated with the NcPlane
.
On success, returns the number of columns the cursor was advanced.
If the glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putc().
sourcepub fn putchar(&mut self, ch: char) -> NcResult<u32>
pub fn putchar(&mut self, ch: char) -> NcResult<u32>
Calls putchar_yx
at the current cursor
location.
On success, returns the number of columns the cursor was advanced.
If the glyph can not fit in the current line, it is an error, unless scrolling is enabled.
NOTE: Unlike the original C function, this one accepts any 4-byte char
.
C style function: ncplane_putchar().
sourcepub fn putchar_stained(&mut self, ch: char) -> NcResult<u32>
pub fn putchar_stained(&mut self, ch: char) -> NcResult<u32>
Replaces the NcCell
at the current location with the provided char
,
while retaining the previous style.
On success, returns the number of columns the cursor was advanced.
If the glyph can not fit in the current line, it is an error, unless scrolling is enabled.
NOTE: Unlike the original C function, this one accepts any 4-byte char
.
C style function: ncplane_putchar_stained().
sourcepub fn putchar_yx(&mut self, y: u32, x: u32, ch: char) -> NcResult<u32>
pub fn putchar_yx(&mut self, y: u32, x: u32, ch: char) -> NcResult<u32>
Replaces the NcCell
at the specified coordinates with the provided
char
, using the current style.
On success, returns the number of columns the cursor was advanced.
If the glyph can not fit in the current line, it is an error, unless scrolling is enabled.
NOTE: Unlike the original C function, this one accepts any 4-byte char
.
C style function: ncplane_putchar_yx().
sourcepub fn putegc(&mut self, egc: &str, sbytes: Option<&mut usize>) -> NcResult<u32>
pub fn putegc(&mut self, egc: &str, sbytes: Option<&mut usize>) -> NcResult<u32>
Replaces the NcCell
at the current location with the provided egc
,
using the current style.
Advances the cursor by the width of the cluster (but not past the end of the the plane), and this number is returned on success.
The number of bytes converted from the egc
can be optionally written
to sbytes
.
If the glyph can not fit in the current line, it is an error, unless scrolling is enabled.
NOTE: Unlike the original C function, this one accepts any 4-byte char
.
C style function: ncplane_putegc().
sourcepub fn putegc_yx(
&mut self,
y: Option<u32>,
x: Option<u32>,
egc: &str,
sbytes: Option<&mut usize>
) -> NcResult<u32>
pub fn putegc_yx( &mut self, y: Option<u32>, x: Option<u32>, egc: &str, sbytes: Option<&mut usize> ) -> NcResult<u32>
Replaces the NcCell
at the specified coordinates with the provided
egc
, using the current style.
Advances the cursor by the width of the cluster (but not past the end of the the plane), and this number is returned on success.
The number of bytes converted from the egc
can be optionally written
to sbytes
.
If the glyph can not fit in the current line, it is an error, unless scrolling is enabled.
NOTE: Unlike the original C function, this one accepts any 4-byte char
.
C style function: ncplane_putegc_yx().
sourcepub fn putegc_stained(
&mut self,
egc: &str,
sbytes: Option<&mut usize>
) -> NcResult<u32>
pub fn putegc_stained( &mut self, egc: &str, sbytes: Option<&mut usize> ) -> NcResult<u32>
Replaces the NcCell
at the current location with the provided egc
,
while retaining the previous style.
Advances the cursor by the width of the cluster (but not past the end of the the plane), and this number is returned on success.
The number of bytes converted from the egc
can be optionally written
to sbytes
.
If the glyph can not fit in the current line, it is an error, unless scrolling is enabled.
NOTE: Unlike the original C function, this one accepts any 4-byte char
.
C style function: ncplane_putegc_stained().
sourcepub fn puttext(
&mut self,
y: u32,
align: impl Into<NcAlign>,
string: &str
) -> NcResult<u32>
pub fn puttext( &mut self, y: u32, align: impl Into<NcAlign>, string: &str ) -> NcResult<u32>
Write the specified text to the plane, breaking lines sensibly, beginning at the specified line.
Returns the number of columns written, including the cleared columns.
When breaking a line, the line will be cleared to the end of the plane (the last line will not be so cleared). Leaves the cursor at the end of output. A partial write will be accomplished as far as it can;
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_puttext().
sourcepub fn putstr(&mut self, string: &str) -> NcResult<u32>
pub fn putstr(&mut self, string: &str) -> NcResult<u32>
Writes a string to the current location, using the current style.
Advances the cursor by some positive number of columns (though not beyond the end of the plane), and this number is returned on success.
Newlines are counted as 1 column.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putstr().
sourcepub fn putstrln(&mut self, string: &str) -> NcResult<u32>
pub fn putstrln(&mut self, string: &str) -> NcResult<u32>
Same as putstr
, but it also puts a newline
character at the end.
This will only work if scrolling is enabled in the plane.
(No equivalent C style function)
sourcepub fn putln(&mut self) -> NcResult<u32>
pub fn putln(&mut self) -> NcResult<u32>
Prints a new line character.
This will only work if scrolling is enabled in the plane.
(No equivalent C style function)
sourcepub fn putstr_stained(&mut self, string: &str) -> NcResult<u32>
pub fn putstr_stained(&mut self, string: &str) -> NcResult<u32>
Writes a string to the current location, retaining the previous style.
Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number is returned on success.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putstr_stained().
sourcepub fn putstr_aligned(
&mut self,
y: Option<u32>,
align: impl Into<NcAlign>,
string: &str
) -> NcResult<u32>
pub fn putstr_aligned( &mut self, y: Option<u32>, align: impl Into<NcAlign>, string: &str ) -> NcResult<u32>
Writes a string to the provided location, using the current style
and NcAlign
ed on x.
Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number is returned on success.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putstr_aligned().
sourcepub fn putstr_yx(
&mut self,
y: Option<u32>,
x: Option<u32>,
string: &str
) -> NcResult<u32>
pub fn putstr_yx( &mut self, y: Option<u32>, x: Option<u32>, string: &str ) -> NcResult<u32>
Writes a string to the provided location, using the current style.
Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number is returned on success.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putstr_yx().
sourcepub fn putstr_aligned_stained(
&mut self,
y: Option<u32>,
align: impl Into<NcAlign>,
string: &str
) -> NcResult<u32>
pub fn putstr_aligned_stained( &mut self, y: Option<u32>, align: impl Into<NcAlign>, string: &str ) -> NcResult<u32>
Writes a string to the provided location, NcAlign
ed on x
and retaining the previous style.
Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number is returned on success.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
(No equivalent C style function)
sourcepub fn putstr_yx_stained(
&mut self,
y: u32,
x: u32,
string: &str
) -> NcResult<u32>
pub fn putstr_yx_stained( &mut self, y: u32, x: u32, string: &str ) -> NcResult<u32>
Writes a string to the provided location, while retaining the previous style.
Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number is returned on success.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
(No equivalent C style function)
sourcepub fn putnstr(&mut self, num_bytes: usize, string: &str) -> NcResult<u32>
pub fn putnstr(&mut self, num_bytes: usize, string: &str) -> NcResult<u32>
Writes a string to the current location, using the current style,
and no more than num_bytes
bytes will be written.
Advances the cursor by some positive number of columns (though not beyond the end of the plane), and this number is returned on success.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putnstr().
sourcepub fn putnstr_aligned(
&mut self,
y: Option<u32>,
align: impl Into<NcAlign>,
num_bytes: usize,
string: &str
) -> NcResult<u32>
pub fn putnstr_aligned( &mut self, y: Option<u32>, align: impl Into<NcAlign>, num_bytes: usize, string: &str ) -> NcResult<u32>
Writes a string to the provided location, using the current style,
NcAlign
ed on x, and no more than num_bytes
bytes will be written.
Advances the cursor by some positive number of columns (though not beyond the end of the plane), and this number is returned on success.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putnstr_aligned().
sourcepub fn putnstr_yx(
&mut self,
y: Option<u32>,
x: Option<u32>,
num_bytes: usize,
string: &str
) -> NcResult<u32>
pub fn putnstr_yx( &mut self, y: Option<u32>, x: Option<u32>, num_bytes: usize, string: &str ) -> NcResult<u32>
Writes a string to the provided location, using the current style,
and no more than num_bytes
bytes will be written.
Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number is returned on success.
On error, a non-positive number is returned, indicating the number of columns which were written before the error.
If a glyph can not fit in the current line, it is an error, unless scrolling is enabled.
C style function: ncplane_putnstr_yx().
sourcepub fn polyfill_yx(&mut self, y: u32, x: u32, cell: &NcCell) -> NcResult<usize>
pub fn polyfill_yx(&mut self, y: u32, x: u32, cell: &NcCell) -> NcResult<usize>
Considers the glyph at y
,x
coordinates as the fill target,
and copies cell
to it and to all cardinally-connected cells.
Returns the number of cells polyfilled.
An invalid initial y
, x
is an error.
C style function: ncplane_putnstr_yx().
source§impl NcPlane
impl NcPlane
§NcPlane methods: NcPlane
& Nc
sourcepub fn dup(&self) -> &mut NcPlane
pub fn dup(&self) -> &mut NcPlane
Duplicates this NcPlane
.
The new NcPlane 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, and will be bound to the same parent. Bound planes are not duplicated; the new plane is bound to the current parent, but has no bound planes.
C style function: ncplane_dup().
sourcepub unsafe fn top(&mut self) -> &mut NcPlane
pub unsafe fn top(&mut self) -> &mut NcPlane
Returns the topmost NcPlane
of the current pile.
§Safety
You must be careful not to end up with multiple exclusive references to the plane.
C style function: ncpile_top().
sourcepub unsafe fn bottom<'a>(&mut self) -> &'a mut NcPlane
pub unsafe fn bottom<'a>(&mut self) -> &'a mut NcPlane
Returns the bottommost NcPlane
of the current pile.
§Safety
You must be careful not to end up with multiple exclusive references to the plane.
C style function: ncpile_bottom().
sourcepub fn move_bottom(&mut self)
pub fn move_bottom(&mut self)
Relocates this NcPlane
at the bottom of the z-buffer.
C style function: ncplane_move_bottom().
sourcepub fn move_top(&mut self)
pub fn move_top(&mut self)
Relocates this NcPlane
at the top of the z-buffer.
C style function: ncplane_move_top().
sourcepub fn move_yx(&mut self, y: i32, x: i32) -> NcResult<()>
pub fn move_yx(&mut self, y: i32, x: i32) -> NcResult<()>
Moves this NcPlane
relative to the standard plane, or the plane to
which it is bound.
It is an error to attempt to move the standard plane.
C style function: ncplane_move_yx().
sourcepub fn move_rel(&mut self, rows: i32, cols: i32) -> NcResult<()>
pub fn move_rel(&mut self, rows: i32, cols: i32) -> NcResult<()>
Moves this NcPlane
relative to its current location.
Negative values move up and left, respectively. Pass 0 to hold an axis constant.
It is an error to attempt to move the standard plane.
C style function: ncplane_moverel().
sourcepub fn above(&mut self) -> Option<&mut NcPlane>
pub fn above(&mut self) -> Option<&mut NcPlane>
Returns the NcPlane
above this one, or None if already at the top.
C style function: ncplane_above().
sourcepub fn below(&mut self) -> Option<&mut NcPlane>
pub fn below(&mut self) -> Option<&mut NcPlane>
Returns the NcPlane
below this one, or None if already at the bottom.
C style function: ncplane_below().
sourcepub fn move_above(&mut self, above: &mut NcPlane) -> NcResult<()>
pub fn move_above(&mut self, above: &mut NcPlane) -> NcResult<()>
Relocates this NcPlane
above the above
NcPlane, in the z-buffer.
Returns an error if the current plane is already in the desired location. Both planes must not be the same.
C style function: ncplane_move_above().
sourcepub fn move_below(&mut self, below: &mut NcPlane) -> NcResult<()>
pub fn move_below(&mut self, below: &mut NcPlane) -> NcResult<()>
Relocates this NcPlane
below the below
NcPlane, in the z-buffer.
Returns an error the current plane is already in the desired location. Both planes must not be the same.
C style function: ncplane_move_below().
sourcepub fn move_family_bottom(&mut self)
pub fn move_family_bottom(&mut self)
Splices this plane and its bound planes out of the z-buffer, and reinserts them at the bottom.
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.
C style function: ncplane_move_family_bottom().
sourcepub fn move_family_top(&mut self)
pub fn move_family_top(&mut self)
Splices this plane and its bound planes out of the z-buffer, and reinserts them at the top.
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.
C style function: ncplane_move_family_top().
sourcepub fn move_family_above(&mut self, above: &mut NcPlane) -> NcResult<()>
pub fn move_family_above(&mut self, above: &mut NcPlane) -> NcResult<()>
Splices this plane and its bound planes out of the z-buffer,
and reinserts them above the above
plane.
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.
C style function: ncplane_move_family_below().
sourcepub fn move_family_below(&mut self, below: &mut NcPlane) -> NcResult<()>
pub fn move_family_below(&mut self, below: &mut NcPlane) -> NcResult<()>
Splices this plane and its bound planes out of the z-buffer,
and reinserts them below the below
plane.
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.
C style function: ncplane_move_family_below().
sourcepub fn mergedown(
&mut self,
source: &mut NcPlane,
beg_src_y: Option<u32>,
beg_src_x: Option<u32>,
len_y: Option<u32>,
len_x: Option<u32>,
dst_y: Option<u32>,
dst_x: Option<u32>
) -> NcResult<()>
pub fn mergedown( &mut self, source: &mut NcPlane, beg_src_y: Option<u32>, beg_src_x: Option<u32>, len_y: Option<u32>, len_x: Option<u32>, dst_y: Option<u32>, dst_x: Option<u32> ) -> NcResult<()>
Merges the NcPlane
source
down onto the current NcPlane
(self
).
This is most rigorously defined as “write to self
the frame that would
be rendered were the entire stack made up only of the specified subregion
of source
and, below it, the subregion of self
having the specified
origin.
Use None
for either or all of beg_src_y
and beg_src_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
).
Merging is independent of the position of both planes on the z-axis.
It is an error to define a subregion that is not entirely contained
within source
.
It is an error to define a target origin such that the projected
subregion is not entirely contained within self
.
Behavior is undefined if both planes are equivalent.
self
is modified, but source
remains unchanged.
Neither source
nor self
may have sprixels.
C style function: ncplane_mergedown().
sourcepub fn mergedown_simple(&mut self, source: &mut NcPlane) -> NcResult<()>
pub fn mergedown_simple(&mut self, source: &mut NcPlane) -> NcResult<()>
Merges source
down onto this NcPlane
.
If source
does not intersect, this plane will not be changed,
but it is not an error.
See mergedown
for more information.
C style function: ncplane_mergedown_simple().
sourcepub unsafe fn parent(&mut self) -> NcResult<&mut NcPlane>
pub unsafe fn parent(&mut self) -> NcResult<&mut NcPlane>
Gets the parent to which this NcPlane
is bound, if any.
§Safety
You must be careful not to end up with multiple exclusive references
to the same NcPlane
, or with one exclusive reference and one
or more shared references.
C style function: ncplane_parent().
sourcepub unsafe fn parent_const(&self) -> NcResult<&NcPlane>
pub unsafe fn parent_const(&self) -> NcResult<&NcPlane>
Gets the parent to which this NcPlane
is bound, if any.
§Safety
You must be careful not to end up with multiple exclusive references
to the same NcPlane
, or with one exclusive reference and one
or more shared references.
C style function: ncplane_parent_const().
sourcepub fn reparent<'a>(
&mut self,
newparent: &'a mut NcPlane
) -> NcResult<&'a mut NcPlane>
pub fn reparent<'a>( &mut self, newparent: &'a mut NcPlane ) -> NcResult<&'a mut NcPlane>
Unbounds this NcPlane
from its parent, makes it a bound child of
‘newparent’, and returns itself.
Any planes bound to this NcPlane
are reparented to the previous parent.
If this NcPlane
is equal to newparent
, then becomes the root of a new
pile, unless it is already the root of a pile, in which case this is a
no-op.
The standard plane cannot be reparented.
C style function: ncplane_reparent().
sourcepub fn reparent_family<'a>(
&mut self,
newparent: &'a mut NcPlane
) -> NcResult<&'a mut NcPlane>
pub fn reparent_family<'a>( &mut self, newparent: &'a mut NcPlane ) -> NcResult<&'a mut NcPlane>
Like reparent
, except any bound
planes comes along with this NcPlane
to its new destination.
Their z-order is maintained.
C style function: ncplane_reparent_family().
sourcepub fn rasterize(&mut self) -> NcResult<()>
pub fn rasterize(&mut self) -> NcResult<()>
Makes the physical screen match the last rendered frame from the pile of
which this NcPlane
is a 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).
C style function: ncpile_rasterize().
sourcepub fn render(&mut self) -> NcResult<()>
pub fn render(&mut self) -> NcResult<()>
Renders the pile of which this NcPlane
is a part.
Rendering this pile again will blow away the render. To actually write out the render, call ncpile_rasterize().
C style function: ncpile_render().
sourcepub fn render_raster(&mut self) -> NcResult<()>
pub fn render_raster(&mut self) -> NcResult<()>
Renders and rasterizes the pile of which this NcPlane
is a part.
(No equivalent C style function)
sourcepub fn render_to_buffer(&mut self, buffer: &mut Vec<u8>) -> NcResult<()>
pub fn render_to_buffer(&mut self, buffer: &mut Vec<u8>) -> NcResult<()>
Performs the rendering and rasterization portion of
render
and rasterize
but does not write the resulting buffer out to the terminal.
Using this function, the user can control the writeout process. The returned buffer must be freed by the caller.
C style function: ncpile_render_to_buffer().
sourcepub fn render_to_file(&mut self, fp: &mut NcFile) -> NcResult<()>
Available on crate feature std
only.
pub fn render_to_file(&mut self, fp: &mut NcFile) -> NcResult<()>
std
only.Writes the last rendered frame, in its entirety, to fp
.
If a frame has not yet been rendered, nothing will be written.
C style function: ncpile_render_to_file().
sourcepub unsafe fn notcurses<'a>(&self) -> NcResult<&'a mut Nc>
pub unsafe fn notcurses<'a>(&self) -> NcResult<&'a mut Nc>
Gets a mutable reference to the Nc
context of this NcPlane
.
§Safety
You have now multiple exclusive references to the same notcurses context, congrats!
C style function: ncplane_notcurses().
sourcepub unsafe fn notcurses_const<'a>(&self) -> NcResult<&'a Nc>
pub unsafe fn notcurses_const<'a>(&self) -> NcResult<&'a Nc>
Gets an immutable reference to the Nc
context of this NcPlane
.
§Safety
You have now both exclusive and shared references to the same notcurses context, congrats!
C style function: ncplane_notcurses_const().
source§impl NcPlane
impl NcPlane
§NcPlane methods: cursor
sourcepub fn cursor_home(&mut self)
pub fn cursor_home(&mut self)
Moves the cursor to 0, 0.
C style function: ncplane_home().
sourcepub fn cursor_yx(&self) -> (u32, u32)
pub fn cursor_yx(&self) -> (u32, u32)
Returns the current position of the cursor within this NcPlane
.
C style function: ncplane_cursor_yx().
sourcepub fn cursor_y(&self) -> u32
pub fn cursor_y(&self) -> u32
Returns the current row of the cursor within this NcPlane
.
C style function: ncplane_cursor_y().
sourcepub fn cursor_x(&self) -> u32
pub fn cursor_x(&self) -> u32
Returns the current column of the cursor within this NcPlane
.
C style function: ncplane_cursor_x().
sourcepub fn cursor_move_yx(&mut self, y: u32, x: u32) -> NcResult<()>
pub fn cursor_move_yx(&mut self, y: u32, x: u32) -> NcResult<()>
Moves the cursor to the specified position within this NcPlane
.
The cursor doesn’t need to be visible.
Parameters exceeding the plane’s dimensions will result in an error, and the cursor position will remain unchanged.
C style function: ncplane_cursor_move_yx().
sourcepub fn cursor_move_y(&mut self, y: u32) -> NcResult<()>
pub fn cursor_move_y(&mut self, y: u32) -> NcResult<()>
Moves the cursor to the specified row within this NcPlane
.
(No equivalent C style function)
sourcepub fn cursor_move_x(&mut self, x: u32) -> NcResult<()>
pub fn cursor_move_x(&mut self, x: u32) -> NcResult<()>
Moves the cursor to the specified column within this NcPlane
.
(No equivalent C style function)
sourcepub fn cursor_move_rows(&mut self, rows: i32) -> NcResult<()>
pub fn cursor_move_rows(&mut self, rows: i32) -> NcResult<()>
Moves the cursor the number of rows specified (forward or backwards).
It will error if the target row exceeds the plane dimensions.
(No equivalent C style function)
sourcepub fn cursor_move_cols(&mut self, cols: i32) -> NcResult<()>
pub fn cursor_move_cols(&mut self, cols: i32) -> NcResult<()>
Moves the cursor the number of columns specified (forward or backwards).
It will error if the target column exceeds the plane dimensions.
(No equivalent C style function)
sourcepub fn cursor_move_rel(&mut self, rows: i32, cols: i32) -> NcResult<()>
pub fn cursor_move_rel(&mut self, rows: i32, cols: i32) -> NcResult<()>
Moves the cursor relatively, the number of rows and columns specified (forward or backwards).
It will error if the target row or column exceeds the plane dimensions.
C style function: ncplane_cursor_move_rel().
source§impl NcPlane
impl NcPlane
§NcPlane methods: size, position & alignment
sourcepub fn halign(&self, align: impl Into<NcAlign>, numcols: u32) -> NcResult<u32>
pub fn halign(&self, align: impl Into<NcAlign>, numcols: u32) -> NcResult<u32>
Returns the column at which numcols
columns ought start in order to be
aligned according to align
within this plane.
Returns -
NCRESULT_MAX if
NcAlign::Unaligned
.
C style function: ncplane_halign().
sourcepub fn valign(&self, align: impl Into<NcAlign>, numrows: u32) -> NcResult<u32>
pub fn valign(&self, align: impl Into<NcAlign>, numrows: u32) -> NcResult<u32>
Returns the row at which numrows
rows ought start in order to be
aligned according to align
within this plane.
Returns -
NCRESULT_MAX if
NcAlign::Unaligned
.
C style function: ncplane_valign().
sourcepub fn center_abs(&self) -> (u32, u32)
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.
C style function: ncplane_center_abs().
sourcepub fn dim_yx(&self) -> (u32, u32)
pub fn dim_yx(&self) -> (u32, u32)
Returns the dimensions of this NcPlane
.
C style function: ncplane_dim_yx().
sourcepub fn dim_y(&self) -> u32
pub fn dim_y(&self) -> u32
Returns the rows of this NcPlane
.
C style function: ncplane_dim_y().
sourcepub fn dim_x(&self) -> u32
pub fn dim_x(&self) -> u32
Returns the columns of this NcPlane
.
C style function: ncplane_dim_x().
sourcepub fn as_rgba(
&mut self,
blitter: impl Into<NcBlitter>,
beg_y: Option<u32>,
beg_x: Option<u32>,
len_y: Option<u32>,
len_x: Option<u32>
) -> NcResult<&mut [NcRgba]>
pub fn as_rgba( &mut self, blitter: impl Into<NcBlitter>, beg_y: Option<u32>, beg_x: Option<u32>, len_y: Option<u32>, len_x: Option<u32> ) -> NcResult<&mut [NcRgba]>
Creates an RGBA flat array from the selected region of the plane.
Begins at the plane’s beg_y
xbeg_x
coordinate (which must lie on the
plane), continuing for len_y
xlen_x
cells.
Use None
for either or both 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
).
Only glyphs from the specified blitset may be present.
C style function: ncplane_as_rgba().
sourcepub fn pixel_geom(&self) -> NcPixelGeometry
pub fn pixel_geom(&self) -> NcPixelGeometry
Returns an NcPixelGeometry
structure filled with pixel geometry for
the display region, each cell, and the maximum displayable bitmap.
This function calls notcurses_check_pixel_support, possibly leading to an interrogation of the terminal.
C style function: ncplane_pixel_geom().
sourcepub fn resize(
&mut self,
keep_y: u32,
keep_x: u32,
keep_len_y: u32,
keep_len_x: u32,
off_y: i32,
off_x: i32,
len_y: u32,
len_x: u32
) -> NcResult<()>
pub fn resize( &mut self, keep_y: u32, keep_x: u32, keep_len_y: u32, keep_len_x: u32, off_y: i32, off_x: i32, len_y: u32, len_x: u32 ) -> NcResult<()>
Resizes this NcPlane
.
The four parameters keep_y
, keep_x
, keep_len_y
, and keep_len_x
defines a subset of this NcPlane
to keep unchanged.
This may be a section of size 0.
keep_x
and keep_y
are relative to this NcPlane
. They must specify a
coordinate within the ncplane’s totality. If either of keep_len_y
or
keep_len_x
is non-zero, both must be non-zero.
y_off
and x_off
are relative to keep_y
and keep_x
, and place the
upper-left corner of the resized NcPlane
.
len_y
and len_x
are the dimensions of this NcPlane
after resizing.
len_y
must be greater than or equal to keep_len_y
,
and len_x
must be greater than or equal to keeplenx
.
It is an error to attempt to resize the standard plane.
C style function: ncplane_resize().
sourcepub fn resize_marginalized(&mut self) -> NcResult<()>
pub fn resize_marginalized(&mut self) -> NcResult<()>
Suitable for use as a ‘resizecb’ with planes created with
NcPlaneFlag::Marginalized
.
This will resize this plane against its parent, attempting to enforce the supplied margins.
C style function: ncplane_resize_marginalized().
sourcepub fn resize_maximize(&mut self) -> NcResult<()>
pub fn resize_maximize(&mut self) -> NcResult<()>
Suitable for use as a ‘resizecb’, this will resize the plane to the visual region’s size. It is used for the standard plane.
C style function: ncplane_resize_maximize().
sourcepub fn resize_placewithin(&mut self) -> NcResult<()>
pub fn resize_placewithin(&mut self) -> NcResult<()>
Moves the plane such that it is entirely within its parent, if possible. no resizing is performed.
C style function: ncplane_resize_placewithin().
sourcepub fn resize_realign(&mut self) -> NcResult<()>
pub fn resize_realign(&mut self) -> NcResult<()>
Realigns this NcPlane
against its parent, using the alignment specified
at creation time.
Suitable for use as an NcResizeCb
.
C style function: ncplane_resize_realign().
sourcepub fn resize_simple(&mut self, len_y: u32, len_x: u32) -> NcResult<()>
pub fn resize_simple(&mut self, len_y: u32, len_x: u32) -> NcResult<()>
Resizes this NcPlane
, retaining what data we can (everything, unless we’re
shrinking in some dimension). Keeps the origin where it is.
C style function: ncplane_resize_simple().
sourcepub fn resizecb(&self) -> Option<NcResizeCb>
pub fn resizecb(&self) -> Option<NcResizeCb>
Returns this NcPlane
’s current resize callback, or None
if not set.
C style function: ncplane_resizecb().
sourcepub fn set_resizecb(&mut self, resizecb: Option<NcResizeCb>)
pub fn set_resizecb(&mut self, resizecb: Option<NcResizeCb>)
Replaces this NcPlane
’s existing resize callback (may be None
)
The standard plane’s resize callback may not be changed.
C style function: ncplane_set_resizecb().
sourcepub fn rotate_cw(&mut self) -> NcResult<()>
pub fn rotate_cw(&mut self) -> NcResult<()>
Rotate the plane π/2 radians (90°) clockwise.
This cannot be performed on arbitrary planes, because glyphs cannot be arbitrarily rotated.
The glyphs which can be rotated are limited: line-drawing characters, spaces, half blocks, and full blocks.
The plane must have an even number of columns.
Use the ncvisual rotation for a more flexible approach.
C style function: ncplane_rotate_cw().
sourcepub fn rotate_ccw(&mut self) -> NcResult<()>
pub fn rotate_ccw(&mut self) -> NcResult<()>
Rotate the plane π/2 radians (90°) counter-clockwise.
See rotate_cw
for more information.
C style function: ncplane_rotate_ccw().
sourcepub fn translate(&self, target: &NcPlane, y: &mut i32, x: &mut i32)
pub fn translate(&self, target: &NcPlane, y: &mut i32, x: &mut i32)
Maps the specified coordinates relative to the origin of this NcPlane
,
to the same absolute coordinates relative to the origin of target
.
C style function: ncplane_translate().
sourcepub fn translate_abs(&self, y: &mut i32, x: &mut i32) -> bool
pub fn translate_abs(&self, y: &mut i32, x: &mut i32) -> bool
Returns true if the provided absolute y
/x
coordinates are within
this NcPlane
, or false otherwise.
Either way, translates the absolute coordinates relative to this NcPlane
.
C style function: ncplane_translate_abs().
sourcepub fn yx(&self) -> (i32, i32)
pub fn yx(&self) -> (i32, i32)
Gets the y
, x
origin of this NcPlane
relative to its parent,
or its pile, if it’s a root plane.
C style function: ncplane_yx().
sourcepub fn y(&self) -> i32
pub fn y(&self) -> i32
Gets the y
origin of this NcPlane
relative to its parent,
or its pile, if it’s a root plane.
C style function: ncplane_y().
sourcepub fn x(&self) -> i32
pub fn x(&self) -> i32
Gets the x
origin of this NcPlane
relative to its parent,
or its pile, if it’s a root plane.
C style function: ncplane_x().
sourcepub fn abs_yx(&self) -> (i32, i32)
pub fn abs_yx(&self) -> (i32, i32)
Gets the origin of this plane relative to its pile.
C style function: ncplane_abs_yx().
sourcepub fn abs_y(&self) -> i32
pub fn abs_y(&self) -> i32
Gets the origin of this plane relative to its pile, in the y axis.
C style function: ncplane_abs_y().
sourcepub fn abs_x(&self) -> i32
pub fn abs_x(&self) -> i32
Gets the origin of this plane relative to its pile, in the x axis.
C style function: ncplane_abs_x().
sourcepub fn scrolling_p(&self) -> bool
pub fn scrolling_p(&self) -> bool
Returns true
if this NcPlane
has scrolling enabled, or false
otherwise.
C style function: ncplane_scrolling_p().
sourcepub fn set_scrolling(&mut self, scroll: bool) -> bool
pub fn set_scrolling(&mut self, scroll: bool) -> bool
(Un)Sets the scrolling behaviour of the plane, and returns true if scrolling was previously enabled, of false, if disabled.
All planes are created with scrolling disabled. Attempting to print past the end of a line will stop at the plane boundary, and indicate an error.
On a plane 10 columns wide and two rows high, printing “0123456789” at the origin should succeed, but printing “01234567890” will by default fail at the eleventh character. In either case, the cursor will be left at location 0x10; it must be moved before further printing can take place. I
See also
NcPlaneOptions::
VSCROLL
C style function: ncplane_set_scrolling().
sourcepub fn scrollup(&mut self, n: u32) -> NcResult<u32>
pub fn scrollup(&mut self, n: u32) -> NcResult<u32>
Sends n
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.
C style function: ncplane_scrollup().
sourcepub fn scrollup_child(&mut self, child: &NcPlane) -> NcResult<u32>
pub fn scrollup_child(&mut self, child: &NcPlane) -> NcResult<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).
C style function: ncplane_scrollup_child().
sourcepub fn autogrow_p(&self) -> bool
pub fn autogrow_p(&self) -> bool
Returns true
if this NcPlane
has autogrow enabled, or false
otherwise.
C style function: ncplane_autogrow_p().
sourcepub fn set_autogrow(&mut self, autogrow: bool) -> bool
pub fn set_autogrow(&mut self, autogrow: bool) -> bool
(Un)Sets the automatic growth of the plane to accommodate output.
Returns true if autogrow 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.
C style function: ncplane_set_autogrow().
source§impl NcPlane
impl NcPlane
§NcPlane methods: boxes & perimeters
sourcepub fn box(
&mut self,
ul: &NcCell,
ur: &NcCell,
ll: &NcCell,
lr: &NcCell,
hline: &NcCell,
vline: &NcCell,
stop_y: u32,
stop_x: u32,
boxmask: impl Into<NcBoxMask>
) -> NcResult<()>
pub fn box( &mut self, ul: &NcCell, ur: &NcCell, ll: &NcCell, lr: &NcCell, hline: &NcCell, vline: &NcCell, stop_y: u32, stop_x: u32, boxmask: impl Into<NcBoxMask> ) -> NcResult<()>
Draws a box with its upper-left corner at the current cursor position,
and its lower-right corner at stop_y
* stop_x
.
The 6 cells provided are used to draw the upper-left, ur, ll, and lr corners, then the horizontal and vertical lines.
See NcBoxMask
for information about the border and gradient masks,
and the drawing of corners.
If the gradient bit is not set, the style from the hline/vlline cells is used for the horizontal and vertical lines, respectively.
If the gradient bit is set, the color is linearly interpolated between the two relevant corner cells.
C style function: ncplane_box().
sourcepub fn box_sized(
&mut self,
ul: &NcCell,
ur: &NcCell,
ll: &NcCell,
lr: &NcCell,
hline: &NcCell,
vline: &NcCell,
len_y: u32,
len_x: u32,
boxmask: impl Into<NcBoxMask>
) -> NcResult<()>
pub fn box_sized( &mut self, ul: &NcCell, ur: &NcCell, ll: &NcCell, lr: &NcCell, hline: &NcCell, vline: &NcCell, len_y: u32, len_x: u32, boxmask: impl Into<NcBoxMask> ) -> NcResult<()>
Draws a box with its upper-left corner at the current cursor position,
having dimensions len_y
* len_x
.
The minimum box size is 2x2, and it cannot be drawn off-screen.
See the box
method for more information.
C style function: ncplane_box_sized().
sourcepub fn ascii_box(
&mut self,
stylemask: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
stop_y: u32,
stop_x: u32,
boxmask: impl Into<NcBoxMask>
) -> NcResult<()>
pub fn ascii_box( &mut self, stylemask: impl Into<NcStyle>, channels: impl Into<NcChannels>, stop_y: u32, stop_x: u32, boxmask: impl Into<NcBoxMask> ) -> NcResult<()>
NcPlane.box
with ASCII characters.
C style function: ncplane_ascii_box().
sourcepub fn double_box(
&mut self,
stylemask: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
stop_y: u32,
stop_x: u32,
boxmask: impl Into<NcBoxMask>
) -> NcResult<()>
pub fn double_box( &mut self, stylemask: impl Into<NcStyle>, channels: impl Into<NcChannels>, stop_y: u32, stop_x: u32, boxmask: impl Into<NcBoxMask> ) -> NcResult<()>
NcPlane.box
with the double box-drawing characters.
C style function: ncplane_double_box().
sourcepub fn double_box_sized(
&mut self,
stylemask: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
len_y: u32,
len_x: u32,
boxmask: impl Into<NcBoxMask>
) -> NcResult<()>
pub fn double_box_sized( &mut self, stylemask: impl Into<NcStyle>, channels: impl Into<NcChannels>, len_y: u32, len_x: u32, boxmask: impl Into<NcBoxMask> ) -> NcResult<()>
NcPlane.box_sized
with the double
box-drawing characters.
C style function: ncplane_double_box_sized().
sourcepub fn perimeter(
&mut self,
ul: &NcCell,
ur: &NcCell,
ll: &NcCell,
lr: &NcCell,
hline: &NcCell,
vline: &NcCell,
boxmask: impl Into<NcBoxMask>
) -> NcResult<()>
pub fn perimeter( &mut self, ul: &NcCell, ur: &NcCell, ll: &NcCell, lr: &NcCell, hline: &NcCell, vline: &NcCell, boxmask: impl Into<NcBoxMask> ) -> NcResult<()>
Draws the perimeter around this NcPlane
.
C style function: ncplane_perimeter().
sourcepub fn perimeter_double(
&mut self,
stylemask: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
boxmask: impl Into<NcBoxMask>
) -> NcResult<()>
pub fn perimeter_double( &mut self, stylemask: impl Into<NcStyle>, channels: impl Into<NcChannels>, boxmask: impl Into<NcBoxMask> ) -> NcResult<()>
NcPlane.
perimeter
with the double box-drawing characters.
C style function: ncplane_perimeter_double().
sourcepub fn perimeter_rounded(
&mut self,
stylemask: impl Into<NcStyle>,
channels: impl Into<NcChannels>,
boxmask: impl Into<NcBoxMask>
) -> NcResult<()>
pub fn perimeter_rounded( &mut self, stylemask: impl Into<NcStyle>, channels: impl Into<NcChannels>, boxmask: impl Into<NcBoxMask> ) -> NcResult<()>
NcPlane.
perimeter
with the rounded box-drawing characters.
C style function: ncplane_perimeter_rounded().
source§impl NcPlane
impl NcPlane
§NcPlane methods: fading, gradients & greyscale
sourcepub fn fadein(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult<()>
pub fn fadein(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult<()>
Fades this NcPlane
in, over the specified time, calling ‘fader’ at
each iteration.
Usage:
- Load this
NcPlane
with the target cells without rendering. - call this function.
When it’s done, the NcPlane
will have reached the target levels,
starting from zeroes.
C style function: ncplane_fadein().
sourcepub fn fadein_iteration(
&mut self,
time: &NcTime,
fader: NcFadeCb
) -> NcResult<()>
pub fn fadein_iteration( &mut self, time: &NcTime, fader: NcFadeCb ) -> NcResult<()>
Fades in through ‘iter’ iterations, where ‘iter’ < ‘ncfadectx_iterations(nctx)’.
C style function: ncplane_fadein_iteration().
sourcepub fn fadeout(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult<()>
pub fn fadeout(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult<()>
Fades this NcPlane
out, over the specified time, calling ‘fader’ at
each iteration.
Requires a terminal which supports truecolor, or at least palette modification (if the terminal uses a palette, our ability to fade planes is limited, and affected by the complexity of the rest of the screen).
C style function: ncplane_fadeout().
sourcepub fn fadeout_iteration(
&mut self,
time: &NcTime,
fader: NcFadeCb
) -> NcResult<()>
pub fn fadeout_iteration( &mut self, time: &NcTime, fader: NcFadeCb ) -> NcResult<()>
Fades out through ‘iter’ iterations, where ‘iter’ < ‘ncfadectx_iterations(nctx)’.
C style function: ncplane_fadeout_iteration().
sourcepub fn pulse(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult<()>
pub fn pulse(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult<()>
Pulses this NcPlane
in and out until the callback returns non-zero,
relying on the callback ‘fader’ to initiate rendering.
time
defines the half-period (i.e. the transition from black to full
brightness, or back again).
Proper use involves preparing (but not rendering) the NcPlane
,
then calling this method, which will fade in from black to the
specified colors.
C style function: ncplane_pulse().
sourcepub fn gradient(
&mut self,
y: Option<u32>,
x: Option<u32>,
stop_y: Option<u32>,
stop_x: Option<u32>,
egc: &str,
stylemask: impl Into<NcStyle>,
ul: impl Into<NcChannels>,
ur: impl Into<NcChannels>,
ll: impl Into<NcChannels>,
lr: impl Into<NcChannels>
) -> NcResult<u32>
pub fn gradient( &mut self, y: Option<u32>, x: Option<u32>, stop_y: Option<u32>, stop_x: Option<u32>, egc: &str, stylemask: impl Into<NcStyle>, ul: impl Into<NcChannels>, ur: impl Into<NcChannels>, ll: impl Into<NcChannels>, lr: impl Into<NcChannels> ) -> NcResult<u32>
Draws a gradient with its upper-left corner at the current cursor
position, stopping at stop_y
* stop_x
.
Returns the number of cells filled on success,
or NCRESULT_ERR
on error.
The glyph composed of egc
and stylemask
is used for all cells.
The channels specified by ul
, ur
, ll
, and lr
are composed into
foreground and background gradients.
To do a vertical gradient, ul
ought equal ur
and ll
ought equal
lr
. To do a horizontal gradient, ul
ought equal ll
and ur
ought
equal ul
.
To color everything the same, all four channels should be equivalent. The resulting alpha values are equal to incoming alpha values.
Palette-indexed color is not supported.
Preconditions for gradient operations (error otherwise):
all: only RGB colors, unless all four channels match as default all: all alpha values must be the same 1x1: all four colors must be the same 1xN: both top and both bottom colors must be the same (vertical gradient) Nx1: both left and both right colors must be the same (horizontal gradient)
C style function: ncplane_gradient().
sourcepub fn gradient2x1(
&mut self,
y: Option<u32>,
x: Option<u32>,
len_y: Option<u32>,
len_x: Option<u32>,
ul: impl Into<NcChannel>,
ur: impl Into<NcChannel>,
ll: impl Into<NcChannel>,
lr: impl Into<NcChannel>
) -> NcResult<u32>
pub fn gradient2x1( &mut self, y: Option<u32>, x: Option<u32>, len_y: Option<u32>, len_x: Option<u32>, ul: impl Into<NcChannel>, ur: impl Into<NcChannel>, ll: impl Into<NcChannel>, lr: impl Into<NcChannel> ) -> NcResult<u32>
Does a high-resolution gradient using upper blocks and synced backgrounds.
This doubles the number of vertical gradations, but restricts you to half blocks (appearing to be full blocks).
Returns the number of cells filled on success.
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
).
C style function: ncplane_gradient2x1().
sourcepub fn greyscale(&mut self)
pub fn greyscale(&mut self)
Converts this NcPlane
’s content to greyscale.
C style function: ncplane_greyscale().
source§impl NcPlane
impl NcPlane
§NcPlane methods: other
sourcepub fn qrcode(&mut self, data: &mut [u8]) -> NcResult<(u32, u32, u32)>
pub fn qrcode(&mut self, data: &mut [u8]) -> NcResult<(u32, u32, u32)>
Draws a QR code at the current position on the plane.
A tuple of 3 elements will be returned: (version, max_y, max_x)
.
- The QR code size is (
version
* 4 + 17) columns wide, and ⌈version
* 4 + 17⌉ rows tall. - The properly-scaled values are returned as
max_y
andmax_x
.
It is an error not to have sufficient room to draw the qrcode.
C style function: ncplane_qrcode().