cslang.tm

来自「一个C格式的脚本处理函数库源代码,可让你的C程序具有执行C格式的脚本文件」· TM 代码 · 共 1,759 行 · 第 1/5 页

\sect{Global Variables} #%{{{
  Although the following \slang global variables have already been
  mentioned earlier, they are gathered together here for completeness.
  
  \verb{int SLang_Ignore_User_Abort;}
  If non-zero, pressing the interrupt character will not result in
  \verb{SLang_Error} being set to \verb{USER_BREAK}.

  \verb{volatile int SLKeyBoard_Quit;}
  This variable is set to a non-zero value when the interrupt
  character is pressed. If the interrupt character is pressed when
  \verb{SLang_getkey} is called, the interrupt character will be
  returned from \verb{SLang_getkey}.

  \verb{int SLang_TT_Baud_Rate;} 
  On systems which support it, this variable is set to the value of the
  terminal's baud rate after the call to \verb{SLang_init_tty}.

#%}}}

#%}}}

\chapter{Screen Management} #%{{{

  The \slang library provides two interfaces to terminal independent
  routines for manipulating the display on a terminal.  The highest level
  interface, known as the \verb{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 \verb{curses} library.  The lowest level interface, or the
  \verb{SLtt}
  interface, is used by the \verb{SLsmg} routines to actually perform the
  task of writing to the display.  This interface is discussed in another
  section.  Like the keyboard routines, the \verb{SLsmg} routines are
  \em{platform independent} and work the same on MSDOS, OS/2, Unix, and VMS.

  The screen management, or \verb{SLsmg}, routines are initialized by
  function \verb{SLsmg_init_smg}.  Once initialized, the application uses
  various \verb{SLsmg} functions to write to a \em{virtual} display.  This does
  not cause the \em{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 \verb{SLsmg_refresh}.  Before exiting, the
  application using these routines is required to call
  \verb{SLsmg_reset_smg} to reset the display system.
  
  The following subsections explore \slang's screen management system in
  greater detail.
  
\sect{Initialization}

  The function \verb{SLsmg_init_smg} must be called before any other
  \verb{SLsmg} function can be used.  It has the simple prototype:
#v+
      int SLsmg_init_smg (void);
#v- 
  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 \em{physical} display.  For these reasons, the lower level \verb{SLtt} routines
  come into play.  In particular, before the first call to
  \verb{SLsmg_init_smg}, the application is required to call the function
  \verb{SLtt_get_terminfo} before calling \verb{SLsmg_init_smg}.

  The \verb{SLtt_get_terminfo} function sets the global variables
  \verb{SLtt_Screen_Rows} and \verb{SLtt_Screen_Cols} to the values
  appropriate for the terminal.  It does this by calling the
  \verb{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 \verb{SLtt_get_screen_size} function
  whenever the display size changes, e.g., in response to a
  \verb{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.

\sect{Resetting SLsmg}  

  Before the program exits or suspends, the function
  \verb{SLsmg_reset_tty}
  should be called to shutdown the display system.  This function has the
  prototype
#v+ 
      void SLsmg_reset_smg (void);
#v-
  This will deallocate any memory allocated for the virtual screen and
  reset the terminal's display.
  
  Basically, a program that uses the \verb{SLsmg} screen management functions
  and \slang's keyboard interface will look something like:
#v+  
      #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;
      }
#v-
  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 \verb{SLsmg} functions will be introduced which may be used
  to make this simple program do much more.

\sect{Handling Screen Resize Events}
  The function \verb{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 \verb{SIGWINCH} signal.  To
  properly handle this signal, the \verb{SLsmg} routines must be
  reinitialized to use the new display size.  This may be accomplished
  by calling \verb{SLtt_get_screen_size} to get the new size, followed by
  \verb{SLsmg_reinit_smg} to reinitialize the \verb{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:
#v+
     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;
     }
#v-    
  

\sect{SLsmg Functions} #%{{{

  In the previous sections, functions for initializing and shutting down the
  \verb{SLsmg} routines were discussed.  In this section, the rest of the
  \verb{SLsmg} functions are presented.  These functions act only on the 
  \em{virtual} display.  The \em{physical} display is updated when the
  \verb{SLsmg_refresh} function is called and \em{not until that time}.
  This function has the simple prototype:
#v+   
     void SLsmg_refresh (void);
#v- 
  
\sect1{Positioning the cursor}

  The \verb{SLsmg_gotorc} function is used to position the cursor at a given
  row and column.  The prototype for this function is:
#v+ 
      void SLsmg_gotorc (int row, int col);
#v-
  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
  \verb{row = 0} and the first column corresponds to \verb{col = 0}.  The last
  row of the screen is given by \verb{row = SLtt_Screen_Rows - 1}.
  
  It is possible to change the origin of the coordinate system by using the
  function \verb{SLsmg_set_screen_start} with prototype:
#v+   
     void SLsmg_set_screen_start (int *r, int *c);
#v-
  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
  \verb{NULL}
  pointer may be passed to indicate that the origin is to be set to its
  initial value of 0.  For example,
#v+ 
      int r = 10;
      SLsmg_set_screen_start (&r, NULL);
#v-
  sets the origin to (10, 0) and after the function returns, the variable
  \verb{r} will have the value of the previous row origin.

\sect1{Writing to the Display}
  
  \verb{SLsmg} has several routines for outputting text to the virtual
  display.  The following points should be understood:
\begin{itemize}   
\item 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.
      
\item Text does \em{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.
      
\item Control characters are displayed in a two character sequence
      representation with \verb{^} as the first character.  That is,
      \key{Ctrl-X} is output as \verb{^X}.
      
\item The newline character does \em{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.
\end{itemize} 

  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.

  \verb{void SLsmg_write_char (char ch);}
  Write a single character to the virtual display.
  
  \verb{void SLsmg_write_nchars (char *str, int len);}
  Write \verb{len} characters pointed to by \verb{str} to the virtual display. 

  \verb{void SLsmg_write_string (char *str);} 
  Write the null terminated string given by pointer \verb{str} to the virtual
  display.  This function is a wrapper around \verb{SLsmg_write_nchars}.

  \verb{void SLsmg_write_nstring (char *str, int n);}
  Write the null terminated string given by pointer \verb{str} to the virtual
  display.  At most, only \verb{n} characters are written.  If the length of
  the string is less than \verb{n}, then the string will be padded with blanks.
  This function is a wrapper around \verb{SLsmg_write_nchars}.
  
  \verb{void SLsmg_printf (char *fmt, ...);}
  This function is similar to \verb{printf} except that it writes to the
  \verb{SLsmg} virtual display.
  
  \verb{void SLsmg_vprintf (char *, va_list);}
  Like \verb{SLsmg_printf} but uses a variable argument list.

\sect1{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)
  
  \verb{void SLsmg_erase_eol (void);}
  Erase line from current position to the end of the line.
  
  \verb{void SLsmg_erase_eos (void);}
  Erase from the current position to the end of the screen.

  \verb{void SLsmg_cls (void);}
  Clear the entire virtual display.

\sect1{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 \verb{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 \verb{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 \verb{SLsmg}, the integer is
  simply called an \em{object}.

  For example, the menu bar might be associated with the object \verb{1}, the
  drop down menu could be object \verb{2}, the shadow could be object
  \verb{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\footnote{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 \em{other} objects
  that have not explicitly been given an object number.  \verb{SLsmg}, or
  more precisely \verb{SLtt}, refers to the attributes of this special object
  as the \em{default} or \em{normal} attributes.

  The \verb{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 \verb{SLtt} routines.  Hence, to map an object to the
  actual set of attributes requires a call to any of the following
  \verb{SLtt}
  routines:
#v+   
     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);
#v-
  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
  \verb{SLtt} interface.

  The \verb{SLtt_set_color} function takes four parameters.  The first
  parameter, \verb{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, \verb{fg}
  and \verb{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:
#v+
     "black"                "gray"
     "red"                  "brightred"
     "green"                "brightgreen"
     "brown"                "yellow"
     "blue"                 "brightblue"
     "magenta"              "brightmagenta"
     "cyan"                 "brightcyan"
     "lightgray"            "white"
#v- 
  The value of the foreground parameter \verb{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\footnote{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 \slang global
  variable \verb{SLtt_Use_Ansi_Colors} is non-zero, the terminal is
  assumed to be a color terminal.  The \verb{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 \verb{SLtt_get_terminfo}
  routine will check whether or not the environment variable
  \verb{COLORTERM} exists.  If it exists, the terminal will be assumed
  to support ANSI colors and \verb{SLtt_Use_Ansi_Colors} will be set to one.
  Nevertheless, the application