Ncurses Module
Linux Menu Config - Ncurses example

Ncurses is a library that provides an API for advanced terminal-based, text interface designs.

Ncurses not only gives you additional options and controls not typically available in a console application, but also aims to be optimized around screen rendering time; something that can be quite slow when you render lots of small data chunks to the standard terminal.

This module provides bindings to various Ncurses functionality. See GNU.org's ncurses page for more details on what Ncurses provides.

 #Global Variables

Colors

The following color constants are available for use the Ncurses windows through functions like ncurses.setPair(), ncurses.setBackground(), or ncurses.setAttribute().

ncurses.BLACK ncurses.RED ncurses.GREEN ncurses.YELLOW
ncurses.BLUE ncurses.MAGENTA ncurses.CYAN ncurses.WHITE

In order to actually print colored text, you will need to first create a color pair, then use setAttribute() or setBackground() using the pair. Like this:

Example:
ncurses.setPair(1, ncurses.RED, ncurses.BLACK) -- Set the pair at index 1 -- Now set STDSCR window to use color pair at index 1, and make it bold ncurses.setAttribute(STDSCR, ncurses.getPair(1) | ncurses.BOLD) ncurses.print(STDSCR, "This should be red on black")

Style attributes

These constants may also be used in pairs, backgrounds, or attribute masks. Be warned, many of them do not work in a Windows console.

For an example of what each attribute looks like, refer to this image.

ncurses.NORMAL ncurses.STANDOUT ncurses.UNDERLINE ncurses.REVERSE
ncurses.BLINK ncurses.DIM ncurses.BOLD ncurses.PROTECT
ncurses.INVIS ncurses.ALTCHARSET ncurses.CHARTEXT

Default window

The default Ncurses window can be identified by STDSCR. Unless you want to output to a specified window, STDSCR is where you'll put it.

 #ncurses.init ncurses.init()

As you can probably imagine, this initializes the Ncurses module. By default, Ncurses is not enabled. By calling this function, you will create the default Ncurses window (STDSCR) and enable the use of other Ncurses functions. That means, once this function is called, the "normal" output (STDOUT) will disappear and you'll be stuck with a black window. Any data output with print(), printf(), or io.write() will not appear on the Ncurses window, so make sure to only use Ncurses functions to output while in this mode.

 #ncurses.cleanup ncurses.cleanup()

When you are in Ncurses mode, calling this function will destroy the Ncurses environment and return you to standard output.

 #ncurses.print ncurses.print(window win, string str)

Prints data to an Ncurses window. The output begins at the virtual cursor's position (use ncurses.move() to reposition the cursor) in the specified Ncurses window. As with most Ncurses functions, you should pass STDSCR as the first parameter if you want to put data on the default window.

Take note that this function will not display the information immediately. The screen is only redrawn (and becomes visible) after you call ncurses.refresh().

Example:
-- Print "Hello World" to STDSCR, then redraw the window so we can see it ncurses.print(STDSCR, "Hello World"); ncurses.refresh(STDSCR);
 #ncurses.refresh ncurses.refresh(window win)

Redraw the given window to commit any changes. Call this after a single call or batch of calls to any output function to update the screen.

 #ncurses.scrollok ncurses.scrollok(window win, boolean scrolling)

Sets (or unsets) scrolling on the given window. By default, scrolling is disabled on Ncurses windows. If you want text to scroll off the top as you continue to dump more text into it, set 'scrolling' to true.

 #ncurses.clear ncurses.clear(window win)

Erase the contents of window 'win'.

 #ncurses.move ncurses.move(window win, number y, number x)

Moves the position of the virtual cursor to y,x in the given window. Notice that the orientation is Y (row) before X (column) and not the other way around. The virtual cursor position is where output will be placed in the given Ncurses window.

Should the position you request be unavailable (probably because it extends beyond the constraints of the window), this function will fail and do nothing.

 #ncurses.createWindow window ncurses.createWindow(number sy, number sx, number width, number height)

Creates a new Ncurses window and returns it. 'sy' and 'sx' indicate the top-left corner of the window (in characters). 'width' and 'height' represent the window's width/height in characters.

If this function fails for any reason, it will return nil.

Note that the position (sy,sx) is in Y,X order.

 #ncurses.getWindowSize number y, number x ncurses.getWindowSize( window win)

Returns the size of a window.

Note that this is in Y,X order.

 #ncurses.resizeWindow boolean ncurses.resizeWindow(window win, number lines, number columns)

