<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Library C Programmer's Guide, V1.4.2: Keyboard Interface</TITLE>
<LINK HREF="cslang-5.html" REL=next>
<LINK HREF="cslang-3.html" REL=previous>
<LINK HREF="cslang.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="cslang-5.html">Next</A>
<A HREF="cslang-3.html">Previous</A>
<A HREF="cslang.html#toc4">Contents</A>
<HR>
<H2><A NAME="s4">4. Keyboard Interface</A></H2>
<P>
<P>
<P>
<P><B>S-Lang</B>'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 (<CODE>SLkp</CODE>) which utilize <B>S-Lang</B>'s keymap facility
for reading multi-character sequences.
<P>To initialize the interface, one must first call the function
<CODE>SLang_init_tty</CODE>. Before exiting the program, the function
<CODE>SLang_reset_tty</CODE> must be called to restore the keyboard
interface to its original state. Once initialized, the low-level
<CODE>SLang_getkey</CODE> function may be used to read <EM>simgle</EM>
keyboard characters from the terminal. An application using the the
higher-level <CODE>SLkp</CODE> interface will read charcters using the
<CODE>SLkp_getkey</CODE> function.
<P>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.
<P>
<P>
<H2><A NAME="ss4.1">4.1 Initializing the Keyboard Interface</A>
</H2>
<P>
<P>The function <CODE>SLang_init_tty</CODE> must be called to initialize the
terminal for single character input. This puts the terminal in a mode
usually referred to as ``raw'' mode.
<P>The prototype for the function is:
<BLOCKQUOTE><CODE>
<PRE>
int SLang_init_tty (int abort_char, int flow_ctrl, int opost);
</PRE>
</CODE></BLOCKQUOTE>
It takes three parameters that are used to specify how the terminal is to
be initialized.
%Although the <B>S-Lang</B> keyboard interface has been
%designed to be as system independent as possible, there are semantic
% differences.
<P>The first parameter, <CODE>abort_char</CODE>, is used to specify the interrupt
character (<CODE>SIGINT</CODE>). Under MSDOS, this value corresponds to the scan
code of the character that will be used to generate the interrupt. For
example, under MSDOS, <CODE>34</CODE> should be used to make <CODE>Ctrl-G</CODE> generate an
interrupt signal since 34 is the scan code for <CODE>G</CODE>. On other
systems, the value of <CODE>abort_char</CODE> will simply be the ascii value of
the control character that will be used to generate the interrupt signal,
e.g., <CODE>7</CODE> for <CODE>Ctrl-G</CODE>. If <CODE>-1</CODE> is passed, the interrupt
character will not be changed.
<P>Pressing the interrupt character specified by the first argument will
generate a signal (<CODE>SIGINT</CODE>) that may or not be caught by the
application. It is up to the application to catch this signal. <B>S-Lang</B>
provides the function <CODE>Slang_set_abort_signal</CODE> to make it easy to
facilitate this task.
<P>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., <CODE>Ctrl-S</CODE> and <CODE>Ctrl-Q</CODE>).
For some systems such as MSDOS, this parameter is meaningless.
<P>The third parameter, <CODE>opost</CODE>, is used to turn output processing on or
off. If <CODE>opost</CODE> is zero, output processing is <EM>not</EM> turned on
otherwise, output processing is turned on.
<P>The <CODE>SLang_init_tty</CODE> function returns -1 upon failure. In addition,
after it returns, the <B>S-Lang</B> global variable <CODE>SLang_TT_Baud_Rate</CODE>
will be set to the baud rate of the terminal if this value can be
determined.
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
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);
</PRE>
</CODE></BLOCKQUOTE>
Here the terminal is initialized such that flow control and output
processing are turned off. In addition, the character
<CODE>Ctrl-G</CODE>
<BLOCKQUOTE>For MSDOS systems, use the <EM>scan code</EM> 34
instead of 7 for <CODE>Ctrl-G</CODE></BLOCKQUOTE>
has been specified to be the interrupt
character. The function <CODE>SLang_set_abort_signal</CODE> is used to
install the default <B>S-Lang</B> interrupt signal handler.
<P>
<P>
<H2><A NAME="ss4.2">4.2 Resetting the Keyboard Interface</A>
</H2>
<P>
<P>The function <CODE>SLang_reset_tty</CODE> must be called to reset the terminal
to the state it was in before the call to <CODE>SLang_init_tty</CODE>. The
prototype for this function is:
<BLOCKQUOTE><CODE>
<PRE>
void SLang_reset_tty (void);
</PRE>
</CODE></BLOCKQUOTE>
Usually this function is only called before the program exits. However,
if the program is suspended it should also be called just before suspension.
<P>
<P>
<H2><A NAME="ss4.3">4.3 Initializing the <CODE>SLkp</CODE> Routines</A>
</H2>
<P>
<P>Extra initialization of the higher-level <CODE>SLkp</CODE> functions are
required because they are layered on top of the lower level
routines. Since the <CODE>SLkp_getkey</CODE> function is able to process
function and arrow keys in a terminal independent manner, it is
necessary to call the <CODE>SLtt_get_terminfo</CODE> function to get
information about the escape character sequences that the terminal's
function keys send. Once that information is available, the
<CODE>SLkp_init</CODE> function can construct the proper keymaps to
process the escape sequences.
<P>This part of the initialization process for an application using
this interface will look something like:
<P>
<BLOCKQUOTE><CODE>
<PRE>
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);
}
</PRE>
</CODE></BLOCKQUOTE>
<P>It is important to check the return status of the <CODE>SLkp_init</CODE>
function which can failed if it cannot allocate enough memory for
the keymap.
<P>
<P>
<H2><A NAME="ss4.4">4.4 Setting the Interrupt Handler</A>
</H2>
<P>
<P>The function <CODE>SLang_set_abort_signal</CODE> may be used to associate an
interrupt handler with the interrupt character that was previously
specified by the <CODE>SLang_init_tty</CODE> function call. The prototype for
this function is:
<BLOCKQUOTE><CODE>
<PRE>
void SLang_set_abort_signal (void (*)(int));
</PRE>
</CODE></BLOCKQUOTE>
This function returns nothing and takes a single parameter which is a
pointer to a function taking an integer value and returning
<CODE>void</CODE>. If a <CODE>NULL</CODE> pointer is passed, the default <B>S-Lang</B>
interrupt handler will be used. The <B>S-Lang</B> default interrupt handler
under Unix looks like:
<BLOCKQUOTE><CODE>
<PRE>
static void default_sigint (int sig)
{
SLsignal_intr (SIGINT, default_sigint);
SLKeyBoard_Quit = 1;
if (SLang_Ignore_User_Abort == 0) SLang_Error = USER_BREAK;
}
</PRE>
</CODE></BLOCKQUOTE>
It simply sets the global variable <CODE>SLKeyBoard_Quit</CODE> to one and
if the variable <CODE>SLang_Ignore_User_Abort</CODE> is non-zero,
<CODE>SLang_Error</CODE> is set to indicate a user break condition. (The
function <CODE>SLsignal_intr</CODE> is similar to the standard C
<CODE>signal</CODE> function <EM>except that it will interrupt system
calls</EM>. Some may not like this behavior and may wish to call
this <CODE>SLang_set_abort_signal</CODE> with a different handler.)
<P>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
<CODE>int 9h</CODE> is hooked).
<P>
<P>
<H2><A NAME="ss4.5">4.5 Reading Keyboard Input with SLang_getkey</A>
</H2>
<P>
<P>After initializing the keyboard via <CODE>SLang_init_tty</CODE>,
the <B>S-Lang</B> function <CODE>SLang_getkey</CODE> may be used to read
characters from the terminal interface. In addition, the function
<CODE>SLang_input_pending</CODE> may be used to determine whether or not
keyboard input is available to be read.
<P>These functions have prototypes:
<BLOCKQUOTE><CODE>
<PRE>
unsigned int SLang_getkey (void);
int SLang_input_pending (int tsecs);
</PRE>
</CODE></BLOCKQUOTE>
The <CODE>SLang_getkey</CODE> function returns a single character from the
terminal. Upon failure, it returns <CODE>0xFFFF</CODE>. If the interrupt
character specified by the <CODE>SLang_init_tty</CODE> function is pressed
while this function is called, the function will return the value of the
interrupt character and set the <B>S-Lang</B> global variable
<CODE>SLKeyBoard_Quit</CODE> to a non-zero value. In addition, if the default
<B>S-Lang</B> interrupt handler has been specified by a <CODE>NULL</CODE> argument to
the <CODE>SLang_set_abort_signal</CODE> function, the global variable
<CODE>SLang_Error</CODE> will be set to <CODE>USER_BREAK</CODE> <EM>unless</EM> the
variable <CODE>SLang_Ignore_User_Abort</CODE> is non-zero.
<P>The <CODE>SLang_getkey</CODE> function waits until input is available to be
read. The <CODE>SLang_input_pending</CODE> 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 <CODE>10</CODE>. Passing a value of zero causes the function
to return right away. <CODE>SLang_input_pending</CODE> returns a positive
integer if input is available or zero if input is not available. It will
return -1 if an error occurs.
<P>Here is a simple example that reads keys from the terminal until one
presses <CODE>Ctrl-G</CODE> or until 5 seconds have gone by with no input:
<BLOCKQUOTE><CODE>
<PRE>
#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;
}
</PRE>
</CODE></BLOCKQUOTE>
<P>
<P>
<P>
<H2><A NAME="ss4.6">4.6 Reading Keyboard Input with SLkp_getkey</A>
</H2>
<P>
<P>Unlike the low-level function <CODE>SLang_getkey</CODE>, the
<CODE>SLkp_getkey</CODE> function can read a multi-character sequence
associated with function keys. The <CODE>SLkp_getkey</CODE> function uses
<CODE>SLang_getkey</CODE> and <B>S-Lang</B>'s keymap facility to process escape
sequences. It returns a single integer which describes the key that
was pressed:
<BLOCKQUOTE><CODE>
<PRE>
int SLkp_getkey (void);
</PRE>
</CODE></BLOCKQUOTE>
That is, the <CODE>SLkp_getkey</CODE> function simple provides a mapping
between keys and integers. In this context the integers are called
<EM>keysyms</EM>.
<P>For single character input such as generated by the <CODE>a</CODE> key on
the keyboard, the function returns the character that was generated,
e.g., <CODE>'a'</CODE>. For single characters, <CODE>SLkp_getkey</CODE> 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 <CODE>slang.h</CODE> include file. For example, the
up arrow key corresponds to the keysym whose value is
<CODE>SL_KEY_UP</CODE>.
<P>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
<CODE>SL_KEY_ERR</CODE> will be returned.
<P>Here is an example of how <CODE>SLkp_getkey</CODE> may be used by a file
viewer:
<BLOCKQUOTE><CODE>
<PRE>
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 ();
}
</PRE>
</CODE></BLOCKQUOTE>
<P>Unlike its lower-level counterpart, <CODE>SLang_getkey</CODE>, there do
not yet exist any functions in the library that are capable of
``ungetting'' keysyms. In particular, the <CODE>SLang_ungetkey</CODE>
function will not work.
<P>
<P>
<H2><A NAME="ss4.7">4.7 Buffering Input</A>
</H2>
<P>
<P><B>S-Lang</B> has several functions pushing characters back onto the
input stream to be read again later by <CODE>SLang_getkey</CODE>. It
should be noted that none of the above functions are designed to
push back keysyms read by the <CODE>SLkp_getkey</CODE> function. These
functions are declared as follows:
<BLOCKQUOTE><CODE>
<PRE>
void SLang_ungetkey (unsigned char ch);
void SLang_ungetkey_string (unsigned char *buf, int buflen);
void SLang_buffer_keystring (unsigned char *buf, int buflen);
</PRE>
</CODE></BLOCKQUOTE>
<P><CODE>SLang_ungetkey</CODE> 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
<CODE>SLang_getkey</CODE> will return this character. This function may be used
to <EM>peek</EM> at the character to be read by first reading it and then
putting it back.
<P><CODE>SLang_ungetkey_string</CODE> has the same function as
<CODE>SLang_ungetkey</CODE> 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.
<P>The last of these three functions, <CODE>SLang_buffer_keystring</CODE> can
handle more than one charater but unlike the other two, it places the
characters at the <EM>end</EM> of the keyboard buffer instead of at the
beginning.
<P>Note that the use of each of these three functions will cause
<CODE>SLang_input_pending</CODE> to return right away with a non-zero value.
<P>Finally, the <B>S-Lang</B> keyboard interface includes the function
<CODE>SLang_flush_input</CODE> with prototype
<BLOCKQUOTE><CODE>
<PRE>
void SLang_flush_input (void);
</PRE>
</CODE></BLOCKQUOTE>
It may be used to discard <EM>all</EM> input.
<P>Here is a simple example that looks to see what the next key to be read is
if one is available:
<BLOCKQUOTE><CODE>
<PRE>
int peek_key ()
{
int ch;
if (SLang_input_pending (0) == 0) return -1;
ch = SLang_getkey ();
SLang_ungetkey (ch);
return ch;
}
</PRE>
</CODE></BLOCKQUOTE>
<P>
<P>
<P>
<H2><A NAME="ss4.8">4.8 Global Variables</A>
</H2>
<P>
Although the following <B>S-Lang</B> global variables have already been
mentioned earlier, they are gathered together here for completeness.
<P><CODE>int SLang_Ignore_User_Abort;</CODE>
If non-zero, pressing the interrupt character will not result in
<CODE>SLang_Error</CODE> being set to <CODE>USER_BREAK</CODE>.
<P><CODE>volatile int SLKeyBoard_Quit;</CODE>
This variable is set to a non-zero value when the interrupt
character is pressed. If the interrupt character is pressed when
<CODE>SLang_getkey</CODE> is called, the interrupt character will be
returned from <CODE>SLang_getkey</CODE>.
<P><CODE>int SLang_TT_Baud_Rate;</CODE>
On systems which support it, this variable is set to the value of the
terminal's baud rate after the call to <CODE>SLang_init_tty</CODE>.
<P>
<P>
<P>
<HR>
<A HREF="cslang-5.html">Next</A>
<A HREF="cslang-3.html">Previous</A>
<A HREF="cslang.html#toc4">Contents</A>
</BODY>
</HTML>
