Struct notcurses::sys::c_api::notcurses

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

Implementations

impl notcurses

Nc Constructors and destructors

pub unsafe fn new<'a>() -> Result<&'a mut notcurses, NcError>

New notcurses context.

Has the SuppressBanners flag enabled.

Safety

You can’t have multiple simultaneous Nc instances in the same thread.

pub unsafe fn new_cli<'a>() -> Result<&'a mut notcurses, NcError>

New notcurses context in CLI mode.

Has the CliMode and SuppressBanners flags enabled.

Safety

You can’t have multiple simultaneous Nc instances in the same thread.

pub unsafe fn with_banners<'a>() -> Result<&'a mut notcurses, NcError>

New notcurses context, with banners.

It prints the version information banner at initialization and the performance information banner at finalization.

Safety

You can’t have multiple simultaneous Nc instances in the same thread.

pub unsafe fn with_banners_cli<'a>() -> Result<&'a mut notcurses, NcError>

New notcurses context in CLI mode, with banners.

It prints the version information banner at initialization and the performance information banner at finalization.

It has the CliMode flag enabled.

Safety

You can’t have multiple simultaneous Nc instances in the same thread.

pub unsafe fn with_flags<'a>(
    flags: impl Into<NcFlag>
) -> Result<&'a mut notcurses, NcError>

New notcurses context, expecting flags.

Safety

You can’t have multiple simultaneous Nc instances in the same thread.

pub unsafe fn with_flags_log<'a>(
    flags: impl Into<NcFlag>,
    log_level: impl Into<NcLogLevel>
) -> Result<&'a mut notcurses, NcError>

New notcurses context, expects flags and log_level.

Safety

You can’t have multiple simultaneous Nc instances in the same thread.

pub unsafe fn with_options<'a>(
    options: notcurses_options
) -> Result<&'a mut notcurses, NcError>

New notcurses context, expects NcOptions.

Safety

You can’t have multiple simultaneous Nc instances in the same thread.

pub unsafe fn stop(&mut self) -> Result<(), NcError>

Destroys the notcurses context.

Safety

You must not call this method repeatedly on the same Nc instance.

C style function: notcurses_stop().

impl notcurses

Nc methods

pub fn align(
    availcols: u32,
    align: impl Into<NcAlign>,
    cols: u32
) -> Result<u32, NcError>

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

Returns -NCRESULT_MAX if NcAlign::Unaligned.

C style function: notcurses_align().

pub fn at_yx(
    &mut self,
    y: u32,
    x: u32,
    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.

C style function: notcurses_at_yx().

pub fn capabilities(&self) -> nccapabilities

Returns the detected capabilities of the current terminal.

C style function: notcurses_capabilities().

pub fn canbraille(&self) -> bool

Returns true if we can reliably use Unicode Braille.

See also NcBlitter::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 NcBlitter::Half.

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 canpixel(&self) -> bool

Returns true if we can blit pixel-accurate bitmaps.

See also check_pixel_support.

C style function: notcurses_canpixel().

pub fn canquadrant(&self) -> bool

Returns true if we can reliably use Unicode quadrant blocks.

See also NcBlitter::Quadrant.

C style function: notcurses_canquadrant().

pub fn cansextant(&self) -> bool

Returns true if we can reliably use Unicode 13 sextants.

See also NcBlitter::Sextant.

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

Checks for pixel support.

Returns NcPixelImpl with a non-zero constant corresponding to some pixel-blitting mechanism if bitmap support (via any mechanism) has been detected, or else 0 (NCPIXEL_NONE).

C style function: notcurses_check_pixel_support().

pub fn default_foreground(&self) -> Option<NcRgb>

Returns the default foreground color, if it is known.

pub fn default_background(&self) -> Option<NcRgb>

Returns the default background color, if it is known.

pub fn cursor_disable(&mut self) -> Result<(), NcError>

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: u32, x: u32) -> Result<(), NcError>

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 enter_alternate_screen(&mut self) -> Result<(), NcError>

Shifts to the alternate screen, if available.

If already using the alternate screen, this returns Ok(()) immediately.

If the alternate screen is not available, returns an Error immediately.

Entering the alternate screen turns off scrolling for the standard plane.

C style function: notcurses_enter_alternate_screen().

pub fn leave_alternate_screen(&mut self) -> Result<(), NcError>

Exits the alternate screen.

Immediately returns Ok(()) if not currently using the alternate screen.

C style function: notcurses_leave_alternate_screen().

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 accountname() -> String

Returns the name of the user under which we are running.

C style function: notcurses_accountname().

