Andrew Korson: Created page with "The '''get.string''' command prompts the player to enter a string that can be manipulated in logic code. == Syntax == get.string(str sA, msg mPROM..."

2019-04-07T20:45:17Z

Created page with "The '''get.string''' command prompts the player to enter a string that can be manipulated in logic code. == Syntax == get.string(str sA, msg mPROM..."

New page

The '''get.string''' command prompts the player to enter a [[string]] that can be manipulated in logic code.

== Syntax ==

get.string([[string|str]] sA, [[message|msg]] mPROMPT, [[number|byt]] ROW, [[number|byt]] COL, [[number|byt]] LEN);<br />
get.string([[string|str]] sA, "prompt", [[number|byt]] ROW, [[number|byt]] COL, [[number|byt]] LEN);<br />

== 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 ==

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="agi">
get.string(s5, "Password?", 1, 0, 12);
print("The password is '%s5'.");
</syntaxhighlight>

== Technical Information ==

{| border="1" cellpadding="2"
| style="background-color: #efefef" width="200" | '''Required Interpreter Version:'''
| width="175" | Available in all AGI versions.
|-
| style="background-color: #efefef" | '''Byte-Code Value:'''
| 115 (0x73 hex)
|}

== See Also ==

[[String Commands]]<br />
'''[[get.num]]'''<br />
'''[[close.dialogue]]'''<br />
'''[[open.dialogue]]'''<br />
[[Category:Commands]]<br />

Get.string - Revision history

Andrew Korson: Created page with "The '''get.string''' command prompts the player to enter a string that can be manipulated in logic code. == Syntax == get.string(str sA, msg mPROM..."