cslang.tm

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

  ``unget'' keyboard characters, flush the input, detect pending-input
  with a timeout, etc. These functions are defined below.

#%}}}

\sect{Initializing the Keyboard Interface} #%{{{

  The function \verb{SLang_init_tty} must be called to initialize the
  terminal for single character input.  This puts the terminal in a mode
  usually referred to as ``raw'' mode.  
  
  The prototype for the function is:
#v+ 
      int SLang_init_tty (int abort_char, int flow_ctrl, int opost);
#v-
  It takes three parameters that are used to specify how the terminal is to
  be initialized.
#%+
  Although the \slang keyboard interface has been
  %designed to be as system independent as possible, there are semantic
  % differences.
#%-

  The first parameter, \verb{abort_char}, is used to specify the interrupt
  character (\tt{SIGINT}).  Under MSDOS, this value corresponds to the scan
  code of the character that will be used to generate the interrupt.  For
  example, under MSDOS, \verb{34} should be used to make \key{Ctrl-G} generate an
  interrupt signal since 34 is the scan code for \key{G}.  On other
  systems, the value of \verb{abort_char} will simply be the ascii value of
  the control character that will be used to generate the interrupt signal,
  e.g., \tt{7} for \key{Ctrl-G}.  If \verb{-1} is passed, the interrupt
  character will not be changed.

  Pressing the interrupt character specified by the first argument will
  generate a signal (\tt{SIGINT}) that may or not be caught by the
  application.  It is up to the application to catch this signal.  \slang
  provides the function \verb{Slang_set_abort_signal} to make it easy to
  facilitate this task.

  The second parameter is used to specify whether or not flow control should
  be used.  If this parameter is zero, flow control is enabled otherwise
  it is disabled.  Disabling flow control is necessary to pass certain
  characters to the application (e.g., \key{Ctrl-S} and \key{Ctrl-Q}).
  For some systems such as MSDOS, this parameter is meaningless.
  
  The third parameter, \verb{opost}, is used to turn output processing on or
  off.  If \verb{opost} is zero, output processing is \em{not} turned on
  otherwise, output processing is turned on.

  The \verb{SLang_init_tty} function returns -1 upon failure.  In addition,
  after it returns, the \slang global variable \verb{SLang_TT_Baud_Rate}
  will be set to the baud rate of the terminal if this value can be
  determined.

  Example:
#v+   
      if (-1 == SLang_init_tty (7, 0, 0))  /* For MSDOS, use 34 as scan code */
        {
          fprintf (stderr, "Unable to initialize the terminal.\n");
          exit (1);
        }
      SLang_set_abort_signal (NULL);
#v-
   Here the terminal is initialized such that flow control and output
   processing are turned off.  In addition, the character
   \key{Ctrl-G}\footnote{For MSDOS systems, use the \em{scan code} 34
   instead of 7 for \key{Ctrl-G}} has been specified to be the interrupt
   character.  The function \verb{SLang_set_abort_signal} is used to
   install the default \slang interrupt signal handler.

#%}}}

\sect{Resetting the Keyboard Interface} #%{{{

  The function \verb{SLang_reset_tty} must be called to reset the terminal
  to the state it was in before the call to \verb{SLang_init_tty}.  The
  prototype for this function is:
#v+
      void SLang_reset_tty (void);
#v-
  Usually this function is only called before the program exits.  However,
  if the program is suspended it should also be called just before suspension.
  
#%}}}

\sect{Initializing the \grp{SLkp} Routines} #%{{{

  Extra initialization of the higher-level \grp{SLkp} functions are
  required because they are layered on top of the lower level
  routines.  Since the \verb{SLkp_getkey} function is able to process
  function and arrow keys in a terminal independent manner, it is
  necessary to call the \verb{SLtt_get_terminfo} function to get
  information about the escape character sequences that the terminal's
  function keys send.  Once that information is available, the
  \verb{SLkp_init} function can construct the proper keymaps to
  process the escape sequences.
  
  This part of the initialization process for an application using
  this interface will look something like:

#v+ 
      SLtt_get_terminfo ();
      if (-1 == SLkp_init ())
        {
           SLang_doerror ("SLkp_init failed.");
           exit (1);
        }
      if (-1 == SLang_init_tty (-1, 0, 1))
        {
           SLang_doerror ("SLang_init_tty failed.");
           exit (1);
        }
#v- 

  It is important to check the return status of the \verb{SLkp_init}
  function which can failed if it cannot allocate enough memory for
  the keymap.
 
#%}}}

\sect{Setting the Interrupt Handler} #%{{{

  The function \verb{SLang_set_abort_signal} may be used to associate an
  interrupt handler with the interrupt character that was previously
  specified by the \verb{SLang_init_tty} function call.  The prototype for
  this function is:
#v+
      void SLang_set_abort_signal (void (*)(int));
#v-
  This function returns nothing and takes a single parameter which is a
  pointer to a function taking an integer value and returning
  \verb{void}.  If a \verb{NULL} pointer is passed, the default \slang
  interrupt handler will be used. The \slang default interrupt handler
  under Unix looks like:
#v+
      static void default_sigint (int sig)
      {
        SLsignal_intr (SIGINT, default_sigint);
        SLKeyBoard_Quit = 1;
        if (SLang_Ignore_User_Abort == 0) SLang_Error = USER_BREAK;
      }
#v- 
  It simply sets the global variable \verb{SLKeyBoard_Quit} to one and
  if the variable \verb{SLang_Ignore_User_Abort} is non-zero,
  \verb{SLang_Error} is set to indicate a user break condition.  (The
  function \verb{SLsignal_intr} is similar to the standard C
  \verb{signal} function \em{except that it will interrupt system
  calls}.  Some may not like this behavior and may wish to call
  this \verb{SLang_set_abort_signal} with a different handler.)

  Although the function expressed above is specific to Unix, the
  analogous routines for other operating systems are equivalent in
  functionality even though the details of the implementation may vary
  drastically (e.g., under MSDOS, the hardware keyboard interrupt
  \verb{int 9h} is hooked).

#%}}}

\sect{Reading Keyboard Input with SLang_getkey} #%{{{

  After initializing the keyboard via \verb{SLang_init_tty},
  the \slang function \verb{SLang_getkey} may be used to read
  characters from the terminal interface.  In addition, the function
  \verb{SLang_input_pending} may be used to determine whether or not
  keyboard input is available to be read.

  These functions have prototypes:
#v+   
      unsigned int SLang_getkey (void);
      int SLang_input_pending (int tsecs);
#v-
  The \verb{SLang_getkey} function returns a single character from the
  terminal.  Upon failure, it returns \verb{0xFFFF}.  If the interrupt
  character specified by the \verb{SLang_init_tty} function is pressed
  while this function is called, the function will return the value of the
  interrupt character and set the \slang global variable
  \verb{SLKeyBoard_Quit} to a non-zero value.  In addition, if the default
  \slang interrupt handler has been specified by a \verb{NULL} argument to
  the \verb{SLang_set_abort_signal} function, the global variable
  \verb{SLang_Error} will be set to \verb{USER_BREAK} \em{unless} the
  variable \verb{SLang_Ignore_User_Abort} is non-zero.

  The \verb{SLang_getkey} function waits until input is available to be
  read.  The \verb{SLang_input_pending} function may be used to determine
  whether or not input is ready.  It takes a single parameter that indicates
  the amount of time to wait for input before returning with information
  regarding the availability of input.  This parameter has units of one
  tenth (1/10) of a second, i.e., to wait one second, the value of the
  parameter should be \tt{10}.  Passing a value of zero causes the function
  to return right away.  \verb{SLang_input_pending} returns a positive
  integer if input is available or zero if input is not available.  It will
  return -1 if an error occurs.

  Here is a simple example that reads keys from the terminal until one
  presses \key{Ctrl-G} or until 5 seconds have gone by with no input:
