CD-ROM Magazin 1997 May/CD_05_97.ISO/doc/script.txt

Text File | 1997-03-02 | 212.3 KB | 5,491 lines

ScalaScript
===========

Foreword

This document provides an overview of the ScalaScript language and its
capabilities under MM200.  Updates to this document will be made available
at the web page http://www.scala.com/scripting.

In general, users of Scala products should not have to resort to hand-editing
scripts--the authoring system should provide all necessary features.  However,
if a feature is required that is not supported by the authoring system, then
manual updating of a script may be required.  It is posible to create new
scripts outside of the authoring system, as well as hand-edit scripts that
were created by the authoring system.

Note that loading an hand-edited or hand-authored script into the authoring
system may produce unexpected results.

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

Contents:

1.  The ScalaScript Language
2.  Launch EX Script Commands and Variables
3.  FileIO EX Script Commands and Variables
4.  Sound EX Script Commands and Variables
5.  Input EX Script Commands and Variables
6.  Time Script Functions and Variables
7.  MPEG EX Script Commands and Variables
8.  Screen 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.

Optional
--------

Commands may be marked as optional by putting the word "optional" in front
of them. The "optional" keyword follows any label, but preceeds the command.

An optional command is one that is not required for the execution of the
script.  If the EX that handles the command is available, then the command
should be normally processed.  If the EX is unavailable, then any errors
should be quietly suppressed and the script playback should proceed without
the command.

    optional my_command(1, foo(on));       // this command not required.

NoAuthor
--------

The 'noauthor' directive keeps Scala from allowing the "group" (cluster) to
be gone into in the editor.  Usually used on hand-authored scripts that
author wouldn't understand.

    noauthor my_command(1, foo(on));

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)
    anytype CONDITIONAL(boolean Expr, any OnTrue, any On False)
    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
-----------------------------------------------

Conditional Functions
---------------------

Conditional
    anytype CONDITIONAL(boolean Expr, anytype OnTrue, anytype On False)

    This function does not show up in the Branch menu list of functions.

    The function Conditional(Expr, OnTrue, OnFalse) takes an expression that
    evaluates to a boolean. If Expr evaluates to TRUE, then OnTrue is returned.
    If Expr evaluates to FALSE, then OnFalse is returned. This is very useful
    for things like:

        page = page + Conditional(line > 20, 1, 0);
        str = word + Conditional(number > 1, "'s", "");

    Otherwise doing things like this requires setting up complex conditional
    pages. It is similar to the C/C++ language construct "?".

    This function is unusual in that any type of variable may be used.
    However, the function return, OnTrue and OnFalse must all be of the
    same type.

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.  Launch EX Script Commands and Variables
===========================================

The Launch EX provides a single command that is used to start other programs
outside of the Scala application.

    Launch (command_line, Minimized(state), Wait(state));

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

3.  FileIO EX Script Commands and Variables
==========================================

Overview
--------

Function          Description
--------          -----------
Open()            Open a file or directory.
Close()           Close a file or directory.
ReadStr()         Read a line from an open file and return it as a string.
ReadInt()         Read a line from an open file, convert it to an integer
                  and return the integer.
ReadBool()        Read a line from an open file, convert it to a boolean
                  (where 1=TRUE and 0=FALSE) and return the boolean.
ReadChars()       Read a number of characters from an open file and return
                  it as a string.
WriteStr()        Write a string to an open file.  The string is written
                  as a complete line, with CR/LF appended.
WriteInt()        Write an integer to an open file.  The integer is written
                  as a complete line, with CR/LF appended.
WriteBool()       Write a boolean to an open file.  The boolean is written
                  as a complete line, with CR/LF appended.
WriteChars()      Write a number of characters to an open file.  Only the
                  characters are written, with no trailing CR/LF.
MkDir()           Create a directory.
FileSize()        Get the size of a file.
RmDir()           Remove a directory.
Eof()             Check for end-of-file condition on an open file.
Erase()           Erase a file.
Rename()          Rename a file.
Copy()            Copy a file.

FileIO variable summary:

Variable          Description
--------          -----------
FileIO.Status     Contains the status returned by the last call to
                  any of the FileIO functions.

Open Function
--------------

This function will open a file or directory for processing.  It will
return a filehandle that will be used in the future to reference the
file until the file is closed.

Note that all File I/O access is restricted to the "Data" directory
within the "Scala" directory.  You are not allowed to use full path
names or drive letters when specifying file names.  All file names
are expected to be relative to the Data directory.

Open has three different access modes.  The first mode is READ, when
the file is opened for READ access only READs may occur.  If a Write
is attempted and error is the result.

The second mode is WRITE, which implies READ access as well.  With this
setting a file can be used for both READING and WRITING.

The third mode is APPEND, which applies both READ and WRITE Access.  The
difference with APPEND is that the filepointer is not set to point at
the end of the file as opposed to the beginning of the file as with all
of the other modes.

