Winzipper/Winzipper_ISO.iso/multimedia/scala/install/DOC/SCRIPT.TXT

Text File | 1996-05-15 | 136.2 KB | 3,842 lines

Contents:

1.  The ScalaScript Language
2.  Sound EX Script Commands and Variables
3.  Input EX Script Commands
4.  Time Script Functions and Variables
5.  MPEG EX Script Commands
6.  Screen EX Script Commands and Variables




-------------------------------------------------------------------------------

1.  The ScalaScript Language
============================

This is a discussion of the ScalaScript language and its usage.

It is important to understand that the ScalaScript language is not a
traditional procedural (imperative) programming language. Commands in
a ScalaScript script are not necessarily executed one after another,
like a Basic or C program. Rather, a ScalaScript script is a
description of an application and its components, much like a
description in English. The ScalaScript parser and the EX modules read
this description and build a model that can be used to play or author
the script.

Also, keep in mind that the ScalaScript language was designed primarily to be
authored in a graphical user interface. It would certainly look different if it
was intended to be used as a programming language.

Example Scripts
---------------

First, a few sample scripts and their ScalaScript descriptions will be
presented.

Simple Picture Sequence
-----------------------

The first example script consists of four event objects; one Block that
contains the full script and three atoms placed in the Block's Sequence list.
In the ScalaScript language, this script could be described with the following
lines:

    !ScalaScript
    EVENT
      Sequence:
        PICTURE (":C/PICTURES/PICTURE1.BMP");
        PICTURE (":C/PICTURES/PICTURE2.BMP");
        PICTURE (":C/PICTURES/PICTURE3.BMP");
    END

Note that the containing Block is often referred to as the "parent" of the
Events that the Block contains, and that the Events within the Block are
often referred to as "sub-events" of the Block.

Sub-events are by default placed in the parent Block's Sequence list. In this
case, the PICTURE events must go into the Sequence list rather than the Group
list. This is because events in the Group list are played in parallel, which
doesn't make much sense for these events (they should be played sequentially).
Since events default to the Sequence list, the Sequence: keyword is optional
here.

