Type Definition libnotcurses_sys::NcPlane

type NcPlane = ncplane;

Fundamental drawing surface.

Unites a:

• CellMatrix
• EgcPool

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 NcPlanes, 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 (NcPlanes 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 NcPlanes 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 NcPlanes to a single NcPlane, proceeding from the top to the bottom along a pile’s z-axis. The result is a matrix of NcCells. Rasterizing takes this matrix, together with the current state of the visual area, and produces a stream of optimized control sequences and EGCs for the terminal. By writing this stream to the terminal, the physical display is synced to some pile’s NcPlanes.

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 NcPlanes. Most of the notcurses statistics are updated as a result of a render, and screen geometry is refreshed (similarly to [Notcurses.refresh][crate::Notcurses#method.refresh]) following the render.

Methods & Associated Functions

• Constructors & Destructors

Methods:

• NcAlphaBits
• NcChannel & NcChannels
• NcComponent, NcRgb & default color
• NcStyle & NcPaletteIndex
• NcCell & strings
• cursor
• NcPlane & Notcurses
• boxes & perimeters
• Size, position & alignment
• fading, gradients & greyscale

Implementations

impl NcPlane

NcPlane constructors & destructors

pub fn new<'a>(
    nc: &mut Nc,
    y: NcOffset,
    x: NcOffset,
    rows: NcDim,
    cols: NcDim
) -> NcResult<&'a mut NcPlane>

New NcPlane.

The returned plane will be the top, bottom, and root of this new pile.

C style function: ncpile_create().

pub fn with_options<'a>(
    nc: &mut Nc,
    options: NcPlaneOptions
) -> NcResult<&'a mut NcPlane>

New NcPlane, expects an NcPlaneOptions struct.

The returned plane will be the top, bottom, and root of this new pile.

C style function: ncpile_create().

pub fn new_bound<'a>(
    bound_to: &mut NcPlane,
    y: NcOffset,
    x: NcOffset,
    rows: NcDim,
    cols: NcDim
) -> NcResult<&'a mut NcPlane>

New NcPlane, bound to another NcPlane.

C style function: ncplane_create().

pub fn with_options_bound<'a>(
    bound_to: &mut NcPlane,
    options: NcPlaneOptions
) -> NcResult<&'a mut NcPlane>

New NcPlane, bound to another plane, expects an NcPlaneOptions struct.

C style function: ncplane_create().

pub fn with_termsize<'a>(nc: &mut Nc) -> NcResult<&'a mut NcPlane>

New NcPlane, with the same dimensions of the terminal.

The returned plane will be the top, bottom, and root of this new pile.

(No equivalent C style function)

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: NcAlphaBits

pub fn fg_alpha(&self) -> NcAlphaBits

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

C style function: ncplane_fg_alpha().

pub fn bg_alpha(&self) -> NcAlphaBits

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

C style function: ncplane_bg_alpha().

pub fn set_fg_alpha(&mut self, alpha: NcAlphaBits) -> NcResult<()>

Sets the foreground NcAlphaBits from this NcPlane.

C style function: ncplane_set_fg_alpha().

pub fn set_bg_alpha(&mut self, alpha: NcAlphaBits) -> NcResult<()>

Sets the background NcAlphaBits 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: 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: 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: 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_stop: NcDim,
    x_stop: NcDim,
    ul: NcChannels,
    ur: NcChannels,
    ll: NcChannels,
    lr: NcChannels
) -> NcResult<u32>

Sets the given NcChannelss throughout the specified region, keeping content and attributes unchanged.

Returns the number of cells set.

C style function: ncplane_stain().

impl NcPlane

NcPlane methods: NcComponent, NcRgb & default color

pub fn fg_rgb8(&self) -> (NcComponent, NcComponent, NcComponent)

Gets the foreground RGB NcComponents from this NcPlane.

C style function: ncplane_fg_rgb8().

pub fn bg_rgb8(&self) -> (NcComponent, NcComponent, NcComponent)

Gets the background RGB NcComponents from this NcPlane.

C style function: ncplane_bg_rgb8().

pub fn set_fg_rgb8(
    &mut self,
    red: NcComponent,
    green: NcComponent,
    blue: NcComponent
)

Sets the foreground RGB NcComponents for this NcPlane.

If the terminal does not support directly-specified 3x8b cells (24-bit “TrueColor”, indicated by the “RGB” terminfo capability), the provided values will be interpreted in some lossy fashion.

“HP-like” terminals require setting foreground and background at the same time using “color pairs”; notcurses will manage color pairs transparently.

C style function: ncplane_set_fg_rgb8().

pub fn set_bg_rgb8(
    &mut self,
    red: NcComponent,
    green: NcComponent,
    blue: NcComponent
)

Sets the background RGB NcComponents for this NcPlane.

