Type Definition libnotcurses_sys::Nc

type Nc = notcurses;

The full notcurses context.

It’s built atop the terminfo abstraction layer to provide reasonably portable vivid character displays.

Implementations

impl Nc

Nc Constructors

pub fn new<'a>() -> NcResult<&'a mut Nc>

New notcurses context (without banners).

pub fn with_banners<'a>() -> NcResult<&'a mut Nc>

New notcurses context, with banners.

This is the default in the C library.

pub fn without_altscreen<'a>() -> NcResult<&'a mut Nc>

New notcurses context, without an alternate screen (nor banners).

pub fn with_flags<'a>(flags: u64) -> NcResult<&'a mut Nc>

New notcurses context, expects NCOPTION_* flags.

pub fn with_options<'a>(options: NcOptions) -> NcResult<&'a mut Nc>

New notcurses context, expects NcOptions.

pub fn with_debug<'a>(loglevel: NcLogLevel, flags: u64) -> NcResult<&'a mut Nc>

New notcurses context, expects NcLogLevel and flags.

impl Nc

Nc methods

pub fn align(availcols: NcDim, align: NcAlign, cols: NcDim) -> NcResult<()>

Returns the offset into availcols at which cols ought be output given the requirements of align.

Returns -NCRESULT_MAX if NCALIGN_UNALIGNED or invalid NcAlign.

C style function: notcurses_align().

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

Retrieves the current contents of the specified NcCell as last rendered, returning the EGC (or None on error) and writing out the NcStyle and the NcChannels.

This EGC must be freed by the caller.

C style function: notcurses_at_yx().

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

Returns the bottommost NcPlane on the standard pile, of which there is always at least one.

C style function: notcurses_bottom().

pub fn canbraille(&self) -> bool

Returns true if we can reliably use Unicode Braille.

See also NCBLIT_BRAILLE.

C style function: notcurses_canbraille().

pub fn canchangecolor(&self) -> bool

Returns true if it’s possible to set the “hardware” palette.

Requires the “ccc” terminfo capability.

C style function: notcurses_canchangecolor().

pub fn canfade(&self) -> bool

Returns true if fading is possible.

Fading requires either the “rgb” or “ccc” terminfo capability.

C style function: notcurses_canfade().

pub fn canhalfblock(&self) -> bool

Returns true if we can reliably use Unicode half blocks.

See also NCBLIT_2x1.

C style function: notcurses_canhalfblock().

pub fn canopen_images(&self) -> bool

Returns true if loading images is possible.

This requires being built against FFmpeg/OIIO.

C style function: notcurses_canopen_images().

pub fn canopen_videos(&self) -> bool

Returns true if loading videos is possible.

This requires being built against FFmpeg.

C style function: notcurses_canopen_videos().

pub fn canquadrant(&self) -> bool

Returns true if we can reliably use Unicode quadrant blocks.

See also NCBLIT_2x2.

C style function: notcurses_canquadrant().

pub fn cansextant(&self) -> bool

Returns true if we can reliably use Unicode 13 sextants.

See also NCBLIT_3x2.

C style function: notcurses_cansextant().

pub fn cantruecolor(&self) -> bool

Returns true if it’s possible to directly specify RGB values per cell, or false if it’s only possible to use palettes.

C style function: notcurses_cantruecolor().

pub fn canutf8(&self) -> bool

Returns true if the encoding is UTF-8.

Requires LANG being set to a UTF-8 locale.

C style function: notcurses_canutf8().

pub fn check_pixel_support(&self) -> NcResult<bool>

Checks for pixel support.

Returns false for no support, or true if pixel output is supported.

This function must successfully return before NCBLIT_PIXEL is available.

Must not be called concurrently with either input or rasterization.

C style function: [notcurses_check_pixel_support()][crate::notcurses_check-pixel_support].

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

Disables the terminal’s cursor, if supported.

Immediate effect (no need for a call to notcurses_render()).

C style function: notcurses_cursor_disable().

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

Enables the terminal’s cursor, if supported, placing it at y, x.

Immediate effect (no need for a call to notcurses_render()). It is an error if y, x lies outside the standard plane.

C style function: notcurses_cursor_enable().

pub fn debug(&mut self, debugfp: &mut NcFile)

Dumps notcurses state to the supplied debugfp.

Output is freeform, and subject to change. It includes geometry of all planes, from all piles.

C style function: notcurses_debug().

pub fn detected_terminal(&self) -> String

Returns the name of the detected terminal.

C style function: notcurses_detected_terminal().

pub fn drop_planes(&mut self)

Destroys all NcPlanes other than the stdplane.

C style function: notcurses_drop_planes().

pub fn getc(
    &mut self,
    time: Option<NcTime>,
    input: Option<&mut NcInput>
) -> NcResult<char>

Returns a char representing a single unicode point.

If an event is processed, the return value is the id field from that event.

Provide a None time to block at length, a time of 0 for non-blocking operation, and otherwise a timespec to bound blocking.

C style function: notcurses_getc().

pub fn getc_nblock(&mut self, input: &mut NcInput) -> char

If no event is ready, returns 0.

C style function: notcurses_getc_nblock().

pub fn getc_blocking(&mut self, input: Option<&mut NcInput>) -> NcResult<char>

Blocks until a codepoint or special key is read, or until interrupted by a signal.