The PICTURE command used here, which an example command supported by some
external EX, requires one parameter: the name of the picture file. Note how
command parameters are enclosed in parentheses. A file name is a string, which
has to be enclosed in double quotes ("). Also note that the ScalaScript language
can use MMOS syntax for path names, which is slightly different from MS-DOS.
However, standard MS-DOS path names are supported.

As can be seen from the example, commands are terminated by semicolons (;).

Simple Page Sequence
--------------------

The next example script uses Blocks to Group related events together:

    !ScalaScript
    EVENT
    Sequence:
        :Page1 EVENT
        Group:
            PICTURE(":C/PICTURES/PICTURE1.BMP");
        Sequence:
            TEXT(120,40,"This is our");
            TEXT(120,60,"first script");
            TEXT(120,80,"with text");
        END

        :Page2 EVENT
        Group:
            ANIM(":C/ANIM/ANIM1.FLC");
            SOUND(":C/MUSIC/SONG1.MID");
        Sequence:
            TEXT(120,350,"You can put text on animations, too");
        END
    END

The EVENT...END commands are used to define Blocks.

Events may be named by proceeding them with a label. The label is an identifier
that is prefixed by a colon. Note that this is an identifier, not a string.
Identifiers must follow stricter rules than strings (see below).

The label attaches to the first event that follows its definition. Therefore,
any label must precede some event. Note that certain commands contain internal
labels and a label should not be placed before these commands. These commands
are those that define named entities, such as variable declarations or style
commands.

Also, note how the PICTURE, ANIM and SOUND commands are placed in their parents'
Group list in this example. The items in a Group list are played in parallel and
are active throughout the execution of the Block's Sequence list.

Simple Chapter Sequence
-----------------------

The EVENT...END commands can be nested any number of levels:

    !ScalaScript
    EVENT
        :Chapter1 EVENT
        Sequence:
            :Page1 EVENT
            Group:
                PICTURE(":C/PICTURES/PICTURE1.BMP");
            Sequence:
                TEXT(120,40,"Some text");
            END
            :Page2 PICTURE(":C/PICTURES/PICTURE2.BMP");
            :Page3 PICTURE(":C/PICTURES/PICTURE3.BMP");
        END

        :Chapter2 EVENT
            :Page1 EVENT
            Group:
                PICTURE(":C/PICTURES/PICTURE4.BMP");
            Sequence:
                TEXT(120,40,"Some text");
            END
        END
    END

Note that it may not be desirable to nest the script a great deal, even though
it is possible. Nested Blocks restrict the access to Events defined within
them. It is often useful to be able to jump directly to any page from any point
in the script. This is not possible if the script uses chapter nesting as shown
above.

Lexical and Syntax Rules
------------------------

Since the arguments of most commands and functions, as well as the indices of
many arrays, are parsed by EX modules, the Player cannot control the lexical
rules in all instances. For instance, in these sample commands, arrays and
functions the parsing within the parenthesis or square brackets is handled by
the EX:

    mx129.play("test", rate(100), delay(long), start(true));
    a = channel_value(1, 17, force(true)) + channel_offset[1, current_channel(true)];

It is assumed that EX implementors will follow the standards in all cases. Not
doing so should be considered an error in the EX implementation.

ScalaScript File Identifier
---------------------------

The first 12 characters of a ScalaScript file must be "!ScalaScript" (without
the quotes.) This identifies the file to the Player as a valid ScalaScript file.
This keyword must be before any comments, commands, white space or any other
characters. It must be on its own line (the first line of the file).

White Space and Comments
------------------------

The ScalaScript language ignores all white space, such as spaces, carriage
returns, line feeds and tabs. Any string of these white space characters is
treated as a single separator character in parsing. That is, this script:

    !ScalaScript
    EVENT Group: integer(x); Sequence: x=x+1; END

Is equivalent to this script:

    !ScalaScript
    EVENT
    Group:
        integer(x);
    Sequence:
        x=x+1;
    END

There are two types of comments in ScalaScript: block comments and line
comments. Block comments delimit a range of characters defined by a block
comment introducer ("/*") and a block comment terminator ("*/"). All characters
within a block comment are ignored including the block comment introducer and
line comment introducer.

    !ScalaScript
    /* this is a block comment */
    Event
    /* this is a comment.  It may appear anywhere within the file,
    except on the first line.  The everything within the block is ignored.
    */
    End
    /* another block comment */

Line comments are introduced by the line comment introducer ("//"). All
characters following the line comment introducer up to the next end of line
character are ignored.

    !ScalaScript
    // this is a comment
    Event
    Sequence:                      // this is a comment.
        my.command(1,2,test(on));  // another comment.
    End
    // this is a comment.

Comments do not nest.

Case
----

Scripts are case insensitive, that is "WHILE" is equivalent to "while".

    /* these three lines are equivalent */
    DISPLAY(STYLE(DISPLAY1));
    Display(Style(Display1));
    display(style(display1));

Labels
------

Labels are defined by a leading colon.

    :cmd_label command();                   // command with label.
    :my_event  event...end                  // block with label.

Labels can collide with other names (variables, styles, etc.).

Labels attach to the next event. Labels that do not have a following event are
ignored (before END, 2 sequential labels).

Disable
-------

Events (commands or blocks) may be disabled by placing the word "disabled"
in front of them.  The "disabled" keyword follows any label, but preceeds the
event or block.

    Disabled my_command(1, foo(on));        // disabled command.
    :my_label disabled cmd();               // disabled command with label.
    :my_event disabled event...end          // disabled block with label.

Identifiers
-----------

Identifiers are used to denote command names and event names (including labels,
variable names and function names.) Identifiers must start with one of the
following characters:

    A-Z, a-z, _ (underscore)

Otherwise, an identifier can contain any number of the following characters:

    A-Z, a-z, _ (underscore), 0-9, . (dot)

Identifiers are not case-sensitive.

Numerals
--------

Numeric literals can be in decimal, hexadecimal or binary form, for example:

    4711        (decimal)
    $7f         (hexadecimal)
    %11010111   (binary)

Numerals are 32-bit signed values. The decimal form uses a minus sign to denote
negative numbers, while the hexadecimal and binary forms use twos-complement.
Hexadecimal numbers are not case sensitive.

Strings
-------

String literals are always enclosed with double quotes ("). ScalaScript imposes
no limit to the length of a string.

The ScalaScript language uses the caret (^) as an "escape" character, to prefix
control codes within a string:

    ^n    New Line
    ^r    Carriage Return
    ^t    Tab
    ^"    Quote
    ^^    Caret
    ^     At end of line: continue string on next line
    ^xNN  Embed any ASCII code NN (hexadecimal 00-FF)

Boolean
-------

Boolean literals may be written in two forms:

    TRUE, FALSE
    ON, OFF

With TRUE being equivalent to ON and FALSE being equivalent to OFF. The two
forms may be used interchangeably.

Parenthesis, Separators and Terminators
---------------------------------------

    Parentheses   ( )   used to enclose command an function parameter lists.
                        They are also used in expressions for grouping.
    Brackets      [ ]   used to enclose index values of an array variable.
    Commas        ,     used to separate parameters in a parameter list.
    Semicolons    ;     used to terminate commands.
    Colons        :     used with certain keywords and with labels.

Operators
---------

For the use in integer arithmetic expressions, the ScalaScript language
recognizes the following operators:

    *    multiplication
    **   Power
    +    addition
    -    subtraction or negation
    /    division
    =    assignment
    MOD  Modulus

Boolean operators are:

    <    less-than
    <=   less-than or equal-to
    <>   not equal-to
    =    equality
    >    greater-than
    >=   greater-than or equal-to
    AND  logical and
    NOT  logical not
    OR   logical or

String operators are:

    +    Concatenation
    =    Assignment

Expressions
-----------

Primitives
----------

The ScalaScript language itself recognizes a few keywords - or primitives:

    {              Block introducer, equivalent to EVENT.
    }              Block terminator, equivalent to END.
    Boolean        Declare one or more Boolean variables.
    Chain          Load and execute a script file. Never return.
    Else           Conditional execution of the current Block if the
                   preceding IF/ELSEIF returned FALSE.
    ElseIf         Conditional execution of the current Block if the
                   preceding IF/ELSEIF returned FALSE and condition evaluates
                   to TRUE.
    End            Block terminator, equivalent to }.
    Event          Block introducer, equivalent to {.
    EX             Open a specified EX.
    Exit           Exit one or more Blocks.
    GoTo           Goto a specified event by name. Pushes a return address
                   (for the RETURN command) if Bookmark(TRUE) is specified
                   as an option.
    Group:         Place events that follow into the Group list of the
                   current Block.
    If             Conditional execution of the current Block if the
                   condition evaluates to TRUE.
    Integer        Declare one or more integer variables.
    Jump           Jump a number of events forward or backward.
    OnNotification Perform an action when a variable changes.
    Quit           Exit a script and return to the caller (from
                   Script command.)
    Resources:     Place events that follow into the Resources list of the
                   current Block.
    Return         Return to the event following the last executed goto that
                   pushed a bookmark. Only returns to GOTOs that set
                   Bookmark(TRUE).
    Script         Load and execute a script file. Continue in this file after
                   loaded file exits.
    Sequence:      Place events that follow into the Sequence list of the
                   current Block.
    String         Declare one or more string variables.
    Until          Repetitive execution of the current Block until the
                   condition becomes TRUE.
    Use            Execute a named Block "in place".
    While          Repetitive execution of the current Block while the
                   condition is TRUE.

Keyed Values
------------

MMOS uses the concept of keyed lists to create self-identifying data which is
often used in parameter lists (see the MMOS document for more information on
keyed lists). Not surprisingly, the same concept can be used directly in the
ScalaScript language. The advantages of using keyed values as ScalaScript
command parameter are the same as when programming in C under MMOS:

Command parameters can be optional. The caller specifies only the parameters he
is interested in and lets the command use default values for the rest.

The script becomes more readable, as each keyed value is preceded by a
explanatory "key."

Using keyed values ensures script compatibility between different software
versions. New optional parameters can be added with keys, without changing the
command syntax.

The ScalaScript language primitives do not use keyed values, because they have
very few, required parameters. Keyed values are more useful for certain EX
commands. For example, consider a command to control sound. In its simplest
form, it would just have one parameter; the name of the file to play.
Additionally, one might add parameters to set the sound's volume, panning,
pitch, fade-in time, fade-out time and so on. Using keyed values, the command
could look like this:

    SOUND(":C/MIDI/TOCCATA.MID");

or, like this:

    SOUND(":C/MIDI/TOCCATA.MID",Volume(24),Pan(-5),FadeOut(10));

In these examples, the first parameter - the file name - is fixed. Following is
a keyed list of parameters, which may be empty or contain any number of keyed
values. Now, if a future version of the Sound EX adds a new option to control,
say, a real-time digital reverb effect, it would just add a new key:

    SOUND(":C/MIDI/TOCCATA.MID",Reverb(10));

The new EX would play old scripts without special handling. The old Sound EX
would even be able to play a script created with the new EX. If the Sound EX was
programmed to ignore unknown keys, it would just skip the Reverb() key and
happily play the file without reverb.

It is possible to have more than one value per key, for example:

    BRUSH(120,400,":C/GRAPHICS/LOGO.BMP",Resize(48,54));

It is even possible to have keys that contain other keys:

    BRUSH(120,400,"LOGO.BMP",bevel(on,size(4)));

The ScriptParser class offers methods that ease the parsing of keyed lists.

Event Names
-----------

There are occasions when references to specific events are needed. For example:

    Branch events (GOTO, EXIT, JUMP, USE)
    Expressions with variables.
    Named styles.

It has already been shown how to name an event with the ":name" construct:

    :foo event                // a Block with the name "foo"
    Group:
        integer(my_var);      // a variable object with the name "my_var"
    Sequence:
        :bar text("hello");   // an event with the name "bar"
    end

All atoms may have names, some of them require names. For instance, variable are
not useful unless they are named.

Note that certain commands accept an event name through a notation different
than the ":name" construct described above. Variables, for instance, take their
name as a parameter to the declaration of the variable. This is usually only
done when the name is required, as it is for a variable.

Name Collisions
---------------

It is possible for event names to collide under certain circumstances as they
are used for more than one purpose in scripting. Event names are currently used
for three reasons:

Labels         - Used as targets for branching.
Variable Names - Allow variables to be referenced as parameters or in expressions.
Style Names    - Allow defined styles to be created for text and other elements.

When writing or authoring scripts, one must bear in mind that all of these names
use the same name space. Specifically, the use of a name in one area (as a
variable name, for instance), may interfere with the use of that same name in
another area (as a label, for instance). The best policy is to keep all names
within a script unique.

Attaching Names to Events
-------------------------

When the script exists in memory as an object hierarchy, labels are maintained
as part of the event that they name. The question is, how are these names
represented in the ScalaScript language? There are three cases to consider here:
Labels, variables and styles.

Labels, as previously mentioned, are described using a leading colon. In
ScalaScript, the label precedes the event to be named:

    :TestLabel
    EVENT        // this event (a Block) will take the name "TestLabel"
    END

Names defined this way should not be used before variable definitions or style
definitions.

Variables contain the label name internal to the definition. For instance, the
definition:

    INTEGER(my_var);

can be thought of as creating a labeled integer variable:

    :my_var INTEGER_VARIABLE(); // for example only, can't really do this.

That is, the variable definition creates a variable instance with the given
name. Having a single variable definition statement that declares multiple
variables (INTEGER(x,y,z);) is equivalent to having multiple labels with
multiple variable entities. This explains why variable names and labels can
collide, they are really using the same internal mechanism for their
implementation.

Styles, such as those implemented by the elements in the Screen book, are
implemented in a similar way to variables. The label name is given internally to
the definition:

    TextStyle(my_style, font("helvetica 20"), face(on, pen(7)));

defines a text style with a specific set of attributes (font and color). This is
equivalent to the statement:

    // not real, for example only.
    :my_style TextStyle(font("helvetica 20"), face(on, pen(7)));

except in the actual implementation, with the name given in the command, the
event name is required. That is, by placing the event name inside of a command
implemented by an EX, that name becomes required. This means that when a style
is defined it must have a name.

Scope
-----

The scope of an event - whether it is a Block, a variable or an atom -
determines the part of the script where the event name is visible. A reference
to an event may only be made within its scope. Scope of a name is determined by
the following rule:

Part 1: An event name's scope consists of all events within the Block in which
the name is defined, including sub-events that are nested within that Block.

Part 2: If a reference is made to an event name that has multiple definitions
that all meet Part 1 of this rule, the name whose parent Block is "closest" to
the reference will be used. Here "closest" means "shortest path".

A few examples to clarify this rule:

    :Chapter1 EVENT
      Sequence:
        :Page1.1 EVENT
            :
        END
            :
    END

    :Chapter2 EVENT
      Sequence:
        :Page2.1 EVENT
            :
        END

        EVENT(Page2.5)
            GOTO(Page2.1);     // Goto number 1
            GOTO(Chapter2);    // Goto number 2
            GOTO(Chapter1);    // Goto number 3
            GOTO(Page1.1);     // Goto number 4
        END
    END

The four alternative GOTOs labeled 1-4 are branch events with references to
other events:

The GOTO(Page2.1) branch is within the scope of Page2.1 as Page2.1 is defined
within the Block that contains the GOTO event.

The GOTO(Chapter2) branch is within the scope of Chapter2 as Chapter2 is defined
within the root Block, which contains all events in the script.

The GOTO(Chapter1) branch is within the scope of Chapter1 for the same reason as 2.

The GOTO(Page1.1) branch is not within the scope of Page1.1 and is therefore
illegal. This is because Page1.1's parent is Chapter1, which is not an ancestor
of the GOTO event.

Now an example that demonstrates the rule's second part:

    :Chapter1 EVENT
      Sequence:
        :TitlePage EVENT       // Note {1}.
            :
        END
            :
    END

    :Chapter2 EVENT
      Sequence:
        :TitlePage EVENT       // Note {2}.
            :
        END
        :Section2.1 EVENT
          Sequence:
            :TitlePage EVENT   // Note {3}.
                :
            END
                :
            GOTO(TitlePage);
        END
    END

Here, there are three events named TitlePage. The first part of the scope rule
eliminates {1} as it is not contained within the Block in which the name is
defined. The second two are both pass part one of the rule, so the Player must
choose between them. It uses the second part of the rule to resolve any
conflicts. The path from the GOTO to {3}'s parent is shorter than the path to
{2}'s parent, therefore, the GOTO is within {3}'s scope.

Binding
-------

There are two possible methods of finding an event name in a script given a
reference to that name:

Static binding - or reference by connector - means that the binding is done when
the script is loaded. The reference is established by a Connector such that
there is no need to search for a named event during playback. The connection
does not change during the entire playback of the script.

Dynamic binding - or reference by name - means that the binding is done during
playback of the script. Every time the event is needed, the player must search
the script for an event with the given name. There are actually other types of
dynamic binding, an event can be referenced by relative position in the Sequence
(JUMP) or by exiting a certain number of Blocks (EXIT).

Static binding is fast compared with dynamic binding. There is no searching for
the target event or computing the location of the name at run time. However, the
referenced event will always remain the same regardless of the execution of the
script.

Dynamic binding is more flexible, but is slower and often not necessary. Dynamic
binding only matters where a single name reference may be accessed from more
than one place in the script. For instance, suppose a string is created that
references a variable:

    event
    Group:
        Integer(x);   x   = 3;
        String(str);  str = "x is !x";
    ...

And then, within that script there are two different uses of that string:

    ...
        EVENT
        Group:
            integer(x);
        Sequence:
            x=100;
            TEXT(10,20,str);
        end
    ...
        EVENT
        Group:
            integer(x);
        Sequence:
            x=9123;
            TEXT(10,20,str);
        end
    ...

If the string uses static binding internally, then it will bind the value of x
to 3 when the script is parsed. When the script is run, it will print "x is 3"
twice. If the string uses dynamic binding internally, then each use of the
string (once in each of the TEXT commands) will bind when they are run. This
means that the script will print "x is 100" and "x is 9123".

In ScalaScript, the GOTO and USE commands use static binding, as do variables
used in expressions. The JUMP and EXIT commands use dynamic binding, as does
variable substitution in strings ("!-expressions").

Note that where a resource is called from does not change the binding of names
in that resource. This is best shown through examples:

    event
    Group:
        integer(x);
        x = 100;
    Sequence:
        use(foo);
        event
        Group:
            integer(x);
            x=123;
        Sequence:
            use(foo);
        end
    Resources:
        :foo text("x is !x");
    end

This script will print "x is 100" twice. The resolution of the name "x" does not
happen from where the resource is used, it happens from where the resource is
defined in the script. Therefore, the name "x" referenced in the Resources list
will be found at the outer level regardless of whether static or dynamic binding
is used.

Or, look at this script:

    event
    Sequence:
        event
        Sequence:
            use(foo);
        Resources:
            :bar text("inner level");
        end
    Resources:
        :foo goto(bar);
        :bar text("outter level");
    end

This script will print "inner level". Again, this is because the GOTO is
resolved from its actual location in the script and not where it is used. This
has nothing to do with static vs. dynamic binding, but is determined solely by
the way resources are handled.

Constructing Scripts
--------------------

A script consists of a series of "events" or statements. A statement might look
like the following:

    Display(style(display1));
    Text ( 10, 10, "Hello, world!" );
    While(x = 1);
    OFFSET( -32, 0 );
    Integer(temptime,timeofday,timeoffset[20]);
    temptime = timeofday + timeoffset[12];
    else();

Where the semicolon terminates each statement.

Parameters to commands are enclosed in parenthesis and multiple parameters are
separated by commas. Parameters may include named options such as this TEXT
command which has a Style() and an Outline() option:

    Text(0, 0, "Outline", Style(t2), Outline(on, Thickness(2), Fill(Pen(1))));

Note that options may be embedded within options as in Outline(). This may go
arbitrarily deep. For instance, the Text() command shown has an Outline() option
which has a Fill() option which has a Pen() option.

In addition to commands, scripts may use variables, array variables and
functions. Most variables and arrays must be declared, although there are
built-in variables (often added by EX modules) that are available without
declaration. Variables and functions are often used in expressions:

    foo = temp[100] + random(1,10);

Variables that are created within the script must be declared before use:

    Integer(temp[200]);

Expressions may be used in place of command/function arguments, and that they
also may be used in strings:

    // substitute the variables x and y in the string, plus use an expression.
    string_var = "X value is !x, Y value is !y, product is !(x * y)";
    Text(x+3,y-100,string_var);

The substitution of variables in strings is automatic, but the handling of
expressions in EX command arguments must be explicitly handled by the EX.

Any command may be labeled, which binds a name with an event. A label consists
of an identifier preceded by a colon. The event following the label takes the
name of the label:

    :one echo("hello^n");
    :two
    a = a + 1;

White space does not matter. In the first statement the echo() is given the name
"one" and in the second statement the assignment is given the name "two".

Labels are primarily used for execution control, that is, the script may GOTO an
event with a name rather than calculating the offset of the target event. This
makes the target event position independent.

A number of events may be grouped into blocks using the EVENT...END construct. A
block of statements may be used anywhere a normal statement is allowed.

    event
        echo("hello^n");
        Text(5,235,"Practice makes perfect.");
    end
    :page1 event
        /* stuff */
    end

Note that for the 'page1' label, the label applies to the block, not to one of
the events in the block.

Blocks
--------

Blocks of statements created with the EVENT...END construct are known as
Blocks. A script consists of a single Block contained in a file. Thus, a
script might be:

    Event
        /* commands and stuff here. */
    End

Note that on the PC, all scripts must begin with the text "!ScalaScript", so the
minimal script would be:

    !ScalaScript
    // This is the minimal ScalaScript script.  Note that nothing is allowed
    // to appear before the !ScalaScript introducer (no comments, blank lines,
    // etc.  This script doesn't do anything.
    EVENT
    END

Blocks are divided into three sections: The Group list, the Sequence list and
the Resources list. By default, commands go into the Sequence. To place commands
into other sections, that section must be explicitly named. The sections are
named as follows:

    :my_Block EVENT
    Group:
        /* Group stuff here */
    Sequence:
        /* Sequence stuff here */
    Resources:
        /* Resources stuff here */
    END

The sections may appear in any order, but are executed in a very well-defined
sequence. The Group is executed first, and all events in the Group are executed
in parallel.

The Group also gives scope to events. Specifically, events in the Group remain
active until the Block is exited. This means that items created in the Group
are guaranteed to exist throughout the execution of the Block's Sequence list.
For instance, variables declared in the Group list of a Block are available
anywhere within that Block.

Generally, Blocks are not placed within the Group list of another Block. If
a Block is placed into the Group of another Block, then only the Group of
the inner Block will be played (the Sequence and Resources lists are ignored).
The Sequence of a Block is executed after the Group, although commands in the
Group have a chance to clean up after the Sequence has finished. Events in the
Sequence are executed sequentially.

The Resources list is just like the Sequence list, but its events are never
executed unless explicitly called.

Execution Control
-----------------

Execution of a Block may be controlled through the IF, ELSEIF, ELSE, WHILE and
UNTIL statements. These statements are put into the Group list of the Block
and they control the execution of the entire Block. For instance, the IF
statement allows a Block to execute only if the condition is true:

    EVENT
    Group:
        if (condition);
    Sequence:
        /* stuff to execute if condition is true */
    END

Blocks that use if/elseif/else must be contiguous, although white space and
comments between the Blocks does not matter. For instance:

    event
    Group:     if (condition);
    Sequence:  // execute if condition is true.
    end
    event
    Group:     elseif (condition);
    Sequence:  // execute if 'if' was false, but elseif is true.
    end
    event
    Group:     else ();
    Sequence:  // execute if 'if' and 'elseif' are false.
    end

The WHILE statement repeats the execution of the Block while the condition is
true.

    EVENT
    Group:
        while (condition);
    Sequence:
        /* stuff to execute while condition is true */
    END

The UNTIL statement repeats the execution of the Block until the condition is
true.

    EVENT
    Group:
        until (condition);
    Sequence:
        /* stuff to execute until condition is true */
    END

Execution order in a script may be controlled using the GOTO, USE, JUMP, EXIT,
QUIT, RETURN, SCRIPT and CHAIN commands.

GOTO is used to transfer control to a named event.

    goto(name);
    ...
    :name echo("this is a test^n");
    /* execution continues here */

The GOTO command by default does not push a return address for the RETURN
command. However, a return address may be set by using the Bookmark(TRUE)
option. This allows for scripts like this:

    GOTO(foo, Bookmark(TRUE));
    ...
    :foo
    // do stuff here.
    return;

The USE command executes the named event, then returns when the event completes.
Note that the named event may be a Block, in which case the entire Block
will be executed. Often, the "USEd" event is kept in the Resources list, but
this is not required (it may be in the Sequence list).

    use(name)
    /* execution continues here */
    ...
    :name echo("this is a test^n");

    Sequence:
        use(res)
        /* execution continues here */
        ...
    Resources:
        :res event
            /* do everything in this event, then return */
            echo("this is a test^n");
        end

The EXIT command may be used to return from a "USEd" resource before the
end of that resource:

        use(res)
        ...
    Resources:
        :res event
            /* return from the resource before the end. */
            exit(1);
            ...
            echo("this is a test^n");
        end

JUMP is used to jump a number of events forward or back.

    jump(2);
    jump(-5);

EXIT is used to exit from the current block. This may cause the currently
executing script to exit, which would return control to the calling script.
If the current script is the top-level script, then the player terminates.
Note that the EXIT command takes a parameter that indicates the number of
blocks to exit:

    exit(1);
    exit(5);

RETURN is used to return to a previous GOTO that has pushed a return address.

    return();

ONNOTIFICATION is used to set-up notification on a specific variable. When
the variable changes value, a specified action is taken. The notification
remains in effect until the variable or the ONNOTIFICATION command go out
of scope.

    OnNotification(variable, goto(foo));
    OnNotification(my_var, use(foo));

SCRIPT is used to load another file and then return when it is done.

    Script(":scala/scripts/test.scr");
    /* execution continues here when test.scr is done. */

QUIT will exit one or more scripts and return to the caller. If a script calls
another script with the SCRIPT command, and that script calls a third, then the
third script may return to the first by executing the command QUIT(2);

    quit(1);
    quit(5);

CHAIN is used to load another file and never return.

    Chain(":scala/scripts/test.scr");
    /* execution never returns from test.scr. */

The EX statement is used to load EX modules. This makes commands available to
the executing script. This statement is often used in the Environment to load EX
modules for the script.

    EVENT
    Group:
        EX ("button.ex");
        EX ("example.ex");
        EX ("console.ex");
        EX ("debug.ex");
        EX ("screen.ex");
        EX ("timing.ex");
        EX ("touch.ex");
    END

Variables
---------

Variables of three types may be declared: BOOLEAN, INTEGER and STRING. Variables
must be declared before they are used (unless they are built-in). Variables must
be declared in the Group section of a Block. The scope of the variable is the
containing Block.

    EVENT
    Group:
        BOOLEAN(bool_1, bool_2, bool_3);
        INTEGER(int_1, int_2, int_3);
        STRING(str_1, str_2, str_3);
    Sequence:
        /* do stuff here */
    END

These three types also allow simple arrays to be declared:

    BOOLEAN(bool_array[10]);
    INTEGER(int_arr[10]);
    STRING(my_str[10]);

Boolean variables may take on any of the following values: TRUE, FALSE, ON or
OFF. Note that TRUE and ON are equivalent, as are FALSE and OFF.

    Group:
        BOOLEAN(bool_1);
    Sequence:
        bool_1 = TRUE;

Integer variables are 32-bit, signed numbers. Decimal numbers are the default.
Hex numbers are introduced with the dollar sign ($) and binary numbers are
introduced with the percent sign (%).

    Group:
        INTEGER(int_1);
    Sequence:
        int_1 = 1;
        int_1 = $7F;
        int_1 = %01011;

Strings are contained in double-quotes and can contain a number of special
control characters:

    Group:
        STRING(str_1);
    Sequence:
        str_1 = "Hello^tThis is a test^n";

Strings may also contain variables that are expanded for display. The variables
or expressions are introduced with the bang (!) operator:

    Text(1,1, "X is !x, Y is !y, array index 10 is !(array[10])");

Note that parenthesis must enclose the expression if it is anything other than a
simple variable. These are valid:

    !my_var
    !(my_var)
    !(a + 1)
    !(my_array[10])
    !(my_function(a,b,10))

Format strings allow integer variables to be printed out with formatting. This
allows for fixed width fields, leading plus or minus signs, and leading or
trailing zeros. For example:

    "This is a test !(my_var, ^"###.##^") of a format string"

This will build a string representation of an integer variable based on
information in the format string.

The FORMAT function may also be used to format integer values:

    str_var = Format("###.##", int_var);

Format strings may be constructed as follows:

    "####" will print an integer, 4 digits wide:

        12345        (too wide, grows freely)
        1234         (fits fine)
         234         (shorter number is padded with spaces)
          34
           4
          -4         (negative numbers just pick up a minus sign)
         -34

    "0###" will print an integer with leading zeroes:

        1234         (fits fine)
        0234         (padded with zeroes)
        0034

    "#0##" will fill with leading zeros all but the first digit:

        1234         (fits fine)
         234         (leftmost place isn't supposed to be zero-filled)
         034         (now we get zeroes)

    "##.##" will print an integer as a fixed-point number based on the fractional
    digits given:

        12.34        (integer 1234 prints like this)
         2.34        (leading zeroes trick would work here if you wanted)
         2.3         (trailing zeroes dropped, but see below!)
          .3         (not even one leading zero)
         0           (special case)

    "#0.#0" is like the above example, but will always display two full decimal
    places listed plus the integral zero:

        12.34
         2.34
         2.30        (note the 0 in the hundredth's place)
         0.30        (never lose that upper zero)
         0.00        (as zero as we get)

    "-####" will print a leading minus sign:

         1234        (no sign printed if positive)
        -1234
        -  34        (compare to first example, where minus sign touches the 3)

    "+####" will print a leading plus:

        +1234        (even the plus is printed)
        + 234
        -1234

    "####<" will print a left-align number in the field:

        1234
        234
        34
        4

Notification
------------

The built-in variable types (and many of the EX variables) support the
concept of "notification". This is a procedure where a variable can tell
another object that its value has changed. The object may then update its
display or internal state based on the new value of the variable.

For instance, the TEXT command supports notification on variables that
are referenced within strings using bang-formatting. This means that a
string may displayed with variable references that will update as the
values in the variables change. For instance:

    EVENT
    group:
        integer(x);
    sequence:
        x = 0;
        TEXT(10,10,"x is !x");
        EVENT
        group:
            while (x < 100);
        sequence:
            pause(1);
            x = x + 1;
        END
    END

Note here that the variable 'x' follows the group scope, while the text object
does not! Text objects are a part of the Element class of the Screen book and
these object follow a different set of scope rules. The Text object will
remain active until the next Display() command. Note that this script assumes
that a Display() command has already been executed. See the Element
documentation for more information.

So, what does this script do? It displays "x is 0". Then after one second the
value of X on screen changes to "1", then to "2", and so on. This is because
the variable is notifying the text object that its value has changed. The
text object then updates its display to show the new value.

Other types of objects can implement notification in their own way, it doesn't
have to involve the updating of the screen. For instance, a Television tuner
might change the channel when the value of the "channel" variable changes.

If an action needs to be taken when the value of a variable changes, but either
the object does not support notification or no object is available, then a
special command is available that allows actions to be taken on any variable's
notification. This command is OnNotification. It works as follows:

    EVENT
    group:
        OnNotification(my_var, use(foo));
    ...

When this command is in scope (it follows the group scope rules), the action
will be taken every time the variable changes. Actions include USE and GOTO
commands.

Expressions
-----------

Arithmetic expressions use parenthesis for grouping.

    Group:
        INTEGER(int_1, int_2);
    Sequence:
        int_1 = 1 + (3 ** 2);
        int_2 = $7F MOD int_1 * -3;

Strings allow for concatenation and assignment.

    Group:
        string(str1);
    Sequence:
        str1 = "hello" + ", " + "world!";

Logical expressions use parenthesis for grouping.

    Group:
        boolean(bool_1);
        integer(int_1);
    Sequence:
        bool_1 = (1 = 1) and not (3 > 7);
        int_1 = 7;
        EVENT
        Group:
            While (int_1 >= 0);
        Sequence:
            int_1 = int_1 - 1;
        END

Standard Functions and Variables
--------------------------------

Although functions are usually supplied by EX modules, the Scala Player itself
also provides a number of useful general-purpose functions and variables.

Functions
---------

    integer ABS(integer N)
    string  CHAR(integer C)
    integer CODE(string S)
    boolean EVALBOOL(string S)
    integer EVALINT(string S)
    string  EVALSTRING(string S)
    boolean EXISTS(string FileName)
    string  FORMAT(string FormatStr, integer Value)
    string  GETENV(string Var)
    string  LEFT(string S, integer N)
    integer LENGTH(string S)
    integer MAX(integer N1, integer N1)
    integer MIN(integer N1, integer N2)
    integer RANDOM(integer Min, integer Max)
    boolean SEED(integer N)
    integer REVISION(string ModuleName)
    string  RIGHT(string S, integer N)
    integer SEARCH(string S, integer P, string T)
    integer SIGN(integer N)
    string  SUBSTRING(string S, integer P, integer N)
    integer VALUE(string S)
    integer VERSION(string ModuleName)

Variables
---------

    string  CPU
    integer MEMORY
    string  PLATFORM

Detailed Information on Functions and Variables
-----------------------------------------------

Casting Functions
-----------------

Value
    integer VALUE(string S)

    Convert S to an integer. Returns 0 if S does not start with a number
    (leading white space is ignored). Recognizes decimal numbers (default),
    hexadecimal (prefixed with a '$'), and binary (prefixed with a '%').

String Functions
----------------

Left
    string LEFT(string S, integer N)

    Return the N first characters of S. If Length(S) <= N, return S.

Right
    string RIGHT(string S, integer N)

    Return the N last characters of S. If Length(S) <= N, return S.

SubString
    string SUBSTRING(string S, integer P, integer N)

    Return substring of S, starting at position P, containing N characters.
    P should be in the range [1...Length(S)]. If N > 1+Length(S)-P, return
    as many characters as possible. If P > Length(S), return an empty string.

Length
    integer LENGTH(string S)

    Return the number of characters in S.

Search
    integer SEARCH(string S, integer P, string T)

    If T is a substring of S (starting at a position >= P) return the position
    of the first occurrence of T within S, else return 0.

Code
    integer CODE(string S)

    Return the ANSI Latin-1 code of the first character in the string S.
    If S is empty, return 0.

Char
    string CHAR(integer C)

    Return a one-character string consisting of the ASCII character defined by
    the code C.

Format
    string  FORMAT(string FormatStr, integer Value)

    Apply the specified format string to the given value and return the result
    as a string. For example:

        my_str = Format("-0####.##0", 123400);

    Will return the string "-00123.400".

Math Functions
--------------

Min
    integer MIN(integer N1, integer N2)

    If N1 > N2 return N2 else return N1.

Max
    integer MAX(integer N1, integer N1)

    If N1 > N2 return N1 else return N2.

Abs
    integer ABS(integer N)

    If N < 0 return -N else return N.

Sign
    integer SIGN(integer N)

    If N < 0 return -1 else if N > 0 return 1 else return 0.

Random
    integer RANDOM(integer Min, integer Max)

    Returns a random number in the range [Min...Max].

Seed
    boolean SEED(integer N)

    Seed the random number generator; N can be any number. The function
    returns True always.

Expression Evaluation
---------------------

EvalString
    string EVALSTRING(string S)

    Evaluate the string expression contained in the string S and return the
    result.

EvalInt
    integer EVALINT(string S)

    Evaluate the integer expression contained in the string S and return the
    result.

EvalBool
    boolean EVALBOOL(string S)

    Evaluate the boolean expression contained in the string S and return the
    result.

System Functions
----------------

GetEnv
    string GETENV(string Var)

    Return the contents of the OS (not Player) Environment variable Var. If
    the variable is not defined, or the OS doesn't support Environment
    variables, return empty string. May not be available on all platforms.

Exists
    boolean EXISTS(string FileName)

    Return TRUE if and only if a file named FileName exists.

Version and Revision
    integer VERSION(string ModuleName)
    integer REVISION(string ModuleName)

    Return the version/revision number of a module (e.g. "player.book" or
    "mpeg.ex").

System Variables
----------------

Platform
    string PLATFORM

    Environment variable containing the name of the OS platform, such as
    "MSDOS", "GIEOS", etc.

CPU
    string CPU

    Environment variable containing the a CPU name, such as: "386", "486",
    "Pentium", etc.

Memory
    integer MEMORY

    Environment variable containing the total amount (not necessarily free)
    of RAM in bytes.




-------------------------------------------------------------------------------

2.  Sound EX Script Commands and Variables
==========================================

The Sound EX supports pre-seek/buffering/loading and sound spooling from disk.
This EX provides a set of commands, functions and variables for controlling and
configuring sound from in Scala Scripts.

The Sound EX supports playback of Audio CD's on a CD-ROM drive, Wave files
(.WAV 8/16-bit mono or stereo digital audio files, also ADPCM), IFF 8SVX files
(8-bit mono uncompressed digital audio files) and General MIDI files (.MID
files, only type 0 and 1 are supported).

The Sound EX supports Audio CD playback by communicating with MSCDEX through
DPMI and automatically detects if a CD-ROM drive is present. MSCDEX must be
running on a DOS or Windows system. If the system is using OS/2 or Windows 95
then MSCDEX is not required. Multiple drives and pre-seek is supported.

Wave/8SVX (sample) playback is supported by using functions in the DPMI book -
the DPMI book currently supports all versions of the SoundBlaster cards
(including the 16-bit versions) and all 100% compatible cards. Most MediaVision
cards are also supported (the MVSOUND driver must be installed). No external
drivers are necessary since the DPMI book communicates directly with the cards.
Sound-spooling from hard-disk is supported, so is preloading/buffering.

MIDI playback is done entirely by the Sound EX. This also includes the
communication with the various chips and cards. Three chips/cards are currently
supported:

    MPU401, AWE32 and Gravis UltraSound.

Since several cards use an MPU401 not only for communication with external
equipment but also for their internal audio, cards like the Roland RAP-10 and
LAPC1/MT32 will also work with the MPU401 setting. No external drivers are
necessary, except for the Gravis UltraSound support which depends on the
ULTRAMID TSR being present (NOTE: ULTRAMID must be started with the -c option).

Sound EX Commands

Below is a list of all Scala Script commands provided by the Sound EX.
Parameters within brackets are optional.

Overview

CD Commands

    CD.Eject([FADE(secs)] [,UNIT(unit)])
    CD.Pan(Panning [,UNIT(unit)])
    CD.Pause([FADE(secs)] [,UNIT(unit)])
    CD.Play(InTrack, OutTrack [,WAIT(bool)] [,LOOPS(loops)]
            [,PAN(panval)] [,FADE(vol,secs)] [,UNIT(unit)])
    CD.PlayMSF(InMSF, OutMSF [,WAIT(bool)] [,LOOPS(loops)]
            [,PAN(panval)] [,FADE(vol,secs)] [,UNIT(unit)])
    CD.ReadToc([UNIT(unit)])
    CD.Resume([FADE(vol,secs)] [,WAIT(bool)] [,UNIT(unit)])
    CD.Stop([FADE(secs)] [,UNIT(unit)])
    CD.Sync(SyncMSF [,TRACK(bool)] [,UNIT(unit)])
    CD.Volume(FadeTo, FadeTime [,WAIT(bool)] [,UNIT(unit)])
    CD.Wait([UNIT(unit)])

Midi Commands

    Midi.Pan(Panning)
    Midi.Pause([FADE(secs)])
    Midi.Play(FileName [,RATE(rate)] [,WAIT(bool)] [,LOOPS(loops)]
            [,PAN(panval)] [,FADE(vol,secs)])
    Midi.Resume([FADE(vol,secs)] [,WAIT(bool)])
    Midi.Stop([FADE(secs)])
    Midi.Volume(FadeTo, FadeTime [,WAIT(bool)])
    Midi.Wait()

Mixer Commands

    Mixer.Pan([MASTER(MasterPan)] [,VOICE(VoicePan)] [,FM(FMPan)]
            [,CD(CDPan)] [,LINEIN(LineInPan)])
    Mixer.Volume(FadeTime [,MASTER(MasterVol)] [,VOICE(VoiceVol)] [,FM(FMVol)]
            [,CD(CDVol)] [,LINEIN(LineInVol)] [,MICIN(MicInVol)])

Sample Commands

    Sample.Pan(Panning)
    Sample.Play(FileName [,RATE(rate)] [,SIGNED(bool)] [,WAIT(bool)]
            [,LOOPS(loops)] [,PAN(panval)] [,FADE(vol,secs)])
    Sample.Stop([FADE(secs)])
    Sample.Volume(FadeTo, FadeTime [,WAIT(bool)])
    Sample.Wait()

Details

CD.PLAY
    InTrack             integer  Play from track number 'InTrack'
    OutTrack            integer  Play until track number 'OutTrack'
    [WAIT(bool)]        boolean  Wait for playback to complete before
                                 continuing?
    [LOOPS(loops)]      integer  Play the sequence/track 'loops' number of
                                 times
    [PAN(panval)]       integer  Set panning value to 'panval'
                                 (range -255 to 255)
    [FADE(vol,secs)]    integer  Fade from zero to 'vol' volume
                        integer  Fade in 'secs' seconds
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.PLAYMSF
    InMSF               string   Play from 'InMSF'
                                 format "MM:SS.FF" (mins/secs/frames)
    OutMSF              string   Play until 'OutMSF'
                                 format "MM:SS.FF" (mins/secs/frames)
    [WAIT(bool)]        boolean  Wait for playback to complete before
                                 continuing?
    [LOOPS(loops)]      integer  Play the sequence/track 'loops'
                                 number of times
    [PAN(panval)]       integer  Set panning value to 'panval'
                                 (range -255 to 255)
    [FADE(vol,secs)]    integer  Fade from zero to 'vol' volume
                        integer  Fade in 'secs' seconds
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.SYNC
    SyncMSF             string   Halt script until 'SyncMSF' is reached
                                 format "MM:SS.FF"
    [TRACK(bool)]       boolean  Set to 'TRUE' if relative to start of track
                                 rather than start of disk.
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.WAIT - Wait for playback to complete before continuing.
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.STOP - Stop playback (playback can not be resumed)
    [FADE(secs)]        integer  Fade down to zero during 'secs' secs
                                 before stopping
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.PAUSE - Pause playback (playback can be resumed if playing)
    [FADE(secs)]        integer  Fade down to zero during 'secs' secs
                                 before stopping
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.RESUME - Resume playback (if stopped during playback)
    [FADE(vol,secs)]    integer  Fade upto 'vol' volume
                        integer  Fade in 'secs' seconds
    [WAIT(bool)]        boolean  Wait for fade to complete before continuing?
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.EJECT - Eject the CD (not supported by all drives)
    [FADE(secs)]        integer  Fade down to zero during 'secs' secs
                                 before ejecting
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.READTOC - Rereads the table of contents if the user has inserted a CD
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'


CD.VOLUME
    FadeTo              integer  Set the new volume to 'FadeTo'
                                 (range 0 to 255)
    FadeTime            integer  The fade should take 'FadeTime' secs
                                 (0 if no fade)
    [WAIT(bool)]        boolean  Wait for fade to complete before continuing?
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'
SEE ALSO: CD.HWVOL


CD.PAN
    Panning             integer  Set the new panning to 'Panning'
                                 (range -255 to 255)
    [UNIT(unit)]        integer  Command is related to CD-ROM unit 'unit'
SEE ALSO: CD.HWVOL


SAMPLE.PLAY
    FileName            string   Play the sample indicated by 'FileName'
    [RATE(rate)]        integer  Override the default rate, set to 'Rate' Hz
    [SIGNED(bool)]      boolean  Override the default sign
                                 (file contains signed data?)
    [WAIT(bool)]        boolean  Wait for playback to complete
                                 before continuing?
    [LOOPS(loops)]      integer  Play the sample 'loops' number of times
    [PAN(panval)]       integer  Set panning value to 'panval'
                                 (range -255 to 255)
    [FADE(vol,secs)]    integer  Fade from zero to 'vol' volume
                        integer  Fade in 'secs' seconds


SAMPLE.WAIT - Wait for playback to complete before continuing


SAMPLE.STOP - Stop playback (playback can be resumed if playing)
    [FADE(secs)]        integer  Fade down to zero during 'secs'
                                 seconds before stopping


SAMPLE.VOLUME
    FadeTo              integer  Set the new volume to 'FadeTo'
                                 (range 0 to 255)
    FadeTime            integer  The fade should take 'FadeTime' secs
                                 (0 if no fade)
    [WAIT(bool)]        boolean  Wait for fade to complete before continuing?


SAMPLE.PAN
    Panning             integer  Set the new panning to 'Panning'
                                 (range -255 to 255)


MIXER.VOLUME
    FadeTime            integer  The fade should take 'FadeTime' secs
                                 (0 if no fade)
    [MASTER(MasterVol)] integer  The new Master volume (range 0 to 255)
    [VOICE(VoiceVol)]   integer  The new Voice/Sample volume (range 0 to 255)
    [FM(FMVol)]         integer  The new FM/Midi volume (range 0 to 255)
    [CD(CDVol)]         integer  The new CD volume (range 0 to 255)
    [LINEIN(LineInVol)] integer  The new Line In volume (range 0 to 255)
    [MICIN(MicInVol)]   integer  The new Mic In volume (range 0 to 255)


MIXER.PAN
    [MASTER(MasterPan)] integer  The new Master panning (range -255 to 255)
    [VOICE(VoicePan)]   integer  The new Voice/Sample panning
                                 (range -255 to 255)
    [FM(FMPan)]         integer  The new FM/Midi panning (range -255 to 255)
    [CD(CDPan)]         integer  The new CD panning (range -255 to 255)
    [LINEIN(LineInPan)] integer  The new Line In panning (range -255 to 255)



MIDI.PLAY
    FileName            string   Play the Midi file indicated by 'FileName'
    [RATE(rate)]        integer  Override the default rate, set to 'Rate' bpm
    [WAIT(bool)]        boolean  Wait for playback to complete before
                                 continuing?
    [LOOPS(loops)]      integer  Play the Midi file 'loops' number of times
    [PAN(panval)]       integer  Set panning value to 'panval'
                                 (range -255 to 255)
    [FADE(vol,secs)]    integer  Fade from zero to 'vol' volume
                        integer  Fade in 'secs' seconds


MIDI.WAIT - Wait for playback to complete before continuing


MIDI.STOP - Stop playback (playback can not be resumed)
    [FADE(secs)]        integer  Fade down to zero during 'secs'
                                 seconds before stopping


MIDI.PAUSE - Stop playback (playback can be resumed if playing)
    [FADE(secs)]        integer  Fade down to zero during 'secs'
                                 seconds before stopping


MIDI.RESUME - Resume playback (if playback was previously stopped)
    [FADE(vol,secs)]    integer  Fade up to 'vol' volume
                        integer  Fade in 'secs' seconds
    [WAIT(bool)]        boolean  Wait for fade to complete before continuing?


MIDI.VOLUME
    FadeTo              integer  Set the new volume to 'FadeTo'
                                 (range 0 to 255)
    FadeTime            integer  The fade should take 'FadeTime' secs
                                 (0 if no fade)
    [WAIT(bool)]        boolean  Wait for fade to complete before continuing?


MIDI.PAN
    Panning             integer  Set the new panning to 'Panning'
                                 (range -255 to 255)


Sound Variables and Functions

FUNCTIONS:

Name                            Type    Description
------------------------------------------------------------------------
CD.LengthTrack(tracknumber)     String  Length of any given tracknumber

VARIABLES:

Name            Type    Example         Description
-----------------------------------------------------------------------
CD.DiscLength   String  "54:32"         Total playing time whole disc
CD.DiscTime     String  "23:45"         Elapsed time whole disc
CD.FirstDrive   String  "D"             Drive letter of first CD drive
CD.MaxTracks    Integer 12              Number of tracks on disc
CD.NumDrives    Integer 1               Number of CD drives on this PC
CD.Track        Integer 3               Current track number
CD.TrackLength  String  "04:56"         Length this track
CD.TrackTime    String  "01:23"         Elapsed time this track

CD variables are Read Only. You cannot assign values to them.


Name            Type    Range           Description
-----------------------------------------------------------------------
Mixer.CDPan     Integer -255...255      CD Pan
Mixer.CDVol     Integer 0..255          CD Volume
Mixer.LinePan   Integer -255...255      Line Pan
Mixer.LineVol   Integer 0..255          Line Volume
Mixer.MasterPan Integer -255...255      Master Pan
Mixer.MasterVol Integer 0..255          Master Volume
Mixer.MicVol    Integer 0..255          Microphone Volume
Mixer.MIDIPan   Integer -255...255      MIDI Pan
Mixer.MIDIVol   Integer 0..255          MIDI Volume
Mixer.SamplePan Integer -255...255      Sample Pan
Mixer.SampleVol Integer 0..255          Sample Volume

Mixer variables are Read/Write. You can read their current value
or set a new value.

All volume settings range from 0 to 255, while all panning settings range from
-255 to 255 (-255 equals full left channel, 0 equals full left and right
channel, 255 equals full right channel.)

Sound Environment variables

Environment variables are used to configure the Sound EX. Below is a sample
configuration file for the Sound EX (sound.sca). This file should be placed
into the "config" directory of the system.

    !ScalaScript
    EVENT
        CD.Hwvol    = FALSE;
        Sample.Type = "NONE";
        Sample.Addr = $220;
        Sample.Irq  = 5;
        Sample.Dma  = 1;
        Midi.Type   = "NONE";
        Midi.Addr   = $330;
        Midi.Patch  = "NONE";
    END

Here is a brief description of the Sound EX module's Environment variables.

CD.HWVOL = FALSE;

The CD volume can be controlled in two ways: Either by using the CD-ROM hardware
for controlling the volume (not supported by all manufacturers), or by using the
soundcard's mixer functions. Set this boolean variable to TRUE if you would like
to use the CD-ROM hardware for controlling the volume.

SAMPLE.TYPE = "NONE";

This variable defines the type of soundcard installed in your machine (for
sample playback).

    "NONE"        No card has been installed.
    "SB1.X"       SoundBlaster version 1.x.
    "SB1.5"       SoundBlaster version 1.5.
    "SB2.0"       SoundBlaster version 2.0.
    "SBPRO"       SoundBlaster Pro series.
    "SB16"        SoundBlaster 16-bit cards.
    "AWE32"       SoundBlaster 16-bit cards.
    "MEDIAVISION" MediaVision - use MVSOUND.

SAMPLE.ADDR = $220;

This variable defines the address of the soundcard. The dollar sign prefixes a
hexa-decimal address.

SAMPLE.IRQ = 5;

This variable defines the soundcard's irq number. Most Blaster cards do not need
this setting.

SAMPLE.DMA = 1;

This variable defines the soundcard 's dma channel. Most cards do not need this
setting.

MIDI.TYPE = "NONE";

This variable defines the type of MIDI card installed in your machine (for MIDI
playback).

    "NONE"   No card has been installed.
    "MPU401" General Midi chip used by most cards for communication
             with external equipment - also used by the Roland RAP-10
             and Roland LAPC1/MT32 cards for internal audio.
    "AWE32"  SoundBlaster AWE32 / EMU8000.
    "GUS"    Gravis UltraSound - use ULTRAMID.EXE.

MIDI.ADDR = $330;

This variable defines the address of your MIDI card, which is normally $330 for
MPU401 and $620 for the AWE32. The dollar sign prefixes a hexadecimal address.

MIDI.PATCH = "NONE";

This variable defines the name of a patch or soundfonts (SBK) file that should
automatically be loaded upon startup .


Example scripts

The following "intro" script plays the first 10 seconds of each track on the CD.

EVENT
Group:
    INTEGER(track);
Sequence:
    EVENT
    Group:
        WHILE(track < CD.MAXTRACK)
    Sequence:
        track = track + 1;
        CD.PLAY(track, track, Wait(FALSE));
        CD.SYNC("00:10.00", Track(TRUE));
    END
END

The following "jukebox" script uses the Console EX for reading input and writing
messages onto the screen.

EVENT
Group:
    INTEGER(track);
    track = 1;
Sequence:
    EVENT
    Group:
        WHILE(track > 0)
    Sequence:
        ECHO("\nEnter track number: ");
        ASK(track);
        CD.PLAY(track, track, Wait(FALSE));
    END
END

The following script plays track one on the CD and crossfades to the WAV file
indicated, waiting for completion.

EVENT
Sequence:
    MIXER.VOLUME(Voice(0), CD(255));
    CD.PLAY(1, 1, Wait(FALSE));
    SAMPLE.PLAY(":n/archive/sounds/jazzriff.wav", Wait(FALSE));
    MIXER.FADE(10, Voice(255), CD(0));
    SAMPLE.WAIT();
END




-------------------------------------------------------------------------------

3.  Input EX Script Commands
============================

Input():

    Input(
        [ Mouse( BOOL ) ]
        [ TouchScreen( BOOL ) ]
        [ Keyboard( BOOL ) ]
        [ MouseControls( BOOL ) ]
        [ KeyboardControls( BOOL ) ]
        [ MousePointer( STRING ) ]
        [ MouseBusyPointer( STRING ) ]
        [ PointerSelectionOnly( BOOL ) ]
        )

    Button Input
    ------------

    - Mouse( BOOL )
        Use a mouse as the ButtonsEX input device.  This option is mutually
        exclusive with the TouchScreen option.

    - TouchScreen( BOOL )
        Use a touch screen as the ButtonsEX input device.  This option is
        mutually exclusive with the Mouse option.

    - Keyboard( BOOL )
        Use the keyboard as the ButtonsEX input device.  This can be used
        with Mouse or TouchScreen.


    Slideshow Controls
    ------------------

    - MouseControls( BOOL )
        Allows the mouse to navigate through a slideshow.  This option will
        be ignored while the Mouse() option is on AND there are buttons on
        the current page.

    - KeyboardControls( BOOL )
        Allow the keyboard to navigate through a slideshow.


    Mouse Pointer
    -------------

    - MousePointer( STRING )
        Filename of normal mouse pointer image.  The image file can be a .bmp
        or other image file format that Scala supports for Clips.  By
        default, Scala will use Scala:\pointers\stdptr.bmp.

    - MouseBusyPointer( STRING )
        Filename of busy mouse pointer image.  The image file can be a .bmp
        or other image file format that Scala supports for Clips.  A busy
        pointer will appear when buttons are on the page but are not yet
        active.  If PointerSelectionOnly (see below) is On, a busy pointer
        can appear while the player is in an idle state and there are no
        wipes in progress.  By default, Scala will not show a busy pointer.

    - PointerSelectionOnly( BOOL )
        If this is On, a mouse pointer will only appear while there are
        buttons on the current page.  If this is Off, a pointer will
        appear on all pages.  Of course, if the user has not set the busy
        pointer image,  there will be no pointer when the player is idle.




-------------------------------------------------------------------------------

4.  Time Script Functions and Variables
=======================================

Time
    string TIME

    Environment variable containing the current time in the current format
    (defined by a system setting).

Date
    string DATE

    Environment variable containing the current date in the current format
    (defined by a system setting).

Clock
    integer CLOCK

    Environment variable containing the number of seconds since some magic date.

SysTime
    integer SYSTIME(enum Mode)

    Where Mode can be:
        Mode     Returned Range
        ----     --------------
        Year     1995, 1996, ...
        Month    [1...12]
        Day      [1...31]
        Hour     [0...23]
        Minute   [0...59]
        Second   [0...59]
        Weekday  [1...7]

    For example:
        SysTime(Weekday) might return 5 (Thursday).
        SysTime(Year) might return 1996.




-------------------------------------------------------------------------------

5.  MPEG EX Script Commands
===========================

MPEG.Stop();

MPEG.Wait();

MPEG.Play(filename, <options>);

    MPEG.Play() required parameters:

        -filename

    MPEG.Play() optional parameters:

        - Pos(x,y),

        - Size(width,height),

        - Wait(boolean)




-------------------------------------------------------------------------------

6.  Screen EX Script Commands and Variables
===========================================

This is a description of the EX commands and variables supported by
the Screen EX and related EXes.

1. EX Variables
---------------

Various EX variables may be set to configure certain aspects of Screen
EX operation. These include:

Screen.ViewMode (string)
    If set, this tells the Screen EX to force all background elements
    to use a specific View mode, as if the View Mode suboption was
    specified in each background command. This overrides any View
    option specified in the background command.

Screen.ViewWidth (integer)
    If set, this tells the Screen EX to force all background elements
    to use a specific View width, as if the View Size suboption was
    specified in each background command. This overrides any View
    option specified in the background command.

Screen.ViewHeight (integer)
    If set, this tells the Screen EX to force all background elements
    to use a specific View height, as if the View Size suboption was
    specified in each background command. This overrides any View
    option specified in the background command.

2. Element and Style Commands
-----------------------------

An element is an on-screen object created by a Scala Script command.
An element may be either a background or a foreground element. Each
background element replaces any background element that appeared
previously. Foreground elements appear in front of the current
background element, and may overlap each other. Each foreground
element will always obscure any overlapping elements that appeared
previously. When a background element is replaced by a new one, all
foreground elements that were shown on it are removed automatically.

Each Scala Script command that creates an element is known as an
element command. Each element command may have required parameters
that it expects, and/or optional parameters that it supports. This
section describes each of these element commands and the parameters
that it uses.

A style is a command that can be used to set up commonly used options
for reference by one or more element commands. Each element command
has an associated style command. A Scala Script author may choose to
use or not to use a style command for any given element command,
depending on the needs of the script. Style commands can be used to
reduce RAM and CPU utilization during Scala Script playback, by
specifying common options on the style commands and referencing those
styles by name on element commands.

Note that styles are not supported by the authoring system at this time.
They may, however, be hand authored. Scripts created with styles will
probably not be able to be loaded into the current authoring system.

An element command may reference a style command, and override some of
the options specified in the style command by re-specifying the same
option again in the element command. If an option is overridden this
way, all suboptions for that option are also overridden (unless
otherwise noted), whether or not they were specified on the element
command. Suboptions that are not specified for an overridden option
will use default values. All element and style commands, unless
otherwise noted, evaluate their parameters only once, when an element
is created.

Background Commands
-------------------

Display() and DisplayStyle():

    Display() creates a solid color or a patterned background.
    DisplayStyle() creates a style object that can be used to specify a
    common set of options used by one or more Display commands.

    Display(
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(<fill options>) ]
        [ View(Mode(name), Size(width, height), Position(left, top),
             Colors(colors), Color(color)) ]
        [ Palette( Clear(state), <palette options> ) ]
        [ UserPalette( Clear(state), <palette options> ) ]
        [ Margin(left, right, top, bottom) ]
        [ Tabs(Implicit(width), Explicit(tab, ...)) ]
        [ Size(width, height) ]
        );

    DisplayStyle(stylename,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(<fill options>) ]
        [ View(Mode(name), Size(width, height), Position(left, top),
             Colors(colors), Color(color)) ]
        [ Palette( Clear(state), <palette options> ) ]
        [ UserPalette( Clear(state), <palette options> ) ]
        [ Margin(left, right, top, bottom) ]
        [ Tabs(Implicit(width), Explicit(tab, ...)) ]
        [ Size(width, height) ]
        );

    Examples:
        DisplayStyle(Fred, View(Mode("NTSC 704")));
        DisplayStyle(Wilma, Style(Fred), Face(RGB(0)));
        Display(Face(RGB($ffffff)));
        Display(Style(Fred), Face(Tile("scalabang.bmp")), Size(608,400));

    DisplayStyle() Required parameters:
        - stylename
            The name of the style being defined.

    Optional parameters:
        - Style(stylename)
            The name of a style style being defined is derived from.

        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping in the element.
            If no wipe is specified, the "Cut" wipe is used.

        - Face(<fill options>)
            The appearance of the face of the element. For images,
            <fill options> defaults to nothing. For other elements,
            <fill options> defaults to RGB(0).

        - View(Mode(name), Size(width, height), Position(left, top),
                Colors(colors), Color(color))
            This describes the View used for this background. Any
            combination of suboptions may be specified to uniquely
            describe the View to be used.

            Mode(name) identifies the mode by a name (in string form).

            Size(w,h) identifies the View by the maximum display size
            it supports. this is the size of the ViewPort that is created.

        - Palette( Clear(state), <palette options> )
            The palette used for this background. This defines
            specific colors to be mapped to specific pens at playback
            time.

            Clear(state) determines whether pens from the style
            (if any) are cleared before applying pens specified in
            this Palette option.

        - UserPalette( Clear(state), <palette options> )
            The user palette for this background. This defines
            specific colors to be mapped to user pen numbers during
            playback. These user pen numbers are used by other
            commands via the 'Pen' fill option to select colors for
            elements to be drawn in. During playback, these user pens
            may end up mapped to any playback pens, and the screen
            book will take care of converting one to the other. The
            net result is that elements may refer to a user pen
            number, and get the desired color, no matter which
            playback pen the user pen number is actually mapped to.

            Clear(state) determines whether user pens from the style
            (if any) are cleared before applying user pens specified
            in this UserPalette option.

        - Margin(left, right, top, bottom)
            This sets margins in the Background element to be used for
            positioning foreground elements on that background. The
            margin values may be 0 or greater, and all default to 0.

        - Tabs(Implicit(width), Explicit(tab, ...))
            A description of tab stops, relative to the background. If
            both Implicit and Explicit tabs are specified, explicit
            tabs are used first, and implicit tabs are used once the
            explicit tabs are used up.

            Implicit(width) set the distance between implied tab
            stops. This represents the number of pixels from each tab
            stop to the next. The width may be 1 or greater, and
            defaults to 50.

            Explicit(tab, ...) sets a list of one or more explicit tab
            stops. Each tab stop represents a number of pixels from
            the tab reference point, and may be 0 or greater. Any
            number of tab stops may be specified, but they must be
            listed in increasing order. There are no default Explicit
            tabs.

        - Size(width, height)
            This may be used to force a visual display size that is
            different than the ViewPort size. If no Display size is
            specified, the display will be the same size as the
            ViewPort (or View). If the display size is smaller than
            the ViewPort size, the display will be centered in the
            ViewPort.

Picture() and PictureStyle():

    Picture() creates a still image background.
    PictureStyle() creates a style object that can be used to specify a
    common set of options used by one or more Picture commands.

    Picture(filename,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(<fill options>) ]
        [ View(Mode(name), Size(width, height), Position(left, top),
            Colors(colors), Color(color)) ]
        [ Palette( Clear(state), <palette options> ) ]
        [ UserPalette( Clear(state), <palette options> ) ]
        [ Margin(left, right, top, bottom) ]
        [ Tabs(Implicit(width), Explicit(tab, ...)) ]
        [ Frame(frame) ]
        [ Operation(state, <operation options>) ]
        );

    PictureStyle(stylename,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(<fill options>) ]
        [ View(Mode(name), Size(width, height), Position(left, top),
            Colors(colors), Color(color)) ]
        [ Palette( Clear(state), <palette options> ) ]
        [ UserPalette( Clear(state), <palette options> ) ]
        [ Margin(left, right, top, bottom) ]
        [ Tabs(Implicit(width), Explicit(tab, ...)) ]
        [ Frame(frame) ]
        [ Operation(state, <operation options>) ]
        );

    Examples:
        PictureStyle(MaryAnn,
            Operation(ImagePalette(RGBPen(1, $ff00ff, $ffff00))));
        PictureStyle(Ginger, Style(MaryAnn));
        Picture("pic1.bmp");
        Picture("pic2.bmp", Style(Ginger), Operation(Resize(800, 600)));

    PictureStyle() required parameters:
        - stylename
            The name of the style being defined.

    Picture() required parameters:
        - filename
            The name of the file containing the image data.

    Optional parameters:
        - Style(stylename)
            The name of a style style being defined is derived from.

        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping in the element.
            If no wipe is specified, the "Cut" wipe is used.

        - Face(<fill options>)
            The appearance of the face of the element. For images,
            <fill options> defaults to nothing. For other elements,
            <fill options> defaults to RGB(0).

        - View(Mode(name), Size(width, height), Position(left, top),
                Colors(colors), Color(color))
            This describes the View used for this background. Any
            combination of suboptions may be specified to uniquely
            describe the View to be used.

            Mode(name) identifies the mode by a name (in string form).

            Size(w,h) identifies the View by the maximum display size
            it supports. this is the size of the ViewPort that is created.

        - Palette( Clear(state), <palette options> )
            The palette used for this background. This defines
            specific colors to be mapped to specific pens at playback
            time.

            Clear(state) determines whether pens from the style
            (if any) are cleared before applying pens specified in
            this Palette option.

        - UserPalette( Clear(state), <palette options> )
            The user palette for this background. This defines
            specific colors to be mapped to user pen numbers during
            playback. These user pen numbers are used by other
            commands via the 'Pen' fill option to select colors for
            elements to be drawn in. During playback, these user pens
            may end up mapped to any playback pens, and the screen
            book will take care of converting one to the other. The
            net result is that elements may refer to a user pen
            number, and get the desired color, no matter which
            playback pen the user pen number is actually mapped to.

            Clear(state) determines whether user pens from the style
            (if any) are cleared before applying user pens specified
            in this UserPalette option.

        - Margin(left, right, top, bottom)
            This sets margins in the Background element to be used for
            positioning foreground elements on that background. The
            margin values may be 0 or greater, and all default to 0.

        - Tabs(Implicit(width), Explicit(tab, ...))
            A description of tab stops, relative to the background. If
            both Implicit and Explicit tabs are specified, explicit
            tabs are used first, and implicit tabs are used once the
            explicit tabs are used up.

            Implicit(width) set the distance between implied tab
            stops. This represents the number of pixels from each tab
            stop to the next. The width may be 1 or greater, and
            defaults to 50.

            Explicit(tab, ...) sets a list of one or more explicit tab
            stops. Each tab stop represents a number of pixels from
            the tab reference point, and may be 0 or greater. Any
            number of tab stops may be specified, but they must be
            listed in increasing order. There are no default Explicit
            tabs.

        - Frame(frame)
            Which image is to be used from the named file, if the file
            contains multiple images.

        - Operation(state, <operation options>)
            Specifies the operations done before drawing this image.
            The state defaults to off.

