You are previewing Lingo in a Nutshell.
O'Reilly logo
Lingo in a Nutshell

Book Description

Macromedia Director 6 is the premiere authoring tool for delivering interactive content on both the Internet and the desktop. It is the dominant multimedia package for Windows 95/NT, Windows 3.1, and the Macintosh. A quarter million developers use Director(R) to incorporate animation and audio into dynamic Web pages, and to create engaging interactive corporate presentations, multimedia advertising, entertainment CD-ROMs, Enhanced music CDs, and even DVDs. Lingo is Director's powerful scripting language. This companion book to Director in a Nutshell is an essential tool for both new and experienced Lingo programmers seeking a deeper knowledge of the language. Bruce Epstein is the author of both these books and brings years of hands-on experience with Director and Lingo. The book includes numerous useful Lingo examples. Exhaustively tested, this book corrects many errors found in Macromedia's Lingo documentation and repeated verbatim in most third-party books. Extremely comprehensive, this book details dozens of misdocumented and undocumented Lingo keywords that are omitted from Macromedia's manuals and third-party books. Lingo in a Nutshell caters to the huge pool of Director users attempting to bridge the Lingo gap, yet provides the details for the experienced Linguist that are lacking in other Lingo books. In typical nutshell style (clear, concise, deep and narrow) this book explores the syntax, structure and commands of the Lingo language. The detailed chapters describe messages, events, scripts, handlers, variables, lists, file I/O, Behaviors, child objects, Xtras, and more. This book teaches you to troubleshoot and debug common Lingo errors. Lingo in a Nutshell is the book for which both Director users and power Lingo programmers have been yearning. The book extensively covers topics not found in other Lingo books:

  • Cross-platform Lingo differences

  • Lingo internals for experienced programmers

  • Events, messages, and scripts

  • Timers, tempos, cue points, and synchronization

  • Data types and expressions

  • Math, numerical expressions, geometry, and trigonometry

  • Coordinates, alignment, and registration point

Lingo in a Nutshell is the most concise and compete guide available. It is a high-end handbook at a low-end price. An essential desktop reference for every Director user.

