1notcurses_output(3) notcurses_output(3)
2
6 notcurses_output - output to ncplanes
7
9 #include <notcurses/notcurses.h>
10 static inline int ncplane_putc(struct ncplane* n, const nccell* c);
12 int ncplane_putc_yx(struct ncplane* n, int y, int x, const nccell* c);
14 static inline int ncplane_putchar(struct ncplane* n, char c);
16 static inline int ncplane_putchar_yx(struct ncplane* n, int y, int x,
18 char c);
19 int ncplane_putchar_stained(struct ncplane* n, char c);
21 static inline int ncplane_putwc(struct ncplane* n, wchar_t w);
23 int ncplane_putwc_yx(struct ncplane* n, int y, int x, wchar_t w);
25 static inline int ncplane_putwc_stained(struct ncplane* n, wchar_t w);
27 static inline int ncplane_putegc(struct ncplane* n, const char* gclust,
29 int* sbytes);
30 int ncplane_putegc_yx(struct ncplane* n, int y, int x, const char*
32 gclust, int* sbytes);
33 int ncplane_putegc_stained(struct ncplane* n, const char* gclust, int*
35 sbytes);
36 static inline int ncplane_putwegc(struct ncplane* n, const wchar_t*
38 gclust, int* sbytes);
39 static inline int ncplane_putwegc_yx(struct ncplane* n, int y, int x,
41 const wchar_t* gclust, int* sbytes);
42 int ncplane_putwegc_stained(struct ncplane* n, const wchar_t* gclust,
44 int* sbytes);
45 int ncplane_putstr_yx(struct ncplane* n, int y, int x, const char*
47 gclustarr);
48 static inline int ncplane_putstr(struct ncplane* n, const char* gclus‐
50 tarr);
51 int ncplane_putstr_aligned(struct ncplane* n, int y, ncalign_e align,
53 const char* s);
54 int ncplane_putstr_stained(struct ncplane* n, const char* s);
56 static inline int ncplane_putwstr(struct ncplane* n, const wchar_t*
58 gclustarr);
59 int ncplane_putwstr_yx(struct ncplane* n, int y, int x, const wchar_t*
61 gclustarr);
62 static inline int ncplane_putwstr_aligned(struct ncplane* n, int y,
64 ncalign_e align, const wchar_t* gclustarr);
65 int ncplane_putwstr_stained(struct ncplane* n, const wchar_t* gclus‐
67 tarr);
68 static inline int ncplane_putnstr(struct ncplane* n, size_t s, const
70 char* gclustarr);
71 int ncplane_putnstr_yx(struct ncplane* n, int y, int x, size_t s, const
73 char* gclusters);
74 int ncplane_putnstr_aligned(struct ncplane* n, int y, ncalign_e align,
76 size_t s, const char* s);
77 int ncplane_vprintf_aligned(struct ncplane* n, int y, ncalign_e align,
79 const char* format, va_list ap);
80 int ncplane_vprintf_yx(struct ncplane* n, int y, int x, const char*
82 format, va_list ap);
83 static inline int ncplane_vprintf(struct ncplane* n, const char* for‐
85 mat, va_list ap);
86 static inline int ncplane_printf(struct ncplane* n, const char* format,
88 ...);
89 static inline int ncplane_printf_yx(struct ncplane* n, int y, int x,
91 const char* format, ...);
92 static inline int ncplane_printf_aligned(struct ncplane* n, int y,
94 ncalign_e align, const char* format, ...);
95 int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);
97 int ncplane_puttext(struct ncplane* n, int y, ncalign_e align, const
99 char* text, size_t* bytes);
100
102 These functions write EGCs (Extended Grapheme Clusters) to the speci‐
103 fied struct ncplanes. The following inputs are supported:
104 • ncplane_putc(): writes a single nccell (see notcurses_cell(3))
106 • ncplane_putchar(): writes a single 7-bit ASCII character
108 • ncplane_putwc(): writes a single wchar_t (following UTF-8 conversion)
110 • ncplane_putwegc(): writes a single EGC from an array of wchar_t
112 • ncplane_putegc(): writes a single EGC from an array of UTF-8
114 • ncplane_putstr(): writes a set of EGCs from an array of UTF-8
116 • ncplane_putwstr(): writes a set of EGCs from an array of wchar_t
118 • ncplane_vprintf(): formatted output using va_list
120 • ncplane_printf(): formatted output using variadic arguments
122 • ncplane_puttext(): multi-line, line-broken, aligned text
124 All of these use the ncplane's active styling, save notcurses_putc(),
126 which uses the nccell's styling. Functions accepting a single EGC ex‐
127 pect a series of wchar_t terminated by L'\0' or a series of UTF-8 char
128 terminated by '\0'. The EGC must be well-formed, and must not contain
129 any cluster breaks. For more information, consult Unicode® Standard
130 Annex #29 (https://unicode.org/reports/tr29/). Functions accepting a
131 set of EGCs must consist of a series of well-formed EGCs, broken by
132 cluster breaks, terminated by the appropriate NUL terminator.
133 Control characters are rejected, aside from two exceptions: a horizon‐
135 tal tab (', 0x09), and a newline ('', 0x0a) when the output plane is in
136 scrolling mode. A newline outside of scrolling mode will be rejected.
137 A tab will advance to the next tab stop, filling the space between with
138 spaces. Tab stops are separated by eight columns, and the first char‐
139 acter of each line is a tab stop.
140 These functions output to the ncplane's current cursor location. Aside
142 from ncplane_puttext(), they do not move to the next line upon reaching
143 the right extreme of the containing plane. If the entirety of the con‐
144 tent cannot be output, they will output as much as possible.
145 Each of these base functions has two additional forms:
147 • ncplane_putc_aligned(), etc.: accepts a row and an alignment type
149 • ncplane_putc_yx(), etc.: accepts a row and column
151 If a positional parameter is -1, no movement will be made along that
153 axis. Passing -1, -1 to e.g. ncplane_putc_yx() is equivalent to call‐
154 ing the base form. These functions are implemented by moving the cur‐
155 sor, and then performing the output. The two steps are atomic on suc‐
156 cess (it is not possible for another caller to move the cursor between
157 when it is positioned, and when output begins), and thus these func‐
158 tions ought generally be preferred to an explicit ncplane_cur‐
159 sor_move_yx().
160 Upon successful return, the cursor will follow the last cell output.
162
164 ncplane_cursor_move_yx() returns -1 on error (invalid coordinate), or 0
165 on success.
166 For output functions, a negative return indicates an error with the in‐
168 puts. Otherwise, the number of screen columns output is returned. It
169 is entirely possible to get a short return, if there was insufficient
170 room to output all EGCs.
171
173 fprintf(3) notcurses(3), notcurses_cell(3), notcurses_plane(3),
174 stdarg(3), ascii(7), unicode(7), utf-8(7)
175
177 nick black <nickblack@linux.com>.
178 v3.0.8 notcurses_output(3)