% ncdirect_init(3) % nick black % v2.1.2 # NAME ncdirect_init - minimal notcurses instances for styling text # SYNOPSIS **#include ** **struct ncdirect* ncdirect_init(const char* ***termtype***, FILE* ***fp***, uint64_t ***flags***);** **unsigned ncdirect_palette_size(const struct ncdirect* ***nc***);** **int ncdirect_bg_rgb8(struct ncdirect* ***nc***, unsigned ***r***, unsigned ***g***, unsigned ***b***);** **int ncdirect_fg_rgb8(struct ncdirect* ***nc***, unsigned ***r***, unsigned ***g***, unsigned ***b***);** **int ncdirect_fg_rgb(struct ncdirect* ***nc***, unsigned ***rgb***);** **int ncdirect_bg_rgb(struct ncdirect* ***nc***, unsigned ***rgb***);** **int ncdirect_fg_default(struct ncdirect* ***nc***);** **int ncdirect_bg_default(struct ncdirect* ***nc***);** **int ncdirect_dim_x(const struct ncdirect* ***nc***);** **int ncdirect_dim_y(const struct ncdirect* ***nc***);** **int ncdirect_styles_set(struct ncdirect* ***n***, unsigned ***stylebits***);** **int ncdirect_styles_on(struct ncdirect* ***n***, unsigned ***stylebits***);** **int ncdirect_styles_off(struct ncdirect* ***n***, unsigned ***stylebits***);** **int ncdirect_clear(struct ncdirect* ***nc***)** **int ncdirect_stop(struct ncdirect* ***nc***);** **int ncdirect_cursor_move_yx(struct ncdirect* ***n***, int ***y***, int ***x***);** **int ncdirect_cursor_enable(struct ncdirect* ***nc***);** **int ncdirect_cursor_disable(struct ncdirect* ***nc***);** **int ncdirect_cursor_up(struct ncdirect* ***nc***, int ***num***);** **int ncdirect_cursor_left(struct ncdirect* ***nc***, int ***num***);** **int ncdirect_cursor_right(struct ncdirect* ***nc***, int ***num***);** **int ncdirect_cursor_down(struct ncdirect* ***nc***, int ***num***);** **int ncdirect_putstr(struct ncdirect* ***nc***, uint64_t ***channels***, const char* ***utf8***);** **int ncdirect_printf_aligned(struct ncdirect* ***n***, int ***y***, ncalign_e ***align***, const char* ***fmt***, ***...***);** **bool ncdirect_canopen_images(const struct ncdirect* ***n***);** **bool ncdirect_canutf8(const struct ncdirect* ***n***);** **int ncdirect_hline_interp(struct ncdirect* ***n***, const char* ***egc***, int ***len***, uint64_t ***h1***, uint64_t ***h2***);** **int ncdirect_vline_interp(struct ncdirect* ***n***, const char* ***egc***, int ***len***, uint64_t ***h1***, uint64_t ***h2***);** **int ncdirect_box(struct ncdirect* ***n***, uint64_t ***ul***, uint64_t ***ur***, uint64_t ***ll***, uint64_t ***lr***, const wchar_t* ***wchars***, int ***ylen***, int ***xlen***, unsigned ***ctlword***);** **int ncdirect_rounded_box(struct ncdirect* ***n***, uint64_t ***ul***, uint64_t ***ur***, uint64_t ***ll***, uint64_t ***lr***, int ***ylen***, int ***xlen***, unsigned ***ctlword***);** **int ncdirect_double_box(struct ncdirect* ***n***, uint64_t ***ul***, uint64_t ***ur***, uint64_t ***ll***, uint64_t ***lr***, int ***ylen***, int ***xlen***, unsigned ***ctlword***);** **int ncdirect_render_image(struct ncdirect* ***n***, const char* ***filename***, ncblitter_e ***blitter***, ncscale_e ***scale***);** # DESCRIPTION **ncdirect_init** prepares the **FILE** provided as **fp** for colorizing and styling. On success, a pointer to a valid **struct ncdirect** is returned. **NULL** is returned on failure. Before the process exits, **ncdirect_stop** should be called to reset the terminal and free up resources. **ncdirect_init** places the terminal into "cbreak" (also known as "rare") mode, disabling line-buffering and echo of input. **ncdirect_stop** restores the terminal state as it was when the corresponding **ncdirect_init** call was made. The following flags are defined: * **NCDIRECT_OPTION_INHIBIT_SETLOCALE**: Unless this flag is set, **ncdirect_init** will call **setlocale(LC_ALL, NULL)**. If the result is either "**C**" or "**POSIX**", it will print a diagnostic to **stderr**, and then call **setlocale(LC_ALL, "").** This will attempt to set the locale based off the **LANG** environment variable. Your program should call **setlocale(3)** itself, usually as one of the first lines. * **NCDIRECT_OPTION_INHIBIT_CBREAK**: Unless this flag is set, **ncdirect_init** will place the terminal into cbreak mode (i.e. disabling echo and line buffering; see **tcgetattr(3)**). An appropriate **terminfo(5)** entry must exist for the terminal. This entry is usually selected using the value of the **TERM** environment variable (see **getenv(3)**), but a non-**NULL** value for **termtype** will override this. An invalid terminfo specification can lead to reduced performance, reduced display capabilities, and/or display errors. notcurses natively targets 24bpp/8bpc RGB color, and it is thus desirable to use a terminal with the **rgb** capability (e.g. xterm's **xterm-direct**). **ncdirect_dim_x** returns the current number of columns, and **ncdirect_dim_y** the current number of rows. **ncdirect_clear** clears the screen using a control code if one exists in terminfo. Otherwise, it prints successive newlines to scroll everything off. **ncdirect_cursor_move_yx** moves the cursor to the specified coordinate. -1 can be specified for either **y** or **x** to leave that axis unchanged. **ncdirect_enable_cursor** and **ncdirect_disable_cursor** always flush the output stream, taking effect immediately. **ncdirect_cursor_up** and friends all move relative to the current position. Attempting to e.g. move up while on the top row will return 0, but have no effect. # RETURN VALUES **ncdirect_init** returns **NULL** on failure. Otherwise, the return value points to a valid **struct ncdirect**, which can be used until it is provided to **ncdirect_stop**. **ncdirect_putstr** and **ncdirect_printf_aligned** return the number of bytes written on success. On failure, they return some negative number. All other functions return 0 on success, and non-zero on error. # SEE ALSO **getenv(3)**, **termios(3)**, **notcurses(3)**, **notcurses_plane(3)**, **terminfo(5)**