cslang.txt

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

  include file.  For example, the up arrow key corresponds to the keysym
  whose value is SL_KEY_UP.

  Since it is possible for the user to enter a character sequence that
  does not correspond to any key.  If this happens, the special keysym
  SL_KEY_ERR will be returned.

  Here is an example of how SLkp_getkey may be used by a file viewer:


             switch (SLkp_getkey ())
               {
                  case ' ':
                  case SL_KEY_NPAGE:
                     next_page ();
                     break;
                  case 'b':
                  case SL_KEY_PPAGE:
                     previous_page ();
                     break;
                  case '\r':
                  case SL_KEY_DOWN:
                     next_line ();
                     break;
                      .
                      .
                  case SL_KEY_ERR:
                  default:
                     SLtt_beep ();
               }



  Unlike its lower-level counterpart, SLang_getkey, there do not yet
  exist any functions in the library that are capable of ``ungetting''
  keysyms.  In particular, the SLang_ungetkey function will not work.



  4.7.  Buffering Input



  S-Lang has several functions pushing characters back onto the input
  stream to be read again later by SLang_getkey.  It should be noted
  that none of the above functions are designed to push back keysyms
  read by the SLkp_getkey function.  These functions are declared as
  follows:


             void SLang_ungetkey (unsigned char ch);
             void SLang_ungetkey_string (unsigned char *buf, int buflen);
             void SLang_buffer_keystring (unsigned char *buf, int buflen);



  SLang_ungetkey is the most simple of the three functions.  It takes a
  single character a pushes it back on to the input stream.  The next
  call to SLang_getkey will return this character.  This function may be
  used to peek at the character to be read by first reading it and then
  putting it back.
  SLang_ungetkey_string has the same function as SLang_ungetkey except
  that it is able to push more than one character back onto the input
  stream.  Since this function can push back null (ascii 0) characters,
  the number of characters to push is required as one of the parameters.

  The last of these three functions, SLang_buffer_keystring can handle
  more than one charater but unlike the other two, it places the
  characters at the end of the keyboard buffer instead of at the
  beginning.

  Note that the use of each of these three functions will cause
  SLang_input_pending to return right away with a non-zero value.

  Finally, the S-Lang keyboard interface includes the function
  SLang_flush_input with prototype


             void SLang_flush_input (void);



  It may be used to discard all input.

  Here is a simple example that looks to see what the next key to be
  read is if one is available:


             int peek_key ()
             {
                int ch;
                if (SLang_input_pending (0) == 0) return -1;
                ch = SLang_getkey ();
                SLang_ungetkey (ch);
                return ch;
             }



  4.8.  Global Variables


  Although the following S-Lang global variables have already been
  mentioned earlier, they are gathered together here for completeness.

  int SLang_Ignore_User_Abort; If non-zero, pressing the interrupt
  character will not result in SLang_Error being set to USER_BREAK.

  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 SLang_getkey is called, the interrupt character will be
  returned from SLang_getkey.

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



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



  5.4.1.  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 vari-
  able r will have the value of the previous row origin.


  5.4.2.  Writing to the Display


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

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


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


  o  Control characters are displayed in a two character sequence
     representation with ^ as the first character.  That is, Ctrl-X is
     output as ^X.


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


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


  5.4.4.  Setting Character Attributes


  Character attributes define the visual characteristics the character
  possesses when it is d