curses_utils

libncurses

ncurses represents the terminal screen using two data structures:

• a physical screen -- what is "actually" on the screen
• a virtual screen -- what is intended to be on the screen

a window is a two-dimensional array of characters representing all or part of the terminal screen

characters in a window are of type chtype containing character and attribute data; on a 64-bit system, a chtype will be a 64-bit unsigned integer

there is also a type alias for chtype, attr_t

in ncurses there is a default window called stdscr that is the size of the terminal screen

Defines

#define NCURSES_ATTR_SHIFT 8 -- bitshift to start of attribute bits

#define NCURSES_BITS (mask, shift) ... -- takes a chtype mask and left-shifts it by NCURSES_ATTR_SHIFT + shift

#define COLOR_PAIR (n) ... -- takes a color pair number and shifts it into a chtype using NCURSES_BITS (n, 0), and masks the result with A_COLOR to clear out any bits outside of the color byte

#define PAIR_NUMBER (attr) ... -- inverse of COLOR_PAIR, masking the color byte of a chtype with A_COLOR and shifting it into a color pair number

Functions

initscr() -- initializes the curses system, allocates the stdscr, and refreshes the screen; this is equivalent to:

newterm(getenv("TERM"), stdout, stdin);
return stdscr;

and must be called before any other screen manipulation functions

wnoutrefresh(WINDOW*) copies named window to the virtual screen

doupdate() compares virtual screen to physical screen and does the "actual update"

wrefresh(WINDOW*) equivalent to calling wnoutrefresh followed by doupdate (wnoutrefresh), then compares the virtual screen to the physical screen and does the update (doupdate)

refresh() equivalent to wrefresh(stdscr)

border()

box() calls border() with given top/bottom and left/right edges and corners

Global variables

int COLORS -- number of colors supported by terminal; this is 256 on a 256-color terminal

int COLOR_PAIRS -- number of color pairs supported by terminal; this is 256 on a 256-color terminal

int COLS

int LINES

WINDOW* stdscr

ncurses

Rust bindings to libncurses

most of the C interface should be exposed in this crate

note that as the libncurses interface uses a number of #defines, they are recreated in this crate as const functions

lib.rs:

• const fn NCURSES_BITS (mask:u32, shift:u32) -> u32
• const fn A_NORMAL() -> attr_t
• const fn A_ATTRIBUTES() -> attr_t
• ...

COLOR_PAIR(n) is recreated as a function, but it is not a const function:

• fn COLOR_PAIR (n : i16) -> attr_t

note that PAIR_NUMBER is a safe wrapper over an ll raw function

in ll.rs, a number of typedefs are made and extern "C" functions are declared that will link to libncurses; these are called in the wrapper functions defined elsewhere in the crate

in constants.rs some more constants are defined (the contents of this module are re-exported at the crate root):

• const ERR : i32 = -1
• const OK : i32 = 0
• const NCURSES_ATTR_SHIFT : u32 = 8
• const COLOR_BLACK : i16 = 0
• const COLOR_RED : i16 = 1
• ...

some extern "C" global variables are also wrapped in constants.rs:

• static stdscr : WINDOW

• static COLORS : c_int

• static COLOR_PAIRS : c_int

• static LINES : c_int

• static COLS : c_int

• ...

pancurses

pancurses provides a cross-platform curses library using ncurses for Linux and pdcurses on Windows; most of the method names are the same, and on Linux, it seems to mostly call raw ncurses::ll functions instead of the "safe" ncurses wrapped functions

pancurses re-defines a number of constants from ncurses, such at OK, ERR, COLOR_BLACK, A_ATTRIBUTES, etc., and some const funtions like NCURSES_BITS(mask,shift) (private) and COLOR_PAIR(n) (public)

Traits

trait ToChtype -- trait with a single to_chtype (&self) -> chtype method; this is only implemented for char as a primitive cast (as chtype), and for chtype itself

Structs

Window -- contains a pointer to the backend WINDOW pointer, and a couple flags to indicate if it is the stdscr or a deleted window; methods:

• window.noutrefresh() -- copies touched lines to the virtual screen; equivalent to ncurses::wnoutrefresh (window)
• window.refresh() -- copies window to the physical screen; must be called to get output to terminal; equivalent to ncurses::wrefresh(window)
• window.touch() -- sets entire window as touched
• window.untouch() -- unset the entire window as touched
• ...

Attributes { chtype, ColorPair } -- an attributes builder; can be converted Into<chtype>

ColorPair (u8)

Enums

Attribute

Input

Functions

note that ncurses::refresh() is not exported; instead call refresh() on the initial Window representing the stdscr

initscr() -> Window -- initialize the curses system and return the stdscr window

doupdate() -- compare virtual screen to physical screen and perform update of the physical screen; this should be called once per frame; if there is only one window in use, instead calling the refresh() method on that window will automatically call doupdate() after first calling noutrefresh() on that window

curs_set(i32) -- set cursor visibility (0 invisible, 1 visible, 2 very visible)

endwin()

easycurses

re-exports pancurses::Input as easycurses::Input

Structs

struct EasyCurses {
    pub win       : pancurses::Window
    auto_resize   : bool = true
    color_support : bool
}

-- ; methods:

• set_color_pair (&mut self, ColorPair) -- calls pancurses::Window::color_set with the color pair number contained in the color pair; with the ncurses backend, this will set the color in the attribute returned by pancurses::Window.attrget(), but not with PDCurses, i.e. the second byte is always 0x0-- however in both backends, the color pair number will be returned in the right member of the tuple returned by pancurses::Window.attrget(), so the preferred way to clear the screen with the current window color would be to construct the attribute with color_pair(color) supplied in the argument to bkgd or bkgdset