Anim() and AnimStyle():

    Anim() creates an animation background.
    AnimStyle() creates a style object that can be used to specify a
    common set of options used by one or more Anim commands.

    Anim(filename,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(<fill options>) ]
        [ View(Mode(name), Size(width, height), Position(left, top),
            Colors(colors), Color(color)) ]
        [ Palette( Clear(state), <palette options> ) ]
        [ UserPalette( Clear(state), <palette options> ) ]
        [ Margin(left, right, top, bottom) ]
        [ Tabs(Implicit(width), Explicit(tab, ...)) ]
        [ Frame(frame) ]
        [ Operation(state, <operation options>) ]
        [ Speed(speed) ]
        [ Loops(loops) ]
        [ StopAtFirstFrame(state) ]
        );

    AnimStyle(stylename,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(<fill options>) ]
        [ View(Mode(name), Size(width, height), Position(left, top),
            Colors(colors), Color(color)) ]
        [ Palette( Clear(state), <palette options> ) ]
        [ UserPalette( Clear(state), <palette options> ) ]
        [ Margin(left, right, top, bottom) ]
        [ Tabs(Implicit(width), Explicit(tab, ...)) ]
        [ Frame(frame) ]
        [ Operation(state, <operation options>) ]
        [ Speed(speed) ]
        [ Loops(loops) ]
        [ StopAtFirstFrame(state) ]
        );

    Examples:
        AnimStyle(Barnum, Speed(40));
        AnimStyle(Bailey, Style(Barnum), Speed(60), Wipe("FlyLeft"));
        Anim("show.flc");
        Anim("show2.flc", Style(Barnum), Loops(5));

    AnimStyle() required parameters:
        - stylename
            The name of the style being defined.

    Anim() required parameters:
        - filename
            The name of the file containing the image data.

    Optional parameters:
        - Style(stylename)
            The name of a style style being defined is derived from.

        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping in the element.
            If no wipe is specified, the "Cut" wipe is used.

        - Face(<fill options>)
            The appearance of the face of the element. For images,
            <fill options> defaults to nothing. For other elements,
            <fill options> defaults to RGB(0).

        - View(Mode(name), Size(width, height), Position(left, top),
                Colors(colors), Color(color))
            This describes the View used for this background. Any
            combination of suboptions may be specified to uniquely
            describe the View to be used.

            Mode(name) identifies the mode by a name (in string form).

            Size(w,h) identifies the View by the maximum display size
            it supports. this is the size of the ViewPort that is created.

        - Palette( Clear(state), <palette options> )
            The palette used for this background. This defines
            specific colors to be mapped to specific pens at playback
            time.

            Clear(state) determines whether pens from the style
            (if any) are cleared before applying pens specified in
            this Palette option.

        - UserPalette( Clear(state), <palette options> )
            The user palette for this background. This defines
            specific colors to be mapped to user pen numbers during
            playback. These user pen numbers are used by other
            commands via the 'Pen' fill option to select colors for
            elements to be drawn in. During playback, these user pens
            may end up mapped to any playback pens, and the screen
            book will take care of converting one to the other. The
            net result is that elements may refer to a user pen
            number, and get the desired color, no matter which
            playback pen the user pen number is actually mapped to.

            Clear(state) determines whether user pens from the style
            (if any) are cleared before applying user pens specified
            in this UserPalette option.

        - Margin(left, right, top, bottom)
            This sets margins in the Background element to be used for
            positioning foreground elements on that background. The
            margin values may be 0 or greater, and all default to 0.

        - Tabs(Implicit(width), Explicit(tab, ...))
            A description of tab stops, relative to the background. If
            both Implicit and Explicit tabs are specified, explicit
            tabs are used first, and implicit tabs are used once the
            explicit tabs are used up.

            Implicit(width) set the distance between implied tab
            stops. This represents the number of pixels from each tab
            stop to the next. The width may be 1 or greater, and
            defaults to 50.

            Explicit(tab, ...) sets a list of one or more explicit tab
            stops. Each tab stop represents a number of pixels from
            the tab reference point, and may be 0 or greater. Any
            number of tab stops may be specified, but they must be
            listed in increasing order. There are no default Explicit
            tabs.

        - Frame(frame)
            Which image is to be used from the named file, if the file
            contains multiple images.

        - Operation(state, <operation options>)
            Specifies the operations done before drawing this image.
            The state defaults to off.

        - Speed(speed)
            The speed of the animation in frames per second.

        - Loops(loops)
            How may times to play the animation in a loop.

        - StopAtFirstFrame(state)
            Whether to stop the animation on the first frame after
            completion of the animation. If this is on, the first
            frame will be the last one shown. If this is off, the
            animation's last frame will be the last one shown. The
            state defaults to off.

