Struct libnotcurses_sys::c_api::ffi::ncplane

#[repr(C)]
pub struct ncplane { /* private fields */ }

Implementations

impl ncplane

NcPlane constructors & destructors

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().

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().

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().

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().

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().

impl ncplane

NcPlane methods: NcAlpha

pub fn fg_alpha(&self) -> NcAlpha

Gets the foreground NcAlpha from this NcPlane, shifted to LSBs.

C style function: ncplane_fg_alpha().

pub fn bg_alpha(&self) -> NcAlpha

Gets the background NcAlpha for this NcPlane, shifted to LSBs.

C style function: ncplane_bg_alpha().

pub fn set_fg_alpha(&mut self, alpha: impl Into<NcAlpha> + Copy) -> NcResult<()>

Sets the foreground NcAlpha from this NcPlane.

C style function: ncplane_set_fg_alpha().

pub fn set_bg_alpha(&mut self, alpha: impl Into<NcAlpha> + Copy) -> NcResult<()>

Sets the background NcAlpha for this NcPlane.

C style function: ncplane_set_bg_alpha().

impl ncplane

NcPlane methods: NcChannel

pub fn channels(&self) -> NcChannels

Gets the current NcChannels from this NcPlane.

C style function: ncplane_channels().

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

Sets the current NcChannels for this NcPlane.

C style function: ncplane_set_channels().

pub fn fchannel(&self) -> NcChannel

Gets the foreground NcChannel from an NcPlane.

C style function: ncplane_fchannel().

pub fn bchannel(&self) -> NcChannel

Gets the background NcChannel from an NcPlane.

C style function: ncplane_bchannel().

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().

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().

pub fn stain(
    &mut self,
    y: Option<u32>,
    x: Option<u32>,
    len_y: Option<u32>,
    len_x: Option<u32>,
    ul: impl Into<NcChannels> + Copy,
    ur: impl Into<NcChannels> + Copy,
    ll: impl Into<NcChannels> + Copy,
    lr: impl Into<NcChannels> + Copy
) -> NcResult<u32>

Sets the given NcChannelss 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().

impl ncplane

NcPlane methods: NcRgb, components & default color

pub fn fg_rgb(&self) -> NcRgb

Gets the foreground NcRgb from this NcPlane, shifted to LSBs.

C style function: ncplane_fg_rgb().

pub fn bg_rgb(&self) -> NcRgb

Gets the background NcRgb from this NcPlane, shifted to LSBs.

C style function: ncplane_bg_rgb().

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().

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().

pub fn fg_default(&self) -> bool

Is this NcPlane’s foreground using the “default foreground color”?

C style function: ncplane_fg_default_p().

pub fn bg_default(&self) -> bool

Is this NcPlane’s background using the “default background color”?

C style function: ncplane_bg_default_p().

pub fn set_fg_default(&mut self)

Uses the default color for the foreground.

C style function: ncplane_set_fg_default().

pub fn set_bg_default(&mut self)

Uses the default color for the background.

C style function: ncplane_set_bg_default().

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().

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().

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().

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().

impl ncplane

NcPlane methods: NcStyle & PaletteIndex

pub fn format(
    &mut self,
    y: Option<u32>,
    x: Option<u32>,
    len_y: Option<u32>,
    len_x: Option<u32>,
    stylemask: impl Into<NcStyle> + Copy
) -> 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().

pub fn styles(&self) -> NcStyle

Returns the current style for this NcPlane.

C style function: ncplane_styles().

pub fn off_styles(&mut self, stylemask: impl Into<NcStyle>)

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

C style function: ncplane_off_styles().

pub fn on_styles(&mut self, stylemask: impl Into<NcStyle>)

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

C style function: ncplane_on_styles().

pub fn set_styles(&mut self, stylemask: impl Into<NcStyle>)

Sets just the specified styles for this NcPlane.

C style function: ncplane_set_styles().

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().

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().

impl ncplane

NcPlane methods: NcCell & strings

pub fn at_cursor(
    &mut self,
    stylemask: &mut NcStyle,
    channels: &mut NcChannels
) -> NcResult<String>

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().

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().

pub fn at_yx(
    &mut self,
    y: u32,
    x: u32,
    stylemask: &mut NcStyle,
    channels: &mut NcChannels
) -> NcResult<String>

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().

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().

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().

pub fn set_base(
    &mut self,
    egc: &str,
    stylemask: impl Into<NcStyle> + Copy,
    channels: impl Into<NcChannels> + Copy
) -> 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().

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().

pub fn contents(
    &mut self,
    beg_y: Option<u32>,
    beg_x: Option<u32>,
    len_y: Option<u32>,
    len_x: Option<u32>
) -> 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).

C style function: ncplane_contents().

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().

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_ 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.

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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.

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().

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)

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)

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().

pub fn putstr_aligned(
    &mut self,
    y: Option<u32>,
    align: impl Into<NcAlign> + Copy,
    string: &str
) -> NcResult<u32>

Writes a string to the provided location, using the current style and NcAligned 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().

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().

pub fn putstr_aligned_stained(
    &mut self,
    y: u32,
    align: impl Into<NcAlign> + Copy,
    string: &str
) -> NcResult<u32>

