| GKeyIn | Function (ROM Call 0x17E)

kbd.h

short GKeyIn (SCR_RECT *cursor_shape, unsigned short Flags);

Gets character from the keyboard, with additional possibilities.

GKeyIn acts similarly to ngetchx, with following differences:

- During waiting for a keypress, a flashing cursor may optionally be displayed. Parameter cursor_shape is a pointer to SCR_RECT structure which defines location and shape of the cursor (it is, in fact, a flashing rectangular area). If cursor_shape is NULL, no cursor will be displayed.
- The activity in the status line during waiting for a keypress is set to IDLE (in opposite to ngetchx which sets activity to BUSY). After a keystroke is ready, the activity will be switched to BUSY. See ST_busy for more info about status line activity indicator.
- During waiting for a keypress, if the user waits too long, the calculator will be switched off (APD feature - Automatic Power Down). This will not happen with ngetchx. See system.h header file for more info about APD.
- During waiting for a keypress, the calculator enters into "idle" state (see idle for more info).
- If Flags is different than zero, some special behaviour happens.

Normally, Flags should be zero. It is collection of binary flags, where bits b0, b1, b3 and b4 are used. They are not very useful, but their meaning is as follows:

- When b0=1, if the pressed key is a modal key (see QModeKey for info what is a "modal" key for TIOS), GKeyIn will return KEY_ESC instead of real keystroke code, and the keystroke will not be picked from the keyboard queue. If the pressed key is not a mode key, GKeyIn behaves as usual.
- When b1=1, GKeyIn will not pick a keystroke from the keyboard queue, so the "keypress" flag will remain set. You must explicitely pick it using ngetchx or flush the queue using GKeyFlush.
- When b3=1, if the pressed key is a system key (see QSysKey for info what is a "system" key for TIOS), GKeyIn will return KEY_ESC (code of ESC key) instead of real keystroke code, and the keystroke will not be picked from the keyboard queue. If the pressed key is not a system key, GKeyIn behaves as usual.
- When b4=1, pressing on CATALOG key will be ignored.

Except in noted special cases, GKeyIn returns the same value as ngetchx. Menus and dialog boxes usually set b0=1 and b3=1, so that if au user presses say VAR-LINK key in the dialog box, the dialog box is closed and then the VAR-LINK key is acted on.
Note: Thomas Nussbaumer informed me that idle interferes with grayscale graphics. As GKeyIn calls the idle function, the use of GKeyIn while grayscale mode is active is not recommended.

Uses: ROM Call 0x3EA
Used by: GKeyFlush, cmd_showstat, cmd_toolbar, Dialog, DlgMessage, handleVarLinkKey, MenuKey, HelpKeys, GT_Trace

See also: ngetchx, kbhit, kbd_queue, OSFastArrows