FullVideo() and FullVideoStyle():

    FullVideo() creates a full-view video display, with no graphics display at
    all. FullVideoStyle() creates a style object that can be used to specify a
    common set of options used by one or more FullVideo commands.

    FullVideo(
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        );

    FullVideoStyle(stylename
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        );

    Examples:
        FullVideoStyle(Fred, Wipe("Cut"));
        FullVideoStyle(Fred, Wipe("Center", Speed(3)));
        FullVideo(Wipe("Center", Speed(4)));
        FullVideo(Style(Fred));

    FullVideoStyle() required parameters:
        - stylename
            The name of the style being defined.

    Optional parameters:
        - Style(stylename)
            The name of a style style being defined is derived from.

        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping in the element.
            If no wipe is specified, the "Cut" wipe is used.

Foreground Commands
-------------------

Box() and BoxStyle():

    Box() creates a foreground object that is a rectangle drawn in a solid
    color or a pattern. BoxStyle() creates a style object that can be used to
    specify a common set of options used by one or more Box commands.

    BoxStyle(stylename,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(state, <fill options>) ]
        [ Shift(x, y) ]
        [ Transparent(state) ]
        [ Border(left, right, top, bottom) ]
        [ Outline(state, Thickness(pixels), <fill options>) ]
        [ Backdrop(state, <fill options>) ]
        [ Bevel(state, Thickness(pixels), Base(color),
            Left(<fill options>), Right(<fill options>),
            Top(<fill options>), Bottom(<fill options>)) ]
        [ Shadow(state, Offset(horizontal, vertical), <fill options>) ]
        [ Align(horizontal, vertical) ]
        [ Replace(state) ]
        );

    Box(X,Y,width,height,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(state, <fill options>) ]
        [ Shift(x, y) ]
        [ Transparent(state) ]
        [ Border(left, right, top, bottom) ]
        [ Outline(state, Thickness(pixels), <fill options>) ]
        [ Backdrop(state, <fill options>) ]
        [ Bevel(state, Thickness(pixels), Base(color),
                Left(<fill options>), Right(<fill options>),
                Top(<fill options>), Bottom(<fill options>)) ]
        [ Shadow(state, Offset(horizontal, vertical), <fill options>) ]
        [ Align(horizontal, vertical) ]
        [ Replace(state) ]
        );

    Examples:
        BoxStyle(Rowan, Wipe("Center", Speed(7)));
        BoxStyle(Martin, Style(Rowan), Outline(on, Thickness(2), Pen(3)));
        Box(x, y, width, height, Face(Pen(4)));
        Box(x, y, width, height, Style(Martin), Face(on, RGB($326496)));

    BoxStyle() required parameters:
        - stylename
            The name of the style being defined.

    Box() required parameters:
        - X
            The horizontal position of the element's face. This
            position may be modified by the effects of Offset commands
            in containing blocks, and by Foreground's Align option.
            See those options' descriptions for more details.

        - Y
            The vertical position of the element's face. This position
            may be modified by the effects of Offset commands in
            containing blocks, and by Foreground's Align option. See
            those options' descriptions for more details.

        - width
            The horizontal dimension of the rectangle.

        - height
            The vertical dimension of the rectangle.

    Optional parameters:
        - Style(stylename)
            The name of a style style being defined is derived from.

        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping in the element.
            If no wipe is specified, the "Cut" wipe is used.

        - Face(state, <fill options>)
            The appearance of the face of the element. The state
            defaults to on. For images, <fill options> defaults to
            nothing. For other elements, <fill options> defaults to
            RGB($ffffff).

        - Shift(x, y)
            The amount the element's face, outline, and shadow are
            shifted from the specified element position. This is
            intended to be used for different button states to move
            the face without moving the backdrop or bevel. The offset
            values may be any numbers, and default to (0, 0).

        - Transparent(state)
            Whether or not pen zero is transparent. The state defaults
            to off. If this is on, any portion of the foreground
            element drawn in pen zero will not be visible, but will
            show through to the image beneath this foreground element.

        - Border(left, right, top, bottom)
            Extra space added to the edges of the element, measured in
            pixels. This effectively extends the element's bounding
            box without affecting the position of the element's face
            or the size of its face image. The border values may be 0
            or greater, and all default to 0.

        - Outline(state, Thickness(pixels), <fill options>)
            A colored outline added to the element. The state defaults
            to off. Thickness may be 1 or greater, and defaults to 1.
            <fill options> defaults to RGB(0).

        - Backdrop(state, <fill options>)
            The appearance of the bounding box of the element behind
            the face and other style options applied to the element.
            The state defaults to off. <fill options> defaults to
            RGB(0).

        - Bevel(state, Thickness(pixels), Base(color),
                Left(<fill options>), Right(<fill options>),
                Top(<fill options>), Bottom(<fill options>))
            A beveled edge added outside the element's bounding box.
            The state defaults to off. Thickness may be 1 or greater,
            and defaults to 2. Base is a hint to the authoring station
            to assist with choosing bevel colors, and is not used by
            the Screen EX otherwise. The Base color is specified as a
            4-byte hexadecimal number, where each byte encodes zero,
            red, green, and blue, from MSB to LSB. The bevel colors
            default to shades of grey.

        - Shadow(state, Offset(horizontal, vertical), <fill options>)
            A drop shadow drawn behind the element, drawn in a solid
            color. The state defaults to off. Either or both of the
            offsets can be positive or negative, and are measured in
            pixels. <fill options> defaults to RGB(0).

        - Align(horizontal, vertical)
            This determines whether the element is positioned based on
            its X,Y values, or by the Background's size and margins.
            These tables describe the alignment values and their
            meanings:

            Horizontal    Description
            ----------    -----------
            None        The left edge of the element's face is
                        positioned relative to the left edge of the
                        background. The element's X value and the
                        cumulative effect of all applicable Offset
                        commands are used for positioning the element.

            Left        The left edge of the element's face is
                        positioned at the Background's left margin.
                        The element's X value and all applicable
                        Offset commands are ignored.

            Center        The vertical centerline of the element's face
                        is positioned midway between the Background's
                        left and right margins. The element's X value
                        and all applicable Offset commands are
                        ignored.

            Right        The right edge of the element's face is
                        positioned at the Background's right margin.
                        The element's X value and all applicable
                        Offset commands are ignored.

            Vertical    Description
            --------    -----------
            None        The top edge of the element's face is
                        positioned relative to the left edge of the
                        background. The element's Y value and the
                        cumulative effect of all applicable Offset
                        commands are used for positioning the element.

            Top            The top edge of the element's face is
                        positioned at the Background's top margin. The
                        element's Y value and all applicable Offset
                        commands are ignored.

            Middle        The horizontal centerline of the element's
                        face is positioned midway between the
                        Background's top and bottom margins. The
                        element's Y value and all applicable Offset
                        commands are ignored.

            Bottom        The bottom edge of the element's face is
                        positioned at the Background's bottom margin.
                        The element's Y value and all applicable
                        Offset commands are ignored.

            If this option is not specified, the element's alignment
            defaults to (None, None).

        - Replace(state)
            This determines whether an element command will create a
            new element or replace an existing element previously
            created by the same command. If the state is On, the
            element command will replace the previous element created
            by the same command. If the state is Off, a new element
            will be created, and any previous elements created by the
            same command will remain on the screen. This defaults to
            Replace(On).

