Goal

In this exercise you will learn how to make use of linear lists in your Adobe Director Movies. You will also learn some basics of property lists, and how they can be used to enhance your Director movies.

Background:

All major programming languages have the capability to store data in an array. An array is a collection of strings, numbers, or other data types contained within a single variable. In Lingo, arrays are called lists. Lingo supports two types of lists, a linear list, and a property list. A linear list usually contains a series of numbers or strings, but may include other data types as well. Linear lists are easiest to manage when they contain the same type of data, such as the names of cast members, or numerical location values for an animated sprite. Property lists are best for multivariate data, such as a database that contains names, addresses, phone numbers, and other contact information for business clients. Property lists are the most versatile of the two, but linear lists are easier to learn. Both types of lists will be discussed below.
 

Creating a Linear List:

A Lingo list is nothing more than a collection of data stored within a variable. Suppose, for example, that you want to keep track of fruit you're going to pick up at the grocery store. Using traditional variables, you would need at least one variable for each list item you want to keep track of. For example, if you wanted to keep track of the names of three fruits you might make a variable called "fruit" and put a number after it, to identify each variable. The three variables would be named, "fruit1", "fruit2", and "fruit3". In a Movie Script you might declare them as global variables, and assign them values when the movie starts up. The Movie Script might look like this:

on startMovie
spacer_global.fruit1 = "Apples"
     _global.fruit2 = "Oranges"
     _global.fruit3 = "Peaches"
end

This method would do the job, but it's awkward, and it relies on you to carefully make sure each variable name is unique, and is assigned the correct string describing the name of the fruit. If you had to make a list of 20 fruits in this way you would quickly become frustrated and find the task to be unnecessarily tedious. For this example, and many other applications, a list is a much better solution. A list may contain any number of items, in both a text (string), or numeric format, (or both), and all data within the list can be stored within a single variable. Lists can even contain other lists, so the possibilities are virtually endless.

For now we'll use the Message Window to experiment with lists. To define a linear list, type the following in the Message Window (don't forget to hit the RETURN key at the end of the line to activate the code statement):

myList = ["Apples", "Oranges", "Peaches"]

The above statement assigns the variable named myList the value of the linear list that is defined to the right of the equals operator. To view the list you just created, as Lingo sees it, type the following in the Message Window:

trace(myList)

You should see:

-- ["Apples", "Oranges", "Peaches"]

The above list has three items in it, yet all of the items in the list are stored within a single variable named myList. To have Lingo tell you how many items are in the above list, type the following in the message window:

trace(myList.count)

You should see:

3

To view just one item (the second item in the list) type:

trace(myList[2])

You should see:

-- "Oranges"

To add an item to the above list, type the following:

myList.add("Bananas")

If you view the list now it will look like this:

-- ["Apples", "Oranges", "Peaches", "Bananas"]

To remove the first item from the above list, type the following:

myList.deleteAt(1)

The list now looks like this:

-- ["Oranges", "Peaches", "Bananas"]

As you can see, linear lists are very easy to use. Let's define a new series of strings for the variable myList. Type the following in the Message Window:

myList = ["apple", "orange", "milk", "cheese", "eggs"]

All of the values in the old version of myList will be replaced with the new items you just typed. When you create a list, Lingo assigns an invisible structure to the data contained within the list, which you can directly access. The above list is comprised of 5 items:

List Items


To view the first item in the list, for example, you could type this into the Message Window:

trace(myList[1])

The Message Window shows:

-- "apple"

As long as the item you access is within the "range" of the list you can view it this way. If you try to access an item in the list that is out of range you will get an error:

List Error

This is telling you that you tried to access a list item position that does not exist. It is "out of range" because the list currently contains only 5 items.

If you are used to other programming languages, such as JavaScript, or C, you will note that Lingo does not use "zero indexed" arrays, meaning that the first index item in a Lingo list equals 1, not 0. This may take a little getting used to, as most other popular C-based programming languages assign the first element of an array an index position of 0.

You can reassign an item in a list by using an equals operator. To reassign the first item in the previously assigned list do this:

myList[1] = "cantaloupe"

-- ["cantaloupe", "orange", "milk", "cheese", "eggs"]

The first item in the list is now "Cantelope," not "Apple".


Putting Linear List
s to Work:

Lists are very useful for controlling sequences of information, such as the order of the display a series of images. At the end of this exercise is an example of a Director Movie that makes use of a list to display the items in a list, one at a time, when a button is clicked. The example movie can be easily enhanced to allow the items of a list to change images, sounds, or even QuickTime movies. This can be very handy if you want to have a Director movie that operates from one frame, without the need to create a "layout" on different frames in your movie, with a unique sprite for each image.

To have a list control the order of appearance of Cast Members, the items in the list must call up Cast Members that have the same names as the items in the list. For example, if you have a bitmap cast member named "Apples" and another one named "Bananas" you could easily swap the member of the sprite having the apple image with the image of a banana, and use a list to determine which image should be swapped next.

You will also find a Director Movie Example at the end of this exercise that uses a list to display text and images for a slide show. This is a very useful technique to learn, and works with a variety of media supported in Director.
 

Property Lists:

Property lists are an expansion on the idea of a linear list. Property lists are more complex than linear lists, but are also more versatile. In a property list each item contains both a property name and a property value. For example, a property list of fruit might also contain the price per pound of the fruit.

myList = [#fruit: "apple", #price: 1.29]

To access the type of fruit from the above list we need to enter the name of the list, followed by a period, followed by the property to retrieve. Like this:

trace(myList.fruit)

This prints the following to the Message Window:

-- "apple"

The property names we created in the list (i.e., the words that have a symbol "#" in front of them) become real properties for the property list. This is why we access the list name, followed by a period, then the property from the list we want to access. The "dot" notation is just like the method used to access sprite properties.

Using the Message Window we can access the price of apples from the above property list like this:

trace(myList.price)

Property lists become somewhat more complex when you want to create a lot of property items, such as in a database. Here's a Movie Script that defines a property list when the movie starts up and puts the names and prices of all the fruit in the list in the Message Window.

on startMovie
spacer-- initialize a linear list and store it in a global variable
spacer_global.database = []
spacer-- add property list items to the linear list
spaceradd _global.database, [#name: "apples", #price: "1.29"]
spaceradd _global.database, [#name: "oranges", #price: "1.50"]
spaceradd _global.database, [#name: "Grapes", #price: "1.99"]

spacer-- display all items in the database
spacerrepeat with i = 1 to _global.database.count
spacerspacerput _global.database[i].name && _global.database[i].price
spacerend repeat
end

Building on the above technique allows powerful database applications to be developed that can manage large numbers of items, such as word lists for word games, or player scores.

We have only scratched the surface of what's possible with lists in Director. Lingo provides many useful keywords that are specifically made for manipulating lists of both types and the Director Help System is a good place to find out more about how to work with Lists. Both linear and property lists are useful for different applications, but Property lists are key to creating your own advanced Lingo behaviors, so they are well worth learning. Peruse the example movies and try making a slide show program that works like the "Wyoming Pictures" example, where a list defines the order of images. You will find that the "list" technique for swapping Cast Members works nicely for sounds, and even movies, with only slight modifications.
 

Example Movies:

Simple List Example (10 KB)

Text List Example (12 KB)

Slideshow List Example (4.6 MB)

Sprite Movement Recorder (10.5 KB)

Shuffle Images in a Slideshow (3.6 MB) 

<     Table of Contents     >