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:

The parameter Flags can be a combination of the following, defined in the GKeyFlags enumeration:
GKF_NORMALNo special key processing. This is the usual value to set.

Note: GKF_NORMAL is actually 0 (i.e. no flags are set).
GKF_MODALIf 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_KEYGKeyIn 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_ACCEPTThe purpose of this flag is unknown for the moment.
GKF_SYSIf 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_EVSPressing 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