Screen management programs are a common component of many commercial computer applications. These programs handle input and output at a video display terminal. A screen program might move a cursor, print a display, or divide a terminal screen into windows. Many screen management programs build end-user terminal interfaces to help users enter and retrieve information from a database - interfaces such as forms, menus, and help and error message displays.
This document explains how to use the Extended Terminal Interface (ETI) package to write screen management programs on a UNIX system. (It also tells you what you need to know about the terminfo database to use ETI.) To start you writing screen management programs as soon as possible, the document does not attempt to cover every routine in the libraries. Although it covers all routines in the high-level libraries (those that build panels, menus, and forms), it covers only the most frequently used routines in the low-level library (curses). For more information, this document points you to the curses(3X), terminfo(4), and other manual pages. Keep these documents close at hand; you'll find them invaluable when you want to know more about these and other routines.
Because the routines are compiled C functions, you should be familiar with the C programming language before using ETI. You should also be familiar with the UNIX system/C language standard I/O package (see "System Calls" and "Standard I/O" in Chapter 2 of the Programmer's Guide: ANSI C and Programming Support Tools and the stdio(3S) manual page ). With that knowledge and an appreciation for the philosophy of building on the work of others, you can design screen management programs for many purposes.
This guide contains eight chapters:
Introduction to ETI
This chapter briefly describes the ETI libraries and how ETI works with the terminfo database.
Basic ETI Programming
This chapter describes the routines and other components that every ETI program needs to work properly, tells you how to compile and run low-level ETI (curses) programs, and introduces important concepts such as "refreshing."
Simple Input and Output
This chapter describes the routines in the low-level ETI (curses) library for writing to, and reading from, a screen. It also covers the suite of video attributes and options which enable you to enhance your displays with striking visual effects.
Windows
This chapter explains the use of windows and subwindows. It delves more deeply into the refresh operation and covers the functions wnoutrefresh() and doupdate().
Panels
This chapter begins the treatment of the high-level ETI functions. It describes the use of panels-windows with interrelationships of depth-and covers the set of panel functions, which enable you to create panels, move them, associate them with different windows, place them on top of other panels, and so forth.
Menus
This chapter explains the suite of menu functions. It explains how to create menu items and menus, display them, change menu video attributes, have users interact with menus, and more.
Forms
This chapter covers the wealth of form functions. It shows how to create fields and forms, display them, change form video attributes, have users interact with forms, and more.
Other ETI Routines
This chapter covers routines for screen management programs that draw line graphics, use a terminal's soft labels, and work with more than one terminal at the same time.
This document uses the following conventions to discuss ETI routines:
In program text, the major ETI data types appear in uppercase. They are
WINDOW |
a rectangular area of the screen treated as a unit |
PANEL |
a window with relations of depth to other windows so that regions hidden behind other windows are invisible |
ITEM |
a character string consisting of a name and an optional description |
MENU |
a screen display that presents a set of items from which the user chooses one or more, depending on the type of menu |
FIELD |
an m x n block of form character positions that ETI functions can manipulate as a unit |
FORM |
a collection of one or more pages of fields |
FIELDTYPE |
a field attribute that determines what kind of data may occupy the field |
Every ETI function is introduced with a SYNOPSIS. The first line of the SYNOPSIS proper describes the routine, while the following lines describe its arguments. On each line, the type of the return value or arguments precedes their names. As an example, consider
SYNOPSIS int set_menu_win (menu, window) MENU * menu; WINDOW * window;
This says that the function set_menu_win() returns a value of type int and that it takes two arguments, menu and window. The argument menu is of type MENU * (pointer to a menu), while the argument window is of type WINDOW * (pointer to a window).
The terms window, panel, menu, and form are often shorthand for the phrases window pointer, panel pointer, menu pointer, and form pointer, respectively. All ETI routines pass or return pointers to these objects, not the objects themselves.
ETI is a set of C library routines that promote the development of application programs that display and manipulate windows, panels, menus, and forms and run under the UNIX system. The rest of this chapter explains the nature of these libraries and the connection between ETI and the terminfo library and database.
ETI consists of
The routines are C functions and macros; many of them resemble routines in the standard C library. For example, there's a routine printw() that behaves much like printf(3S) and another routine getch() that behaves like getc(3S). The automatic teller program at your bank might use printw() to print its menus and getch to accept your requests for withdrawals (or, better yet, deposits). A visual screen editor like the UNIX system screen editor vi(1) might also use these and other ETI routines.
A major feature of ETI is cursor optimization. Cursor optimization minimizes the amount a cursor has to move around a screen to update it. For example, if you designed a screen editor program with ETI routines and edited the sentence
ETI is a great package for creating forms and menus.
to read
ETI is the best package for creating forms and menus.
the program would change only the best in place of a great. The other characters would be preserved. Because the amount of data transmitted-the output-is minimized, cursor optimization is also referred to as output optimization.
Cursor optimization takes care of updating the screen in a manner appropriate for the terminal on which an ETI program is run. This means that ETI can do whatever is required to update many different terminal types. It searches the terminfo database (described below) to find the correct description for a terminal.
How does cursor optimization help you and those who use your programs? First, it saves you time in describing in a program how you want to update screens. Second, it saves a user's time when the screen is updated. Third, it reduces the load on your UNIX system's communication lines when the updating takes place. Fourth, you don't have to worry about the myriad of terminals on which your program might be run.
Here's a simple ETI program. It uses some of the basic ETI routines to move a cursor to the middle of a terminal screen and print the character string BullsEye. Each of these routines is described later in this chapter. For now, just look at their names and you will get an idea of what each of them does:
A Simple ETI Program
#include <curses.h> main() { initscr(); move( LINES/2 - 1, COLS/2 - 4 ); addstr("Bulls"); refresh(); addstr("Eye"); refresh(); endwin(); } <a name="The ETI/terminfo Connection"></a>
terminfo is both a set of routines that make use of the capabilities of a wide range of terminals and a database that contains descriptions of the terminals that can be used with ETI. Its use as a database is our concern here. See Chapter 13 of this guide for details on its use as a set of routines.
A screen management program with ETI routines refers to the terminfo database at run time to obtain the information it needs about the terminal being used-what we'll call the current terminal from here on.
Suppose, for instance, that you are using an AT&T Teletype 5425 terminal to run the simple ETI program. To execute properly, the program needs to know how many lines and columns the terminal screen has to print the BullsEye in the middle of it. The description of the AT&T Teletype 5425 in the terminfo database has this information, as well as other information about the terminal's capabilities and how it performs various operations - for example, how its control characters are interpreted. All ETI needs to know before it goes looking for the information is the name of your terminal.
You tell the program the name by putting it in the environment variable $TERM when you log in or by setting and exporting $TERM in your .profile file (see profile(4)). Knowing $TERM, an ETI program run on the current terminal can search the terminfo database to find the correct terminal description.
For example, assume that the following lines are in a .profile:
TERM=5425 export TERM tput init
The first line names the terminal type, and the second line exports it. (See profile(4).) The third line of the example tells the UNIX system to initialize the current terminal. That is, it makes sure that the terminal is set up according to its description in the terminfo database. (The order of these lines is important.$TERM must be defined and exported first, so that when tput(1) is called the proper initialization for the current terminal takes place.) If you had these lines in your .profile and you ran an ETI program, the program would get the information that it needs about your terminal from the file /usr/share/lib/terminfo/5/5425 in the database, which provides a match for $TERM. For more information about the terminfo database, see Chapter 13 in this guide.
You have been given a brief look at the main components of screen management. This section will complete the overview by making you familiar with the other components of this system.
Components of the Screen Management System
The terminfo database has already been described as one of the main components of the screen management system. The rules for creating a terminal description source file are in the manual page terminfo(4). The source file is then compiled using tic. Unless you have created a shell environment variable called TERMINFO that indicates a different path, tic will place the compiled description file into the proper directory under /usr/share/lib/terminfo (provided that you have permission to create or overwrite files in that directory). To use tic simply type:
tic filename
You may use the -v option to get a running commentary. An integer from 1 to 10 may follow the option (no space) to set the level of verbosity. The default is 1.
The system uses the shell environment variable TERMINFO to find the terminal description files. Initializing a terminal will cause TERMINFO to be set to null and then be converted to /usr/share/lib/terminfo unless you have already set it to some other path ($HOME/bin, for example). The system will look for the definition of a specific terminal under $TERMINFO/?/*, where ? is the first letter of the terminal name, and * is the terminal name.
Once a terminal description file has been compiled, it is no longer human readable. The routine infocmp translates a compiled description file back to source statements. Invoking the command without arguments will print out the description of the terminal defined by the shell environment variable TERM. A single argument is taken as the name of a terminal you want to see the source description for. With no options declared (or -I), you will see descriptions as defined in terminfo(4). There are options for seeing the C variable names (-L), the old termcap names (-C), and all output in termcap format (-r).
If two arguments are given, infocmp assumes they identify two descriptions you want to compare. If no options are given (or -d), the differences are printed. You may also ask for a list of capabilities that the two have in common (-c) or a list of capabilities that neither describes (-n). In all of the above cases, the output lists the Boolean fields first, the numeric fields second, and the strings third.
infocmp also has options to print, trace, sort, compare files in two different directories, and output a source file derived from the union of two or more compiled description files. For more information consult the infocmp manual page.
Early versions of the UNIX system used a different method of describing terminals, called termcap. You can convert a termcap file to a terminfo file by using captoinfo. If the command is invoked with no arguments,the shell environment variable TERMCAP is used to get the path and the shell environment variable TERM to get the terminal. If TERMCAP is null, the routine tries to convert /usr/share/lib/termcap. If a file name is given as an option, that is the file that will be converted. The output is to standard out, and may be piped. Options include a trace mode (-v), one field to a line output (-l), and changing the output width (-w).
One of the definitions given earlier for terminfo was that it is a group of routines within curses that allow you to manipulate the data in a terminal description file. This small library of routines is documented in this guide and in the curses(3X) manual pages. The command tput(1)will allow you to perform many of these manipulations from the command line or in a shell script.
tput can always be given the-Tterminaltype option, but doesn't need it if the shell environment variable TERM is set. It can be given init, reset, or longname as special arguments. These initialize, reset, and print out the name of the terminal, respectively. Finally, you can use the name of a terminfo(4) terminal attribute or capability (called acapname) as an argument. These capabilities can fall into three categories; Boolean, numeric, and strings. If the capname you specify is a string, you may include, as an argument, a list of parameters to insert into coded places in the string (instantiation).
This completes the overview of the screen management system. More detailed information starts in the next chapter. If you elect to skip this and go directly to the manual pages, remember that the examples at the end of the guide might still prove useful.