Type Definition libnotcurses_sys::NcDirect

pub type NcDirect = ncdirect;

Minimal notcurses instance for styling text.

Implementations

impl NcDirect

NcDirect constructors and destructors

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

New NcDirect with the default options.

Initializes a direct-mode notcurses context on the tty.

Direct mode supports a limited subset of notcurses routines, and neither supports nor requires notcurses_render. This can be used to add color and styling to text in the standard output paradigm.

Safety

You must not create multiple NcDirect instances at the same time, on the same thread. You must stop the current one before creating a new one.

C style function: ncdirect_init().

pub unsafe fn with_flags<'a>(
    flags: impl Into<NcDirectFlag>
) -> NcResult<&'a mut NcDirect>

New NcDirect with optional flags.

Safety

You must not create multiple NcDirect instances at the same time, on the same thread. You must stop the current one before creating a new one.

C style function: ncdirect_init().

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

Releases this NcDirect and any associated resources.

Safety

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

C style function: ncdirect_stop().

impl NcDirect

NcDirect methods: clear, flush, render

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

Clears the screen.

C style function: ncdirect_clear().

pub fn flush(&self) -> NcResult<()>

Forces a flush.

C style function: ncdirect_flush().

pub fn raster_frame(
    &mut self,
    frame: &mut NcPlane,
    align: impl Into<NcAlign>
) -> NcResult<()>

Takes the result of render_frame and writes it to the output.

C style function: ncdirect_raster_frame().

pub fn render_frame<'a>(
    &mut self,
    filename: &str,
    blitter: impl Into<NcBlitter> + Copy,
    scale: impl Into<NcScale> + Copy,
    max_y: u32,
    max_x: u32
) -> NcResult<&'a mut NcPlane>

Renders an image using the specified blitter and scaling, but doesn’t write the result.

The image may be arbitrarily many rows – the output will scroll – but will only occupy the column of the cursor, and those to the right.

To actually write (and free) this, invoke ncdirect_raster_frame().

max_y' and 'max_x (cell geometry, not pixel), if greater than 0, are used for scaling; the terminal’s geometry is otherwise used.

C style function: ncdirect_render_frame().

pub fn render_image(
    &mut self,
    filename: &str,
    align: impl Into<NcAlign> + Copy,
    blitter: impl Into<NcBlitter> + Copy,
    scale: impl Into<NcScale> + Copy
) -> NcResult<()>

Displays an image using the specified blitter and scaling.

The image may be arbitrarily many rows – the output will scroll – but will only occupy the column of the cursor, and those to the right.

The render/raster process can be split by using [render_frame][#method.render_frame] and [raster_frame][#method.raster_frame].

C style function: ncdirect_render_image().

impl NcDirect

NcDirect methods: NcPaletteIndex, NcRgb, NcStyle & default color

pub fn set_fg_palindex(
    &mut self,
    index: impl Into<NcPaletteIndex> + Copy
) -> NcResult<()>

Sets the foreground NcPaletteIndex.

C style function: ncdirect_set_fg_palindex().

pub fn set_bg_palindex(
    &mut self,
    index: impl Into<NcPaletteIndex> + Copy
) -> NcResult<()>

Sets the background NcPaletteIndex.

C style function: ncdirect_set_bg_palindex().

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

pub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>) -> NcResult<()>

Sets the foreground NcRgb.

C style function: ncdirect_set_fg_rgb().

pub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>) -> NcResult<()>

Sets the background NcRgb.

C style function: ncdirect_set_bg_rgb().

pub fn styles(&self) -> NcStyle

Returns the current styling.

C style function: ncdirect_styles().

pub fn styles_off(
    &mut self,
    stylebits: impl Into<NcStyle> + Copy
) -> NcResult<()>

Removes the specified styles.

C style function: ncdirect_off_styles().

pub fn styles_on(
    &mut self,
    stylebits: impl Into<NcStyle> + Copy
) -> NcResult<()>

Adds the specified styles.

C style function: ncdirect_on_styles().

pub fn styles_set(
    &mut self,
    stylebits: impl Into<NcStyle> + Copy
) -> NcResult<()>

