Variables in Director

October 16, 1997
by Alex Zavatone

When getting started in Director and learning lingo, especially from a non-programming background, there are so many areas to start and not a clear path of what to learn when and how does everything fit together. Part of this puzzle are the things that store data -- variables. How many different types are there, what type of data goes in which variable, are any variables really slow, etc, etc... Once you learn the variable basics, you've got a good part of the fundamental information under your belt that is required for every Director programmer.

Variable Types

The Integer Variable

Among the fastest of Director's variables, the integer contains well... integers (whole numbers). The values that an integer variable can contain are the values between the results generated by the two lines below:

put the maxinteger -- (maximum positive) put the maxInteger + 1 -- (maximum negative)

Integers and floating point variables can have their values changed through numerical operators: typical math functions like +, -, *, /, mod, and so on.

The Floating Point Variable

Floating point can be described as any decimal value. 1 is not a floating point variable but 1.0 is. Though modern processors have very fast floating point units, use of floating point when it is not needed can slow your lingo down by up to 2.8 times - that's a 280% performance hit! Floating point variables can have much higher and lower values assigned to them but there is no function which will return the maximum allowed value. If you attempt to assign a value past its max or min, you will get the result of INF or -INF. This indicates that your variable's value is so large that it is approaching positive or negative infinity.

The String Variable

Strings can be summed up as anything that will appear within quotes, or simply text. The amount of information that a string can contain is well over a million characters but I haven't been able to find the upper limit! Data within strings can be accessed directly by the word, character, item or line. This type of access is called "text chunking" and is used as described below:

put char 4 of myString put char 4 to 10 of myString put item 5 of myString put line 3 of myString put word 3 of myString

Strings and floating point variables are both slower than integers but provide similar performance. If you plan on holding a value within a string, then it must be converted back to an integer or a float (floating point) before performing numerical operations on the value. This is done through the value() function.

set myString = "3 + 5" put myString -- "3 + 5" put value(myString) -- 8

Strings can be combined by using the & function to concatenate two strings, like so:

set myString = "My name is " set myName = "Zav." put myString & myName -- "My name is Zav."

The Symbol Variable

Symbols are interesting variables in that they usually don't contain anything. They just exist as a data type or serve as a tag to locate other information. Symbols provide the speed of integers with the descriptive power of strings. In a property list, symbols are a great method to identify data by name instead of position.

set myErrorState = #noError ... if myErrorState = #error then PostErrorMessage set myList = [#age: 32, #birthday: 1, #birthMonth: 12, #birthYear: 65, #rank: "Geezer" ] put getProp( myList, #rank)

The List variable

Lists are Lingo's version of arrays and are both a powerful and complicated variable type. Though lists are slower than other variables, the functionality that they provide can not be performed with any other variable. Lists are able to exist in two forms, linear and property.

Linear lists have data that can be accessed by the position it holds within the list. Property lists can do that as well, but each value has a property or tag that is associated with the data so that you can grab the data from within the list by asking for the data's tag. In property lists, the property tag for each value can be any data type. It usually makes the most sense to use a symbol, string, integer or a float. Property lists can be used to implement look up tables in Lingo.

An important note is that the speed of accessing the list is dependant upon the basic speed of the list + the speed of the data it contains. Using the Sort function can greatly improve the speed of accessing the data, and once the list is sorted, it will maintain the sort as you add or delete items from the list. Both property lists and linear lists can contain lists inside them. These types of lists are often used for x/y coordinate systems.

Linear List

