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.

Examples

answer "Great! You got " & pctRight & "% correct!"

answer "Go on?" with "Yes" or "No" title "DECIDE"

answer "How do you feel?" with "Great!" or \

"Okay" or "Really Lousy" title "Greetings!"

Tech Talk

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

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.

Examples

ask "Enter your name:"

ask "How do you feel?" title "Greetings!"

ask query with defaultAnswer title "Please Answer"

ask password "Enter the secret code"

Tech Talk

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

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.

Examples

put "Successfully loaded file " & fileName

put n

put "The area is: " & pi * radius^2

Tech Talk

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

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.

Examples

beep

beep 5 -- really get their attention!

Tech Talk

Syntax: beep {expr}

Expr can be any valid SenseTalk expression, yielding a number of times to beep.

play

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.

Examples

play "Glass" -- without full path, plays a system sound

play "~/Music/iTunes/iTunes Music/Billy Joel/Piano Man.mp3"

play stop -- stops the music

Tech Talk

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.

Examples

wait until the sound is "done"

Tech Talk

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:

answer file

answer folder

ask file

ask folder

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

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”.

Examples

answer file

answer file "Select Account File" with "Dec03"

answer multiple files "Choose Data Sets" in folder "/Users/mmalone/data"

answer file with button label "Select" of type "png", "tif", or "tiff" in folder "~/Pictures" title "Choose an Image"

Tech Talk

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

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”.

Examples

answer folder "Select the working Directory:"

answer multiple folders "Choose source paths" \

in folder "~/Documents"

Tech Talk

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

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 ....

Examples

ask file "Enter output file name:

ask file "Temporary file to create:" with "temp1"

ask file "Log Changes" of type ".mylog" in folder "logs"

ask folder "Enter new folder name:" in folder homeFolder

Tech Talk

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 withdefaultFile 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.

 

This topic was last updated on November 20, 2019, at 03:32:06 PM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2020 Eggplant