If the terminal does not support directly-specified 3x8b cells (24-bit “TrueColor”, indicated by the “RGB” terminfo capability), the provided values will be interpreted in some lossy fashion.

“HP-like” terminals require setting foreground and background at the same time using “color pairs”; notcurses will manage color pairs transparently.

C style function: ncplane_set_bg_rgb8().

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: NcRgb)

Sets the foreground NcRgb for this NcPlane.

C style function: ncplane_set_fg_rgb().

pub fn set_bg_rgb(&mut self, rgb: 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_stop: NcDim,
    x_stop: NcDim,
    stylemask: NcStyle
) -> NcResult<NcDim>

Sets the given style throughout the specified region, keeping content and channels unchanged.

Returns the number of cells set.

C style function: ncplane_format().

pub fn styles(&self) -> NcStyle

Returns the current styling for this NcPlane.

C style function: ncplane_styles().

pub fn off_styles(&mut self, stylemask: NcStyle)

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

C style function: ncplane_off_styles().

pub fn on_styles(&mut self, stylemask: NcStyle)

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

C style function: ncplane_on_styles().

pub fn set_styles(&mut self, stylemask: NcStyle)

Sets just the specified styles for this NcPlane.

C style function: ncplane_set_styles().

pub fn set_fg_palindex(&mut self, palindex: 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: NcPaletteIndex)

Sets this NcPlane’s background 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.

This EGC must be freed by the caller.

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: NcDim,
    x: NcDim,
    stylemask: &mut NcStyle,
    channels: &mut NcChannels
) -> NcResult<String>

Retrieves the current contents of the specified NcCell, returning the EGC and writing out the NcStyle and the NcChannels.

This EGC must be freed by the caller.

C style function: ncplane_at_yx().

pub fn at_yx_cell(
    &mut self,
    y: NcDim,
    x: NcDim,
    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: NcStyle,
    channels: 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().

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: NcDim,
    beg_x: NcDim,
    len_y: NcDim,
    len_x: NcDim,
    through_y: bool,
    through_x: bool
) -> 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.

If either through_y or through_x are true, then len_y or len_x, will be respectively ignored, and will go through the boundary of the plane.

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 putc_yx(&mut self, y: NcDim, x: NcDim, cell: &NcCell) -> NcResult<NcDim>

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 the NcPlane.

Returns the number of columns the cursor was advanced.

C style function: ncplane_putc_yx().

pub fn putc(&mut self, cell: &NcCell) -> NcResult<NcDim>

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.

Returns the number of columns the cursor was advanced.

C style function: ncplane_putc().

pub fn putchar(&mut self, ch: char) -> NcResult<NcDim>

Calls putchar_yx at the current cursor location.

Returns the number of columns the cursor was advanced.

C style function: ncplane_putchar().

pub fn putchar_yx(&mut self, y: NcDim, x: NcDim, ch: char) -> NcResult<NcDim>

Replaces the NcCell at the y,x coordinates with the provided 7-bit char, but retain the styling. The current styling of the plane will not be changed.

On success, returns the number of columns the cursor was advanced.

C style function: ncplane_putchar_yx().

pub fn putstr(&mut self, string: &str) -> NcResult<NcDim>

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.

C style function: ncplane_putstr().

pub fn putstrln(&mut self, string: &str) -> NcResult<NcDim>

Same as putstr, but it also tries to move the cursor to the beginning of the next row.

Advances the cursor by some positive number of columns (though not beyond the end of the plane); this number will be returned on success, after calling putln.

On error, a non-positive number is returned, indicating the number of columns which were written before the error.

(No equivalent C style function)

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

Moves the cursor to the beginning of the next row.

(No equivalent C style function)

pub fn putstr_aligned(
    &mut self,
    y: NcDim,
    align: NcAlign,
    string: &str
) -> NcResult<NcDim>

Same as putstr_yx() but NcAligned on x.

C style function: ncplane_putstr_aligned().

pub fn putstr_stained(&mut self, string: &str) -> NcResult<NcDim>

Writes a string to the current location, but retains the styling.

The current styling of the plane will not be changed.

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.

C style function: ncplane_putstr_stained().

pub fn putstr_yx(&mut self, y: NcDim, x: NcDim, string: &str) -> NcResult<NcDim>

Writes a string to the provided location, using the current style.

They will be interpreted as a series of columns.

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.

C style function: ncplane_putstr_yx().

impl NcPlane

NcPlane methods: NcPlane & Nc

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

Gets the origin of this plane relative to its pile.

C style function: ncplane_abs_yx().

pub fn abs_y(&self) -> NcDim

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) -> NcDim

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 fn top(&mut self) -> &mut NcPlane

Returns the topmost NcPlane of the current pile.

C style function: ncpile_top().

