Scripting 6.6. Controlling the user

You can temporarily halt a Praat script:

`pauseScript`: message
  suspends execution of the script, and allows the user to interrupt it. A message window will appear with the message (you can use the same argument list as with `writeInfoLine`) and the buttons Stop and Continue:

`pauseScript: “The next file will be ”, fileName$
`

The `pauseScript` function is useful if you want to send a simple message to the user, and you only want to ask the user whether she wants to proceed or not. More interesting interactions between your script and the user are possible with the pause window. In a pause window you can include the same kinds of arguments as in a form. Here is an extensive example:

`writeInfoLine: “script”
` `compression = 1
` `number_of_channels = 2
` `worth = 3
` `for i to 5
` `beginPause: “Hi”
` `comment: “Type a lot of nonsense below.”
` `natural: “Number of people”, 10
` `real: “Worth”, worth + 1
` `positive: “Sampling frequency (Hz)”, “44100.0 (= CD quality)”
` `word: “hi”, “hhh”
` `sentence: “lo”, “two words”
` `text: “shortText”, “some one-line text here”
` `text: 2, “longText”, “some scrollable text here, within a height of 2 lines”
` `boolean: “You like it?”, 1
` `infile: “Input file”, “hello.wav”
` `outfile: 2, “Output file”, “../out.txt”
` `realvector: 2, “Array of reals”, “(whitespace-separated)”, “20 80 60”
` `if worth < 6
` `choice: “Compression”, compression
` `option: “lossless (FLAC)”
` `option: “MP3”
` `option: “Ogg”
` `endif
` `optionmenu: “Number of channels”, number_of_channels
` `option: “mono”
` `option: “stereo”
` `option: “quadro”
` `comment: “Then click Stop or one of the continuation buttons.”
` `clicked = endPause: “Continue”, “Next”, “Proceed”, 2
` `appendInfoLine: number_of_people, “ ”, worth, “ ”, sampling_frequency, “ ”, clicked
` `appendInfoLine: “Compression: ”, compression, “ (”, compression$, “)”
` `appendInfoLine: “Number of channels: ”, number_of_channels$
` `appendInfoLine: “Short text: ”, shortText$
` `appendInfoLine: “Input file: ”, input_file$
` `appendInfoLine: “Array: ”, array_of_reals#
` `endfor
`

This example uses several tricks. A useful one is seen with `number_of_channels`: this is at the same time the value that is passed to `optionmenu` (and therefore determines the setting of the Number of channels menu when the window appears) and the name of the variable in which the user’s chosen value of Number of channels is stored (because the text “number_of _channels” is what you get by replacing the spaces in “Number of channels” with underscores and turning its first letter to lower case).

Your own pause windows are not likely to be as rich as the above example. For instance, the example has three continuation buttons (the second of these is the default button, i.e. the button that you can “click” by pressing the Enter or Return key). You will often use only one continuation button, for instance

`endPause: “Continue”, 1
`

or

`endPause: “Finish”, 1
`

or

`endPause: “OK”, 1
`

If your script shows multiple different pause windows, then it is in fact a wizard, and it becomes useful to have

`endPause: “Next”, 1
`

for most of them, and

`endPause: “Finish”, 1
`

for the last one.

The possibility of multiple continuation buttons can save the user a mouse click. The following script, for instance, requires two mouse clicks per sound:

`for %i to 20
` `Read from file: “sound“ + string$ (i) + “.wav”
` `Play
` `Remove
` `#beginPause: “Rate the quality”
` `#comment: “How good is the sound on a scale from 1 to 7?”
` `#choice: “Quality”, 4
` `#option: “1”
` `#option: “2”
` `#option: “3”
` `#option: “4”
` `#option: “5”
` `#option: “6”
` `#option: “7”
` `endPause: if i = 20 then “Finish” else “Next” fi, 1
` `appendInfoLine: quality
` `endfor
`

The following script works faster:

`for i to 20
` `Read from file: “sound” + string$ (i) + “.wav”
` `Play
` `Remove
` `#beginPause: “Rate the quality"
` `#comment: “How good is the sound on a scale from 1 to 7?”
` `quality = endPause: “1”, “2”, “3”, “4”, “5”, “6”, “7”, 0
` `appendInfoLine: quality
` `endfor
`

In this example, the 0 at the end of endPause means that there is no default button.

## File selection

If you want the user to choose a file name for reading (opening), do

`fileName$ = chooseReadFile$: “Open a table file"
` `if fileName$ <> “”
` `table = Read Table from tab-separated file: fileName$
` `endif
`

A file selector window will appear, with (in this example) Open a table file as the title. If the user clicks OK, the variable `fileName$` will contain the name of the file that the user selected; if the user clicks Cancel, the variable `fileName$` will contain the empty string (“”).

If you want the user to choose a file name for writing (saving), do

`selectObject: mySound
` `fileName$ = chooseWriteFile$: “Save as a WAV file”, “mySound.wav”
` `if fileName$ <> “”
` `Save as WAV file: fileName$
` `endif
`

A file selector window will appear, with (in this example) Save as a WAV file as the title and “mySound.wav” as the suggested file name (which the user can change). If the user clicks OK, the form will ask for confirmation if the file name that the user typed already exists. If the user clicks OK with a new file name, or clicks OK in the confirmation window, the variable `fileName$` will contain the file name that the user typed; if the user clicks Cancel at any point, the variable `fileName$` will contain the empty string (“”).

If you want the user to choose a folder (directory) name, do

`folderName$ = chooseFolder$: “Choose a folder to save all the new files in”
` `if folderName$ <> “”
` `for i to numberOfSelectedSounds
` `selectObject: sound [i]
` `Save as WAV file: folderName$ + “/sound” + string$ (i) + “.wav”
` `endfor
` `endif
`

A folder selector window will appear, with (in this example) Choose a folder to save all the new files in as the title. If the user clicks OK, the variable `folderName$` will contain the name of the folder that the user selected; if the user clicks Cancel, the variable `folderName$` will contain the empty string (“”).

## A non-pausing pause window without a Stop button

Especially if you use the pause window within the Demo window, you may not want to give the user the capability of ending the script by hitting Stop or closing the pause window. In that case, you can add an extra numeric argument to `endPause` (at the end) that denotes the cancel button:

`beginPause: “Learning settings”
` `positive: “Learning rate”, “0.01”
` `choice: “Directions”, 3
` `option: “Forward”
` `option: “Backward”
` `option: “Bidirectional”
` `clicked = endPause: “Cancel”, “OK”, 2, 1
` `if clicked = 2
` `learningRate = learning_rate
` `includeForward = ( directions = 1 or directions = 3 )
` `includeBackward = ( directions = 2 or directions = 3 )
` `endif
`

In this example, the default button is 2 (i.e. OK), and the cancel button is 1 (i.e. Cancel). The form will now contain no Stop button, and if the user closes the window, this will be the same as clicking Cancel, namely that `clicked` will be 1 (because the Cancel button is the first button) and the variables `learning_rate`, `directions` and `directions$` will not be changed (i.e. they might remain undefined).

## Pausing for a fixed time without a window

You can pause Praat for 1.3 seconds by saying

`sleep (1.3)
`

This is of course not about controlling the user, but it is mentioned here because this section is about pausing.

### Links to this page

- `pauseScript`
- pause window
- Scripting
- Scripting 6. Communication outside the script
- What was new in 5.1?
- What was new in 5.2?
- What was new in 5.3?