Button():

    Button() creates an interactive element on the display.
    Buttons do not support styles.

    Button(
        [ Wipe(wipename, <wipe options>) ]
        [ HotKey( [shift-][alt-][ctrl-]<keyname> ) ]
        [ BoxedHit(on|off) ]
        [ LinkPositions(on|off) ]
        [ MatchSize(on|off) ]
        [ Normal( [ Text|Clip|Box( <command params here > ), ]
                [ Use|Goto(<branch parameters>) ] ) ]
        [ Highlight( [ MousePointer( <filename> ), ]
                [ Text|Clip|Box( <command params here > ), ]
                [ Use|Goto(<branch parameters>) ] ) ]
        [ Select( [ MousePointer( <filename> ), ]
                [ Text|Clip|Box( <command params here > ), ]
                [ Use|Goto(<branch parameters>) ] ) ]
        [ SelectDown( [ Use|Goto(<branch parameters>) ] ) ]
        );

    Examples:

        Button(HotKey("F"), MatchSize(On),
            Normal(Text(20, 20, "hello", Wrap(Off, Auto(610)))),
            Select(Goto("btn: hello", Bookmark(On))));
        Button(HotKey("F12"), MatchSize(On),
            Normal(Text(20, 20, "Test button",
                Backdrop(On, Image("Scala:\buttons\steel\steel01.bmp")),
                Wrap(Off, Auto(610)))),
            Highlight(Text(20, 20, "Test button",
                Backdrop(On, Image("Scala:\buttons\steel\steel02.bmp")),
                Wrap(Off, Auto(610)))),
            Select(Text(20, 20, "Test button",
                Backdrop(On, Image("Scala:\buttons\steel\steel03.bmp")),
                Shift(10, 10), Wrap(Off, Auto(610))), Goto("_TempName1")));
        Button(Wipe("Flyon", Direction(0)), HotKey("Space"), MatchSize(On),
            Normal(Text(20, 20, "foo", Wrap(Off, Auto(610)))),
            Select(Text(20, 20, "foo", Wrap(Off, Auto(610))), Return()));

    Optional parameters:

        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping in the element.
            If no wipe is specified, the "Cut" wipe is used.

        - HotKey( [shift-][alt-][ctrl-]<keyname> )
            Specifies the key that triggers the button's selection. Buttons
            support all the keys below along with all of the qualifiers,
            although many of them don't really make sense to use
            (shift-1, ctrl-alt-DEL).

                UP, DOWN, LEFT, RIGHT, ENTER, HELP, TAB,
                SPACE, BACKSPACE, ESCAPE, F1-F12, A-Z,
                !\#$%&'()*+,-./:;<=>?@[\]^_`{|}~

            The authoring station only allows A-Z, 0-9, F1-F12, and SPACE,
            and doesn't permit modifiers.

            Keys are specified in double quotes (they are string parameters).
            For example:

                HotKey("SHIFT-ENTER"),
                HotKey("ALT-F1"),
                HotKey("&"),
                HotKey("CTRL-R"),

        - BoxedHit(on|off)
            Tells the button to use the bounding box as the hit area
            for the mouse.

        - LinkPositions(on|off)
            Pertains only to authoring.

        - MatchSize(on|off)
            If on, all faces will have the same rectangular size.

        - Normal(
                [ Text|Clip|Box( <command params here > ), ]
                [ Use|Goto(<branch parameters>) ]*
                ),
            The Text, Clip, or Box options is an embedded Element command.
            With the exception of the Wipe options, the embedded Element
            command supports all normal options. Wipe options will be ignored.

            The Use|Goto branches are embedded player branches and accept
            their normal parameters.

        - Highlight(
                [ MousePointer( <filename> ), ]
                [ Text|Clip|Box( <command params here > ), ]
                [ Use|Goto(<branch parameters>) ]*
                ),
            The Text, Clip, or Box options is an embedded Element command.
            With the exception of the Wipe options, the embedded Element
            command supports all normal options. Wipe options will be ignored.

            The Use|Goto branches are embedded player branches and accept
            their normal parameters.

        - Select(
                [ MousePointer( <filename> ), ]
                [ Text|Clip|Box( <command params here > ), ]
                [ Use|Goto(<branch parameters>) ]*
                ),
            The Text, Clip, or Box options is an embedded Element command.
            With the exception of the Wipe options, the embedded Element
            command supports all normal options. Wipe options will be ignored.

            The Use|Goto branches are embedded player branches and accept
            their normal parameters.

        - SelectDown(
                [ Use|Goto(<branch parameters>) ]*
                ),
            The Use|Goto branches are embedded player branches and accept
            their normal parameters.