Syntax:
-------

FileHandle = INTEGER Open("filename", READ)
FileHandle = INTEGER Open("filename", WRITE)
FileHandle = INTEGER Open("filename", APPEND)
DirHandle  = INTEGER Open("directory", DIR)

Returns
-------

If successful a positive integer value is returned.  If there is a
failure a zero will be returned.

Close Function
--------------

The Close function will close the current open file or directory.  The
user would pass the FileHandle or DirHandle to the close function.

Syntax
------

status = INTEGER Close(INTEGER FileHandle)
status = INTEGER Close(INTEGER DirHandle)

Returns
-------

If succesful Close() returns 0.
This command also sets FileIO.Status.  The variable will
contain 1 if successful, or 0 zero if not.

ReadStr Function
----------------

This function will read from the specified filehandle an entire line
of text from the file.

Syntax
------

buffer = STRING ReadStr(INTEGER FileHandle)

Returns
-------

Will return either a string or "" if it fails.
This command also sets FileIO.Status.  The variable will
contain 1 if successful, or 0 zero if not.

ReadInt Function
----------------

The ReadInt Function will read from the provided filehandle a single
integer.

Syntax
------

value = INTEGER ReadInt(INTEGER FileHandle)

Returns
-------

returns an integer value.

This command also sets FileIO.Status.  The variable will
contain 1 if successful, or 0 zero if not.

ReadBool Function
------------------

Reads a single line of text from a file.  Then the text is converted
into an integer.  If this succeeds then a 1 is returned otherwise
a zero is returned.

Example text.dat file

    text              result
    ------------      ------
    80 some text ---> Returns 1 (because this converts to an 80)
    1            ---> Returns 1
    some text 4  ---> Returns 0 (because this does not convert to an integer)
    0            ---> Returns 0

Syntax
------

value = BOOLEAN ReadBool(INTEGER FileHandle)

Returns
-------

Returns either a 0 or a 1

This command also sets FileIO.Status.  The variable will
contain 1 if successful, or 0 zero if not.

ReadChars Function
------------------

This function will read the specified number of characters from the
file.  It should be noted that Scala STRING variables can not contain
any illegal character data.  NO special characters or binary data
may be held in this type of variable.

Syntax
------

buffer = STRING ReadChars(INTEGER FileHandle, INTEGER BytesToRead)

Returns
-------

Returns either a string or NULL.

This command also sets FileIO.Status.  The variable will
contain 1 if successful, or 0 zero if not.

WriteStr Function
-----------------

This function will write the specified string into the opened
text file.  It will add a CR/LF to the end of the line before
it is written to the file.

Syntax
------

status = BOOLEAN WriteStr(INTEGER FileHandle, STRING buffer)

Returns
-------

Returns TRUE if succesful, FALSE if failure.

WriteInt Function
------------------

This function will convert the specified integer into a string
and write that string to a text file appending a CR/LF sequence
to the end of the string.

Syntax
------

status = BOOLEAN WriteInt(INTEGER FileHandle, INTEGER value)

Returns
-------

Returns TRUE if successful, FALSE if failure.

WriteBool Function
------------------

This function will convert the specified boolean value into a
string (either a "1" or a "0") and append a CR/LF to the string
and write the string to the file specified.

Syntax
------

status = BOOLEAN WriteBool(INTEGER FileHandle, BOOLEAN value)

Returns
-------

Returns TRUE if successful, FALSE if failure.

WriteChars Function
-------------------

Writes the specified number of bytes from the variable specified to
a file.  It will NOT add a CR/LF sequence to the end of the string
prior to writing to the file.

Syntax
------

bytes = INTEGER WriteChars(INTEGER FileHandle, STRING buffer,
                INTEGER BytesToWrite)

Returns
-------

Number of bytes written.

This command also sets FileIO.Status.  The variable will
contain 1 if successful, or 0 zero if not.

MkDir Function
--------------

Creates the specified directory.  The function will accept any valid
Scala filename.

Syntax
------

status = BOOLEAN MkDir("filename")

Returns
-------

Returns TRUE if successful, FALSE if failure.

FileSize Function
-----------------

Returns the number of bytes a specified file uses on a disk.

Syntax
------

bytes = INTEGER FileSize("filename")

Returns
-------

Byte count.

This command also sets FileIO.Status.  The variable will
contain 1 if successful, or 0 zero if not.

RmDir Function
---------------

Deletes the directory specified.  In order for this function to be
successful the directory must be empty first.

Syntax
------

status = BOOLEAN RmDir("filename")

Returns
-------

TRUE successful, FALSE if failure

Eof Function
-------------

This function will return a 1 if you have read all of the data contained
in the file.  It will return a zero otherwise.

Syntax
------

status = BOOLEAN Eof(INTEGER FileHandle)

Returns
-------

TRUE if End of File
FALSE if not at end of file

