ngetchx Function (ROM Call 0x51)

kbd.h

short ngetchx (void);

Gets character from the keyboard, without echoing to the screen.

ngetchx reads a single character directly from the keyboard, without echoing to the screen. If the keyboard queue is empty, ngetchx will wait for the keypress, else the character will be picked from the keyboard queue.

ngetchx returns the code of the character read from the keyboard. This code is mainly the same as TI-Basic function GetKey returns. All keypresses which correspond to the ASCII character will return the ASCII code of it, for example pressing on '+' key will return the ASCII code of '+' (which is 43 in decimal), so you can write

if (ngetchx () == '+') ...
Codes for some other common keypresses which do not have an ASCII representation (ESC, ENTER, function keys, etc.) and which are the same on the TI-89 and TI-92 Plus are defined in the enum CommonKeys (for example, KEY_ESC, KEY_ENTER etc.).

Be aware that codes assigned to arrow keys is shuffled in comparation with TI-Basic. These codes are also different on TI-89 and TI-92 Plus. Note that the documentation of releases of TIGCCLIB prior to 2.0 has an error: it recommends usage of OSGetStatKeys as a calculator-independent method for reading arrow keys. This is simply not true. Here is a table of return codes for pressing arrow keys on TI-89 and TI-92 Plus:

TI-89:

Key Normal +Shift +2nd +Diamond +alpha
Up337852944331672133105
Right344853644401672833112
Down340853244361672433108
Left338853044341672233106

TI-92+:

Key Normal +Shift +2nd +Diamond +alpha
Up338167224434853033106
Right340167244436853233108
Down344167284440853633112
Left337167214433852933105

It is interesting that the ngetchx function is able to handle pressing to more than one arrow keys at the same moment. The returned value is then simply logical OR of values for a particular key.

To increase compatibility between TI-89 and TI-92 Plus, a header file compat.h is implemented. This file (among others) defines pseudo-constants (known from DoorsOS) like KEY_LEFT, KEY_RIGHT, KEY_UP and KEY_DOWN which represent return values for arrow keys. These "pseudo-constants" have different values on the TI-89 and TI-92 Plus, so if you use testing like
if (key == KEY_LEFT) ...
such test will work fine on both the TI-89 and TI-92 Plus. These pseudo-constants works in both "nostub" and "DoorsOS" mode. Pseudo-constants KEY_UPRIGHT and KEY_DOWNLEFT are also defined, with obvious meaning.

Codes of keystrokes like <Diamond> + <key> are also different in comparison with the TI-Basic GetKey function. I will not give a complete table here, because such keystrokes are rarely used in programs. If you are interested for a code of the concrete keystroke, you can easily find it by yourself. Principally, the code for a keystroke like <Diamond> + <key> is mainly equal to the code for <key> increased by KEY_DIAMOND. This is also a pseudo-constant with value 16384 on TI-89 and 8192 on TI-92 Plus. The same is true for keystrokes like <Shift> + <key>, and the appropriate pseudo-constant which need to be added is called KEY_SHIFT (8192 on TI-89 and 16384 on TI-92 Plus).

As a side effett, ngetchx also sets the activity in the status bar to BUSY, so the "BUSY" indicator will appear in the status bar. If you want later to remove the "BUSY" indicator, you must call ST_busy function to do this.

Note: ngetchx function is slow, because it also handles receiving eventual bytes from the link port. This is used in TIOS mainly when the calculator is in the Home screen, but principally, if the program is waiting for a keypress using ngetchx function, any valid data which come to the link port will be received and processed accordingly (for example, the program waiting for a keypress can accept another program via the link port during waiting). See kbd_queue for much faster way to gets characters from the keyboard.


Uses: OSFastArrows, HomeAlone, OSCheckSilentLink, OSLinkCmd, OSReadLinkBlock, OSWriteLinkBlock, OSdequeue, OSSetSR, OSTimerRestart, ROM Call 0x471
Used by: assert, cmd_disptbl, cmd_pause, push_getkey, EV_eventLoop, EV_getc, fgetchar, gets, getsn, GS_PlotAll, GZ_Stat, Regraph


See also: GKeyIn, kbhit, kbd_queue, OSFastArrows