4 Using the Kbd utility

The Kbd utility of the GnuDOS library provides functions for getting input from the keyboard, initializing and restoring the terminal state to enable the utility to grasp proper keyboard input, and some global variables.

The global variables defined in kbd.h are:

bool ALT;
bool CTRL;
bool SHIFT;
bool CAPS;
bool INSERT;
bool X_IS_RUNNING;

This is their explanation:

• ALT: Boolean variable that indicates the state of the ALT key
    (1=pressed, 0=released)
  
• CTRL: Boolean variable that indicates the state of the CTRL key
    (1=pressed, 0=released)
  
• SHIFT: Boolean variable that indicates the state of the SHIFT key
    (1=pressed, 0=released)
  
• CAPS: Boolean variable that indicates the state of CAPSLOCK
    (1=pressed/ON, 0=released/OFF)
  
• INSERT: Boolean variable that indicates the state of the INSERT key
    (1=pressed/ON, 0=released/OFF)
  
• X_IS_RUNNING: Boolean variable that indicates whether X is running
    (1=running under X, 0=running under console)
  

Three functions are defined:

int initTerminal();
void restoreTerminal();
int getKey();

The initTerminal() function must be called before any other library function is used. It initializes the terminal for library use. What this means in simple English is that the console will be messed up for other programs during your program execution. This is why it is MANDATORY to call restoreTerminal() just before your program exits to ensure that the terminal is restored to its previous state. Failing to do so, the terminal is left in an intermediate state that the user will have only one option: to reboot (under console) or to kill (or close) the terminal (under X).

The function getKey() is called to get the next key press from the keyboard. It actually relies on two functions internally: one to get the key under X, the other to get it under console mode. The difference between the two is of no relevance to the user. Just call getKey() to get the next keypress whether under X or the console.

The getKey() function returns its result as an integer. For alphanumeric keys this will mean the ASCII value of that key (ASCII 65-90 for Latin capitals, 97-122 for Latin smalls, 32 for Space, 33-64 for numbers and punctuation, 96 for backtick, 123-126 for braces, vertical bar and tilde). Other keys like arrows and ESC and ENTER are defined as macros in the kbd.h file:

#define ESC_KEY  27
#define BACKSPACE_KEY 8
#define TAB_KEY  9
#define ENTER_KEY 13
#define CAPS_KEY 1
#define SHIFT_KEY 2
#define CTRL_KEY 3
#define ALT_KEY  4
#define SPACE_KEY 32
#define UP_KEY   5
#define DOWN_KEY 6
#define LEFT_KEY 7
#define RIGHT_KEY 10
#define DEL_KEY  11
#define	HOME_KEY 12
#define END_KEY  14
#define INS_KEY  15
#define SHIFT_DOWN 17
#define SHIFT_UP 18
#define PGUP_KEY 19
#define PGDOWN_KEY 20

What you need to do is to match the return value of getKey() against the desired key. For example:

if(getKey() == ESC_KEY)
{
   exit(0);
}

Or, more elegantly, in a switch loop:

int c = getKey();
switch(c) 
{
  case(ESC_KEY):
     //do-something
     break;
  case(UP_KEY):
     //do-other-stuff
     break;
  default:
     if(c >= 32 && c <= 126)
        print("%c", c);
     break;
}

To test for special key combinations (e.g. CTRL+S):

c = getKey()
if(c == 's' && CTRL) 
{
   //do something
   ...
}

Another utility has been added, which is called UKbd ("U" stands for Unicode). As such, this utility is the exact same replica of the Kbd utility, with the exception that it handles unicode characters. The functions defined are almost the same as Kbd’s functions, with an added "u" in front of each, i.e.:

char *ugetKey();
char *ugetKeyUnderConsole();
char *ugetKeyUnderX();

The results are returned as a character pointer in each.

One additional piece of information is the mask that is used to determine the length of a given unicode char, as unicode chars have variable lengths:

static unsigned short mask[] = {192, 224, 240};