This command also sets FileIO.Status.  The variable will
contain 1 if successful, or 0 zero if not.

Erase function
--------------

This function will delete a file.

Syntax
------

status = BOOLEAN Erase("filename")

Returns
-------

TRUE if successful, FALSE if failure

Rename Function
---------------

Renames the source file to the specified destination file.

Syntax
------

status = BOOLEAN Rename("filename1", "filename2")

Returns
-------

TRUE if successful, FALSE if failure

Copy Function
--------------

Copies the source file to the specified destrination file.

Syntax
------

status = BOOLEAN Copy("filename1", "filename2")

Returns
-------

TRUE if successful, FALSE if failure

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

4.  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).

MIDI playback is done entirely by the Sound EX.

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

The sound for MM200 is processed through Microsoft DirectX support, and does
not depend on proprietary hardware drivers.  Most of the variables listed
in this section are now obsolete.

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

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

5.  Input EX Script Commands
============================

Input():

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

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

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

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

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


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

    - MouseControls( BOOLEAN )
        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( BOOLEAN )
        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( BOOLEAN )
        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.

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

6.  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.

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

7.  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)

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

8.  Screen Script Commands and Variables
===========================================

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

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 system 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 system 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 system 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.

Screen.Switched (boolean)
    This variable changes to TRUE when the Scala application is
    switched in, and to FALSE when it is switched out. A script can
    resume execution at a specific position by setting up
    notification on this variable. Without this notification, the
    script will exit when playback is switched out.

Screen.ViewColorModel (string)
    If set, this tells the system to force all background elements
    to use a specific View ColorModel, as if the View ColorModel
    suboption was specified in each background command. This can be
    PaletteMapped, HiColor, or TrueColor. This overrides any View
    option specified in the background command.

Screen.ViewRefreshRate (integer)
    It takes an integer, and determines the refresh rate used by all pages.
    Zero uses the system default.

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

AnimStyle():

    This command creates a style object that can be used to specify a
    common set of options used by one or more Anim commands.

    Synopsis:

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

    Examples:

        AnimStyle(Barnum, Speed(40));
        AnimStyle(Bailey, Style(Barnum), Speed(60), Wipe("FlyLeft"));

    Required Parameters Used by This Class:

        - stylename
            The name of the style being defined.

    Optional Parameters Supported by This Class:

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

        - 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.

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

        - 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.

        - PlayAfter(state)
            Whether the animation shall stop after the first frame
            and let the sequence list be played before resuming the
            animation. Default to FALSE. If FALSE then the animation
            will be played first, then the element in the sequence
            list will be played.

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

        - 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.

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

        - 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.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - 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.

Anim():

    This command creates an animation background.

    All <operation options> are available for Anim() with the exception
    of TransparentRGB. In most cases, performance will not be good enough
    for any of the <operation options> to be used.

    Synopsis:

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

    Examples:

        Anim("show.flc");
        Anim("show2.flc", Style(Barnum), Loops(5));

    Required Parameters Used by This Class:

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

    Optional Parameters Supported by This Class:

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

        - 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.

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

        - 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.

        - PlayAfter(state)
            Whether the animation shall stop after the first frame
            and let the sequence list be played before resuming the
            animation. Default to FALSE. If FALSE then the animation
            will be played first, then the element in the sequence
            list will be played.

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

        - 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.

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

        - 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.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - 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.

DisplayStyle():

    This command creates a style object that can be used to specify a
    common set of options used by one or more Display commands.

    Synopsis:

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

    Examples:

        DisplayStyle(Fred, View(Mode("NTSC 704")));
        DisplayStyle(Wilma, Style(Fred), Face(RGB(0)));

    Required Parameters Used by This Class:

        - stylename
            The name of the style being defined.

    Optional Parameters Supported by This Class:

        - 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($ffffff).

        - 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.

        - 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.

        - 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.

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

        - 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.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))

        - 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.

Display():

    This command creates a solid color or a patterned background.

    Synopsis:

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

    Examples:

        Display(Face(RGB($ffffff)));
        Display(Style(Fred), Face(Tile("scalabang.bmp")), Size(608,400));

    Optional Parameters Supported by This Class:

        - 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($ffffff).

        - 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.

        - 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.

        - 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.

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

        - 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.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - 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.

