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
property
pMarker, pMovie  


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

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 \
marker:
", #format : #string, #default : \
"marker name here"
]
  return pList
end

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"
end

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.
pVideoSprite
represents the sprite channel the video is placed.
pDuration
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
on
beginSprite me
  pDuration = sprite(pVideoSprite).duration
end

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

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

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, \
#default
:1]
  return pList
end

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