User Interaction in SenseTalk Scripting
You can write SenseTalk scripts that prompt for information during runtime. The following commands allow your SenseTalk script to interact with the user by displaying or requesting information.
Answer Command
Behavior: The answer command displays a simple modal panel containing a message and up to four buttons which the user may click. The from list option lets the user choose from a longer list of possible answers. As a modal panel, script execution is paused while the panel is displayed.
Use the answer command when you need to display short to medium-length messages in a modal panel, or to solicit input from the user in the form of a choice between two or more different alternatives. The basic answer command is ideal for situations where the user must make a yes/no or continue/cancel type of decision. For more complex choices use the from list option, or for open responses use the ask command.
Returns the title of the selected button or selected item from the list in the variable it.
Syntax:
answer {panelType} OptionsOptions:
{prompt | body | message} prompt
[title | titled] titleExpr
with reply1 {or reply2 {or reply3 {or reply4}}}
[timeout | time out] {after | in} duration
icon iconName
[default {answer} | answer] defaultSelection
{from} list listOfChoices
{allow} multiple
An optional panelType of information, question, warning, or error may be specified. The exact implementation of each panel type is up to the host application, but typically shows a related icon in the panel.
The prompt is an expression whose value will be displayed as the primary text in the panel. TitleExpr is the title which will be displayed in a larger font at the top of the panel.
Reply1, reply2, reply3, and reply4 are the labels that will be shown on the buttons at the bottom of the panel, with reply1 being the default button. The number of buttons shown will match the number of reply strings specified in the command. If no replies are specified, a single button labelled OK will be included.
If the timeout option is used, duration specifies the length of time (in seconds, if not explicitly specified) that the panel will be displayed waiting for user input. If the user doesn't respond to the panel within that time, it will be dismissed automatically. In that case, the variable it will be empty, and the result function will be set to a value indicating that the panel timed out.
The icon option may be used to supply a different icon to be shown in the panel. If it is used, iconName may be either the name of a known system icon, or the full path to an icon file.
If a listOfChoices is given, all of those choices will be displayed in the main part of the panel. The user may select one before clicking the "OK" button. If multiple is also specified, the user will be able to select more than one of the choices which will then be returned as a list.
The order in which the options are specified is flexible, and all of them are optional (except that at least one option must be supplied).
After execution of the answer command, the variable it will contain the title of the button that was clicked (or empty if the panel's timeout elapsed). If a listOfChoices was presented and the default button was clicked, it will contain the choice or list of choices that was selected by the user.
For more information about the answer command, see Using Ask and Answer.
Example:
answer "Great! You got " & pctRight &"% correct!"
Example:
answer "Go on?" with "Yes" or "No" title "DECIDE"
Example:
answer "How do you feel?" with "Great!" or \
"Okay" or "Really Lousy" title "Greetings!"
Example:
answer "What would you like to drink?" from list ["Coffee", "Tea", "Beer", "Water"]
Example:
answer "Account" from list the unique items of myListOfChoices
Related:
Ask Command
Behavior: Displays a modal panel containing a prompt string and a text entry field in which the user may type a response. A default response may be supplied. Returns the user’s answer in the variable it. As a modal panel, script execution is paused while the panel is displayed.
Use the ask command when an answer is required from the user which is not from a predetermined list of choices. Use the ask password command to request input that is hidden while it is being typed.
Syntax:
ask {password} OptionsOptions:
{prompt | question} question
[title | titled] titleExpr
[with {answer} | answer] presetAnswer
[hint | placeholder | place holder] placeholder
[message | body] {text} message
{with} [buttons | button {label{s}] label1 {[and | ,] label2}
[timeout | time out] {after | in} duration
icon iconName
Example:
ask "Enter your name:"
Example:
ask "How do you feel?" title "Greetings!"
Example:
ask query with defaultAnswer titled "Please Answer"
Example:
ask password "Enter the secret code"
The text value of question is displayed as the prompt above the input field in the panel. TitleExpr is the title, which will be displayed in a larger font at the top of the panel. The string value of the presetAnswer expression is displayed in the answer field as the default response. If placeholder is given, the placeholder value will be displayed in the answer field when it is empty and not selected. The message text will be displayed in the panel below the title.
If label1 (and optionally label2) are specified, they define the buttons on the panel, otherwise two buttons are presented at the bottom of the panel: Cancel and OK. If the user clicks the OK button (or presses return) the value in the answer field is put into the variable it. If the user clicks the Cancel button the value of the variable it is set to empty, and the result function returns "Cancel".
If the timeout option is used, duration specifies the length of time (in seconds, if not explicitly specified) that the panel will be displayed waiting for user input. If the user doesn't respond to the panel within that time, it will be dismissed automatically. In that case, the variable it will be empty, and the result function will be set to a value indicating that the panel timed out.
The icon option may be used to supply a different icon to be shown in the panel. If it is used, iconName may be either the name of a known system icon, or the full path to an icon file.
The order in which the options are specified is flexible, and all of them are optional (except that at least one option must be supplied).
After execution of the ask command, the variable it will contain the value entered in the field (or empty if the panel's timeout elapsed).
For more information about the ask command, see Using Ask and Answer.
Related:
Put Command
Behavior: When no destination container is specified, the put command displays text in the standard output.
Use the put command in this way when you want to display status information during a script without putting up a modal panel like the answer command would. The put command is also very popular during the development of a script for displaying the current value of variables at different points in the script.
Syntax:
put {expr {, expr ...}}
Example:
put "Successfully loaded file " & fileName
Example:
put n
Example:
put "The area is: " & pi * radius^2
Expr can be any valid SenseTalk expression. If multiple expressions are given, separated by commas, each is displayed on a separate line.
Only the simplest form of the put command is described here. For other uses of the put command, see Put - An Essential Command.
Beep Command
Behavior: Plays the system beep sound.
Use the beep command to get the user’s attention or alert them to some occurrence.
Syntax:
beep {expr}
Example:
beep
Example:
beep 5 -- really get their attention!
Expr can be any valid SenseTalk expression, yielding a number of times to beep.
Related:
Play Command
Behavior: Plays a sound file.
Use the play command to begin playing a system sound or other sound or music file. The script continues executing while the sound plays.
Syntax:
play soundFile
Example:
play "Glass" -- without full path, plays a system sound
Example:
play "~/Music/iTunes/iTunes Music/Billy Joel/Piano Man.mp3"
Example:
play stop -- stops the music
SoundFile can be any valid SenseTalk expression, yielding the name of a sound to play, or one of the special commands: pause, resume, or stop.
Related:
Sound Function
Behavior: Returns the name of the currently playing sound, or “done.”
Use the sound function to monitor the sound being played.
Syntax:
the sound
sound()
Example:
wait until the sound is "done"
Related:
Asking the User to Choose a File or Folder
There are several commands that interact with the user to allow them to select or specify particular files or folders in the file system that your script will work with:
The answer file and answer folder commands display a standard Open panel for the user to select an existing file or folder, respectively. The ask file and ask folder commands display a standard Save panel for the user to select a location in the file system and enter a new file name.
Answer File Command
Behavior: Displays an Open panel so the user may select an existing file, and returns the full path name of the selected file in the variable it.
Use the answer file command any time you want the user to supply the name of an existing file. You can then open the file (with the open command) or use it in other ways.
The full path name of the file selected by the user will be returned in the variable it. If multiple files were selected, a list is returned, with each file name selected by the user in a separate item in it. If no file is selected (that is, the user clicks the “Cancel” button in the panel), the variable it will be empty following the answer file command and the result function will return “Cancel”.
Syntax:
answer {multiple | single} file{s} OptionsOptions:
{prompt} promptExpr
[title | titled] titleExpr
[of | with] type{s} factor {or factor}...
with defaultFile
in [folder | directory] defaultFolder
allow multiple
{with} {button} label buttonLabel
Example:
answer file
Example:
answer file "Select Account File" with "Dec03"
Example:
answer multiple files "Choose Data Sets" in folder "/Users/mmalone/data"
Example:
answer file with button label "Select" of type "png", "tif", or "tiff" in folder "~/Pictures" title "Choose an Image"
The simplest form of the answer file command is answer file. The word multiple or single may be used before the word file to specify whether or not the user should be allowed to select multiple files at once. If not specified, only a single file may be selected.
A number of additional options may be specified as part of this command. None of these options is required, and they may be specified in any order, although no option may be specified more than once.
If the prompt or title options are specified, the expression given will be used as the title to be displayed at the top of the Open panel, on systems that support setting a title on the open panel. If not given, the word “Open” will be used. If both are specified, only the promptExpr will be used.
One or more file types may be specified using the type option. Several different types may be listed by using commas, the word or, or both between types. If this option is included, only files whose extension matches one of the specified types will be accepted (a file extension is the part of the file name following the last period in the name). File extensions may be specified with or without the period (e.g., “eps” and “.eps” are both acceptable). Specify empty or “” to include files without any extension.
If with defaultFile is specified, that file will be selected if it exists. If the value includes a folder as well as a file name, that will be the initial folder shown in the Open panel.
The in folder option specifies the initial folder whose contents will be shown in the Open panel.
If the label option is specified, buttonLabel is used as the label of the default button in the Open panel. If not specified, the button’s label will be "Open".
If allow multiple is specified, then the user will be able to select several files at once. This option is an alternative to the answer multiple files syntax.
Related:
Answer Folder, Answer Directory Commands
Behavior: Displays an Open panel so the user may select an existing folder, and returns the full path name of that folder in the variable it.
Use the answer folder command any time you want the user to supply the name of a folder.
Syntax:
answer {multiple | single} [folder{s} | directory | directories] OptionsOptions:
{prompt} promptExpr
[title | titled] titleExpr
[of | with] type{s} factor {or factor}...
with defaultPath
in [folder | directory] defaultFolder
allow multiple
{with} {button} label buttonLabel
Example:
answer folder "Select the working Directory:"
Example:
answer multiple folders "Choose source paths" \\
in folder "~/Documents"
The answer folder command is almost the same as the answer file command, except that the user will be presented with an Open panel which allows folders to be selected, rather than files.
A number of additional options may be specified as part of this command. None of these options is required, and they may be specified in any order, although no option may be specified more than once. See the option descriptions under the answer file command above. File type extensions may not be specified with this command.
The full path name of the folder selected by the user will be returned in the variable it. If multiple folders were selected, a list is returned with each folder name in a separate item of it. If no folder is selected (that is, the user clicks the “Cancel” button), it will be empty following the answer folder command, and the result function will return “Cancel”.
The value returned will end with a slash, unless the folderNamesEndWithSlash global property is set to false. The slash at the end makes it easy to create a full path name by simply appending a file name.
Related:
Ask File, Ask Folder, Ask Directory Commands
Behavior: Displays a Save Panel so the user may specify the name of a file or folder to create, and returns the full path name of the file in the variable it.
Use the ask file or ask folder command when you want the user to specify the name and location of a file or folder that will be created or overwritten by your script.
The full path name of the file name specified by the user will be returned in the variable it. If no file is selected (that is, the user clicks the “Cancel” button), the variable it will be empty following the ask file command, and the result function will return “Cancel”.
Note that, as with all standard Save panels, if the user selects an existing file, an alert panel will be displayed, asking whether the file should be replaced. If the user clicks the “Replace” button in this panel, the selected file name will be returned in the variable it. However, the existing file will not be removed or changed in any way. It is up to your script to remove the existing file, if possible, before creating a new one with the same name. You can check whether a file exists by using the there is a file operator, as in if there is a file fileName then ....
Syntax:
ask [file | folder | directory] OptionsOptions:
{prompt} promptExpr
[title | titled] titleExpr
of type requiredExtension
with defaultFile
in [folder | directory] defaultFolder
{with} {button} label buttonLabel
Example:
ask file "Enter output file name:"
Example:
ask file "Temporary file to create:" with "temp1"
Example:
ask file "Log Changes" of type ".mylog" in folder "logs"
Example:
ask folder "Enter new folder name:" in folder homeFolder
The simplest form of the ask file command is simply ask file. A number of additional options may be specified as part of this command. None of these options is required, and they may be specified in any order, although no option may be specified more than once.
If the prompt or title options are specified, the expression given will be used as the title to be displayed at the top of the Save panel. If not given, the word "Save" will be used. If both are specified, only the promptExpr will be used.
If the of type requiredExtension option is used, the Save panel will use the specified file extension as the type of file to be saved, and will ensure that the file name returned has that extension (a file extension is the part of the file name following the last period in the name). File extensions may be specified with or without the period (e.g., "eps" and ".eps" are both acceptable).
If with defaultFile is specified, the Save panel will come up with that name already entered in its file name field. If the value includes a folder as well as a file name, that will be the initial folder shown in the Save panel.
The in folder option specifies the initial folder whose contents will be shown in the Save panel.
If the label option is specified, buttonLabel is used as the label of the default button in the Save panel. If not specified, the button’s label will be "Save".
In the case of the ask folder command, the value returned will end with a slash, unless the folderNamesEndWithSlash global property is set to false. The slash at the end makes it easy to create a full path name by simply appending a file name.
Related: