cref.tm

一个C格式的脚本处理函数库源代码,可让你的C程序具有执行C格式的脚本文件

#i linuxdoc.tm

#d slang \bf{S-lang}
#d jed \bf{jed}
#d slang-c-programmers-guide \em{S-Lang Library C Programmer's Guide}
#d kw#1 \tt{$1}
#d exmp#1 \tt{$1}
#d var#1 \tt{$1}
#d ldots ...
#d chapter#1 <chapt>$1<p>
#d preface <preface>
#d tag#1 <tag>$1</tag>

#d function#1 \sect{<bf>$1</bf>\label{$1}}<descrip>
#d variable#1 \sect{<bf>$1</bf>\label{$1}}<descrip>
#cd function#1 <p><bf>$1</bf>\label{$1}<p><descrip>
#d synopsis#1 <tag> Synopsis </tag> $1
#d keywords#1 <tag> Keywords </tag> $1
#d usage#1 <tag> Usage </tag> <tt>$1</tt>
#d description <tag> Description </tag>
#d example <tag> Example </tag>
#d notes <tag> Notes </tag>
#d seealso#1 <tag> See Also </tag> <tt>$1</tt>
#d documentstyle article
#d r#1 \ref{$1}{$1}
#d done </descrip><p>
#d 0 \exmp{0}
#d -1 \exmp{-1}
#d 1 \exmp{1}

\linuxdoc
\begin{\documentstyle}

\title {The \slang C Library Reference}
\author John E. Davis, \tt{[e-mail]}
\date \__today__

\toc


\function{SLsmg_fill_region}
\synopsis{Fill a rectangular region with a character}
\usage{void SLsmg_fill_region (r, c, nr, nc, ch)}
#v+
    int r
    int c
    unsigned int nr
    unsigned int nc
    unsigned char ch
#v-
\description
  The \var{SLsmg_fill_region} function may be used to a 
  rectangular region with the character \var{ch} in the current color.
  The rectangle's upper left corner is at row \var{r} and column
  \var{c}, and spans \var{nr} rows and \var{nc} columns.  The position
  of the virtual cursor will be left at (\var{r}, \var{c}).
\seealso{SLsmg_write_char, SLsmg_set_color}
\done



