notcurses_direct(3)

1notcurses_direct(3)                                        notcurses_direct(3)
2
3
4

NAME

6       notcurses_direct - minimal notcurses instances for styling text
7

SYNOPSIS

9              #include <notcurses/direct.h>
10
11              #define NCDIRECT_OPTION_INHIBIT_SETLOCALE   0x0001ull
12              #define NCDIRECT_OPTION_INHIBIT_CBREAK      0x0002ull
13              #define NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS 0x0008ull
14
15       struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t
16       flags);
17
18       unsigned ncdirect_palette_size(const struct ncdirect* nc);
19
20       int ncdirect_set_bg_rgb8(struct ncdirect* nc, unsigned r,  unsigned  g,
21       unsigned b);
22
23       int  ncdirect_set_fg_rgb8(struct  ncdirect* nc, unsigned r, unsigned g,
24       unsigned b);
25
26       int ncdirect_set_fg_rgb(struct ncdirect* nc, unsigned rgb);
27
28       int ncdirect_set_bg_rgb(struct ncdirect* nc, unsigned rgb);
29
30       int ncdirect_set_fg_default(struct ncdirect* nc);
31
32       int ncdirect_set_bg_default(struct ncdirect* nc);
33
34       int ncdirect_set_fg_palindex(struct ncdirect* nc, int pidx);
35
36       int ncdirect_set_bg_palindex(struct ncdirect* nc, int pidx);
37
38       int ncdirect_dim_x(const struct ncdirect* nc);
39
40       int ncdirect_dim_y(const struct ncdirect* nc);
41
42       int ncdirect_styles_set(struct ncdirect* n, unsigned stylebits);
43
44       int ncdirect_styles_on(struct ncdirect* n, unsigned stylebits);
45
46       int ncdirect_styles_off(struct ncdirect* n, unsigned stylebits);
47
48       int ncdirect_clear(struct ncdirect* nc)
49
50       int ncdirect_stop(struct ncdirect* nc);
51
52       int ncdirect_cursor_move_yx(struct ncdirect* n, int y, int x);
53
54       int ncdirect_cursor_enable(struct ncdirect* nc);
55
56       int ncdirect_cursor_disable(struct ncdirect* nc);
57
58       int ncdirect_cursor_up(struct ncdirect* nc, int num);
59
60       int ncdirect_cursor_left(struct ncdirect* nc, int num);
61
62       int ncdirect_cursor_right(struct ncdirect* nc, int num);
63
64       int ncdirect_cursor_down(struct ncdirect* nc, int num);
65
66       int ncdirect_putstr(struct ncdirect* nc, uint64_t channels, const char*
67       utf8);
68
69       int ncdirect_printf_aligned(struct ncdirect* n, int y, ncalign_e align,
70       const char* fmt, ...);
71
72       bool ncdirect_canopen_images(const struct ncdirect* n);
73
74       bool ncdirect_canutf8(const struct ncdirect* n);
75
76       int ncdirect_check_pixel_support(struct ncdirect* n);
77
78       int ncdirect_hline_interp(struct ncdirect* n, const char* egc, int len,
79       uint64_t h1, uint64_t h2);
80
81       int ncdirect_vline_interp(struct ncdirect* n, const char* egc, int len,
82       uint64_t h1, uint64_t h2);
83
84       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
88       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
91       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
94       int ncdirect_render_image(struct ncdirect*  n,  const  char*  filename,
95       ncblitter_e blitter, ncscale_e scale);
96
97       char* ncdirect_readline(struct ncdirect* n, const char* prompt);
98

DESCRIPTION

