Module libnotcurses_sys::c_api::ffi
source · Expand description
Rust FFI bindings, automatically generated with bindgen.
Structs
The tag name of this struct is _G_fpos64_t to preserve historic
C++ mangled names for functions taking fpos_t and/or fpos64_t
arguments. That name should not be used in new code.
The tag name of this struct is _G_fpos_t to preserve historic
C++ mangled names for functions taking fpos_t arguments.
That name should not be used in new code.
The tag name of this struct is _IO_FILE to preserve historic
C++ mangled names for functions taking FILE* arguments.
That name should not be used in new code.
Conversion state information.
Structure used for storage of ancillary data object information.
Returned by `div’.
IPv6 address
Structure for scatter/gather I/O.
Structure used to manipulate the SO_LINGER option.
Returned by `lldiv’.
Capabilities, derived from terminfo, environment variables, and queries
An nccell corresponds to a single character cell on some plane, which can be
occupied by a single grapheme cluster (some root spacing glyph, along with
possible combining characters, which might span multiple columns). At any
cell, we can have a theoretically arbitrarily long UTF-8 EGC, a foreground
color, a background color, and an attribute set. Valid grapheme cluster
contents include:
read from an fd until EOF (or beyond, if follow is set), invoking the user’s
callback each time. runs in its own context. on EOF or error, the finalizer
callback will be invoked, and the user ought destroy the ncfdplane. the
data is not guaranteed to be nul-terminated, and may contain arbitrary
zeroes.
An input event. Cell coordinates are currently defined only for mouse
events. It is not guaranteed that we can set the modifiers for a given
ncinput. We encompass single Unicode codepoints, not complete EGCs.
FIXME for abi4, combine the bools into |modifiers|
Menus. Horizontal menu bars are supported, on the top and/or bottom rows.
If the menu bar is longer than the screen, it will be only partially
visible. Menus may be either visible or invisible by default. In the event of
a plane resize, menus will be automatically moved/resized. Elements can be
dynamically enabled or disabled at all levels (menu, section, and item),
multiselection widget – a selector supporting multiple selections.
Palette API. Some terminals only support 256 colors, but allow the full
palette to be specified with arbitrary RGB colors. In all cases, it’s more
performant to use indexed colors, since it’s much less data to write to the
terminal. If you can limit yourself to 256 colors, that’s probably best.
selection widget – an ncplane with a title header and a body section. the
body section supports infinite scrolling up and down.
whenever a new field is added here, ensure we add the proper rule to
notcurses_stats_reset(), so that values are preserved in the stash stats.
each item has a curry, and zero or more subitems.
describes all geometries of an ncvisual: those which are inherent, and those
dependent upon a given rendering regime. pixy and pixx are the true internal
pixel geometry, taken directly from the load (and updated by
ncvisual_resize()). cdimy/cdimx are the cell-pixel geometry at the time
of this call (it can change with a font change, in which case all values
other than pixy/pixx are invalidated). rpixy/rpixx are the pixel geometry as
handed to the blitter, following any scaling. scaley/scalex are the number
of input pixels drawn to a single cell; when using NCBLIT_PIXEL, they are
equivalent to cdimy/cdimx. rcelly/rcellx are the cell geometry as written by
the blitter, following any padding (there is padding whenever rpix{y, x} is
not evenly divided by scale{y, x}, and also sometimes for Sixel).
maxpixely/maxpixelx are defined only when NCBLIT_PIXEL is used, and specify
the largest bitmap that the terminal is willing to accept. blitter is the
blitter which will be used, a function of the requested blitter and the
blitters actually supported by this environment. if no ncvisual was
supplied, only cdimy/cdimx are filled in.
Configuration for notcurses_init().
Structure describing the action to be taken when a signal arrives.
Structure describing a generic socket address.
Structure describing an Internet socket address.
Ditto, for IPv6.
POSIX.1b structure for a time value. This is like a `struct timeval’ but
has nanoseconds instead of microseconds.
ISO C `broken-down time’ structure.
Constants
Atomically set close-on-exec flag for the
new descriptor(s).
Datagram Congestion Control Protocol.
Connectionless, unreliable datagrams
of fixed maximum length.
Atomically mark descriptor(s) as
non-blocking.
Linux specific way of getting packets
at the dev level. For writing rarp and
other similar things on the user level.
Raw protocol interface.
Reliably-delivered messages.
Sequenced, reliable, connection-based,
datagrams of fixed maximum length.
Sequenced, reliable, connection-based
byte streams.
space, compatible with ASCII
halves + 1x1 (space) ▄▀
quadrants + 2x1 ▗▐ ▖▀▟▌▙
sextants (NOT 2x2) 🬀🬁🬂🬃🬄🬅🬆🬇🬈🬉🬊🬋🬌🬍🬎🬏🬐🬑🬒🬓🬔🬕🬖🬗🬘🬙🬚🬛🬜🬝🬞
four vertical levels █▆▄▂
eight vertical levels █▇▆▅▄▃▂▁
4 rows, 2 cols (braille) ⡀⡄⡆⡇⢀⣀⣄⣆⣇⢠⣠⣤⣦⣧⢰⣰⣴⣶⣷⢸⣸⣼⣾⣿
let the ncvisual pick
pixel graphics
this is honestly a bit much
we can’t keep doing this, but we can do other things
we’re hanging around, but we’ve had a horrible fault
“standard information”
print diagnostics related to catastrophic failure
default. print nothing once fullscreen service begins
there’s probably a better way to do what you want
“detailed information”
you probably don’t want what’s happening to happen
until 0.22.0’s introduction of ‘a=c’ for self-referential composition, we
had to keep a complete copy of the RGBA data, in case a wiped cell needed
to be rebuilt. we’d otherwise have to unpack the glyph and store it into
the auxvec on the fly.
with 0.22.0, we only ever write transparent cells after writing the
original image (which we now deflate, since we needn’t unpack it later).
the only data we need keep is the auxvecs.
C=1 (disabling scrolling) was only introduced in 0.20.0, at the same
time as animation. prior to this, graphics had to be entirely redrawn
on any change, and it wasn’t possible to use the bottom line.
linux framebuffer
Statics
If daylight-saving time is ever in use.
Seconds west of UTC.
Current timezone names.
For communication from ‘getopt’ to the caller.
When ‘getopt’ finds an option that takes an argument,
the argument value is returned here.
Also, when ‘ordering’ is RETURN_IN_ORDER,
each non-option ARGV-element is returned here.
Callers store zero here to inhibit the error message ‘getopt’ prints
for unrecognized options.
Index in ARGV of the next element to be scanned.
This is used for communication to and from the caller
and for communication between successive calls to ‘getopt’.
Set to an option character which was unrecognized.
Standard error output stream.
Standard input stream.
Standard output stream.
Same as above.
Functions
Same as ncblit_rgba(), but for BGRx.
Supply an alpha value [0..255] to be applied throughout. linesize must be
a multiple of 4 for this RGBx data.
Supply an alpha value [0..255] to be applied throughout.
Blit a flat array ‘data’ of RGBA 32-bit values to the ncplane ‘vopts->n’,
which mustn’t be NULL. the blit begins at ‘vopts->y’ and ‘vopts->x’ relative
to the specified plane. Each source row ought occupy ‘linesize’ bytes (this
might be greater than ‘vopts->lenx’ * 4 due to padding or partial blits). A
subregion of the input can be specified with the ‘begy’x’begx’ and
‘leny’x’lenx’ fields from ‘vopts’. Returns the number of pixels blitted, or
-1 on error.
Duplicate ‘c’ into ‘targ’; both must be/will be bound to ‘n’. Returns -1 on
failure, and 0 on success.
return a pointer to the NUL-terminated EGC referenced by ‘c’. this pointer
can be invalidated by any further operation on the plane ‘n’, so…watch out!
Breaks the UTF-8 string in ‘gcluster’ down, setting up the nccell ‘c’.
Returns the number of bytes copied out of ‘gcluster’, or -1 on failure. The
styling of the cell is left untouched, but any resources are released.
Release resources held by the nccell ‘c’.
Draw a box with its upper-left corner at the current cursor position, having
dimensions |ylen|x|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 wide characters: UL, UR, LL, LR, HL, VL.
Is there support for acquiring the cursor’s current position? Requires the
u7 terminfo capability, and that we are connected to an actual terminal.
Is our encoding UTF-8? Requires LANG being set to a UTF8 locale.
Can we blit pixel-accurate bitmaps?
Clear the screen.
The same as ncdirect_init(), but without any multimedia functionality,
allowing for a svelter binary. Link with notcurses-core if this is used.
Move the cursor in direct mode. -1 to retain current location on that axis.
Push or pop the cursor location to the terminal’s stack. The depth of this
stack, and indeed its existence, is terminal-dependent.
Get the cursor 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 deleterious.
Capabilites
Get the current number of columns/rows.
ncdirect_box() with the double box-drawing characters
Force a flush. Returns 0 on success, -1 on failure.
Provide a NULL ‘ts’ to block at length, a ‘ts’ of 0 for non-blocking
operation, and otherwise an absolute deadline in terms of CLOCK_MONOTONIC.
Returns a single Unicode code point, a synthesized special key constant,
or (uint32_t)-1 on error. Returns 0 on a timeout. If an event is processed,
the return value is the ‘id’ field from that event. ‘ni’ may be NULL.
Draw horizontal/vertical lines using the specified channels, interpolating
between them as we go. The EGC may not use more than one column. For a
horizontal line, |len| cannot exceed the screen width minus the cursor’s
offset. For a vertical line, it may be as long as you’d like; the screen
will scroll as necessary. All lines start at the current cursor position.
Initialize a direct-mode Notcurses context on the connected terminal at ‘fp’.
‘fp’ must be a tty. You’ll usually want stdout. Direct mode supports a
limited subset of Notcurses routines which directly affect ‘fp’, and neither
supports nor requires notcurses_render(). This can be used to add color and
styling to text in the standard output paradigm. ‘flags’ is a bitmask over
NCDIRECT_OPTION_*.
Returns NULL on error, including any failure initializing terminfo.
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!).
Returns the number of simultaneous colors claimed to be supported, or 1 if
there is no color support. Note that several terminal emulators advertise
more colors than they actually support, downsampling internally.
Formatted printing (plus alignment relative to the terminal). Returns the
number of columns printed on success.
Output a single EGC (this might be several characters) from |utf8|,
according to the channels |channels|. On success, the number of columns
thought to have been used is returned, and if |sbytes| is not NULL,
the number of bytes consumed will be written there.
Output the string |utf8| according to the channels |channels|. Note that
ncdirect_putstr() does not explicitly flush output buffers, so it will not
necessarily be immediately visible. Returns EOF on error.
Takes the result of ncdirect_render_frame() and writes it to the output,
freeing it on all paths.
Read a (heap-allocated) newline-delimited chunk of text, after printing the
prompt. The newline itself, if present, is included. Returns NULL on error.
Render an image using the specified blitter and scaling, but do not 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(). ‘maxx’
and ‘maxy’ (cell geometry, not pixel), if greater than 0, are used for
scaling; the terminal’s geometry is otherwise used.
Display 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 ncdirect_render_frame() and ncdirect_raster_frame().
ncdirect_box() with the rounded box-drawing characters
Direct mode. This API can be used to colorize and stylize output generated
outside of notcurses, without ever calling notcurses_render(). These should
not be intermixed with standard Notcurses rendering.
ncplane_styles_*() analogues
Release ‘nc’ and any associated resources. 0 on success, non-0 on failure.
Load successive frames from a file, invoking ‘streamer’ on each.
Returns a 16-bit bitmask of supported curses-style attributes
(NCSTYLE_UNDERLINE, NCSTYLE_BOLD, etc.) 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).
Free a ncdirectf returned from ncdirectf_from_file().
Load media from disk, but do not yet render it (presumably because you want
to get its geometry via ncdirectf_geom(), or to use the same file with
ncdirect_render_loaded_frame() multiple times). You must destroy the result
with ncdirectf_free();
Having loaded the frame ‘frame’, get the geometry of a potential render.
Same as ncdirect_render_frame(), except ‘frame’ must already have been
loaded. A loaded frame may be rendered in different ways before it is
destroyed.
Release the resources associated with ‘nctx’.
Return the number of iterations through which ‘nctx’ will fade.
Rather than the simple ncplane_fade{in/out}(), ncfadectx_setup() can be
paired with a loop over ncplane_fade{in/out}_iteration() + ncfadectx_free().
Create an ncfdplane around the fd ‘fd’. Consider this function to take
ownership of the file descriptor, which will be closed in ncfdplane_destroy().
Create a menu with the specified options, bound to the specified plane.
Destroy a menu created with ncmenu_create().
Disable or enable a menu item. Returns 0 if the item was found.
Return the item description corresponding to the mouse click ‘click’. The
item must be on an actively unrolled section, and the click must be in the
area of a valid item. If ‘ni’ is not NULL, and the selected item has a
shortcut, ‘ni’ will be filled in with the shortcut.
Move to the previous/next item within the currently unrolled section. If no
section is unrolled, the first section will be unrolled.
Unroll the previous/next section (relative to current unrolled). If no
section is unrolled, the first section will be unrolled.
Offer the input to the ncmenu. If it’s relevant, this function returns true,
and the input ought not be processed further. If it’s irrelevant to the
menu, false is returned. Relevant inputs include:
Return the ncplane backing this ncmenu.
Roll up any unrolled menu section, and hide the menu if using hiding.
Return the selected item description, or NULL if no section is unrolled. If
‘ni’ is not NULL, and the selected item has a shortcut, ‘ni’ will be filled
in with that shortcut–this can allow faster matching.
Unroll the specified menu section, making the menu visible if it was
invisible, and rolling up any menu section that is already unrolled.
Destroy the ncmultiselector.
Offer the input to the ncmultiselector. If it’s relevant, this function
returns true, and the input ought not be processed further. If it’s
irrelevant to the multiselector, false is returned. Relevant inputs include:
Return a reference to the ncmultiselector’s underlying ncplane.
Return selected vector. An array of bools must be provided, along with its
length. If that length doesn’t match the itemcount, it is an error.
snprintf(3) is used internally, with ‘s’ as its size bound. If the output
requires more size than is available, NULL will be returned.
Free the palette store ‘p’.
Create a new palette store. It will be initialized with notcurses’ best
knowledge of the currently configured palette.
Attempt to configure the terminal with the provided palette ‘p’. Does not
transfer ownership of ‘p’; ncpalette_free() can (ought) still be called.
Return the bottommost plane of the pile containing ‘n’.
Same as ncplane_create(), but creates a new pile. The returned plane will
be the top, bottom, and root of this new pile.
Make the physical screen match the last rendered frame from the pile of
which ‘n’ is a part. This is a blocking call. Don’t call this before the
pile has been rendered (doing so will likely result in a blank screen).
Renders the pile of which ‘n’ is a part. Rendering this pile again will blow
away the render. To actually write out the render, call ncpile_rasterize().
Perform the rendering and rasterization portion of ncpile_render() and
ncpile_rasterize(), but do not write the resulting buffer out to the
terminal. Using this function, the user can control the writeout process.
The returned buffer must be freed by the caller.
Write the last rendered frame, in its entirety, to ‘fp’. If a frame has
not yet been rendered, nothing will be written.
Return the topmost plane of the pile containing ‘n’.
Return the plane above this one, or NULL if this is at the top.
Get the origin of plane ‘n’ relative to its pile. Either or both of ‘x’ and
‘y’ may be NULL.
Create an RGBA flat array from the selected region of the ncplane ‘nc’.
Start at the plane’s ‘begy’x’begx’ coordinate (which must lie on the
plane), continuing for ‘leny’x’lenx’ cells. Either or both of ‘leny’ and
‘lenx’ can be specified as 0 to go through the boundary of the plane.
Only glyphs from the specified ncblitset may be present. If ‘pxdimy’ and/or
‘pxdimx’ are non-NULL, they will be filled in with the total pixel geometry.
Retrieve the current contents of the cell under the cursor. The EGC is
returned, or NULL on error. This EGC must be free()d by the caller. The
stylemask and channels are written to ‘stylemask’ and ‘channels’, respectively.
Retrieve the current contents of the cell under the cursor into ‘c’. This
cell is invalidated if the associated plane is destroyed. Returns the number
of bytes in the EGC, or -1 on error.
Retrieve the current contents of the specified cell. The EGC is returned, or
NULL on error. This EGC must be free()d by the caller. The stylemask and
channels are written to ‘stylemask’ and ‘channels’, respectively. The return
represents how the cell will be used during rendering, and thus integrates
any base cell where appropriate. If called upon the secondary columns of a
wide glyph, the EGC will be returned (i.e. this function does not distinguish
between the primary and secondary columns of a wide glyph). If called on a
sprixel plane, its control sequence is returned for all valid locations.
Retrieve the current contents of the specified cell into ‘c’. This cell is
invalidated if the associated plane is destroyed. Returns the number of
bytes in the EGC, or -1 on error. Unlike ncplane_at_yx(), when called upon
the secondary columns of a wide glyph, the return can be distinguished from
the primary column (nccell_wide_right_p(c) will return true). It is an
error to call this on a sprixel plane (unlike ncplane_at_yx()).
Extract the ncplane’s base nccell into ‘c’. The reference is invalidated if
‘ncp’ is destroyed.
Return the plane below this one, or NULL if this is at the bottom.
Draw a box with its upper-left corner at the current cursor position, and its
lower-right corner at ‘ystop’x’xstop’. The 6 cells provided are used to draw the
upper-left, ur, ll, and lr corners, then the horizontal and vertical lines.
‘ctlword’ is defined in the least significant byte, where bits [7, 4] are a
gradient mask, and [3, 0] are a border mask:
Find the center coordinate of a plane, preferring the top/left in the
case of an even number of rows/columns (in such a case, there will be one
more cell to the bottom/right of the center than the top/left). The
center is then modified relative to the plane’s origin.
Get the current colors and alpha values for ncplane ‘n’.
Create a flat string from the EGCs of the selected region of the ncplane
‘n’. Start at the plane’s ‘begy’x’begx’ coordinate (which must lie on the
plane), continuing for ‘leny’x’lenx’ cells. Either or both of ‘leny’ and
‘lenx’ can be specified as 0 to go through the boundary of the plane.
-1 can be specified for ‘begx’/‘begy’ to use the current cursor location.
Create a new ncplane bound to plane ‘n’, at the offset ‘y’x’x’ (relative to
the origin of ‘n’) and the specified size. The number of ‘rows’ and ‘cols’
must both be positive. This plane is initially at the top of the z-buffer,
as if ncplane_move_top() had been called on it. The void* ‘userptr’ can be
retrieved (and reset) later. A ‘name’ can be set, used in debugging.
Move the cursor relative to the current cursor position (the cursor needn’t
be visible). Returns -1 on error, including target position exceeding the
plane’s dimensions.
Move the cursor to the specified position (the cursor needn’t be visible).
Pass -1 as either coordinate to hold that axis constant. Returns -1 if the
move would place the cursor outside the plane.
Get the current position of the cursor within n. y and/or x may be NULL.
Destroy the specified ncplane. None of its contents will be visible after
the next call to notcurses_render(). It is an error to attempt to destroy
the standard plane.
Return the dimensions of this ncplane. y or x may be NULL.
Duplicate an existing ncplane. The new plane will have the same geometry,
will duplicate all content, and will start with the same rendering state.
The new plane will be immediately above the old one on the z axis, and will
be bound to the same parent (unless ‘n’ is a root plane, in which case the
new plane will be bound to it). Bound planes are not duplicated; the new
plane is bound to the parent of ‘n’, but has no bound planes.
Erase every cell in the ncplane (each cell is initialized to the null glyph
and the default channels/styles). All cells associated with this ncplane are
invalidated, and must not be used after the call, excluding the base cell.
The cursor is homed. The plane’s active attributes are unaffected.
Erase every cell in the region starting at {ystart, xstart} and having size
{|ylen|x|xlen|} for non-zero lengths. If ystart and/or xstart are -1, the current
cursor position along that axis is used; other negative values are an error. A
negative ylen means to move up from the origin, and a negative xlen means to move
left from the origin. A positive ylen moves down, and a positive xlen moves right.
A value of 0 for the length erases everything along that dimension. It is an error
if the starting coordinate is not in the plane, but the ending coordinate may be
outside the plane.
Fade the ncplane in over the specified time. Load the ncplane with the
target cells without rendering, then call this function. When it’s done, the
ncplane will have reached the target levels, starting from zeroes.
Fade in through ‘iter’ iterations, where
‘iter’ < ‘ncfadectx_iterations(nctx)’.
Fade the ncplane out over the provided time, calling ‘fader’ at each
iteration. Requires a terminal which supports truecolor, or at least palette
modification (if the terminal uses a palette, our ability to fade planes is
limited, and affected by the complexity of the rest of the screen).
Fade out through ‘iter’ iterations, where
‘iter’ < ‘ncfadectx_iterations(nctx)’.
Set the given style throughout the specified region, keeping content and
channels unchanged. The upper left corner is at ‘y’, ‘x’, and -1 may be
specified to indicate the cursor’s position in that dimension. The area
is specified by ‘ylen’, ‘xlen’, and 0 may be specified to indicate everything
remaining to the right and below, respectively. It is an error for any
coordinate to be outside the plane. Returns the number of cells set,
or -1 on failure.
Draw a gradient with its upper-left corner at the position specified by ‘y’/‘x’,
where -1 means the current cursor position in that dimension. The area is
specified by ‘ylen’/‘xlen’, where 0 means “everything remaining below or
to the right, respectively.” The glyph composed of ‘egc’ and ‘styles’ is
used for all cells. The channels specified by ‘ul’, ‘ur’, ‘ll’, and ‘lr’
are composed into foreground and background gradients. To do a vertical
gradient, ‘ul’ ought equal ‘ur’ and ‘ll’ ought equal ‘lr’. To do a
horizontal gradient, ‘ul’ ought equal ‘ll’ and ‘ur’ ought equal ‘ul’. To
color everything the same, all four channels should be equivalent. The
resulting alpha values are equal to incoming alpha values. Returns the
number of cells filled on success, or -1 on failure.
Palette-indexed color is not supported.
Do a high-resolution gradient using upper blocks and synced backgrounds.
This doubles the number of vertical gradations, but restricts you to
half blocks (appearing to be full blocks). Returns the number of cells
filled on success, or -1 on error.
Convert the plane’s content to greyscale.
Draw horizontal or vertical lines using the specified cell, starting at the
current cursor position. The cursor will end at the cell following the last
cell output (even, perhaps counter-intuitively, when drawing vertical
lines), just as if ncplane_putc() was called at that spot. Return the
number of cells drawn on success. On error, return the negative number of
cells drawn. A length of 0 is an error, resulting in a return of -1.
Move the cursor to 0, 0. Can’t fail.
Merge the ncplane ‘src’ down onto the ncplane ‘dst’. This is most rigorously
defined as “write to ‘dst’ the frame that would be rendered were the entire
stack made up only of the specified subregion of ‘src’ and, below it, the
subregion of ‘dst’ having the specified origin. Supply -1 to indicate the
current cursor position in the relevant dimension. Merging is independent of
the position of ‘src’ viz ‘dst’ on the z-axis. It is an error to define a
subregion that is not entirely contained within ‘src’. It is an error to
define a target origin such that the projected subregion is not entirely
contained within ‘dst’. Behavior is undefined if ‘src’ and ‘dst’ are
equivalent. ‘dst’ is modified, but ‘src’ remains unchanged. Neither ‘src’
nor ‘dst’ may have sprixels. Lengths of 0 mean “everything left”.
Merge the entirety of ‘src’ down onto the ncplane ‘dst’. If ‘src’ does not
intersect with ‘dst’, ‘dst’ will not be changed, but it is not an error.
Splice ncplane ‘n’ out of the z-buffer, and reinsert it above ‘above’.
Returns non-zero if ‘n’ is already in the desired location. ‘n’ and
‘above’ must not be the same plane. If ‘above’ is NULL, ‘n’ is moved
to the bottom of its pile.
Splice ncplane ‘n’ out of the z-buffer, and reinsert it below ‘below’.
Returns non-zero if ‘n’ is already in the desired location. ‘n’ and
‘below’ must not be the same plane. If ‘below’ is NULL, ‘n’ is moved to
the top of its pile.
Splice ncplane ‘n’ and its bound planes out of the z-buffer, and reinsert
them above or below ‘targ’. Relative order will be maintained between the
reinserted planes. For a plane E bound to C, with z-ordering A B C D E,
moving the C family to the top results in C E A B D, while moving it to
the bottom results in A B D C E.
Move this plane relative to the standard plane, or the plane to which it is
bound (if it is bound to a plane). It is an error to attempt to move the
standard plane.
Return a heap-allocated copy of the plane’s name, or NULL if it has none.
Extract the Notcurses context to which this plane is attached.
Remove the specified styles from the ncplane’s existing spec.
Add the specified styles to the ncplane’s existing spec.
Get the plane to which the plane ‘n’ is bound, if any.
Retrieve pixel geometry for the display region (‘pxy’, ‘pxx’), each cell
(‘celldimy’, ‘celldimx’), and the maximum displayable bitmap (‘maxbmapy’,
‘maxbmapx’). If bitmaps are not supported, or if there is no artificial
limit on bitmap size, ‘maxbmapy’ and ‘maxbmapx’ will be 0. Any of the
geometry arguments may be NULL.
Starting at the specified coordinate, if its glyph is different from that of
‘c’, ‘c’ is copied into it, and the original glyph is considered the fill
target. We do the same to all cardinally-connected cells having this same
fill target. Returns the number of cells polyfilled. An invalid initial y, x
is an error. Returns the number of cells filled, or -1 on error.
Pulse the plane in and out until the callback returns non-zero, relying on
the callback ‘fader’ to initiate rendering. ‘ts’ defines the half-period
(i.e. the transition from black to full brightness, or back again). Proper
use involves preparing (but not rendering) an ncplane, then calling
ncplane_pulse(), which will fade in from black to the specified colors.
Replace the cell at the specified coordinates with the provided cell ‘c’,
and advance the cursor by the width of the cell (but not past the end of the
plane). On success, returns the number of columns the cursor was advanced.
‘c’ must already be associated with ‘n’. On failure, -1 is returned.
Replace the EGC underneath us, but retain the styling. The current styling
of the plane will not be changed.
Replace the EGC underneath us, but retain the styling. The current styling
of the plane will not be changed.
Replace the cell at the specified coordinates with the provided EGC, and
advance the cursor by the width of the cluster (but not past the end of the
plane). On success, returns the number of columns the cursor was advanced.
On failure, -1 is returned. The number of bytes converted from gclust is
written to ‘sbytes’ if non-NULL.
Write the specified text to the plane, breaking lines sensibly, beginning at
the specified line. Returns the number of columns written. When breaking a
line, the line will be cleared to the end of the plane (the last line will
not be so cleared). The number of bytes written from the input is written
to ‘*bytes’ if it is not NULL. Cleared columns are included in the return
value, but not included in the number of bytes written. Leaves the cursor
at the end of output. A partial write will be accomplished as far as it can;
determine whether the write completed by inspecting ‘*bytes’. Can output to
multiple rows even in the absence of scrolling, but not more rows than are
available. With scrolling enabled, arbitrary amounts of data can be emitted.
All provided whitespace is preserved – ncplane_puttext() followed by an
appropriate ncplane_contents() will read back the original output.
Replace the EGC underneath us, but retain the styling. The current styling
of the plane will not be changed.
Draw a QR code at the current position on the plane. If there is insufficient
room to draw the code here, or there is any other error, non-zero will be
returned. Otherwise, the QR code “version” (size) is returned. The QR code
is (version * 4 + 17) columns wide, and ⌈version * 4 + 17⌉ rows tall (the
properly-scaled values are written back to ‘*ymax’ and ‘*xmax’).
Plane ‘n’ will be unbound from its parent plane, and will be made a bound
child of ‘newparent’. It is an error if ‘n’ or ‘newparent’ are NULL. If
‘newparent’ is equal to ‘n’, ‘n’ becomes the root of a new pile, unless ‘n’
is already the root of a pile, in which case this is a no-op. Returns ‘n’.
The standard plane cannot be reparented. Any planes bound to ‘n’ are
reparented to the previous parent of ‘n’.
The same as ncplane_reparent(), except any planes bound to ‘n’ come along
with it to its new destination. Their z-order is maintained. If ‘newparent’
is an ancestor of ‘n’, NULL is returned, and no changes are made.
Resize the specified ncplane. The four parameters ‘keepy’, ‘keepx’,
‘keepleny’, and ‘keeplenx’ define a subset of the ncplane to keep,
unchanged. This may be a region of size 0, though none of these four
parameters may be negative. ‘keepx’ and ‘keepy’ are relative to the ncplane.
They must specify a coordinate within the ncplane’s totality. ‘yoff’ and
‘xoff’ are relative to ‘keepy’ and ‘keepx’, and place the upper-left corner
of the resized ncplane. Finally, ‘ylen’ and ‘xlen’ are the dimensions of the
ncplane after resizing. ‘ylen’ must be greater than or equal to ‘keepleny’,
and ‘xlen’ must be greater than or equal to ‘keeplenx’. It is an error to
attempt to resize the standard plane. If either of ‘keepleny’ or ‘keeplenx’
is non-zero, both must be non-zero.
resize the plane to its parent’s size, attempting to enforce the margins
supplied along with NCPLANE_OPTION_MARGINALIZED.
resize the plane to the visual region’s size (used for the standard plane).
move the plane such that it is entirely within its parent, if possible.
no resizing is performed.
realign the plane ‘n’ against its parent, using the alignments specified
with NCPLANE_OPTION_HORALIGNED and/or NCPLANE_OPTION_VERALIGNED.
Returns the ncplane’s current resize callback.
Rotate the plane π/2 radians clockwise or counterclockwise. This cannot
be performed on arbitrary planes, because glyphs cannot be arbitrarily
rotated. The glyphs which can be rotated are limited: line-drawing
characters, spaces, half blocks, and full blocks. The plane must have
an even number of columns. Use the ncvisual rotation for a more
flexible approach.
Effect |r| scroll events on the plane |n|. Returns an error if |n| is not
a scrolling plane, and otherwise returns the number of lines scrolled.
Scroll |n| up until |child| is no longer hidden beneath it. Returns an
error if |child| is not a child of |n|, or |n| is not scrolling, or |child|
is fixed. Returns the number of scrolling events otherwise (might be 0).
If the child plane is not fixed, it will likely scroll as well.
By default, planes are created with autogrow disabled. Autogrow can be
dynamically controlled with ncplane_set_autogrow(). Returns true if
autogrow was previously enabled, or false if it was disabled.
Set the ncplane’s base nccell. It will be used for purposes of rendering
anywhere that the ncplane’s gcluster is 0. Note that the base cell is not
affected by ncplane_erase(). ‘egc’ must be an extended grapheme cluster.
Returns the number of bytes copied out of ‘gcluster’, or -1 on failure.
Set the ncplane’s base nccell to ‘c’. The base cell is used for purposes of
rendering anywhere that the ncplane’s gcluster is 0. Note that the base cell
is not affected by ncplane_erase(). ‘c’ must not be a secondary cell from a
multicolumn EGC.
Set the background alpha and coloring bits of the plane’s current
channels from a single 32-bit value.
Same, but clipped to [0..255].
Set the alpha and coloring bits of the plane’s current channels from a
64-bit pair of channels.
Set the foreground alpha and coloring bits of the plane’s current
channels from a single 32-bit value.
Set the alpha parameters for ncplane ‘n’.
Use the default color for the foreground/background.
Set the ncplane’s foreground palette index, set the foreground palette index
bit, set it foreground-opaque, and clear the foreground default color bit.
Same, but with rgb assembled into a channel (i.e. lower 24 bits).
Set the current fore/background color using RGB specifications. If the
terminal does not support directly-specified 3x8b cells (24-bit “TrueColor”,
indicated by the “RGB” terminfo capability), the provided values will be
interpreted in some lossy fashion. None of r, g, or b may exceed 255.
“HP-like” terminals require setting foreground and background at the same
time using “color pairs”; Notcurses will manage color pairs transparently.
Set the plane’s name (may be NULL), replacing any current name.
Replace the ncplane’s existing resizecb with ‘resizecb’ (which may be NULL).
The standard plane’s resizecb may not be changed.
All planes are created with scrolling disabled. Scrolling can be dynamically
controlled with ncplane_set_scrolling(). Returns true if scrolling was
previously enabled, or false if it was disabled.
Set the specified style bits for the ncplane ‘n’, whether they’re actively
supported or not.
Manipulate the opaque user pointer associated with this plane.
ncplane_set_userptr() returns the previous userptr after replacing
it with ‘opaque’. the others simply return the userptr.
Set the given channels throughout the specified region, keeping content and
channels unchanged. The upper left corner is at ‘y’, ‘x’, and -1 may be
specified to indicate the cursor’s position in that dimension. The area
is specified by ‘ylen’, ‘xlen’, and 0 may be specified to indicate everything
remaining to the right and below, respectively. It is an error for any
coordinate to be outside the plane. Returns the number of cells set,
or -1 on failure.
Get the current styling for the ncplane ‘n’.
provided a coordinate relative to the origin of ‘src’, map it to the same
absolute coordinate relative to the origin of ‘dst’. either or both of ‘y’
and ‘x’ may be NULL. if ‘dst’ is NULL, it is taken to be the standard plane.
Fed absolute ‘y’/‘x’ coordinates, determine whether that coordinate is
within the ncplane ‘n’. If not, return false. If so, return true. Either
way, translate the absolute coordinates relative to ‘n’. If the point is not
within ‘n’, these coordinates will not be within the dimensions of the plane.
The ncplane equivalents of printf(3) and vprintf(3).
Get the origin of plane ‘n’ relative to its bound plane, or pile (if ‘n’ is
a root plane). To get absolute coordinates, use ncplane_abs_yx().
Takes ownership of the ncplane ‘n’, which will be destroyed by
ncprogbar_destroy(). The progress bar is initially at 0%.
Destroy the progress bar and its underlying ncplane.
Return a reference to the ncprogbar’s underlying ncplane.
Get the progress bar’s completion, a double on [0, 1].
Set the progress bar’s completion, a double 0 <= ‘p’ <= 1.
empty the ncreader of any user input, and home the cursor.
return a heap-allocated copy of the current (UTF-8) contents.
ncreaders provide freeform input in a (possibly multiline) region, supporting
optional readline keybindings. takes ownership of ‘n’, destroying it on any
error (ncreader_destroy() otherwise destroys the ncplane).
destroy the reader and its bound plane. if ‘contents’ is not NULL, the
UTF-8 input will be heap-duplicated and written to ‘contents’.
Atttempt to move in the specified direction. Returns 0 if a move was
successfully executed, -1 otherwise. Scrolling is taken into account.
Offer the input to the ncreader. If it’s relevant, this function returns
true, and the input ought not be processed further. Almost all inputs
are relevant to an ncreader, save synthesized ones.
Destructively write the provided EGC to the current cursor location. Move
the cursor as necessary, scrolling if applicable.
Add a new nctablet to the provided ncreel ‘nr’, having the callback object
‘opaque’. Neither, either, or both of ‘after’ and ‘before’ may be specified.
If neither is specified, the new tablet can be added anywhere on the reel.
If one or the other is specified, the tablet will be added before or after
the specified tablet. If both are specified, the tablet will be added to the
resulting location, assuming it is valid (after->next == before->prev); if
it is not valid, or there is any other error, NULL will be returned.
Take over the ncplane ‘nc’ and use it to draw a reel according to ‘popts’.
The plane will be destroyed by ncreel_destroy(); this transfers ownership.
Delete the tablet specified by t from the ncreel ‘nr’. Returns -1 if the
tablet cannot be found.
Destroy an ncreel allocated with ncreel_create().
Return the focused tablet, if any tablets are present. This is not a copy;
be careful to use it only for the duration of a critical section.
Change focus to the next tablet, if one exists
Offer input ‘ni’ to the ncreel ‘nr’. If it’s relevant, this function returns
true, and the input ought not be processed further. If it’s irrelevant to
the reel, false is returned. Relevant inputs include:
Returns the ncplane on which this ncreel lives.
Change focus to the previous tablet, if one exists
Redraw the ncreel ‘nr’ in its entirety. The reel will be cleared, and
tablets will be lain out, using the focused tablet as a fulcrum. Tablet
drawing callbacks will be invoked for each visible tablet.
Return the number of nctablets in the ncreel ‘nr’.
Dynamically add or delete items. It is usually sufficient to supply a static
list of items via ncselector_options->items.
Destroy the ncselector.
Offer the input to the ncselector. If it’s relevant, this function returns
true, and the input ought not be processed further. If it’s irrelevant to
the selector, false is returned. Relevant inputs include:
Return a reference to the ncselector’s underlying ncplane.
Move up or down in the list. A reference to the newly-selected item is
returned, or NULL if there are no items in the list.
Return reference to the selected option, or NULL if there are no items.
Returns the number of columns occupied by the longest valid prefix of a
multibyte (UTF-8) string. If an invalid character is encountered, -1 will be
returned, and the number of valid bytes and columns will be written into
*|validbytes| and *|validwidth| (assuming them non-NULL). If the entire
string is valid, *|validbytes| and *|validwidth| reflect the entire string.
see exec(2). p-types use $PATH. e-type passes environment vars.
Returns the tab callback.
Move ‘t’ after ‘after’ (if not NULL) and before ‘before’ (if not NULL).
If both ‘after’ and ‘before’ are NULL, the function returns -1, otherwise
it returns 0.
Move ‘t’ to the right by one tab, looping around to become the last tab if needed.
Move ‘t’ to the right by one tab, looping around to become leftmost if needed.
Returns the tab name. This is not a copy and it should not be stored.
Returns the width (in columns) of the tab’s name.
Returns the tab to the right of ‘t’. This does not change which tab is selected.
Returns the tab to the left of ‘t’. This does not change which tab is selected.
Set the tab callback function for ‘t’. Returns the previous tab callback.
Change the name of ‘t’. Returns -1 if ‘newname’ is NULL, and 0 otherwise.
Set the user pointer of ‘t’. Returns the previous user pointer.
Returns the tab’s user pointer.
Add a new tab to ‘nt’ with the given tab callback, name, and user pointer.
If both ‘before’ and ‘after’ are NULL, the tab is inserted after the selected
tab. Otherwise, it gets put after ‘after’ (if not NULL) and before ‘before’
(if not NULL). If both ‘after’ and ‘before’ are given, they must be two
neighboring tabs (the tab list is circular, so the last tab is immediately
before the leftmost tab), otherwise the function returns NULL. If ‘name’ is
NULL or a string containing illegal characters, the function returns NULL.
On all other failures the function also returns NULL. If it returns NULL,
none of the arguments are modified, and the widget state is not altered.
Write the channels for tab headers, the selected tab header, and the separator
to ‘*hdrchan’, ‘*selchan’, and ‘*sepchan’ respectively.
Returns the tab content plane.
Creates a new nctabbed widget, associated with the given ncplane ‘n’, and with
additional options given in ‘opts’. When ‘opts’ is NULL, it acts as if it were
called with an all-zero opts. The widget takes ownership of ‘n’, and destroys
it when the widget is destroyed. Returns the newly created widget. Returns
NULL on failure, also destroying ‘n’.
Remove a tab ‘t’ from ‘nt’. Its neighboring tabs become neighbors to each
other. If ‘t’ if the selected tab, the tab after ‘t’ becomes selected.
Likewise if ‘t’ is the leftmost tab, the tab after ‘t’ becomes leftmost.
If ‘t’ is the only tab, there will no more be a selected or leftmost tab,
until a new tab is added. Returns -1 if ‘t’ is NULL, and 0 otherwise.
Destroy an nctabbed widget. All memory belonging to ‘nt’ is deallocated,
including all tabs and their names. The plane associated with ‘nt’ is also
destroyed. Calling this with NULL does nothing.
Make sure the tab header of the currently selected tab is at least partially
visible. (by rotating tabs until at least one column is displayed)
Does nothing if there are no tabs.
Returns the leftmost tab, or NULL if there are no tabs.
Select the tab after the currently selected tab, and return the newly selected
tab. Returns NULL if there are no tabs.
Returns the plane associated to ‘nt’.
Select the tab before the currently selected tab, and return the newly selected
tab. Returns NULL if there are no tabs.
Redraw the widget. This calls the tab callback of the currently selected tab
to draw tab contents, and draws tab headers. The tab content plane is not
modified by this function, apart from resizing the plane is necessary.
Rotate the tabs of ‘nt’ right by ‘amt’ tabs, or ‘-amt’ tabs left if ‘amt’ is
negative. Tabs are rotated only by changing the leftmost tab; the selected tab
stays the same. If there are no tabs, nothing happens.
Change the selected tab to be ‘t’. Returns the previously selected tab.
Returns the currently selected tab, or NULL if there are no tabs.
Returns the tab separator. This is not a copy and it should not be stored.
This can be NULL, if the separator was set to NULL in ncatbbed_create() or
nctabbed_set_separator().
Returns the tab separator width, or zero if there is no separator.
Set the tab headers channel for ‘nt’.
Set the selected tab header channel for ‘nt’.
Change the tab separator for ‘nt’. Returns -1 if ‘separator’ is not NULL and
is not a valid string, and 0 otherwise.
Set the tab separator channel for ‘nt’.
Returns the number of tabs in the widget.
Access the ncplane associated with nctablet ‘t’, if one exists.
Returns a pointer to a user pointer associated with this nctablet.
Insert |add| into the nctree |n| at |spec|. The path up to the last element
must already exist. If an item already exists at the path, it will be moved
to make room for |add|.
|opts| may not be NULL, since it is necessary to define a callback
function.
Delete the item at |spec|, including any subitems.
Destroy the nctree.
Return the focused item, if any items are present. This is not a copy;
be careful to use it only for the duration of a critical section.
Go to the item specified by the array |spec| (a spec is a series of unsigned
values, each identifying a subelement in the hierarchy thus far, terminated
by UINT_MAX). If the spec is invalid, NULL is returned, and the depth of the
first invalid spec is written to *|failspec|. Otherwise, the true depth is
written to *|failspec|, and the curry is returned (|failspec| is necessary
because the curry could itself be NULL).
Change focus to the next item.
Offer input ‘ni’ to the nctree ‘n’. If it’s relevant, this function returns
true, and the input ought not be processed further. If it’s irrelevant to
the tree, false is returned. Relevant inputs include:
Returns the ncplane on which this nctree lives.
Change focus to the previous item.
Redraw the nctree ‘n’ in its entirety. The tree will be cleared, and items
will be lain out, using the focused item as a fulcrum. Item-drawing
callbacks will be invoked for each visible item.
Add to or set the value corresponding to this x. If x is beyond the current
x window, the x window is advanced to include x, and values passing beyond
the window are lost. The first call will place the initial window. The plot
will be redrawn, but notcurses_render() is not called.
Use the provided plane ‘n’ for plotting according to the options ‘opts’. The
plot will make free use of the entirety of the plane. For domain
autodiscovery, set miny == maxy == 0. ncuplot holds uint64_ts, while
ncdplot holds doubles.
Return a reference to the ncplot’s underlying ncplane.
Get the specified pixel from the specified ncvisual.
Render the decoded frame according to the provided options (which may be
NULL). The plane used for rendering depends on vopts->n and vopts->flags.
If NCVISUAL_OPTION_CHILDPLANE is set, vopts->n must not be NULL, and the
plane will always be created as a child of vopts->n. If this flag is not
set, and vopts->n is NULL, a new plane is created as root of a new pile.
If the flag is not set and vopts->n is not NULL, we render to vopts->n.
A subregion of the visual can be rendered using ‘begx’, ‘begy’, ‘lenx’, and
‘leny’. Negative values for any of these are an error. It is an error to
specify any region beyond the boundaries of the frame. Returns the (possibly
newly-created) plane to which we drew. Pixels may not be blitted to the
standard plane.
extract the next frame from an ncvisual. returns 1 on end of file, 0 on
success, and -1 on failure.
decode the next frame ala ncvisual_decode(), but if we have reached the end,
rewind to the first frame of the ncvisual. a subsequent ‘ncvisual_blit()’
will render the first frame, as if the ncvisual had been closed and reopened.
the return values remain the same as those of ncvisual_decode().
Destroy an ncvisual. Rendered elements will not be disrupted, but the visual
can be neither decoded nor rendered any further.
ncvisual_from_rgba(), but ‘bgra’ is arranged as BGRA. note that this is a
byte-oriented layout, despite being bunched in 32-bit pixels; the lowest
memory address ought be B, and A is reached by adding 3 to that address.
Open a visual at ‘file’, extract a codec and parameters, decode the first
image to memory.
ncvisual_from_rgba(), but ‘data’ is ‘pstride’-byte palette-indexed pixels,
arranged in ‘rows’ lines of ‘rowstride’ bytes each, composed of ‘cols’
pixels. ‘palette’ is an array of at least ‘palsize’ ncchannels.
Promote an ncplane ‘n’ to an ncvisual. The plane may contain only spaces,
half blocks, and full blocks. The latter will be checked, and any other
glyph will result in a NULL being returned. This function exists so that
planes can be subjected to ncvisual transformations. If possible, it’s
better to create the ncvisual from memory using ncvisual_from_rgba().
Lengths of 0 are interpreted to mean “all available remaining area”.
ncvisual_from_rgba(), but the pixels are 4-byte RGBx. A is filled in
throughout using ‘alpha’. rowstride must be a multiple of 4.
ncvisual_from_rgba(), but the pixels are 3-byte RGB. A is filled in
throughout using ‘alpha’.
Prepare an ncvisual, and its underlying plane, based off RGBA content in
memory at ‘rgba’. ‘rgba’ is laid out as ‘rows’ lines, each of which is
‘rowstride’ bytes in length. Each line has ‘cols’ 32-bit 8bpc RGBA pixels
followed by possible padding (there will be ‘rowstride’ - ‘cols’ * 4 bytes
of padding). The total size of ‘rgba’ is thus (rows * rowstride) bytes, of
which (rows * cols * 4) bytes are actual non-padding data.
Construct an ncvisual from a nul-terminated Sixel control sequence.
all-purpose ncvisual geometry solver. one or both of ‘nc’ and ‘n’ must be
non-NULL. if ‘nc’ is NULL, only pixy/pixx will be filled in, with the true
pixel geometry of ‘n’. if ‘n’ is NULL, only cdimy/cdimx, blitter,
scaley/scalex, and maxpixely/maxpixelx are filled in. cdimy/cdimx and
maxpixely/maxpixelx are only ever filled in if we know them.
Get the default media (not plot) blitter for this environment when using
the specified scaling method. Currently, this means:
Polyfill at the specified location within the ncvisual ‘n’, using ‘rgba’.
Scale the visual to ‘rows’ X ‘columns’ pixels, using the best scheme
available. This is a lossy transformation, unless the size is unchanged.
Scale the visual to ‘rows’ X ‘columns’ pixels, using non-interpolative
(naive) scaling. No new colors will be introduced as a result.
Rotate the visual ‘rads’ radians. Only M_PI/2 and -M_PI/2 are supported at
the moment, but this might change in the future.
Set the specified pixel in the specified ncvisual.
Shut up and display my frames! Provide as an argument to ncvisual_stream().
If you’d like subtitles to be decoded, provide an ncplane as the curry. If the
curry is NULL, subtitles will not be displayed.
Stream the entirety of the media, according to its own timing. Blocking,
obviously. streamer may be NULL; it is otherwise called for each frame, and
its return value handled as outlined for streamcb. If streamer() returns
non-zero, the stream is aborted, and that value is returned. By convention,
return a positive number to indicate intentional abort from within
streamer(). ‘timescale’ allows the frame duration time to be scaled. For a
visual naturally running at 30FPS, a ‘timescale’ of 0.1 will result in
300FPS, and a ‘timescale’ of 10 will result in 3FPS. It is an error to
supply ‘timescale’ less than or equal to 0.
If a subtitle ought be displayed at this time, return a new plane (bound
to ‘parent’ containing the subtitle, which might be text or graphics
(depending on the input format).
Returns a heap-allocated copy of the user name under which we are running.
Retrieve the contents of the specified cell as last rendered. Returns the EGC
or NULL on error. This EGC must be free()d by the caller. The stylemask and
channels are written to ‘stylemask’ and ‘channels’, respectively.
Can we load images? This requires being built against FFmpeg/OIIO.
Can we load videos? This requires being built against FFmpeg.
Can we blit pixel-accurate bitmaps?
The same as notcurses_init(), but without any multimedia functionality,
allowing for a svelter binary. Link with notcurses-core if this is used.
Disable the hardware cursor. It is an error to call this while the
cursor is already disabled.
Enable or disable 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. Can be
called while already visible to move the cursor.
Get the current location of the terminal’s cursor, whether visible or not.
Dump selected Notcurses state to the supplied ‘debugfp’. Output is freeform,
newline-delimited, and subject to change. It includes geometry of all
planes, from all piles. No line has more than 80 columns’ worth of output.
Get the default background color, if it is known. Returns -1 on error
(unknown background). On success, returns 0, writing the RGB value to
‘bg’ (if non-NULL) and setting ‘bgtrans’ high iff the background color
is treated as transparent.
Get the default foreground color, if it is known. Returns -1 on error
(unknown foreground). On success, returns 0, writing the RGB value to
‘fg’ (if non-NULL)
Returns the name (and sometimes version) of the terminal, as Notcurses
has been best able to determine.
Destroy all ncplanes other than the stdplane.
Shift to the alternate screen, if available. If already using the alternate
screen, this returns 0 immediately. If the alternate screen is not
available, this returns -1 immediately. Entering the alternate screen turns
off scrolling for the standard plane.
Read a UTF-32-encoded Unicode codepoint from input. This might only be part
of a larger EGC. Provide a NULL ‘ts’ to block at length, and otherwise a
timespec specifying an absolute deadline calculated using CLOCK_MONOTONIC.
Returns a single Unicode code point, or a synthesized special key constant,
or (uint32_t)-1 on error. Returns 0 on a timeout. If an event is processed,
the return value is the ‘id’ field from that event. ‘ni’ may be NULL.
Acquire up to ‘vcount’ ncinputs at the vector ‘ni’. The number read will be
returned, or -1 on error without any reads, 0 on timeout.
Returns a heap-allocated copy of the local host name.
Initialize a Notcurses context on the connected terminal at ‘fp’. ‘fp’ must
be a tty. You’ll usually want stdout. NULL can be supplied for ‘fp’, in
which case /dev/tty will be opened. Returns NULL on error, including any
failure initializing terminfo.
Get a file descriptor suitable for input event poll()ing. When this
descriptor becomes available, you can call notcurses_get_nblock(),
and input ought be ready. This file descriptor is not necessarily
the file descriptor associated with stdin (but it might be!).
Exit the alternate screen. Immediately returns 0 if not currently using the
alternate screen.
Lex a blitter.
Lex 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.
Lex a scaling mode (one of “none”, “stretch”, “scale”, “hires”,
“scalehi”, or “inflate”).
Disable signals originating from the terminal’s line discipline, i.e.
SIGINT (^C), SIGQUIT (^), and SIGTSTP (^Z). They are enabled by default.
Restore signals originating from the terminal’s line discipline, i.e.
SIGINT (^C), SIGQUIT (^), and SIGTSTP (^Z), if disabled.
Enable mice events according to ‘eventmask’; an eventmask of 0 will disable
all mice tracking. On failure, -1 is returned. On success, 0 is returned, and
mouse events will be published to notcurses_get().
Returns a heap-allocated copy of human-readable OS name and version.
Returns the number of simultaneous colors claimed to be supported, or 1 if
there is no color support. Note that several terminal emulators advertise
more colors than they actually support, downsampling internally.
Refresh the physical screen to match what was last rendered (i.e., without
reflecting any changes since the last call to notcurses_render()). 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. The
current screen geometry is returned in ‘y’ and ‘x’, if they are not NULL.
Acquire an atomic snapshot of the Notcurses object’s stats.
Allocate an ncstats object. Use this rather than allocating your own, since
future versions of Notcurses might enlarge this structure.
Reset all cumulative stats (immediate ones, such as fbbytes, are not reset),
first copying them into |*stats| (if |stats| is not NULL).
Get a reference to the standard plane (one matching our current idea of the
terminal size) for this terminal. The standard plane always exists, and its
origin is always at the uppermost, leftmost cell of the terminal.
Destroy a Notcurses context. A NULL ‘nc’ is a no-op.
Get the name of a blitter.
Get the name of a scaling mode.
Returns a 16-bit bitmask of supported curses-style attributes
(NCSTYLE_UNDERLINE, NCSTYLE_BOLD, etc.) 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).
input functions like notcurses_get() return ucs32-encoded uint32_t. convert
a series of uint32_t to utf8. result must be at least 4 bytes per input
uint32_t (6 bytes per uint32_t will future-proof against Unicode expansion).
the number of bytes used is returned, or -1 if passed illegal ucs32, or too
small of a buffer.
Get a human-readable string describing the running Notcurses version.
Cannot be inline, as we want to get the versions of the actual Notcurses
library we loaded, not what we compile against.
Get and/or set the action for signal SIG.
Add SIGNO to SET.
Remove SIGNO from SET.
Clear all signals from SET.
Set all signals in SET.
Return 1 if SIGNO is in SET, 0 if not.
Put in SET all signals that are blocked and waiting to be delivered.
Get and/or change the set of blocked signals.
Change the set of blocked signals to SET,
wait until a signal arrives, and restore the set of blocked signals.
Type Definitions
The tag name of this struct is _IO_FILE to preserve historic
C++ mangled names for functions taking FILE* arguments.
That name should not be used in new code.
The tag name of this struct is _G_fpos64_t to preserve historic
C++ mangled names for functions taking fpos_t and/or fpos64_t
arguments. That name should not be used in new code.
The tag name of this struct is _G_fpos_t to preserve historic
C++ mangled names for functions taking fpos_t arguments.
That name should not be used in new code.
Fixed-size types, underlying types depend on word size and compiler.
Smallest types with at least a given width.
These few don’t really vary by system, they always correspond
to one of the other defined types.
C99: An integer type that can be accessed as an atomic entity,
even in the presence of asynchronous interrupts.
It is not currently necessary for this to be machine-specific.
Type of a signal handler.
Types of sockets.
Convenience types.
Returned by `clock’.
Clock ID used in clock and timer functions.
Called for each fade iteration on ‘ncp’. If anything but 0 is returned,
the fading operation ceases immediately, and that value is propagated out.
The recommended absolute display time target is passed in ‘tspec’.
The tag name of this struct is _G_fpos_t to preserve historic
C++ mangled names for functions taking fpos_t arguments.
That name should not be used in new code.
Internet address.
Type to represent a port.
Signed.
Signed.
Largest integral types.
Alignment within a plane or terminal. Left/right-justified, or centered.
we never blit full blocks, but instead spaces (more efficient) with the
background set to the desired foreground. these need be kept in the same
order as the blitters[] definition in lib/blit.c.
These log levels consciously map cleanly to those of libav; Notcurses itself
does not use this full granularity. The log level does not affect the opening
and closing banners, which can be disabled via the notcurses_option struct’s
‘suppress_banner’. Note that if stderr is connected to the same terminal on
which we’re rendering, any kind of logging will disrupt the output (which is
undesirable). The “default” zero value is NCLOGLEVEL_PANIC.
pixel blitting implementations. informative only; don’t special-case
based off any of this information!
How to scale an ncvisual during rendering. NCSCALE_NONE will apply no
scaling. NCSCALE_SCALE scales a visual to the plane’s size, maintaining
aspect ratio. NCSCALE_STRETCH stretches and scales the image in an attempt
to fill the entirety of the plane. NCSCALE_NONE_HIRES and
NCSCALE_SCALE_HIRES behave like their counterparts, but admit blitters
which don’t preserve aspect ratio.
Called for each frame rendered from ‘ncv’. If anything but 0 is returned,
the streaming operation ceases immediately, and that value is propagated out.
The recommended absolute display time target is passed in ‘tspec’.
POSIX.1g specifies this type name for the `sa_family’ member.
An integral type that can be modified atomically, without the
possibility of a signal arriving in the middle of the operation.
A set of signals to be blocked, unblocked, or waited for.
Tab content drawing callback. Takes the tab it was associated to, the ncplane
on which tab content is to be drawn, and the user pointer of the tab.
It is called during nctabbed_redraw().
Tablet draw callback, provided a tablet (from which the ncplane and userptr
may be extracted), and a bool indicating whether output ought be drawn from
the top (true) or bottom (false). Returns non-negative count of output lines,
which must be less than or equal to ncplane_dim_y(nctablet_plane(t)).
Timer ID returned by `timer_create’.
These were defined by ISO C without the first `_’.
Unsigned.
Unsigned.
Scalar type that can hold values which represent locale-specific
character classifications.