Resize a Ncurses window to the given columns and lines. Returns true on success, false on failure.

 #ncurses.moveWindow boolean ncurses.moveWindow(window win, number y, number x)

Move a Ncurses window to the given position. Returns true on success, false on failure.

Note that the position is in Y,X order.

 #ncurses.getString string ncurses.moveWindow(window win)

Prompt the user for some input on a Ncurses window. Returns that input as a string value. While waiting for user input, the rest of the program is blocked from continuing.

#ncurses.getPair number ncurses.getPair(number pairIndex)

Returns the attribute mask of a given color pair. You may call ncurses.setPair() on the pair to modify the value.

The 'pairIndex' must be in the range of 0 to 63; 0 is the default pair.

 #ncurses.setPair ncurses.setPair(number pairIndex, number foregroundColor, number backgroundColor)

Modifies the color (foreground/background) pair at a given index.

The 'pairIndex' must be in the range of 1 to 63; 0 is reserved for the default pair.

 #ncurses.attributeOn ncurses.attributeOn(window win, number attrib)

Turns an attribute (identified by 'attrib') on for the given window.

 #ncurses.attributeOff ncurses.attributeOn(window win, number attrib)

Turns an attribute (identified by 'attrib') off for the given window.

 #ncurses.setAttribute ncurses.setAttribute(window win, number attrib)

Sets an attribute mask (identified by 'attrib') on the given window. The attribute mask can represent a handful of attributes at once. You should use Bitwise Operator OR (|) to combine them.

Example:
-- Set attribute to bold & underline ncurses.setAttribute(STDSCR, ncurses.STANDOUT | ncurses.UNDERLINE);
 #ncurses.getAttribute number attributes, number pair ncurses.setAttribute( window win, number attrib)

Returns the attribute mask and color pair for a Ncurses window. If this function fails, it will return nil.

#ncurses.setBackground ncurses.setBackground( window win, number attrib)

Sets the background on the given window to the attribute mask.

 #A working example Example:
require 'timestamp' local speed = 10 local redrawFrequencyInSeconds = 0.25 local randomTimeBetweenLogs = 3 local logWindowHeight = 5 local dir local x, y local lastRedraw local positionWindow local logWindow local nextLogMsg function macro.init() ncurses.init() dir = math.random(100) / math.pi * 2 x, y = 0, 0 lastRedraw = time.getNow() nextLogMsg = Timestamp:now():addSeconds(math.random(randomTimeBetweenLogs)) ncurses.setPair(1, ncurses.RED, ncurses.GREEN) ncurses.move(STDSCR, 0, 0) ncurses.print(STDSCR, "Ncurses Example - CTRL+C to quit") ncurses.refresh(STDSCR) positionWindow = ncurses.createWindow(2, 0, 1, 32) -- one line window ncurses.setPair(1, ncurses.RED, ncurses.WHITE) ncurses.setAttribute(positionWindow, ncurses.getPair(1)) -- A window to hold log messages; older messages will scroll off the window and disappear logWindow = ncurses.createWindow(5, 0, logWindowHeight + 1, 60) -- add 1 for newline ncurses.scrollok(logWindow, true) ncurses.setPair(2, ncurses.BLACK, ncurses.WHITE) ncurses.setBackground(logWindow, ncurses.getPair(2)) ncurses.clear(logWindow) ncurses.refresh(logWindow) addLogLine("Example started!") redraw() end local firstLogged = false function addLogLine(str) if( firstLogged ) then ncurses.print(logWindow, "\n") else firstLogged = true end ncurses.print(logWindow, sprintf("[%s] %s", Timestamp:now(), str)) ncurses.refresh(logWindow) end function updatePosition(dt) x = x + math.cos(dir) * speed * dt y = y + math.sin(dir) * speed * dt if math.abs(x) > 1000 then x = 0 end if math.abs(y) > 1000 then y = 0 end end function redrawPosition() ncurses.clear(positionWindow) ncurses.move(positionWindow, 2, 1) ncurses.print(positionWindow, sprintf("Pos: (%g, %g)", x, y)) ncurses.refresh(positionWindow) end function redraw() redrawPosition() end function macro.main(deltaTime) updatePosition(deltaTime) if time.diff(time.getNow(), lastRedraw) > redrawFrequencyInSeconds then -- lastRedraw:addSeconds(1):isPast() then redraw() lastRedraw = time.getNow() end if nextLogMsg:isPast() then nextLogMsg = Timestamp:now():addSeconds(math.random(randomTimeBetweenLogs)) addLogLine("Something happened!") end return true end

Page last updated at 2024-04-20 14:58:15

Copyright 2024