# Chapter 12

# Working with Lingo

CONTENTS

- Scripts
  - Frame Scripts
  - Movie Scripts
  - Scripts Attached to Cast Members
  - Sprite Scripts
- Variables
  - Global Variables
  - Local Variables
- Writing Your Own Handlers
  - Plain Vanilla Handlers
  - Passing and Returning Values in Handlers
- Simple Lingo Structures
  - Setting Values
  - Testing Using If…Then…Else Structures
  - Repeat Loops
- From Here…

If you moved to Mexico, you would probably learn Spanish. You could get by with hand gestures and a lot of enchiladas you didn't mean to order, but sooner or later you'd probably want to speak the language.

Lingo is Director's programming language. You could make movies without knowing a word of Lingo, but it's definitely worth the effort to at least learn the basics. This chapter offers you just that-a crash course in working with Lingo.

Here are a few highlights:

- Covers the various types of scripts you can write so you'll know where to use each type.
- Defines global and local variables and shows you how to use them to keep track of information.
- Shows how to write handlers to organize and streamline your scripting.
- Covers some basic programming structures, such as setting values, testing for conditions, loops, and so on.
- Provides simple examples of how to write scripts to help you get started quickly.

## Scripts

A script is a group of Lingo statements that performs a particular action. Scripts can contain one line of code or many lines. The Lingo code is organized and grouped into handlers. All handlers begin and end similarly:

>     on (event)
>        (do this action)
>     end

Fortunately Lingo is very similar to the English language, so many Lingo terms relate well to the way we speak. The above handler format can be phrased almost like a sentence: "On a certain event, perform an action, then end."

Before you start writing actual scripts, the following defines the various types and when they occur.

### Frame Scripts

Frame scripts are very common. You place them in the score in the frame script channel (figure 12.1). As the movie plays, anytime the playback head encounters a frame script, it will execute it. You may create two different types of handlers that respond in different ways:

>     on enterframe
>        (lingo commands)
>     end

>     on exitframe
>        (lingo commands)
>     end

Figure 12.1 : A frame script.

Just like they sound, the "enterframe" handler executes when the playback head enters the frame; and the "exitframe" handler executes when the playback head exits the frame.

Note
Exitframe and enterframe do not necessarily refer to leaving one frame and entering a different one. If you create a loop that stays in frame 12, for example, the playback head is still entering and exiting the same frame repeatedly.

### Movie Scripts

A movie script is available to the whole movie while it is playing (figure 12.2). Within a movie script you can place several types of handlers.

>     on startmovie
>        (lingo commands)
>     end

>     on stopmovie
>        (lingo commands)
>     end
>     on (customhandler)
>        (lingo commands)
>     end

Figure 12.2 : A movie script.

The "startmovie" handler runs immediately when the movie begins to play. Conversely, "stopmovie" runs when the movie ends. If the movie loops continually and never ends, the "stopmovie" handler never executes.

The third type is a custom handler that you create yourself. We'll talk more about these later. By putting them in the movie script, they are available anytime you call the handler from another script.

### Scripts Attached to Cast Members

In the cast member window, you have the option of adding a Lingo script to any cast member that can be placed on the stage (figure 12.3). This could be buttons, bit-map images, text fields, vector graphics, and so on. Whenever the cast member is clicked, the script executes.

Figure 12.3 : A cast member script.

Two types of handlers can be used in cast member scripts:

>     on mousedown
>        (lingo commands)
>     end

>     on mouseup
>        (lingo commands)
>     end

When the mouse is over the top of the cast member on the stage and the mouse button is pressed, the "mousedown" handler executes; when the button is released, the "mouseup" handler executes. Usually, people press andrelease the mouse button immediately, so either handler can be used for a standard mouse click. You might want to use "mouseup" to control movie actions unless you have specific events that should occur while the button is held down.

Note
Two other types of handlers are available for editable text fields, but have no effect on other cast member types. "on keydown" and "on keyup" will respond when the user presses or releases a key. You can then check what key was pressed and have Lingo statements respond accordingly.

### Sprite Scripts

In certain instances, you will want a script to execute when a sprite is clicked, but you won't want to attach a script to the cast member. Using a sprite script, you can attach a script that only executes in the frames that contain it (figure 12.4). The same cast member could have one sprite script attached in one frame, and a different sprite script attached in a different frame. This is useful for using the same button cast member to perform different actions when clicked in different frames of the movie.

Figure 12.4 : A sprite script.

To use a sprite script, select the sprite (or range of sprites) in the score and
select "new" from the pull-down script menu in the score window (or click the script viewing bar at the top of the window). By selecting only certain frames that contain the sprite, you can attach the script only for specific positions in the score.

Sprite scripts operate in the same way that cast member scripts do, and require a mouse or keyboard input to execute. Note that sprite scripts will override any cast member scripts that are attached to the same item.

