By Bruce A. Epstein
Price: $24.95 USD
£17.50 GBP

Cover | Table of Contents | Colophon

Table of Contents

Chapter 1: How Lingo Thinks

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Do you really have time to read a book on Lingo when you're facing a deadline? The answer depends on how much time you waste struggling with Lingo and how often you've compromised your Director projects for lack of Lingo skills. If you make the investment now, this book will pay marvelous dividends. It may save you weeks otherwise spent flailing over relatively trivial Lingo problems, and it can help you to add snazzy new features and a professional polish to your Director projects.

If you don't have a project to work on, pick one now. You will learn much more if you have a concrete goal and concrete problems to solve. You have been warned.

Learning to program is a process, not an event. Although this book is not a substitute for an introductory programming class, it covers basic, intermediate, and advanced topics. The material is very condensed, but the book also lavishes attention on topics that are omitted entirely from other Lingo books. Before proceeding, you should understand Director's Cast, Score, and media editing windows, as covered in Macromedia's Using Director manual. You might also want to skim Macromedia's Learning Lingo manual for a broad overview of Lingo.

Most books provide simple examples that leave you stranded when you try to accomplish your specific goals. This book teaches you how to do anything you want with Lingo, not just create simple clickable buttons. It provides a solid foundation instead of a house of cards, and it is for people who want to know more, not less. As such, this book explores many abstract concepts that may not be relevant to your immediate needs. You must exercise reasonable discretion by ignoring topics that don't interest you or are beyond your current level.

This chapter lays the groundwork for your Lingo-laden future, but the details of using Lingo to add interactivity are in later chapters (starting with , Events, Messages, and Scripts). You should first focus on understanding how Lingo itself "thinks." Lingo is a marathon, not a sprint, and the extra training will pay off in the long run. More practical examples are given in , Mouse Events, and , Keyboard Events. Refer to the companion book,

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

So You're Too Busy to Learn Lingo

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Do you really have time to read a book on Lingo when you're facing a deadline? The answer depends on how much time you waste struggling with Lingo and how often you've compromised your Director projects for lack of Lingo skills. If you make the investment now, this book will pay marvelous dividends. It may save you weeks otherwise spent flailing over relatively trivial Lingo problems, and it can help you to add snazzy new features and a professional polish to your Director projects.

If you don't have a project to work on, pick one now. You will learn much more if you have a concrete goal and concrete problems to solve. You have been warned.

Learning to program is a process, not an event. Although this book is not a substitute for an introductory programming class, it covers basic, intermediate, and advanced topics. The material is very condensed, but the book also lavishes attention on topics that are omitted entirely from other Lingo books. Before proceeding, you should understand Director's Cast, Score, and media editing windows, as covered in Macromedia's Using Director manual. You might also want to skim Macromedia's Learning Lingo manual for a broad overview of Lingo.

Most books provide simple examples that leave you stranded when you try to accomplish your specific goals. This book teaches you how to do anything you want with Lingo, not just create simple clickable buttons. It provides a solid foundation instead of a house of cards, and it is for people who want to know more, not less. As such, this book explores many abstract concepts that may not be relevant to your immediate needs. You must exercise reasonable discretion by ignoring topics that don't interest you or are beyond your current level.

This chapter lays the groundwork for your Lingo-laden future, but the details of using Lingo to add interactivity are in later chapters (starting with , Events, Messages, and Scripts). You should first focus on understanding how Lingo itself "thinks." Lingo is a marathon, not a sprint, and the extra training will pay off in the long run. More practical examples are given in , Mouse Events, and , Keyboard Events. Refer to the companion book,

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Lingo Scripting Basics

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Computer languages tend to be simpler and more rigid than human languages, but like any other language Lingo has a set of rules that control the structure (syntax) of your Lingo program. Just as languages have grammar, Lingo's syntactical rules restrict the spelling, vocabulary, and punctuation so that Director can understand your instructions.

A syntax error or script error usually indicates a typographical error or the incorrect use of a Lingo statement.

