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!"

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.

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

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:

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 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 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 July 02, 2020, at 02:51:55 PM.

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