S-Lang Library C Programmer's Guide, V1.4.2: Keyboard Interface

Next Previous Contents

## 4. 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 simgle keyboard characters from the terminal. An application using the 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.

## 4.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);

> `

It takes three parameters that are used to specify how the terminal is to be initialized.

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 otherwise it is disabled. Disabling flow control is necessary to pass certain characters to the application (e.g., `Ctrl-S` and `Ctrl-Q`). 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);

> `

Here the terminal is initialized such that flow control and output processing are turned off. In addition, the character `Ctrl-G`

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

has been specified to be the interrupt character. The function `SLang_set_abort_signal` is used to install the default S-Lang interrupt signal handler.

## 4.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);

> `

Usually this function is only called before the program exits. However, if the program is suspended it should also be called just before suspension.

## 4.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.

## 4.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));

> `

This function returns nothing and takes a single parameter which is a pointer to a function taking an integer value and returning `void`. If a `NULL` pointer is passed, the default S-Lang interrupt handler will be used. The S-Lang default interrupt handler under Unix looks like:

> `

>           static void default_sigint (int sig)
>           {
>             SLsignal_intr (SIGINT, default_sigint);
>             SLKeyBoard_Quit = 1;
>             if (SLang_Ignore_User_Abort == 0) SLang_Error = USER_BREAK;
>           }

> `

It simply sets the global variable `SLKeyBoard_Quit` to one and if the variable `SLang_Ignore_User_Abort` is non-zero, `SLang_Error` is set to indicate a user break condition. (The function `SLsignal_intr` is similar to the standard C `signal` function except that it will interrupt system calls. Some may not like this behavior and may wish to call this `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 `int 9h` is hooked).

## 4.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 returns a single character from the terminal. Upon failure, it returns `0xFFFF`. If the interrupt character specified by the `SLang_init_tty` function is pressed while this function is called, the function will return the value of the interrupt character and set the S-Lang global variable `SLKeyBoard_Quit` to a non-zero value. In addition, if the default S-Lang interrupt handler has been specified by a `NULL` argument to the `SLang_set_abort_signal` function, the global variable `SLang_Error` will be set to `USER_BREAK` unless the variable `SLang_Ignore_User_Abort` is non-zero.

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

> `

## 4.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);

> `

That is, the `SLkp_getkey` function simple provides a mapping between keys and integers. In this context the integers are called keysyms.

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.

## 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`.

Next Previous Contents