{The S-Lang C Library Reference}: Functions that deal with the interpreter

Next Previous Contents

## 5. Functions that deal with the interpreter

## 5.1 SLsmg_fill_region

Synopsis

  Fill a rectangular region with a character

Usage

  `void SLsmg_fill_region (r, c, nr, nc, ch)`

  > `

  >         int r
  >         int c
  >         unsigned int nr
  >         unsigned int nc
  >         unsigned char ch

  > `

Description

  The `SLsmg_fill_region` function may be used to a rectangular region with the character `ch` in the current color. The rectangle's upper left corner is at row `r` and column `c`, and spans `nr` rows and `nc` columns. The position of the virtual cursor will be left at (`r`, `c`).

See Also

  `SLsmg_write_char, SLsmg_set_color`

## 5.2 SLsmg_set_char_set

Synopsis

  Turn on or off line drawing characters

Usage

  `void SLsmg_set_char_set (int a);`

Description

  `SLsmg_set_char_set` may be used to select or deselect the line drawing character set as the current character set. If `a` is non-zero, the line drawing character set will be selected. Otherwise, the standard character set will be selected.

Notes

  There is no guarantee that this function will actually enable the use of line drawing characters. All it does is cause subsequent characters to be rendered using the terminal's alternate character set. Such character sets usually contain line drawing characters.

See Also

  `SLsmg_write_char, SLtt_get_terminfo`

## 5.3 int SLsmg_Scroll_Hash_Border;

Synopsis

  Set the size of the border for the scroll hash

Usage

  `int SLsmg_Scroll_Hash_Border = 0;`

Description

  This variable may be used to ignore the characters that occur at the beginning and the end of a row when performing the hash calculation to determine whether or not a line has scrolled. The default value is zero which means that all the characters on a line will be used.

See Also

  `SLsmg_refresh`

## 5.4 SLsmg_suspend_smg

Synopsis

  Suspend screen management

Usage

  `int SLsmg_suspend_smg (void)`

Description

  `SLsmg_suspend_smg` can be used to suspend the state of the screen management facility during suspension of the program. Use of this function will reset the display back to its default state. The funtion `SLsmg_resume_smg` should be called after suspension.

  It returns zero upon success, or `-1` upon error.

  This function is similar to `SLsmg_reset_smg` except that the state of the display prior to calling `SLsmg_suspend_smg` is saved.

See Also

  `SLsmg_resume_smg, SLsmg_reset_smg`

## 5.5 SLsmg_resume_smg

Synopsis

  Resume screen management

Usage

  `int SLsmg_resume_smg (void)`

Description

  `SLsmg_resume_smg` should be called after `SLsmg_suspend_smg` to redraw the display exactly like it was before `SLsmg_suspend_smg` was called. It returns zero upon success, or `-1` upon error.

See Also

  `SLsmg_suspend_smg`

## 5.6 SLsmg_erase_eol

Synopsis

  Erase to the end of the row

Usage

  `void SLsmg_erase_eol (void);`

Description

  `SLsmg_erase_eol` erases all characters from the current position to the end of the line. The newly created space is given the color of the current color. This function has no effect on the position of the virtual cursor.

See Also

  `SLsmg_gotorc, SLsmg_erase_eos, SLsmg_fill_region`

## 5.7 SLsmg_gotorc

Synopsis

  Move the virtual cursor

Usage

  `void SLsmg_gotorc (int r, int c)`

Description

  The `SLsmg_gotorc` function moves the virtual cursor to the row `r` and column `c`. The first row and first column is specified by `r = 0` and `c = 0`.

See Also

  `SLsmg_refresh`

## 5.8 SLsmg_erase_eos

Synopsis

  Erase to the end of the screen

Usage

  `void SLsmg_erase_eos (void);`

Description

  The `SLsmg_erase_eos` is like `SLsmg_erase_eol` except that it erases all text from the current position to the end of the display. The current color will be used to set the background of the erased area.

See Also

  `SLsmg_erase_eol`

## 5.9 SLsmg_reverse_video

Synopsis

  Set the current color to 1

Usage

  `void SLsmg_reverse_video (void);`

Description

  This function is nothing more than `SLsmg_set_color(1)`.

See Also

  `SLsmg_set_color`

## 5.10 SLsmg_set_color (int)

Synopsis

  Set the current color

Usage

  `void SLsmg_set_color (int c);`

Description

  `SLsmg_set_color` is used to set the current color. The parameter `c` is really a color object descriptor. Actual foreground and background colors as well as other visual attributes may be associated with a color descriptor via the `SLtt_set_color` function.

