Director Tutorials


The Power of Lists - List Lingo

Lists are variables that contain multiple pieces of data at once. Each unit (known as an entry) can be manipulated without affecting the others. Knowledge of lists is vital for a strong command of Lingo’s advanced functions. Well-written lists help manage multiple windows, Xtras, Parent/Child objects and any other data you have in your movies.

There are 2 types of lists:
Linear list:
a series of single values in sequence. Each item, separated by a comma, is a single unit of data.

Property list: contains 2 units of data for each entry, separated by a colon (:). The first unit is the property name (data that can be used for organising purposes), the second unit is the value associated with the property (data to be stored, retrieved or modified).

Creating Lists

Lists have to be assigned to a variable to be used.
ListName = [entry1, entry2, etc]

The square brackets are crucial, since they tell Lingo how to recognise a list. To dispose of a list (or create a list prior to entries), set the values to 0 by using empty brackets ListName = [ ]. For a property list, use a colon ListName to [:]

1. In the message window type:
CourseList = ["Advanced Multimedia", "Computer-Aided Design", "Digital Design Techniques"]

This creates a linear list, called CourseList, with 3 entries, each a text string. Text is always placed in inverted commas (" "), otherwise Lingo will read the entries as variables.

2. In the message window type:
put CourseList

This returns/displays the list we just created. If you read any <void> entries, you may have left out the inverted commas and Director is reading the entry as a variable, which has no value. Try creating the list in step one with just variables.

The power of lists lies in the many ways you can access and modify the information they contain. Lingo has several commands and functions serving this purpose.

getAt (listName, position) or listName [position]
This function returns the value on the list at the position indicated.

3. In the message window type:
put getAt (CourseList, 2)
put CourseList [2]

You should see
-- "Computer-Aided Design"

You could assign getAt (CourseList, 2) to a variable as shown below:
CAD = getAt (CourseList, 2)

getOne (listName, value) or listName.getOne(value)
This function returns the position of the given value on a linear list.

4. In the message window type:
put getOne (CourseList, "Digital Design Techniques")

This time the result should be 3, since it is the third item on the list.

addAt (listName, position, value) or listName.AddAt(position, value)
This function adds an entry at a specified position of a linear list.

4. In the message window type:
addAt (CourseList, 2, "Construction")
put CourseList

The new name should appear in the list at position 2, pushing the other items one back.

Below is further linear list Lingo:
setAt (listName, position, value) or listName.setAt(position, value) or list[position] = value
Adds an entry at a specified slot, overwriting the contents of that location.

add(listName, value) or listName.add(value)
Will simply add another entry. If the list is unsorted, the addition will be at the end, if sorted, it will go into its proper location in the alphanumeric order.

addAt(listName, position, value)
or listName.addAt(position, value)
Adds a value at a specified position in the list.

append(listName, value) or listName.append( value)

Adds the specified value at the end of the list even if it is sorted.

getLast(listName) or listName.getLast()
Returns the last value on a list

count(listName) or listName.count
Returns the number of items on a list

sort(listName) or listName.sort()
Sorts a list in ascending order

Property Lists

Sometimes data has meaning only in a specific context and this is when we property lists can be used. Property lists have the format of [property1:value1, property2:value2]

For example: Let’s look at students each with a grade for their multimedia assignment.

1. In the message window type:
MMList = ["Jack":95, "Jill":50, "Peter":65, "Sarah":75]

Each name has a numerical value associated with it. The name is the property, and the number is the value, which in this case represents the percentage score. The properties are text strings. Since they are just names that won't be changed, it is better to use symbols as a data type. Symbols are faster than text strings. (See bottom of page for more info on symbols.)

In property lists, the property data does not change, only the value associated with it. If you wanted to change the property, you would delete the entry and add a new one with the new property name and value.

2 In the message window type:
MMList = [#Jack:95, #Jill:50, #Peter:65, #Sarah:75]

getProp(listName, property) or
2. Enter the following:
result = getProp (MMList, #Peter)
put result

The above gets the value associated with a property, so finds 65, the value of property #Peter. If you were writing the statement in dot syntax, you'd use:
result = MMList.Peter

3. Enter the following:
put min (MMList)

The result is 50, can you guess why?

4. Enter the following:
put getOne (MMList, 95)

The message window should return #Jack.

Some of the linear list functions work for property lists. Some functions are specific to each list type.:
getAt (listName, position) or listName [position]
As in linear lists, this function returns the value on the list at the position indicated. You can also get the value associated with a property using listName [property]

To find a property at certain position, we can use
getPropAt (listName, position) or listName.getPropAt(position)

Other property list functions and commands
findPos(listName, property) or listName.findPos(property)
Identifies the position of a property in a property list.

setProp(list, property, newValue)
or = newValue
Replaces the value assigned to a specified property with a new value.
only works when the property is a symbol.

deleteProp(listName, property)
or llistName.deleteProp(property)
Deletes a property and also deletes its associated value.

or listName.sort()
When the list is a linear list, the list is sorted by values.
When the list is a property list, the list is sorted alphabetically by properties.

Common among Linear Lists and Property Lists
deleteAt(listName, position) or listName.deleteAt(position)
Command that deletes an entry from a linear or property list at a specified position.

For more information on lists, check out:
DOUG - Why Use Lists?
DOUG - Using property lists
DOUG - Drag 'n Drop into a List


One trick that comes in handy when using lists is the use of symbols rather than text strings to identify values. By placing a pound sign (#) before a data name (e.g. #dean) you define it as symbol. Symbols are not variables but a variable value that cannot change. The advantage is they take up less memory, are retrieved faster and are generally very efficient.

And that is a basic explanation of lists. To learn more about the application of lists, go to the
User Tracking with Lists Tutorial.