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
What it Does
Displays a simple modal panel containing a message and up to three buttons which the user may click. Returns the title of the selected button in the variable it.
When to Use It
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 three different alternatives.
The 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 ask command.
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 "Account" from list the unique items of myListOfChoices
Example:
answer "What would you like to drink?" from list ["Coffee", "Tea", "Beer", "Water"] allow multiple default "Coffee"
Syntax
answer {panelType} {Options}
Options:
{prompt | body | message}
prompt
with reply1 {or reply2 { or reply3 {or reply4}}}
[title | titled] titleExpr
[timeout | time out ] {after | in} duration
icon iconName
[default {answer} | answer] defaultSelection
{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 (rightmost) 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.
The order in which the prompt, replies, title, timeout, and icon 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).
For more information about the Answer command, see Using Ask and Answer.
ask
What it Does
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.
When to Use It
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.
Example
ask "Enter your name:"
Example
ask "How do you feel?" title "Greetings!"
Example
ask query with defaultAnswer title "Please Answer"
Example
ask password "Enter the secret code"
Syntax
ask
{password} {
Options
}
Options:
{
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
{from} list listOfChoices
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.
put
What it Does
When no destination container is specified, the put command displays text in the standard output.
When to Use It
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.
Example
put "Successfully loaded file " & fileName
Example
put n
Example
put "The area is: " & pi * radius^2
Syntax
put {
expr
{ ,
expr
...}}
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 Containers.
beep
command
What it Does
Plays the system beep sound.
When to Use It
Use the beep command to get the user’s attention or alert them to some occurrence.
Example
beep
Example
beep 5 -- really get their attention!
Syntax
beep {expr}
Expr can be any valid SenseTalk expression, yielding a number of times to beep.
play command
What it Does
Plays a sound file.
When to Use It
Use the play command to begin playing a system sound or other sound or music file.
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
Syntax
play
soundFile
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.
sound function
What it Does
Returns the name of the currently playing sound, or “done.”
When to Use It
Use the sound function to monitor the sound being played.
Example
wait until the sound is "done"
Syntax
the sound
sound()
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 displays a standard Save panel for the user to select a location in the file system and enter a new file name.
answer file command
What it Does
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.
When to Use 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”.
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"
Syntax
answer {multiple | single} file {Options}
Options:
{prompt} promptExpr
[title | titled] titleExpr
of type factor {or factor}...
with defaultFile
in [folder | directory] defaultFolder
allow multiple
{with} {button} label buttonLabel
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. 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 of 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 withdefaultFile 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.
answer folder, answer directory commands
What it Does
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.
When to Use It
Use the answer folder command any time you want the user to supply the name of a folder.
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”.
Example
answer folder "Select the working Directory:"
Example
answer multiple folders "Choose source paths" \
in folder "~/Documents"
Syntax
answer {multiple | single} [folder | directory] {Options}
Options:
{prompt} promptExpr
[title | titled] titleExpr
with defaultPath
in [folder | directory] defaultFolder
allow multiple
{with} {button} label buttonLabel
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 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.
ask file, ask folder, ask directory commands
What it Does
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.
When to Use 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. The existing file will not be removed or changed in any way, however. 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 ....
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
Syntax
ask [file | folder | directory] {Options}
Options {
prompt} promptExpr
[title | titled] titleExpr
of type requiredExtension
with defaultFile
in [folder | directory] defaultFolder
allow multiple
{with} {button} label buttonLabel
The simplest form of the ask file command is merely 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.