.\" Automatically generated by Pandoc 2.9.2.1 .\" .TH "ncdirect_init" "3" "v2.0.4" "" "" .hy .SH NAME .PP ncdirect_init - minimal notcurses instances for styling text .SH SYNOPSIS .PP \f[B]#include \f[R] .PP \f[B]struct ncdirect* ncdirect_init(const char* \f[R]\f[I]termtype\f[R]\f[B], FILE* \f[R]\f[I]fp\f[R]\f[B], uint64_t \f[R]\f[I]flags\f[R]\f[B]);\f[R] .PP \f[B]unsigned ncdirect_palette_size(const struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_bg_rgb8(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], unsigned \f[R]\f[I]r\f[R]\f[B], unsigned \f[R]\f[I]g\f[R]\f[B], unsigned \f[R]\f[I]b\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_fg_rgb8(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], unsigned \f[R]\f[I]r\f[R]\f[B], unsigned \f[R]\f[I]g\f[R]\f[B], unsigned \f[R]\f[I]b\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_fg_rgb(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], unsigned \f[R]\f[I]rgb\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_bg_rgb(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], unsigned \f[R]\f[I]rgb\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_fg_default(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_bg_default(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_dim_x(const struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_dim_y(const struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_styles_set(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_styles_on(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_styles_off(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], unsigned \f[R]\f[I]stylebits\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_clear(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B])\f[R] .PP \f[B]int ncdirect_stop(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_cursor_move_yx(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]y\f[R]\f[B], int \f[R]\f[I]x\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_cursor_enable(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_cursor_disable(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_cursor_up(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]num\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_cursor_left(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]num\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_cursor_right(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]num\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_cursor_down(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]num\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_putstr(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], uint64_t \f[R]\f[I]channels\f[R]\f[B], const char* \f[R]\f[I]utf8\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_printf_aligned(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]y\f[R]\f[B], ncalign_e \f[R]\f[I]align\f[R]\f[B], const char* \f[R]\f[I]fmt\f[R]\f[B], \f[R]\f[I]\&...\f[R]\f[B]);\f[R] .PP \f[B]bool ncdirect_canopen_images(const struct ncdirect* \f[R]\f[I]n\f[R]\f[B]);\f[R] .PP \f[B]bool ncdirect_canutf8(const struct ncdirect* \f[R]\f[I]n\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_hline_interp(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]egc\f[R]\f[B], int \f[R]\f[I]len\f[R]\f[B], uint64_t \f[R]\f[I]h1\f[R]\f[B], uint64_t \f[R]\f[I]h2\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_vline_interp(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]egc\f[R]\f[B], int \f[R]\f[I]len\f[R]\f[B], uint64_t \f[R]\f[I]h1\f[R]\f[B], uint64_t \f[R]\f[I]h2\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_box(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], uint64_t \f[R]\f[I]ul\f[R]\f[B], uint64_t \f[R]\f[I]ur\f[R]\f[B], uint64_t \f[R]\f[I]ll\f[R]\f[B], uint64_t \f[R]\f[I]lr\f[R]\f[B], const wchar_t* \f[R]\f[I]wchars\f[R]\f[B], int \f[R]\f[I]ylen\f[R]\f[B], int \f[R]\f[I]xlen\f[R]\f[B], unsigned \f[R]\f[I]ctlword\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_rounded_box(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], uint64_t \f[R]\f[I]ul\f[R]\f[B], uint64_t \f[R]\f[I]ur\f[R]\f[B], uint64_t \f[R]\f[I]ll\f[R]\f[B], uint64_t \f[R]\f[I]lr\f[R]\f[B], int \f[R]\f[I]ylen\f[R]\f[B], int \f[R]\f[I]xlen\f[R]\f[B], unsigned \f[R]\f[I]ctlword\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_double_box(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], uint64_t \f[R]\f[I]ul\f[R]\f[B], uint64_t \f[R]\f[I]ur\f[R]\f[B], uint64_t \f[R]\f[I]ll\f[R]\f[B], uint64_t \f[R]\f[I]lr\f[R]\f[B], int \f[R]\f[I]ylen\f[R]\f[B], int \f[R]\f[I]xlen\f[R]\f[B], unsigned \f[R]\f[I]ctlword\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_render_image(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]filename\f[R]\f[B], ncblitter_e \f[R]\f[I]blitter\f[R]\f[B], ncscale_e \f[R]\f[I]scale\f[R]\f[B]);\f[R] .SH DESCRIPTION .PP \f[B]ncdirect_init\f[R] prepares the \f[B]FILE\f[R] provided as \f[B]fp\f[R] for colorizing and styling. On success, a pointer to a valid \f[B]struct ncdirect\f[R] is returned. \f[B]NULL\f[R] is returned on failure. Before the process exits, \f[B]ncdirect_stop\f[R] should be called to reset the terminal and free up resources. \f[B]ncdirect_init\f[R] places the terminal into \[lq]cbreak\[rq] (also known as \[lq]rare\[rq]) mode, disabling line-buffering and echo of input. \f[B]ncdirect_stop\f[R] restores the terminal state as it was when the corresponding \f[B]ncdirect_init\f[R] call was made. .PP The following flags are defined: .IP \[bu] 2 \f[B]NCDIRECT_OPTION_INHIBIT_SETLOCALE\f[R]: Unless this flag is set, \f[B]ncdirect_init\f[R] will call \f[B]setlocale(LC_ALL, NULL)\f[R]. If the result is either \[lq]\f[B]C\f[R]\[rq] or \[lq]\f[B]POSIX\f[R]\[rq], it will print a diagnostic to \f[B]stderr\f[R], and then call \f[B]setlocale(LC_ALL, \[dq]\[dq]).\f[R] This will attempt to set the locale based off the \f[B]LANG\f[R] environment variable. Your program should call \f[B]setlocale(3)\f[R] itself, usually as one of the first lines. .IP \[bu] 2 \f[B]NCDIRECT_OPTION_INHIBIT_CBREAK\f[R]: Unless this flag is set, \f[B]ncdirect_init\f[R] will place the terminal into cbreak mode (i.e.\ disabling echo and line buffering; see \f[B]tcgetattr(3)\f[R]). .PP An appropriate \f[B]terminfo(5)\f[R] entry must exist for the terminal. This entry is usually selected using the value of the \f[B]TERM\f[R] environment variable (see \f[B]getenv(3)\f[R]), but a non-\f[B]NULL\f[R] value for \f[B]termtype\f[R] 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 \f[B]rgb\f[R] capability (e.g.\ xterm\[cq]s \f[B]xterm-direct\f[R]). .PP \f[B]ncdirect_dim_x\f[R] returns the current number of columns, and \f[B]ncdirect_dim_y\f[R] the current number of rows. .PP \f[B]ncdirect_clear\f[R] clears the screen using a control code if one exists in terminfo. Otherwise, it prints successive newlines to scroll everything off. .PP \f[B]ncdirect_cursor_move_yx\f[R] moves the cursor to the specified coordinate. -1 can be specified for either \f[B]y\f[R] or \f[B]x\f[R] to leave that axis unchanged. .PP \f[B]ncdirect_enable_cursor\f[R] and \f[B]ncdirect_disable_cursor\f[R] always flush the output stream, taking effect immediately. .PP \f[B]ncdirect_cursor_up\f[R] 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. .SH RETURN VALUES .PP \f[B]ncdirect_init\f[R] returns \f[B]NULL\f[R] on failure. Otherwise, the return value points to a valid \f[B]struct ncdirect\f[R], which can be used until it is provided to \f[B]ncdirect_stop\f[R]. .PP \f[B]ncdirect_putstr\f[R] and \f[B]ncdirect_printf_aligned\f[R] return the number of bytes written on success. On failure, they return some negative number. .PP All other functions return 0 on success, and non-zero on error. .SH SEE ALSO .PP \f[B]getenv(3)\f[R], \f[B]termios(3)\f[R], \f[B]notcurses(3)\f[R], \f[B]notcurses_plane(3)\f[R], \f[B]terminfo(5)\f[R] .SH AUTHORS nick black .