MACROMEDIA DIRECTOR AND LINGO

Cast
Score
Movie
Stage
Menus

Programming
Events
Handlers
Scripts
Debugging
Variables
Lists
Objects
Puppets

Shockwave

Cast

A cast is a database of multimedia objects. Everything that appears in your movie is refered to as a cast member. That includes all of the images, whether they are snapshots of a cartoon character in motion, props on the stage, or background images. Titles and labels are also cast members. So are the buttons you push and the text areas that you write in. Even the sound effects and instructions to the computer (scripts) are cast members.

All cast members are stored in a cast, which may be viewed with the cast window (select Cast from the Window option on the menu bar). A cast members may be referenced by a number (reflecting its position in the cast) or a name that you gave it. You can rearrange cast members within the cast at any time, so it's a good idea to always refer to cast members by their name rather than their number.

Although something must be a cast member in order to appear in the movie, cast members don't actually appear in the movie until they are placed on stage.

• Cast member is a single object
• graphic
• text
• movie
• sound
• button
• script

• Cast members may be created using Director, or imported from another source
• Sprite is an instance of a cast member

Score

The score tracks the action in your application. The score is similar in appearance (and function) to timing sheets used in traditional animation. The main part of the score is a large table divided into rows and columns. Each column corresponds to a different instant of time or frame. Each row corresponds to a different channel. The numbered channels are the sprite channels, which show what sprites are on the stage. Notice that there is a limit to the number of sprites that can appear on stage at any one time. There are also special channels for everything else that goes on in the movie, including two sound channels, a timing channel, and a script channel (for computer instructions).

When you play your movie, Director does this by showing one frame after another until it reaches the end of the movie. It starts at the current frame, so you have to rewind if you want to start from the beginning. The end of the movie is the last frame (column) that has anything in it. You can set the frame rate in either the control panel or in the timing channel.

• Frame represents an instant of time
• Tempo determines the rate at which frames are viewed
• Frames may be Marked and Labeled for future reference
• Represented by a column in the score
• Channel represents an individual sprite, effect, or script over time
• Up to 128 graphic channels
• Effects channels for Tempos, Transitions, Palettes, and Sounds
• Script channel
• Represented by a row in the score
• Cell contains information about one sprite at one frame in the application

Movie

The resulting application, described by the Score, is called a Movie. A movie has a beginning, a middle and an end. You can play the movie, stop the movie, rewind the movie. You can even splice movies together, or show a movie inside another movie.

When you save a movie, Director creates a file on your disk. This file contains all the necessary information about your movie, so you can always go back and change it. One of the nice things about Director is that the movie file format is platform independent. This means you can create a movie on a Macintosh and then play/edit that movie on a Windows computer, or vice versa (as long as you have Director installed on both machines).

• Stage is the window where all action occurs
• Scripts provide interactivity with lists of instructions or descriptions
• Instructions are written in Lingo
• Activated by Events
• Scripts may be associated with different parts of the movie
• Cast member script
• Sprite script
• Frame script
• Movie script

Stage

All the action in your movie takes place on the stage. It's that big blank area that you see when you first start up Director. You create your movie by arranging your cast members on the stage. Placing cast members on the stage is very easy: you simply click on the cast member you want, and then drag it onto the stage (while holding down the mouse button; releasing the button "drops" the cast member where it is).

What you see on the stage is actually a copy of the cast member known as a sprite. Each sprite has properties such as its position on stage and its size (you can make it bigger or smaller). This means that if you have one picture of a bird in your cast, you can use that to create a hundred birds of various sizes all over the stage.

Menus

• Control Panel - stepping through and playing the movie
• Cast - store, show, and edit cast members
• Score - control the action
• Paint - create bitmapped cast members
• Tools - add text, buttons, shapes directly to a frame
• Marker - shows all marked frames

Programming Capabilities

• Lingo supports a variety of decision and control statements, including loops and conditional branching.
• Lingo is weakly typed, with variables taking on the type of whatever they are assigned. So, a variable x can contain a string in one part of the program, and an integer later on (although this is not recommended). A variable that hasn't been assigned a value is void by default.
• Variables may contain simple values -- such as integers, reals, booleans, or strings -- or more complex data -- including arrays and objects. Lingo provides functions for discovering the type of a variable, and for changing the type of the variable (e.g. integer to real).
• Lingo supports both linear arrays and associative arrays. The elements of an array need not all be of the same type.
• Variables may be local (by default) or global (if declared) in their scope.
• Director also maintains a set of system variables which you cannot set, but can refer to. All of these begin with the keyword "the". Some examples are
  • the frame = the number of the frame that is currently displayed on Stage
  • the mouseLoc = the current location of the mouse pointer on Stage, measured in pixels from the left and top edges of the Stage
  • the clickOn = the number of the sprite that was most recently clicked on
