1notcurses_output(3)                                        notcurses_output(3)
2
3
4

NAME

6       notcurses_output - output to ncplanes
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11       static inline int ncplane_putc(struct ncplane* n, const nccell* c);
12
13       int ncplane_putc_yx(struct ncplane* n, int y, int x, const nccell* c);
14
15       static inline int ncplane_putchar(struct ncplane* n, char c);
16
17       static  inline  int ncplane_putchar_yx(struct ncplane* n, int y, int x,
18       char c);
19
20       int ncplane_putchar_stained(struct ncplane* n, char c);
21
22       static inline int ncplane_putwc(struct ncplane* n, wchar_t w);
23
24       int ncplane_putwc_yx(struct ncplane* n, int y, int x, wchar_t w);
25
26       static inline int ncplane_putwc_stained(struct ncplane* n, wchar_t w);
27
28       static inline int ncplane_putegc(struct ncplane* n, const char* gclust,
29       int* sbytes);
30
31       int  ncplane_putegc_yx(struct  ncplane*  n,  int  y, int x, const char*
32       gclust, int* sbytes);
33
34       int ncplane_putegc_stained(struct ncplane* n, const char* gclust,  int*
35       sbytes);
36
37       static  inline  int  ncplane_putwegc(struct  ncplane* n, const wchar_t*
38       gclust, int* sbytes);
39
40       static inline int ncplane_putwegc_yx(struct ncplane* n, int y,  int  x,
41       const wchar_t* gclust, int* sbytes);
42
43       int  ncplane_putwegc_stained(struct  ncplane* n, const wchar_t* gclust,
44       int* sbytes);
45
46       int ncplane_putstr_yx(struct ncplane* n, int  y,  int  x,  const  char*
47       gclustarr);
48
49       static  inline int ncplane_putstr(struct ncplane* n, const char* gclus‐
50       tarr);
51
52       int ncplane_putstr_aligned(struct ncplane* n, int y,  ncalign_e  align,
53       const char* s);
54
55       int ncplane_putstr_stained(struct ncplane* n, const char* s);
56
57       static  inline  int  ncplane_putwstr(struct  ncplane* n, const wchar_t*
58       gclustarr);
59
60       int ncplane_putwstr_yx(struct ncplane* n, int y, int x, const  wchar_t*
61       gclustarr);
62
63       static  inline  int  ncplane_putwstr_aligned(struct  ncplane* n, int y,
64       ncalign_e align, const wchar_t* gclustarr);
65
66       int ncplane_putwstr_stained(struct ncplane* n,  const  wchar_t*  gclus‐
67       tarr);
68
69       static  inline  int  ncplane_putnstr(struct ncplane* n, size_t s, const
70       char* gclustarr);
71
72       int ncplane_putnstr_yx(struct ncplane* n, int y, int x, size_t s, const
73       char* gclusters);
74
75       int  ncplane_putnstr_aligned(struct ncplane* n, int y, ncalign_e align,
76       size_t s, const char* s);
77
78       int ncplane_vprintf_aligned(struct ncplane* n, int y, ncalign_e  align,
79       const char* format, va_list ap);
80
81       int  ncplane_vprintf_yx(struct  ncplane*  n,  int y, int x, const char*
82       format, va_list ap);
83
84       static inline int ncplane_vprintf(struct ncplane* n, const  char*  for‐
85       mat, va_list ap);
86
87       static inline int ncplane_printf(struct ncplane* n, const char* format,
88       ...);
89
90       static inline int ncplane_printf_yx(struct ncplane* n, int  y,  int  x,
91       const char* format, ...);
92
93       static  inline  int  ncplane_printf_aligned(struct  ncplane*  n, int y,
94       ncalign_e align, const char* format, ...);
95
96       int ncplane_cursor_move_yx(struct ncplane* n, int y, int x);
97
98       int ncplane_puttext(struct ncplane* n, int y,  ncalign_e  align,  const
99       char* text, size_t* bytes);
100

DESCRIPTION

102       These  functions  write EGCs (Extended Grapheme Clusters) to the speci‐
103       fied struct ncplanes.  The following inputs are supported:
104
105ncplane_putc(): writes a single nccell (see notcurses_cell(3))
106
107ncplane_putchar(): writes a single 7-bit ASCII character
108
109ncplane_putwc(): writes a single wchar_t (following UTF-8 conversion)
110
111ncplane_putwegc(): writes a single EGC from an array of wchar_t
112
113ncplane_putegc(): writes a single EGC from an array of UTF-8
114
115ncplane_putstr(): writes a set of EGCs from an array of UTF-8
116
117ncplane_putwstr(): writes a set of EGCs from an array of wchar_t
118
119ncplane_vprintf(): formatted output using va_list
120
121ncplane_printf(): formatted output using variadic arguments
122
123ncplane_puttext(): multi-line, line-broken, aligned text
124
125       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
134       These functions output to the ncplane's current cursor location.  Aside
135       from ncplane_puttext(), they do not move to the next line upon reaching
136       the right extreme of the containing plane.  If the entirety of the con‐
137       tent cannot be output, they will output as much as possible.
138
139       Each of these base functions has two additional forms:
140
141ncplane_putc_aligned(), etc.: accepts a row and an alignment type
142
143ncplane_putc_yx(), etc.: accepts a row and column
144
145       If a positional parameter is -1, no movement will be  made  along  that
146       axis.  Passing -1, -1 to e.g.  ncplane_putc_yx() is equivalent to call‐
147       ing the base form.  These functions are implemented by moving the  cur‐
148       sor,  and then performing the output.  The two steps are atomic on suc‐
149       cess (it is not possible for another caller to move the cursor  between
150       when  it  is  positioned, and when output begins), and thus these func‐
151       tions  ought  generally  be  preferred  to  an  explicit   ncplane_cur‐
152       sor_move_yx().
153
154       Upon successful return, the cursor will follow the last cell output.
155

RETURN VALUES

157       ncplane_cursor_move_yx() returns -1 on error (invalid coordinate), or 0
158       on success.
159
160       For output functions, a negative return indicates an error with the in‐
161       puts.   Otherwise, the number of screen columns output is returned.  It
162       is entirely possible to get a short return, if there  was  insufficient
163       room to output all EGCs.
164

SEE ALSO

166       fprintf(3)    notcurses(3),    notcurses_cell(3),   notcurses_plane(3),
167       stdarg(3), ascii(7), unicode(7), utf-8(7)
168

AUTHORS

170       nick black <nickblack@linux.com>.
171
172
173
174                                    v2.3.1                 notcurses_output(3)
Impressum