This chapter describes the screen management routines available with Compaq C for OpenVMS Systems.

On all OpenVMS systems, the OpenVMS Curses screen management package is supported. This is the same package of routines used by the VAX C Run-Time Library (RTL).

On Alpha systems, for OpenVMS Alpha Version 1.5 or higher, two screen management packages are supported: OpenVMS Curses and a more UNIX compatible package based on the Berkeley Standard Distribution (BSD) Curses software.¹ Section 6.1 for more information.

Furthermore, beginning with OpenVMS Alpha Version 7.0, the Compaq C RTL offers a curses package based on the 4.4BSD Berkeley Software Distribution. Documentation on the 4.4BSD curses package can be found in Screen Updating and Cursor Movement Optimization: A Library Package, by Kenneth C.R.C. Arnold.

The functions and macros in the OpenVMS and BSD-based Curses packages are nearly the same. Most differences between them are called out in this chapter. Otherwise, this chapter makes no distinction between the two Curses packages, and refers to "Curses" or the "Curses functions and macros."

6.1 Using the BSD-Based Curses Package (ALPHA ONLY)

The <curses.h> header file required to use the BSD-based Curses implementation is provided with the Compaq C compiler on OpenVMS Alpha systems.

Existing programs are not affected by the BSD-based Curses functions because the OpenVMS Curses functions are still available as the default curses package. (Note that is a change from previous versions of Compaq C, where BSD-based curses was the default.)

To get the the 4.4BSD Curses implementation, you must compile modules that include <curses.h> with the following qualifier:

/DEFINE=_BSD44_CURSES

The BSD-based Curses functions do not provide the support required to call the OpenVMS SMG$ routines with the pasteboard and keyboard allocated by the curses functions. Consequently, Curses programs that rely on calling SMG$ entry points, as well as Curses functions, must continue to use the OpenVMS Curses implementation.

The BSD-based Curses implementation is not interoperable with the old implementation. Attempts to mix calls to the new functions and the old functions will result in incorrect output displayed on the screen and could result in an exception from an SMG$ routine.

6.2 Curses Overview

Curses, the Compaq C Screen Management Package, is composed of Compaq C RTL functions and macros that create and modify defined sections of the terminal screen and optimize cursor movement. Using the screen management package, you can develop a user interface that is both visually attractive and user-friendly. Curses is terminal-independent and provides simplified terminal screen formatting and efficient cursor movement.

Most Curses functions and macros are listed in pairs where the first routine is a macro and the second is a function beginning with the prefix "w," for "window." These prefixes are delimited by brackets ([ ]). For example, [w]addstr designates the addstr macro and the waddstr function. The macros default to the window stdscr ; the functions accept a specified window as an argument.

To access the Curses functions and macros, include the <curses.h> header file.

The terminal-independent Screen Management Software, which is part of the OpenVMS RTL, is used to implement Curses. For portability purposes, most functions and macros are designed to perform in a manner similar to other C implementations. However, the Curses routines depend on the OpenVMS system and its Screen Management Software, so performance of some functions and macros could differ slightly from those of other implementations.

Some functions and macros available on other systems are not available with the Compaq C RTL Curses package.

Some functions, such as [w]clrattr , [w]insstr , mv[w]insstr , and [w]setattr are specific to Compaq C for OpenVMS Systems and are not portable.

Table 6-1 lists all of the Curses functions and macros found in the Compaq C RTL. For more detailed information on each function and macro, see the Reference Section.

Table 6-1 Curses Functions and Macros