• Lingo is not case sensitive. In fact, even strings aren't case sensitive: in Lingo, "STOP" is equivalent to "stop".

Program Flow

Director handles events internally, then gives your application the opportunity to perform additional tasks in response to the event.

• Your script does not gain control until it is given that control by Director (in response to an event)
• Once your script has control, it retains control until the end of the handler is reached
• After the end is reached, Director regains control, processes the next event

Event-Driven Program

A Lingo "program" is actually a collection of scripts or handlers. Playing a movie can be viewed as a succession of events. The movie starts; each frame is shown (entered and exited); the movie stops. Director also recognizes several other events: a mouse button is clicked; a key on the keyboard is pressed; a timer runs out. Normally, these events go by unnoticed. That is, unless the creator of the movie has written event handlers indicating that something else should be done.

An event handler is a sequence of instructions to the computer. When the named event occurs, the computer follows (executes) the instructions within the handler. Handlers are written in scripts using a language called Lingo. Lingo is a powerful scripting language that supports everything you would expect from a programming language: branching and conditional statements; local and global variables; sequential and associative arrays; string, numeric, and boolean operators. It even supports a form of object-oriented class definition. Lingo is what makes Director a powerful tool for creating interactive multimedia. It's also a fun language to learn and use, whether you're an experienced programmer or a complete novice.

A handler is invoked in response to either an event or a direct call. Director automatically captures and delivers the following events:

• enterFrame
• exitFrame
• idle
• keyDown
• keyUp
• mouseDown
• mouseUp
• startMovie
• stepMovie
• stopMovie

Event Hierarchy

Director uses a hierarchy to determine what handler (if any) should respond to a given event:

• Sprite
• score script is attached to the sprite in the score, for the current frame
• on keyDown, keyUp, mouseDown, mouseUp
• Cast
• cast member script attached directly to the cast member
• on keyDown, keyUp, mouseDown, mouseUp
• Frame
• score script placed in the script channel of the current frame
• on keyDown, keyUp, mouseDown, mouseUp, enterFrame, exitFrame
• Movie
• movie script associated with the entire movie
• on all events

Overriding the Event Hierarchy

You may also intercept this hierarchy by defining a primary event handler:

• the keyDownScript
• the keyUpScript
• the mouseDownScript
• the mouseUpScript

Example:

set the keyDownScript to "detectKeys"

After the specified handler is executed, it passes the event on to the usual event hierarchy unless it encounters a dontPassEvent instruction.

Handlers

Handlers are subroutines (procedures or functions) that accomplish specific tasks.

• Event handlers
• invoked by Director in response to pre-defined events
• defined as Score (sprite or frame), Movie, or Cast Member scripts
• Personal handlers
• invoked by calls made in other handlers
• defined as Movie or Cast Member (object) scripts
• All handler definitions begin with the keyword on and end with the keyword end

Personal Handlers

Handlers are defined using the syntax:

on handlername [ param1, param2, ... ]
    statements
end [ handlername ]

In addition to performing tasks, a handler may return a valuereturn expressionHandlers are called one of two ways

• as a procedure
  handlername param1, param2, ...
• as a function
  varname = handlername ( param1, param2, ... )

Handlers and Events

A block of code, starting with "on" and ending with "end", is known as a handler.

Each handler corresponds to some event. When that event occurs, all of the statements in the corresponding handler are executed in sequential order. Events may be triggered by the user doing something (like clicking the mouse button) or they may occur naturally as part of playing the movie (like going from frame to frame). The programmer can also define events. It's important to remember that Director will always do precisely what it is told to do, in the order that it is told to do it in.

Playing a Movie startMovie stopMovie enterFrame exitFrame

Triggered by User keyDown mouseDown mouseUp idle

Different Types of Scripts

In addition to handling a lot of different kinds of events, Lingo allows you to relate an event to some object in the movie. So, for example, you could have a bunch of buttons on the stage, and something different happens when you click each one.

A script may be associated with a sprite, a cast member, a frame in the movie, or the entire movie. Whenever a pre-defined event occurs, Director takes the following steps:

• If the cursor is over a sprite, and there is a handler for the event associated with that sprite, then that handler is executed.
• Otherwise, if the cursor is over a sprite, and there is a handler for the event associated with the cast member for that sprite, then that handler is executed.
• Otherwise, if there is a handler for the event associated with the current frame, then that handler is executed.
• Otherwise, if there is a handler for the event in a movie script, then that handler is executed.
• Otherwise, the event is ignored.

