HP OpenVMS Systems Documentation

HP CRun-Time Library Reference Manual for
OpenVMS Systems

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

The OpenVMS Curses screen management package is supported on all
OpenVMS systems.

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

Furthermore, the HP 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."

1 Copyright (c) 1981 Regents of the
University of California.

The
<curses.h>
header file required to use the BSD-based Curses implementation is
provided with the HP 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
HP C, where BSD-based Curses was the default.)

To get 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.

Curses, the HP C Screen Management Package, is composed of
HP 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 HP C RTL Curses package.

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

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

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).

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 HP 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.

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
.

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.

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.

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
.

The
initscr
and
endwin
functions begin and end the window editing session. The
initscr
function clears the terminal screen (for OpenVMS Curses only; BSD-based
Curses does not clear the screen), 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.

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).

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
.

Note

Most Curses macros update
stdscr
by default. Curses functions that update other windows have the same
name as the macros but with the added prefix "w". For
example, the
addstr
macro adds a given string to
stdscr
at the current cursor position. The
waddstr
function adds a given string to a specified window at the current
cursor position.

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.

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.