MovieStyle():

     MovieStyle() creates a style object that can be used to specify a
     common set of options used by one or more Movie commands.

    Synopsis:

        MovieStyle(stylename,
                [, Loops(loops) ]
                [, Margin(left, right, top, bottom) ]
                [, Operation(state, <operation options>) ]
                [, Palette( Clear(state), <palette options> ) ]
                [, PlayAfter(state) ]
                [, Style(stylename) ]
                [, Tabs(Implicit(width), Explicit(tab, ...)) ]
                [, UserPalette( Clear(state), <palette options> ) ]
                [, View(Mode(name), Size(width, height), ColorModel(colors)) ]
                [, Volume(volume) ]
                [, Wipe(wipename, <wipe options>) ]
                );

    Examples:

        MovieStyle(Barnum, Speed(40));
        MovieStyle(Bailey, Style(Barnum), Speed(60), Wipe("FlyLeft"));

    Required Parameters Used by This Class:

        - stylename
            The name of the style being defined.

    Optional Parameters Supported by This Class:

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

        - 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.

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

        - 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.

        - PlayAfter(state)
            Whether the animation shall stop after the first frame
            and let the sequence list be played before resuming the
            animation. Default to FALSE. If FALSE then the animation
            will be played first, then the element in the sequence
            list will be played.

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

        - 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.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - Volume(volume)
            This specifies the volume for the movie / movieclip.
            Range is 0 to 255. Defaults to 255 meaning full
            volume. 0 is silence.

        - 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.

Movie()

    Movie() creates an movie background.

    All <operation options> are available for Movie() with the exception
    of TransparentRGB. In most cases, performance will not be good enough
    for any of the <operation options> to be used.

    Synopsis:

        Movie(filename,
                [, Loops(loops) ]
                [, Margin(left, right, top, bottom) ]
                [, Operation(state, <operation options>) ]
                [, Palette( Clear(state), <palette options> ) ]
                [, PlayAfter(state) ]
                [, Style(stylename) ]
                [, Tabs(Implicit(width), Explicit(tab, ...)) ]
                [, UserPalette( Clear(state), <palette options> ) ]
                [, View(Mode(name), Size(width, height), ColorModel(colors)) ]
                [, Volume(volume) ]
                [, Wipe(wipename, <wipe options>) ]
                );


    Examples:

        Movie("show.avi");
        Movie("show2.avi", Style(Barnum), Loops(5));

    Required Parameters Used by This Class:

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

    Optional Parameters Supported by This Class:

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

        - 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.

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

        - 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.

        - PlayAfter(state)
            Whether the animation shall stop after the first frame
            and let the sequence list be played before resuming the
            animation. Default to FALSE. If FALSE then the animation
            will be played first, then the element in the sequence
            list will be played.

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

        - 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.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - Volume(volume)
            This specifies the volume for the movie / movieclip.
            Range is 0 to 255. Defaults to 255 meaning full
            volume. 0 is silence.

        - 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.

PictureStyle():

    This command creates a style object that can be used to specify a
    common set of options used by one or more Picture commands.

    Synopsis:

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

    Examples:

        PictureStyle(MaryAnn,
            Operation(On, ImagePalette(RGBPen(1, $ff00ff, $ffff00))));
        PictureStyle(Ginger, Style(MaryAnn));

    Required Parameters Used by This Class:

        - stylename
            The name of the style being defined.

    Optional Parameters Supported by This Class:

        - 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($ffffff).

        - 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.

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

        - 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.

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

        - 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.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - 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.

Picture():

    This command creates a still image background.

    Synopsis:

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

    Examples:

        Picture("pic1.bmp");
        Picture("pic2.bmp", Style(Ginger), Operation(On, Resize(800, 600)));

    Required Parameters Used by This Class:

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

    Optional Parameters Supported by This Class:

        - 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($ffffff).

        - 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.

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

        - 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.

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

        - 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.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

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

AnimClipStyle():

    AnimClipStyle() creates a style object that can be used to specify a
    common set of options used by one or more AnimClip commands.

    Synopsis:

         AnimClipStyle( stylename,
                [, Loops(loops) ]
                [, Margin(left, right, top, bottom) ]
                [, Operation(state, <operation options>) ]
                [, Palette( Clear(state), <palette options> ) ]
                [, Speed(speed) ]
                [, StopAtFirstFrame(state) ]
                [, Style(stylename) ]
                [, Tabs(Implicit(width), Explicit(tab, ...)) ]
                [, Transparent(state) ]
                [, UserPalette( Clear(state), <palette options> ) ]
                [, View(Mode(name), Size(width, height), ColorModel(colors)) ]
                [, Wait(state) ]
                [, Wipe(wipename, <wipe options>) ]
                );

    Examples:

         AnimClipStyle(Barnum, Speed(40));
         AnimClipStyle(Bailey, Style(Barnum), Speed(60), Wipe("FlyLeft"));

    Required Parameters Used by This Class:

        - stylename
            The name of the style being defined.

    Optional Parameters Supported by This Class:

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

        - 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.

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

        - 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.

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

        - 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.

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

        - 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.

        - Transparent(state)
            This specifies if there should be any transparent areas
            in the front image. This option is used with the
            Operation(TransparentRGB()) option to turn on
            transparency.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - Wait(state)
            Whether the player shall wait until the animation is
            finished before continuing with the sequence list.
            Defaults to FALSE. If FALSE we will not wait until the
            current animclip is finished before continuing the script.

        - 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.

