| 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 which is obtained by XORing a rectangle while waiting on a key). 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).
- GKeyIn bypasses the event manager’s handling of keys so this routine should be used with caution.
- If Flags is different than zero, some special behaviour happens.

The parameter Flags can be a combination of the following, defined in the GKeyFlags enumeration:

GKF_NORMAL | No special key processing. This is the usual value to set. Note: GKF_NORMAL is actually 0 (i.e. no flags are set).

GKF_MODAL

If the pressed key is a modal key (see QModeKey for information on what is a "modal" key for the TIOS), GKeyIn will return KEY_ESC instead of the 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.
Note that DIALOG boxes usually set GKF_MODAL and GKF_SYS so that if the user presses [VAR-LINK] in the dialog box, the dialog box is closed and then the [VAR-LINK] key is acted on (though there is a flag to allow [VAR-LINK] to be activated from inside a dialog box).

GKF_REPUSH_KEY | GKeyIn will not pick the 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.
GKF_ACCEPT | The purpose of this flag is unknown for the moment.
GKF_SYS | If the pressed key is a system key (see QSysKey for information on what is a "system" key for the TIOS), GKeyIn will return KEY_ESC instead of the 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.
GKF_NO_EVS | Pressing the [CATALOG] key will be ignored.

Except in noted special cases, GKeyIn returns the same value as ngetchx. Menus and dialog boxes usually set GKF_MODAL and GKF_SYS, so that if a user presses say the VAR-LINK key in the dialog box, the dialog box is closed and then the VAR-LINK key is acted on.
Note: TI doesn't recommend to use GKeyIn as it bypasses the event manager’s handling of keys. Programs should use the event manager to process keys in most cases. GKeyIn should only be used in special cases where the event manager is not accessible. For games, you'll probably be better off using kbd_queue or _keytest.
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