.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_output" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_output - output to ncplanes
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.PP
\f[B]static inline int ncplane_putc(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const cell* \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putc_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], const cell*
\f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putchar(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], char \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putchar_yx(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]y\f[R]\f[B], int
\f[R]\f[I]x\f[R]\f[B], char \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putchar_stained(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
char \f[R]\f[I]c\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putwc(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], wchar_t \f[R]\f[I]w\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putwc_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], wchar_t
\f[R]\f[I]w\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putwc_stained(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], wchar_t \f[R]\f[I]w\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putegc(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]gclust\f[R]\f[B], int*
\f[R]\f[I]sbytes\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putegc_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], const char*
\f[R]\f[I]gclust\f[R]\f[B], int* \f[R]\f[I]sbytes\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putegc_stained(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]gclust\f[R]\f[B], int*
\f[R]\f[I]sbytes\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putwegc(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const wchar_t* \f[R]\f[I]gclust\f[R]\f[B], int*
\f[R]\f[I]sbytes\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putwegc_yx(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]y\f[R]\f[B], int
\f[R]\f[I]x\f[R]\f[B], const wchar_t* \f[R]\f[I]gclust\f[R]\f[B], int*
\f[R]\f[I]sbytes\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putwegc_stained(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const wchar_t* \f[R]\f[I]gclust\f[R]\f[B], int*
\f[R]\f[I]sbytes\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putstr_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], const char*
\f[R]\f[I]gclustarr\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putstr(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]gclustarr\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putstr_aligned(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]y\f[R]\f[B], ncalign_e \f[R]\f[I]align\f[R]\f[B], const
char* \f[R]\f[I]s\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putstr_stained(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]s\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putwstr(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const wchar_t*
\f[R]\f[I]gclustarr\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putwstr_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], const wchar_t*
\f[R]\f[I]gclustarr\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putwstr_aligned(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]y\f[R]\f[B], ncalign_e
\f[R]\f[I]align\f[R]\f[B], const wchar_t*
\f[R]\f[I]gclustarr\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putwstr_stained(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const wchar_t* \f[R]\f[I]gclustarr\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_putnstr(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], size_t \f[R]\f[I]s\f[R]\f[B], const char*
\f[R]\f[I]gclustarr\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putnstr_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], size_t
\f[R]\f[I]s\f[R]\f[B], const char* \f[R]\f[I]gclusters\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_putnstr_aligned(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]y\f[R]\f[B], ncalign_e \f[R]\f[I]align\f[R]\f[B], size_t
\f[R]\f[I]s\f[R]\f[B], const char* \f[R]\f[I]s\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_vprintf_aligned(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]y\f[R]\f[B], ncalign_e \f[R]\f[I]align\f[R]\f[B], const
char* \f[R]\f[I]format\f[R]\f[B], va_list \f[R]\f[I]ap\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_vprintf_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B], const char*
\f[R]\f[I]format\f[R]\f[B], va_list \f[R]\f[I]ap\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_vprintf(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]format\f[R]\f[B], va_list
\f[R]\f[I]ap\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_printf(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]format\f[R]\f[B],
\f[R]\f[I]\&...\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_printf_yx(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]y\f[R]\f[B], int
\f[R]\f[I]x\f[R]\f[B], const char* \f[R]\f[I]format\f[R]\f[B],
\f[R]\f[I]\&...\f[R]\f[B]);\f[R]
.PP
\f[B]static inline int ncplane_printf_aligned(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]y\f[R]\f[B], ncalign_e
\f[R]\f[I]align\f[R]\f[B], const char* \f[R]\f[I]format\f[R]\f[B],
\f[R]\f[I]\&...\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_cursor_move_yx(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
int \f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B]);\f[R]
.PP
\f[B]int ncplane_puttext(struct ncplane* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]y\f[R]\f[B], ncalign_e \f[R]\f[I]align\f[R]\f[B], const char*
\f[R]\f[I]text\f[R]\f[B], size_t* \f[R]\f[I]bytes\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
These functions write EGCs (Extended Grapheme Clusters) to the specified
\f[B]struct ncplane\f[R]s.
The following inputs are supported:
.IP \[bu] 2
\f[B]ncplane_putc()\f[R]: writes a single cell (see
\f[B]notcurses_cell(3)\f[R])
.IP \[bu] 2
\f[B]ncplane_putchar()\f[R]: writes a single 7-bit ASCII character
.IP \[bu] 2
\f[B]ncplane_putwc()\f[R]: writes a single \f[B]wchar_t\f[R] (following
UTF-8 conversion)
.IP \[bu] 2
\f[B]ncplane_putwegc()\f[R]: writes a single EGC from an array of
\f[B]wchar_t\f[R]
.IP \[bu] 2
\f[B]ncplane_putegc()\f[R]: writes a single EGC from an array of UTF-8
.IP \[bu] 2
\f[B]ncplane_putstr()\f[R]: writes a set of EGCs from an array of UTF-8
.IP \[bu] 2
\f[B]ncplane_putwstr()\f[R]: writes a set of EGCs from an array of
\f[B]wchar_t\f[R]
.IP \[bu] 2
\f[B]ncplane_vprintf()\f[R]: formatted output using \f[B]va_list\f[R]
.IP \[bu] 2
\f[B]ncplane_printf()\f[R]: formatted output using variadic arguments
.IP \[bu] 2
\f[B]ncplane_puttext()\f[R]: multi-line, line-broken, aligned text
.PP
All of these use the \f[B]ncplane\f[R]\[cq]s active styling, save
\f[B]notcurses_putc()\f[R], which uses the cell\[cq]s styling.
Functions accepting a single EGC expect a series of \f[B]wchar_t\f[R]
terminated by \f[B]L\[cq]\[rs]0\[cq]\f[R] or a series of UTF-8
\f[B]char\f[R] terminated by \f[B]`\[rs]0'\f[R].
The EGC must be well-formed, and must not contain any cluster breaks.
For more information, consult Unicode\[rg] Standard Annex
#29 (https://unicode.org/reports/tr29/).
Functions accepting a set of EGCs must consist of a series of
well-formed EGCs, broken by cluster breaks, terminated by the
appropriate NUL terminator.
.PP
These functions output to the \f[C]ncplane\f[R]\[cq]s current cursor
location.
Aside from \f[B]ncplane_puttext()\f[R], they \f[I]do not\f[R] move to
the next line upon reaching the right extreme of the containing plane.
If the entirety of the content cannot be output, they will output as
much as possible.
.PP
Each of these base functions has two additional forms:
.IP \[bu] 2
\f[B]ncplane_putc_aligned()\f[R], etc.: accepts a row and an alignment
type
.IP \[bu] 2
\f[B]ncplane_putc_yx()\f[R], etc.: accepts a row and column
.PP
If a positional parameter is -1, no movement will be made along that
axis.
Passing \f[B]-1, -1\f[R] to e.g.\ \f[B]ncplane_putc_yx()\f[R] is
equivalent to calling the base form.
These functions are implemented by moving the cursor, and then
performing the output.
The two steps are \f[I]atomic\f[R] on success (it is not possible for
another caller to move the cursor between when it is positioned, and
when output begins), and thus these functions ought generally be
preferred to an explicit \f[B]ncplane_cursor_move_yx()\f[R].
.PP
Upon successful return, the cursor will follow the last cell output.
.SH RETURN VALUES
.PP
\f[B]ncplane_cursor_move_yx()\f[R] returns -1 on error (invalid
coordinate), or 0 on success.
.PP
For output functions, a negative return indicates an error with the
inputs.
Otherwise, the number of \f[I]screen columns\f[R] output is returned.
It is entirely possible to get a short return, if there was insufficient
room to output all EGCs.
.SH SEE ALSO
.PP
\f[B]fprintf(3)\f[R] \f[B]notcurses(3)\f[R],
\f[B]notcurses_cell(3)\f[R], \f[B]notcurses_plane(3)\f[R],
\f[B]stdarg(3)\f[R], \f[B]ascii(7)\f[R], \f[B]unicode(7)\f[R],
\f[B]utf-8(7)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.