In the case of a valid read, a 32-bit Unicode codepoint is returned.

Optionally writes the event details in input.

C style function: notcurses_getc_blocking().

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

Gets a file descriptor suitable for input event poll()ing.

When this descriptor becomes available, you can call getc_nblock(), and input ought be ready.

This file descriptor is not necessarily the file descriptor associated with stdin (but it might be!).

C style function: notcurses_inputready_fd().

pub fn lex_blitter(blitter_str: &str) -> NcResult<NcBlitter>

Returns an NcBlitter from a string representation.

C style function: notcurses_lex_blitter().

pub fn lex_margins(margins_str: &str, options: &mut NcOptions) -> NcResult<()>

Lexes a margin argument according to the standard notcurses definition.

There can be either a single number, which will define all margins equally, or there can be four numbers separated by commas.

C style function: notcurses_lex_margins().

pub fn lex_scalemode(scalemode_str: &str) -> NcResult<NcScale>

Returns an NcScale from a string representation.

C style function: notcurses_lex_scalemode().

pub fn lex_styles(styles_str: &str) -> NcResult<NcStyle>

Returns an NcStyle from a string representation.

It is case-insensitive, and supports multiple styles separated by spaces.

The supported styles are: italic, underline, undercurl, struck, bold, blink and none.

If a style is are not recognized returns an error.

(No equivalent C style function)

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

Disables signals originating from the terminal’s line discipline, i.e. SIGINT (^C), SIGQUIT (^), and SIGTSTP (^Z). They are enabled by default.

C style function: notcurses_linesigs_disable().

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

Restores signals originating from the terminal’s line discipline, i.e. SIGINT (^C), SIGQUIT (^), and SIGTSTP (^Z), if disabled.

C style function: notcurses_linesigs_enable().

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

Disables mouse events.

Any events in the input queue can still be delivered.

C style function: notcurses_mouse_disable().

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

Enable the mouse in “button-event tracking” mode with focus detection and UTF8-style extended coordinates.

On success, mouse events will be published to getc().

C style function: notcurses_mouse_enable().

pub fn palette_size(&self) -> NcResult<u32>

Returns the number of simultaneous colors claimed to be supported, if there is color support.

Note that several terminal emulators advertise more colors than they actually support, downsampling internally.

C style function: notcurses_palette_size().

pub fn refresh(&mut self) -> NcResult<(NcDim, NcDim)>

Refreshes the physical screen to match what was last rendered (i.e., without reflecting any changes since the last call to render).

Returns the current screen geometry (y, x).

This is primarily useful if the screen is externally corrupted, or if an NCKEY_RESIZE event has been read and you’re not yet ready to render.

C style function: notcurses_refresh().

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

Renders and rasterizes the standard pile in one shot. Blocking call.

C style function: notcurses_render().

pub fn render_to_buffer(&mut self, buffer: &mut Vec<u8>) -> NcResult<()>

Performs the rendering and rasterization portion of render but do not write the resulting buffer out to the terminal.

Using this function, the user can control the writeout process, and render a second frame while writing another.

The returned buffer must be freed by the caller.

C style function: notcurses_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 render has not yet been called, nothing will be written.

C style function: notcurses_render_to_file().

pub fn stats(&mut self, stats: &mut NcStats)

Acquires an atomic snapshot of the notcurses object’s stats.

C style function: notcurses_stats().

pub fn stats_alloc(&mut self) -> &mut NcStats

Allocates an NcStats object.

Use this rather than allocating your own, since future versions of notcurses might enlarge this structure.

C style function: notcurses_stats_alloc().

pub fn stats_reset(&mut self, stats: &mut NcStats)

Resets all cumulative stats (immediate ones, such as fbbytes, are not reset).

C style function: notcurses_stats_reset().

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

Returns a mutable reference to the standard NcPlane for this terminal.

The standard plane always exists, and its origin is always at the uppermost, leftmost cell.

C style function: notcurses_stdplane().

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

Returns a reference to the standard NcPlane for this terminal.

The standard plane always exists, and its origin is always at the uppermost, leftmost cell.

C style function: notcurses_stdplane_const().

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

Destroys the notcurses context.

C style function: notcurses_stop().

pub fn str_blitter(blitter: NcBlitter) -> String

Gets the name of an NcBlitter blitter.

C style function: notcurses_str_blitter().

pub fn str_scalemode(scalemode: NcScale) -> String

Gets the name of an NcScale scaling mode.

C style function: notcurses_str_scalemode().

pub fn str_styles(style: NcStyle) -> String

Gets the lowercase name (or names) of the styles included in an NcStyle.

(No equivalent C style function)

pub fn supported_styles(&self) -> NcStyle

Returns an NcStyle with the supported curses-style attributes.

The attribute is only indicated as supported if the terminal can support it together with color.

For more information, see the “ncv” capability in terminfo(5).

C style function: notcurses_supported_styles().

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

Returns our current idea of the terminal dimensions in rows and cols.

C style function: notcurses_term_dim_yx().

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

Returns the topmost NcPlane, of which there is always at least one.

C style function: notcurses_top().

pub fn version() -> String

Returns a human-readable string describing the running notcurses version.

C style function: notcurses_version().

pub fn version_components() -> (u32, u32, u32, u32)

Returns the running notcurses version components (major, minor, patch, tweak).

C style function: notcurses_version_components().