AnimClip()

    AnimClip() creates an animated object that may be placed on a page.

    All <operation options> are available for AnimClip(), but, in most cases,
    performance will not be good enough for them to be used.

    Synopsis:

        AnimClip( filename,
                [, Loops(loops) ]
                [, Margin(left, right, top, bottom) ]
                [, Operation(state, <operation options>) ]
                [, Palette( Clear(state), <palette options> ) ]
                [, Speed(speed) ]
                [, StopAtFirstFrame(state) ]
                [, Style(stylename) ]
                [, Tabs(Implicit(width), Explicit(tab, ...)) ]
                [, Transparent(state) ]
                [, UserPalette( Clear(state), <palette options> ) ]
                [, View(Mode(name), Size(width, height), ColorModel(colors)) ]
                [, Wait(state) ]
                [, Wipe(wipename, <wipe options>) ]
                );

    Examples:

        AnimClip("show.flc");
        AnimClip("show2.flc", Style(Barnum), Loops(5));

    Required Parameters Used by This Class:

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

    Optional Parameters Supported by This Class:

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

        - 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.

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

        - 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.

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

        - 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.

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

        - 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.

        - Transparent(state)
            This specifies if there should be any transparent areas
            in the front image. This option is used with the
            Operation(TransparentRGB()) option to turn on
            transparency.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - Wait(state)
            Whether the player shall wait until the animation is
            finished before continuing with the sequence list.
            Defaults to FALSE. If FALSE we will not wait until the
            current animclip is finished before continuing the script.

        - 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.

BoxStyle():

    This command creates a style object that can be used to specify a
    common set of options used by one or more Box commands.

    Synopsis:

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

    Examples:

        BoxStyle(Rowan, Wipe("Center", Speed(7)));
        BoxStyle(Martin, Style(Rowan), Outline(on, Thickness(2), Pen(3)));

    Required Parameters Used by This Class:

        - stylename
            The name of the style being defined.

    Optional Parameters Supported by This Class:

        - 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).

        - Antialias(state)
            This determines if the element is antialiased. The state
            defaults to off.

        - 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($7f7f7f).

        - 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 system 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.

        - 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.

        - 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).

        - Focus(state, <fill options>)
            How to highlight the face of the last-wiped-in element.
            When a new element gets wiped in, the face of this element
            reverts to its normal face appearance. If a group of
            elements are wiped in together, each element with this
            option specified will be highlighted. The state defaults
            to off. <fill options> defaults to RGB($ffff7f).

        - 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).

        - 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).

        - 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).

        - 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).

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

        - 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.

        - 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.

Box():

    This command creates a foreground object that is a rectangle drawn
    in a solid color or a pattern.

    Synopsis:

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

    Examples:

        Box(x, y, width, height, Face(Pen(4)));
        Box(x, y, width, height, Style(Martin), Face(on, RGB($326496)));

    Required Parameters Used by This Class:

        - X
            The horizontal position of the element's face. This
            position may be modified by the effects of Offset commands
            in containing clusters, 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 clusters, 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 Supported by This Class:

        - 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).

        - Antialias(state)
            This determines if the element is antialiased. The state
            defaults to off.

        - 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($7f7f7f).

        - 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 system 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.

        - 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.

        - 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).

        - Focus(state, <fill options>)
            How to highlight the face of the last-wiped-in element.
            When a new element gets wiped in, the face of this element
            reverts to its normal face appearance. If a group of
            elements are wiped in together, each element with this
            option specified will be highlighted. The state defaults
            to off. <fill options> defaults to RGB($ffff7f).

        - 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).

        - 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).

        - 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).

        - 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).
            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).

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

        - 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.

        - 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.

Button():

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

    Synopsis:

        Button(
                [ Wipe(wipename, <wipe options>) ]
                [ HotKey( [shift-][alt-][ctrl-]<keyname> ) ]
                [ BoxedHit(on|off) ]
                [ LinkPositions(on|off) ]
                [ MatchSize(on|off) ]
                [ Normal(
                    [ Text|Clip|AnimClip|MovieClip|Box( <command params here> ), ]
                    [ Use|Goto(<branch parameters>) ] ) ]
                [ Highlight( [ MousePointer( <filename> ), ]
                    [ Text|Clip|AnimClip|MovieClip|Box( <command params here> ), ]
                    [ Use|Goto(<branch parameters>) ] ) ]
                [ Select( [ MousePointer( <filename> ), ]
                    [ Text|Clip|AnimClip|MovieClip|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|AnimClip|MovieClip|Box( <command params here> ), ]
                [ Use|Goto(<branch parameters>) ]*
                ),
            The Text, Clip, AnimClip, MovieClip, or Box option 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|AnimClip|MovieClip|Box( <command params here> ), ]
                [ Use|Goto(<branch parameters>) ]*
                ),
            The Text, Clip, AnimClip, MovieClip, or Box option 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|AnimClip|MovieClip|Box( <command params here> ), ]
                [ Use|Goto(<branch parameters>) ]*
                ),
            The Text, Clip, AnimClip, MovieClip, or Box option 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.