pub fn bottom<'a>(&mut self) -> &'a mut NcPlane

Returns the bottommost NcPlane of the current pile.

C style function: ncpile_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_bottom(&mut self)

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

C style function: ncplane_move_bottom().

pub fn move_yx(&mut self, y: NcOffset, x: NcOffset) -> 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: NcOffset, cols: NcOffset) -> 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) -> NcResult<&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) -> NcResult<&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 NCRESULT_ERR 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 NCRESULT_ERR if the current plane is already in the desired location. Both planes must not be the same.

C style function: ncplane_move_below().

pub fn mergedown(
    &mut self,
    source: &mut NcPlane,
    source_y: NcDim,
    source_x: NcDim,
    len_y: NcDim,
    len_x: NcDim,
    target_y: NcDim,
    target_x: NcDim
) -> NcResult<()>

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

Merging is independent of the position of both planes on the z-axis.

It is an error to define a subregion of zero area, or 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 fn parent(&mut self) -> NcResult<&mut NcPlane>

Gets the parent to which this NcPlane is bound, if any.

C style function: ncplane_parent().

pub fn parent_const(&self) -> NcResult<&NcPlane>

Gets the parent to which this NcPlane is bound, if any.

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 notcurses<'a>(&self) -> NcResult<&'a mut Nc>

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

C style function: ncplane_notcurses().

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

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

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) -> (NcDim, NcDim)

Returns the current position of the cursor within this NcPlane.

C style function: ncplane_cursor_yx().

pub fn cursor_y(&self) -> NcDim

Returns the current row of the cursor within this NcPlane.

(No equivalent C style function)

pub fn cursor_x(&self) -> NcDim

Returns the current column of the cursor within this NcPlane.

(No equivalent C style function)

pub fn cursor_move_yx(&mut self, y: NcDim, x: NcDim) -> 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: NcDim) -> NcResult<()>

Moves the cursor to the specified row within this NcPlane.

(No equivalent C style function)

pub fn cursor_move_x(&mut self, x: NcDim) -> NcResult<()>

Moves the cursor to the specified column within this NcPlane.

(No equivalent C style function)

pub fn cursor_move_rows(&mut self, rows: NcOffset) -> 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: NcOffset) -> 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: NcOffset,
    cols: NcOffset
) -> 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.

(No equivalent C style function)

impl NcPlane

NcPlane methods: size, position & alignment

pub fn halign(&mut self, align: NcAlign, cols: NcDim) -> NcResult<()>

Returns the column at which cols columns ought start in order to be aligned according to align within this NcPlane.

Returns -NCRESULT_MAX if NCALIGN_UNALIGNED or invalid NcAlign.

C style function: ncplane_halign().

pub fn valign(&mut self, align: NcAlign, cols: NcDim) -> NcResult<()>

Returns the row at which rows rows ought start in order to be aligned according to align within this NcPlane.

Returns -NCRESULT_MAX if NCALIGN_UNALIGNED or invalid NcAlign.

C style function: ncplane_valign().

pub fn center_abs(&self, y: &mut NcDim, x: &mut NcDim)

C style function: ncplane_center_abs().

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

Returns the dimensions of this NcPlane.

C style function: ncplane_dim_yx().

pub fn dim_y(&self) -> NcDim

Return the rows of this NcPlane.

C style function: ncplane_dim_y().

pub fn dim_x(&self) -> NcDim

Return the columns of this NcPlane.

C style function: ncplane_dim_x().

pub fn rows(&self) -> NcDim

Return the rows of this NcPlane.

Alias of dim_y

C style function: ncplane_dim_y().

pub fn cols(&self) -> NcDim

Return the cols of this NcPlane.

Alias of dim_x

C style function: ncplane_dim_x().

pub fn resize(
    &mut self,
    keep_y: NcDim,
    keep_x: NcDim,
    keep_len_y: NcDim,
    keep_len_x: NcDim,
    y_off: NcOffset,
    x_off: NcOffset,
    y_len: NcDim,
    x_len: NcDim
) -> 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.

y_len and x_len are the dimensions of this NcPlane after resizing. y_len must be greater than or equal to keep_len_y, and x_len 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 NCPLANE_OPTION_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 as_rgba(
    &mut self,
    blitter: NcBlitter,
    beg_y: NcDim,
    beg_x: NcDim,
    len_y: Option<NcDim>,
    len_x: Option<NcDim>
) -> NcResult<&mut [u32]>

Creates an RGBA flat array from the selected region of the plane.

Starts 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 len_y and len_x in order to go through the boundary of the plane in that axis.

Only glyphs from the specified blitset may be present.

C style function: ncplane_rgba().

pub fn pixelgeom(&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_pixelgeom().

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, y_len: NcDim, x_len: NcDim) -> 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.

