1notcurses_direct(3) notcurses_direct(3)
2
6 notcurses_direct - minimal notcurses instances for styling text
7
9 #include <notcurses/direct.h>
10 #define NCDIRECT_OPTION_INHIBIT_SETLOCALE 0x0001ull
12 #define NCDIRECT_OPTION_INHIBIT_CBREAK 0x0002ull
13 #define NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS 0x0008ull
14 struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t
16 flags);
17 unsigned ncdirect_palette_size(const struct ncdirect* nc);
19 int ncdirect_set_bg_rgb8(struct ncdirect* nc, unsigned r, unsigned g,
21 unsigned b);
22 int ncdirect_set_fg_rgb8(struct ncdirect* nc, unsigned r, unsigned g,
24 unsigned b);
25 int ncdirect_set_fg_rgb(struct ncdirect* nc, unsigned rgb);
27 int ncdirect_set_bg_rgb(struct ncdirect* nc, unsigned rgb);
29 int ncdirect_set_fg_default(struct ncdirect* nc);
31 int ncdirect_set_bg_default(struct ncdirect* nc);
33 int ncdirect_set_fg_palindex(struct ncdirect* nc, int pidx);
35 int ncdirect_set_bg_palindex(struct ncdirect* nc, int pidx);
37 int ncdirect_dim_x(const struct ncdirect* nc);
39 int ncdirect_dim_y(const struct ncdirect* nc);
41 int ncdirect_styles_set(struct ncdirect* n, unsigned stylebits);
43 int ncdirect_styles_on(struct ncdirect* n, unsigned stylebits);
45 int ncdirect_styles_off(struct ncdirect* n, unsigned stylebits);
47 int ncdirect_clear(struct ncdirect* nc)
49 int ncdirect_stop(struct ncdirect* nc);
51 int ncdirect_cursor_move_yx(struct ncdirect* n, int y, int x);
53 int ncdirect_cursor_enable(struct ncdirect* nc);
55 int ncdirect_cursor_disable(struct ncdirect* nc);
57 int ncdirect_cursor_up(struct ncdirect* nc, int num);
59 int ncdirect_cursor_left(struct ncdirect* nc, int num);
61 int ncdirect_cursor_right(struct ncdirect* nc, int num);
63 int ncdirect_cursor_down(struct ncdirect* nc, int num);
65 int ncdirect_putstr(struct ncdirect* nc, uint64_t channels, const char*
67 utf8);
68 int ncdirect_printf_aligned(struct ncdirect* n, int y, ncalign_e align,
70 const char* fmt, ...);
71 bool ncdirect_canopen_images(const struct ncdirect* n);
73 bool ncdirect_canutf8(const struct ncdirect* n);
75 int ncdirect_check_pixel_support(struct ncdirect* n);
77 int ncdirect_hline_interp(struct ncdirect* n, const char* egc, int len,
79 uint64_t h1, uint64_t h2);
80 int ncdirect_vline_interp(struct ncdirect* n, const char* egc, int len,
82 uint64_t h1, uint64_t h2);
83 int ncdirect_box(struct ncdirect* n, uint64_t ul, uint64_t ur, uint64_t
85 ll, uint64_t lr, const wchar_t* wchars, int ylen, int xlen, unsigned
86 ctlword);
87 int ncdirect_rounded_box(struct ncdirect* n, uint64_t ul, uint64_t ur,
89 uint64_t ll, uint64_t lr, int ylen, int xlen, unsigned ctlword);
90 int ncdirect_double_box(struct ncdirect* n, uint64_t ul, uint64_t ur,
92 uint64_t ll, uint64_t lr, int ylen, int xlen, unsigned ctlword);
93 ncdirectv* ncdirect_render_frame(struct ncdirect* n, const char* file‐
95 name, ncblitter_e blitter, ncscale_e scale, int maxy, int maxx);
96 char* ncdirect_readline(struct ncdirect* n, const char* prompt);
98 typedef struct ncvgeom {
100 int pixy, pixx; // true pixel geometry of ncvisual data
101 int cdimy, cdimx; // terminal cell geometry when this was calculated
102 int rpixy, rpixx; // rendered pixel geometry
103 int rcelly, rcellx; // rendered cell geometry
104 int scaley, scalex; // pixels per filled cell
105 // only defined for NCBLIT_PIXEL
106 int maxpixely, maxpixelx;
107 } ncvgeom;
108 int ncdirect_render_image(struct ncdirect* n, const char* filename,
110 ncblitter_e blitter, ncscale_e scale);
111 int ncdirect_raster_frame(struct ncdirect* n, ncdirectv* ncdv,
113 ncalign_e align);
114 int ncdirect_stream(struct ncdirect* n, const char* filename, ncstream‐
116 cb streamer, struct ncvisual_options* vopts, void* curry);
117 int ncdirect_raster_frame(struct ncdirect* n, ncdirectv* ncdv,
119 ncalign_e align);
120 struct ncdirectf* ncdirectf_from_file(struct ncdirect* n, const char*
122 filename);*
123 void ncdirectf_free(struct ncdirectf* frame);
125 ncdirectv* ncdirectf_render(struct ncdirect* n, struct ncdirectf*
127 frame, ncblitter_e blitter, ncscale_e scale, int maxy, int maxx);
128 int ncdirectf_geom(struct ncdirect* n, struct ncdirectf* frame, ncblit‐
130 ter_e* blitter, ncscale_e scale, int maxy, int maxx, ncvgeom* geom);
131
133 ncdirect_init prepares the FILE provided as fp for colorizing and
134 styling. On success, a pointer to a valid struct ncdirect is returned.
135 NULL is returned on failure. Before the process exits, ncdirect_stop
136 should be called to reset the terminal and free up resources. ncdi‐
137 rect_init places the terminal into "cbreak" (also known as "rare")
138 mode, disabling line-buffering and echo of input. ncdirect_stop re‐
139 stores the terminal state as it was when the corresponding ncdi‐
140 rect_init call was made.
141 The following flags are defined:
143 • NCDIRECT_OPTION_INHIBIT_SETLOCALE: Unless this flag is set, ncdi‐
145 rect_init will call setlocale(LC_ALL, NULL). If the result is either
146 "C" or "POSIX", it will print a diagnostic to stderr, and then call
147 setlocale(LC_ALL, ""). This will attempt to set the locale based off
148 the LANG environment variable. Your program should call setlocale(3)
149 itself, usually as one of the first lines.
150 • NCDIRECT_OPTION_INHIBIT_CBREAK: Unless this flag is set, ncdi‐
152 rect_init will place the terminal into cbreak mode (i.e. disabling
153 echo and line buffering; see tcgetattr(3)).
154 • NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be
156 installed for SIGINT, SIGILL, SIGQUIT, SIGSEGV, SIGTERM, and SIGABRT,
157 cleaning up the terminal on such exceptions. With this flag, the
158 handler will not be installed.
159 An appropriate terminfo(5) entry must exist for the terminal. This en‐
161 try is usually selected using the value of the TERM environment vari‐
162 able (see getenv(3)), but a non-NULL value for termtype will override
163 this. An invalid terminfo specification can lead to reduced perfor‐
164 mance, reduced display capabilities, and/or display errors. notcurses
165 natively targets 24bpp/8bpc RGB color, and it is thus desirable to use
166 a terminal with the rgb capability (e.g. xterm's xterm-direct).
167 ncdirect_dim_x returns the current number of columns, and ncdi‐
169 rect_dim_y the current number of rows.
170 ncdirect_clear clears the screen using a control code if one exists in
172 terminfo. Otherwise, it prints successive newlines to scroll every‐
173 thing off.
174 ncdirect_cursor_move_yx moves the cursor to the specified coordinate.
176 -1 can be specified for either y or x to leave that axis unchanged.
177 ncdirect_enable_cursor and ncdirect_disable_cursor always flush the
179 output stream, taking effect immediately.
180 ncdirect_cursor_up and friends all move relative to the current posi‐
182 tion. Attempting to e.g. move up while on the top row will return 0,
183 but have no effect.
184 ncdirect_readline uses the Readline library to read a (heap-allocated)
186 line of arbitrary length, supporting line-editing controls. For more
187 information, consult readline(3). If you want input echoed to the ter‐
188 minal while using ncdirect_readline, NCDIRECT_OPTION_INHIBIT_CBREAK
189 must be supplied to ncdirect_init.
190 ncdirect_check_pixel_support must be called (and successfully return)
192 before NCBLIT_PIXEL can be used to render images; see notcurses_vis‐
193 ual(3) for more details.
194 When rendering an image, maxy and maxx specify a maximum number of
196 (cell) rows and columns to use, respectively. Passing 0 means "use as
197 much space as is necessary". It is an error to pass a negative number
198 for either.
199
201 ncdirect_init returns NULL on failure. Otherwise, the return value
202 points to a valid struct ncdirect, which can be used until it is pro‐
203 vided to ncdirect_stop.
204 ncdirect_putstr and ncdirect_printf_aligned return the number of bytes
206 written on success. On failure, they return some negative number.
207 ncdirect_check_pixel_support returns -1 on error, 0 if there is no pix‐
209 el support, and 1 if pixel support is successfully detected.
210 All other functions return 0 on success, and non-zero on error.
212
214 getenv(3), readline(3) notcurses(3), notcurses_plane(3), notcurses_vis‐
215 ual(3), terminfo(5), termios(3)
216
218 nick black <nickblack@linux.com>.
219 v2.3.1 notcurses_direct(3)