ex_ncurses

v0.3.1

ex_ncurses v0.3.1 ExNcurses

ExNcurses lets Elixir programs create text-based user interfaces using ncurses.

Aside from keyboard input, ExNcurses looks almost like a straight translation of the C-based ncurses API. ExNcurses sends key events via messages. See listen/0 for this.

Ncurses documentation can be found at:

Link to this section Summary

Types

color()
color_name()
pair()
window()

Functions

addstr(s)
attroff(pair)

Turn off the bit-masked attribute values pass in on the current screen

attron(pair)

Turn on the bit-masked attribute values pass in on the current screen

beep()
border()

Draw a border around the current window

cbreak()
clear()

Clear the screen

cols()

Return the number of visible columns

curs_set(visibility)

Set the cursor mode

delwin(w)

Delete a window w. This cleans up all memory resources associated with it. The application must delete subwindows before deleteing the main window

endwin()

Stop using ncurses and clean the terminal back up

flushinp()
fun(atom)
getch()

Poll for a key press

getstr()

Poll for a string

getx()

Return the cursor’s column

gety()

Return the cursor’s row

has_colors()

Return whether the display supports color

init_pair(pair, f, b)

Initialize a foreground/background color pair

initscr(termname \\ "")

Initialize ncurses on a terminal. This should be called before any of the other functions

keypad()

Enable the terminal’s keypad to capture function keys as single characters

lines()

Return the number of visible lines

listen()

Listen for events

move(y, x)

Move the cursor for the current window to (y, x) relative to the window’s orgin

mvaddstr(y, x, s)
mvcur(oldrow, oldcol, newrow, newcol)

Move the cursor to the new location

mvprintw(y, x, s)
n_begin()
n_end()
newwin(nlines, ncols, begin_y, begin_x)

Create a new window with number of nlines, number columns, starting y position, and starting x position

nocbreak()
noecho()
printw(s)

Print the specified string and advance the cursor. Unlike the ncurses printw, this version doesn’t support format specification. It is really the same as addstr/1

raw()
refresh()

Refresh the display. This needs to be called after any of the print or addstr functions to render their changes

scrollok()

Enable scrolling on stdscr

setscrreg(top, bottom)

Set a scrollable region on the stdscr

start_color()

Enable the use of colors

stop_listening()

Stop listening for events

waddstr(win, str)

Add a string to a window win. This function will advance the cursor position, perform special character processing, and perform wrapping

wborder(w)

Draw a wborder around a specific window

wclear(w)
wmove(win, y, x)

Move the cursor associated with the specified window to (y, x) relative to the window’s orgin

wrefresh(w)

Link to this section Types

Link to this type color() 
color() :: 0..7 | color_name()
Link to this type color_name() 
color_name() ::
  :black | :red | :green | :yellow | :blue | :magenta | :cyan | :white
Link to this type window() 
window() :: reference()

Link to this section Functions

Link to this function addstr(s) 
addstr(String.t()) :: :ok
Link to this function attroff(pair) 
attroff(pair()) :: :ok

Turn off the bit-masked attribute values pass in on the current screen.

Link to this function attron(pair) 
attron(pair()) :: :ok

Turn on the bit-masked attribute values pass in on the current screen.

Link to this function beep() 
beep() :: :ok
Link to this function border() 
border() :: :ok

Draw a border around the current window.

Link to this function cbreak() 
cbreak() :: :ok
Link to this function clear() 
clear() :: :ok

Clear the screen

Link to this function cols() 
cols() :: non_neg_integer()

Return the number of visible columns

Link to this function curs_set(visibility) 
curs_set(0..2) :: :ok

Set the cursor mode

  • 0 = Invisible
  • 1 = Terminal-specific normal mode
  • 2 = Terminal-specific high visibility mode
Link to this function delwin(w) 
delwin(window()) :: :ok

Delete a window w. This cleans up all memory resources associated with it. The application must delete subwindows before deleteing the main window.

Link to this function endwin() 
endwin() :: :ok

Stop using ncurses and clean the terminal back up.

Link to this function flushinp() 
flushinp() :: :ok
Link to this function getch()

Poll for a key press.

See listen/0 for a better way of getting keyboard input.

Link to this function getstr()

Poll for a string.

Link to this function getx() 
getx() :: non_neg_integer()

Return the cursor’s column.

Link to this function gety() 
gety() :: non_neg_integer()

Return the cursor’s row.

Link to this function has_colors() 
has_colors() :: boolean()

Return whether the display supports color

Link to this function init_pair(pair, f, b) 
init_pair(pair(), color(), color()) :: :ok

Initialize a foreground/background color pair

Link to this function initscr(termname \\ "") 
initscr(String.t()) :: :ok

Initialize ncurses on a terminal. This should be called before any of the other functions.

By default, ncurses uses the current terminal. If you’re debugging or want to have IEx available while in ncurses-mode you can also have it use a different window. One way of doing this is to open up another terminal session. At the prompt, run tty. Then pass the path that it returns to this function. Currently input doesn’t work in this mode.

TODO: Return stdscr (a window)

Link to this function keypad() 
keypad() :: :ok

Enable the terminal’s keypad to capture function keys as single characters.

Link to this function lines() 
lines() :: non_neg_integer()

Return the number of visible lines

Link to this function listen()

Listen for events.

Events will be sent as messages of the form:

{ex_ncurses, :key, key}

Link to this function move(y, x) 
move(non_neg_integer(), non_neg_integer()) :: :ok

Move the cursor for the current window to (y, x) relative to the window’s orgin.

Link to this function mvaddstr(y, x, s) 
mvaddstr(non_neg_integer(), non_neg_integer(), String.t()) :: :ok
Link to this function mvcur(oldrow, oldcol, newrow, newcol) 
mvcur(
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer()
) :: :ok

Move the cursor to the new location.

Link to this function mvprintw(y, x, s) 
mvprintw(non_neg_integer(), non_neg_integer(), String.t()) :: :ok
Link to this function newwin(nlines, ncols, begin_y, begin_x) 
newwin(
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer()
) :: window()

Create a new window with number of nlines, number columns, starting y position, and starting x position.

Link to this function nocbreak() 
nocbreak() :: :ok
Link to this function noecho() 
noecho() :: :ok
Link to this function printw(s) 
printw(String.t()) :: :ok

Print the specified string and advance the cursor. Unlike the ncurses printw, this version doesn’t support format specification. It is really the same as addstr/1.

Link to this function raw() 
raw() :: :ok
Link to this function refresh() 
refresh() :: :ok

Refresh the display. This needs to be called after any of the print or addstr functions to render their changes.

Link to this function scrollok() 
scrollok() :: :ok

Enable scrolling on stdscr.

Link to this function setscrreg(top, bottom) 
setscrreg(non_neg_integer(), non_neg_integer()) :: :ok

Set a scrollable region on the stdscr

Link to this function start_color() 
start_color() :: :ok

Enable the use of colors.

Link to this function stop_listening()

Stop listening for events

Link to this function waddstr(win, str) 
waddstr(window(), String.t()) :: :ok

Add a string to a window win. This function will advance the cursor position, perform special character processing, and perform wrapping.

Link to this function wborder(w) 
wborder(window()) :: :ok

Draw a wborder around a specific window.

Link to this function wclear(w) 
wclear(window()) :: :ok
Link to this function wmove(win, y, x) 
wmove(window(), non_neg_integer(), non_neg_integer()) :: :ok

Move the cursor associated with the specified window to (y, x) relative to the window’s orgin.

Link to this function wrefresh(w) 
wrefresh(window()) :: :ok