Example

  This example defines color `7` to be green foreground on black background and then displays some text in this color:

  > `

  >           SLtt_set_color (7, NULL, "green", "black");
  >           SLsmg_set_color (7);
  >           SLsmg_write_string ("Hello");
  >           SLsmg_refresh ();

  > `

Notes

  It is important to understand that the screen managment routines know nothing about the actual colors associated with a color descriptor. Only the descriptor itself is used by the `SLsmg` routines. The lower level `SLtt` interface converts the color descriptors to actual colors. Thus

  > `

  >           SLtt_set_color (7, NULL, "green", "black");
  >           SLsmg_set_color (7);
  >           SLsmg_write_string ("Hello");
  >           SLtt_set_color (7, NULL, "red", "blue");
  >           SLsmg_write_string ("World");
  >           SLsmg_refresh ();

  > `

  will result in `"hello"` displayed in red on blue and not green on black.
See Also

  `SLtt_set_color, SLtt_set_color_object`

## 5.11 SLsmg_normal_video

Synopsis

  Set the current color to 0

Usage

  `void SLsmg_normal_video (void);`

Description

  `SLsmg_normal_video` sets the current color descriptor to `0`.

See Also

  `SLsmg_set_color`

## 5.12 SLsmg_printf

Synopsis

  Format a string on the virtual display

Usage

  `void SLsmg_printf (char *fmt, ...)`

Description

  `SLsmg_printf` format a `printf` style variable argument list and writes it on the virtual display. The virtual cursor will be moved to the end of the string.

See Also

  `SLsmg_write_string, SLsmg_vprintf`

## 5.13 SLsmg_vprintf

Synopsis

  Format a string on the virtual display

Usage

  `void SLsmg_vprintf (char *fmt, va_list ap)`

Description

  `SLsmg_vprintf` formats a string in the manner of vprintf and writes the result to the display. The virtual cursor is advanced to the end of the string.

See Also

  `SLsmg_write_string, SLsmg_printf`

## 5.14 SLsmg_write_string

Synopsis

  Write a character string on the display

Usage

  `void SLsmg_write_string (char *s)`

Description

  The function `SLsmg_write_string` displays the string `s` on the virtual display at the current position and moves the position to the end of the string.

See Also

  `SLsmg_printf, SLsmg_write_nstring`

## 5.15 SLsmg_write_nstring

Synopsis

  Write the first n characters of a string on the display

Usage

  `void SLsmg_write_nstring (char *s, unsigned int n);`

Description

  `SLsmg_write_nstring` writes the first `n` characters of `s` to this virtual display. If the length of the string `s` is less than `n`, the spaces will used until `n` characters have been written. `s` can be `NULL`, in which case `n` spaces will be written.

See Also

  `SLsmg_write_string, SLsmg_write_nchars`

## 5.16 SLsmg_write_char

Synopsis

  Write a character to the virtual display

Usage

  `void SLsmg_write_char (char ch);`

Description

  `SLsmg_write_char` writes the character `ch` to the virtual display.

See Also

  `SLsmg_write_nchars, SLsmg_write_string`

## 5.17 SLsmg_write_nchars

Synopsis

  Write n characters to the virtual display

Usage

  `void SLsmg_write_nchars (char *s, unsigned int n);`

Description

  `SLsmg_write_nchars` writes at most `n` characters from the string `s` to the display. If the length of `s` is less than `n`, the whole length of the string will get written.

  This function differs from `SLsmg_write_nstring` in that `SLsmg_write_nstring` will pad the string to write exactly `n` characters. `SLsmg_write_nchars` does not perform any padding.

See Also

  `SLsmg_write_nchars, SLsmg_write_nstring`

## 5.18 SLsmg_write_wrapped_string

Synopsis

  Write a string to the display with wrapping

Usage

  `void SLsmg_write_wrapped_string (s, r, c, nr, nc, fill)`

  > `

  >         char *s
  >         int r, c
  >         unsigned int nr, nc
  >         int fill

  > `

Description

  `SLsmg_write_wrapped_string` writes the string `s` to the virtual display. The string will be confined to the rectangular region whose upper right corner is at row `r` and column `c`, and consists of `nr` rows and `nc` columns. The string will be wrapped at the boundaries of the box. If `fill` is non-zero, the last line to which characters have been written will get padded with spaces.

Notes

  This function does not wrap on word boundaries. However, it will wrap when a newline charater is encountered.

See Also

  `SLsmg_write_string`

## 5.19 SLsmg_cls

Synopsis

  Clear the virtual display

