.\" Automatically generated by Pandoc 2.9.2.1 .\" .TH "notcurses_direct" "3" "v2.2.3" "" "" .hy .SH NAME .PP notcurses_direct - minimal notcurses instances for styling text .SH SYNOPSIS .IP .nf \f[C] #include #define NCDIRECT_OPTION_INHIBIT_SETLOCALE 0x0001ull #define NCDIRECT_OPTION_INHIBIT_CBREAK 0x0002ull #define NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS 0x0008ull \f[R] .fi .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_set_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_set_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_set_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_set_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_set_fg_default(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_set_bg_default(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_set_fg_palindex(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]pidx\f[R]\f[B]);\f[R] .PP \f[B]int ncdirect_set_bg_palindex(struct ncdirect* \f[R]\f[I]nc\f[R]\f[B], int \f[R]\f[I]pidx\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_check_pixel_support(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] .PP \f[B]char* ncdirect_readline(struct ncdirect* \f[R]\f[I]n\f[R]\f[B], const char* \f[R]\f[I]prompt\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 \[dq]cbreak\[dq] (also known as \[dq]rare\[dq]) 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 \[dq]\f[B]C\f[R]\[dq] or \[dq]\f[B]POSIX\f[R]\[dq], 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]). .IP \[bu] 2 \f[B]NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS\f[R]: A signal handler will usually be installed for \f[B]SIGINT\f[R], \f[B]SIGILL\f[R], \f[B]SIGQUIT\f[R], \f[B]SIGSEGV\f[R], \f[B]SIGTERM\f[R], and \f[B]SIGABRT\f[R], cleaning up the terminal on such exceptions. With this flag, the handler will not be installed. .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\[aq]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. .PP \f[B]ncdirect_readline\f[R] uses the Readline library to read a (heap-allocated) line of arbitrary length, supporting line-editing controls. For more information, consult \f[B]readline(3)\f[R]. If you want input echoed to the terminal while using \f[B]ncdirect_readline\f[R], \f[B]NCDIRECT_OPTION_INHIBIT_CBREAK\f[R] must be supplied to \f[B]ncdirect_init\f[R]. .PP \f[B]ncdirect_check_pixel_support\f[R] must be called (and successfully return) before \f[B]NCBLIT_PIXEL\f[R] can be used to render images; see \f[B]notcurses_visual(3)\f[R] for more details. .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 \f[B]ncdirect_check_pixel_support\f[R] returns -1 on error, 0 if there is no pixel support, and 1 if pixel support is successfully detected. .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]readline(3)\f[R] \f[B]notcurses(3)\f[R], \f[B]notcurses_plane(3)\f[R], \f[B]notcurses_visual(3)\f[R], \f[B]terminfo(5)\f[R], \f[B]termios(3)\f[R] .SH AUTHORS nick black .