Clip() and ClipStyle():

    Clip() creates a foreground object that is a rectangle drawn with a still
    image. ClipStyle() creates a style object that can be used to specify a
    common set of options used by one or more Clip commands.

    ClipStyle(stylename,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(state, <fill options>) ]
        [ Shift(x, y) ]
        [ Transparent(state) ]
        [ Border(left, right, top, bottom) ]
        [ Outline(state, Thickness(pixels), <fill options>) ]
        [ Backdrop(state, <fill options>) ]
        [ Bevel(state, Thickness(pixels), Base(color),
            Left(<fill options>), Right(<fill options>),
            Top(<fill options>), Bottom(<fill options>)) ]
        [ Shadow(state, Offset(horizontal, vertical), <fill options>) ]
        [ Align(horizontal, vertical) ]
        [ Replace(state) ]
        [ Frame(frame) ]
        [ Operation(state, <operation options>) ]
        );

    Clip(X,Y,filename,
        [ Style(stylename) ]
        [ Wipe(wipename, <wipe options>) ]
        [ Face(state, <fill options>) ]
        [ Shift(x, y) ]
        [ Transparent(state) ]
        [ Border(left, right, top, bottom) ]
        [ Outline(state, Thickness(pixels), <fill options>) ]
        [ Backdrop(state, <fill options>) ]
        [ Bevel(state, Thickness(pixels), Base(color),
            Left(<fill options>), Right(<fill options>),
            Top(<fill options>), Bottom(<fill options>)) ]
        [ Shadow(state, Offset(horizontal, vertical), <fill options>) ]
        [ Align(horizontal, vertical) ]
        [ Replace(state) ]
        [ Frame(frame) ]
        [ Operation(state, <operation options>) ]
        );

    Examples:
        ClipStyle(Ricky, Operation(Crop(10, 10, 80, 80)));
        ClipStyle(Lucy, Style(Ricky), Operation(Resize(100, 100)));
        Clip(x, y, "pic3.bmp");
        Clip(x, y, "pic3.bmp", Style(Lucy), Bevel(on));

    ClipStyle() required parameters:
        - stylename
            The name of the style being defined.

    Clip() required parameters:
        - X
            The horizontal position of the element's face. This
            position may be modified by the effects of Offset commands
            in containing blocks, and by Foreground's Align option.
            See those options' descriptions for more details.

        - Y
            The vertical position of the element's face. This position
            may be modified by the effects of Offset commands in
            containing blocks, and by Foreground's Align option. See
            those options' descriptions for more details.

        - filename
            The name of the file containing the image data.

    Optional parameters:
        - Style(stylename)
            The name of a style style being defined is derived from.

        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping in the element.
            If no wipe is specified, the "Cut" wipe is used.

        - Face(state, <fill options>)
            The appearance of the face of the element. The state
            defaults to on. For images, <fill options> defaults to
            nothing. For other elements, <fill options> defaults to
            RGB($ffffff).

        - Shift(x, y)
            The amount the element's face, outline, and shadow are
            shifted from the specified element position. This is
            intended to be used for different button states to move
            the face without moving the backdrop or bevel. The offset
            values may be any numbers, and default to (0, 0).

        - Transparent(state)
            Whether or not pen zero is transparent. The state defaults
            to off. If this is on, any portion of the foreground
            element drawn in pen zero will not be visible, but will
            show through to the image beneath this foreground element.

        - Border(left, right, top, bottom)
            Extra space added to the edges of the element, measured in
            pixels. This effectively extends the element's bounding
            box without affecting the position of the element's face
            or the size of its face image. The border values may be 0
            or greater, and all default to 0.

        - Outline(state, Thickness(pixels), <fill options>)
            A colored outline added to the element. The state defaults
            to off. Thickness may be 1 or greater, and defaults to 1.
            <fill options> defaults to RGB(0).

        - Backdrop(state, <fill options>)
            The appearance of the bounding box of the element behind
            the face and other style options applied to the element.
            The state defaults to off. <fill options> defaults to
            RGB(0).

        - Bevel(state, Thickness(pixels), Base(color),
                Left(<fill options>), Right(<fill options>),
                Top(<fill options>), Bottom(<fill options>))
            A beveled edge added outside the element's bounding box.
            The state defaults to off. Thickness may be 1 or greater,
            and defaults to 2. Base is a hint to the authoring station
            to assist with choosing bevel colors, and is not used by
            the Screen EX otherwise. The Base color is specified as a
            4-byte hexadecimal number, where each byte encodes zero,
            red, green, and blue, from MSB to LSB. The bevel colors
            default to shades of grey.

        - Shadow(state, Offset(horizontal, vertical), <fill options>)
            A drop shadow drawn behind the element, drawn in a solid
            color. The state defaults to off. Either or both of the
            offsets can be positive or negative, and are measured in
            pixels. <fill options> defaults to RGB(0).

        - Align(horizontal, vertical)
            This determines whether the element is positioned based on
            its X,Y values, or by the Background's size and margins.
            These tables describe the alignment values and their
            meanings:

            Horizontal    Description
            ----------    -----------
            None        The left edge of the element's face is
                        positioned relative to the left edge of the
                        background. The element's X value and the
                        cumulative effect of all applicable Offset
                        commands are used for positioning the element.

            Left        The left edge of the element's face is
                        positioned at the Background's left margin.
                        The element's X value and all applicable
                        Offset commands are ignored.

            Center        The vertical centerline of the element's face
                        is positioned midway between the Background's
                        left and right margins. The element's X value
                        and all applicable Offset commands are
                        ignored.

            Right        The right edge of the element's face is
                        positioned at the Background's right margin.
                        The element's X value and all applicable
                        Offset commands are ignored.

            Vertical    Description
            --------    -----------
            None        The top edge of the element's face is
                        positioned relative to the left edge of the
                        background. The element's Y value and the
                        cumulative effect of all applicable Offset
                        commands are used for positioning the element.

            Top            The top edge of the element's face is
                        positioned at the Background's top margin. The
                        element's Y value and all applicable Offset
                        commands are ignored.

            Middle        The horizontal centerline of the element's
                        face is positioned midway between the
                        Background's top and bottom margins. The
                        element's Y value and all applicable Offset
                        commands are ignored.

            Bottom        The bottom edge of the element's face is
                        positioned at the Background's bottom margin.
                        The element's Y value and all applicable
                        Offset commands are ignored.

            If this option is not specified, the element's alignment
            defaults to (None, None).

        - Replace(state)
            This determines whether an element command will create a
            new element or replace an existing element previously
            created by the same command. If the state is On, the
            element command will replace the previous element created
            by the same command. If the state is Off, a new element
            will be created, and any previous elements created by the
            same command will remain on the screen. This defaults to
            Replace(On).

        - Frame(frame)
            Which image is to be used from the named file, if the file
            contains multiple images.

        - Operation(state, <operation options>)
            Specifies the operations done before drawing this image.
            The state defaults to off.