Usage

  `void SLsmg_cls (void)`

Description

  `SLsmg_cls` erases the virtual display using the current color. This will cause the physical display to get cleared the next time `SLsmg_refresh` is called.

Notes

  This function is not the same as

  > `

  >          SLsmg_gotorc (0,0); SLsmg_erase_eos ();

  > `

  since these statements do not guarantee that the physical screen will get cleared.
See Also

  `SLsmg_refresh, SLsmg_erase_eos`

## 5.20 SLsmg_refresh

Synopsis

  Update physical screen

Usage

  `void SLsmg_refresh (void)`

Description

  The `SLsmg_refresh` function updates the physical display to look like the virtual display.

See Also

  `SLsmg_suspend_smg, SLsmg_init_smg, SLsmg_reset_smg`

## 5.21 SLsmg_touch_lines

Synopsis

  Mark lines on the virtual display for redisplay

Usage

  `void SLsmg_touch_lines (int r, unsigned int nr)`

Description

  `SLsmg_touch_lines` marks the `nr` lines on the virtual display starting at row `r` for redisplay upon the next call to `SLsmg_refresh`.

Notes

  This function should rarely be called, if ever. If you find that you need to call this function, then your application should be modified to properly use the `SLsmg` screen management routines. This function is provided only for curses compatibility.

See Also

  `SLsmg_refresh`

## 5.22 SLsmg_init_smg

Synopsis

  Initialize the `SLsmg` routines

Usage

  `int SLsmg_init_smg (void)`

Description

  The `SLsmg_init_smg` function initializes the `SLsmg` screen management routines. Specifically, this function allocates space for the virtual display and calls `SLtt_init_video` to put the terminal's physical display in the proper state. It is up to the caller to make sure that the `SLtt` routines are initialized via `SLtt_get_terminfo` before calling `SLsmg_init_smg`.

  This function should also be called any time the size of the physical display has changed so that it can reallocate a new virtual display to match the physical display.

  It returns zero upon success, or `-1` upon failure.

See Also

  `SLsmg_reset_smg`

## 5.23 SLsmg_reset_smg

Synopsis

  Reset the `SLsmg` routines

Usage

  `int SLsmg_reset_smg (void);`

Description

  `SLsmg_reset_smg` resets the `SLsmg` screen management routines by freeing all memory allocated while it was active. It also calls `SLtt_reset_video` to put the terminal's display in it default state.

See Also

  `SLsmg_init_smg`

## 5.24 SLsmg_char_at

Synopsis

  Get the character at the current position on the virtual display

Usage

  `unsigned short SLsmg_char_at(void)`

Description

  The `SLsmg_char_at` function returns the character and its color at the current position on the virtual display.

See Also

  `SLsmg_read_raw, SLsmg_write_char`

## 5.25 SLsmg_set_screen_start

Synopsis

  Set the origin of the virtual display

Usage

  `void SLsmg_set_screen_start (int *r, int *c)`

Description

  `SLsmg_set_screen_start` sets the origin of the virtual display to the row `*r` and the column `*c`. If either `r` or `c` is `NULL`, then the corresponding value will be set to `0`. Otherwise, the location specified by the pointers will be updated to reflect the old origin.

  See `slang/demo/pager.c` for how this function may be used to scroll horizontally.

See Also

  `SLsmg_init_smg`

## 5.26 SLsmg_draw_hline

Synopsis

  Draw a horizontal line

Usage

  `void SLsmg_draw_hline (unsigned int len)`

Description

  The `SLsmg_draw_hline` function draws a horizontal line of length `len` on the virtual display. The position of the virtual cursor is left at the end of the line.

See Also

  `SLsmg_draw_vline`

## 5.27 SLsmg_draw_vline

Synopsis

  Draw a vertical line

Usage

  `void SLsmg_draw_vline (unsigned int len);`

Description

  The `SLsmg_draw_vline` function draws a vertical line of length `len` on the virtual display. The position of the virtual cursor is left at the end of the line.

See Also

  `??`

## 5.28 SLsmg_draw_object

Synopsis

  Draw an object from the alternate character set

Usage

  `void SLsmg_draw_object (int r, int c, unsigned char obj)`

