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: "ko", "jkgkjhkj g gdfg dfg"
       boolean: "You like it?", 1
       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$
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 "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 directory (folder) name, do

directoryName$ = chooseDirectory$: "Choose a directory to save all the new files in"
if directoryName$ <> ""
    for i to numberOfSelectedSounds
       selectObject: sound [i]
       Save as WAV file: directoryName$ + "/sound" + string$ (i) + ".wav"
    endfor
endif

A directory selector window will appear, with (in this example) "Choose a directory to save all the new files in" as the title. If the user clicks OK, the variable directoryName$ will contain the name of the directory that the user selected; if the user clicks Cancel, the variable directoryName$ 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 argument to endPause 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


© ppgb, March 17, 2017