KEYBOARD INDEPENDENCE

Man Page Index

Keyboard input can be handled independently of the current terminal type within end user coded routines by using the jBASE Command Key subroutines supplied in the jBASE libutils library.

The jBASE supplied includes, JBC.h and jCmdKeys.h, and the subroutines CommandInit and CommandNext are integral to using this feature. The CommandInit subroutine initializes the keyboard mappings while the ComandNext subroutine would be used in place of the INPUT statement to return the actual command (i.e. Page Up, Insert Line, Cursor Left, etc). It is then up to the application to provide the appropriate functionality for each command.

The CommandInit subroutine uses un-named COMMON internally so, if the application requires the use of COMMON, then it should use named-COMMON.

Many of the commands returned by the CommandNext subroutine are taken from default command keys used with the JED editor. The .jedrc file can be configured to alter the default definitions. Be aware that modifying .jedrc will also change the corresponding behavior in JED.

Required Includes: JBC.h, jCmdKeys.h

Required Subroutines: CommandInit, CommandNext(KeyDescriptionCode,KeyData,Timeout)

PROCEDURE

First add the following lines to the initialization of your program:

$INCLUDE JBC.h
$INCLUDE jCmdKeys.h
CALL CommandInit ;* Initialize keyboard mappings

Then to check the keyboard for input (or window resizing etc.):

CALL CommandNext(KeyDescriptionCode,KeyData,Timeout)

Where:

KeyDescriptionCode
This variable is returned by the CommandNext subroutine. The jCmdKeys.h file contains a list of equates for this description e.g. if Page Up was pressed the code returned will be 30 (i.e. cmd_scroll_up_page) and if a Alpha/Numeric key was pressed then the code returned will be 101 (i.e. cmd_alpha_numeric). If the timeout occurs before a key is pressed then the code returned will be 102 (i.e. cmd_timeout). Refer to jCmdKeys.h for a complete list of codes and their descriptions.

KeyData
This is the actual code sequence that has been typed as defined in jCmdKeys.h or the ASCII code of the Alpha/Numeric key pressed. Note that all keyboard input is echoed to the screen. For this reason it is advisable to use ECHO OFF before the CALL to the CommandNext routine and ECHO ON after (see EXAMPLE below).

Timeout
This is a variable that is passed to the CommandNext subroutine. It must be an integer indicating the number of tenths of seconds to wait until the CommandNext subroutine terminates, so 150 will be a 15 second timeout. To inhibit the timeout feature initialize this variable to zero (ie Timeout = 0).

EXAMPLES

This code shows how to use the timeout capability:

$INCLUDE JBC.h
$INCLUDE jCmdKeys.h
EQU Timeout TO 100 ;* 10 seconds
CALL CommandInit
* Accept keyboard input until ESC is pressed or the Timeout limit has been reached
LOOP
     ECHO OFF
     CALL CommandNext(RtnNo, KeyData, Timeout)
     ECHO ON
     CRT @(0):@(-4):'KeyDescriptionCode=':RtnNo:' KeyData=':KeyData:
UNTIL RtnNo = cmd_escape OR RtnNo = cmd_timeout DO
REPEAT
CRT

The following program can be used to determine the exact KeyDescriptionCode and KeyData returned for various keyboard commands:

$INCLUDE JBC.h
$INCLUDE jCmdKeys.h
EQU Timeout TO 300; * 30 Seconds
CALL CommandInit

LOOP
    ECHO OFF
    CALL CommandNext(RtnNo, KeyData, Timeout)
    ECHO ON
UNTIL RtnNo = cmd_escape DO
    BEGIN CASE
    CASE RtnNo = cmd_alpha_numeric  ;* Simple alpha-numeric
        Line := KeyData
        GOSUB CursorRight
    CASE RtnNo = cmd_clear_end_line ;* Clear to end of line
        CRT @(-4):
    CASE RtnNo = cmd_insert_value   ;* Insert a char(253)
        Line := @VM
        GOSUB CursorRight
    CASE RtnNo = cmd_cursor_up      ;* Move cursor up a line
        GOSUB CursorUp
    CASE RtnNo = cmd_cursor_down    ;* Move cursor down a line
        GOSUB CursorDown
    CASE RtnNo = cmd_cursor_right   ;* Move cursor to the right
        GOSUB CursorRight
    CASE RtnNo = cmd_cursor_left    ;* Move cursor to the left
        GOSUB CursorLeft
    CASE RtnNo = cmd_error          ;* Unknown command string
        GOSUB InputError
    CASE RtnNo = cmd_timeout        ;* The input timed out
        GOSUB CheckStatus
    CASE RtnNo = cmd_winsize        ;* Size of the X window changed.
        GOSUB RefreshScreen
    CASE 1
        GOSUB InputError
    END CASE
REPEAT

TERMINAL