#v+ 
      #include <stdio.h>
      #include "slang.h"
      int main ()
      {
         int abort_char = 7;  /* For MSDOS, use 34 as scan code */
         unsigned int ch;
         
         if (-1 == SLang_init_tty (abort_char, 0, 1))
           {
              fprintf (stderr, "Unable to initialize the terminal.\n");
              exit (-1);
           }
         SLang_set_abort_signal (NULL);
         while (1)
           {
              fputs ("\nPress any key.  To quit, press Ctrl-G: ", stdout);
              fflush (stdout);
              if (SLang_input_pending (50) == 0)  /* 50/10 seconds */
                {
                   fputs ("Waited too long! Bye\n", stdout);
                   break;
                }
              
              ch = SLang_getkey ();
              if (SLang_Error == USER_BREAK)
                {
                   fputs ("Ctrl-G pressed!  Bye\n", stdout);
                   break;
                }
              putc ((int) ch, stdout);
           }
         SLang_reset_tty ();
         return 0;
      }
#v- 


#%}}}

\sect{Reading Keyboard Input with SLkp_getkey} #%{{{

  Unlike the low-level function \verb{SLang_getkey}, the
  \verb{SLkp_getkey} function can read a multi-character sequence
  associated with function keys.  The \verb{SLkp_getkey} function uses
  \verb{SLang_getkey} and \slang's keymap facility to process escape
  sequences.  It returns a single integer which describes the key that
  was pressed:
#v+ 
      int SLkp_getkey (void);
#v-
  That is, the \verb{SLkp_getkey} function simple provides a mapping
  between keys and integers.  In this context the integers are called
  \em{keysyms}.
  
  For single character input such as generated by the \key{a} key on
  the keyboard, the function returns the character that was generated,
  e.g., \verb{'a'}.  For single characters, \verb{SLkp_getkey} will
  always return an keysym whose value ranges from 0 to 256. For
  keys that generate multiple character sequences, e.g., a function or
  arrow key, the function returns an keysym whose value is greater
  that 256.  The actual values of these keysyms are represented as
  macros defined in the \file{slang.h} include file.  For example, the
  up arrow key corresponds to the keysym whose value is
  \verb{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
  \verb{SL_KEY_ERR} will be returned.
  
  Here is an example of how \verb{SLkp_getkey} may be used by a file
  viewer:
#v+ 
      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 ();
        }
#v- 
   
   Unlike its lower-level counterpart, \verb{SLang_getkey}, there do
   not yet exist any functions in the library that are capable of
   ``ungetting'' keysyms.  In particular, the \verb{SLang_ungetkey}
   function will not work.
   
#%}}}

\sect{Buffering Input} #%{{{

  \slang has several functions pushing characters back onto the
  input stream to be read again later by \verb{SLang_getkey}.  It
  should be noted that none of the above functions are designed to
  push back keysyms read by the \verb{SLkp_getkey} function.  These
  functions are declared as follows:
#v+
      void SLang_ungetkey (unsigned char ch);
      void SLang_ungetkey_string (unsigned char *buf, int buflen);
      void SLang_buffer_keystring (unsigned char *buf, int buflen);
#v-

  \verb{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
  \verb{SLang_getkey} will return this character.  This function may be used
  to \em{peek} at the character to be read by first reading it and then
  putting it back.

  \verb{SLang_ungetkey_string} has the same function as
  \verb{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, \verb{SLang_buffer_keystring} can
  handle more than one charater but unlike the other two, it places the
  characters at the \em{end} of the keyboard buffer instead of at the
  beginning.

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

  Finally, the \slang keyboard interface includes the function
  \verb{SLang_flush_input} with prototype
#v+
      void SLang_flush_input (void);
#v- 
  It may be used to discard \em{all} input.
  
  Here is a simple example that looks to see what the next key to be read is
  if one is available:
#v+ 
      int peek_key ()
      {
         int ch;
         if (SLang_input_pending (0) == 0) return -1;
         ch = SLang_getkey ();
         SLang_ungetkey (ch);
         return ch;
      }
#v-       


#%}}}