Using the Script Window

Before writing a lot of Lingo scripts, it's good to become familiar with the script window.

• A blinking cursor shows the current position in the script. If you type anything, or paste in some text (using Edit -> Paste in the menu bar), the text will appear where the cursor is. The box directly above the script area shows what handler the current position is in; if it isn't in any handler, you will see "[global]".
• If you highlight some text and then start typing, whatever you type will replace the highlighted text.
• The button with "i" in a blue circle is used to change the type of the script. A movie script is automatically associated with the movie you are working on; a score script may be explicitly linked to either a frame or a sprite.
• The button marked with "L" brings up an alphabetized list of Lingo statements. Hold down the mouse button as you scroll through the list, and then release the mouse button when you find the command that you want. The command will then be inserted where the cursor is (or the text is highlighted) in your script. This is a great way to ensure your script has the correct syntax!
• The button next to the "L" brings up a categorized list of Lingo statements. It works the same way as the "L" button; the only difference is how the statements are organized in the list.
• The button with two dashes in it ("--") will add two dashes to your script. In Lingo, anything that appears on a line after two dashes is considered a comment. A comment is text that is there simply to remind you, the programmer, of what you're doing; it is ignored by Director when the handler is executed. Use this button to temporarily disable one or more lines of code in your handler.
• The button next to this un-comments text in the script.

It's important to note that Director doesn't necessarily know about your scripts until you do one of two things:

• Close the Script window, or
• Select Control -> Recompile All Scripts from the menu bar.

When you do this, Director will check for syntax errors (i.e. determine whether or not it knows how to follow the instructions you have given it). If there are syntax errors, a pop-up window will give you the choice of ignoring the errors (not a good idea) or going to the place in the script that is causing the error. It's then up to you to debug your program.

Debugging With the Message Window

As with all programming languages (and, in fact, all languages of any kind), Lingo has its own syntax and semantics. Semantics are concerned with the meaning of statements in the language. Syntax is concerned with rules of how these statements are structured.If the statements in your program don't follow the syntactic rules exactly, the computer won't know what to do, and so it will give up. The semantics are equally precise: the computer will only do exactly what it is told to do, in the order it is told to do it in.

Each Lingo statement appears on a separate line; when the line ends, the statement ends. Whenever a handler is invoked, Director interprets and executes the statements line by line. Director also provides a message window (select Window -> Message from the menu bar) where you can type in Lingo commands. When you press the Enter key, Director interprets and executes that statement. This is a good way to test Lingo statements (to see what they do). It's also a good way to check the values and types of variables.

Variables

Variables are named memory slots that contain information that may change as the program is executed

• Names begin with a letter, and may contain letters, digits, and '_'
• Variables are created as they are used
• Local to the handler it is used in (default)
• Global variable
• must be declared as such at the beginning of every handler that uses it
• global varname [ , varname ]

Variable Types

Variable type is determined by its contents. A variable that has not been assigned a value has a default value of <Void>.

• Testing the type of a variable
• floatP(varname)
• integerP(varname)
• listP(varname)
• objectP(varname)
• stringP(varname)
• symbolP(varname)
• voidP(varname)
• Changing the type of a variable
• charToNum(string)
• float(expression)
• integer(expression)
• point(horizontal, vertical)
• rect(left, top, right, bottom)
• rect(point1, point2)
• string(expression)
• value(string)

Variable Assignment and Operators

Variable values are set one of two ways:

set varname to expression

set varname = expression

• Numeric expressions
• literals - floats contain decimal point
• math operators
• +  -  *  /  mod
• abs  atan  cos  exp  sin  sqrt
• boolean operators
• TRUE = 1, FALSE = 0
• =  <  <=  >  >=  <>
• and  or  not
• String expressions
• literals - surrounded by double quotes
• constants
• BACKSPACE
• EMPTY
• ENTER
• QUOTE
• RETURN
• TAB
• concatenation
• & - concatenates 2 strings
• && - concatenates 2 strings and adds a space between them

Lists

Lists are ordered sets of values, like arrays or records (struct) in other programming languages.

• Empty list may be expressed as
• []
• list()
• The size of a list is determined by the number of elements assigned to it (dynamic)
• Elements of a list need not be all the same type
• Elements of a list may be enumerated (linear lists) or labeled (property lists)
• List operators are only valid on lists that have been defined

Linear Lists

Linear lists contain sequences of values, referred to by their positions.

