Get.string
The get.string command prompts the player to enter a string that can be manipulated in logic code.
Syntax
get.string(str sA, msg mPROMPT, byt ROW, byt COL, byt LEN);
get.string(str sA, "prompt", byt ROW, byt COL, byt LEN);
Remarks
The get.string command lets the programmer designate a location for the prompt and player input, instead of using the existing input line like the get.num command does. Message mPROMPT is used as the prompt, which is displayed at text column COL, row ROW.
The last argument, LEN, is the maximum number of characters that the player can enter. LEN is limited to 40.
When running on a system using the Hercules Graphics Card (HGC), the get.string command normally uses an input box similar to the normal HGC input box. The open.dialogue command will cause the get.string command to operate the same as on other systems, as described above.
Possible Errors
AGI does not automatically clear the prompt from the screen; it remains on the screen in the same way that text drawn by the display command. Calling the graphics command is one way to refresh the display and clear the prompt.
If the prompt is drawn on top of the input line, this will cause confusion if the player had text on the input line prior to the get.string call. The previous text will still exist on the line, but it won't be visible. An easy workaround to this is to call the prevent.input and accept.input commands immediately after you use get.string to clear and restore the input line.
There is a minor bug in AGI that causes the input line to be offset by one space after calling the get.string command when a cursor character is being used. When AGI restores the input line after displaying the get.string prompt, it uses the position of the cursor, which is actually one space beyond the location of the last actual character. It will appear to the player that there is a space there when in reality there is not. This can be avoided by calling the prevent.input and accept.input commands immediately after you use get.string.
If a value for LEN greater than 40 is passed, AGI ignores it and uses 40. Also, AGI does not check to see if the total amount of space used for input (length of the prompt, plus the COL value, plus the LEN value) exceeds 40; if it does, the input will wrap around to column 0 of the next row, which may not be what was desired.
AGI does not check that a valid string argument is passed. If an invalid string number is used (the limit is 24 [s0 - s23], except for versions 2.089, 2.272 and 3.002.149, which have a limit of 12 [s0 - s11]) AGI will overwrite areas of memory used for other purposes, which may result in crashing AGI.
If ROW is greater than 24, then both COL and ROW values are ignored, and the prompt will be displayed a the current input line location.
Example
<syntaxhighlight lang="agi"> get.string(s5, "Password?", 1, 0, 12); print("The password is '%s5'."); </syntaxhighlight>
Technical Information
| Required Interpreter Version: | Available in all AGI versions. |
| Byte-Code Value: | 115 (0x73 hex) |