ClipStyle():

    This command creates a style object that can be used to specify a
    common set of options used by one or more Clip commands.

    Synopsis:

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

    Examples:

        ClipStyle(Ricky, Operation(On, Crop(10, 10, 80, 80)));
        ClipStyle(Lucy, Style(Ricky), Operation(On, Resize(100, 100)));

    Required Parameters Used by This Class:

        - stylename
            The name of the style being defined.

    Optional Parameters Supported by This Class:

        - 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).

        - Antialias(state)
            This determines if the element is antialiased. The state
            defaults to off.

        - 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($7f7f7f).

        - 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 system 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.

        - 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.

        - 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).

        - Focus(state, <fill options>)
            How to highlight the face of the last-wiped-in element.
            When a new element gets wiped in, the face of this element
            reverts to its normal face appearance. If a group of
            elements are wiped in together, each element with this
            option specified will be highlighted. The state defaults
            to off. <fill options> defaults to RGB($ffff7f).

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

        - 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).

        - 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).

        - 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).

        - 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).

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

        - 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.

        - 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.

Clip():

    This command creates a foreground object that is a rectangle
    drawn with a still image.

    Synopsis:

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

    Examples:

        Clip(x, y, "pic3.bmp");
        Clip(x, y, "pic3.bmp", Style(Lucy), Bevel(on));

    Required Parameters Used by This Class:

        - X
            The horizontal position of the element's face. This
            position may be modified by the effects of Offset commands
            in containing clusters, 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 clusters, 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 Supported by This Class:

        - 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).

        - Antialias(state)
            This determines if the element is antialiased. The state
            defaults to off.

        - 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($7f7f7f).

        - 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 system 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.

        - 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.

        - 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).

        - Focus(state, <fill options>)
            How to highlight the face of the last-wiped-in element.
            When a new element gets wiped in, the face of this element
            reverts to its normal face appearance. If a group of
            elements are wiped in together, each element with this
            option specified will be highlighted. The state defaults
            to off. <fill options> defaults to RGB($ffff7f).

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

        - 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).

        - 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).

        - 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).

        - 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).

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

        - 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.

        - 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.

MovieClipStyle():

    MovieClipStyle() creates a style object that can be used to specify a
    common set of options used by one or more MovieClip commands.

    Synopsis:

        MovieClipStyle(stylename,
                [, Loops(loops) ]
                [, Margin(left, right, top, bottom) ]
                [, Operation(state, <operation options>) ]
                [, Palette( Clear(state), <palette options> ) ]
                [, Style(stylename) ]
                [, Tabs(Implicit(width), Explicit(tab, ...)) ]
                [, Transparent(state) ]
                [, UserPalette( Clear(state), <palette options> ) ]
                [, View(Mode(name), Size(width, height), ColorModel(colors)) ]
                [, Volume(volume) ]
                [, Wait(state) ]
                [, Wipe(wipename, <wipe options>) ]
                );

    Examples:

        MovieClipStyle(Barnum, Speed(40));
        MovieClipStyle(Bailey, Style(Barnum), Speed(60), Wipe("FlyLeft"));

    Required Parameters Used by This Class:

        - stylename
            The name of the style being defined.

    Optional Parameters Supported by This Class:

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

        - 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.

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

        - 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.

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

        - 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.

        - Transparent(state)
            This specifies if there should be any transparent areas
            in the front image. This option is used with the
            Operation(TransparentRGB()) option to turn on
            transparency.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - Volume(volume)
            This specifies the volume for the movie / movieclip.
            Range is 0 to 255. Defaults to 255 meaning full
            volume. 0 is silence.

        - Wait(state)
            Whether the player shall wait until the animation is
            finished before continuing with the sequence list.
            Defaults to FALSE. If FALSE we will not wait until the
            current animclip is finished before continuing the script.

        - 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.

MovieClip()

    MovieClip() creates an movie background.

    All <operation options> are available for MovieClip(), but, in most cases,
    performance will not be good enough for them to be used.

    Synopsis:

        MovieClip(filename,
                [, Loops(loops) ]
                [, Margin(left, right, top, bottom) ]
                [, Operation(state, <operation options>) ]
                [, Palette( Clear(state), <palette options> ) ]
                [, Style(stylename) ]
                [, Tabs(Implicit(width), Explicit(tab, ...)) ]
                [, Transparent(state) ]
                [, UserPalette( Clear(state), <palette options> ) ]
                [, View(Mode(name), Size(width, height), ColorModel(colors)) ]
                [, Volume(volume) ]
                [, Wait(state) ]
                [, Wipe(wipename, <wipe options>) ]
                );

    Examples:

        MovieClip("show.avi");
        MovieClip("show2.avi", Style(Barnum), Loops(5));

    MovieClip() required parameters:

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

    Optional Parameters Supported by This Class:

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

        - 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.

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

        - 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.

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

        - 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.

        - Transparent(state)
            This specifies if there should be any transparent areas
            in the front image. This option is used with the
            Operation(TransparentRGB()) option to turn on
            transparency.

        - 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.

        - View(Mode(name), Size(width, height), ColorModel(colors))
            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.

            ColorModel(colors) identifies the View by
            the maximum number of colors it supports. This can be
            PaletteMapped, HiColor, or TrueColor, and defaults to
            PaletteMapped.

        - Volume(volume)
            This specifies the volume for the movie / movieclip.
            Range is 0 to 255. Defaults to 255 meaning full
            volume. 0 is silence.

        - Wait(state)
            Whether the player shall wait until the animation is
            finished before continuing with the sequence list.
            Defaults to FALSE. If FALSE we will not wait until the
            current animclip is finished before continuing the script.

        - 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.

