Session 12
Flexible Input Forms

Pause Forms

If you need more flexibility than input forms provide you can use the pause form. You already know the simplest incarnation of the pause form (Useful Tools):

pauseScript: "Click Continue when you're done"

This statement draws a window like below and waits for the user to do something and then click Continue. If the user clicks Stop instead, the script is aborted and exits with an error message.

Ok, nice and handy, but not (yet) really flexible. To recreate the simple pause form shown above, we need three lines of code:

beginPause: "stop or continue"
    comment: "Click Continue when you're done"
endPause: "Continue", 1

The definition of a complex pause form starts with the keyword beginPause:, followed by an obligatory string argument (the window title), enclosed in double quotes. The definition ends with endPause:, followed by a button definition. We'll come back to the button definition in a minute. The stuff between beginPause and endPause is essentially the same as in simple input forms: Field types with a colon followed by one argument in the case of comment and two arguments in all other cases. Yes, right, you can have all the other field types known from simple input forms as well: Integer, real, natural, and positive; word, sentence, and text; boolean, choice, and optionMenu.

The following script illustrates the different field types and the slightly different syntax compared to input forms. If you want to see how the result looks, just copy & paste the code to the script editor and run it—looks familiar, right?

beginPause: "Input different types of data"
    comment: "Enter some data and see what happens."
    real: "Real number", -273.15
    positive: "Positive number", "373.15 (= a fine number)"
    integer: "Whole number", -76543
    natural: "Unsigned integer", 42
    boolean: "Want icecream", 1
    word: "Greeting", "Hello"
    sentence: "Phrase", "Hello World"
    choice: "Color", 1
        option: "red"
        option: "green"
        option: "blue"
    optionMenu: "Operating system", 2
        option: "Linux"
        option: "Mac OS X"
        option: "Windows"
endPause: "Continue", 1

As you can see, all field type declarations end with a colon, arguments are comma-separated, and string arguments are enclosed in double quotes. Unlike simple input forms, numeric arguments can be specified with or without quotes (in the example above, see declarations of positive vs. real, integer, natural, and boolean).

Compared to input forms, pause forms have important advantages:

1. Pause forms acknowledge procedural processing; all commands above beginPause are indeed executed before the pause form shows up.
2. More than one pause form per script is permitted.
3. Variables in pause forms definitions behave like everywhere else.
4. It's possible to declare more than one continuation button and you can get rid of the stop button.

We'll discuss (1) and (2) bellow, followed by (3) and (4) in separate sections.

Multiple Pause Forms

With input forms there's only one opportunity to ask the user for input, i.e. right at the beginning of the script. With pause forms you can ask whenever you want and as often as you want. More than one pause form per script means that you can have different pause form definitions across your script, but it's also possible to have one pause form appear multiple times if you put the pause form definition in a loop.

Consider a script that loads sound files from a directory, waits for the user to evaluate the sounds, and than writes the evaluated sounds back to the disk. The script provides 3 directories to save the evaluated sounds, good, decent, and poor, and asks the user to choose one before saving. Here's the load file loop, which should look familiar to you:

# create file list
list = Create Strings as file list: "SoundFiles", "sounds/*.wav"
# determine number of files
n = Get number of strings
# load files one by one
for i to n
    selectObject: list
    filename$ = Get string: i
    fileID = Read from file: "sounds/" + filename$
    Play

    # let the user evaluate the sound

    removeObject: fileID
endfor
removeObject: list

Now we insert the command to save the evaluated sound at the end of the loop, before removing the current sound object.

list = Create Strings as file list: "SoundFiles", "sounds/*.wav"
n = Get number of strings
for i to n
    selectObject: list
    filename$ = Get string: i
    fileID = Read from file: "sounds/" + filename$
    Play

    # let the user evaluate the sound

    # make sure that the current sound object is selected
    selectObject: fileID
    # save sound object to target directory
    Save as WAV file: target_Directory$ + "/" + filename$
    removeObject: fileID
endfor
removeObject: list

The selectObject command seems redundant, but what if the user does something during evaluation that de-selects the target sound? Remember: Redundant object selection is harmless, a missing selection may have serious consequences.

Setting the target directory is done with a pause form:

beginPause: "Set the target directory"
    comment: "Choose the appropriate directory for this sound."
    optionMenu: "Target Directory", 1
        option: "good"
        option: "decent"
        option: "poor"
endPause: "Continue", 1

The comment explains what the user should do, and optionMenu provides a menu to choose one of the three directories. "Target Directory" represents the variable that contains the chosen option. Later in the script, you can use the variable as target_Directory (numeric; index of the chosen option) or target_Directory$ (string; chosen option as it appears in the menu), i.e. initial capitals and spaces must be 'translated' the same way as input form variables. The second argument of optionMenu specifies the default option (1 = first option = good). This definition creates the following window:

That's fine, so we can use the code in the evaluation script. Where would you insert the pause form code? Remember, we want the script user to make a decision for every sound separately, not one decision for all sounds!

list = Create Strings as file list: "SoundFiles", "sounds/*.wav"
n = Get number of strings
for i to n
    selectObject: list
    filename$ = Get string: i
    fileID = Read from file: "sounds/" + filename$
    Play

    # show pause form for evaluation
    beginPause: "Set the target directory"
        comment: "Choose the appropriate directory for this sound."
        optionMenu: "Target Directory", 1
            option: "good"
            option: "decent"
            option: "poor"
    endPause: "Continue", 1

    # saving and removing
    selectObject: fileID
    Save as WAV file: target_Directory$ + "/" + filename$
    removeObject: fileID
endfor
removeObject: list

With this script we illustrated the first two advantages of pause forms compared to simple input forms: The dialog window appears multiple times (not only once) and it appears exactly when we need it (not at the very beginning of the script).