NCURSES Programming HOWTO
Prev		Next

1. Introduction

In the olden days of teletype terminals, terminals were away from computers and were connected to them through serial cables. The terminals could be configured by sending a series of bytes to each of them. All the capabilities (such as moving the cursor to a new location, erasing part of the screen, scrolling the screen, changing modes, changing appearance, colors, brightness, blinking, underlining, reverse video etc.) of terminals could be accessed through these series of bytes which are usually called escape sequences because they start with an escape(0x1B) character. Even today, with proper emulation, we can send escape sequences to the emulator and achieve the same effect on the terminal window.

Suppose you wanted to print a line in color. Try typing this on your console.

echo "^[[0;31;40mIn Color"

The first character is an escape character, which looks like two characters ^ and [. To be able to print that you have to press CTRL+V and then the ESC key. All the others are normal printable characters. You should be able to see the string "In Color" in red. It stays that way and to revert back to the original mode type this.

echo "^[[0;37;40m"

Now, what do those magic characters mean? Difficult to comprehend? They might even be different for different terminals. So the designers of UNIX invented a mechanism named termcap. It is a file that lists all the capabilities of a particular terminal, along with the escape sequences needed to achieve a particular effect. In the later years, this was replaced by terminfo. Without delving too much into details, the concept of the mechanism is to allow application programs query the terminfo database and obtain the control characters to be sent to the terminal or terminal emulator.

1.1. What is NCURSES?

You might be wondering, what the import of all this technical gibberish is. In the above scenario, every application program is supposed to query the terminfo and do the necessary stuff(sending control characters etc.). It soon became difficult to manage this complexity and this gave birth to 'CURSES'. Curses is a pun on the name "cursor optimization". The Curses library forms a wrapper over working with raw terminal codes, and provides highly flexible and efficient API (Application Programming Interface). It provides functions to move the cursor, create windows, produce colors, play with mouse etc. The Application programs need not worry about the underlying terminal capabilities.

So what is NCURSES? NCURSES is a clone of the original System V Release 4.0 (SVr4) curses. It is a freely distributable library, fully compatible with older version of curses. In short, it is a library of functions that manages an application's display on character-cell terminals. In the remainder of the document, the terms curses and ncurses are used interchangeably.

The ncurses package was originated by Pavel Curtis. The original maintainer of this package is Zeyd Ben-Halim <zmbenhal@netcom.com>. Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features in versions after 1.8.1. JЭrgen Pfeifer wrote all of the menu and forms code as well as the Ada95 binding. Ongoing work is being done by Thomas Dickey and JЭrgen Pfeifer. Florian La Roche acts as the maintainer for the Free Software Foundation, which holds the copyright on ncurses. Contact the current maintainers at bug-ncurses@gnu.org.

1.2. What we can do with NCURSES

Ncurses not only creates a wrapper over terminal capabilities, but also gives a robust framework to create nice looking UI (User Interface)s in text mode. It provides functions to create windows etc. Its sister libraries panel, menu and form provide an extension to the basic curses library. These libraries usually come along with curses. One can create applications that contain multiple windows, menus, panels and forms. Windows can be managed independently, can provide 'scrollability' and even can be hidden.

Menus provide the user with an easy command selection option. Forms allow the creation of easy-to-use data entry and display windows. Panels extend the capabilities of ncurses to deal with overlapping and stacked windows.

These are just some of the basic things we can do with ncurses. As we move along, We will see all the capabilities of these libraries.

1.3. Where to get it

All right, now that you know what you can do with ncurses, you must be rearing to get started. Ncurses is usually shipped with your installation. In case you don't have the library or want to compile it on your own, read on.

Compiling the package

Ncurses can be obtained from ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz or any of the ftp sites mentioned in http://www.gnu.org/order/ftp.html. The latest stable release is 5.2 20001021.

Read the README and INSTALL files for details on to how to install it. It usually involves the following operations.

    tar zxvf ncurses<version>.tar.gz  # unzip and untar the archive
    cd ncurses<version>               # cd to the directory
    ./configure                             # configure the build according to your 
                                            # environment
    make                                    # make it
    su root                                 # become root
    make install                            # install it

Using the RPM

Ncurses RPM can be found and downloaded from http://rpmfind.net . The RPM can be installed with the following command after becoming root.

    rpm -i <downloaded rpm>

1.4. Purpose/Scope of the document

This document is intended to be a "All in One" guide for programming with ncurses and its sister libraries. We graduate from a simple "Hello World" program to more complex form manipulation. No prior experience in ncurses is assumed.

1.5. About the Programs

All the programs in the document are available in zipped form here. Unzip and untar it. The directory structure looks like this.

ncurses
   |
   |----> JustForFun     -- just for fun programs
   |----> basics         -- basic programs
   |----> demo           -- output files go into this directory after make
   |          |
   |          |----> exe -- exe files of all example programs
   |----> forms          -- programs related to form library
   |----> menus          -- programs related to menus library
   |----> panels         -- programs related to panels library
   |----> Makefile       -- the top level Makefile
   |----> README         -- the top level README file. contains instructions
   |----> COPYING        -- copyright notice

The individual directories contain the following files.

Description of files in each directory
--------------------------------------
JustForFun
    |
    |----> hanoi.c   -- The Towers of Hanoi Solver
    |----> life.c    -- The Game of Life demo
    |----> magic.c   -- An Odd Order Magic Square builder 
    |----> queens.c  -- The famous N-Queens Solver
    |----> shuffle.c -- A fun game, if you have time to kill
    |----> tt.c      -- A very trivial typing tutor

  basics
    |
    |----> acs_vars.c            -- ACS_ variables example
    |----> hello_world.c         -- Simple "Hello World" Program
    |----> init_func_example.c   -- Initialization functions example
    |----> key_code.c            -- Shows the scan code of the key pressed
    |----> mouse_menu.c          -- A menu accessible by mouse
    |----> other_border.c        -- Shows usage of other border functions apa
    |                               -- rt from box()
    |----> printw_example.c      -- A very simple printw() example
    |----> scanw_example.c       -- A very simple getstr() example
    |----> simple_attr.c         -- A program that can print a c file with 
    |                               -- comments in attribute
    |----> simple_color.c        -- A simple example demonstrating colors
    |----> simple_key.c          -- A menu accessible with keyboard UP, DOWN 
    |                               -- arrows
    |----> temp_leave.c          -- Demonstrates temporarily leaving curses mode
    |----> win_border.c          -- Shows Creation of windows and borders
    |----> with_chgat.c          -- chgat() usage example

  forms 
    |
    |----> form_attrib.c     -- Usage of field attributes
    |----> form_options.c    -- Usage of field options
    |----> form_simple.c     -- A simple form example
    |----> form_win.c        -- Demo of windows associated with forms

  menus 
    |
    |----> menu_attrib.c     -- Usage of menu attributes
    |----> menu_item_data.c  -- Usage of item_name() etc.. functions
    |----> menu_multi_column.c    -- Creates multi columnar menus
    |----> menu_scroll.c     -- Demonstrates scrolling capability of menus
    |----> menu_simple.c     -- A simple menu accessed by arrow keys
    |----> menu_toggle.c     -- Creates multi valued menus and explains
    |                           -- REQ_TOGGLE_ITEM
    |----> menu_userptr.c    -- Usage of user pointer
    |----> menu_win.c        -- Demo of windows associated with menus

  panels 
    |
    |----> panel_browse.c    -- Panel browsing through tab. Usage of user 
    |                           -- pointer
    |----> panel_hide.c      -- Hiding and Un hiding of panels
    |----> panel_resize.c    -- Moving and resizing of panels
    |----> panel_simple.c    -- A simple panel example

There is a top level Makefile included in the main directory. It builds all the files and puts the ready-to-use exes in demo/exe directory. You can also do selective make by going into the corresponding directory. Each directory contains a README file explaining the purpose of each c file in the directory.

For every example I have given the path name for the file relative to the ncurses directory.

If you prefer you can browse individual programs at http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/

All the programs are released under GPL and you can use them for any thing you like.

1.6. Other Formats of the document

This howto is also availabe in various other formats on the tldp.org site. Here are the links to other formats of this document.

1.6.1. Readily available formats from tldp.org

1.6.2. Building from source

If above links are broken or if you want to experiment with sgml read on.
Get both the source and the tar,gzipped programs, available at http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/ NCURSES-HOWTO/NCURSES-Programming-HOWTO.sgml http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/ NCURSES-HOWTO/ncurses_programs.tar.gz Unzip ncurses_programs.tar.gz with tar zxvf ncurses_programs.tar.gz Use jade to create various formats. For example if you just want to create the multiple html files, you would use jade -t sgml -i html -d <path to docbook html stylesheet> NCURSES-Programming-HOWTO.sgml to get pdf, first create a single html file of the HOWTO with jade -t sgml -i html -d <path to docbook html stylesheet> -V nochunks NCURSES-Programming-HOWTO.sgml > NCURSES-ONE-BIG-FILE.html then use htmldoc to get pdf file with htmldoc --size universal -t pdf --firstpage p1 -f <output file name.pdf> NCURSES-ONE-BIG-FILE.html for ps, you would use htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps> NCURSES-ONE-BIG-FILE.html

See LDP Author guide for more details. If all else failes, mail me at p_padala@yahoo.com

1.7. Credits

I thank Sharath and Emre Akbas for helping me with few sections. The introduction was initially written by sharath. I rewrote it with few excerpts taken from his initial work. Emre helped in writing printw and scanw sections.

Then comes Ravi Parimi, my dearest friend, who has been on this project before even one line was written. He constantly bombarded me with suggestions and patiently reviewed the whole text. He also checked each program on Linux and Solaris. See his notes to check on your problems.

1.8. Wish List

This is the wish list, in the order of priority. If you have a wish or you want to work on completing the wish, mail me.

Add examples to last parts of forms section. (I am working on it)
Prepare a Demo showing all the programs and allow the user to browse through description of each program. Let the user compile and see the program in action. A dialog based interface is preferred. (My friend N.N.Ashok is working on it)
Add debug info. _tracef, _tracemouse stuff.
Accessing termcap, terminfo using functions provided by ncurses package.
Working on two terminals simultaneously.
Add things in miscellaneous section.

1.9. Copyright

This HOWTO is free documentation; you can redistribute it and/or modify it under the terms of the LDP license. This document is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the LDP license for more details.

Prev	Home	Next
NCURSES Programming HOWTO		The Hello World Program