multimedia:

What is a List?    back to top

A variable is a container to hold information that will be needed by a script, and that can change.
A variable can allow Lingo to remember and use information for short periods (in a local variable) or long periods (in a global variable).

In normal variables, you can only hold one piece of information in a variable at a time. However, list variables allow you to store many pieces of information in one variable. Not only that, but a list is a data structure, and so allows us to do more than simply hold our data. Lists can be very powerful when scripting in Director.

When you consider many pieces of information being remembered and manipulated, think about how you might need to deal with those pieces of information. Is the information all related? Does it break down into subgroups of related info? Is there an order or progression to the information? How will you want to access or use the information? Will you need to count it? Or sort/reorder it?

Use lists when:

• you need to remember and/or access a lot of information or choices
• a lot of information is related or can be grouped together
• you need to count how many pieces of info have been gathered
• you need to preserve the order of the information or input
• you need to be able to shuffle/sort/reorder the order of things
• you want to be able to do a (limited) search for pieces of info
• you need to choose one thing (or certain number of things) out of many initial choices
• it would be awkward to use normal local or global variables

• the names of sound cast members to play randomly as background music
• the names of image cast members that you want to display in a certain set order
• the names of 20 image cast members from which you need to randomly pick 5 out for display in a random order
• the x and y positions of all sprites currently on the stage (basically, the sprite locations of everything on the stage)

Initial List Commands   back to top

Make a list variable global (in this case, the variable called playlist) by using the following command:

global playlist

global playlist, startlist, usernames

Initialize a list variable, which must be done before setting the list to anything or adding anything else into it:

playlinearlist = []

playpropertylist = [:]

Setting linear lists to hold desired information:   back to top

decimal = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

origlist = ["sound1", "sound2", "sound3", "sound4", "sound5", "sound6", "sound7", "sound8"]

Notice how the list items in both these simple list examples are within square brackets, and separated by commas. Notice how the list holding strings has quotation marks around the words.

This is necessary because of how Director always classifies information as either a value or a string -- quotation marks around something indicate it is a string. A string without quotation marks around it will be interpreted by Director as a variable if it has letters in it, or as a number if it only has numbers in it. Here's more information about strings and values.

Here is a linear list being set to hold both numeric (value) information, and word (string) information:

decimal = ["nw", 1, "cg", 3, "gh", 2]

When using lists, it is important to be able to know or to count the number of items in the list, and it is important to be able to refer to items in the list by their number.

Other List Commands:   back to top

append list, thing2add

So if my list is:

sharks = ["ancient", "beautiful", "widespread", "carnivorous"]

and I want to add the word "endangered" on to the end of the list, I would say:

append sharks, "endangered"

And the list would now be:

sharks = ["ancient", "beautiful", "widespread", "carnivorous", "endangered"]

I could also append a value to the list, or a variable to the list:

If I wanted to add the number 7 to the end of the list, I'd say:

append sharks, 7

Or if I wanted to add the contents of the variable x to the end of the list, I'd say

append sharks, x

Delete an item from anywhere in the list, using the command:

deleteAt list, position

So if my list is:

sharks = ["ancient", "beautiful", "widespread", "carnivorous", "endangered"]

and I want to delete the word "widespread" from the list, I have to know what order the list items are in, know that "widespread" is therefore item number 3, and say

deleteAt sharks, 3

Get an item out of anywhere in a list, using the command:

getAt(list, position)     -- old syntax
OR
list[position]     -- new syntax

So if my list is:

sharks = ["ancient", "beautiful", "carnivorous", "endangered"]

and I want to get the word "ancient" from the list, I have to know what order the list items are in, know that "ancient" is therefore item number 1, and say

getAt(sharks, 1)
OR
sharks[1]

I could put item 1 from the list sharks into a variable called qualities like so:

put getAt(sharks, 1) into qualities
OR
qualities = sharks[1]

Count items in the list, using the command:

count(list or theObject)     -- old syntax
OR
list.count     -- new syntax

So if my list is:

sharks = ["ancient", "beautiful", "carnivorous", "endangered"]

and I want to count the list and put the number of items left in the list into a variable, I say

x = sharks.count

and I know that x will equal 4, because there are 4 items in the list.

Counting lists can be really useful when you keep adding or deleting things from a list (which makes it hard to keep track of how many items there are), or when you are collecting pieces of information about the user and you don't know how many you've got.
Any time you want to go through a list (in order to search for certain data, or to set things in your movie to the data in the list), it is wise to count the list to make sure your script knows how many items are in the list so it doesn't go looking for item 21 if there are only 20 items in the list (it avoids causing an error).

If you append items to the list, or add additional items to the list with another command, or delete items from the list, this will change the result you get from counting the list (as expected, because these commands change how many items there are in the list).

