Type Alias libnotcurses_sys::NcDirect
source · pub type NcDirect = ncdirect;
Expand description
Minimal notcurses instance for styling text.
Aliased Type§
struct NcDirect { /* private fields */ }
Implementations§
source§impl NcDirect
impl NcDirect
§NcDirect
constructors and destructors
sourcepub unsafe fn new<'a>() -> NcResult<&'a mut NcDirect>
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().
sourcepub unsafe fn with_flags<'a>(
flags: impl Into<NcDirectFlag>
) -> NcResult<&'a mut NcDirect>
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().
source§impl NcDirect
impl NcDirect
§NcDirect methods: clear, flush, render
sourcepub fn clear(&mut self) -> NcResult<()>
pub fn clear(&mut self) -> NcResult<()>
Clears the screen.
C style function: ncdirect_clear().
sourcepub fn flush(&self) -> NcResult<()>
pub fn flush(&self) -> NcResult<()>
Forces a flush.
C style function: ncdirect_flush().
sourcepub fn raster_frame(
&mut self,
frame: &mut NcPlane,
align: impl Into<NcAlign>
) -> NcResult<()>
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().
sourcepub fn render_frame<'a>(
&mut self,
filename: &str,
blitter: impl Into<NcBlitter>,
scale: impl Into<NcScale>,
max_y: u32,
max_x: u32
) -> NcResult<&'a mut NcPlane>
pub fn render_frame<'a>( &mut self, filename: &str, blitter: impl Into<NcBlitter>, scale: impl Into<NcScale>, 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().
sourcepub fn render_image(
&mut self,
filename: &str,
align: impl Into<NcAlign>,
blitter: impl Into<NcBlitter>,
scale: impl Into<NcScale>
) -> NcResult<()>
pub fn render_image( &mut self, filename: &str, align: impl Into<NcAlign>, blitter: impl Into<NcBlitter>, scale: impl Into<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().
source§impl NcDirect
impl NcDirect
§NcDirect methods: NcPaletteIndex
, NcRgb
, NcStyle
& default color
sourcepub fn set_fg_palindex(
&mut self,
index: impl Into<NcPaletteIndex>
) -> NcResult<()>
pub fn set_fg_palindex( &mut self, index: impl Into<NcPaletteIndex> ) -> NcResult<()>
Sets the foreground NcPaletteIndex
.
C style function: ncdirect_set_fg_palindex().
sourcepub fn set_bg_palindex(
&mut self,
index: impl Into<NcPaletteIndex>
) -> NcResult<()>
pub fn set_bg_palindex( &mut self, index: impl Into<NcPaletteIndex> ) -> NcResult<()>
Sets the background NcPaletteIndex
.
C style function: ncdirect_set_bg_palindex().
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: ncdirect_palette_size().
sourcepub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>) -> NcResult<()>
pub fn set_fg_rgb(&mut self, rgb: impl Into<NcRgb>) -> NcResult<()>
Sets the foreground NcRgb
.
C style function: ncdirect_set_fg_rgb().
sourcepub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>) -> NcResult<()>
pub fn set_bg_rgb(&mut self, rgb: impl Into<NcRgb>) -> NcResult<()>
Sets the background NcRgb
.
C style function: ncdirect_set_bg_rgb().
sourcepub fn styles(&self) -> NcStyle
pub fn styles(&self) -> NcStyle
Returns the current styling.
C style function: ncdirect_styles().
sourcepub fn styles_off(&mut self, styles: impl Into<NcStyle>) -> NcResult<()>
pub fn styles_off(&mut self, styles: impl Into<NcStyle>) -> NcResult<()>
Removes the specified styles
.
C style function: ncdirect_off_styles().
sourcepub fn styles_on(&mut self, styles: impl Into<NcStyle>) -> NcResult<()>
pub fn styles_on(&mut self, styles: impl Into<NcStyle>) -> NcResult<()>
Adds the specified styles
.
C style function: ncdirect_on_styles().
sourcepub fn styles_set(&mut self, styles: impl Into<NcStyle>) -> NcResult<()>
pub fn styles_set(&mut self, styles: impl Into<NcStyle>) -> NcResult<()>
Sets just the specified styles
.
C style function: ncdirect_set_styles().
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: ncdirect_supported_styles().
sourcepub fn set_fg_default(&mut self) -> NcResult<()>
pub fn set_fg_default(&mut self) -> NcResult<()>
Indicates to use the “default color” for the foreground.
C style function: ncdirect_set_fg_default().
sourcepub fn set_bg_default(&mut self) -> NcResult<()>
pub fn set_bg_default(&mut self) -> NcResult<()>
Indicates to use the “default color” for the background.
C style function: ncdirect_set_bg_default().
source§impl NcDirect
impl NcDirect
§NcDirect methods: capabilities, cursor, dimensions
sourcepub fn canget_cursor(&self) -> bool
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.
sourcepub fn canbraille(&self) -> bool
pub fn canbraille(&self) -> bool
Can we reliably use Unicode braille?
C style function: ncdirect_canbraille().
sourcepub fn canchangecolor(&self) -> bool
pub fn canchangecolor(&self) -> bool
Can we set the “hardware” palette?
Requires the “ccc” terminfo capability.
C style function: ncdirect_canchangecolor().
sourcepub fn canfade(&self) -> bool
pub fn canfade(&self) -> bool
Can we fade?
Requires either the “rgb” or “ccc” terminfo capability.
C style function: ncdirect_canfade().
sourcepub fn canhalfblock(&self) -> bool
pub fn canhalfblock(&self) -> bool
Can we reliably use Unicode halfblocks?
C style function: ncdirect_canhalfblock().
sourcepub fn canopen_images(&self) -> bool
pub fn canopen_images(&self) -> bool
Can we load images?
Requires being built against FFmpeg/OIIO.
C style function: ncdirect_canopen_images().
sourcepub fn canopen_videos(&self) -> bool
pub fn canopen_videos(&self) -> bool
Can we load videos?
Requires being built against FFmpeg/OIIO.
C style function: ncdirect_canopen_videos().
sourcepub fn canquadrant(&self) -> bool
pub fn canquadrant(&self) -> bool
Can we reliably use Unicode quadrants?
C style function: ncdirect_canquadrant().
sourcepub fn cansextant(&self) -> bool
pub fn cansextant(&self) -> bool
Can we reliably use Unicode sextants?
C style function: ncdirect_cansextant().
sourcepub fn cantruecolor(&self) -> bool
pub fn cantruecolor(&self) -> bool
Can we directly specify RGB values per cell, or only use palettes?
C style function: ncdirect_cantruecolor().
sourcepub fn canutf8(&self) -> bool
pub fn canutf8(&self) -> bool
Is our encoding UTF-8?
Requires LANG being set to a UTF8 locale.
C style function: ncdirect_canutf8().
sourcepub fn capabilities(&self) -> NcCapabilities
pub fn capabilities(&self) -> NcCapabilities
Returns the NcCapabilities
.
C style function: ncdirect_capabilities().
sourcepub fn check_pixel_support(&self) -> NcResult<bool>
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].
sourcepub fn cursor_disable(&mut self) -> NcResult<()>
pub fn cursor_disable(&mut self) -> NcResult<()>
Disables the terminal’s cursor, if supported.
C style function: ncdirect_cursor_disable().
sourcepub fn cursor_enable(&mut self) -> NcResult<()>
pub fn cursor_enable(&mut self) -> NcResult<()>
Enables the terminal’s cursor, if supported.
C style function: ncdirect_cursor_enable().
sourcepub fn cursor_down(&mut self, rows: i32) -> NcResult<()>
pub fn cursor_down(&mut self, rows: i32) -> NcResult<()>
Moves the cursor down any number of rows.
C style function: ncdirect_cursor_down().
sourcepub fn cursor_left(&mut self, cols: i32) -> NcResult<()>
pub fn cursor_left(&mut self, cols: i32) -> NcResult<()>
Moves the cursor left any number of columns.
C style function: ncdirect_cursor_left().
sourcepub fn cursor_right(&mut self, cols: i32) -> NcResult<()>
pub fn cursor_right(&mut self, cols: i32) -> NcResult<()>
Moves the cursor right any number of columns.
C style function: ncdirect_cursor_right().
sourcepub fn cursor_up(&mut self, rows: i32) -> NcResult<()>
pub fn cursor_up(&mut self, rows: i32) -> NcResult<()>
Moves the cursor up any number of rows.
C style function: ncdirect_cursor_up().
sourcepub fn cursor_set_yx(&mut self, y: u32, x: u32) -> NcResult<()>
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().
sourcepub fn cursor_set_y(&mut self, y: u32) -> NcResult<()>
pub fn cursor_set_y(&mut self, y: u32) -> NcResult<()>
Sets the cursor to the specified row y
.
(No equivalent C style function)
sourcepub fn cursor_set_x(&mut self, x: u32) -> NcResult<()>
pub fn cursor_set_x(&mut self, x: u32) -> NcResult<()>
Sets the cursor to the specified column x
.
(No equivalent C style function)
sourcepub fn cursor_yx(&mut self) -> NcResult<(u32, u32)>
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().
sourcepub fn cursor_push(&mut self) -> NcResult<()>
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().
sourcepub fn cursor_pop(&mut self) -> NcResult<()>
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().
sourcepub fn dim_y(&mut self) -> u32
pub fn dim_y(&mut self) -> u32
Gets the current number of rows.
C style function: ncdirect_dim_y().
sourcepub fn dim_x(&mut self) -> u32
pub fn dim_x(&mut self) -> u32
Gets the current number of columns.
C style function: ncdirect_dim_x().
sourcepub fn dim_yx(&mut self) -> (u32, u32)
pub fn dim_yx(&mut self) -> (u32, u32)
Gets the current number of rows and columns.
C style function: ncdirect_dim_y().
sourcepub fn detected_terminal(&self) -> String
pub fn detected_terminal(&self) -> String
Returns the name of the detected terminal.
C style function: ncdirect_detected_terminal().
source§impl NcDirect
impl NcDirect
§NcDirect methods: I/O
sourcepub fn get(
&mut self,
time: Option<NcTime>,
input: Option<&mut NcInput>
) -> NcResult<char>
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().
sourcepub fn get_blocking(&mut self, input: Option<&mut NcInput>) -> NcResult<char>
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().
sourcepub fn get_nblock(&mut self, input: Option<&mut NcInput>) -> NcResult<char>
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().
sourcepub fn inputready_fd(&mut self) -> NcResult<NcFd>
pub fn inputready_fd(&mut self) -> NcResult<NcFd>
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().
sourcepub fn putstr(
&mut self,
channels: impl Into<NcChannels>,
string: &str
) -> NcResult<()>
pub fn putstr( &mut self, channels: impl Into<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().
sourcepub fn readline(&mut self, prompt: &str) -> NcResult<String>
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().
sourcepub fn box(
&mut self,
ul: impl Into<NcChannels>,
ur: impl Into<NcChannels>,
ll: impl Into<NcChannels>,
lr: impl Into<NcChannels>,
wchars: &[char; 6],
len_y: u32,
len_x: u32,
ctlword: u32
) -> NcResult<()>
pub fn box( &mut self, ul: impl Into<NcChannels>, ur: impl Into<NcChannels>, ll: impl Into<NcChannels>, lr: impl Into<NcChannels>, 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().
sourcepub 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<()>
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().
sourcepub 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<()>
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().
sourcepub fn hline_interp(
&mut self,
egc: &str,
len: u32,
h1: impl Into<NcChannels>,
h2: impl Into<NcChannels>
) -> NcResult<()>
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().
sourcepub fn vline_interp(
&mut self,
egc: &str,
len: u32,
h1: impl Into<NcChannels>,
h2: impl Into<NcChannels>
) -> NcResult<()>
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().