6. Keyboard Interface

S-Lang's keyboard interface has been designed to allow an application to read keyboard input from the user in a system-independent manner. The interface consists of a set of low routines for reading single character data as well as a higher level interface (SLkp) which utilize S-Lang's keymap facility for reading multi-character sequences.

To initialize the interface, one must first call the function SLang_init_tty. Before exiting the program, the function SLang_reset_tty must be called to restore the keyboard interface to its original state. Once initialized, the low-level SLang_getkey function may be used to read single keyboard characters from the terminal. An application using the higher-level SLkp interface will read charcters using the SLkp_getkey function.

In addition to these basic functions, there are also functions to ``unget'' keyboard characters, flush the input, detect pending-input with a timeout, etc. These functions are defined below.

6.1 Initializing the Keyboard Interface

The function 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:

      int SLang_init_tty (int abort_char, int flow_ctrl, int opost);

The first parameter, abort_char, is used to specify the interrupt character (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, 34 should be used to make Ctrl-G generate an interrupt signal since 34 is the scan code for G. On other systems, the value of abort_char will simply be the ascii value of the control character that will be used to generate the interrupt signal, e.g., 7 for Ctrl-G. If -1 is passed, the interrupt character will not be changed.

Pressing the interrupt character specified by the first argument will generate a signal (SIGINT) that may or not be caught by the application. It is up to the application to catch this signal. S-Lang provides the function 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. If the value is positive, flow control will be disabled. Disabling flow control is necessary to pass certain characters to the application (e.g., Ctrl-S and Ctrl-Q). Otherwise, the value is negative and the flow control behavior will be inherited from the terminal. The latter interpretation was added to version 2.3.0 of the library; earlier versions disabled flow control for both positive and negative values of this parameter. For some systems such as MSDOS, this parameter is meaningless.

The third parameter, opost, is used to turn output processing on or off. If opost is zero, output processing is not turned on otherwise, output processing is turned on.

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

Example:

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

For MSDOS systems, use the scan code 34 instead of 7 for Ctrl-G

6.2 Resetting the Keyboard Interface

The function SLang_reset_tty must be called to reset the terminal to the state it was in before the call to SLang_init_tty. The prototype for this function is:

      void SLang_reset_tty (void);

6.3 Initializing the SLkp Routines

Extra initialization of the higher-level SLkp functions are required because they are layered on top of the lower level routines. Since the SLkp_getkey function is able to process function and arrow keys in a terminal independent manner, it is necessary to call the 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 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:

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

It is important to check the return status of the SLkp_init function which can failed if it cannot allocate enough memory for the keymap.

6.4 Setting the Interrupt Handler

The function SLang_set_abort_signal may be used to associate an interrupt handler with the interrupt character that was previously specified by the SLang_init_tty function call. The prototype for this function is:

      void SLang_set_abort_signal (void (*)(int));

      static void default_sigint (int sig)
      {
        SLsignal_intr (SIGINT, default_sigint);
        SLKeyBoard_Quit = 1;
        if (SLang_Ignore_User_Abort == 0)
          SLang_set_error (SL_UserBreak_Error);
      }

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 int 9h is hooked).

6.5 Reading Keyboard Input with SLang_getkey

After initializing the keyboard via SLang_init_tty, the S-Lang function SLang_getkey may be used to read characters from the terminal interface. In addition, the function SLang_input_pending may be used to determine whether or not keyboard input is available to be read.

These functions have prototypes:

      unsigned int SLang_getkey (void);
      int SLang_input_pending (int tsecs);

The SLang_getkey function waits until input is available to be read. The 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 10. Passing a value of zero causes the function to return right away. 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 Ctrl-G or until 5 seconds have gone by with no input:

      #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_get_error () == SL_UserBreak_Error)
                {
                   fputs ("Ctrl-G pressed!  Bye\n", stdout);
                   break;
                }
              putc ((int) ch, stdout);
           }
         SLang_reset_tty ();
         return 0;
      }

6.6 Reading Keyboard Input with SLkp_getkey

Unlike the low-level function SLang_getkey, the SLkp_getkey function can read a multi-character sequence associated with function keys. The SLkp_getkey function uses SLang_getkey and S-Lang's keymap facility to process escape sequences. It returns a single integer which describes the key that was pressed:

      int SLkp_getkey (void);

For single character input such as generated by the a key on the keyboard, the function returns the character that was generated, e.g., 'a'. For single characters, 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 slang.h 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.

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

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

6.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 the libraries error state set to SL_UserBreak_Error.

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.