inkey

inchar (STRING*);

inkey (STRING*);

Enters keyboard input into the given string. The local keyboard layout is activated. inchar() waits until a key is pressed, and returns its ASCII value; inkey() reads characters into the string until the input is terminated with [Enter] or [Tab].

Parameters:

STRING* - String pointer to receive keyboard entry, or NULL for just returning the key value.

Returns:

1	Input terminated prematurely because inkey_active was set to 0 or another keyboard entry was active at the same time.
9	Input terminated by [Tab]
13	Input terminated by [Enter]
27	Input aborted by [Esc]
72	Input aborted by [Up]
73	Input aborted by [PgUp]
80	Input aborted by [Down]
81	Input aborted by [PgDn]
other	ASCII value of the pressed key.

Modifies:

STRING	String receives keyboard entry.
inkey_active	is set to 1 or 2 during entry.

Remarks:.

The text of the inkey() input can be edited using [BackSpace], [Del], [Right], [Left], [Home] and [End] . The original length of the string can not be exceeded. The keys [Esc], [Up], [Down], [PgUp], [PgDn] or [F1]..[F11] abort inkey(); the previous content of the string is then restored, and the scan code of the key is returned.
If the string appears in a TEXT object displayed on screen, the input as well as the cursor are visible. The cursor is the character 127 from a bitmap font, or the character 59 (underscore '_') from a TrueType font. The str_cursor function can be used to get the current cursor position while the string is edited.
Keyboard entry can be aborted externally by setting the inkey_active variable to 0.
Key events (on_a etc.) are inactive during keyboard entry, and game_save/game_load functions are not executed.
This function is not exported in acknex.dll.

Example:

STRING* entry_str = "                      "; // long empty string
...
result = inkey(entry_str); // wait until [enter] pressed
if (result == 13) {
  process_entry(entry_str); 
}