Overview
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.
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.
%Although the S-Lang keyboard interface has been
%designed to be as system independent as possible, there are semantic
% differences.
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 non-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.
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.
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.
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).
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;
}
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.
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;
}
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
.