Function or Macro	Description
[w]addch	Adds a character to the window at the current position of the cursor.
[w]addstr	Adds a string to the window at the current position of the cursor.
box	Draws a box around the window.
[w]clear	Erases the contents of the specified window and resets the cursor to coordinates (0,0).
clearok	Sets the clear flag for the window.
[w]clrattr	Deactivates the video display attribute within the window.
[w]clrtobot	Erases the contents of the window from the current position of the cursor to the bottom of the window.
[w]clrtoeol	Erases the contents of the window from the current cursor position to the end of the line on the specified window.
[no]crmode	Sets and unsets the terminal from cbreak mode.
[w]delch	Deletes the character on the specified window at the current position of the cursor.
[w]deleteln	Deletes the line at the current position of the cursor.
delwin	Deletes the specified window from memory.
[no]echo	Sets the terminal so that characters may or may not be echoed on the terminal screen.
endwin	Clears the terminal screen and frees any virtual memory allocated to Curses data structures.
[w]erase	Erases the window by painting it with blanks.
[w]getch	Gets a character from the terminal screen and echoes it on the specified window.
[w]getstr	Gets a string from the terminal screen, stores it in a character variable, and echoes it on the specified window.
getyx	Puts the (y,x) coordinates of the current cursor position on the window in the variables y and x.
[w]inch	Returns the character at the current cursor position on the specified window without making changes to the window.
initscr	Initializes the terminal-type data and all screen functions.
[w]insch	Inserts a character at the current cursor position in the specified window.
[w]insertln	Inserts a line above the line containing the current cursor position.
[w]insstr	Inserts a string at the current cursor position on the specified window.
leaveok	Leaves the cursor at the current coordinates after an update to the window.
longname	Assigns the full terminal name to a character name that must be large enough to hold the character string.
[w]move	Changes the current cursor position on the specified window.
mv[w]addch	Moves the cursor and adds a character to the specified window.
mv[w]addstr	Moves the cursor and adds a string to the specified window.
mvcur	Moves the terminal's cursor.
mv[w]delch	Moves the cursor and deletes a character on the specified window.
mv[w]getch	Moves the cursor, gets a character from the terminal screen, and echoes it on the specified window.
mv[w]getstr	Moves the cursor, gets a string from the terminal screen, stores it in a variable, and echoes it on the specified window.
mv[w]inch	Moves the cursor and returns the character on the specified window without making changes to the window.
mv[w]insch	Moves the cursor and inserts a character in the specified window.
mv[w]insstr	Moves the cursor and inserts a string in the specified window.
mvwin	Moves the starting position of the window to the specified coordinates.
newwin	Creates a new window with lines and columns starting at the coordinates on the terminal screen.
[no]nl	Provided only for UNIX software compatibility and has no functionality in the OpenVMS environment.
overlay	Writes the contents of one window that will fit over the contents of another window, beginning at the starting coordinates of both windows.
overwrite	Writes the contents of one window, insofar as it will fit, over the contents of another window beginning at the starting coordinates of both windows.
[w]printw	Performs a printf on the window starting at the current position of the cursor.
[no]raw	Provided only for UNIX software compatibility and has no functionality in the OpenVMS environment.
[w]refresh	Repaints the specified window on the terminal screen.
[w]scanw	Performs a scanf on the window.
scroll	Moves all the lines on the window up one line.
scrollok	Sets the scroll flag for the specified window.
[w]setattr	Activates the video display attribute within the window.
[w]standend	Deactivates the boldface attribute for the specified window.
[w]standout	Activates the boldface attribute of the specified window.
subwin	Creates a new subwindow with lines and columns starting at the coordinates on the terminal screen.
touchwin	Places the most recently edited version of the specified window on the terminal screen.
wrapok	OpenVMS Curses only. Allows the wrapping of a word from the right border of the window to the beginning of the next line.

6.3 Curses Terminology

This section explains some of the Curses terminology and shows you how Curses looks on the terminal screen.

Consider a Curses application as being a series of overlapping windows. Window overlapping is called occlusion. To distinguish the boundaries of these occluding windows, you can outline the rectangular windows with specified characters, or you can turn on the reverse video option (make the window a light background with dark writing).

6.3.1 Predefined Windows (stdscr and curscr)

Initially, two windows the size of the terminal screen are predefined by Curses. These windows are called stdscr and curscr . The stdscr window is defined for your use. Many Curses macros default to this window. For example, if you draw a box around stdscr , move the cursor to the left-corner area of the screen, write a string to stdscr , and then display stdscr on the terminal screen, your display will look like that in Figure 6-1.

Figure 6-1 An Example of the stdscr Window

The second predefined window, curscr , is designed for internal Curses work; it is an image of what is currently displayed on the terminal screen. The only Compaq C for OpenVMS Curses function that will accept this window as an argument is clearok . Do not write to or read from curscr . Use stdscr and user-defined windows for all your Curses applications.

6.3.2 User-Defined Windows

You can occlude stdscr with your own windows. The size and location of each window is given in terms of the number of lines, the number of columns, and the starting position.