C style function: ncplane_resizecb().

pub fn set_resizecb(&mut self, resizecb: Option<NcResizeCb>)

Replaces this NcPlane’s existing resize callback (which may be None).

The standard plane’s resizecb may not be changed.

C style function: ncplane_set_resizecb().

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

Rotate the plane π/2 radians 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 counter-clockwise.

See rotate_cw for more information.

C style function: ncplane_rotate_ccw().

pub fn translate(&self, target: &NcPlane, y: &mut NcDim, x: &mut NcDim)

Maps the provided 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 NcDim, x: &mut NcDim) -> 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) -> (NcOffset, NcOffset)

Gets the y, x origin of this NcPlane relative to the standard plane, or the NcPlane to which it is bound.

C style function: ncplane_yx().

pub fn x(&self) -> NcOffset

Gets the x origin of this NcPlane relative to the standard plane, or the NcPlane to which it is bound.

C style function: ncplane_x().

pub fn y(&self) -> NcOffset

Gets the y origin of this NcPlane relative to the standard plane, or the NcPlane to which it is bound.

C style function: ncplane_y().

pub fn scrolling_p(&self) -> bool

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

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

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

C style function: ncplane_set_scrolling().

impl NcPlane

NcPlane methods: boxes & perimeters

pub fn box(
    &mut self,
    ul: &NcCell,
    ur: &NcCell,
    ll: &NcCell,
    lr: &NcCell,
    hline: &NcCell,
    vline: &NcCell,
    y_stop: NcDim,
    x_stop: NcDim,
    boxmask: NcBoxMask
) -> NcResult<()>

Draws a box with its upper-left corner at the current cursor position, and its lower-right corner at y_stop * x_stop.

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 styling 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,
    y_len: NcDim,
    x_len: NcDim,
    boxmask: NcBoxMask
) -> NcResult<()>

Draws a box with its upper-left corner at the current cursor position, having dimensions y_len * x_len. 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 double_box(
    &mut self,
    stylemask: NcStyle,
    channels: NcChannels,
    y_stop: NcDim,
    x_stop: NcDim,
    boxmask: NcBoxMask
) -> NcResult<()>

NcPlane.box() with the double box-drawing characters.

C style function: ncplane_double_box().

pub fn double_box_sized(
    &mut self,
    stylemask: NcStyle,
    channels: NcChannels,
    y_len: NcDim,
    x_len: NcDim,
    boxmask: NcBoxMask
) -> NcResult<()>

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: NcBoxMask
) -> NcResult<()>

Draws the perimeter around this NcPlane.

C style function: ncplane_perimeter().

pub fn perimeter_double(
    &mut self,
    stylemask: NcStyle,
    channels: NcChannels,
    boxmask: NcBoxMask
) -> NcResult<()>

NcPlane.perimeter() with the double box-drawing characters.

C style function: ncplane_perimeter_double().

pub fn perimeter_rounded(
    &mut self,
    stylemask: NcStyle,
    channels: NcChannels,
    boxmask: 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,
    egc: &str,
    stylemask: NcStyle,
    ul: NcChannels,
    ur: NcChannels,
    ll: NcChannels,
    lr: NcChannels,
    y_stop: NcDim,
    x_stop: NcDim
) -> NcResult<NcDim>

Draws a gradient with its upper-left corner at the current cursor position, stopping at y_stop * xstop.

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 gradient_sized(
    &mut self,
    egc: &str,
    stylemask: NcStyle,
    ul: NcChannels,
    ur: NcChannels,
    ll: NcChannels,
    lr: NcChannels,
    y_len: NcDim,
    x_len: NcDim
) -> NcResult<NcDim>

Draw a gradient with its upper-left corner at the current cursor position, having dimensions y_len * x_len.

See gradient for more information.

C style function: ncplane_gradient_sized().

pub fn highgradient(
    &mut self,
    ul: NcChannel,
    ur: NcChannel,
    ll: NcChannel,
    lr: NcChannel,
    y_stop: NcDim,
    x_stop: NcDim
) -> NcResult<NcDim>

Draws a high-resolution gradient using upper blocks and synced backgrounds.

Returns the number of cells filled on success, or NCRESULT_ERR on error.

This doubles the number of vertical gradations, but restricts you to half blocks (appearing to be full blocks).

C style function: ncplane_highgradient().

pub fn highgradient_sized(
    &mut self,
    ul: NcChannel,
    ur: NcChannel,
    ll: NcChannel,
    lr: NcChannel,
    y_stop: NcDim,
    x_stop: NcDim
) -> NcResult<NcDim>

gradient_sized meets highgradient.

C style function: ncplane_highgradient_sized().

pub fn greyscale(&mut self)

Converts this NcPlane’s content to greyscale.

C style function: ncplane_greyscale().