100       ncdirect_init  prepares  the  FILE  provided  as  fp for colorizing and
101       styling.  On success, a pointer to a valid struct ncdirect is returned.
102       NULL  is  returned on failure.  Before the process exits, ncdirect_stop
103       should be called to reset the terminal and free  up  resources.   ncdi‐
104       rect_init  places  the  terminal  into  "cbreak" (also known as "rare")
105       mode, disabling line-buffering and echo of  input.   ncdirect_stop  re‐
106       stores  the  terminal  state  as  it  was  when the corresponding ncdi‐
107       rect_init call was made.
108
109       The following flags are defined:
110
111       · NCDIRECT_OPTION_INHIBIT_SETLOCALE: Unless this  flag  is  set,  ncdi‐
112         rect_init will call setlocale(LC_ALL, NULL).  If the result is either
113         "C" or "POSIX", it will print a diagnostic to stderr, and  then  call
114         setlocale(LC_ALL, "").  This will attempt to set the locale based off
115         the LANG environment variable.  Your program should call setlocale(3)
116         itself, usually as one of the first lines.
117
118       · NCDIRECT_OPTION_INHIBIT_CBREAK:   Unless  this  flag  is  set,  ncdi‐
119         rect_init will place the terminal into cbreak mode  (i.e.   disabling
120         echo and line buffering; see tcgetattr(3)).
121
122       · NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be
123         installed for SIGINT, SIGILL, SIGQUIT, SIGSEGV, SIGTERM, and SIGABRT,
124         cleaning  up  the  terminal  on such exceptions.  With this flag, the
125         handler will not be installed.
126
127       An appropriate terminfo(5) entry must exist for the terminal.  This en‐
128       try  is  usually selected using the value of the TERM environment vari‐
129       able (see getenv(3)), but a non-NULL value for termtype  will  override
130       this.   An  invalid  terminfo specification can lead to reduced perfor‐
131       mance, reduced display capabilities, and/or display errors.   notcurses
132       natively  targets 24bpp/8bpc RGB color, and it is thus desirable to use
133       a terminal with the rgb capability (e.g.  xterm's xterm-direct).
134
135       ncdirect_dim_x  returns  the  current  number  of  columns,  and  ncdi‐
136       rect_dim_y the current number of rows.
137
138       ncdirect_clear  clears the screen using a control code if one exists in
139       terminfo.  Otherwise, it prints successive newlines  to  scroll  every‐
140       thing off.
141
142       ncdirect_cursor_move_yx  moves  the cursor to the specified coordinate.
143       -1 can be specified for either y or x to leave that axis unchanged.
144
145       ncdirect_enable_cursor and  ncdirect_disable_cursor  always  flush  the
146       output stream, taking effect immediately.
147
148       ncdirect_cursor_up  and  friends all move relative to the current posi‐
149       tion.  Attempting to e.g.  move up while on the top row will return  0,
150       but have no effect.
151
152       ncdirect_readline  uses the Readline library to read a (heap-allocated)
153       line of arbitrary length, supporting line-editing controls.   For  more
154       information, consult readline(3).  If you want input echoed to the ter‐
155       minal  while  using  ncdirect_readline,  NCDIRECT_OPTION_INHIBIT_CBREAK
156       must be supplied to ncdirect_init.
157
158       ncdirect_check_pixel_support  must  be called (and successfully return)
159       before NCBLIT_PIXEL can be used to render  images;  see  notcurses_vis‐
160       ual(3) for more details.
161

RETURN VALUES

163       ncdirect_init  returns  NULL  on  failure.  Otherwise, the return value
164       points to a valid struct ncdirect, which can be used until it  is  pro‐
165       vided to ncdirect_stop.
166
167       ncdirect_putstr  and ncdirect_printf_aligned return the number of bytes
168       written on success.  On failure, they return some negative number.
169
170       ncdirect_check_pixel_support returns -1 on error, 0 if there is no pix‐
171       el support, and 1 if pixel support is successfully detected.
172
173       All other functions return 0 on success, and non-zero on error.
174

AUTHORS

180       nick black <nickblack@linux.com>.
181
182
183
184                                    v2.2.3                 notcurses_direct(3)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

SEE ALSO

AUTHORS