TERM

Section: Local Commands (L)
Updated: Radiation Oncology, NCMH
Index Return to Main Contents

NAME

term - "crash-proof" datum entry routines using termcap(3x)

SYNOPSIS

#include <term.h>

cc [ flags ] files -lterm -ltermcap [ libraries ]

DESCRIPTION

These routines look after datum entry for the basic datum types and provide some cursor control. A call to InitTerm initializes the term package by getting the terminal type from environment variable TERM and by reading the appropriate termcap entry. In typical use, the calling program would paint a screen and place the cursor at the beginning of a datum field using page, gotoxy, and printf and would then call the appropriate term routine to enter or edit that datum. The field is highlighted using underline mode and the default value, if any, is displayed. The user may then enter a new value of the datum under strict field size enforcement or accept the default. Acceptance of the displayed value is indicated by a RETURN. The default value can be retrieved by ^X. No abort is possible. When the value is accepted, the field is rewritten in normal mode and with the new value of the datum, and the cursor is left at the end of the field.

Exceptions to the above are GetBool for which valid inputs are n, N, y, Y, SPACE, and RETURN, for no, yes, toggle, and accept respectively, PickOne which understands ^ for previous value, SPACE for next value, and RETURN for accept, and MenuPick which understands ^ for previous value, SPACE for next value, > for next page, and RETURN for accept.

Magic cookies are dealt with properly but with the result that the field on the screen is wider than the requested datum field during entry. The requested field size is used when the field is rewritten in normal mode after acceptance of a datum value. This is a feature of term and a bug in the terminals with magic cookies. Curses(3x) deals with this problem by just not allowing standout mode. Which would you rather buy?

AUTHOR

George W. Sherouse
Radiation Oncology
North Carolina Memorial Hospital
University of North Carolina, Chapel Hill

FUNCTIONS

Initialize term. Returns 0 if successful, -1 if getenv fails, -2 if tgetent cannot open termcap file, -3 if tgetent cannot find entry for terminal. If the return is not zero, do not pass GO.
int InitTerm();

Get a floating point number. Imagine %(field_width).(places)f in a printf.
       float GetFloat(default, field_width, places);

       float default;

       int field_width;

       int places;

Get an integer.
       int GetInt(default, field_width);

       int default;

       int field_width;

Get a boolean.
int GetBool(default);

int default;

Get a string. String should be at least field_size + 1 long to accomodate the appended null. Null_ok is a boolean which declares whether or not a string of length zero is acceptable.
       void GetString(string, field_size, null_ok);

       char *string;

       int field_size;

       int null_ok;

Get a hospital number in the format 00-00-00.
void GetHospNum(hosp_num);

char *hosp_num

Pick one string from a list of strings by displaying one choice at a time in the field.
       int PickOne(list, choice_count);

       char **list;

       int choice_count;

A full-screen version of PickOne. The page is cleared, the prompt is displayed at the top of the page and the first <some number> choices are displayed. The user may step through the choices with ^ and SPACE. If there are more than <some number> choices, the user may also change pages with >. RETURN accepts currently highlighted value.
       int MenuPick(prompt, list, choice_count);

       char *prompt;

       char **list;

       int choice_count;

Clear the screen.
void page();

Move cursor. Coordinates are 1-indexed from upper left.
       void gotoxy(col, line);

       int col;

       int line;

Clear to end of line.
void ClearEOL();

Print string centered on line. Mode == 0 requests normal print, == 1 requests underline, and == 2 requests standout.
       void center(line, string, mode);

       int line;

       char *string;

       int mode;

Set or clear standout mode. Not very useful at the applications level.
void StandOut(on_or_off);

int on_or_off;

Set or clear underline mode. Not very useful at the applications level.
void underline(on_or_off);

int on_or_off;

Issue some backspaces. Not very interesting at the applications level.
void TermRewind(count);

int count;

Place stdin into raw mode with no echo on odd calls and restore original modes on even calls. Return the terminal's erase character. Not intended for use at the applications level.
char TermSetUp();

BUGS

Many sorts of stupidity are not checked for. These include but are not limited to string longer than terminal width in center, line or col out of bounds in center or gotoxy, fractional part longer than field_size in GetFloat, and 0 or negative field_size anywhere.

Some unreasonable assumptions are made regarding sanity in the termcap. You will know what they are if you violate them. I apologize in advance.

GetFloat does not support scientific notation. It also does not let you back up over the decimal point once it has placed it. This is no great hardship since you can always ^X to restart.

Some of the code is a little ugly, having been hacked unmercifully through many revisions. It does seem to work, though.

This document was created by man2html, using the manual pages.
Time: 06:39:54 GMT, December 12, 2024