## Variables

If you are familiar with any type of computer programming, you probably know what a variable is. It's an object in the computer's memory that is a substitute for a value that can change or vary. Variables are powerful because they allow your movie to perform differently in different circumstances, depending on the value of the variables.

Director uses two types of variables: global and local.

### Global Variables

Global variables stay in the computer's memory for as long as the movie runs (or until you tell it to clear any global variables). They are used for information that must be available in different situations. For example, you may want to store information that the user enters and display it again later in the movie.

Any time you use a global variable, you need to first use the statement:

>     global variablename

For example, to create a global variable called "gpoints" to track points in a game, you could use the following Lingo:

>     global gpoints
>     set gpoints=0

The first statement shows that this is a global variable you're dealing with. The second statement sets your variable equal to zero. Later, if you want to change your global variable, you could use this handler:

>     on mousedown
>        global gpoints
>        set gpoints=gpoints + 5
>     end

Whenever this handler runs, it takes your gpoints variable and adds five to it.

Note
Many Lingo programmers put a "g" in front of the variable name they create to help them remember that it is a global variable. This is only optional. Your variable can be any word that is not already used by Lingo to mean something else.

### Local Variables

Local variables are used within a handler and then are gone. Any variable used without the "global" term is created as a local variable. If you don't need the variable's information later in the movie, local variables are ideal.

Here's an example: There is an editable text field on the stage called "textfile." The user types the location and name of a text file into the field and the Shockwave movie loads the text using the `getnettext` command. The Lingo could look like this:

>     on exitframe
>        set whattext=field "textfile"
>        getnettext whattext
>     end

The `getnettext` command only needs the information once to perform its action, so we used a local variable called "whattext." When the handler finishes, "whattext" is no longer in memory.

## Writing Your Own Handlers

You have seen various handlers that can be used: "on exitframe," "on mouseup," "on startmovie," and so on. But the real organizing power of handlers is in creating your own. By putting your own handlers in a movie script, you allow a common function to be called from anywhere else in the movie.

### Plain Vanilla Handlers

When I say "plain vanilla handlers," I am referring to handlers that are called from another place in the movie and don't pass or return values. These are the most simple, but not at all less useful than handlers that pass values.

Here's a game example (stop taking your job so seriously and have some fun!). Every time the user clicks a space alien, you want to increase the score and put some text on the screen. You can make your own handler called "scorepoint" and put it in a movie script so it's always available.

>     on scorepoint
>        global gpoints
>        set gpoints=gpoints + 1
>        put "Good Shot!" into field "response"
>     end

Now, in the sprite script of the space alien, you can call the handler:

>     on mousedown
>        scorepoint
>     end

This example just shows the basics. All you're doing here is dividing the Lingo into two places. Instead of placing the statements in the scorepoint handler, you could place them in the sprite script and it would work the same way. But you might have many different situations where you want to score a point and put "Good shot!" on the stage. Instead of writing the whole segment over and over in different places, you can just call the scorepoint handler.

### Passing and Returning Values in Handlers

Try to think of the various Lingo terms as parts of speech. The preceding handler is like a verb. The handler is even named to sound like a verb: "scorepoint." When you issue the command, you're telling Lingo to "score a point." Passing values can be done two ways: one is like a verb and one is like a noun.

#### Passing Values

Passing values to a handler is a verb. It's basically like the plain vanilla handler but with a few additional elements, called arguments. By specifying one or more values after the name of the handler, you can send information to the handler when you call it.

Going back to the space alien game, there might be several different types of aliens. One scores five points, one scores 10 points, and one scores 50 points. Instead of making three different handlers to add the points, you can pass a value to the same one.

>     on scorepoint howmuch
>        global gpoints
>        set gpoints=gpoints + howmuch
>        put "You got "&howmuch&" points!" into field "response"
>     end

Then, when you call the handler, you add a parameter that passes the number of points to the handler.

>     on mousedown
>        scorepoint 5
>     end

In another script on a different sprite, you might use "scorepoint 10" to add ten points. You can pass more than one parameter by separating them by commas.

#### Returning Values from Handlers

Using a handler to return a value makes it operate more like a noun instead of a verb. Instead of standing alone as a call to a handler, it is used as a part of another Lingo statement. With the `return` command, a value can be sent back to the script that called the handler.

For example, this handler (called "returnscore") adds the new points to the players current score and returns the total value. It looks like this:

>     on returnscore oldpoints, newpoints
>        set newscore=oldpoints + newpoints
>        return newscore
>     end

The script that calls the handler is:

>     on mousedown
>        global gpoints
>        put returnscore(gpoints,10) into field "points"
>     end

This script passes two values to the handler: the current score (gpoints) and the new points to add to it (10). The handler adds the two and returns the total score, which is put into a field called "points."