struct ColorPair (i16) -- uses an internal function fgbg_pairid to combine a pair of foreground and background color numbers into a color pair number, using the formula:

1 + (8 * fg + bg)

during intialization, each fg/bg combination of the 8 base colors are initialized for a total of 8 * 8 = 64 colors, using the above formula gives color pairs numbered from 1 to 64; it should be noted that this will not work on a terminal that supports only 64 colors, since color 0 is technically reserved for white/black, the maximum allowed color pair would be 63

Enums

Color -- an enumeration convertible to i16 color numbers (i.e. COLOR_BLACK, COLOR_RED, etc.)

Functions

initialize_system() -> EasyCurses -- initializes the curses system through pancurses::initscr() and subsequently sets up the colors

Curses

Newtype wrapping an EasyCurses window.

The new() creation method will construct an EasyCurses window with the following settings:

• Hidden cursor
• No input echo
• No line buffering (immediate input mode)

There are a number of methods to get input which will set the input mode as needed, depending on the type of input:

• getch_wait() -> Option<pancurses::Input> -- get single character, block indefinitely
• getch_timeout(timeout) -> Option<pancurses::Input> -- get single character, block until timeout
• getch_nowait() -> Option<pancurses::Input> -- get single character, returns immediately if no input is waiting
• getline_wait() -> Option<pancurses::Input> -- get line, block indefinitely
• getline_nowait() -> Option<pancurses::Input> -- get line, returns immediately if no input is waiting

The newly created window (the stdscr) will have attributes A_NORMAL = 0, and background chtype of (A_NORMAL | ' ' as chtype).

Utility functions

curses_utils defines a few utility functions for working with curses chtypes (attributes + character data):

• color_pair_number (fg, bg) -> i16 -- gives the color pair number that easycurses uses to identify the fg/bg combination

• character (chtype) -> char -- returns the first byte of the chtype (the character data), cast to a char

• color_pair (chtype) -> i16 -- returns the second byte of the chtype (the color pair number), cast to an i16

Colors

ncurses:

• PAIR_NUMBER (attr : i32) -> i32 -- inverse of COLOR_PAIR: masks out the color byte and right-shifts into a color pair number

Pancurses:

• fn COLOR_PAIR (n : chtype) -> attr_t -- turns a color pair number into an attribute (left-shifts by 8 bits and masks the color byte)
• window.attrget() -> (attrs, color_pair : i16) -- this returns the current window attributes (including the color attribute), along with the color pair number corresponding to the color attribute, equal to PAIR_NUMBER(attrs)
• window.color_set (color_pair : i16) -- change the color attribute to the given color pair number, equal to COLOR_PAIR(color_pair)
• window.chgat (n, attrs, color_pair : i16)
• window.mvchgat (y, x, n, attrs, color_pair : i16)
• ColorPair (u8) -- this type only appears to be used by the Attribute builder type; it is the color number which will be set in the 2nd byte of the attribute chtype
• attributes.color_pair() -> ColorPair -- get color pair of an attribute builder
• attributes.set_color_pair(color_pair : ColorPair) -- set color pair of an attribute builder

Easycurses:

• Color -- an enumeration of base colors that can be converted to i16 color numbers
• ColorPair (i16) -- easycurses defines a color pair number by the formula 1 + 8*fg + bg, giving a range of color pair numbers from 1-64
• easycurses.set_color_pair (color_pair : ColorPair)

the easycurses::ColorPair type is only used as the argument to the set_color_pair method; as a convenience, curses_utils defines a function color_pair_number which applies the above formula and returns a raw i16, so that it can be used in other places where a color pair number is needed

Attributes

pancurses::Window::attrset (chtype) -- sets the current window attributes; if there is any character data here it will be "combined" with all inputs

pancurses::Window::bkgdset (chtype) -- sets the current window "background" chtype; inserted text will be "combined" with the attributes set in this variable, and any blank characters (spaces) will show the background character data, if any; note that this function does not immediately change any window contents, to fill the window with the background use erase or bkgd

pancurses::Window::bkgd (chtype) -- sets the current background and immediately applies it to all cells in the window; note that this will copy the background character into blank cells (spaces), but will not clear cells with existing character data

Drawing

pancurses::Window::erase() -- copies blanks to every cell of the window, in combination with the background chtype

pancurses::Window::clearok(bool) -- if true, the next time this window calls window.refresh(), the entire screen will clear and re-draw

pancurses::Window::clear() -- equivalent to window.erase() followed by window.clearok(true)

easycurses::Easycurses::clear() -- just calls pancurses window.clear() internally

pancurses::Window::noutrefresh() -- copies the window to the virtual screen

pancurses::doupdate() -- compares the virtual screen to the physical screen and copies updated portions to the physical screen

pancurses::Window::refresh() -- equivalent to window.noutrefresh() followed by doupdate()

pancurses::Window::addch(chtype) -- "adds" the chtype (attribute + character data) to the window; note that if the cursor is moved past the end of the window (i.e. the cursor was at (ncurses::LINES()-1, ncurses::COLS()-1), then this function will return '-1' (pancurses::ERR), but the character will still be drawn-- this is also true for addstr and printw

pancurses::Window::chgat(n:i32, ch:chtype, color_pair:i16) -- "changes" n consecutive characters to the given chtype and color pair number; this method "combines" the character data with the current character data at the target using a bitwise OR operation; note that only character data and non-color attributes are taken from the chtype argument-- a color number needs to be given in the color pair argument.

pancurses::Window::hline/vline -- note that this will return -1 on windows if called with ncols=0

... TODO: box drawing functions

Inspecting

pancurses::Window::mvinch (row:i32, col:i32) -> chtype -- returns the rendered chtype at the given position, or else returns -1 (0xFFFFFFFF)