Lingo's built-in keywords (or reserved words) make up Lingo's vocabulary and are the building blocks of any Lingo program. We'll see later how these keywords form the skeleton of your Director program, just as any language's words are the basis for sentences and paragraphs. It is crucial that you recognize which items in a Lingo script are built-in keywords versus those that are specified arbitrarily by the programmer. Refer to , Lingo Keyword and Command Summary, for a complete list of all Lingo keywords. The PrettyScript Xtra (http://rampages.onramp.net/~joker/tools/) is a $20 U.S. shareware tool that colorizes some items in your Lingo scripts to make them easier to recognize. The ScriptOMatic Lite Xtra, is available under XtrasScriptOMatic➤Lite, colorizes a broader range of items, but it is crippled almost to the point of being useless. The full version is promised imminently from g/matter (http://www.gmatter.com/products/scriptomatic/) at press time.

A handler is a series of Lingo statements that tell Director to perform some useful function. Handlers are typed into script cast members in the Script window. ("Script" is also used loosely to refer to a handler within a script. "Code" is used both as a noun to indicate your Lingo scripts and as a verb, meaning "to program" or "to write Lingo scripts.")

The scripts in a Director movie control the action, just as real-life actors follow a script. There are several types of scripts (castmember scripts, movie scripts, sprite scripts, parent scripts, and Behaviors), which are covered in detail in the "

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Variables and Properties

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You'll often read Lingo properties to obtain information about the user or the run-time environment and set properties to affect the run-time environment. You'll use variables as containers to store and manipulate any type of data, including Lingo properties. Later we'll see how you can define your own properties using so-called property variables, which are a particular type of variable but are unrelated to Director's built-in properties.

Lingo defines dozens of properties (not to be confused with programmer-defined property variables, discussed later), which are always preceded by the keyword the.

If you omit the word the, Lingo thinks you are referring to a programmer-defined variable, not a Lingo property.

A property may pertain to the overall system, the current movie or MIAW, a cast member, or a sprite. Lingo properties are universally accessible (they can be used from any script at any time), and they may be static (fixed) or may change over time or based on user actions. For example, the platform property doesn't change unless you switch computers, but the mouseH and the mouseV properties change whenever the cursor moves.

The general format for setting a Lingo property is:

set the property {of object} = value
or
put value into the property {of object}

where value is replaced with a meaningful value, property is a property name and object is usually a sprite, member, or window reference. The following examples set the locH of sprite sprite property, the regPoint of member member property, and the soundEnabled system property. Note that all three properties start with the, although no object is specified for the soundEnabled property because it is a system property, not a property of a sprite or a cast member.

set the locH of sprite 1 = 17
set the regPoint of member 1 = point(0,0)
set the soundEnabled = TRUE

The general format for reading a Lingo property is:

set variableName = the property {of object}

such as:

set 

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Lingo's Skeletal Structure

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This section covers the bones on which you'll hang the flesh of your Lingo program. A handful of Lingo commands and functions control program structure and execution. Each line of Lingo is executed in order, unless the Lingo itself changes the flow. Lingo detours to execute any handler names it encounters, as shown in detail under "Nested Handlers" in the earlier section, "." A detour taken to execute another handler is known as a subroutine call in most languages. Refer to , How Director Works in Director in a Nutshell regarding the difference between Lingo's program flow and the movement of the Score's playback head.

Although Lingo tells Director what to do, the Lingo code is ultimately written and maintained by humans (or programmers, anyway). Lines starting with two hyphens (--) are comments that Director ignores; they do not increase the execution time. Adding comments to someone else's code is a great way to make sure you understand what it does.

I place comments before the code they describe, although some people place them afterward, which seems patently absurd to me. Comments should give a preview, not a postmortem.

Always describe the big picture:

Include comments at the top of your handler to describe its purpose. Describe what the handler does and why. Describe the data stored in major variables, such as lists, and which global variables the code uses.

Use comments liberally, even when you are the only programmer:

Your own comments will help you immensely if you have to fix a bug six months later, or they'll help the next poor slob who has to maintain your code when you take a better job.

Write comments that complement, not simply reiterate, the programming code:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Conditional Execution

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You can have Director execute different Lingo code in response to various conditions. Any non-zero expression (including negative numbers) is considered TRUE, and only an expression that evaluates to zero is considered FALSE. Refer to for details on evaluating comparisons, including compound expressions. (These example multi-line code fragments must be placed in a handler for testing.)

The if statement will execute different Lingo code based on the value of the specified expression. This allows you to, say, use a single Director movie on both Macintosh and Windows but branch to different code depending on the playback platform, as determined by the platform property, such as:

if (the platform starts "Windows") then
  -- Do Windows-specific stuff here
else
  -- Do Macintosh-specific stuff here
end if

The if statement has many possible forms, but I recommend only these. Items shown in curly braces are optional. Note the correct indentation:

Single-Clause If...Then...End If

if expression then
  statement1
  statement2
end if

Multiple-Clause If...Then...Else If...Else...End If

The else if and else clauses are optional:

if expression then
   statement1
{else if expression then
   statement2}
{else
   defaultAction}
end if

For example:

if x = 1 then
  go frame "Slide1"
else if x = 2 then
  go frame "Slide2"
else if x = 3 then
  go frame "Slide3"
else
  go frame "End"
end if

One-Line and Two-Line If Statements

The following forms are theoretically valid, but they often misbehave in Projectors and within nested if statements, so I don't recommend them:

if expression then statement1

or

if expression then statement1
else statement2

The Classic Three-Line If Statement

The one-line and two-line forms of the if statement make it hard to tell if the indenting is correct even after Director auto-formats your Lingo.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Parameters and Arguments

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Imagine you own a calculator with buttons that each perform a single complete operation—one button adds 5 plus 7, and another button adds 5 plus 8, and so on. It might be convenient for those limited operations, but the calculator could rapidly become unwieldy. (Similarly, Chinese pictographs are inconvenient for computer usage compared to an alphabet from which you can construct any word.) In reality, each button on a calculator actually represents either an operand, such as the number 5, or an operation, such as addition, allowing for many possible combinations with relatively few keys.

At the beginning of this chapter we used the alert command to display the string "Hello World" in a dialog box. The alert command accepts any text string as an argument. An argument is analogous to the operands used in the example of a calculator above, and the alert command is analogous to the addition button that performs some operation using the argument(s). The words parameters and arguments are often used interchangeably to indicate inputs that are passed to a function on which it can operate. Strictly speaking, an argument is the item specified as part of the function call, and a parameter is the same item once it is received inside the function.

Just as the alert command can accept any string for display, we should strive to make our custom handlers flexible by using variables to represent values that can change. In contrast, using a fixed number, such as 5, or a fixed string, such as "Bruce," in your program is called hardcoding a value.

Instead of hardcoding specific values into a handler, generalize the function so that it can operate on whatever arguments are passed into it.

For example, a handler that finds a file should be flexible enough to find any file we ask it to find, rather than always looking for a particular hardcoded filename. Beginning programmers often create two or more copies of the same handler with only minor variations to accomplish nearly identical tasks. Instead, you should create a

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 2: Events, Messages, and Scripts

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter covers the foundation on which every Director project is built—interactivity. How does Director respond to user events? How can you control the flow of both Lingo and the Score? How does Director know which Lingo to execute? If you are new to Lingo, I explain everything in great detail below.

Users familiar with D5 should note these important changes in D6:

• Score scripts are now instantiated and "know" who they are (they receive the me parameter indicating their script instance and, indirectly, their sprite number).
• Sprites can have multiple scripts (Behaviors) attached, all of which can receive the same events. A sprite might have multiple mouseUp and mouseDown handlers in different attached Behaviors.
• Behaviors are instantiated scripts that can have custom properties applied each time they are used in the Score. Multiple Behaviors can be "piled on" a sprite, allowing you to modularize your Behaviors. (One Behavior might have just a mouseUp handler, and one might have just a mouseDown handler). These factors can dramatically reduce the total number of scripts required.
• A single frame script can span multiple frames in the script channel, just as sprites now span multiple frames.
• Many new events are broadcast in parallel to multiple sprites and the frame script (including beginSprite, endSprite and prepareFrame).
• The new mouseWithin, mouseEnter, and mouseLeave events make it much easier to handler rollovers on a per-sprite basis, rather than checking for rollovers in a frame script. The traditional mouse event hierarchy remains in place.
• The new beginSprite and endSprite events make it easy to create self-reliant sprite scripts and frame scripts that initialize and clean up after themselves.
• The new prepareMovie and prepareFrame events allow you to perform initialization

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Events and Messages

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter covers the foundation on which every Director project is built—interactivity. How does Director respond to user events? How can you control the flow of both Lingo and the Score? How does Director know which Lingo to execute? If you are new to Lingo, I explain everything in great detail below.

Users familiar with D5 should note these important changes in D6:

• Score scripts are now instantiated and "know" who they are (they receive the me parameter indicating their script instance and, indirectly, their sprite number).
• Sprites can have multiple scripts (Behaviors) attached, all of which can receive the same events. A sprite might have multiple mouseUp and mouseDown handlers in different attached Behaviors.
• Behaviors are instantiated scripts that can have custom properties applied each time they are used in the Score. Multiple Behaviors can be "piled on" a sprite, allowing you to modularize your Behaviors. (One Behavior might have just a mouseUp handler, and one might have just a mouseDown handler). These factors can dramatically reduce the total number of scripts required.
• A single frame script can span multiple frames in the script channel, just as sprites now span multiple frames.
• Many new events are broadcast in parallel to multiple sprites and the frame script (including beginSprite, endSprite and prepareFrame).
• The new mouseWithin, mouseEnter, and mouseLeave events make it much easier to handler rollovers on a per-sprite basis, rather than checking for rollovers in a frame script. The traditional mouse event hierarchy remains in place.
• The new beginSprite and endSprite events make it easy to create self-reliant sprite scripts and frame scripts that initialize and clean up after themselves.
• The new prepareMovie and prepareFrame events allow you to perform initialization

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Lingo Script Types

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Where should Lingo scripts be placed? The answer depends on the event you wish to trap (respond to) and when you want to trap it.

Macromedia advertises Director 6's Behaviors as "scriptless authoring." You can use Behaviors without understanding the specifics of what they do, but they are still scripts, even if someone else wrote them. At a minimum, you must understand how to attach scripts in the Score and how Director processes events. Behaviors are score scripts, but configurable Behaviors are very different from the simple score scripts you may have used in Director 5. Refer to .

In some cases, Director handles the desired task without scripting. The Tempo channel can be used to wait a specific length of time, to wait for a mouse click or key press, or to wait for a sound or video to play. Editable text fields handle keyboard input automatically when the editable of member or editable of sprite property is set. Refer to in this book and , Text and Fields, in Director in a Nutshell for details.

Director's terminology is very confusing regarding the various types of scripts. Although the scriptType of member property returns only three different values (#movie, #score, and #parent) there are actually six types of scripts. (Movie scripts, parent scripts, three subspecies of score scripts (frame scripts, score scripts, and Behaviors), plus cast scripts, which don't have their own scriptType).

