[Main]
Name=cmd_inputstr
Type=Function
Subtype=ROM Call
Header Files=bascmd.h
Definition=void cmd_inputstr (ESI PromptAndVar);
MinAMS=1.01

[ROM Call]
Index=$357

[Description]
Executes TI-Basic 'InputStr' command.

[Explanation]
If <I>PromptAndVar</I> points to a string item (more precise,
to its <A HREF="$$LINK(estack.h/Tags)">STR_TAG</A>), cmd_inputstr first displays the current
contents of the TI-Basic Program I/O Screen window, pauses the program, displays the
prompt string pointed to by <I>PromptAndVar</I> on the Program I/O Screen, waits for the
user to enter a response, and stores the response in a TI-Basic variable whose name is
given on the expression stack just below the expression pointed to by <I>PromptAndVar</I>.
This is illustated in the following example, which stores the user's name in a TI-Basic variable
named "x":
<PRE>push_quantum (VAR_X_TAG);
push_zstr ("Enter your name:");
cmd_inputstr (top_estack);
</PRE>
If <I>PromptAndVar</I> points directly to a variable tag, "?" is displayed as a
prompt.
<BR><BR>
<B>Note:</B> cmd_inputstr is not the recommended way for inputing data from the keyboard into the
program. It is limited to the TI-Basic Program I/O Screen window, and it stores the result in TI-Basic
variables, which is not so useful in C programs (i.e. you need to import the value
of a TI-Basic variable into the program, which is not so straightforward). See the
<A HREF="$$INFOLINK(faq/input)">keyboard input</A> section of the FAQ list for explanation of much
better ways to enter data from the keyboard.

[References]
Out=error.h/ER_catch, error.h/ER_success, error.h/ER_throwVar, error.h/ERD_dialog, estack.h/next_expression_index, estack.h/NG_tokenize, estack.h/push_quantum, estack.h/top_estack, events.h/EV_captureEvents, events.h/EV_eventLoop, events.h/EV_paintWindows, events.h/EV_setFKeyState, events.h/EV_startApp, graph.h/ScrToHome, graph.h/ScrToWin, string.h/strlen, textedit.h/TE_close, textedit.h/TE_focus, textedit.h/TE_isBlank, textedit.h/TE_open, textedit.h/TE_reopen, textedit.h/TE_select, textedit.h/TE_shrinkWrap, textedit.h/TE_unfocus, unknown.h/EV_currentApp, unknown.h/EV_quit, unknown.h/NG_control, estack.h/push_simplify, vat.h/VarStore, wingraph.h/WinActivate, wingraph.h/WinBackupToScr, wingraph.h/WinChar, wingraph.h/WinClr, wingraph.h/WinDeactivate, wingraph.h/WinFill, wingraph.h/WinHide, wingraph.h/WinScrollV, wingraph.h/WinStrXY, wingraph.h/WinWidth, unknown.h/_ds16u16, unknown.h/_du32u32, unknown.h/_ROM_CALL_455, unknown.h/_ROM_CALL_471, unknown.h/_ROM_CALL_5CA
Out_EV_eventLoop=1