Sets just the specified styles.

C style function: ncdirect_set_styles().

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

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

Indicates to use the “default color” for the foreground.

C style function: ncdirect_set_fg_default().

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

Indicates to use the “default color” for the background.

C style function: ncdirect_set_bg_default().

impl NcDirect

NcDirect methods: capabilities, cursor, dimensions

pub fn canget_cursor(&self) -> bool

Is there support for acquiring the cursor’s current position?

Requires the u7 terminfo capability, and that we are connected to an actual terminal.

pub fn canbraille(&self) -> bool

Can we reliably use Unicode braille?

C style function: ncdirect_canbraille().

pub fn canchangecolor(&self) -> bool

Can we set the “hardware” palette?

Requires the “ccc” terminfo capability.

C style function: ncdirect_canchangecolor().

pub fn canfade(&self) -> bool

Can we fade?

Requires either the “rgb” or “ccc” terminfo capability.

C style function: ncdirect_canfade().

pub fn canhalfblock(&self) -> bool

Can we reliably use Unicode halfblocks?

C style function: ncdirect_canhalfblock().

pub fn canopen_images(&self) -> bool

Can we load images?

Requires being built against FFmpeg/OIIO.

C style function: ncdirect_canopen_images().

pub fn canopen_videos(&self) -> bool

Can we load videos?

Requires being built against FFmpeg/OIIO.

C style function: ncdirect_canopen_videos().

pub fn canquadrant(&self) -> bool

Can we reliably use Unicode quadrants?

C style function: ncdirect_canquadrant().

pub fn cansextant(&self) -> bool

Can we reliably use Unicode sextants?

C style function: ncdirect_cansextant().

pub fn cantruecolor(&self) -> bool

Can we directly specify RGB values per cell, or only use palettes?

C style function: ncdirect_cantruecolor().

pub fn canutf8(&self) -> bool

Is our encoding UTF-8?

Requires LANG being set to a UTF8 locale.

C style function: ncdirect_canutf8().

pub fn capabilities(&self) -> NcCapabilities

Returns the NcCapabilities.

C style function: ncdirect_capabilities().

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: [ncdirect_check_pixel_support()][c_api::ncdirect_check-pixel_support].

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

Disables the terminal’s cursor, if supported.

C style function: ncdirect_cursor_disable().

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

Enables the terminal’s cursor, if supported.

C style function: ncdirect_cursor_enable().

pub fn cursor_down(&mut self, rows: i32) -> NcResult<()>

Moves the cursor down any number of rows.

C style function: ncdirect_cursor_down().

pub fn cursor_left(&mut self, cols: i32) -> NcResult<()>

Moves the cursor left any number of columns.

C style function: ncdirect_cursor_left().

pub fn cursor_right(&mut self, cols: i32) -> NcResult<()>

Moves the cursor right any number of columns.

C style function: ncdirect_cursor_right().

pub fn cursor_up(&mut self, rows: i32) -> NcResult<()>

Moves the cursor up any number of rows.

C style function: ncdirect_cursor_up().

pub fn cursor_set_yx(&mut self, y: u32, x: u32) -> NcResult<()>

Sets the cursor to the specified row y, column x.

C style function: ncdirect_cursor_move_yx().

pub fn cursor_set_y(&mut self, y: u32) -> NcResult<()>

Sets the cursor to the specified row y.

(No equivalent C style function)

pub fn cursor_set_x(&mut self, x: u32) -> NcResult<()>

Sets the cursor to the specified column x.

(No equivalent C style function)

pub fn cursor_yx(&mut self) -> NcResult<(u32, u32)>

Gets the cursor (y, x) position, when supported.

This requires writing to the terminal, and then reading from it. If the terminal doesn’t reply, or doesn’t reply in a way we understand, the results might be detrimental.

C style function: ncdirect_cursor_yx().

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

Pushes the cursor location to the terminal’s stack.

The depth of this stack, and indeed its existence, is terminal-dependent.

C style function: ncdirect_cursor_push().

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

Pops the cursor location from the terminal’s stack.

The depth of this stack, and indeed its existence, is terminal-dependent.

C style function: ncdirect_cursor_pop().

