====== User Interaction Through Views ======

Views are special TOOL scripts that can create or display model variables within the Scenario and Model Manager (SAMM).  Views may interact with a user to either prompt the user to enter information or to provide the user with status updates as the view runs.  TOOL provides the following commands for screen input and output:

^ Command      ^ Syntax       ^ Description          ^
| [[user_interaction#Listen Command |listen]]    | listen (constant string, TOOL variable)| prompts the user for input |
| [[user_interaction#Say Command |say]] | say (expression1, expression2, ...) | displays strings, constants and TOOL variables on the screen then moves the cursor to a new line |
| [[user_interaction#Mumble Command |mumble]] | mumble (expression1, expression2, ...) | displays strings, constants and TOOL variables on the screen but does not move the cursor to a new line |
| [[user_interaction#Menu Command |menu]] | menu (prompt, numItems, item1, ..., itemN, $choices[]) | displays a menu on the screen and allows a user to select items from the menu |
===== Listen Command =====
The snytax of the listen command is:

listen (constant string, TOOL variable)

where

//constant string// is a string of alphanumeric characters enclosed by quotation marks " ". This string is the prompt that the user will see before entering data.

//TOOL variable// is the variable into which the entered data is placed. If this is an integer variable, only an integer value can be entered. If this is a boolean variable, the possible values that can be entered are {yes, y, true, 1} or {no, n, false, 0}.  These can also be entered as upper case letters.
==== Example ====

Listen code example with a default option:

<code>
listen ("What percentage change do you want to allow? {0..}[75] ",$percentChangeImm)
if $percentChangeImm == ""
	$percentChangeImm = "75.0"
	percentChangeImm[] = create (; data=75.0)
else
	percentChangeImm[] = create (; data=$percentChangeImm)
endif
</code>



===== Say Command =====
The syntax of the say command is:

say (expression1, expression2, ...)

where

//expressionN// is an integer constant, a string of alphanumeric characters enclosed by quotation marks " ", or a TOOL variable. If the TOOL variables are boolean, the strings "true" or "false" will be displayed. The cursor will be moved to a new line after this command is finished.

===== Mumble Command =====
The syntax of the mumble command is:

mumble (expression1, expression2, ...)

where

//expressionN// is an integer constant, a string of alphanumeric characters enclosed by quotation marks " ", or a TOOL variable. If the TOOL variables are boolean, the strings "true" or "false" will be displayed. All expressions will be displayed on the same line and the cursor will remain on the same line.  

===== Menu Command =====
The syntax of the menu command is:

menu (prompt, numItems, item1, ..., itemN, $choices[]; {defaultChoice={1..N}, {oneChoice={true,false}}})  

where

//prompt// is a string of alphanumeric characters enclosed by quotation marks " ". This string is the prompt that the user will see before the menu items.

//numItems// is an integer constant. This is the number of items that you would like to appear in the menu.

//itemI// is a string of alphanumeric characters enclosed by quotation marks " ". This will appear as an item in the menu indented from the prompt. The number of item strings specified must match numItems parameter.

//$choices[]// is an array of boolean TOOL variables. After the user has entered their menu choices, this array will contain true if the menu item has been selected and false if it has not. This array must be at least as big as the number of items in the menu.

//defaultChoice// is an integer that specifies which option is the default selection if the user does not make a selection.

//oneChoice// is an optional boolean flag that forces the user to choose only one option.

//**note:**// If both //defaultChoice// and //oneChoice// are used, defaultChoice must precede oneChoice.

=== Example ===
Code:

  boolean $sector[4]
  say ("")
  menu ("What sectors do you want to see? ", 4, \
  	"personal use", \
	"commercial use use light duty", \
	"commercial use use medium duty", \
	"commercial use use heavy duty", \
	$sector[])


Output:

{{howtos:toolcoding:menu_output.png}}