od_get_input()

Retrieves one character or translated extended-key event.

Synopsis

BOOL od_get_input(tODInputEvent *pInputEvent,
    tODMilliSec TimeToWait, WORD wFlags);

Description

od_get_input() reads from the common remote/local input queue. Unlike od_get_key(), it reports where the input originated and can combine a multi-byte terminal sequence into one logical function, cursor, or navigation key.

pInputEvent points to the tODInputEvent which receives the result:

typedef struct {
    tODInputEventType EventType;
    BOOL bFromRemote;
    char chKeyPress;
} tODInputEvent;

EVENT_CHARACTER means that chKeyPress contains one ordinary input byte. EVENT_EXTENDED_KEY means that it contains one of the OD_KEY_* values. bFromRemote is TRUE for remote input and FALSE for enabled local-keyboard input.

The translated extended values include:

Values	Logical keys
OD_KEY_F1 through OD_KEY_F12	Function keys F1 through F12
OD_KEY_UP, OD_KEY_DOWN, OD_KEY_LEFT, OD_KEY_RIGHT	Cursor movement
OD_KEY_INSERT, OD_KEY_DELETE	Insert and Delete
OD_KEY_HOME, OD_KEY_END, OD_KEY_PGUP, OD_KEY_PGDN	Navigation keys
OD_KEY_SHIFTTAB	Shift-Tab

When normal translation is enabled, OpenDoors also recognizes these single-byte control-key alternatives:

Control key	Extended result
Ctrl-E	OD_KEY_UP
Ctrl-X	OD_KEY_DOWN
Ctrl-S	OD_KEY_LEFT
Ctrl-D	OD_KEY_RIGHT
Ctrl-V	OD_KEY_INSERT
Ctrl-G or DEL	OD_KEY_DELETE

TimeToWait specifies the maximum initial wait in milliseconds. Zero performs an immediate queue check. OD_NO_TIMEOUT waits indefinitely. Any other value supplies a finite timeout. Once the first byte of a possible extended sequence has been received, OpenDoors can wait up to an additional 250 milliseconds between sequence bytes before deciding whether to return a translated key or the leading character. On 16-bit DOS, timer resolution is approximately 55 milliseconds.

Use od_get_input_until() when one absolute deadline must bound both the initial wait and any extended-sequence translation wait.

wFlags selects translation behavior:

Flag	Behavior
GETIN_NORMAL	Translate recognized terminal sequences and control-key alternatives.
GETIN_RAW	Return remote bytes individually as character events, without sequence translation.
GETIN_RAWCTRL	Translate terminal sequences but return the control-key alternatives as ordinary character events.

The flags may be combined, although GETIN_RAW necessarily prevents all extended-sequence translation and therefore takes precedence over GETIN_RAWCTRL.

This function does not update od_control.od_last_input; use the returned bFromRemote field when the source matters.

Return value

The function returns TRUE when it has filled pInputEvent. A timeout or an immediate empty-queue check returns FALSE without manufacturing an event. A null pInputEvent also returns FALSE and sets od_control.od_error to ERR_PARAMETER.

Example

tODInputEvent event;

if(od_get_input(&event, OD_NO_TIMEOUT, GETIN_NORMAL))
{
    if(event.EventType == EVENT_EXTENDED_KEY)
    {
        switch((unsigned char)event.chKeyPress)
        {
            case OD_KEY_UP:
                move_selection_up();
                break;

            case OD_KEY_DOWN:
                move_selection_down();
                break;
        }
    }
    else
    {
        process_character((unsigned char)event.chKeyPress);
    }
}

Cast chKeyPress to unsigned char before comparing values above 127, notably OD_KEY_F11 and OD_KEY_F12, on systems where plain char is signed.

See also

od_get_key(), od_key_pending(), od_clear_keybuffer(), od_get_input_until(), Input constants, Types and callbacks