Text():

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

    Synopsis:

        Text( X, Y , string
                [, Append( string,
                    Font(typeface, size),
                    Bold(state, Delta(value)),
                    Italic(state, Delta(value)),
                    Spacing(pixels),
                    Kerning(state),
                    Face(state, <fill options>),
                    Focus(state, <fill options>),
                    Outline(state, Thickness(pixels), <fill options>),
                    Shadow(state, Offset(h, v), <fill options>),
                    Under(state, Position(top), Thickness(height),
                        Air(size), <fill options>) ]
                [, Align(horizontal, vertical) ]
                [, Antialias(state) ]
                [, Backdrop(state, <fill options>) ]
                [, Bevel(state, Thickness(pixels), Base(color),
                        Left(<fill options>), Right(<fill options>),
                        Top(<fill options>), Bottom(<fill options>)) ]
                [, Bold(state, Delta(value)) ]
                [, Border(left, right, top, bottom) ]
                [, Face(state, <fill options>) ]
                [, Focus(state, <fill options>) ]
                [, Font(typeface, size) ]
                [, Italic(state, Delta(value)) ]
                [, Justify(horizontal, vertical) ]
                [, Kerning(state) ]
                [, Leading(pixels) ]
                [, Outline(state, Thickness(pixels), <fill options>) ]
                [, Replace(state) ]
                [, Shadow(state, Offset(horizontal, vertical), <fill options>) ]
                [, Shift(x, y) ]
                [, Size(width, height) ]
                [, Spacing(pixels) ]
                [, Tabs(Relative(state), Implicit(width), Explicit(tab, ...)) ]
                [, Transparent(state) ]
                [, Under(state, Position(top), Thickness(height), Air(size),
                        <fill options>) ]
                [, Update(type) ]
                [, Wipe(wipename, <wipe options>) ]
                [, Wrap(state) ]
                );

    Examples:

        Text(x, y, "Larry");
        Text(x, y, "Curly", Face(on, Pen(3)));
        Text(x, y, "",
            Transparent(on), Under(on, Pen(1)),
            Append("John,", Face(on, RGB($ff0000))),
            Append(" Paul,", Face(on, RGB($00ff00))),
            Append(" George,", Face(on, RGB($0000ff))),
            Append(" and Ringo!", Face(on, RGB($ffff00))))

    Required Parameters Used by This Class:

        - X
            The horizontal position of the element's face. This
            position may be modified by the effects of Offset commands
            in containing clusters, 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 clusters, and by Foreground's Align option. See
            those options' descriptions for more details.

        - string
            The text string to be displayed. If this is an expression,
            and the Live option is turned on, the string displayed by
            the Text element will change each time this expression
            changes.


    Optional repeatable Parameters Supported by This Class:

        - Append(string,
                Font(typeface, size),
                Bold(state, Delta(value)),
                Italic(state, Delta(value)),
                Spacing(pixels),
                Kerning(state),
                Face(state, <fill options>),
                Focus(state, <fill options>),
                Outline(state, Thickness(pixels), <fill options>),
                Shadow(state, Offset(h, v), <fill options>),
                Under(state, Position(top), Thickness(height),
                    Air(size), <fill options>)

            This may be repeated in a Text command to create Text
            elements with in-line style changes. Each occurrence of
            the Append option creates a text segment. A text segment
            is also created by the string provided to the Text command
            itself. All text segments will be concatenated together in
            the same order as they appear in the Text command.

    Optional Parameters Supported by This Class:

        - 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).

        - Antialias(state)
            This determines if the element is antialiased. The state
            defaults to off.

        - 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($7f7f7f).

        - 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 system 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.

        - Bold(state, Delta(value))
            Indicates whether the text should be bolder than normal.
            The state defaults to off. Text weight is calculated from
            1 (thin) to 12 (black). The Delta value may range from -11
            to 11, and defaults to 3. This gives the ability to use
            any weight within the supported range with any font. Note
            that the Delta value is relative to the font's nominal
            weight, not an absolute weight value. Note also that some
            fonts won't look different at each available Delta value,
            and that bitmap fonts cannot be made thinner than their
            nominal weight.

        - 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.

        - 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).

        - Focus(state, <fill options>)
            Highlight the face of the last-wiped-in element.
            When a new element gets wiped in, the face of this element
            reverts to its normal face appearance. If a group of
            elements are wiped in together, each element with this
            option specified will be highlighted. The state defaults
            to off. <fill options> defaults to RGB($ffff7f).

            It affects the face color of focus text only; it cannot
            be used to set the color of shadow or outline, nor can
            it be used to set the face color to transparent (in the
            way Face( Off, ... ) sets the face color to transparent.)
            The underline color will only change if, after evaluation,
            the face, focus, and underline color of every text segment
            are the same AND the face, focus, and underline state of
            every text segment are in the ON state, then the focus pen
            affects the underline color too.

        - Font(typeface, size)
            The typeface and size to be used for drawing the text.

        - Italic(state, Delta(value))
            Indicates whether the text should be more or less italic
            than normal (most fonts are normally upright). The state
            defaults to off. Text slant is calculated from -99 (full
            left slant) to 99 (full right slant). The Delta value may
            range from -198 to 198, and defaults to 32. This gives the
            ability to use any slant within the supported range with
            any font. Note that the Delta value is relative to the
            font's nominal slant, not an absolute slant value.

        - Justify(horizontal, vertical)
            The justification of the text within its bounding box (if
            any). Horizontal can be Left, Center, or Right, and
            defaults to Left. Vertical can be Top, Middle, or Bottom,
            and defaults to Top. This option has no effect if no Size
            option is specified, and there is only one line of text.

        - Kerning(state)
            Indicates whether or not the text is kerned. The state
            defaults to off.

        - Leading(pixels)
            Indicates the vertical distance between lines of text in a
            Text element. Pixels may be any positive or negative
            number, and defaults to 0. This represents the number of
            pixels of space added below the bottom of each line.

        - 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).

        - 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).

        - 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).

        - 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).

        - Size(width, height)
            The horizontal and vertical dimensions of the bounding box
            for the Text element, measured in pixels. If Wrap is on,
            this will wrap text to fit the bounding box's width. If
            Wrap is off, text is clipped at the width of the bounding
            box. In both cases, text is clipped at the height of the
            bounding box.

        - Spacing(pixels)
            Indicates the intercharacter spacing of the text. Pixels
            may be any positive or negative number, and defaults to 0.
            This represents the number of pixels of space added to the
            right side of each character.

        - Tabs(Relative(state), Implicit(width), Explicit(tab, ...))
            A description of tab stops, relative to either the element
            or 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.

            Relative(state) determines whether tabs are relative to
            the element or to the background. If TRUE, tabs are
            relative to the left edge of the element. Otherwise, tabs
            are relative to the left edge of the background. The
            Relative state defaults to FALSE.

            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.

        - 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.

        - Under(state, Position(top), Thickness(height), Air(size),
                <fill options>)
            The underline of the text, if any. The state defaults to
            off. Position is measured in pixels from the top of the
            underline to the baseline of the text, increasing
            downward, and defaults to 1. Thickness is the height of
            the underline measured in pixels, and defaults to 2. Air
            is the distance in pixels between the underline and the
            nearest text pixel, and defaults to 1.

        - Update(type)
            Whether or not the text element updates when the string
            parameter is an expression, and that expression changes
            value. The type can be one of None, Normal, or Extended,
            and defaults to Extended. If the string parameter is
            constant, this option has no effect.

        - 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.

        - Wrap(state)
            Whether or not the text element wraps at the edge of its
            bounding box. The state defaults to off. If no Size option
            is specified, this option is ignored.

Non-Element Commands
--------------------

These are descriptions of other commands supported by the Screen book
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
    cluster, offsets the positions of all Foreground elements by the
    specified offset amount. If Offset commands are used in nested
    clusters, the net result of each Offset command is added together
    to determine the effective offset for Foreground elements in the
    most nested cluster. 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.

    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.

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.

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.

    All fill options have a default Pen if there is a user palette,
    and a default RGB if there is no user palette.

        - 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,
                Justify(horizontal, vertical),
                Offset(direction, amount),
                <operation options>)
            (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.

            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.

            <operation options> specifies the operations done before
            drawing this image.

        - Image(filename, <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.

            <operation options> specifies the operations done before
            drawing this image.

<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(  <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.

        - 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.

        - TransparentRGB(Color,TransparentDelta(Delta))
            This option allows you to choose a transparent color.
            The color should be given as a 32bit RGB number
            (like $7f7f7f). If TransparentDelta is specified,
            all the colors within the specified delta range from the
            main color will be transparent as well. Delta is unsigned.

<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 book to choose a wipe wpeed that
            results in a smooth wipe.

        - Direction(dir)
            Indicates the direction of travel for the wipe.

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