The S-Lang library provides two interfaces to terminal independent
routines for manipulating the display on a terminal. The highest level
interface, known as the SLsmg interface is discussed in this
section. It provides high level screen management functions for
manipulating the display in an optimal manner and is similar in spirit to
the curses library. The lowest level interface, or the
SLtt
interface, is used by the SLsmg routines to actually perform the
task of writing to the display. This interface is discussed in another
section. Like the keyboard routines, the SLsmg routines are
platform independent and work the same on MSDOS, OS/2, Unix, and VMS.
The screen management, or SLsmg, routines are initialized by
function SLsmg_init_smg. Once initialized, the application uses
various SLsmg functions to write to a virtual display. This does
not cause the physical terminal display to be updated immediately.
The physical display is updated to look like the virtual display only
after a call to the function SLsmg_refresh. Before exiting, the
application using these routines is required to call
SLsmg_reset_smg to reset the display system.
The following subsections explore S-Lang's screen management system in greater detail.
The function SLsmg_init_smg must be called before any other
SLsmg function can be used. It has the simple prototype:
int SLsmg_init_smg (void);
For this routine to properly initialize the virtual display, the
capabilities of the terminal must be known as well as the size of
the physical display. For these reasons, the lower level SLtt routines
come into play. In particular, before the first call to
SLsmg_init_smg, the application is required to call the function
SLtt_get_terminfo before calling SLsmg_init_smg.
The SLtt_get_terminfo function sets the global variables
SLtt_Screen_Rows and SLtt_Screen_Cols to the values
appropriate for the terminal. It does this by calling the
SLtt_get_screen_size function to query the terminal driver
for the appropriate values for these variables. From this point on,
it is up to the application to maintain the correct values for these
variables by calling the SLtt_get_screen_size function
whenever the display size changes, e.g., in response to a
SIGWINCH signal. Finally, if the application is going to read
characters from the keyboard, it is also a good idea to initialize
the keyboard routines at this point as well.
Before the program exits or suspends, the function
SLsmg_reset_smg
should be called to shutdown the display system. This function has the
prototype
void SLsmg_reset_smg (void);
Basically, a program that uses the SLsmg screen management functions
and S-Lang's keyboard interface will look something like:
#include <slang.h>
int main ()
{
SLtt_get_terminfo ();
SLang_init_tty (-1, 0, 0);
SLsmg_init_smg ();
/* do stuff .... */
SLsmg_reset_smg ();
SLang_reset_tty ();
return 0;
}
SLsmg functions will be introduced which may be used
to make this simple program do much more.
The function SLsmg_reinit_smg is designed to be used in
conjunction with resize events.
Under Unix-like operating systems, when the size of the display
changes, the application will be sent a SIGWINCH signal. To
properly handle this signal, the SLsmg routines must be
reinitialized to use the new display size. This may be accomplished
by calling SLtt_get_screen_size to get the new size, followed by
SLsmg_reinit_smg to reinitialize the SLsmg interface
to use the new size. Keep in mind that these routines should
not be called from within the signal handler. The following code
illustrates the main ideas involved in handling such events:
static volatile int Screen_Size_Changed;
static sigwinch_handler (int sig)
{
Screen_Size_Changed = 1;
SLsignal (SIGWINCH, sigwinch_handler);
}
int main (int argc, char **argv)
{
SLsignal (SIGWINCH, sigwinch_handler);
SLsmg_init_smg ();
.
.
/* Now enter main loop */
while (not_done)
{
if (Screen_Size_Changed)
{
SLtt_get_screen_size ();
SLsmg_reinit_smg ();
redraw_display ();
}
.
.
}
return 0;
}
In the previous sections, functions for initializing and shutting down the
SLsmg routines were discussed. In this section, the rest of the
SLsmg functions are presented. These functions act only on the
virtual display. The physical display is updated when the
SLsmg_refresh function is called and not until that time.
This function has the simple prototype:
void SLsmg_refresh (void);
The SLsmg_gotorc function is used to position the cursor at a given
row and column. The prototype for this function is:
void SLsmg_gotorc (int row, int col);
row = 0 and the first column corresponds to col = 0. The last
row of the screen is given by row = SLtt_Screen_Rows - 1.
It is possible to change the origin of the coordinate system by using the
function SLsmg_set_screen_start with prototype:
void SLsmg_set_screen_start (int *r, int *c);
NULL
pointer may be passed to indicate that the origin is to be set to its
initial value of 0. For example,
int r = 10;
SLsmg_set_screen_start (&r, NULL);
r will have the value of the previous row origin.
SLsmg has several routines for outputting text to the virtual
display. The following points should be understood:
^ as the first character. That is,
Ctrl-X is output as ^X.
SLsmg_Newline_Behavior variable. It may be set to
any one of the following values:
SLSMG_NEWLINE_IGNORED : If a newline character is
encountered when writing a string to the virtual display, the
characters in the string following the newline character will not
be written. In other words, the newline character will act like
a string termination character. This is the default setting for
the SLsmg_Newline_Behavior.
SLSMG_NEWLINE_MOVES : If a newline character is when
writing to the virtual display, the following characters will be
written to the beginning of the next row.
SLSMG_NEWLINE_SCROLLS : When set to this value and a
newline character is output at the bottom of the virtual
display, the display will scroll up. Otherwise the behavior
will be the same as that of SLSMG_NEWLINE_MOVES.
SLSMG_NEWLINE_PRINTABLE : When set to this value, a
newline character will be printed as the two characters sequence
^J.
Although the some of the above items might appear to be too restrictive, in practice this is not seem to be the case. In fact, the design of the output routines was influenced by their actual use and modified to simplify the code of the application utilizing them.
void SLsmg_write_char (char ch);Write a single character to the virtual display.
void SLsmg_write_nchars (char *str, int len);Write len characters pointed to by str to the
virtual display.
void SLsmg_write_string (char *str);Write the null terminated string given by pointer str to the
virtual display. This function is a wrapper around
SLsmg_write_nchars.
void SLsmg_write_nstring (char *str, int n);The purpose of this function is to write a null terminated string to
a field that is at most n cells wide. Each double-wide
character in the string will use two cells. If the string is not
big enough to fill the n cells, the rest of the cells will be
filled with space characters. This function is a wrapper around
SLsmg_write_wrapped_string.
void SLsmg_write_wrapped_string(SLuchar_Type *str, int r, int c, unsigned int dr, unsigned int dc, int fill)The purpose of this function is to write a string str to a
box defined by rows and columns satisfying r<=row<r+dc and
c<=column<c+dc. The string will be wrapped at the column
boundaries of the box and truncated if its size exceeds to size of
the box. If the total size of the string is less than that of the
box, and the fill parameter is non-zero, then the rest of the
cells in the box will be filled with space characters. Currently the
wrapping algorithm is very simple and knows nothing about word
boundaries.
void SLsmg_printf (char *fmt, ...);This function is similar to printf except that it writes to
the SLsmg virtual display.
void SLsmg_vprintf (char *, va_list);Like SLsmg_printf but uses a variable argument list.
The following functions may be used to fill portions of the display with blank characters. The attributes of blank character are the current attributes. (See below for a discussion of character attributes)
void SLsmg_erase_eol (void);Erase line from current position to the end of the line.
void SLsmg_erase_eos (void);Erase from the current position to the end of the screen.
void SLsmg_cls (void);Clear the entire virtual display.
Character attributes define the visual characteristics the character
possesses when it is displayed. Visual characteristics include the
foreground and background colors as well as other attributes such as
blinking, bold, and so on. Since SLsmg takes a different approach
to this problem than other screen management libraries an explanation of
this approach is given here. This approach has been motivated by
experience with programs that require some sort of screen management.
Most programs that use SLsmg are composed of specific textual
objects or objects made up of line drawing characters. For example,
consider an application with a menu bar with drop down menus. The menus
might be enclosed by some sort of frame or perhaps a shadow. The basic
idea is to associate an integer to each of the objects (e.g., menu bar,
shadow, current menu item, etc.) and create a mapping from the integer to
the set of attributes. In the terminology of SLsmg, the integer is
simply called an object.
For example, the menu bar might be associated with the object 1, the
drop down menu could be object 2, the shadow could be object
3,
and so on.
The range of values for the object integer is restricted from 0 up to and including 255 on all systems except MSDOS where the maximum allowed integer is 15
This difference is due to memory constraints imposed by MSDOS. This restriction might be removed in a future version of the library.. The object numbered zero should not be regarding as an object at all. Rather it should be regarded as all other objects that have not explicitly been given an object number.
SLsmg, or
more precisely SLtt, refers to the attributes of this special object
as the default or normal attributes.
The SLsmg routines know nothing about the mapping of the color to the
attributes associated with the color. The actual mapping takes place at a
lower level in the SLtt routines. Hence, to map an object to the
actual set of attributes requires a call to any of the following
SLtt
routines:
void SLtt_set_color (int obj, char *name, char *fg, char *bg);
void SLtt_set_color_object (int obj, SLtt_Char_Type attr);
void SLtt_set_mono (int obj, char *, SLtt_Char_Type attr);
SLtt interface.
The SLtt_set_color function takes four parameters. The first
parameter, obj, is simply the integer of the object for which
attributes are to be assigned. The second parameter is currently
unused by these routines. The third and forth parameters, fg
and bg, are the names of the foreground and background color
to be used associated with the object. The strings that one can use
for the third and fourth parameters can be any one of the 16 colors:
"black" "gray"
"red" "brightred"
"green" "brightgreen"
"brown" "yellow"
"blue" "brightblue"
"magenta" "brightmagenta"
"cyan" "brightcyan"
"lightgray" "white"
fg can be anyone of these
sixteen colors. However, on most terminals, the background color will
can only be one of the colors listed in the first column
This is also true on the Linux console. However, it need not be the case and hopefully the designers of Linux will someday remove this restriction..
Of course not all terminals are color terminals. If the S-Lang global
variable SLtt_Use_Ansi_Colors is non-zero, the terminal is
assumed to be a color terminal. The SLtt_get_terminfo will
try to determine whether or not the terminal supports colors and set
this variable accordingly. It does this by looking for the
capability in the terminfo/termcap database. Unfortunately many Unix
databases lack this information and so the SLtt_get_terminfo
routine will check whether or not the environment variable
COLORTERM exists. If it exists, the terminal will be assumed
to support ANSI colors and SLtt_Use_Ansi_Colors will be set to one.
Nevertheless, the application should provide some other mechanism to set
this variable, e.g., via a command line parameter.
When the SLtt_Use_Ansi_Colors variable is zero, all objects
with numbers greater than one will be displayed in inverse
video
This behavior can be modified by using the
SLtt_set_mono function call.
.
With this background, the SLsmg functions for setting the character
attributes can now be defined. These functions simply set the object
attributes that are to be assigned to subsequent characters written
to the virtual display. For this reason, the new attribute is called the
current attribute.
void SLsmg_set_color (int obj);Set the current attribute to those of object obj.
void SLsmg_normal_video (void);This function is equivalent to SLsmg_set_color (0).
void SLsmg_reverse_video (void);This function is equivalent to SLsmg_set_color (1). On monochrome
terminals, it is equivalent to setting the subsequent character attributes
to inverse video.
Unfortunately there does not seem to be a standard way for the
application or, in particular, the library to determine which color
will be used by the terminal for the default background. Such
information would be useful in initializing the foreground and
background colors associated with the default color object (0). For
this reason, it is up to the application to provide some means for
the user to indicate what these colors are for the particular
terminal setup. To facilitate this, the SLtt_get_terminfo
function checks for the existence of the COLORFGBG
environment variable. If this variable exists, its value will be
used to initialize the colors associated with the default color
object. Specifically, the value is assumed to consist of a
foreground color name and a background color name separated by a
semicolon. For example, if the value of COLORFGBG is
lightgray;blue, the default color object will be initialized
to represent a lightgray foreground upon a blue
background.
The S-Lang screen management library also includes routines for turning on and turning off alternate character sets. This is especially useful for drawing horizontal and vertical lines.
void SLsmg_set_char_set (int flag);If flag is non-zero, subsequent write functions will use characters
from the alternate character set. If flag is zero, the default, or,
ordinary character set will be used.
void SLsmg_draw_hline (int len);Draw a horizontal line from the current position to the column that is
len characters to the right.
void SLsmg_draw_vline (int len);Draw a horizontal line from the current position to the row that is
len rows below.
void SLsmg_draw_box (int r, int c, int dr, int dc);Draw a box whose upper right corner is at row r and column
c.
The box spans dr rows and dc columns. The current position
will be left at row r and column c.
void SLsmg_touch_lines (int r, int n);Mark screen rows numbered r, r + 1, ... r +
(n - 1) as
modified. When SLsmg_refresh is called, these rows will be
completely redrawn.
int SLsmg_char_at(SLsmg_Char_Type *ch);Returns the character and its attributes at the current position. The SLsmg_Char_Type object is a structure representing the character cell:
#define SLSMG_MAX_CHARS_PER_CELL 5
typedef struct
{
unsigned int nchars;
SLwchar_Type wchars[SLSMG_MAX_CHARS_PER_CELL];
SLsmg_Color_Type color;
}
SLsmg_Char_Type;
nchars field will be 1 to indicate
that the character contains precisely one character whose value is
given by the zeroth element of the wchars array of the structure.
The value of nchars will be greater than one if the character
cell also contains so-called Unicode combining characters. The
combining characters are given by the elements 1 through
nchars-1 of the wchars array. If nchars is 0,
then the character cell represents the second half of a double-wide
character.
The color field repesents both the color of the character
cell and the alternate character set setting of the cell. This
value may be bitwise-anded with SLSMG_COLOR_MASK to obtain
the cell's color, and bitwise-anded with SLSMG_ACS_MASK to
determine whether or not the alternate-character set setting is in
effect for the cell (zero or non-zero).
The following S-Lang global variables are used by the SLsmg
interface. Some of these have been previously discussed.
int SLtt_Screen_Rows;
int SLtt_Screen_Cols;
The number of rows and columns of the physical display. If either of
these numbers changes, the functions SLsmg_reset_smg and
SLsmg_init_smg should be called again so that the SLsmg
routines can re-adjust to the new size.
int SLsmg_Tab_Width;
Set this variable to the tab width that will be used when expanding tab
characters. The default is 8.
int SLsmg_Display_Eight_Bit;
This variable determines how characters with the high bit set are to be
output. Specifically, a character with the high bit set with a value
greater than or equal to this value is output as is; otherwise, it will be
output in a 7-bit representation. The default value for this variable is
128 for MSDOS and 160 for other systems (ISO-Latin).
In UTF-8 mode, the value of this variable is 0.
int SLtt_Use_Ansi_Colors;
If this value is non-zero, the terminal is assumed to support ANSI colors
otherwise it is assumed to be monochrome. The default is 0.
int SLtt_Term_Cannot_Scroll;
If this value is zero, the SLsmg will attempt to scroll the physical
display to optimize the update. If it is non-zero, the screen management
routines will not perform this optimization. For some applications, this
variable should be set to zero. The default value is set by the
SLtt_get_terminfo function.
This section discusses some general design issues that one must face when writing an application that requires some sort of screen management.