set myList = [1, 2, 4, "No Caffe Latte Next 20 Miles", #noError ]

Property List

set myList = [#age: 32, #birthday: 1, #birthMonth: 12, #birthYear: 65, #rank: "Dinosaur" ] put getProp( myList, #rank) -- "Dinosaur"

Nested Linear List

set shipCoords = [[[1,2],[3,4]], [6,3],[4,5]]]

Nested Property List

set coords = [ #Team1: [[1,2],[3,4]], #Team2: [6,3],[4,5]]

Boolean variables

True and False are the only booleans in Director and they equate to the integer values of "anything that is not zero or void" and "zero or void". 1 and 0 are often used to represent True and False since 1 = True and 0 = False.

Objects

Variables can also contain an object which is the result of taking a script, treating it as the blueprint to make an often complex handler and data structure and placing the result into a variable. Objects are normally created by issuing a new command on the script containing the object blueprint and then the new handler will return the datatype which gets put in to a variable. The argument to the new handler must be the script you are creating (instantiating) the object from. When inside the handler, this becomes the me variable. Like so:

--- Script 1 contents: on new me return me end --- end script --- Command to create an object set myObject = new(script 1)

objects normally contain properties which are explained in the section on variable scope.

Misc Variable Types

Many of Director's contents can be assigned to variables. A variable can contain the media of a cast member or even the castmember itself. It can also be the structure that represents a movie in a window or the stage movie itself. By setting a variable to a "non standard" data type and displaying the contents with a put command, put normally displays the memory scructure and number of properties that that variable contains which are accessable via lingo. This is similar to the results you get when displaying an object variable by using put. Though initially hard to understand, diving into these fearsome waters can result in many wondrous discoveries.

Void variables

Void is not really a variable type but a variable value. Void simply means that this variable contains nothing. This is not the same as the integer value of 0. They will equate to the same value but are essentially different. Before a variable is given a value, it is void. Commonly, errors occur when attempting to use an unreferenced global within a new handler. If the global variable exists but is not referenced with the global command, then it is treated as a local and it's contents are nothing or Void.

Variable scope

For lack of a better term, where the variables exist and how they are accessed is called scope. Scope is kind of an odd concept that simply adds structure to the variables. When you put items in your fridge, not everything is tossed in without care. Your items are organized. Veggies are in the crisper and you must open the crisper to get to them. This is sort of what scope is like.

Global variables are scoped so that once they are declared, any routine in Director can access and change their values by simply "referencing" the global again and then accessing it. An important fact to note is that when moving from movie to movie but running within one shockwave or projector session all global variables are preserved between the movies. You can bring data from one movie to another!

Local variables are scoped so that they are only accessable within the handlers that they are declared in. When the handler finishes, they go away.They can be passed on as arguments to functions and handlers but they will get passed to the local variables in the destination handler which will take on their values. ShowGlobals and ShowLocals are the commands to issue to view the values of the locals or globals. Remember that when using showlocals, it must be issued from where the locals exist or you'll get no output in the message window.

For the ultimate in organizing your data, variables can by declared as properties. These properties have the benefits of locals but with the fact that they can persist and stay around after the handler has finished. This is because properties are normally found in parent scripts and these parent scripts are used to create objects. Once the object is created from the parent script, the properties within exist until the object is disposed of. Kinda neat and very useful. In Director 6, properties also exist within behaviors that can be added to sprites.

Oddities

There are several beasties that exist outside of the the variable types and scopes and have their important places in any discussion regarding Director and variables. These are the actorList and the windowList. The actorlist is a linear list structure which will not get cleared on a clearglobals. It was meant to contain objects and on every frame advance, issue an enterframe event to all the objects within. While this is nice, multiple updatestages are also issued as well - whether you want them or not. The actorList can contain whatever you want though - not just objects. Use it as a container to hold the data you do not want cleared on a clearGlobals!

Like the actorList, the windowList was meant to hold the index of windows but can easily hold whatever you put in it! Credit here goes to Dana Nuon for discovering this functionality. The windowlist also persists outside of global space, between movies AND there is a very special bit of extra functionality in that every window in the windowList contains its own actorlist! These can be the next to ultimate containers for hiding data if you so desire. The ultimate is to stuff data into a parent script blueprint without creating an object from it. Unfortunately, that's a bit beyond the scope of this article. :]

In summary, once you've gotten a good understanding of the variable data types and variable scope, then you'll have a better idea how to proceed with your projects and have some fun discovering new areas within Director.

A Director user since 1987, Alex (Zav) Zavatone has worked on the engineering teams for both Director and Shockwave, 4, 5, 6 and 7. Recent investigations find him developing foundation classes for Director with asynchronous process management and other life threatening activities. In its early days, he had something to do with this Internet thing known as "DOUG". A noted ne'erdowell, slacker and laggard, Mr. Zavatone is nonetheless is trusted by children, small animals and the elderly. In his spare time, Mr. Zavatone rehabilitates lame desert trout.