Text():

    This command creates a foreground object that is one or more words
    of text drawn with a specified font and effects.

    Text(X,Y,string,
        [ Wipe(wipename, <wipe options>) ]
        [ Face(state, <fill options>) ]
        [ Shift(x, y) ]
        [ Transparent(state) ]
        [ Border(left, right, top, bottom) ]
        [ Outline(state, Thickness(pixels), <fill options>) ]
        [ Backdrop(state, <fill options>) ]
        [ Bevel(state, Thickness(pixels), Base(color),
            Left(<fill options>), Right(<fill options>),
            Top(<fill options>), Bottom(<fill options>)) ]
        [ Shadow(state, Offset(horizontal, vertical), <fill options>) ]
        [ Align(horizontal, vertical) ]
        [ Replace(state) ]
        [ Append(string) ]
        [ Wrap(bool [,Width(w)] [,Auto(w)]) ]
        [ Justify(horizontal,vertical) ]
        [ Leading(value) ]
        [ Live(bool) ]
        [ Font(name, size) ]
        [ Italic(bool [,Delta(value)]) ]
        [ Bold(bool [,Delta(value)]) ]
        [ Kerning(enum) ]
        [ Spacing(value) ]
        [ Underline(bool
            [,Position(value)] [,Thickness(value)]
            [,Air(value)] [,Pen(pen)]) ]
        );

    Text() required parameters:
        - X
            The horizontal position of the element's face. This
            position may be modified by the effects of Offset commands
            in containing blocks, and by Foreground's Align option.
            See those options' descriptions for more details.

        - Y
            The vertical position of the element's face. This position
            may be modified by the effects of Offset commands in
            containing blocks, and by Foreground's Align option. See
            those options' descriptions for more details.

        - string
            A double quoted ASCII/Latin1 string of text to print.

    Optional parameters:
        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping in the element.
            If no wipe is specified, the "Cut" wipe is used.

        - Face(state, <fill options>)
            The appearance of the face of the element. The state
            defaults to on. For images, <fill options> defaults to
            nothing. For other elements, <fill options> defaults to
            RGB($ffffff).

        - Shift(x, y)
            The amount the element's face, outline, and shadow are
            shifted from the specified element position. This is
            intended to be used for different button states to move
            the face without moving the backdrop or bevel. The offset
            values may be any numbers, and default to (0, 0).

        - Transparent(state)
            Whether or not pen zero is transparent. The state defaults
            to off. If this is on, any portion of the foreground
            element drawn in pen zero will not be visible, but will
            show through to the image beneath this foreground element.

        - Border(left, right, top, bottom)
            Extra space added to the edges of the element, measured in
            pixels. This effectively extends the element's bounding
            box without affecting the position of the element's face
            or the size of its face image. The border values may be 0
            or greater, and all default to 0.

        - Outline(state, Thickness(pixels), <fill options>)
            A colored outline added to the element. The state defaults
            to off. Thickness may be 1 or greater, and defaults to 1.
            <fill options> defaults to RGB(0).

        - Backdrop(state, <fill options>)
            The appearance of the bounding box of the element behind
            the face and other style options applied to the element.
            The state defaults to off. <fill options> defaults to
            RGB(0).

        - Bevel(state, Thickness(pixels), Base(color),
                Left(<fill options>), Right(<fill options>),
                Top(<fill options>), Bottom(<fill options>))
            A beveled edge added outside the element's bounding box.
            The state defaults to off. Thickness may be 1 or greater,
            and defaults to 2. Base is a hint to the authoring station
            to assist with choosing bevel colors, and is not used by
            the Screen EX otherwise. The Base color is specified as a
            4-byte hexadecimal number, where each byte encodes zero,
            red, green, and blue, from MSB to LSB. The bevel colors
            default to shades of grey.

        - Shadow(state, Offset(horizontal, vertical), <fill options>)
            A drop shadow drawn behind the element, drawn in a solid
            color. The state defaults to off. Either or both of the
            offsets can be positive or negative, and are measured in
            pixels. <fill options> defaults to RGB(0).

        - Align(horizontal, vertical)
            This determines whether the element is positioned based on
            its X,Y values, or by the Background's size and margins.
            These tables describe the alignment values and their
            meanings:

            Horizontal    Description
            ----------    -----------
            None        The left edge of the element's face is
                        positioned relative to the left edge of the
                        background. The element's X value and the
                        cumulative effect of all applicable Offset
                        commands are used for positioning the element.

            Left        The left edge of the element's face is
                        positioned at the Background's left margin.
                        The element's X value and all applicable
                        Offset commands are ignored.

            Center        The vertical centerline of the element's face
                        is positioned midway between the Background's
                        left and right margins. The element's X value
                        and all applicable Offset commands are
                        ignored.

            Right        The right edge of the element's face is
                        positioned at the Background's right margin.
                        The element's X value and all applicable
                        Offset commands are ignored.

            Vertical    Description
            --------    -----------
            None        The top edge of the element's face is
                        positioned relative to the left edge of the
                        background. The element's Y value and the
                        cumulative effect of all applicable Offset
                        commands are used for positioning the element.

            Top            The top edge of the element's face is
                        positioned at the Background's top margin. The
                        element's Y value and all applicable Offset
                        commands are ignored.

            Middle        The horizontal centerline of the element's
                        face is positioned midway between the
                        Background's top and bottom margins. The
                        element's Y value and all applicable Offset
                        commands are ignored.

            Bottom        The bottom edge of the element's face is
                        positioned at the Background's bottom margin.
                        The element's Y value and all applicable
                        Offset commands are ignored.

            If this option is not specified, the element's alignment
            defaults to (None, None).

        - Replace(state)
            This determines whether an element command will create a
            new element or replace an existing element previously
            created by the same command. If the state is On, the
            element command will replace the previous element created
            by the same command. If the state is Off, a new element
            will be created, and any previous elements created by the
            same command will remain on the screen. This defaults to
            Replace(On).

        - Append()
            May appear multiple times within the Text() command.

            Text can have style changes imbedded in the string data. These
            can be encoded by breaking the string into pieces within the same
            TEXT command using the APPEND option. Options that can be used
            within the TEXT command, and within the APPEND option are listed
            below. For every option that is not specified within an APPEND
            option, that option is inherited from the enclosing TEXT
            attributes. If an option is specified within an APPEND option,
            all of the defaults for that option take precedence if the
            sub-options are not specified within the option.

            APPEND(string)
                string    - A double quoted ASCII/Latin1 string of text.

            Note that the authoring station will never generate an APPEND
            option that has no sub-options specified. It would be an
            inefficient way to encode the script.

        - Wrap()
            The Wrap() option is valid only within the Text() command.
            Because it affects the layout of all text in the Text() command,
            including any text in Append() options, it is not valid within an
            Append() option.

            DEFAULT: Word wrap is Off.

            WRAP(bool, <WIDTH(w)>, <AUTO(w)>)
                bool    - "On" or "Off"

            Note that the authoring station will never generate both a WIDTH
            and an AUTO sub-option. If both are specified, AUTO takes
            precedence. The default is word-wrap is off. If the option is
            missing, or written as WRAP(), or written as WRAP(Off), these are
            all equivalent. If neither WIDTH or AUTO is specified, WRAP(On)
            is invalid by itself, and is treated as WRAP(Off).

            The Width() and Auto() sub-options are valid within a Wrap(On)
            option.

                WIDTH(w)
                AUTO(w)
                    w    - integer word-wrap width.

                These sub-options are almost equivalent. Hand written
                scripts will almost always use WIDTH, while authoring
                generated scripts are more likely to use AUTO. AUTO has the
                additional meaning that the wrap-width, and state are
                uncommitted during authoring.

                If word-wrap is set to Auto during editing (the default),
                word-wrap is effectively on during the editing session. Then
                if the text wrapped during the editing session, this
                information is saved in the script as Wrap(On,Auto(width)),
                and if it did not wrap, it is saved as
                Wrap(Off,Auto(width)). This serves as a performance hint to
                the playback engine because Wrap(Off) text renders somewhat
                faster than word-wrapped text. The user wrap width are also
                saved in the script in this way so that the same width is
                used when the script is loaded again for editing.

                The authoring station may also generate Wrap(On,Width()) if
                the user selects word-wrap On in the styles menu. This is
                primarily of use for script that have variables in the
                strings so that word-wrap can be forced on, whether or not
                the text wrapped during authoring.

                If the user selects word-wrap Off in the styles menu, the
                authoring station will not generate the WRAP option or any
                of it's sub-options because this is the default. Setting
                word-wrap to explicitly to Off is primarily of use for
                scripts that have variables in the strings so that word-wrap
                can be forced off, no matter how long the text is at
                evaluation time. It is also the default, so that
                hand-written scripts that commonly have single lines of
                text, and no variables are encoded in the smallest form.

        - Justify()
            The Justify() option is valid only within the Text() command.
            Because it affects the layout of all text in the Text() command,
            including any text in Append() options, it is not valid within an
            Append() option. Note that the Text() Justify() option can be
            combined with the element Align() option to set the alignment of
            the text within the element (Justify) and the alignment of the
            element relative to the page margins (Align).

            DEFAULT: Text lines are left aligned, top position.

            JUSTIFY(horizontal,vertical)
                horizontal - Left or Center or Right
                vertical - Top or Middle or Bottom

            Note that full text justification is not currently supported, so
            this option is currently only supports left, center, or right
            alignment of multiline text. It can be specified for single line
            text, but has no visible effect.

            Vertical placement is not supported at this time.

        - Leading()
            The Leading() option is valid only within the Text() command.
            Because it affects the layout of all text in the Text() command,
            including any text in Append() options, it is not valid within an
            Append() option.

            DEFAULT: Zero (0) pixels of space between lines of text.

            LEADING(value)
                value - A positive or negative integer.

            Used to add or subtract lines of pixels between lines of text
            within the same text element. It can be specified for single line
            text, but has no visible effect at playback time.

        - Live()
            The Live() option is valid only within the Text() command.

            DEFAULT: Live(On)

            LIVE(bool)
                bool - On or Off

            The LIVE option is used to enable/disable playback time updating
            of variables. If On (the default), a text element will auto
            update if a variable in a string changes.

            Note that variables must be entirely within a string, in other
            words, it is not possible to change styles in the middle of a
            variable, though it is possible to have variables displayed in
            different styles in the same TEXT command by using the APPEND
            option.

        - Font()
            The Font() option is valid within the Text() command, or Append()
            option.

            DEFAULT: System dependent, but it is SFuturaX 24 for MM100, and
            will therefore stay that way in the future for compatability on
            DOS products.

            FONT(<name>, <size>)
                name - Font name in double quotes such as "SCompact".
                size - Integer size of font, in pixels.

            Note that for the bitmap fonts the font must be installed,
            matching both name and size else the Text() command will fail
            with an error set. Note that both name and size are required
            for the FONT option.

        - Italic()
            The Italic() option is valid within the Text() command, or
            Append() option.

            DEFAULT: By default, Italic is Off on all systems, though the
            default italic delta is system dependent (it is 16 on DOS
            platforms including MM100, 32 on the GI box)

            ITALIC(bool <DELTA(<value>)>)
                bool - On or Off. If On, the DELTA sub-option can also be
                       specified.

            The ITALIC option is used to apply algorithmic slant to a font.
            It can be used to increase or decrease the slant of any font,
            including fonts that are designed as Italic.

            The Delta() sub-option is valid within an Italic(On) option.

                DELTA(value)
                    value - An integer amount in the range of -99 to +99.

                Negative numbers apply algorithmic backward (to the left
                visually) slant to the glyphs in a font, positive numbers apply
                forward slant. Examples include:

                    +99 - Approximately 1.5:1 slant ratio to the right.
                    +64 - 1:1 slant ratio (45 degrees) to the right.
                    +32 - 1:2 slant ratio to the right.
                    +16 - 1:4 slant ratio to the right.
                    +00 - No algolrithmic slant.
                    -16 - 1:4 slant ratio to the left.
                    -32 - 1:2 slant ratio to the left.

                Very small slant amounts may not be visible (e.g., +1/-1)
                depending on the height of the font.

        - Bold()
            The Bold() option is valid within the Text() command, or Append()
            option.

            DEFAULT: By default, Bold is Off on all systems, though the
            default bold delta is system dependent (it is 3 on DOS systems
            including MM100).

            BOLD(bool <DELTA(<value>)>)
                bool - On or Off. If On, the DELTA sub-option can also be
                       specified.

            The BOLD option is used to apply algorithmic bold to a font. It
            can be used to increase the apparent boldness (weight) of any
            font, including those designed as light, normal, bold, extra
            bold, etc. Fonts that are made bolder in this way will not be any
            taller, but the glyphs will appear wider and thicker.

            The Delta() sub-option is valid within a Bold(On) option.

            DELTA(value)
                value - An integer amount in the range of 1 to 9.

                The delta values apply a calculation based on the weight of the
                font and the delta value to calculate additional algorithmic
                weight. This calculation performs rouding. Therefore a thinner
                font such as SCompactL will support a greater range of visible
                weight changes than would a heavier font such as SFuturaX.
                Experiment to find values that look good to you.

        - Kerning()
            The Kerning() option is valid within the Text() command, or
            Append() option.

            DEFAULT: By default, Kerning is On, and applies to both
            alphabetic characters and numeric pairs on DOS systems including
            MM100.

            KERNING(enum)
                enum - None or Alpha or AlphaNum.

            The KERNING option is used to apply kerning between character
            pairs. Valid character pairs for kerning are determined by the
            font, but usually include alphabetic character pairs, plus
            alphabetic characters followed by some symbols (usually
            punctuation marks). In addition, kerning can be enabled or
            disabled for numeric pairs. It is most often useful to turning
            numeric kerning off for tables or other text in which monospacing
            of the numeric glyphs is preferred. For standalone text, numeric
            pair kerning may look better.

            Example:
                Text(20, 20, "a", Append("b", Kerning(None)), Append("cdef"));

            Note that kerning is between characters. Therefore in this
            example, "ab" are kerned, but "bc" are not kerned, and "cdef" are
            kerned.

        - Spacing()
            The Spacing() option is valid within the Text() command, or
            Append() option.

            DEFAULT: Zero (0) extra space between glyphs.

            SPACING(value)
                value - -9 through +999

            The SPACING option is used to add/subtract an additional amount
            of pixel space between glyphs. It can be applied in addition to
            kerning to fine adjust spacing.

            Note that positive spacing at the end of lines is visually
            stripped, and does not contribute the size of the text element.

            Example:
                Text(20, 20, "a", Append("b", Spacing(2)), Append("cdef"));

            Note that spacing is between characters. Therefore in this
            example, "ab" have 0 extra space, "bc" have 2 pixels of extra
            space, and "cdef" have 0 extra space between the glyphs.

        - Pen control options
            The following are pen control options, and have the same syntax
            as screen elements. They are valid within the Text() command, or
            Append() option.

                FACE(bool, <Pen(pen)>)
                OUTLINE(bool, <Thickness(value)>, <Pen(pen)>)
                SHADOW(bool, <Offset(horizontal,vertical)>, <Pen(pen)>)

        - Underline()
            The Underline() option is valid within the Text() command, or
            Append() option.

            DEFAULT: Underline off.

            UNDERLINE(bool, <Position(value)>, <Thickness(value)>,
                            <Air(value)>, <Pen(pen)>)
                bool - On or Off. If Off, sub-options have no visible effect.

            The Air() sub-option is valid within an Underline(On) option.

            DEFAULT: 1 pixel of air.

            AIR(value)
                value - A positive integer with a range of 0 through 3
                inclusive. Used to control the space between glyphs and
                the underline bar. A value of 0 is a solid underline.

            The Position() sub-option is valid within an Underline(On)
            option.

            DEFAULT: Depends on font; often 1 pixel below the baseline.

            Position(value)
                value - A positive or negative integer that is used to control
                the underline bar position relative to the font's baseline.

                Negative values move the underline start position above the
                baseline, positive values below. A value of 0 places the
                top of the underline bar at the baseline.

                If the sub-option is not specified, the font's suggested
                underline position is used.

            The Thickness() sub-option is valid within an Underline(On)
            option. DEFAULT: Depends on font.

            Thickness(value)
                value - A positive integer that is used to control the
                thickness of the underline bar in pixels.

                If the sub-option is not specified, the font's suggested
                underline thickness is used.

            The Pen() sub-option is valid within an Underline(On) option.
            DEFAULT: Same as face pen.

            Pen(value)
                value - An indexed pen value. See FACE, OUTLINE, and SHADOW.

                If the sub-option is not specified, the FACE pen is used for
                the underline pen.