The lines and columns of the terminal screen form a coordinate system, or grid, on which the windows are formed. You specify the starting position of a window with the (y,x) coordinates on the terminal screen where the upper left corner of the window is located. The coordinates (0,0) on the terminal screen, for example, are the upper left corner of the screen.

The entire area of the window must be within the terminal screen borders; windows can be as small as a single character or as large as the entire terminal screen. You can create as many windows as memory allows.

When writing to or deleting from windows, changes do not appear on the terminal screen until the window is refreshed. When refreshing a window, you place the updated window onto the terminal screen, which leaves the rest of the screen unaltered.

All user-defined windows, by default, occlude stdscr . You can create two or more windows that occlude each other as well as stdscr . When writing data to one occluding window, the data is not written to the underlying window.

You can create overlapping windows (called subwindows). A declared window must contain the entire area of its subwindow. When writing data to a subwindow or to the portion of the window overlapped by the subwindow, both windows contain the new data. For instance, if you write data to a subwindow and then delete that subwindow, the data is still present on the underlying window.

If you create a window that occludes stdscr and a subwindow of stdscr , your terminal screen will look like Figure 6-2.

Figure 6-2 Displaying Windows and Subwindows

If you delete both the user-defined window and the subwindow, and then update the terminal screen with the new image, your terminal screen will look like Figure 6-3.

Figure 6-3 Updating the Terminal Screen

The string written on the window is deleted, but the string written on the subwindow remains on stdscr .

6.4 Getting Started with Curses

There are commands that you must use to initialize and restore the terminal screen when using Curses Screen Management functions and macros. Also, there are predefined variables and constants on which Curses depends. Example 6-1 shows how to set up a program using Curses.

Example 6-1 A Curses Program

(1)#include <curses.h> (2)WINDOW *win1, *win2, *win3; main() { (3) initscr(); . . . endwin(); }

Key to Example 6-1:

1. The preprocessor directive includes the <curses.h> header file, which defines the data structures and variables used to implement Curses. The <curses.h> header file includes the <stdio.h> header file, so it is not necessary to duplicate this action by including <stdio.h> again in the program source code. You must include <curses.h> to use any of the Curses functions or macros.
2. In the example, WINDOW is a data structure defined in <curses.h> . You must declare each user-specified window in this manner. In Example 6-1, the three defined windows are win1 , win2 , and win3 .
3. The initscr and endwin functions begin and end the window editing session. The initscr function clears the terminal screen (OpenVMS Curses only; BSD-based Curses does not), and allocates space for the windows stdscr and curscr . The endwin function deletes all windows and clears the terminal screen.

Most Curses users wish to define and modify windows. Example 6-2 shows you how to define and write to a single window.

Example 6-2 Manipulating Windows

#include <curses.h> WINDOW *win1, *win2, *win3; main() { initscr(); (1) win1 = newwin(24, 80, 0, 0); (2) mvwaddstr(win1, 2, 2, "HELLO"); . . . endwin(); }

Key to Example 6-2:

1. The newwin function defines a window 24 rows high and 80 columns wide with a starting position at coordinates (0,0), the upper left corner of the terminal screen. The program assigns these attributes to win1 . The coordinates are specified as follows: (lines,columns) or (y,x).
2. The mvwaddstr macro performs the same task as a call to the separate macros move and addstr . The mvwaddstr macro moves the cursor to the specified coordinates and writes a string onto stdscr .

When updating a window, specify the cursor position relative to the origin of the window, not the origin of the terminal screen. For example, if a window has a starting position of (10,10) and you want to add a character to the window at its starting position, specify the coordinates (0,0), not (10,10).

The string HELLO in Example 6-2 does not appear on the terminal screen until you refresh the screen. You accomplish this by using the wrefresh function. Example 6-3 shows how to display the contents of win1 on the terminal screen.

Example 6-3 Refreshing the Terminal Screen

#include <curses.h> WINDOW *win1, *win2, *win3; main() { initscr(); win1 = newwin(22, 60, 0, 0); mvwaddstr(win1, 2, 2, "HELLO"); wrefresh(win1); . . . endwin(); }

The wrefresh function updates just the region of the specified window on the terminal screen. When the program is executed, the string HELLO appears on the terminal screen until the program executes the endwin function. The wrefresh function only refreshes the part of the window on the terminal screen that is not overlapped by another window. If win1 was overlapped by another window and you want all of win1 to be displayed on the terminal screen, call the touchwin function.