\function{SLsmg_set_char_set}
\synopsis{Turn on or off line drawing characters}
\usage{void SLsmg_set_char_set (int a);}
\description
  \var{SLsmg_set_char_set} may be used to select or deselect the line drawing
  character set as the current character set.  If \var{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.
\seealso{SLsmg_write_char, SLtt_get_terminfo}
\done


\variable{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.
\seealso{SLsmg_refresh}
\done


\function{SLsmg_suspend_smg}
\synopsis{Suspend screen management}
\usage{int SLsmg_suspend_smg (void)}
\description
  \var{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 \var{SLsmg_resume_smg} should be called after suspension.  

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

  This function is similar to \var{SLsmg_reset_smg} except that the
  state of the display prior to calling \var{SLsmg_suspend_smg} is saved.
\seealso{SLsmg_resume_smg, SLsmg_reset_smg}
\done


\function{SLsmg_resume_smg}
\synopsis{Resume screen management}
\usage{int SLsmg_resume_smg (void)}
\description
  \var{SLsmg_resume_smg} should be called after
  \var{SLsmg_suspend_smg} to redraw the display exactly like it was
  before \var{SLsmg_suspend_smg} was called.  It returns zero upon
  success, or \-1 upon error.
\seealso{SLsmg_suspend_smg}
\done


\function{SLsmg_erase_eol}
\synopsis{Erase to the end of the row}
\usage{void SLsmg_erase_eol (void);}
\description
  \var{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.
\seealso{SLsmg_gotorc, SLsmg_erase_eos, SLsmg_fill_region}
\done


\function{SLsmg_gotorc}
\synopsis{Move the virtual cursor}
\usage{void SLsmg_gotorc (int r, int c)}
\description
  The \var{SLsmg_gotorc} function moves the virtual cursor to the row
  \var{r} and column \var{c}.  The first row and first column is
  specified by \exmp{r = 0} and \exmp{c = 0}.
\seealso{SLsmg_refresh}
\done


\function{SLsmg_erase_eos}
\synopsis{Erase to the end of the screen}
\usage{void SLsmg_erase_eos (void);}
\description
  The \var{SLsmg_erase_eos} is like \var{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.
\seealso{SLsmg_erase_eol}
\done


\function{SLsmg_reverse_video}
\synopsis{Set the current color to 1}
\usage{void SLsmg_reverse_video (void);}
\description
  This function is nothing more than \exmp{SLsmg_set_color(1)}.  
\seealso{SLsmg_set_color}
\done


\function{SLsmg_set_color (int)}
\synopsis{Set the current color}
\usage{void SLsmg_set_color (int c);}
\description
  \var{SLsmg_set_color} is used to set the current color.  The
  parameter \var{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
  \var{SLtt_set_color} function.
\example
  This example defines color \exmp{7} to be green foreground on black
  background and then displays some text in this color:
#v+
      SLtt_set_color (7, NULL, "green", "black");
      SLsmg_set_color (7);
      SLsmg_write_string ("Hello");
      SLsmg_refresh ();
#v-
\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 \var{SLsmg}
  routines.  The lower level \var{SLtt} interface converts the color
  descriptors to actual colors.  Thus
#v+
      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 ();
#v-
  will result in \exmp{"hello"} displayed in red on blue and \em{not}
  green on black.
\seealso{SLtt_set_color, SLtt_set_color_object}
\done


\function{SLsmg_normal_video}
\synopsis{Set the current color to 0}
\usage{void SLsmg_normal_video (void);}
\description
  \var{SLsmg_normal_video} sets the current color descriptor to \var{0}.
\seealso{SLsmg_set_color}
\done


\function{SLsmg_printf}
\synopsis{Format a string on the virtual display}
\usage{void SLsmg_printf (char *fmt, ...)}
\description
  \var{SLsmg_printf} format a \var{printf} style variable argument
  list and writes it on the virtual display.  The virtual cursor will
  be moved to the end of the string.
\seealso{SLsmg_write_string, SLsmg_vprintf}
\done


\function{SLsmg_vprintf}
\synopsis{Format a string on the virtual display}
\usage{void SLsmg_vprintf (char *fmt, va_list ap)}
\description
  \var{SLsmg_vprintf} formats a string in the manner of \em{vprintf}
  and writes the result to the display.  The virtual cursor is
  advanced to the end of the string.
\seealso{SLsmg_write_string, SLsmg_printf}
\done


\function{SLsmg_write_string}
\synopsis{Write a character string on the display }
\usage{void SLsmg_write_string (char *s)}
\description
  The function \var{SLsmg_write_string} displays the string \var{s} on
  the virtual display at the current position and moves the position
  to the end of the string.
\seealso{SLsmg_printf, SLsmg_write_nstring}
\done


\function{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
  \var{SLsmg_write_nstring} writes the first \var{n} characters of
  \var{s} to this virtual display.  If the length of the string
  \var{s} is less than \var{n}, the spaces will used until
  \var{n} characters have been written.  \var{s} can be \var{NULL}, in
  which case \var{n} spaces will be written.
\seealso{SLsmg_write_string, SLsmg_write_nchars}
\done


\function{SLsmg_write_char}
\synopsis{Write a character to the virtual display}
\usage{void SLsmg_write_char (char ch);}
\description
  \var{SLsmg_write_char} writes the character \var{ch} to the virtual
  display.
\seealso{SLsmg_write_nchars, SLsmg_write_string}
\done


\function{SLsmg_write_nchars}
\synopsis{Write n characters to the virtual display}
\usage{void SLsmg_write_nchars (char *s, unsigned int n);}
\description
  \var{SLsmg_write_nchars} writes at most \var{n} characters from the
  string \var{s} to the display.  If the length of \var{s} is less
  than \var{n}, the whole length of the string will get written.
  
  This function differs from \var{SLsmg_write_nstring} in that
  \var{SLsmg_write_nstring} will pad the string to write exactly
  \var{n} characters.  \var{SLsmg_write_nchars} does not perform any
  padding.
\seealso{SLsmg_write_nchars, SLsmg_write_nstring}
\done


\function{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)}
#v+
    char *s
    int r, c
    unsigned int nr, nc
    int fill
#v-
\description
  \var{SLsmg_write_wrapped_string} writes the string \var{s} to the
  virtual display.  The string will be confined to the rectangular
  region whose upper right corner is at row \var{r} and column \var{c},
  and consists of \var{nr} rows and \var{nc} columns.  The string will
  be wrapped at the boundaries of the box.  If \var{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.
\seealso{SLsmg_write_string}
\done


\function{SLsmg_cls}
\synopsis{Clear the virtual display}
\usage{void SLsmg_cls (void)}
\description
  \var{SLsmg_cls} erases the virtual display using the current color.
  This will cause the physical display to get cleared the next time
  \var{SLsmg_refresh} is called.
\notes
  This function is not the same as
#v+
     SLsmg_gotorc (0,0); SLsmg_erase_eos ();
#v-
  since these statements do not guarantee that the physical screen
  will get cleared.
\seealso{SLsmg_refresh, SLsmg_erase_eos}
\done


\function{SLsmg_refresh}
\synopsis{Update physical screen}
\usage{void SLsmg_refresh (void)}
\description
  The \var{SLsmg_refresh} function updates the physical display to
  look like the virtual display.
\seealso{SLsmg_suspend_smg, SLsmg_init_smg, SLsmg_reset_smg}
\done


\function{SLsmg_touch_lines}
\synopsis{Mark lines on the virtual display for redisplay}
\usage{void SLsmg_touch_lines (int r, unsigned int nr)}
\description
  \var{SLsmg_touch_lines} marks the \var{nr} lines on the virtual
  display starting at row \var{r} for redisplay upon the next call to
  \var{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 \var{SLsmg} screen management routines.
  This function is provided only for curses compatibility.
\seealso{SLsmg_refresh}
\done

\function{SLsmg_init_smg}
\synopsis{Initialize the \var{SLsmg} routines}
\usage{int SLsmg_init_smg (void)}
\description
  The \var{SLsmg_init_smg} function initializes the \var{SLsmg} screen
  management routines.   Specifically, this function allocates space
  for the virtual display and calls \var{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 \var{SLtt} routines are initialized via
  \var{SLtt_get_terminfo} before calling \var{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.
\seealso{SLsmg_reset_smg}
\done


\function{SLsmg_reset_smg}
\synopsis{Reset the \var{SLsmg} routines}