Table of Contents

  1. Lingo in a Nutshell
    1. Preface
      1. About This Book
        1. What Are These Books and Who Are They for?
        2. What These Books Are Not
      2. Lingo in a Nutshell
      3. Conventions Used in This Book
        1. Typographical Conventions
        2. Grammatical and Stylistic Conventions
        3. Examples
      4. New Features in Director 6 and 6.5
      5. Director Resources
        1. Director in a Nutshell and Lingo in a Nutshell
        2. Macromedia
        3. Web Sites and Xtras
        4. Mailing Lists
      6. Dedication
      7. Acknowledgments
    2. I. Lingo Basics
      1. 1. How Lingo Thinks
        1. So You’re Too Busy to Learn Lingo
        2. Lingo Scripting Basics
          1. Handlers and Scripts
            1. Hello World
            2. Calling All Scripts
            3. Nested Handler Calls
            4. Recursion
          2. Entering and Compiling Scripts
            1. Where Commands Go
          3. Handler Scope
          4. Commands and Functions
          5. Return Values and Exiting Handlers
            1. Leaving the Current Handler
          6. Dynamic Script Creation
            1. Do Statements
            2. Value Statements
            3. Setting the ScriptText at Runtime
        3. Variables and Properties
          1. Built-In Lingo Properties and Constants
            1. Common Errors When Using Properties and Constants
            2. Version
          2. Using Variables
            1. Assigning a Value to a Variable, Property, or Field
            2. Common Misconceptions About Variables
          3. Variable Types
            1. Local Variables
            2. Parameters
            3. Global Variables
            4. Property Variables
            5. Common Errors When Using Variables
            6. La Persistencia de la Memoria
            7. One-Time Initialization
          4. Variable-Related Lingo
          5. Allocation and Scope of Variables
        4. Lingo’s Skeletal Structure
          1. Comments
          2. Multi-line Code Structures
            1. Common Handler Declaration Errors
            2. Common Multi-Line Structure Errors
        5. Conditional Execution
          1. If...Then...Else...End If Decisions
            1. Single-Clause If...Then...End If
            2. Multiple-Clause If...Then...Else If...Else...End If
            3. One-Line and Two-Line If Statements
            4. The Classic Three-Line If Statement
            5. Nested Ifs
          2. Common Errors When Using If Statements
            1. Omitting the End If or the Then
            2. Failure to Use Else If
            3. Improper Comparison Expressions
            4. Nesting If Statement Unnecessarily or Incorrectly
            5. Excess End If Statements
            6. Missing End If Statements
            7. Inefficient Use of If Clauses:
          3. Case Statements
          4. Repeat Loops
            1. Altering Loop Execution
            2. Manually Controlling the Loop’s Counter
            3. Infinite Loops
        6. Parameters and Arguments
          1. Passing Arguments
          2. Generalizing Functions
            1. Generalized Sprite Handlers
            2. Generalizing a Function with Parameters
          3. Using a Generalized Function
          4. Special Treatment of the First Argument Passed
          5. Optional Arguments and Varying Argument Types
          6. Variable-Length Parameter Lists
          7. Parameter Error Checking
          8. Congratulations!
      2. 2. Events, Messages, and Scripts
        1. Events and Messages
          1. You Look Like a Programmer to Me
          2. Where the Hell Are My Scripts?
          3. Script Templates
          4. An Inexcusable Bug in Script Creation
          5. Events Versus System Properties
          6. Order of Event Execution
          7. The Lingo Messaging Hierarchy
        2. Lingo Script Types
          1. No Scripts Required
          2. A Dizzying Array of Scripts
          3. Cast Scripts
          4. Score Scripts
            1. Behaviors
            2. Sprite Scripts
            3. Frame Scripts
          5. Movie Scripts
          6. Parent Scripts
          7. Creating and Manipulating Scripts
            1. Finding Cast Members
          8. Compiling Scripts
          9. Primary Event Handlers
          10. Intercepting Errors and Messages
            1. The AlertHook
            2. Intercepting Built-In Lingo
          11. Handler Scope
          12. Script-Related Lingo
          13. Script Instances
            1. To Me or Not To Me
            2. Determining the Current Sprite’s Number
        3. Trapping Events with Scripts
          1. Movie and Window Events
            1. Movie Event Order
          2. Mouse, Keyboard, and TimeOut Events
          3. Frame and Sprite Events in the Score
          4. Miscellaneous Events
          5. Where Events Are Sent
        4. Message Processing Order
          1. Initialization and Clean-up
          2. Manually Passing and Stopping Messages
          3. The ActorList
          4. Simulating Events and Messages
          5. Custom Messages and Simulated Events
            1. Custom Message Errors and Return Values
      3. 3. Lingo Coding and Debugging Tips
        1. Lingo Coding Tips
          1. Coding Debugging and TroubleShooting Resources
          2. Coding Techniques
            1. Wrapper Functions
            2. Convenience Functions
            3. Redirection or Override Functions
            4. Consolidate Common Code Blocks into a Single Centralized Function
            5. Optional Debugging
            6. Shortcuts During Testing
            7. Alternative Code and Easter Eggs
          3. Error Checking
            1. Checking the User Configuration
            2. Checking Whether Lingo Commands Succeeded
            3. Checking Whether the Programmer Made a Mistake
            4. Checking User Input
            5. Range Checking
            6. Status Checking
            7. Bullet-Proofing
            8. Assuming Default Values
          4. Envisioning Your Lingo
          5. Director Doesn’t Know Anything
          6. Translating Reality to Lingo
          7. Feedback
            1. The Four Questions
        2. Zen and the Art of Debugging
          1. How to Think Like a Programmer
          2. What the Hell is Debugging Anyway?
            1. Debugging Is the Systematic Challenging of Assumptions
            2. Be Systematic
            3. Challenge Your Own Assumptions
            4. Debugging Tips
        3. The Lingo Debugger
          1. Script Errors
          2. Breakpoints
          3. Examining Problems in the Debugger and Watcher Windows
            1. Stepping Through Your Lingo Code
          4. The Message Window
            1. The Mighty Put
            2. The Trace, TraceLoad, TraceLogFile
          5. Alert
            1. The AlertHook and On AlertHook
          6. Debugging Projectors and Shockwave
        4. A Simple Sample Debugging Session
        5. Lingo Debugging Commands
      4. 4. Lingo Internals
        1. Lingo Internals
          1. Memory, Pointers, and Memory Access
          2. Compilation, Interpretation, and Performance
            1. Dynamic Compilation
          3. Language Definition
          4. Parameters and Variables
          5. Declarations, Type Checking, and Conversion
            1. Data Type Checking and Conversion
            2. Lists, Arrays, and Structures
            3. Strings
          6. Event and Error Trapping
            1. Debugging
            2. File I/O, Character Streams, and Printing
          7. Lingo Object-Oriented Programming Versus C++
            1. Class Hierarchy and Inheritance
            2. Encapsulation
    3. II. Lingo Data Types and Expressions
      1. 5. Data Types and Expressions
        1. Data Types and Variable Types
          1. Type Assignment and Conversion
          2. Type Checking
          3. Type Conversion Caveats
          4. Constants
          5. Symbols
        2. Operators
          1. Comparison Operators
            1. Comparison Caveats
          2. Boolean Properties and Logical Operators
            1. Implicit Comparison to Zero
            2. Forever TRUE
          3. Compound Expressions
            1. Common Errors in Compound Expressions
          4. String Operators
          5. Precedence Caveats
            1. String Precedence
            2. Cast Member and Sprite Reference Precedence
            3. Boolean Precedence
      2. 6. Lists
        1. List Basics
          1. Linear Lists
          2. Property Lists
          3. Rects and Points
          4. Creating Lists
            1. Invalid List Declarations
            2. Valid List Declarations
          5. Assigning, Passing, and Duplicating Lists
          6. Using Lists to Return Multiple Values from a Handler
          7. Cleaning Up After Lists
          8. Multidimensional Arrays
          9. Lists as a Database
        2. Lingo List Commands
          1. Making Sense of List Commands
          2. Sorting, Adding, and Changing List Elements
            1. Sort Order
            2. Recursive Sorting
            3. Reverse Sorting and Reverse Ordering
            4. Sorting and List Performance
            5. Adding Elements to Sorted and Unsorted Lists
          3. List Commands That Add and Modify Elements
          4. Deleting Elements
          5. Getting Info About, and Elements from, Lists
          6. Performing Math with Lists
          7. Lists in Expressions
            1. The list is treated as a single entity
            2. The first element of the list is used in the expression
            3. The operation is invalid or otherwise ignored
            4. Non-list Variables in Compound Expressions
        3. Commands by List Type
          1. Determining a List’s Type
          2. Linear List Operations
          3. Property List Operations
          4. Rect and Point Operations
          5. Looping with Lists
        4. List Utilities
          1. Randomized Lists
          2. Nonrepeating Random Numbers in a Range
          3. Converting List Types
        5. Other Lingo Commands That Use Lists
          1. Linear Lists
          2. Property Lists
          3. Pseudo-Lists
            1. Child Objects Properties
            2. Text Lists and Pick Lists
            3. Variable-Length Parameter Lists
      3. 7. Strings
        1. Strings and Chunk Expressions
          1. Chunk Expressions
          2. String Containers
          3. String Comparisons
          4. Lingo String Commands
            1. String Sizes and String Functions
            2. String Concatenation
          5. Text Parsing
          6. Accepting and Evaluating User Input
          7. Searching and Replacing Text
      4. 8. Math (and Gambling)
        1. Arithmetic Operators
          1. Integer and Modulo Division
            1. Integer Versus Floating-Point Division
            2. Division by Zero
            3. Modulo Division
        2. Math Functions
            1. Minimum and Maximum
            2. Checking and Clipping Values Within a Range
            3. Sum
            4. Average
          1. Exponents, Roots, and Logarithms
            1. Logarithms
            2. Exponents
          2. Geometry and Trigonometry
            1. Area of a Circle
            2. Moving a Sprite in a Circle or Along an Ellipse
        3. Number Systems and Formats
          1. Rounding and Precision
            1. Display Precision
            2. Numbers Out of Range
            3. Integer Rounding
            4. Integer Truncation
            5. Float Rounding
            6. Float Truncation
          2. Unit Conversion
            1. Converting Between Number Systems
          3. Random Numbers
            1. How Random Is Random?
            2. Random Numbers of Different Ranges
          4. The Online Casino
            1. Simulating Dice Rolls and Coin Flips
            2. Simulating a Deck of Cards
    4. III. Lingo Events
      1. 9. Mouse Events
        1. Mouse Events
          1. Mouse-Opaque Sprites
          2. Cursor-Opaque Sprites
          3. Checking for Mouse Events
            1. Determining the Current Sprite’s Number
            2. Determining Which Sprite Was Clicked
            3. Determining Which Sprite Was Rolled Over
            4. Invisible Sprites
          4. Standard Mouse Events
            1. MouseUpOutside Events and the ButtonStyle
          5. Double-Clicks
            1. Eating Rapid-Fire Clicks
          6. Multi-button Mice
            1. Windows Right Mouse Button
            2. Macintosh Right Mouse Button
        2. Mouse Properties
        3. Mouse Tasks
          1. Creating Draggable Sprites
          2. Mouse Traps
          3. Simulating Mouse Events
            1. Custom Mouse Events
          4. Flushing Mouse Events
          5. Mouse Event Idiosyncrasies
            1. MIAWs
            2. Shockwave
            3. Editable Text Fields
            4. Right Mouse Button under Window
            5. Menu Bars
            6. Custom Buttons
            7. Rollovers
      2. 10. Keyboard Events
        1. Keyboard Events
          1. Author-Time versus Runtime Keyboarding
          2. Standard Keyboard Events
          3. Multiple and Repeat Keys
        2. Keyboard Properties
          1. Determining Which Key Was Pressed
            1. Detecting the Key’s Case
          2. Modifier Keys
          3. Special Key Combinations
          4. Controlling the Quit Sequence
          5. Trapping Quit Keys Manually
          6. Keyboard Focus
            1. Creating Editable Fields
            2. Auto-Tabbing
            3. Highlighted Text and the Insertion Point
        3. Filtering Keyboard Input
          1. Simulating a Password Entry Field
          2. Editing Keys
          3. Numeric Keypad Input
          4. Function Keys
        4. Keyboard Tasks
          1. Key Trap
          2. Simulating Keyboard Events
          3. Keyboard Xtras
            1. Flushing Keyboard Events
            2. Polling for Keys and Multiple Simultaneous Keys
            3. Sending Key Events and Disabling Keys
          4. Keyboard Event Idiosyncrasies
            1. Authoring Caveats
            2. Kiosks Without Keyboards
            3. RSX Conflict
            4. Keyboard Events to Frame and Movie Scripts
            5. MIAWs
            6. Menu Bars
            7. MouseUp Events
            8. Shockwave
          5. KeyCode Tester
          6. Keyboard Potential
      3. 11. Timers and Dates
        1. Timers and Delays
          1. Timers
          2. Waits
            1. Waiting for a Fixed Time
          3. Waiting for Media
          4. TimeOuts
            1. Testing TimeOuts During Development
            2. Trapping TimeOut Events
            3. Handling Timeouts
        2. Time Units
          1. Time Scales
          2. Converting Time Units
            1. Frames Per Second to Time
        3. Date and Time Functions
          1. Date Properties
          2. Date Formats and Y2K
          3. Time Formats
          4. Parsing the Time
        4. Timing Utilities
          1. Gauging Performance
          2. Stop Watch Timer Object
          3. And You Thought I Forgot
          4. Asynchronous Operations
    5. IV. Applied Lingo
      1. 12. Behaviors and Parent Scripts
        1. What Is a Behavior?
          1. Creating Simple Behaviors
          2. Using the Behavior Inspector
            1. Inside the Behavior Inspector
            2. Behavior Inspector Pitfalls
        2. Objects of Mystery
          1. A Procedural Stopwatch
          2. Object-Oriented Programming
            1. The Life and Death of an Object
            2. Creating a Parent Script
            3. A Very Simple Parent Script
          3. An Object-Oriented Stopwatch
          4. I Gotta Be Me
          5. Common Errors with Parent-Child Scripting
          6. When to Use Object-Oriented Programming
          7. When to Use Behaviors
          8. Child Object References
            1. Child Object Properties
        3. Behaviors versus Other Script Types
          1. What Is a Behavior Script?
            1. Differences Among Behaviors, Sprite Scripts, and Frame Scripts
            2. Differences Between Behaviors and Parent Scripts
          2. Anatomy of a Behavior
            1. The GetBehaviorDescription Method
            2. The GetPropertyDescriptionList Method
            3. The #format Code
            4. The RunPropertyDialog Method
        4. Behavior and Parent Script Lingo
          1. Handler Evaluation with Behaviors
            1. New Sprite Events Sent to Behaviors Used as Sprite Scripts
            2. Handler Execution, The ScriptInstanceList, and the SpriteNum of Me
          2. The ActorList
          3. Adding Behaviors at Runtime
      2. 13. Lingo Xtras and XObjects
        1. Xtras
          1. ShowXlib
          2. Including Xtras with a Projector
        2. Lingo Scripting Xtras
          1. Deciphering the mMessageList
            1. Global-Level Methods
            2. Xtra-Level Methods
            3. Instance-Level Methods
          2. Using Instance-Level Methods
          3. Programming with Xtras
            1. Detecting Installed Xtras
          4. Xtras versus XObjects, XFCNs, XCMDs, and DLLs
          5. XObjects versus Xtras
          6. XObject Lingo
          7. Deciphering mDescribe
          8. Using an XObject
          9. Using an XCMD or XFCN
        3. Writing Your Own Xtras
          1. MOA XDK
          2. Supported Compilers
            1. Windows Compilers
            2. Macintosh Compilers
      3. 14. External Files
        1. External Files
          1. Lingo Commands for External Files
        2. File Paths
            1. Macintosh File Types and Creator Codes
            2. Files and Folders on the Desktop:
            3. Common File Problems
          1. Specifying File Paths in Lingo
            1. Parsing File Paths
          2. File Dialog Boxes
        3. FileIO
          1. File Operations
          2. SetFilterMask
          3. SetFinderInfo and GetFinderInfo
            1. Differences Between the FileIO Xtra and XObject
          4. Preferences File
            1. Writing Data to a File
            2. Parsing Retrieved Data
        4. External Applications
          1. Printing
          2. External File Caveats
      4. 15. The MUI Dialog Xtra
        1. MUI Alert Dialogs
        2. Custom MUI Dialogs
    6. V. Lingo Command Reference
      1. 16. Enumerated Values
      2. 17. Changed, Undocumented, and Misdocumented Lingo
        1. Underdocumented Utilities and Lingo
          1. LINGO.INI and DIRECTOR.INI Files
          2. Launcher Utility
          3. Xtras and XObjects
            1. FileIO Xtra—Read and Write Text Files
            2. MUI Dialog Xtra—Custom Dialog Boxes
            3. Custom Button Editor Xtra—Multi-state Buttons
            4. DirMMX Xtra
            5. The UI Helper Xtra and FileXtra
            6. The ActiveX Xtra and Java Export Xtra
            7. QuickTime-Related Xtras
            8. Flash Asset and Custom Cursor Xtras
            9. Unsupported Xtras
            10. Serial Port, CommPort, and Other XObjects
          4. Undocumented Variations and Misdocumented Lingo
          5. Lingo Changes from Director 5
          6. Obsolete Lingo
      3. 18. Lingo Keyword and Command Summary
          1. Why a Massive Table?
          2. Conventions Used in the Table
            1. Typographical Conventions
            2. Stylistic Conventions
          3. Categories and Comments
            1. New in Director 6
            2. Shockwave
            3. URL-enhanced
            4. Macintosh and Windows Compatibility
            5. Undocumented Keywords and Supplemental Commands
            6. Obsolete Commands
            7. Buggy or Erroneously Documented
            8. Read-Only Properties and Score Recording
            9. Chapter and Topic Cross-Reference
      4. 19. The Lingo Symbol Table
        1. Why Do I Care?
          1. Symbol Table Entries’ Case
          2. Symbol Table Entry Numbers
            1. Determining the Size of the Current Symbol Table
            2. Determining a Symbol’s Presence and Number
            3. Determining a Sprite Asset Xtra’s Presence
            4. Symbol Table Limits and Limiting the Symbol Table
    7. VI. Appendixes
      1. A. ASCII Codes and Key Codes
      2. B. Changes in D6 Through D6.5
        1. New Lingo in Director 6.5
        2. QuickTime 3 Sprite Asset Xtra
        3. QTVR 1.0 Xtra
        4. Flash Asset Xtra
        5. Custom Cursor Xtra
        6. Changes in Earlier Versions of D6
          1. Changes for D5 to D6
          2. Changes from D6.0 to 6.0.1
          3. Changes from D6.0.1 to 6.0.2
      3. C. Case-Sensitivity, Sort Order, Diacritical Marks, and Space-Sensitivity
        1. Case-Sensitivity
          1. Case-Sensitivity in Comparisons
            1. Sort Order Ranking
            2. Case-Insensitive Comparison
            3. Case-Sensitive Comparison
            4. Case-Sensitivity in Lists
          2. Case-Sensitivity in URLs
        2. Diacritical Marks
        3. Space-Sensitivity
          1. Trimming Spaces
      4. D. The DIRECTOR.INI and LINGO.INI Files
        1. DIRECTOR.INI
          1. [Memory]
          2. [Graphics]
          3. [Palette]
          4. [Sound]
          5. Other Sound Card Settings
        2. LINGO.INI
            1. LINGO.INI for Director for Windows
      5. E. Error Messages and Error Codes
        1. Lingo Compiler and Runtime Error Messages
        2. Director Error Codes
        3. FileIO Errors
        4. SWA Xtra getError(), getErrorString()
        5. Flash Asset Xtra getError()
        6. Network Errors—netError()
          1. Error Handling in Shockwave versus Projectors
        7. MOA Errors
      6. Glossary
    8. Index