Director Tutorials


Understanding Behaviors -
Creating a Parameter Dialog Box

Behaviors are script objects, and like every other object in Director (like sound, text, images), they can have their own properties. Behaviors are most useful when their properties can change each time they are applied. This is because they are flexible and can be reused from one project to the next without rewriting the Lingo. These properties are also known as parameters for the behavior. See Using me and other parameters in Lingo.

First, let's look at a relatively simple navigation behavior that prompts the user for the marker and movie to Director to when a sprite is clicked.

Navigation behavior
-- define properties
pMarker, pMovie  

mouseUp me
go to frame (pMarker) of movie (pMovie)

on getPropertyDescriptionList
-- create an empty property list called pList
set pList = [:]
addProp pList, #pMovie, [#comment : "Choose \
destination movie:"
, #format :#string, #default : \
"movie name here"
addProp pList, #pMarker, [#comment : "Choose \
", #format : #string, #default : \
"marker name here"
return pList

Note: The Continuation symbol ( \ ) allows us to continue statements onto the next line without breaking them into two separate statements.

We start the script by defining the properties (parameters) for the behavior - pMarker and pMovie. Using naming conventions, I have given the property names words that define what they represent as well as placing a p at the start to represent property.

Then we have our regular mouseUp handler followed by a statement that refers to our two parameters. We then use the getPropertyDescriptionList handler. This handler describes the information for which the user will be prompted. The data will be stored in a property list.

The list contains the following:
#comment is used for the description of the parameter in the dialog box that will appear
#format is the value type of the parameter, which in our case is an string #integer for both the marker and movie parameters
#default is the value that appears in the dialog box when it first appears

If you wanted to add a description to the behavior that appears in a behavior's description pane in the Behavior Inspector, then you can use the getBehaviorDescription handler. The following may be added to the navigation behavior we just wrote above.

on getBehaviorDescription me
return "Navigation behavior between movies"

The behaviors in the Library Palette will usually have a further handler, the getBehaviorTooltip. It is used in exactly the same way as the getBehaviorDescription handler, and it adds a rollover tooltip for users selecting behaviors from the library.

Below is a wait until finished playing video behavior. It has 2 properties, pVideoSprite and pDuration.
represents the sprite channel the video is placed.
is the duration property of the video.
Both properties are given a descriptive name to represent what they represent and have a 'p' prefix to indicate they are properties.

-- define properties
property pVideoSprite, pDuration

-- event handlers
beginSprite me
pDuration = sprite(pVideoSprite).duration

on exitFrame me
if sprite(pVideoSprite).movieTime < pDuration then
-- video paused or still playing
go the frame
-- video finished go somewhere else (next frame)
go the frame + 1
end if

-- prompt user for parameter value
getPropertyDescriptionList me
pList = [:]
pList[#pVideoSprite] = [#comment: \
"Select the video sprite"
pList[#pVideoSprite][#format] = #integer
pList[#pVideoSprite][#default] = 1
return pList

As you can see the getPropertyDescriptionList handler uses a list called pList but was written in a slightly different way to our first example. Following the first example the list could be written as:

on getPropertyDescriptionList
set pList = [:]
addProp pList, #pVideoSprite, [#comment: \
"Select the video sprite:"
, #format:#integer, \
return pList

For more examples and information on getPropertyDescriptionList see the Behavior Initializers technote