Hello there! AGVolnutt here with a tutorial for an amazing (but little known)
new feature in OS 3.0! Corrected: Only a little known feature.
AGVolnutt presents...USING "REQUEST" AND "TEXT" for nSPIRE BASIC (and how to apply them!)SummaryWhen OS
3.0 2.0 was introduced, a new command was added to the OS which would improve functionality on the nSpire drastically! This command is called the "request" command, (with it's sibling called "text"). In short, what these commands do is that they 1. ask you for input and pause the program as it awaits for your input and 2. displays a message (warning, notice, etc.) without creating a mess using "disp", respectively. Before request was added, users had to input values before the program or function started, which created a hassle about what to input and where to input.
In the following tutorial, I will demonstrate how to use the request function and workflows on how to apply it.
Getting StartedYou will need OS
3.0 2.0 on your nSpire or your nSpire Student Software. You will then need to setup your workstation. For those that don't
know how to launch the workstation, (you shouldn't be here anyways.
), the command is (for the handheld) MENU>9>1>1.
Getting to know madame "REQUEST"The request command allows you to gain user input (through windows!) for
logical values (1,0,2x,3av,3/4,4^2). I probably just gave you a headache, so therefore I will explain. "request" alone in itself will only take in "number values", however, it's sibling "RequestStr" will allow you to take in
strings (Lady Gaga, arc, paper, spoon). Whenever "request" is summoned, it pauses the current program and awaits user input, refusing to move on until input is given or the dialogue is canceled.
It should also be noted that the "request" command cannot be used in straight-forward "function" apps.
Something that should be noted is that there is one ugly-as-sin error every developer will encounter when using request.
USER NONCOMPLIANCE *GASP* That's right. This occurs when the user refuses to give input and totally causes the program to wig out. But we'll get to that later.
Generally, a basic "request" command starts out as (inside a program template):
request "How old are you?",oay
will ask the user how old he/she is and print to the calculator
How old are you? 9000
with 9000 being the age that the user inputs.
If you wish for strings to be inputed, just add "str" to the end of "request", like so: "RequestStr" and then use words instead of numbers as your input!
Breaking down the Request commandThe request command has four options, with two being mandatory. The most basic request command you can have is "
request "How old are you?",oay
". But let's say you want a little more handle on your execution of commands. Since you don't prefer to have a bunch of mess in your output, you would want to define
DispFlag. DispFlag basically tells the compiler "print this to the calculator or not". DispFlag is either true (1) or false (0).
There is also another special option called a StatVar. The StatVar is also a T/F, but that is defnied by the user. When the user encounters the request window, they are given two choices. OK or Cancel. Whenever the user selects either one of the choices, the calculator automatically logs the StarVar as 1 or 0, respectively. This is an invaluable tool for dealing with user noncompliance, which was explained earlier.
Avoiding unwanted bugs with the Request commandAssessing to common knowledge, computers normally resolve to "on" or "off" (like Ke$ha), right? (Unless you're running with quantum computing, of which I would love to see!) The same thing applies the "request" stuff. When you use request, you are given two options: "OK" or "CANCEL". If you're just using request to store variables (which is completely redundant, even counter-productive), choosing "Cancel" would do absolutely nothing, as the program would progress with no input given, with the request command completely ignored. But let's say you're running a complex application with if's and such. If a variable that the "if" relies on is undefined, then the program will totally wig out at the lack of definition and immediately abort the program with an error. To avoid this, we use a technique I call: "ReqWrap".
To apply a Request Wrap, you must define two actions, like a fork in the road. Of course, the two actions must not be the same (which would again, be redundant). The request wrap is generally having an if that corresponds to a request's StatVar right after the request is asked.
In order to utilize a request wrap, you must have a StatVar named. Your ReqWrap must also be logical and with common sense. The simplest way to use a ReqWrap is to have it set up so that when a user presses cancel, the program automatically ends (cleanly) by skipping the meat of the program in general.
(Below is an example program that calculates the amount of sliced apples that could be made with x apples in a machine.)
[Insert new program header]
Request "Number of Apples",qa,0,hqa
If hqa=0 Then
Disp "Apple Slicer aborted."
Goto asprgmend
ElseIf hqa=1 Then
define sa=ga/10
define sa=sa@>decimal
disp sa
Endif
lbl asprgmend
[Insert end program opposite-header]The italicized lines show a basic wrapper for a request function. Basically, it's a fall-back for when the user quits the application by hitting cancel. Under normal, unwrapped circumstances, the program would progress normally and screw up.
But normally, that would not be enough to protect a program from user-error. Let's say the user hits "OK"... but enters no input. This would cause an equally wiggy error to the program if they hit an unwrapped cancel. Unfortumately, we cannot do much if the user refuses to give input. But, we can prevent the calculator from wiggin' out if the user gives an out-of-bounds input. To counter this, we would have another wrapper layer that tells the calculator, "if the amount of apples is below/above a certain number, then automatically abort the program. This is seen below in the bolded text alongside the italicized text.
[Insert new program header]
Request "Number of Apples",qa,0,hqa
If hqa=0 Then
Disp "Apple Slicer aborted."
Goto asprgmend
ElseIf hqa=1 Then
If qa<1 Then
Goto asprgmend
ElseIf qa>0 Then
Define sa=((qa)/(10))
Disp sa," sliced apples can be made from ",qa," apples"
EndIf:
EndIf
Lbl asprgmend
[Insert end program opposite-header]HOW TO APPLY REQUEST TO YOUR APPLICATIONlGenerally, people would use "request" as a formal way to ask for input in an organized window. Although I choose in my programs to ask for input at the beginning of the program, sometimes, it would be much more logical to ask for input as the program progresses. For example, your program asks for a code to start the program. Obviously, you would not ask for other inputs right after the code input, as that would spoil the secrecy about the program's internals. (Rough and dirty explanation.
)
Although not recommended, you could apply request to a "true/false" scenario. As in have the user input 0 or 1 for false or true, respectivly. Of course, this is quite not recommded as your program should determine that on it's own rather than have the user read a "text command" before hand and using a brashly thrown-together true/false box.
USING TEXTText is NOT a variant of request. It is simply just a standard information window, but access was recently given to the user. Of course, you can use text to display disclaimers, EULA's, instructions and etc., but that's pretty much all you can do. In fact, that is the only thing you can do. You can only control the text displayed, and whether or not to print the defined text to the calculator output or not.
You should know, the text is not stored in a variable, but ripped directly from the instruction itself. Therefore, you cannot call up the text later in the program to print the message (to the output) to the user without retyping everything again.
text "STOP COLON I DUN WANNA EULA ANYMOAR.",0 
Note the "
0" at the end of the teletype. That denotes that the defined text NOT be printed to the calculator output, the same with request.
When you use "text", it can be applied almost anywhere, with the thought in mind that the user will actually take the time to read it and not pass it off as another spam post. Normally, these text boxes should only contain important messages, such as warning the user about some ludicrous input. (Something nice to add to request is to tell the user theyput in an invalid input and take them back to the request box.)
CONCLUSIONTexas Instruments has provided us with some valuable tools here. It's up to us whether we will use it or apply it correctly. The request command is a powerful command, with it being similar to modern day input windows. And the "text"-box is also useful as well for displaying vital information. How we use it will shape the user's and out experience on the calculator programming field.
_______________________________________________________________________________
Text copyright of AGVolnutt
You may link to this text, but not copy or repost it on any other site.
Author's notes:
I spent a few days on this. If this has some errors or is not to your standards, please post below on how I can improve in the future. Input is much appreciated.
I also colored the teletype text, so this could be used as a basis for a potential IDE for nSpire.
