Type Definition libnotcurses_sys::NcDirect

type NcDirect = ncdirect;

Minimal notcurses instance for styling text.

Implementations

impl NcDirect

NcDirect constructors and destructors

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

C style function: ncdirect_init().

pub fn with_flags<'a>(flags: NcDirectFlags) -> NcResult<&'a mut NcDirect>

New NcDirect with optional flags.

flags is a bitmask over:

• NCDIRECT_OPTION_INHIBIT_CBREAK
• NCDIRECT_OPTION_INHIBIT_SETLOCALE
• NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS
• NCDIRECT_OPTION_VERBOSE
• NCDIRECT_OPTION_VERY_VERBOSE

C style function: ncdirect_init().

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

Releases this NcDirect and any associated resources.

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: 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: NcBlitter,
    scale: NcScale,
    max_y: NcDim,
    max_x: NcDim
) -> 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: NcAlign,
    blitter: NcBlitter,
    scale: NcScale
) -> 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: NcPaletteIndex) -> NcResult<()>

Sets the foreground NcPaletteIndex.

C style function: ncdirect_set_fg_palindex().

pub fn set_bg_palindex(&mut self, index: NcPaletteIndex) -> 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: NcRgb) -> NcResult<()>

Sets the foreground NcRgb.

C style function: ncdirect_set_fg_rgb().

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

Sets the background NcRgb.

C style function: ncdirect_set_bg_rgb().

pub fn set_fg_rgb8(
    &mut self,
    red: NcComponent,
    green: NcComponent,
    blue: NcComponent
) -> NcResult<()>

Sets the foreground NcComponent components.

C style function: ncdirect_set_fg_rgb8().

pub fn set_bg_rgb8(
    &mut self,
    red: NcComponent,
    green: NcComponent,
    blue: NcComponent
) -> NcResult<()>

Sets the background NcComponent components.

C style function: ncdirect_set_bg_rgb().

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

Removes the specified styles.

C style function: ncdirect_off_styles().

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

Adds the specified styles.

C style function: ncdirect_on_styles().

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

Sets just the specified styles.

C style function: ncdirect_set_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()][crate::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: NcOffset) -> NcResult<()>

Moves the cursor down any number of rows.

C style function: ncdirect_cursor_down().

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

Moves the cursor left any number of columns.

C style function: ncdirect_cursor_left().

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

Moves the cursor right any number of columns.

C style function: ncdirect_cursor_right().

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

Moves the cursor up any number of rows.

C style function: ncdirect_cursor_up().

pub fn cursor_set_yx(&mut self, y: NcDim, x: NcDim) -> 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: NcDim) -> NcResult<()>

Sets the cursor to the specified row y.

(No equivalent C style function)

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

Sets the cursor to the specified column x.

(No equivalent C style function)

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

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

Gets the current number of rows.

C style function: ncdirect_dim_y().

pub fn dim_x(&mut self) -> NcDim

Gets the current number of columns.

C style function: ncdirect_dim_x().

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

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

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

C style function: ncdirect_getc_nblock().

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

C style function: ncdirect_getc_blocking().

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

pub fn putstr(&mut self, channels: NcChannels, 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<&str>

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 NCDIRECT_OPTION_INHIBIT_CBREAK be provided to the constructor.

C style function: ncdirect_readline().

pub fn box(
    &mut self,
    ul: NcChannels,
    ur: NcChannels,
    ll: NcChannels,
    lr: NcChannels,
    wchars: &[char; 6],
    y_len: NcDim,
    x_len: NcDim,
    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: NcChannels,
    ur: NcChannels,
    ll: NcChannels,
    lr: NcChannels,
    y_len: NcDim,
    x_len: NcDim,
    ctlword: u32
) -> NcResult<()>

NcDirect.box() with the double box-drawing characters.

C style function: ncdirect_double_box().

pub fn rounded_box(
    &mut self,
    ul: NcChannels,
    ur: NcChannels,
    ll: NcChannels,
    lr: NcChannels,
    y_len: NcDim,
    x_len: NcDim,
    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: NcDim,
    h1: NcChannels,
    h2: 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: NcDim,
    h1: NcChannels,
    h2: 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().