pub fn hostname() -> String

Returns the name of the local hostname.

C style function: notcurses_hostname().

pub fn detected_terminal(&self) -> String

Returns the name of the detected terminal.

C style function: notcurses_detected_terminal().

pub fn osversion(&self) -> String

Returns the name of the detected OS version.

C style function: notcurses_osversion().

pub fn drop_planes(&mut self)

Destroys all NcPlanes other than the stdplane.

C style function: notcurses_drop_planes().

pub fn get(
    &mut self,
    time: Option<timespec>,
    input: Option<&mut ncinput>
) -> Result<NcReceived, NcError>

Reads input.

Provide None in time to block at length, and otherwise Some(NcTime) to bound blocking.

time is an a delay bound against CLOCK_MONOTONIC (see pthread_cond_clockwait(3)).

C style function: notcurses_get().

pub fn get_blocking(
    &mut self,
    input: Option<&mut ncinput>
) -> Result<NcReceived, NcError>

Reads input blocking until an event is processed or a signal is received.

Will optionally write the event details in input.

C style function: notcurses_get_blocking().

pub fn get_nblock(
    &mut self,
    input: Option<&mut ncinput>
) -> Result<NcReceived, NcError>

Reads input without blocking.

C style function: notcurses_get_nblock().

pub fn getvec(
    &mut self,
    time: Option<timespec>,
    ni: &mut Vec<ncinput, Global>,
    vcount: u32
) -> Result<u32, NcError>

Acquire up to ‘vcount’ NcInputs at the vector ‘ni’.

The number read will be returned, or 0 on timeout.

C style function: notcurses_getvec().

pub fn inputready_fd(&mut self) -> Result<i32, NcError>

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

When this descriptor becomes available, you can call get_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) -> Result<NcBlitter, NcError>

Returns an NcBlitter from a string representation.

C style function: notcurses_lex_blitter().

pub fn lex_margins(
    margins_str: &str,
    options: &mut notcurses_options
) -> Result<(), NcError>

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(scale_str: &str) -> Result<NcScale, NcError>

Returns an NcScale from a string representation.

C style function: notcurses_lex_scalemode().

pub fn lex_styles(styles_str: &str) -> Result<NcStyle, NcError>

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, and none.

If a style is are not recognized returns an error.

(No equivalent C style function)

pub fn linesigs_disable(&mut self) -> Result<(), NcError>

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) -> Result<(), NcError>

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 mice_disable(&mut self) -> Result<(), NcError>

Disables mice events.

C style function: notcurses_mice_disable().

pub fn mice_enable(&mut self, eventmask: NcMiceEvents) -> Result<(), NcError>

Enables mice events according to eventmask.

An eventmask of 0 will disable all mice tracking.

On success mouse events will be published to notcurses_get.

C style function: notcurses_mice_enable().

pub fn palette_size(&self) -> Result<u32, NcError>

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) -> Result<(u32, u32), NcError>

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) -> Result<(), NcError>

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

C style function: notcurses_render().

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

Safety

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

C style function: notcurses_stdplane().

pub unsafe 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.

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

pub fn str_blitter(blitter: impl Into<NcBlitter>) -> String

Gets the name of an NcBlitter blitter.

C style function: notcurses_str_blitter().

pub fn str_scalemode(scale: impl Into<NcScale>) -> String

Gets the name of an NcScale scaling mode.

C style function: notcurses_str_scalemode().

pub fn str_styles(style: impl Into<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) -> (u32, u32)

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

C style function: notcurses_term_dim_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 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().

pub fn visual_geom(
    &self,
    visual: Option<&ncvisual>,
    vopts: Option<&ncvisual_options>
) -> Result<NcVisualGeometry, NcError>

Returns NcVisualGeometry.

If an NcVisual is not provided, only the cdim_yx, blitter, scale_yx, and maxpixel_yx fields will be filled in.

If an NcVisualOptions is not provided, a default one will be used.

Additionally cdim_yx and maxpixel_yx are only ever filled in if we know them, and maxpixel_yx is only defined for NcBlitter::Pixel.

See also

• NcVisual.geom

C style function: ncvisual_geom().

pub fn visual_geom_with_pixel(
    &self,
    visual: Option<&ncvisual>
) -> Result<NcVisualGeometry, NcError>

Like visual_geom but auto-fills the NcVisualOptions with NcBlitter::Pixel in order to get the maximum available resolution for scale_yx, which determines the minimum dot-size for an NcVisual.

Trait Implementations

impl Debug for notcurses

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

Formats the value using the given formatter.