4.1.1 Using the Guile Curses module

To use ncurses library functions, you have to load the (ncurses curses) module into the program.

Here is the Hello World program.

#!/usr/bin/guile
!#
(use-modules (ncurses curses))

(define stdscr (initscr))
(addstr stdscr "Hello World!!!")
(refresh stdscr)
(getch stdscr)
(endwin)

The first line of the example, #!/usr/bin/guile, gives the location of where Guile is installed on my system. This may differ on your system.

The above program prints “Hello World!!!” to the screen, waits for the user to press any key, and then exits. This program shows how to initialize curses and do screen manipulation and end curses mode. Let’s dissect it line by line.

4.1.1.1 About initscr

The procedure initscr initializes the terminal in curses mode. It clears the screen and presents a blank screen. To do any screen manipulation using the curses package, this has to be called first. This function initializes the curses system and allocates memory for screen handling and some other data structures. It returns a SMOB that represents the default window: the window that represents the entire screen. By convention, this window is denoted stdscr, the standard screen. Under extreme cases, this function might fail due to insufficient memory to allocate memory for curses library’s data structures.

The procedure initscr returns a #<window> that contains necessary information about the curses screen. The #<window> that is returned must be stored until the program is finished with the curses library. If that #<window> is garbage collected, the curses library cannot continue.

After this is done, we can do a variety of initializations to customize our curses settings

4.1.1.2 The mysterious refresh

The next line addstr prints the string “Hello World!!!” on to the screen. This function prints the data on a window called stdscr at the current (y, x) coordinates. Since our present coordinates are at 0,0 the string is printed at the top, left-hand corner of the window.

This brings us to the mysterious (refresh stdscr). Well, when we called addstr, the data is actually written to an imaginary window, which is not updated on the screen yet. The job of addstr is to update a few flags and data structures and write the data to a buffer corresponding to stdscr. In order to show it on the screen, we need to call refresh and tell the curses system to dump the contents on the screen.

The philosophy behind all this is to allow the programmer to do multiple updates on the imaginary screen or windows and to do a refresh once all the screen update is done. refresh checks the window and updates only the portion which has been changed. This improves performance and offers greater flexibility, too. But, it is sometimes frustrating to beginners. A common mistake committed by beginners is to forget to call refresh after they did some update through addstr.

4.1.1.3 About endwin

And finally, don’t forget to end the curses mode. Otherwise your terminal might behave strangely after the program quits. endwin frees the memory taken by the curses sub-system and its data structures and puts the terminal in normal mode. This function must be called after you are done with curses mode.