If a handler returns a value, the call to the handler must have parentheses-even if no values are passed to the handler. You can have a call to a handler that looks like this:

>     put returnscore() into field "points"

If the point value for the aliens were always the same, the handler could be:

>     on returnscore
>        global gpoints
>        set newpoints=gpoints + 10
>        return newpoints
>     end

It's up to you to decide where to use handlers that return values, and where to use handlers that work on their own. It's just a matter of whether or not you want to continue working with that value in the script that calls the handler.

## Simple Lingo Structures

You could learn specific words of Spanish using a dictionary, but you would still need to know how to phrase the words together in a sentence. This section shows just a few basic structures that are common to Lingo programming. They are fairly straightforward and logical.

### Setting Values

A common command you will perform is setting one value equal to another value. Of course, this doesn't refer to constants; you can't set 8 equal to 14, but you will have variables that can be set and changed.

There are several ways of phrasing a Lingo statement to set a value.

>     set variable=new value

>     set variable to new value

>     put new value into variable

So the following Lingo statements would all set a variable called "gnumber" to 8:

>     set gnumber=8

>     set gnumber to 8

>     put 8 into gnumber

The phrasing is up to you. Sometimes one way sounds more natural than another, depending on your preference.

### Testing Using If…Then…Else Structures

Often you will want to test for a certain condition, then respond depending on the outcome of the test. The "if…then…else" structure is very common and works like its name suggests.

>     If true condition then perform action

The "else" is optional; if you have one action for the "true" condition and one for the "false" condition, you can use this structure:

>     if true condition then perform action
>     else perform a different action

You also may have multiple lines of code for each of the parts of the structure. If you do have multiple lines, you need to end the test structure with an `end if` statement.

>     if true condition then
>        perform action one
>        perform action two
>        perform action three
>     else
>        perform other action one
>        perform other action two
>     end if

Let's say you want to test for a rollover in sprite channel one; if it's true that there is a rollover, the cast number will be changed to eight. If there is not a rollover, the number will be set to five. The handler can look like the following. Note that in Director 5, the term "member" can replace the "castnum" Lingo from Director 4.

>     if rollover(1) then
>        set the member of sprite 1 to 8
>        updatestage
>     else
>        set the member of sprite 1 to 5
>        updatestage
>     end if

### Repeat Loops

In many cases you will want to repeat the same Lingo statements over and over. You may have a certain number of loops, or you may loop continuously until a condition changes. Here are a few basic repeat structures you can use.

#### Repeat While…

"Repeat while…" continues the loop until a condition is false. If the condition is already false when the test is started, the Lingo within the repeat structure never occurs. If the condition is true and never becomes false, the loop will go on endlessly.

>     Repeat while true condition
>        lingo statement
>        lingo statement
>        lingo statement
>     end repeat

For example, you want a sprite to be visible while the mouse button is held down and to turn invisible when it's released. Your script looks like this:

>     repeat while the mousedown=true
>        set the visible of sprite 4 to true
>        updatestage
>     end repeat
>     set the visible of sprite 4 to false
>     updatestage

The loop continues to repeat until the mouse button is not down, then the Lingo will progress outside the repeat loop.

#### Repeat With…

Here is a simple loop that repeats a specific number of times. It uses a variable that counts from one number to another number. These loops are particularly useful if you want to test a range of sprites for a condition.

>     Repeat with variable=firstnumber to secondnumber
>        lingo statements
>        lingo statements
>     end repeat

The above syntax is used if "firstnumber" is less than "secondnumber." If the reverse is true, the loop counts down by using the statement "repeat with firstnumber down to secondnumber."

For example, I want to check sprites four through nine for a rollover, and then go to a new frame if any one of them is true.

>     Repeat with n=4 to 9
>        if rollover(n) then go "rollframe"
>     end repeat

The above example will progress through the loop five times testing for a rollover using the variable "n", which will be equal to 4, 5, 6, 7, 8, and 9.

## From Here…

Of course, this chapter is only the tip of the iceberg when it comes to Lingo. It shows you some basic structures and scripts to get you started on understanding the language. The number of actual commands available through Lingo is enormous. To learn more, you will want to study the Director manuals or a third party Lingo book.

There are countless people who can use Director to make simple movies, but a good Lingo programmer is much less common. You can really set yourself apart if you learn to work with the programming aspect of Director.

- Chapter 13, "Internet Lingo for Shockwave": Begins with some Internet Lingo that is new for Shockwave. Functions are described to interact with the Web.
- Chapter 14, "Further Use of Internet Lingo": Carries the Internet Lingo a step further with some more advanced functions and applications.
- Chapter 15, "Putting It All Together: A Shocked Site": Puts much of your Shockwave knowledge together in a complete Shockwave Web site.