GnuDOS library version 1.0: Kbd

Next: Dialogs, Previous: hello_strings, Up: Top [Contents][Index]

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

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
    }

Next: Dialogs, Previous: hello_strings, Up: Top [Contents][Index]