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-2024, Director Online. Article content copyright by respective authors.