pub fn dim_y(&mut self) -> u32

Gets the current number of rows.

C style function: ncdirect_dim_y().

pub fn dim_x(&mut self) -> u32

Gets the current number of columns.

C style function: ncdirect_dim_x().

pub fn dim_yx(&mut self) -> (u32, u32)

Gets the current number of rows and columns.

C style function: ncdirect_dim_y().

pub fn detected_terminal(&self) -> String

Returns the name of the detected terminal.

C style function: ncdirect_detected_terminal().

impl NcDirect

NcDirect methods: I/O

pub fn get(
    &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: ncdirect_get().

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

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

Will optionally write the event details in input.

In the case of a valid read, a char is returned.

C style function: ncdirect_get_blocking().

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

Reads input without blocking.

In the case of a valid read, a char is returned.

If no event is ready, returns 0.

C style function: ncdirect_get_nblock().

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

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

When this descriptor becomes available, you can call NcDirect. 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: ncdirect_inputready_fd().

pub fn putstr(
    &mut self,
    channels: impl Into<NcChannels> + Copy,
    string: &str
) -> NcResult<()>

Outputs the string according to the channels, and returns the total number of characters written on success.

Note that it does not explicitly flush output buffers, so it will not necessarily be immediately visible.

It will fail if the NcDirect context and the foreground channel are both marked as using the default color.

C style function: ncdirect_putstr().

pub fn readline(&mut self, prompt: &str) -> NcResult<String>

Reads a (heap-allocated) line of text using the Readline library.

Initializes Readline the first time it’s called.

For input to be echoed to the terminal, it is necessary that the flag NcDirectFlag::INHIBIT_CBREAK be provided to the constructor.

C style function: ncdirect_readline().

pub fn box(
    &mut self,
    ul: impl Into<NcChannels> + Copy,
    ur: impl Into<NcChannels> + Copy,
    ll: impl Into<NcChannels> + Copy,
    lr: impl Into<NcChannels> + Copy,
    wchars: &[char; 6],
    len_y: u32,
    len_x: u32,
    ctlword: u32
) -> NcResult<()>

Draws a box with its upper-left corner at the current cursor position, having dimensions ylen * xlen.

See NcPlane.box for more information.

The minimum box size is 2x2, and it cannot be drawn off-screen.

wchars is an array of 6 characters: UL, UR, LL, LR, HL, VL.

C style function: ncdirect_box().

pub fn double_box(
    &mut self,
    ul: impl Into<NcChannels>,
    ur: impl Into<NcChannels>,
    ll: impl Into<NcChannels>,
    lr: impl Into<NcChannels>,
    len_y: u32,
    len_x: u32,
    ctlword: u32
) -> NcResult<()>

NcDirect.box with the double box-drawing characters.

C style function: ncdirect_double_box().

pub fn rounded_box(
    &mut self,
    ul: impl Into<NcChannels>,
    ur: impl Into<NcChannels>,
    ll: impl Into<NcChannels>,
    lr: impl Into<NcChannels>,
    len_y: u32,
    len_x: u32,
    ctlword: u32
) -> NcResult<()>

NcDirect.box with the rounded box-drawing characters.

C style function: ncdirect_rounded_box().

pub fn hline_interp(
    &mut self,
    egc: &str,
    len: u32,
    h1: impl Into<NcChannels>,
    h2: impl Into<NcChannels>
) -> NcResult<()>

Draws horizontal lines using the specified NcChannelss, interpolating between them as we go.

All lines start at the current cursor position.

The string at egc may not use more than one column.

For a horizontal line, len cannot exceed the screen width minus the cursor’s offset.

C style function: ncdirect_hline_interp().

pub fn vline_interp(
    &mut self,
    egc: &str,
    len: u32,
    h1: impl Into<NcChannels>,
    h2: impl Into<NcChannels>
) -> NcResult<()>

Draws horizontal lines using the specified NcChannelss, interpolating between them as we go.

All lines start at the current cursor position.

The string at egc may not use more than one column.

For a vertical line, len may be as long as you’d like; the screen will scroll as necessary.

C style function: ncdirect_vline_interp().