The on getPropertyDescriptionList handler isn't covered thoroughly in the book, but it is a very useful script. This handler allows you to set and control custom properties of a sprite throughout the life of the sprite, without using global variables. With getPropertyDescriptionList, you define properties and create a dialog box which allows you to set the properties of a sprite when you attach the behavior to the sprite, and each sprite with that script can have unique properties. You can easily change the property values for each sprite in the behavior inspector, or you can access and change the properties dynamically during runtime with scripting.
For example, you have several shapes or characters you want to animate. They all need to move, or change size or change rotation or all of those things. They may need to have a state like "on" or "off." Instead of writing separate scripts for each of those, you can write one script and define multiple properties and set each sprites values. You would include a script like this in a sprite behavior.
on getPropertyDescriptionList
list = [:] --this defines an empty property list
addProp list, #phorzmove, [#comment:"horizontal speed", #format:#integer,
#range:[#min:-10, #max:10], #default:0]
addProp list, #pvertmove, [#comment:"vertical speed", #format:#integer, #range:[#min:-10, #max:10], #default:0]
addProp list, #protation, [#comment:"rotation angle", #format:#integer, #range:[#min:0, #max:360], #default:0]
addProp list, #pscale, [#comment:"scale amount", #format:#integer, #range:[#min:0.1, #max:2], #default:1]
return list --this line is VERY important
end getPropertyDescriptionList
Each propery begins with a "p" to distinguish it from other variables. We use symbols to save space in RAM. The #comment field shows what prompt you want in the dialog box, so you or a user will know what parameter they are adjusting. The #format field sets the type of the item that goes in that field--an image? an integer? another symbol? a list? The #range field is optional. If you don't include it, you get an empty field to type in. If you do use it, you have two choices--you can include a min and max value, which creates a slider for that parameter (not a slider on your screen), or you can include a linear list of possible values, which creates a drop down box for that parameter.
You access those values like any other property. If you are using the behavior on a sprite, you can just use the pvertMove like any other variable:
sprite(spriteNum).locV = sprite(spriteNum).locV + pvertMove
and the value for pvertMove will be dependent on the sprite you choose. If you are accessing it or setting it from another script on the frame or other sprites or movie, you would use dot syntax
someVariable = sprite(3).pvertMove
These values will revert to the default value whenever you leave the sprite.
If you need to save values for the life of the movie, you are better off with
creating an object with parent child scripting.
Arrays and computer processing
A list in computerese is usually called an array. Director calls it a list, but you should get comfortable with the word array if you plan to continue programming. A list is a variable, and like a variable it must be defined before you can use it, it can be local or global and you can change the value of that variable in a variety of ways. A list, however, contains more than one value. A variable can contain one string, one numerical value, one symbol, or one other variable. Lists can contain an unlimited number of items with different values, and for this reason it is sometimes referred to as a supervariable or multipart variable.
In most programming languages, a list can contain only one data type: string, numerical value, symbol, list, or variable. Lingo can teach bad habits because it will let you mix data types in a list. That is convenient if you want to store a bunch of different pieces of information about someone (name (string), high score (numerical value), hobbies (list)), but just remember that that convenience is unique to Lingo. Don't try this in Javascript or C++ . . .
List are an efficient way of managing information. It you use many variables,
the computer searches around for where it put them all in RAM. The list variable
points to the address of the first item in RAM, and all of the other items of
the list are located one after another in RAM, easy to find. (A string essentially
is a list, too--each letter is in the next location in RAM, and in lingo you
would access a character at a particular position by the property char -- so
the fifth letter of the string "Hello World" would be accessed as
member("Hello World").text,char[5] .)
We use lists to streamline code -- an array can eliminate the need for multiple copies of a behavior. We use lists for slide shows or sound or movie play lists, which helps us react dynamically to user events in one frame instead of building multiple frames. We use lists to define and keep objects with their properties (in either property lists or using the getPropertyDescriptionList command). We can also use lists of lists to create databases of information for games or for company information programs or for user information.
This is described in detail in Chapter 16. I'll only summarize here.
There are two types of lists: linear lists and property lists. Linear lists included a list of items, property lists include items and ONE property linked to that item. You can have a list of foods ["carrots", "apples", "pasta", "cheese", "sausage"] or a list of foods and their categories [[#carrots:"vegetable", #apples:"fruit",# pasta:"grains", #cheese:"dairy", #sausage:"meat"]. The # sign denotes the item as a symbol. Since only item properties change in a property list, not item names (if you want to change an item name you have to delete the item and than add a new one), item names are usually denoted as symbols since they take up less room in ram than strings.
Lists, being variables, are defined the same way. The above lists could be
defined with the following statements:
foodList = ["carrots", "apples", "pasta", "cheese",
"sausage"]
foodPropList = [#carrots:"vegetable", #apples:"fruit",#
pasta:"grains", #cheese:"dairy", #sausage:"meat"]
They can be local or global, and as with variables you would have to include
the line
global foodList in the handler where you define the list and before you try
to access the values from that list in any other handler. You can also initialize
a list empty, and dynamically add to it later
foodList = [ ] or foodPropList = [ : ]
Lists can be accessed in several ways. Refer to the class handout or the lexicon in the book for all the syntaxes. You can just use the list and it's index number
thisValue = foodList[3] or
put foodList[3] --in the message window
or you can use the functions getAt to return the value at a particular index
and getOne to return the index that has that value.
foodList.getAt(3) would return "pasta"
foodList.getOne("pasta") would return 3
or you can use the functions getProp or getPropAt or just dot syntax on a property
list:
foodPropList.getPropAt(3) would return "grains"
foodPropList.getProp(#pasta) would return "grains"
foodPropList.pasta would return "grains"
Changing information in lists
In a linear list, just reassign the value.
foodList = ["carrots", "apples", "pasta", "cheese",
"sausage"]
if you use the statement foodList[4] = "yogurt" then the new foodlist
is
["carrots", "apples", "pasta", "yogurt",
"sausage"]
you can also use the command setAt:
foodList.setAt(4, "yogurt")
In a property list you can only change the property.
foodPropList = foodPropList = [#carrots:"vegetable", #apples:"fruit",# pasta:"grains", #cheese:"dairy", #sausage:"meat"]
the statement: foodPropList.apples = "vitamin" gives us a new list
of
[#carrots:"vegetable", #apples:"vitamin",# pasta:"grains",
#cheese:"dairy", #sausage:"meat"]
you can also use the setProp command
foodPropList.setProp(#apples, "vitamin")
Use the addAt command to add to a linear list at a particular index. Use the append command to add to a linear list at the end. Use the add command to add to a sorted list in the right positon, or to add to an unsorted list at the end.
Use the deleteAt command to delete from a particular index in a list, and
the deleteOne command to delete a particular value from the list (if you don't
know the index). Use the deleteProp command to delete and item and its property
from a property list.
sort(foodList) or foodList = foodList.sort would alphabetize the list (or put it in numerical order if it were a list of numbers).
count(foodList) or foodList.count would return 5--the number of items in the
list. count(foodPropList) would also return 5.
Chapter 19 and Lingo Lexicon in Director 8 Demystified
Example files:
Director files: parameter example
(for getPropertyDescriptionList), parent
child example and parent
child example 2.
Zipped file examples2.zip (containing all
three)