There can be a virtually unlimited number of scripts of each type in a Director movie. Each script can contain one or more handlers, but the total length of a single script cannot exceed 32,000 characters. Create libraries of scripts in external castLibs that can be shared among multiple movies.

A cast member script (or simply cast script) is one way to make a bitmap sprite clickable. It is associated with a cast member in the Cast window but takes effect automatically for any sprite created from that cast member. (Recall that a sprite is an instance of a cast member that has been placed in the Score or on the Stage. Refer to ,

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Trapping Events with Scripts

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Each Director event is usually sent to the scripts in the following order, but there are a lot of exceptions, as noted below:

1. Primary event handler(s)
2. Sprite Behavior(s) and cast script(s)
3. Frame script of current frame
4. Movie scripts

Director 6 added many new events that are broadcast to both sprite scripts and the frame script in the current frame. Sprite scripts can prevent events from reaching cast scripts, and frame scripts can prevent events from reaching movie scripts.

Score events (such as exitFrame) are broadcast to all sprites and the frame script. Sprite events (such a beginSprite) are sent to whatever sprite span(s) or frame script span begins or ends in a frame. Mouse events (such as mouseUp) are generally sent to only one sprite at a time and only passed the frame scripts if not trapped by a sprite.

Let's examine what happens in detail at each of these levels:

Primary Event Handler

If a primary event handler is defined, it receives the event first. By default, it passes the message onto other scripts rather than consuming it.

Sprite Behaviors (Sprite Scripts) and Cast Scripts

Many sprites have no scripts attached, and some have multiple scripts attached. Even sprites with scripts may ignore most events, trapping only those of interest. Refer to for many more details on how sprites trap mouse events. For this discussion, you need only understand that mouse events are sent only to the first sprite that traps them.

If the member of sprite property is changed, the cast script (if any) changes along with it. Sprite scripts are unaffected by changing the member of sprite property, which is why I prefer them over cast scripts.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Message Processing Order

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Director generates many events continually. (This is one reason it is hard to follow the output of the trace command in the Message window—there's too much of it.) Some events are sent every frame, whereas others are sent only at startup or when encountering a new sprite in the Score.

shows the Score for my Event Test movie that is used in . (This movie is available from the download site cited in the .)

Figure : Event Test Movie

In , note the frames in which each sprite begins or end. The frame script and the sprite in channel 5 both span all three frames of the Score (and sprite 5 has two Behaviors attached). The sprite in channel 6 begins in frame 1, ends in frame 2, and has one Behavior attached. The sprite in channel 7 begins and ends in frame 2 and also has one Behavior attached. All sprites also have cast scripts attached to their cast members.

shows the event sequence generated by the three-frame movie shown in . You will often ignore the majority of events, but Director sends events in a non-intuitive order that you should understand. Remember that the Stage is drawn between the prepareFrame and enterFrame events, as indicated in .

The number and order of idle events depend on the frameTempo (set to 30 fps in this example) and the idleHandlerPeriod (defaults to 0). In the example there is only one idle event per frame. (That is 30 idles per second, so keep your idle handlers slim!) If the frameTempo is set to 1 fps and the idleHandlerPeriod is set to 20 ticks (one-third of a second), there would be three idle events per frame (that is, three idles per second). In that case, the idle events would occur before the exitFrame events, rather than after them.

In all events have been manually pass'ed so that they are received by all entities that can trap them. All items of interest have been added to the actorList so that they receive stepFrame messages. The current frame number (the frame) is shown in parentheses at the end of each line.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 3: Lingo Coding and Debugging Tips

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Programming is often an iterative process. You need not write perfect code that does everything the first time you run it. Start simple, and test each step along the way. Before you know it, you will be building real Lingo programs.

Many of the tips and techniques discussed throughout this book won't mean anything to you until you've programmed for a while. (Refer to """ in , How Lingo Thinks). Revisit the earlier chapters after completing a project. What would you do differently the next time? Try to practice the following Lingo techniques:

Plan Ahead

Plan your design and layout of the presentation and the Lingo you'll need. A formal design helps both beginners and experienced Linguists spot problems and opportunities.

Be organized. If your Lingo code starts messy and scattered, it will only get worse. Well-structured code gets easier, not harder, to debug toward the end of a project.

Develop and maintain a library of utility Lingo routines (this book is a good start). Store them in externally linked casts for easy inclusion in other projects.

Don't confuse analysis with implementation. The mechanics of Lingo are sometimes easier than figuring out what Lingo you need to write. See "" later in this chapter.

Structure your Score and Cast so that it makes your Lingo easier to write as described in , How Director Works, in Director in a Nutshell.

Use comments effectively as described in the "" section of .

Develop a programming style, and use it consistently. For example, I always use sprite scripts and never use cost scripts.

Avoid the errors cited in the "," "," "," and "Common Errors When Using If Statements" sections in .

Use Scripts and Handlers Effectively

Use the correct type of script for your handlers, as described in , Events, Messages, and Scripts

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Lingo Coding Tips

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Programming is often an iterative process. You need not write perfect code that does everything the first time you run it. Start simple, and test each step along the way. Before you know it, you will be building real Lingo programs.

Many of the tips and techniques discussed throughout this book won't mean anything to you until you've programmed for a while. (Refer to """ in , How Lingo Thinks). Revisit the earlier chapters after completing a project. What would you do differently the next time? Try to practice the following Lingo techniques:

Plan Ahead

Plan your design and layout of the presentation and the Lingo you'll need. A formal design helps both beginners and experienced Linguists spot problems and opportunities.

Be organized. If your Lingo code starts messy and scattered, it will only get worse. Well-structured code gets easier, not harder, to debug toward the end of a project.

Develop and maintain a library of utility Lingo routines (this book is a good start). Store them in externally linked casts for easy inclusion in other projects.

Don't confuse analysis with implementation. The mechanics of Lingo are sometimes easier than figuring out what Lingo you need to write. See "" later in this chapter.

Structure your Score and Cast so that it makes your Lingo easier to write as described in , How Director Works, in Director in a Nutshell.

Use comments effectively as described in the "" section of .

Develop a programming style, and use it consistently. For example, I always use sprite scripts and never use cost scripts.

Avoid the errors cited in the "," "," "," and "Common Errors When Using If Statements" sections in .

Use Scripts and Handlers Effectively

Use the correct type of script for your handlers, as described in , Events, Messages, and Scripts

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Zen and the Art of Debugging

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Debugging is the single most important skill in programming, if not in life. Debugging, like most worthwhile pursuits, is a learned art, but I've rarely seen it taught. This section is aimed at those who have never debugged, at least not successfully, and probably don't know how to use the Lingo Debugger.

The title of the well-known book, Zen and the Art of Motorcycle Maintenance, was taken from a book on Zen archery. A Zen archer holds his bow awkwardly over his head so that it is clearly impossible to "sight" the target. Instead, he attempts to "become one" with the target; he seeks not to act, but only to confirm what already is. He does not aim and shoot, but rather recognizes that the arrow has already been released, has already flown toward its target, and has already made a bull's-eye. If you watched the 1998 Winter Olympics from Nagano you could pick out the athletes that knew they would win before the competition began. Almost invariably they were right. The competition itself was merely a confirmation of that which they had already envisioned from an early age. And so it is with programming and debugging.

To debug is to recognize that the problem has already been solved; you simply unearth the solution as one would unearth a diamond. Before it is possible to debug a problem, you must convince yourself that it is possible to debug the problem.

There are many paradoxes in programming and debugging. You must be confident that you can solve a problem yet admit that you probably made a mistake somewhere. You must fight the urge to lay blame on yourself or on Director, but at the same time be unbiased in assessing who or what is the culprit. Debugging is at the very core of what it means to be conscious: to have control over one's present and future, and to recognize that you had control over your past whether you exercised it or not.

To debug is to follow whatever path wherever it may lead and yet to control the ultimate destination. Don't confuse bugs with debugging. Bugs suck. Debugging is fun.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

The Lingo Debugger

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

A good programmer can often correct simple errors by simply inspecting the code, just as a good speller doesn't need a dictionary or a spellchecker. But experienced programmers constantly use the Lingo Debugger whereas beginners don't even seem to know it exists. Refer to , Troubleshooting, in Macromedia's Learning Lingo manual for a brief overview.

The Debugger is a diagnostic tool. It does not debug your program for you any more than an X-ray cures disease. The Debugger can show you what Lingo commands are being executed and the values held in various variables. See also the Watcher window in .

Figure : The Debugger Window

When Director compiles a script—see """ in and "" —it checks that your Lingo code has a recognizable structure and acceptable keywords. It does not attempt to actually run your Lingo code. Recompile to help find typographical errors.

A so-called compile-time or syntax error causes a dialog box to appear, indicating what Director suspects is wrong.

Figure : A Script Error Dialog

Script errors are your friends. Read the error message carefully; Director will tell you which line confused it.

Unfortunately, when you close the Script window (which recompiles the script) and the script error dialog appears (see ), the Script button will not always take you to the exact line causing the problem. Usually you can guess which line was the problem, unless you have an extremely long script or a long line of Lingo code (such as a big list or quoted string).

If you are unsure which line in the script is the problem, choose the Cancel button, then run the movie using the Enter key on the numeric keypad. Director will recompile the script and post the error dialog a second time. This time, choosing the Script

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

A Simple Sample Debugging Session

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You should become adept at using the Debugger, and there is no substitute for practice. Start with a fresh Director movie that doesn't have any scripts. Use:

          set the alertHook = 0
        

to cancel any alertHook in effect to make sure that error dialogs are displayed.

Suppose we want to create a handler that returns a list of numbers from 1 to 10.

Type the following into a movie script cast member exactly as shown. (There are supposed to be errors; this is a debugging example.)

Example . A Simple Sample Debugging Session: Initial attempt to create handler

on createList
  repeat x = 1 to 10
    add myList, x
end

Before closing the script window type createList in the Message window and press Return. You should get a "Handler not defined: createList" error. Why? Because we haven't compiled the script, so Director doesn't know about our new handler yet.

Close the Script window to compile the script. Oops, we get an "Expected WHILE or WITH" error. What is wrong? Click the Script button in the error dialog to reedit the script. We've mistyped the repeat command and need to add the word with. Correct it as follows.

Example . Improved repeat loop including "with"

on createList
  repeat with x = 1 to 10 -- Correct this line
    add myList, x
end

Close the script again; this time we get an "Expected END REPEAT" error. We forgot the end repeat for our repeat loop.

Example . Improved repeat loop including "end repeat"

on createList
  repeat with x = 1 to 10
    add myList, x
  end repeat -- Add this line
end

Press the Tab key to reformat the script. Close the script one more time. Ah ha, success! The Script window closes without incident, and we assume that all is well. Finally we can test it from the Message window:

createList

What? We get another "Handler not defined:add myList,x " error! I thought we just compiled the script and Director should now be able to find our

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Lingo Debugging Commands

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

shows Lingo commands convenient for debugging.

Table : Debugging-related Lingo Commands

Command	Usage
alert	Display a message or variable's value in a dialog. See .
Alert(MUI)	Display a message or variable value in a multi-button dialog. See .
the alertHook	Intercept alert and error messages before they cause a dialog to appear. See on alertHook.
error (FileIO)	Interpret an error code returned by the FileIO Xtra. (The FileIO XObject used the mError method instead). See and .
externalEvent	Strings sent to the Browser using externalEvent from within Shockwave are displayed in the Message window during authoring.
getError()	Return an error code related to an SWA cast member. Requires SWA Streaming Xtra. See .
getErrorString()	Return an error string related to an SWA cast member. Requires SWA Streaming Xtra. See .
ilk()	Check a variable's type. See .
listP()	Check if a variable is a list. See .
MoaErrorToString (MUI Xtra)	MoaErrorToString() interprets MOA error codes returned by some Lingo commands. See .
netError()	Check the result of a network operation. See .
netStatus()

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 4: Lingo Internals

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter covers Lingo's internal operation, with an emphasis on comparing it to C and C++. You should be familiar with , before proceeding. You should also understand Director's paradigm as explained in , How Director Thinks, in Director in a Nutshell. Refer to , Using Xtras, in Director in a Nutshell and , in this book for details on extending Director (especially if you are a skilled C programmer). If you are unfamiliar with C, portions of this chapter will make no sense to you. Either ignore it, or read the books on C cited at the end of .

There wasn't room in this book for a full comparison of Lingo and C. Luckily, an extensive comparison can be found in the downloadable Chapter 20, Lingo for C Programmers, at http://www.zeusprod.com/nutshell/chapters/lingovsc.html. Even if you are not a C programmer, comparing Lingo to another language illuminates numerous issues, and it is highly recommended reading.

Director's memory usage is dominated by multimedia content, primarily graphics, rich text, and nonstreaming audio. In Lingo, you don't explicitly allocate RAM, as with malloc or alloc in C. There is no low-level access to RAM or to Director's off-screen buffer, except via Xtras. Nor are there address or indirection operators, as in C, that would give access to a variable's memory space. In Lingo, items are disposed of by setting them equal to 0, except for XObject instances, which are freed with mDispose. When an item in memory is no longer referenced by any variables, Director will deallocate and recapture the memory (using reference count-based garbage collection), but on an ambiguous schedule. (Refer to , Memory and Performance, in Director in a Nutshell for details on allocating and freeing memory, loading and unloading assets, and Director's memory requirements.)

Lingo is not compiled, but rather tokenized into byte-code. The byte-code is the same on both the Macintosh and Windows platforms, and it is translated at runtime by the Projector into machine-specific instructions. This is convenient for cross-platform development, but it does not offer the speed of assembler. Because Lingo is not compiled, there are no separate compiler or compiler directives.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Lingo Internals

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

There wasn't room in this book for a full comparison of Lingo and C. Luckily, an extensive comparison can be found in the downloadable Chapter 20, Lingo for C Programmers, at http://www.zeusprod.com/nutshell/chapters/lingovsc.html. Even if you are not a C programmer, comparing Lingo to another language illuminates numerous issues, and it is highly recommended reading.

Director's memory usage is dominated by multimedia content, primarily graphics, rich text, and nonstreaming audio. In Lingo, you don't explicitly allocate RAM, as with malloc or alloc in C. There is no low-level access to RAM or to Director's off-screen buffer, except via Xtras. Nor are there address or indirection operators, as in C, that would give access to a variable's memory space. In Lingo, items are disposed of by setting them equal to 0, except for XObject instances, which are freed with mDispose. When an item in memory is no longer referenced by any variables, Director will deallocate and recapture the memory (using reference count-based garbage collection), but on an ambiguous schedule. (Refer to , Memory and Performance, in Director in a Nutshell for details on allocating and freeing memory, loading and unloading assets, and Director's memory requirements.)

Lingo is not compiled, but rather tokenized into byte-code. The byte-code is the same on both the Macintosh and Windows platforms, and it is translated at runtime by the Projector into machine-specific instructions. This is convenient for cross-platform development, but it does not offer the speed of assembler. Because Lingo is not compiled, there are no separate compiler or compiler directives.

Director's Modify➤Movie ➤Properties➤Allow Outdated Lingo option controls how Director interprets the Lingo of movies created in previous versions of Director. It is available only when upgrading movies from prior versions. Your concern is not necessarily the new Lingo features, but rather the changes in the behavior of existing functions that might break legacy code. Such a change from version to version would be exceedingly rare in a language such as C, but it is common in Director. In Director 6, the major alteration from prior versions involves sprite message passing (see ,

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 5: Data Types and Expressions

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter covers data types, expression evaluation, and operators. Refer to , for a discussion of variables, and to , for details on numeric data types. Refer to , for details on string manipulation and to , for many details on lists. See also , for a detailed discussion of symbols.

In addition to Lingo keywords, Lingo uses constants, variables, symbols, and literals, which can contain various data types such as integers, floats, and strings.

Constants

Constants are common values, such as PI, FALSE, and TRUE, that are predefined in Lingo for convenience.

Literals

Literals are fixed values specified by the programmer, such as 6 (an integer literal), and "flubber" (a string literal).

Symbols

Symbols are a convenient way to represent strings or integers. Lingo includes some symbols, such as #digitalVideo, and the programmer can define others.

Variables

Variables contain data that can change. A variable, such as myHighScore, may equal 5 at one point but later be updated so that it equals 7.

Lingo data types, summarized in , include those common to most languages, as well as objects and other complex types that are unique to Lingo. Note that there is no double-precision float type or short integer type. Lists are roughly equivalent to arrays and structures. Refer to and for a discussion of variables and lists, and refer to , and the downloadable Chapter 20, Lingo for C Programmers, for a comparison of Lingo and C data types.

Table : Data Types

Data Type

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Data Types and Variable Types

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

In addition to Lingo keywords, Lingo uses constants, variables, symbols, and literals, which can contain various data types such as integers, floats, and strings.

Constants

Constants are common values, such as PI, FALSE, and TRUE, that are predefined in Lingo for convenience.

Literals

Literals are fixed values specified by the programmer, such as 6 (an integer literal), and "flubber" (a string literal).

Symbols

Symbols are a convenient way to represent strings or integers. Lingo includes some symbols, such as #digitalVideo, and the programmer can define others.

Variables

Variables contain data that can change. A variable, such as myHighScore, may equal 5 at one point but later be updated so that it equals 7.

Lingo data types, summarized in , include those common to most languages, as well as objects and other complex types that are unique to Lingo. Note that there is no double-precision float type or short integer type. Lists are roughly equivalent to arrays and structures. Refer to and for a discussion of variables and lists, and refer to , and the downloadable Chapter 20, Lingo for C Programmers, for a comparison of Lingo and C data types.

Table : Data Types

Data Type	Usage and Range
Boolean	A TRUE or FALSEvalue (equal to 1 or 0, respectively)
constant

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Operators

Content preview·Buy PDF of this chapter|