Add an item to the list anywhere in the list without deleting any current items, using the command:

addAt list, position, thing2add

So if my list is:

sharks = ["ancient", "beautiful", "carnivorous", "endangered"]

and I want to add the contents of the variable newadj to the list in position 4, I would say

addAt sharks, 4, newadj

The list would now be one item longer, and whatever was in newadj would now be in position 4.

Assuming the variable newadj had been set to contain the string "important", the list would now look like this:

sharks = ["ancient", "beautiful", "carnivorous", "important", "endangered"]

Notice that the item that was previously in position 4 is now in position 5. If there had been any items after it, they would also have moved down one position.

Set an item anywhere in the list to something else (will delete any current item currently in that position, replacing it with the new data) using the command:

setAt list, position, thing2add     -- old syntax
OR
list[position] = thing2add     -- new syntax

So if my list is:

sharks = ["ancient", "beautiful", "carnivorous", "important", "endangered"]

and I want to replace the string "ancient" with the string "an ancient form", I need to know what position the string "ancient" is in, and say

sharks[1] = "an ancient form"

which will result in a list that is the same in terms of how many items it contains, but is changed in terms of what is in item 1:

sharks = ["an ancient form", "beautiful", "carnivorous", "important", "endangered"]

Find the location of an item anywhere in the list, or figure out whether it is contained in the list at all using the command:

findPos (list, thingsearchingfor)     -- old syntax
OR
list.findPos(thingsearchingfor)     -- new syntax

So if my list is:

sharks = ["ancient", "beautiful", "carnivorous", "important", "endangered"]

and I want to see if the string "carnivorous" is in the list, I say

x = sharks.findPos("carnivorous")

which will set x to be the item number of the string "carnivorous", assuming that "carnivorous" is in the sharks list. If "carnivorous" is not in the sharks list, x will equal 0.

Once you find out that an item is in the list, you can use the item number you got with the findPos command to do things with the item; get the item immediately after it, for instance, or delete the item itself out of the list...

You can also use findPos in an if statement to check if an item is in the list, and if it is not already, add it into the list. For example, here's a list called nowtouching in an if statement:

if nowtouching.findPos(me.spritenum) then -- if the sprite number is in the list then
    nothing -- do nothing
else -- BUT if the sprite number is not in the list then
    germ = germ + 1 -- add to the score
    member("germ").text = string(germ) -- display score
    append nowtouching, me.spritenum -- add sprite number to nowtouching list
end if

Here's another if statement, using the same list, but deleting the sprite number out of the list if it is already in there:

if nowtouching.findPos(me.spritenum) then -- if the spritenum is in the list
    p = nowtouching.findPos(me.spritenum) -- find the position of the sprite number in the list, and put it into p
    -- deleteAt listname, position -- is the delete command
    deleteAt nowtouching, p -- delete the item from the list at the p position
end if

Set a variable to be an independent copy of a list (as opposed to just setting a variable to equal the list, which means it would not be independent) using the command:

duplicate(list)    

So if my initial list is:

sharks = ["ancient", "beautiful", "carnivorous", "important", "endangered"]

and I want to have a variable called reptilians, and I want it to be the same as the sharks list, but totally independent, I would do this:

reptilians = duplicate(sharks)

which will result in a reptilians list that contains exactly the same items as sharks, but is independent.


In contrast, the following line is not a desirable way to make a copy of a list:

seamonsters = sharks

This line results in the seamonsters list being exactly the same as the sharks list, such that if I do anything to the sharks list (like add or delete something) that change will also have been made in the seamonsters list. This is also true of any changes I made to the seamonsters list --they would immediately show up in the sharks list. In this situation, anything you do to one list affects both. This, therefore, is not very useful or desirable, because it is not like having two lists; instead, it is like having one list with two names.

What is useful and desirable is to be able to have an independent list that starts out as a copy, but which we can now make changes to without affecting the original list. This is what the duplicate command allows us to do. If, for example, I delete something from the reptilians list, like so:

deleteAt reptilians, 3

the resulting reptilians list would be equal to: ["ancient", "beautiful", "important", "endangered"]

but the sharks list would remain as it was (item 3 would not have been deleted out of it) which would make sharks still be this: ["ancient", "beautiful", "carnivorous", "important", "endangered"]

And if we were to do anything to the sharks list, it would only affect the sharks list; it would not affect the reptilians list.





Property lists:

for example:
foundtext = ["FACS": 2, "word": 1]

notice how items are pairs, and each pair has a colon between them.

Property list commands:

getAt(list, item#)
gets out of the property list the 2nd thing in the pair (in the above, the value)

getPropAt(list, item#)
gets out of the property list the 1st thing in the pair (in the above, the string)