Description

  The `SLsmg_draw_object` function may be used to place the object specified by `obj` at row `r` and column `c`. The object is really a character from the alternate character set and may be specified using one of the following constants:

  > `

  >         SLSMG_HLINE_CHAR         Horizontal line
  >         SLSMG_VLINE_CHAR         Vertical line
  >         SLSMG_ULCORN_CHAR        Upper left corner
  >         SLSMG_URCORN_CHAR        Upper right corner
  >         SLSMG_LLCORN_CHAR        Lower left corner
  >         SLSMG_LRCORN_CHAR        Lower right corner
  >         SLSMG_CKBRD_CHAR         Checkboard character
  >         SLSMG_RTEE_CHAR          Right Tee
  >         SLSMG_LTEE_CHAR          Left Tee
  >         SLSMG_UTEE_CHAR          Up Tee
  >         SLSMG_DTEE_CHAR          Down Tee
  >         SLSMG_PLUS_CHAR          Plus or Cross character

  > `

See Also

  `SLsmg_draw_vline, SLsmg_draw_hline, SLsmg_draw_box`

## 5.29 SLsmg_draw_box

Synopsis

  Draw a box on the virtual display

Usage

  `void SLsmg_draw_box (int r, int c, unsigned int dr, unsigned int dc)`

Description

  `SLsmg_draw_box` uses the `SLsmg_draw_hline` and `SLsmg_draw_vline` functions to draw a rectangular box on the virtual display. The box's upper left corner is placed at row `r` and column `c`. The width and length of the box is specified by `dc` and `dr`, respectively.

See Also

  `SLsmg_draw_vline, SLsmg_draw_hline, SLsmg_draw_object`

## 5.30 SLsmg_set_color_in_region

Synopsis

  Change the color of a specifed region

Usage

  `void SLsmg_set_color_in_region (color, r, c, dr, dc)`

  > `

  >       int color;
  >       int r, c;
  >       unsigned int dr, dc;

  > `

Description

  `SLsmg_set_color_in_region` may be used to change the color of a rectangular region whose upper left corner is given by (`r`,`c`), and whose width and height is given by `dc` and `dr`, respectively. The color of the region is given by the `color` parameter.

See Also

  `SLsmg_draw_box, SLsmg_set_color`

## 5.31 SLsmg_get_column

Synopsis

  Get the column of the virtual cursor

Usage

  `int SLsmg_get_column(void);`

Description

  The `SLsmg_get_column` function returns the current column of the virtual cursor on the virtual display.

See Also

  `SLsmg_get_row, SLsmg_gotorc`

## 5.32 SLsmg_get_row

Synopsis

  Get the row of the virtual cursor

Usage

  `int SLsmg_get_row(void);`

Description

  The `SLsmg_get_row` function returns the current row of the virtual cursor on the virtual display.

See Also

  `SLsmg_get_column, SLsmg_gotorc`

## 5.33 SLsmg_forward

Synopsis

  Move the virtual cursor forward n columns

Usage

  `void SLsmg_forward (int n);`

Description

  The `SLsmg_forward` function moves the virtual cursor forward `n` columns.

See Also

  `SLsmg_gotorc`

## 5.34 SLsmg_write_color_chars

Synopsis

  Write characters with color descriptors to virtual display

Usage

  `void SLsmg_write_color_chars (unsigned short *s, unsigned int len)`

Description

  The `SLsmg_write_color_chars` function may be used to write `len` characters, each with a different color descriptor to the virtual display. Each character and its associated color are encoded as an `unsigned short` such that the lower eight bits form the character and the next eight bits form the color.

See Also

  `SLsmg_char_at, SLsmg_write_raw`

## 5.35 SLsmg_read_raw

Synopsis

  Read characters from the virtual display

Usage

  `unsigned int SLsmg_read_raw (unsigned short *buf, unsigned int len)`

Description

  `SLsmg_read_raw` attempts to read `len` characters from the current position on the virtual display into the buffer specified by `buf`. It returns the number of characters actually read. This number will be less than `len` if an attempt is made to read past the right margin of the display.

Notes

  The purpose of the pair of functions, `SLsmg_read_raw` and `SLsmg_write_raw`, is to permit one to copy the contents of one region of the virtual display to another region.

See Also

  `SLsmg_char_at, SLsmg_write_raw`

## 5.36 SLsmg_write_raw

Synopsis

  Write characters directly to the virtual display

Usage

  `unsigned int SLsmg_write_raw (unsigned short *buf, unsigned int len)`

Description

  The `SLsmg_write_raw` function attempts to write `len` characters specified by `buf` to the display at the current position. It returns the number of characters successfully written, which will be less than `len` if an attempt is made to write past the right margin.

Notes

  The purpose of the pair of functions, `SLsmg_read_raw` and `SLsmg_write_raw`, is to permit one to copy the contents of one region of the virtual display to another region.

See Also

  `SLsmg_read_raw`

Next Previous Contents