Lingo in a Nutshell

Conventions Used in This Book

Typographical Conventions

• Lingo keywords (functions, commands, and property names) are shown in italics except in tables where they are italicized only when necessary to distinguish them from the surrounding text. Italics in tables usually indicate replaceable values.

• Arguments, user-specified, and replaceable items are shown in italics and should be replaced by real values when used in your code.

• New terms are shown in italics and are often introduced by merely using them in context. Refer to the Glossary for details.

• Menu commands are shown as MenuName➤ MenuItem.

• Options in dialog boxes, such as the Tab to Next Field checkbox, are shown in italics.

• Constants, such as TRUE, FALSE, and RETURN, are shown in Courier.

• #symbols are preceded by the # character and shown in Courier.

• Optional items are specified with curly braces ({}) instead of the traditional square braces ([]) which Lingo uses for lists. For example:

  go {to} {frame} whichFrame

  means that the following all are equivalent:

  go whichFrame
  go to whichFrame
  go to frame whichFrame
  go frame whichFrame

• Allowed values for a property are separated by a “|”. The following indicates that the alignment of member property can be set to “left,” “right,” or “center”:

  set the alignment of member 1 = "left" | "right" | "center"

Grammatical and Stylistic Conventions

• Most Lingo properties start with the word the, which can lead to sentences such as “The the member of sprite property can be changed at runtime.” I often omit the keyword the preceding properties to make sentences or tables more readable, but you should include the the in your Lingo code.

• Lingo event handlers all begin with the word on, such as on mouseUp. I often omit the word on when discussing events, messages, and handlers or in tables where the meaning is implied.

• Be aware that some Director keywords are used in multiple contexts such as the on mouseUp event handler and the the mouseUp system property. The intended usage is discernible from context, or stated explicitly in ambiguous circumstances.

• I use terminology fairly loosely, as is typical among Lingo developers. For example, a "mouseUp script” is technically “an on mouseUp handler within a script.” The meaning should be clear from the context.

• I capitalize the names of Director entities, such as the Score, the Stage, the Cast, and the Message window. I don’t capitalize general terms that refer to classes of items, such as sprite scripts.

• Most handler names used in the examples are arbitrary, although handlers such as on mouseUp that trap built-in events must be named as shown. I use variable names like myThing or whichSprite to indicate items for which you should substitute your own values. When in doubt, consult Table 18-1.

• I use few segues and assume you will reread the material until it makes sense. As with a Dalí painting, you must revisit the text periodically to discover details that you missed the first time.

Examples

• Example code is shown monospaced and set off in its own paragraph. If a code fragment is shown, especially using the put command, it is implicit that you should type the example in the Message window to see the result. Any text following "--" is the output from Director or a comment from me:

   set x = 5   -- Set the variable x to 5
   put x       -- Display the value of x
   -- 5

• Long lines of Lingo code are continued on the next line using the Lingo continuation character ([LC]) as shown here. This character is created using Opt-Return or Option-L (Macintosh) or Alt-Enter (Windows).

   set the member of sprite (the currentSpriteNum) = ¬
      member "Hilighted Button"

• If you have trouble with an example, check for lines that may have been erroneously split without the Lingo continuation character (¬). Remember to use parentheses when calling any function that returns a value. Otherwise you’ll either see no result or receive an error.

   rollover        -- wrong
   rollover()      -- wrong
   put rollover    -- wrong
   put rollover()  -- correct

• I sometimes use the single-line form of the if...then statement in an example for brevity. You should use multiline if...then statements in your code. See Chapter 1 for details on the if statement.

  -- This will usually work
   if (x > 5) then put "It's True!"
   -- But this is more reliable
   if (x > 5) then
      put "It's True!"
   end if

• If a handler is shown in an example, it is implied that the handler has been entered into the appropriate type of script. Generally, mouse event handlers such as mouseUp belong in sprite scripts; frame events handlers such as exitFrame belong in frame scripts; and custom utilities belong in movie scripts. I often show a handler followed by an example of its use. Type the handler into an appropriate script, and then test it from the Message window. If I don’t show a test in the Message window, either the handler does not output a visible result, or it is assumed that you will test it yourself.

  -- This goes in a script, in this case a movie script
   on customHandler
     put "Hello Sailor!"
   end customHandler
  
   -- This is a test in the Message window
   customHandler
   -- "Hello Sailor"

• The output shown may vary inconsequentially from the results you would see based on your system setup. Most notably, the number of decimal places output for floating-point values depends on your setting for the floatPrecision property.

• If the output of a handler is extremely long, the results will not be shown in their entirety or may not be shown at all.

• The examples are demonstrative and not necessarily robust, and they assume that you provide valid inputs when applicable. It is good practice to include type checking and error checking in your actual Lingo code, as described in Chapter 1 and Chapter 3. I often omit such checking to keep examples shorter and to focus on the main issue at hand.

• Some examples, particularly the tests performed from the Message window, are code fragments and won’t work without help from the studio audience. You should ensure that any variables required by the examples (particularly lists) have been initialized with meaningful values, although such initialization is not shown. For example:

  put count (myList)

  The previous code fragment assumes that you have previously set a valid value for myList, such as:

  set myList = [1, 7, 5, 9]

• Some examples allude to field cast members, such as:

  set the text of field "Memory" = string(the freeBlock)

  It is implied that you should create a field cast member of the specified name in order for the example to work.

• Screen shots may not match your platform’s graphical user interface exactly.

• I present a simplified view of the universe whenever my assumptions are overwhelmingly likely to be valid. You can intentionally confuse Director by setting bizarre values for a property or performing malicious operations, such as deleting elements from a rect structure, but you do so at your own risk. I cover situations where errors might occur accidentally, but you should assume that all statements presented as fact are prefaced by, “Assuming you are not trying to screw with Director just for fun...” When they are likely to be relevant, I state my assumptions clearly.

• The myriad ways to perform a given task are shown when that task is the main topic of discussion but not if it is peripheral to the subject at hand. When it is incidental, I may show the most expedient or clearest method rather than the suggested method.

• Examples are usually self-contained, but they may rely on custom handlers shown nearby. If an example builds on previous examples or material cross-referenced in another chapter, it is assumed that the relevant handlers have been entered in an appropriate script (usually a movie script).

• What rightly belongs in one table sometimes is broken into two or three due to space constraints. Similar information may be organized in different ways in multiple tables to help you find what you want, especially in Chapter 6. The first column of each table contains the table’s “key item” for which full details are provided. Subservient items, for which the table may not contain complete information, are relegated to other columns. For example, if a function is listed in the "See Also" column of a table, complete details on that command can be found in surrounding prose or other tables.

Refer to the Glossary for a complete list of definitions.