Crate libnotcurses_sys[−][src]
Expand description
libnotcurses-sys is a low-level Rust wrapper for the
notcurses C library
It is built with several layers of zero-overhead abstractions over the C functions and pointers accessed through FFI.
It adds greater safety and type correctness over the underlying C library API, while trying to remain very close to it.
It offers the choice of using it more like Rust and/or more like C.
Like Rust
Where you use the more safely wrapped types, with its methods and
constructors, and error handling with the NcResult enum:
Example
use libnotcurses_sys::*;
fn main() -> NcResult<()> {
let nc = unsafe { Nc::new_cli()? };
let stdp = unsafe { nc.stdplane() };
stdp.putstr("hello world")?;
nc.render()?;
unsafe { nc.stop()? };
Ok(())
}
Notes on the Rust API
The Drop trait is not implemented for any wrapping type in this library.
This means you still have to manually call the stop() method for Nc
and NcDirect objects, and the destroy() method for the rest of types that
allocate, (like NcPlane, NcMenu…) at the end of their scope, since the
But they do implement methods and use NcResult as the return type,
for handling errors in the way we are used to in Rust.
For the types that don’t allocate, most are based on primitives like i32,
u32, u64… without a name in the C library. In Rust they are type aliased
(e.g.: NcChannel, NcChannelPair, NcRgb, NcColor…), to
leverage type checking, and they implement methods through traits
(e.g. NcChannelApi must be in scope to use the NcChannel methods.
Several methods are declared unsafe when they have addittional contracts to manually upheld in order to avoid UB.
even more like Rust
The WIP sister crate
notcurses will eventually
offer a closer to Rust, higher-level, safer, and simpler API, and make it
easier to interoperate with the rest of the Rust ecosystem.
Like C
You can access the imported, or reimplemented C API functions directly, and use it in a very similar way as the C library is used.
It requires more use of unsafe, since it has less safer abstractions.
Error handling is done this way by checking the returned NcIntResult,
or in case of receiving a pointer, by comparing it to null_mut().
Example
use core::ptr::{null, null_mut};
use std::process::exit;
use libnotcurses_sys::c_api::*;
fn main() {
let options = ffi::notcurses_options {
termtype: null(),
loglevel: 0,
margin_t: 0,
margin_r: 0,
margin_b: 0,
margin_l: 0,
flags: NCOPTION_NO_ALTERNATE_SCREEN | NCOPTION_PRESERVE_CURSOR | NCOPTION_SUPPRESS_BANNERS,
};
unsafe {
let nc = notcurses_init(&options, null_mut());
if nc.is_null() {
exit(1);
}
let plane = notcurses_stdplane(nc);
let cols = ncplane_putstr(&mut *plane, "hello world");
if cols < NCRESULT_OK {
notcurses_stop(nc);
exit(cols.abs());
}
if notcurses_render(&mut *nc) < NCRESULT_OK {
exit(2);
}
if notcurses_stop(nc) < NCRESULT_OK {
exit(3);
}
}
}
The notcurses C API docs
Modules
The C API including global constants, functions and structs.
The library examples/.
The notcurses widgets.
Macros
Nc::render($nc)? + sleep![$sleep_args].
NcPlane::render($p)? +
NcPlane::rasterize($p)? +
sleep![$sleep_args].
Wrapper around NcPlane.putstr,
rendering and rasterizing the plane afterwards.
Wrapper around NcPlane.putstrln.
rendering and rasterizing the plane afterwards.
Sleeps for $s seconds + $ms milliseconds
+ $us microseconds + $ns nanoseconds
NcVisual::blit($v, $nc, $vo)? +
Nc::render($nc)? + sleep![$sleep_args].
Structs
The error type for the Rust methods API.
A wrapper struct around
libc::FILE
Synthesized input events (any input event we can report that isn’t representative of some Unicode).
Contains the pixel geometry information as returned by the
NcPlane.pixel_geom method.
Builder object for NcPlaneOptions.
Builder object for NcVisualOptions.
Enums
A received character or event.
Traits
Enables the NcBoxMask associated methods and constants.
Enables the NcChannel associated methods and constants.
Enables the NcChannels associated methods and constants.
Enables the NcDirectFlags associated methods and constants.
Enables the NcEvType associated methods and constants.
Enables the NcIntResult associated methods and constants.
Enables the NcLogLevel associated methods and constants.
Enables the NcMiceEvents associated methods and constants.
Enables the NcPixel associated methods and constants.
Enables the NcPixelImpl associated methods and constants.
Enables the NcResizeCb associated methods and constants.
Enables the NcStyle associated methods and constants.
Type Definitions
Controls the drawing of borders, gradients and corners (alias of u32).
Capabilities, derived from terminfo, environment variables, and queries.
64 bits containing a foreground and background NcChannel (alias of u64).
8 bits representing an R/G/B color component or an alpha channel component
(alias of u8).
Represents a dimension in rows or columns (alias of u32).
Minimal notcurses instance for styling text.
Flags (options) for NcDirect (alias of u64).
Context for a palette fade operation
Options struct for NcFdPlane.
Reads and decodes input events.
The value used to return errors by the underlying C API (alias of i32).
Log level for NcOptions (alias of i32).
A mask for mice input events (alias of u32).
Represents an offset in rows or columns (alias of i32).
Used for indexing into a NcPalette (alias of u8).
An ABGR pixel (alias of u32).
Pixel blitting implementations, informative only (alias of u32).
Options struct for NcPlane.
A callback function called when an NcPlane is resized.
The unsafe version of NcResizeCb expected by the notcurses C API.
The result type for the Rust methods API.
24 bits broken into 3x 8bpp channels (alias of u32).
Three RGB NcComponents plus one alpha NcComponent (alias of u32).
notcurses runtime statistics
Styling attribute flags (alias of u16).
Options struct for NcSubproc
Describes all geometries of an NcVisual:
those which are inherent, and those dependent upon a given rendering regime.
A visual bit of multimedia.
Options struct for NcVisual.