{"id":7495,"date":"2024-09-11T03:00:00","date_gmt":"2024-09-11T07:00:00","guid":{"rendered":"https:\/\/www.both.org\/?p=7495"},"modified":"2024-09-07T11:58:41","modified_gmt":"2024-09-07T15:58:41","slug":"a-gentle-introduction-to-ncurses","status":"publish","type":"post","link":"https:\/\/www.both.org\/?p=7495","title":{"rendered":"A gentle introduction to ncurses"},"content":{"rendered":"
\r\n
\r\n \r\n <\/i>\r\n <\/a>\r\n <\/span>\r\n<\/div><\/div>\n

In days past, Unix programs ran in \u201cteletype\u201d mode, reading from standard input<\/em> and writing to standard output<\/em> such as the ls<\/strong> and awk<\/strong> commands. In more modern times, Linux programs might run in a graphical user interface like GNOME or KDE, allowing the user to interact with the program using a mouse, by clicking on menus and buttons. But another way that programs can interact with the user is via screen control<\/em>, by manipulating the screen directly. Examples of such text user interfaces include the vi<\/strong> editor, implemented on modern systems as Vim<\/strong>.<\/p>\n\n\n\n

You can create your own programs that use a text user interface to control the screen. The classic way to do this is with the curses<\/strong> library from BSD Unix, but Linux systems provide the same interface using ncurses<\/strong>, or new curses<\/em>. Let\u2019s explore ncurses by writing a simple \u201cHello world\u201d program.<\/p>\n\n\n\n

To follow along, you\u2019ll need to have the ncurses development library installed. On most Linux systems, this is in the ncurses-devel<\/code> package, which you can install like this on Fedora Linux:<\/p>\n\n\n\n

$ sudo dnf install ncurses-devel<\/code><\/pre>\n\n\n\n
Starting up and shutting down<\/h2>\n\n\n\n
To use screen addressing, you first need to use initscr<\/code> to initialize the screen. This does several things at once, but all behind the scenes: ncurses determines if the screen is addressable\u2014and if so, prepares the screen for direct addressing. Finally, ncurses also sets the LINES<\/code> and COLS<\/code> global variables with the current screen dimensions.<\/p>\n\n\n\n
In the process of doing all of this, ncurses may also clear the screen, although your program should still clear the screen on its own to ensure that the terminal is in the right \u201cstate.\u201d<\/p>\n\n\n\n
When your program is finished, you should use the endwin<\/code> function to reset the terminal back to its normal state.<\/p>\n\n\n\n
Let\u2019s test this by writing a simple program to initialize the screen and then immediately exit the program. I\u2019ve also used the getch<\/code> function, which is part of ncurses, to get a single keystroke from the keyboard. That way, the program starts up, waits for a key, then exits. This sample program doesn\u2019t do any other work such as clearing the screen or printing text, but it\u2019s a demonstration of the minimum<\/em> that you need to write a program with ncurses:<\/p>\n\n\n\n
#include <curses.h>\n\nint main()\n{\n    initscr();\n\n    getch();\n\n    endwin();\n    return 0;\n}<\/code><\/pre>\n\n\n\n
You compile the program like any other C program, but you need to include the ncurses<\/code> library at link-time like this:<\/p>\n\n\n\n
$ gcc -o demo demo.c -lncurses<\/code><\/pre>\n\n\n\n
And when you run the program, you\u2019ll just see the cursor in the upper left corner, waiting for you to press a key. As soon as you press any key on the keyboard, the program immediately exits:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Printing text<\/h2>\n\n\n\n
Let\u2019s add to this program by printing a short message. When using ncurses, you can position text anywhere on the screen. The standard way to reposition the cursor is with the move<\/code> function, which takes the line<\/em> and column<\/em> of the new screen position. Screen coordinates always start from zero, so move(0,0)<\/code> would put the cursor in the upper left corner.<\/p>\n\n\n\n
For this demonstration, let\u2019s add some text to start at line 5 and column 10. To do that, we\u2019ll move the cursor with move(5,10)<\/code> and then add a string<\/em> to the screen using the addstr<\/code> function:<\/p>\n\n\n\n
#include <curses.h>\n\nint main()\n{\n    initscr();\n\n    move(5, 10);\n    addstr(\"Hello world!\");\n    refresh();\n\n    getch();\n\n    endwin();\n    return 0;\n}<\/code><\/pre>\n\n\n\n
When updating the screen, such as to print text with addstr<\/code>, you also need to redraw the screen with the refresh<\/code> function. The screen update in ncurses is quite clever, and only updates the on screen characters that have changed; it doesn\u2019t actually \u201crepaint\u201d the entire screen from scratch every time.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Centering a message<\/h2>\n\n\n\n
Let\u2019s make another update to the \u201cHello world\u201d program, to center the message on the screen. In this version, we\u2019ll write a new function called center_text<\/code> that prints the text so it\u2019s on the middle line, and positions the text appropriately so it\u2019s centered on the line.<\/p>\n\n\n\n
#include <curses.h>\n#include <string.h>\n\nvoid center_text(const char *s)\n{\n    int line, col;\n\n    line = LINES \/ 2;\n    col = (COLS \/ 2) - (strlen(s) \/ 2);\n\n    mvaddstr(line, col, s);\n    refresh();\n}\n\nint main()\n{\n    initscr();\n\n    center_text(\"Hello world\");\n\n    getch();\n\n    endwin();\n    return 0;\n}<\/code><\/pre>\n\n\n\n
Because moving to a new coordinate<\/em> and printing text<\/em> is a common thing to do in a program, ncurses provides a function that combines the two actions. The mvaddstr<\/code> function first uses move<\/code> to go to a new screen coordinate, then uses addstr<\/code> to print the text.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
There\u2019s more to explore<\/h2>\n\n\n\n
This program is a simple example of how to use the curses functions to draw characters to the screen. You can do so much more with curses, depending on what you need your program to do. If you are interested in getting a head start with curses, I encourage you to read the ncurses manual page, in section 3 of the man<\/strong> pages:<\/p>\n\n\n\n
$ man 3 ncurses<\/code><\/pre>\n","protected":false},"excerpt":{"rendered":"
You can create your own programs that use a text user interface to control the screen.<\/p>\n","protected":false},"author":33,"featured_media":6830,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_lmt_disableupdate":"","_lmt_disable":"","footnotes":""},"categories":[5,150],"tags":[91,152],"class_list":["post-7495","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-linux","category-programming","tag-linux","tag-programming"],"modified_by":"Jim Hall","_links":{"self":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/7495","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/users\/33"}],"replies":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=7495"}],"version-history":[{"count":1,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/7495\/revisions"}],"predecessor-version":[{"id":7499,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/7495\/revisions\/7499"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/media\/6830"}],"wp:attachment":[{"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=7495"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=7495"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=7495"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}