Lingo Programming

If you want your movie to do anything other than just play from beginning to end, you must control what it does with Lingo.

Lingo is ...

• an interpreted language,
• event-driven,
• weakly typed,
• case-insensitive, and
• extensible with Xtra libraries.

Lingo commands are terminated by a RETURN character. If your line is getting too long, you can place the "\" continutation character at the end of the line, and continue on the next line.

Comments are preceded by "--", and end with the end of the line.

Events

A Lingo "program" is actually a collection of functions or handlers. A handler defines what should be done when it is invoked in response to either an event or a direct call. All Lingo commands must appear inside a handler, and are executed only when that handler is invoked.

Director automatically detects a number of events when the movie is playing. Here are just a few:

• exitFrame - when the play head moves from one frame to the next
• idle - nothing is happening
• keyDown - a key on the keyboard has been pressed
• mouseUp - the mouse button has just been released
• startMovie - we just started playing the Director movie
• beginSprite - a sprite has just appeared on the stage

Scripts

A script is a collection of one or more handlers, which can be viewed on the same page. Director supports 4 types of scripts:

• movie scripts contain handlers that are global in scope
• behavior scripts contain handlers that are explicitly associated with specific sprites and/or frames
• parent scripts define objects that are created with the new command
• cast scripts contain handlers that are explicitly associated with a specific cast member

Whenever an event occurs, Director uses the following hierarchy to determine what handler (if any) should be invoked:

• Sprite
• score script, attached to the sprite that the mouse is over, for the current frame
• on keyDown, keyUp, mouseDown, mouseUp
• Cast
• cast script, associated with the cast member that the mouse is over
• 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

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.

Defining Handlers

Handlers are subroutines (procedures or functions) that accomplish specific tasks. All handler definitions begin with the keyword on and end with the keyword end.

• 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

Handlers are defined using the syntax:

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

In addition to performing tasks, a handler may return a value

return expression

Handlers are called one of two ways

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

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