• Defining a list
• [ 1, 2.5, "this", [ a, b, c ] ]
• list (1, 2.5, "this", [ a, b, c] )
• Adding elements
• add (list, value)
• addAt (list, position, value)
• append (list, value)
• Accessing elements
• count (list)
• getAt (list, position)
• getLast (list)
• getPos (list, value)
• max (list)
• min (list)
• Modifying elements
• deleteAt (list, position)
• setAt (list, position, value)
• Sorting elements - sort (list)
• sorts by value
• add retains sorted order
• Arithmetic operations
• applies operation to all elements of the list
• put mylist + 5

Property Lists

Property lists contain labeled values, referred to by their labels. You may also use numbers instead of labels.

• Defining a list
• [ #item: "Snowboard", #cost: 400, #quantity: 1 ]

• Adding elements
• addProp (list, property, value)
• Accessing elements
• count (list)
• findPos (list, property)
• findPosNear (list, property)
• getProp (list, property)
• getLast (list)
• getPropAt (list, value)
• max (list)
• min (list)
• Modifying elements
• deleteAt (list, position)
• setaProp (list, property, value)
• Sorting elements - sort (list)
• sorts by label
• retains sorted order
• Arithmetic operations
• applies operation to all elements of the list
• put mylist + 5

Objects

An object is an entity with properties and behaviors defined by a class.

• A class is defined in the script of a cast member
• An object is created with the new handler
  set varname = new (script castMember)
• Behaviors are defined by handlers in the class script
• in the definition, the 1st parameter is always me
• in the call, the 1st argument is always the object reference
• Properties are variables where an object may store values
• each object carries its own unique set of properties
• the ancestor property implements inheritence
• object properties may only be referenced by handlers in the class

Working with Puppets

Normally the Score determines what cast members appear where on the stage, keeping track of 48 sprite channels and their attributes in each frame. However, your Lingo scripts may also control the appearance of the stage by manipulating sprite attributes. In order for your script to take control of a sprite channel, you must make that sprite a puppet.

• When you make a sprite a puppet, Lingo gains control and the Score loses control of that sprite channel.
• puppetSprite sprite_channel, TRUE
• set the puppet of sprite sprite_channel to TRUE
• To return control of a sprite to the Score, you must turn off the puppet property for that sprite channel.
• puppetSprite sprite_channel, FALSE
• set the puppet of sprite sprite_channel to FALSE

Changing Sprite Properties

To change the attributes (properties) of a sprite channel, use the following Lingo statement:set the property of sprite sprite_channel to valueYou may set the following properties of a sprite:

• memberNum - cast member instantiated by the sprite, represented as a cast number
• height - vertical dimension of the sprite, measured in pixels
• width - horizontal dimension of the sprite, measured in pixels
• locH - horizontal position of the sprite's registration point, measured in pixels from the left edge of the stage
• locV - vertical position of the sprite's registration point, measured in pixels from the top edge of the stage
• constraint - restrict the sprite's location such that its registration point must lie over another indicated sprite
• moveableSprite - affects the user's ability to move the sprite interactively (TRUE or FALSE)
• trails - indicates whether a moving sprite's previous locations should be shown (TRUE or FALSE)
• visible - indicates whether the sprite is visible or not (TRUE or FALSE)
• cursor - affects the appearance of the cursor as it rolls over the sprite
• ink - horizontal position of the sprite, measured in pixels from the left edge of the stage
• blend - horizontal position of the sprite, measured in pixels from the left edge of the stage
• foreColor - foreground color of the sprite (only for cast members created with the Tool Palette)
• backColor - background color of the sprite (only for cast members created with the Tool Palette)

• calling updateStage
• re-entering the current frame:
  on exitFrame
    ....
      go to the frame
  end

• Movie script - in effect as long as the movie is playing
• on startMovie
• on endMovie
• in custom handles (functions) that you write
• Frame script - in effect for the frame in which it appears
• on enterFrame
• on exitFrame

• Castmember script - in effect when a castmember is selected
• on mouseDown
• on mouseUp
• Sprite script - in effect when a sprite is selected
• on mouseDown
• on mouseUp

Guidelines for Creating Shockwave Movies

Make your movie as small as possible, to reduce download times

• Set your stage size to a reasonable size
• Use 8-bit color for your graphics
• Use shapes and fields instead of bitmaps when feasible
• Use transitions, inks, and color maps for special effects
• Create large backgrounds from small repeated tiles

• No Movies In A Window
• No linked media
• No file access
• No references to cast libraries with external names
• Xtras must be included with .dcr file