Articles Archive
Articles Search
Director Wiki
 

Why Use Lists?

March 9, 1999
by Judi Taugher

You're probably familiar with the concept of variables. A variable is a storage area that you define to hold a piece of data. For example, to define a variable called "soundFx" and to set its value to "snap", you would use the command:

set soundFx = "snap"

If you wanted to store the name of more than one sound effect, you could define a variable for each one:

set soundFx1 = "snap"
set soundFx2 = "crackle"
set soundFx3 = "pop"

However, soon the number of variables would become unmanageable. Besides, Lingo provides a convenient way to store multiple pieces of data: in a list. A list is just a type of variable that can hold several pieces of data at a time. You define a list by surrounding all the data with square brackets and putting a comma in between each piece of data:

set soundFx = ["snap", "crackle", "pop"]

Using lists is a smart thing to do and makes your code concise and readable.

What Can You Do With Lists?

Once you've defined a list, what can you do with it? You can check whether something is in the list, you can get the position of a piece of data, you can sort the list, you can add data, or delete data. One action that you'll always want to do is to retrieve a piece of data from the list.

Say you want to play a different sound effect each time the user clicks a button. The first time the button is clicked you want to play the first sound effect in the list. To retrieve a piece of data from a list when you know its position, use the getAt command. getAt is followed by the name of the list and the position of the piece of data that you want to retrieve. So the first time the button is clicked, you would use a command like this:

puppetSound 1, getAt(soundFx, 1)

which gets translated into:

puppetSound 1, "snap"

Linear Lists

There are two types of lists in Lingo. The type of list I've been talking about so far is called a linear list. In a linear list each item is made up of a single piece of data.

One example of a linear list that I've used in my projects is a cue list to time an animation to a voiceover. We translate our product into 10 languages and the timing needs to be different for each language. In the prepareMovie script, I define a list variable called gCueList and set it to a different list of values depending on which language is running on the user's computer. Like this:

if gLanguage = #english then
  set gCueList = [30, 60, 90, 120, 150]
else if gLanguage = #francais then
  set gCueList = [33, 70, 120, 165, 210]
else if gLanguage = #espanol then
  set gCueList = [31, 66, 110, 150, 183]
end if

Then in each frame of the movie where I want the animation to pause and wait for the voiceover to catch up, I have an exitFrame script similar to:

if the timer < getAt(gCueList, 1) then go the frame

Linear lists are also useful for things like making a list of video clips for the user to watch, playing a set of wave files randomly, or keeping track of which screens the user has already seen.

Property Lists

A property list is a special type of list for associating two related pieces of data. Or another way to think of it is each piece of data that you want to store is labeled with a descriptive name. The descriptive name is called a property. The data itself is called a value. The two together form a property:value pair. To define a property list, use a colon between the property and the value:


set highScore = ["Joe":14000, "Sally":12750, "June": 9905]

It is important to note that you can not have duplicate property names in a property list. For example, in the highScore list above, if another player named Joe got a highscore, the original Joe's score would be replaced. So, you may want to take special care in selecting unique property names that are not likely to be duplicated.

A Plethora of List Commands

As you'll soon find out as you begin to use lists, there are many list commands. Moreover, there are many similarly named list commands and, sometimes, there is more than one list command that does exactly the same thing. For example, for the getAt command that I used earlier, I could have also used getaProp. They're exactly the same. In addition, Director 7 adds yet another way to do this: the square bracket notation.

There have been many times when I've gone to the Lingo Dictionary and spent 15 minutes (or more) figuring out the difference between getaProp, getProp, getPropAt, and getAt. Because the command names are so similar, it just doesn't stick with me and I have to do it all over again the next time. This is the reason why I put together the tables in this article. With the tables I can look up the commands a lot faster. I hope you find them useful too.

Using the Tables

There's one table for linear lists and another for property lists. In the first column, find the action you want to perform. In the second column, find the information that you already know. Then in the third column, find the command to use. If more than one command is listed, they're equivalent unless a footnote explains the difference. Of course, you might still need to read your Lingo Dictionary to learn about any quirks the commands might have. The square bracket and dot notations are new in Director 7 and can't be used in previous versions.

You can install these tables online in Director so that you can easily refer to them while you're coding. Download the file and uncompress it into your Director Xtras folder (usually something like C:\Program Files\Macromedia\Director 6_5\Xtras on the PC). The next time you restart Director, click Xtras on the menu bar. You'll see two new choices: "Commands for linear lists" and "Commands for property lists". Click to bring up an online version of these tables.

The files are available for download in ZIP format.

Linear List (item1, item2, ... )
To: And you know the: Use the command:

Create
create an empty linear list -- list = [ ]
create a populated linear list items list = [item1, item2, ...]

Add
add an item at end of an unsorted list or in order in a sorted list -- list.add (item)
add list, item
add an item at end regardless of whether the list is sorted -- list.append (item)
append list, item
add an item in a specific position position list.addAt ( position, value)
addAt list, position, item

Replace
replace an item position list[position] = newItem
setAt list, position, newItem

Delete
delete an item item list.deleteOne (item)
deleteOne list, item
delete an item position list.deleteAt (position)
list.deleteProp (position)
deleteAt list, position
deleteProp list, position
delete all items -- list.deleteAll ( )
deleteAll list
Get
get an item position list[position]
getaProp (list, position)
getAt (list, position)
get the last item -- list.getLast ( )
getLast (list)
get the greatest item -- list.max ( )
max (list)
get the least item -- list.min ( )
min (list)
get a position item list.getOne (item)
list.getPos (item)
getOne (list, item)
getPos (list, item)
get the position of the closest match item list.findPosNear (item)1
findPosNear (list, item)1

Sort
sort the list -- list.sort ( )
sort list
 
Property List (property1:value1, property2:value2, ... )
(The word item refers to a property:value pair.)
To: And you know the: Use the command:

Create
create an empty property list -- list = [:]
create a populated property list items list = [property1:value1, property2:value2, ...]

Add
add an item at end of an unsorted list or in order in a sorted list -- list.addProp (property, value)
addProp list, property, value

Replace
replace a value property list.property = newValue2, 4
list[property] = newValue2
setaProp list, property, newValue2
setProp list, property, newValue2
replace a value position list[position] = newValue
setAt list, position, newValue

Delete
delete an item property list.deleteProp (property)
deleteProp list, property
delete an item value list.deleteOne (value)
deleteOne list, value
delete an item position list.deleteAt (position)
deleteAt list, position
delete all items -- list.deleteAll ( )
deleteAll list

Get
get a property value list.getOne (value)
getOne (list, value)
get a property position list.getPropAt (position)
getPropAt (list, position)
get a value property list[property]3
list[#property]3
list["property"]3
getaProp (list, property)3
getProp (list, property)3
list.property3, 4
get a value position list[position]
getAt (list, position)
get the last value -- list.getLast ( )
getLast (list)
get the greatest value -- list.max ( )
max (list)
get the least value -- list.min ( )
min (list)
get a position property list.findPos (property)
findPos (list, property)
get a position value list.getPos (value)
getPos (list, value)
get the position of the closest match property list.findPosNear (property)5
findPosNear (list, property)5

Sort
sort the list -- list.sort ( )
sort list

2 setaProp and the [] syntax add the item if the property doesn't already exist. setProp and the . (dot) syntax return an error if the property doesn't exist.

3 getaProp and the [] syntax do not return an error if the property is not found. getProp and the . (dot) syntax return an error if the property is not found.

4 In the property, don't use the # character if this is part of your property name.

5 The list must be sorted to use this command.

Copyright 1997-2017, Director Online. Article content copyright by respective authors.