Writes a string to the provided location, NcAligned 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)

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)

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().

pub fn putnstr_aligned(
    &mut self,
    y: u32,
    align: impl Into<NcAlign> + Copy,
    num_bytes: usize,
    string: &str
) -> NcResult<u32>

Writes a string to the provided location, using the current style, NcAligned 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().

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().

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-connect cells.

Returns the number of cells polyfilled.

An invalid initial y, x is an error.

C style function: ncplane_putnstr_yx().

impl ncplane

NcPlane methods: NcPlane & Nc

pub fn abs_yx(&self) -> (i32, i32)

Gets the origin of this plane relative to its pile.

C style function: ncplane_abs_yx().

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().

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().

pub fn dup(&mut 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().

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().

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().

pub fn move_bottom(&mut self)

Relocates this NcPlane at the bottom of the z-buffer.

C style function: ncplane_move_bottom().

pub fn move_top(&mut self)

Relocates this NcPlane at the top of the z-buffer.

C style function: ncplane_move_top().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

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().

pub fn render_raster(&mut self) -> NcResult<()>

Renders and rasterizes the pile of which this NcPlane is a part.

(No equivalent C style function)

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().

pub fn render_to_file(&mut self, fp: &mut NcFile) -> NcResult<()>

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().

pub unsafe fn notcurses<'a>(&self) -> NcResult<&'a mut Nc>

Gets a mutable reference to the Nc context of this NcPlane.

Safety

You must be careful not to end up with multiple exclusive references to the same Nc context, or with one exclusive reference and one or more shared references.

C style function: ncplane_notcurses().

pub unsafe fn notcurses_const<'a>(&self) -> NcResult<&'a Nc>

Gets an immutable reference to the Nc context of this NcPlane.

Safety

You must be careful not to end up with a mix of exclusive references and shared references to the standard plane.

C style function: ncplane_notcurses_const().

impl ncplane

NcPlane methods: cursor

pub fn cursor_home(&mut self)

Moves the cursor to 0, 0.

C style function: ncplane_home().

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

Returns the current position of the cursor within this NcPlane.

C style function: ncplane_cursor_yx().

pub fn cursor_y(&self) -> u32

Returns the current row of the cursor within this NcPlane.

C style function: ncplane_cursor_y().

pub fn cursor_x(&self) -> u32

Returns the current column of the cursor within this NcPlane.

C style function: ncplane_cursor_x().

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().

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)

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)

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)

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)

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().

impl ncplane

NcPlane methods: size, position & alignment

pub fn halign(
    &self,
    align: impl Into<NcAlign> + Copy,
    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().

pub fn valign(
    &self,
    align: impl Into<NcAlign> + Copy,
    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().

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().

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

Returns the dimensions of this NcPlane.

C style function: ncplane_dim_yx().

pub fn dim_y(&self) -> u32

Returns the rows of this NcPlane.

C style function: ncplane_dim_y().

pub fn dim_x(&self) -> u32

Returns the columns of this NcPlane.

C style function: ncplane_dim_x().

pub fn as_rgba(
    &mut self,
    blitter: impl Into<NcBlitter> + Copy,
    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_yxbeg_x coordinate (which must lie on the plane), continuing for len_yxlen_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().

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().

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().

pub fn resize_marginalized(&mut self) -> NcResult<()>

Suitable for use as a ‘resizecb’ with planes created with [NcPlaneFlag::Marginalized][NcPlaneFlag#associatedconstant.Marginalized].

This will resize this plane against its parent, attempting to enforce the supplied margins.

C style function: ncplane_resize_marginalized().

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().

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().

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().

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().

pub fn resizecb(&self) -> Option<NcResizeCb>

Returns this NcPlane’s current resize callback, or None if not set.

C style function: ncplane_resizecb().

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().

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().

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().

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().

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().

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().

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().

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().

pub fn scrolling_p(&self) -> bool

Returns true if this NcPlane has scrolling enabled, or false otherwise.

C style function: ncplane_scrolling_p().

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().

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().

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().

pub fn autogrow_p(&self) -> bool

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

C style function: ncplane_autogrow_p().

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().

impl ncplane

NcPlane methods: boxes & perimeters

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().

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().

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().

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().

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().

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().

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().

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().

impl ncplane

NcPlane methods: fading, gradients & greyscale

pub fn fadein(&mut self, time: &NcTime, fader: NcFadeCb) -> NcResult<()>

Fades this NcPlane in, over the specified time, calling ‘fader’ at each iteration.

Usage:

1. Load this NcPlane with the target cells without rendering.
2. call this function.

When it’s done, the NcPlane will have reached the target levels, starting from zeroes.

C style function: ncplane_fadein().

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().

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().

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().

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().

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().

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().

pub fn greyscale(&mut self)

Converts this NcPlane’s content to greyscale.

C style function: ncplane_greyscale().

impl ncplane

NcPlane methods: other

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 and max_x.

It is an error not to have sufficient room to draw the qrcode.

C style function: ncplane_qrcode().

Trait Implementations

impl Debug for ncplane

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

Formats the value using the given formatter.