S-Lang Library C Programmer's Guide, V1.4.2: Screen Management

Next Previous Contents

## 5. Screen Management

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

## 5.1 Initialization

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

> `

It returns zero if successful or -1 if it cannot allocate space for the virtual display.

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.

## 5.2 Resetting SLsmg

Before the program exits or suspends, the function `SLsmg_reset_tty` should be called to shutdown the display system. This function has the prototype

> `

>           void SLsmg_reset_smg (void);

> `

This will deallocate any memory allocated for the virtual screen and reset the terminal's display.

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;
>           }

> `

If this program is compiled and run, all it will do is clear the screen and position the cursor at the bottom of the display. In the following sections, other `SLsmg` functions will be introduced which may be used to make this simple program do much more.

## 5.3 Handling Screen Resize Events

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;
>          }

> `

## 5.4 SLsmg Functions

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

> `

### Positioning the cursor

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

> `

The origin of the screen is at the top left corner and is given the coordinate (0, 0), i.e., the top row of the screen corresponds to `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);

> `

This function takes pointers to the new values of the first row and first column. It returns the previous values by modifying the values of the integers at the addresses specified by the parameter list. A `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);

> `

sets the origin to (10, 0) and after the function returns, the variable `r` will have the value of the previous row origin.

### Writing to the Display

`SLsmg` has several routines for outputting text to the virtual display. The following points should be understood:

- The text is output at the position of the cursor of the virtual display and the cursor is advanced to the position that corresponds to the end of the text.
- Text does not wrap at the boundary of the display--- it is trucated. This behavior seems to be more useful in practice since most programs that would use screen management tend to be line oriented.
- Control characters are displayed in a two character sequence representation with `^` as the first character. That is, `Ctrl-X` is output as `^X`.
- The newline character does not cause the cursor to advance to the next row. Instead, when a newline character is encountered when outputting text, the output routine will return. That is, outputting a string containing a newline character will only display the contents of the string up to the newline character.

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);` Write the null terminated string given by pointer `str` to the virtual display. At most, only `n` characters are written. If the length of the string is less than `n`, then the string will be padded with blanks. This function is a wrapper around `SLsmg_write_nchars`.

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

### Erasing the Display

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.

### Setting Character Attributes

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

> `

Only the first of these routines will be discussed briefly here. The latter two functions allow more fine control over the object to attribute mapping (such as assigning a ``blink'' attribute to the object). For a more full explanation on all of these routines see the section about the `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"

> `

The value of the foreground parameter `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 `COLORTERM` is `lightgray;blue`, the default color object will be initialized to represent a `lightgray` foreground upon a `blue` background.

### Lines and Alternate Character Sets

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

### Miscellaneous Functions

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

`unsigned short SLsmg_char_at(void);` Returns the character and its attributes object number at the current cursor position. The character itself occupies the lower byte and the object attributes number forms the upper byte. The object returned by this function call should not be written back out via any of the functions that write characters or character strings.

## 5.5 Variables

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

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

## 5.6 Hints for using SLsmg

This section discusses some general design issues that one must face when writing an application that requires some sort of screen management.

Next Previous Contents