Basic ETI programming

The header files

The header files menu.h, form.h, and panel.h define several global variables and data structures and defines several ETI routines as macros.

To begin, let us consider the variables and data structures defined. ocurses.h, among other things, defines the integer variables LINES and COLS; when an ETI program is run on a particular terminal, these variables are assigned the vertical and horizontal dimensions of the terminal screen, respectively, by the routine initscr described below.

NOTE: LINES and COLS are external (global) variables that represent the size of a terminal screen. Two similar variables, $LINES and $COLUMNS, may be set in a user's shell environment; an ETI program uses the environment variables to determine the size of a screen. Whenever we refer to the environment variables in this topic we will use the ``$'' to distinguish them from the C declarations in the ocurses.h header file.

For more information about these variables, see ``The routines initscr, refresh, endwin'' and ``More about initscr and lines and columns''.

The integer variables COLORS and COLOR_PAIRS are also defined in ocurses.h. These will be assigned, respectively, the maximum number of colors and color-pairs the terminal can support. These variables are initialized by the start_color routine. (See ``Color manipulation''.)

The header files define the integer constants COK, E_OK, ERR (E_OK is in eti.h), and others listed in the following topics. ETI routines that return int values return these constants under the following conditions:

COK: returned if a low-level or panel function completes properly
E_OK: returned if a menu or form function does so
ERR: returned if a low-level function encounters an error

The other error values returned by the high-level functions are described in the appropriate topics.

Now let us consider the macro definitions. ocurses.h defines many ETI routines as macros that call other macros or ETI routines. For instance, the simple routine refresh is a macro. The line

   #define refresh()	wrefresh(stdscr)

shows that when refresh is called, it is expanded to call the ETI routine wrefresh. In turn, wrefresh (although it is not a macro) calls the two ETI routines wnoutrefresh and doupdate. Many other routines also group two or three routines together to achieve a particular result.

CAUTION: Macro expansion in ETI programs may cause problems with certain sophisticated C features, such as the use of automatic incrementing variables.

One final point about ocurses.h: it automatically includes stdio.h and the termio.h tty driver interface file. Including either file again in a program is harmless but wasteful.