3. Non-Element Commands
-----------------------

These are descriptions of other commands supported by the Screen EX
and related software. These commands do not create elements, but they
can affect elements that are displayed.

Offset():

    The Offset command, when used in the Group list of a Scala Script
    block, offsets the positions of all Foreground elements by the
    specified offset amount. If Offset commands are used in nested
    blocks, the net result of each Offset command is added together
    to determine the effective offset for Foreground elements in the
    most nested block. The effect of having an Offset command in a
    group list between several foreground elements is undefined.

    This command is useful when grouping related Foreground elements
    so the group can be moved around easily during authoring. The
    Offset command can be used for positioning the group, and
    Foreground elements within the group are positioned relative to
    the group's effective position, taking into account the offsets
    of all nested groups.

    Offset(X,Y);

    Offset() required parameters:
        - X
            The horizontal offset, relative to the left edge of the
            background.

        - Y
            The vertical offset, relative to the top edge of the
            background.

Preload():

    (supports only one filename at a time so far)
    The Preload command obtains a SnapScope object for each file
    listed on its command line during its Do_EVENT_Make method, and
    releases these objects during its Do_EVENT_End method.

    Preload(filename);

    Examples:
        Preload(":scala/pictures/kjell.flc");
        Preload(":scala/pictures/oyvind.bmp", ":scala/pictures/lars.bmp");

    Preload() required parameters:
        - filename
            The name of a file to be loaded. The file must be in a
            format supported by the currently loaded set of SnapLoad
            parsers. One or more filenames may be specified. If more
            than one filename is specified, they must be separated by
            commas.

WipeOut():

    The WipeOut command wipes out an element that has been wiped in.

    WipeOut(elementname,
        [ Wipe(wipename, <wipe options>) ]
        );

    WipeOut() required parameters:
        - elementname
            The script label of the command that created the
            foreground element to be wiped out, or the label of a
            block containing at least one foreground element to be
            wiped out.

    Optional parameters:
        - Wipe(wipename, <wipe options>)
            A description of the wipe used for wiping out the element.

4. Option Groups
----------------

These are descriptions of the option groups that are used in several
different classes. Rather than repeat the descriptions for each class
that supports these options, this section describes them once.

<fill options>:

    There are several fill options, only one of which can be used at a
    time. If none of these options are used, the behaviour depends on
    the element.

        - Pen(pen)
            A pen used for filling the specified area.

        - RGB(color)
            A solid color used for filling the specified area. This
            is not used directly, but the closest matching pen from the
            current background's palette is used.

        - Tile(filename, Frame(frame),
                Operation(<operation options>),
                Justify(horizontal, vertical),
                Offset(direction, amount))
            (implemented only for Box, Display, and Foreground's Backdrop)
            Specifies an image to be tiled onto the specified area,
            and options describing how it is to be tiled.

            Filename specifies the name of the file containing the
            image data to be used. This image file may be a stretcher
            file or a standard bitmap file.

            Frame specifies which image is to be used from
            the named file, if the file contains multiple images.

            Justify(horizontal, vertical) specifies how the image is
            justified when tiling.

            Offset(direction, amount) specifies the offset for the
            tiled image from one row (or column) to the next.

        - Image(filename, Frame(frame), Operation(<operation options>))
            (implemented only for Box, Display, and Foreground's Backdrop)
            Specifies an image to be drawn into the specified area.
            The image will be sized to fit the filled area, using an
            appropriate scaling method for the source image.

            Filename specifies the name of the file containing the
            image data to be used. This image file may be a stretcher
            file or a standard bitmap file.

            Frame specifies which image is to be used from
            the named file, if the file contains multiple images.

<operation options>:

    There are several operation options, which may be used in
    combination. The options specified are applied in this order:

        - Crop(left, top, width, height)
            A sub-part of the image to be displayed. By default, the
            image is not cropped and the entire source image is used.

        - Flip(horizontal, vertical)
            (vertical flip not implemented yet)
            Flip the source image in the horizontal and/or vertical
            direction before using it for drawing the element. This
            defaults to Flip(off, off).

        - Rotate(angle)
            Rotate the source image clockwise the specified angle
            before using it for drawing the element. The angle is
            specified in degrees clockwise from North, and is limited
            to the range 0 through 359, inclusive.

        - Resize(width, height)
            Scale the image, using absolute scaling.

            Width indicates the new width in pixels for the image.
            This may be 1 or greater, and defaults to the nominal
            width of the image.

            Height indicates the new height in pixels for the image.
            This may be 1 or greater, and defaults to the nominal
            height of the image.

        - ImagePalette( MapToZero(pen,pen,pen...), <palette options> )
            Remap one or more pens in the source image to the pens
            from the current background's palette that most closely
            match the specified colors.

            MapToZero(pen,pen,pen...) is used to map one or more pens
            in the source image to pen zero so they will show through
            to the graphics beneath the element when the image is
            drawn with the Transparent(on) option.

        - Dither(state, Auto(autostate))
            Use Floyd-Steinberg dithering to make the source image
            more closely match its original coloring using the current
            background's palette. This defaults to off.

            Auto(autostate) is used to tell the software to ignore the
            Dither state provided, and to determine the dither state
            based on whether the image is a true color image. If
            autostate is on and the image is a true color image, then
            the image will be dithered. If autostate is on and the
            image is not a true color image, the image will not be
            dithered. If autostate is off, then the supplied dither
            state will be used. Autostate defaults to off.

<palette options>:

    There is one palette option, which may be repeated as many times
    as needed. If a Palette option is specified on a style command and
    an element command that references that style, both will be used
    in this way: first, the palette will be set from the style's
    Palette option, then from the element command's Palette option. If
    a pen is set more than once, the last color set for the pen will
    be used.

        - RGBPen(pen, color, ...)
            Set a specific pen to a specific color. Color is specified
            as a 3-byte hexadecimal number, where each byte encodes
            red, green, and blue, from MSB to LSB.
            Color may be repeated. If more than one color is
            specified, each color is assigned to the next consecutive pen,
            starting at the specified pen.

<wipe options>:

    These wipe options may be used in any combination. Some wipes may
    impose certain restrictions on the values of these options, and
    may ignore some other options altogether.

        - Speed(value)
            Indicates a subjective speed for the wipe. The value may
            range from 1 (slow) to 10 (fast) for most wipes, and
            defaults to 5. Some wipes may allow speeds outside the
            range 1-10. In all cases, the number chosen will be used
            as a guide for the Screen EX to choose a wipe wpeed that
            results in a smooth wipe.

        - Angle(degrees)
            Indicates the direction of travel for the wipe. Degrees
            may be any angle from 0 to 359 degrees, (starting at North
            and increasing clockwise), and defaults to 270 degrees
            (West). For script wipes, degrees will be rounded to the
            nearest 90-degree increment.

        - Flip(horizontal, vertical)
            Indicates whether the wipe is flipped horizontally and/or
            vertically. This defaults to Flip(off, off).