CD-ROM Magazin 1997 May

home *** CD-ROM | disk | FTP | other *** search

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

Wrap

Text File | 1997-03-02 | 217KB | 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).