Type Alias libnotcurses_sys::Nc
source · pub type Nc = notcurses;
Expand description
Notcurses state for a given terminal, composed of NcPlane
s.
It’s built atop the terminfo abstraction layer to provide reasonably portable vivid character displays.
Aliased Type§
struct Nc { /* private fields */ }
Implementations§
source§impl Nc
impl Nc
§Nc
Constructors and destructors
sourcepub unsafe fn new<'a>() -> NcResult<&'a mut Nc>
pub unsafe fn new<'a>() -> NcResult<&'a mut Nc>
New notcurses context.
Has the SuppressBanners
flag enabled.
§Safety
You can’t have multiple simultaneous Nc
instances in the same thread.
sourcepub unsafe fn new_cli<'a>() -> NcResult<&'a mut Nc>
pub unsafe fn new_cli<'a>() -> NcResult<&'a mut Nc>
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.
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.
sourcepub unsafe fn with_flags<'a>(flags: impl Into<NcFlag>) -> NcResult<&'a mut Nc>
pub unsafe fn with_flags<'a>(flags: impl Into<NcFlag>) -> NcResult<&'a mut Nc>
New notcurses context, expecting flags
.
§Safety
You can’t have multiple simultaneous Nc
instances in the same thread.
sourcepub unsafe fn with_flags_log<'a>(
flags: impl Into<NcFlag>,
log_level: impl Into<NcLogLevel>
) -> NcResult<&'a mut Nc>
pub unsafe fn with_flags_log<'a>( flags: impl Into<NcFlag>, log_level: impl Into<NcLogLevel> ) -> NcResult<&'a mut Nc>
New notcurses context, expects flags
and log_level
.
§Safety
You can’t have multiple simultaneous Nc
instances in the same thread.
sourcepub unsafe fn with_options<'a>(options: NcOptions) -> NcResult<&'a mut Nc>
pub unsafe fn with_options<'a>(options: NcOptions) -> NcResult<&'a mut Nc>
sourcepub unsafe fn stop(&mut self) -> NcResult<()>
pub unsafe fn stop(&mut self) -> NcResult<()>
Destroys the notcurses context.
§Safety
You must not call this method repeatedly on the same Nc
instance.
C style function: notcurses_stop().
sourcepub unsafe fn drop_planes(&mut self)
pub unsafe fn drop_planes(&mut self)
Destroys all NcPlane
s other than the stdplane.
§Safety
Must not use any pre-existing references to NcPlane
s.
C style function: notcurses_drop_planes().
source§impl Nc
impl Nc
§Nc
methods
sourcepub fn align(
availcols: u32,
align: impl Into<NcAlign>,
cols: u32
) -> NcResult<u32>
pub fn align( availcols: u32, align: impl Into<NcAlign>, cols: u32 ) -> NcResult<u32>
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().
sourcepub fn at_yx(
&mut self,
y: u32,
x: u32,
stylemask: &mut NcStyle,
channels: &mut NcChannels
) -> Option<String>
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().
sourcepub fn capabilities(&self) -> NcCapabilities
pub fn capabilities(&self) -> NcCapabilities
Returns the detected capabilities of the current terminal.
C style function: notcurses_capabilities().
sourcepub fn canbraille(&self) -> bool
pub fn canbraille(&self) -> bool
Returns true if we can reliably use Unicode Braille.
See also NcBlitter::Braille
.
C style function: notcurses_canbraille().
sourcepub fn canchangecolor(&self) -> bool
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().
sourcepub fn canfade(&self) -> bool
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().
sourcepub fn canhalfblock(&self) -> bool
pub fn canhalfblock(&self) -> bool
Returns true if we can reliably use Unicode half blocks.
See also NcBlitter::Half
.
C style function: notcurses_canhalfblock().
sourcepub fn canopen_images(&self) -> bool
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().
sourcepub fn canopen_videos(&self) -> bool
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().
sourcepub fn canpixel(&self) -> bool
pub fn canpixel(&self) -> bool
Returns true if we can blit pixel-accurate bitmaps.
See also check_pixel_support
.
C style function: notcurses_canpixel().
sourcepub fn canquadrant(&self) -> bool
pub fn canquadrant(&self) -> bool
Returns true if we can reliably use Unicode quadrant blocks.
See also NcBlitter::Quadrant
.
C style function: notcurses_canquadrant().
sourcepub fn cansextant(&self) -> bool
pub fn cansextant(&self) -> bool
Returns true if we can reliably use Unicode 13 sextants.
See also NcBlitter::Sextant
.
C style function: notcurses_cansextant().
sourcepub fn cantruecolor(&self) -> bool
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().
sourcepub fn canutf8(&self) -> bool
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().
sourcepub fn check_pixel_support(&self) -> NcPixelImpl
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().
sourcepub fn default_foreground(&self) -> Option<NcRgb>
pub fn default_foreground(&self) -> Option<NcRgb>
Returns the default foreground color, if it is known.
sourcepub fn default_background(&self) -> Option<NcRgb>
pub fn default_background(&self) -> Option<NcRgb>
Returns the default background color, if it is known.
sourcepub fn cursor_disable(&mut self) -> NcResult<()>
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().
sourcepub fn cursor_enable(&mut self, y: u32, x: u32) -> NcResult<()>
pub fn cursor_enable(&mut self, y: u32, x: u32) -> 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().
sourcepub fn enter_alternate_screen(&mut self) -> NcResult<()>
pub fn enter_alternate_screen(&mut self) -> NcResult<()>
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().
sourcepub fn leave_alternate_screen(&mut self) -> NcResult<()>
pub fn leave_alternate_screen(&mut self) -> NcResult<()>
Exits the alternate screen.
Immediately returns Ok(()) if not currently using the alternate screen.
C style function: notcurses_leave_alternate_screen().
sourcepub fn debug(&mut self, debugfp: &mut NcFile)
Available on crate feature std
only.
pub fn debug(&mut self, debugfp: &mut NcFile)
std
only.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().
sourcepub fn accountname() -> String
pub fn accountname() -> String
Returns the name of the user under which we are running.
C style function: notcurses_accountname().
sourcepub fn hostname() -> String
pub fn hostname() -> String
Returns the name of the local hostname.
C style function: notcurses_hostname().
sourcepub fn osversion() -> String
pub fn osversion() -> String
Returns the name of the detected OS version.
C style function: notcurses_osversion().
sourcepub fn detected_terminal(&self) -> String
pub fn detected_terminal(&self) -> String
Returns the name of the detected terminal.
C style function: notcurses_detected_terminal().
sourcepub fn get(
&mut self,
time: Option<NcTime>,
input: Option<&mut NcInput>
) -> NcResult<NcReceived>
pub fn get( &mut self, time: Option<NcTime>, input: Option<&mut NcInput> ) -> NcResult<NcReceived>
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().
sourcepub fn get_blocking(
&mut self,
input: Option<&mut NcInput>
) -> NcResult<NcReceived>
pub fn get_blocking( &mut self, input: Option<&mut NcInput> ) -> NcResult<NcReceived>
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().
sourcepub fn get_nblock(
&mut self,
input: Option<&mut NcInput>
) -> NcResult<NcReceived>
pub fn get_nblock( &mut self, input: Option<&mut NcInput> ) -> NcResult<NcReceived>
Reads input without blocking.
C style function: notcurses_get_nblock().
sourcepub fn getvec(
&mut self,
time: Option<NcTime>,
ni: &mut Vec<NcInput>,
vcount: u32
) -> NcResult<u32>
pub fn getvec( &mut self, time: Option<NcTime>, ni: &mut Vec<NcInput>, vcount: u32 ) -> NcResult<u32>
Acquire up to ‘vcount’ NcInput
s at the vector ‘ni’.
The number read will be returned, or 0 on timeout.
C style function: notcurses_getvec().
sourcepub fn inputready_fd(&mut self) -> NcResult<NcFd>
pub fn inputready_fd(&mut self) -> NcResult<NcFd>
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().
sourcepub fn lex_blitter(blitter_str: &str) -> NcResult<NcBlitter>
pub fn lex_blitter(blitter_str: &str) -> NcResult<NcBlitter>
Returns an NcBlitter
from a string representation.
C style function: notcurses_lex_blitter().
sourcepub fn lex_margins(margins_str: &str, options: &mut NcOptions) -> NcResult<()>
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().
sourcepub fn lex_scalemode(scale_str: &str) -> NcResult<NcScale>
pub fn lex_scalemode(scale_str: &str) -> NcResult<NcScale>
Returns an NcScale
from a string representation.
C style function: notcurses_lex_scalemode().
sourcepub fn lex_styles(styles_str: &str) -> NcResult<NcStyle>
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
, and none
.
If a style is are not recognized returns an error.
(No equivalent C style function)
sourcepub fn linesigs_disable(&mut self) -> NcResult<()>
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().
sourcepub fn linesigs_enable(&mut self) -> NcResult<()>
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().
sourcepub fn mice_disable(&mut self) -> NcResult<()>
pub fn mice_disable(&mut self) -> NcResult<()>
Disables mice events.
C style function: notcurses_mice_disable().
sourcepub fn mice_enable(&mut self, eventmask: NcMiceEvents) -> NcResult<()>
pub fn mice_enable(&mut self, eventmask: NcMiceEvents) -> NcResult<()>
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().
sourcepub fn palette_size(&self) -> NcResult<u32>
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().
sourcepub fn refresh(&mut self) -> NcResult<(u32, u32)>
pub fn refresh(&mut self) -> NcResult<(u32, u32)>
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().
sourcepub fn render(&mut self) -> NcResult<()>
pub fn render(&mut self) -> NcResult<()>
Renders and rasterizes the standard pile in one shot. Blocking call.
C style function: notcurses_render().
sourcepub fn stats(&mut self, stats: &mut NcStats)
pub fn stats(&mut self, stats: &mut NcStats)
Acquires an atomic snapshot of the notcurses object’s stats.
C style function: notcurses_stats().
sourcepub fn stats_alloc(&mut self) -> &mut NcStats
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().
sourcepub fn stats_reset(&mut self, stats: &mut NcStats)
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().
sourcepub unsafe fn stdplane<'a>(&mut self) -> &'a mut NcPlane
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().
sourcepub unsafe fn stdplane_const<'a>(&self) -> &'a NcPlane
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().
sourcepub fn str_blitter(blitter: impl Into<NcBlitter>) -> String
pub fn str_blitter(blitter: impl Into<NcBlitter>) -> String
Gets the name of an NcBlitter
blitter.
C style function: notcurses_str_blitter().
sourcepub fn str_scalemode(scale: impl Into<NcScale>) -> String
pub fn str_scalemode(scale: impl Into<NcScale>) -> String
Gets the name of an NcScale
scaling mode.
C style function: notcurses_str_scalemode().
sourcepub fn str_styles(style: impl Into<NcStyle>) -> String
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)
sourcepub fn supported_styles(&self) -> NcStyle
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().
sourcepub fn term_dim_yx(&self) -> (u32, u32)
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().
sourcepub fn bottom(&mut self) -> &mut NcPlane
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().
sourcepub fn top(&mut self) -> &mut NcPlane
pub fn top(&mut self) -> &mut NcPlane
Returns the topmost NcPlane
, of which there is always at least one.
C style function: notcurses_top().
sourcepub fn version() -> String
pub fn version() -> String
Returns a human-readable string describing the running notcurses version.
C style function: notcurses_version().
sourcepub fn version_components() -> (u32, u32, u32, u32)
pub fn version_components() -> (u32, u32, u32, u32)
Returns the running notcurses version components (major, minor, patch, tweak).
C style function: notcurses_version_components().
sourcepub fn visual_geom(
&self,
visual: Option<&NcVisual>,
vopts: Option<&NcVisualOptions>
) -> NcResult<NcVisualGeometry>
pub fn visual_geom( &self, visual: Option<&NcVisual>, vopts: Option<&NcVisualOptions> ) -> NcResult<NcVisualGeometry>
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
C style function: ncvisual_geom().
sourcepub fn visual_geom_with_pixel(
&self,
visual: Option<&NcVisual>
) -> NcResult<NcVisualGeometry>
pub fn visual_geom_with_pixel( &self, visual: Option<&NcVisual> ) -> NcResult<NcVisualGeometry>
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
.