Using Director > Behaviors > Customizing a behavior's property

 

Customizing a behavior's property

If a behavior's script includes an on getPropertyDescriptionList handler, Director lets users set the property's initial values from the Parameters dialog box. The behavior's Parameters dialog box opens in three circumstances:

After the user drags a behavior to a sprite or frame

When the user double-clicks the behavior in the Behavior Inspector dialog box

When the user clicks the Parameters button in the Behavior Inspector

The on getPropertyDescriptionList handler generates a property list that specifies these attributes of the property:

The default initial value

The type of data the property contains, such as Boolean, integer, string, cast member, or a specific type of cast member

A comment in the Parameters dialog box to describe what the user is setting

The definition of a behavior's property must include the property's name, default value, and data type and the descriptive string that appears in the Parameters dialog box. The definition can also include an optional specification for the range of values allowed for the property.

The name of the property comes first in the definition. The remainder of the definition is a property list that assigns a value to each of the property's attributes.

For example, to define the property movement as an integer that can be set to a value from 1 to 10 and whose default value is 5, use a phrase similar to this:

#movement: [#default: 5, #format:#integer, ¬
#comment: "Set motion to the right:", #range: [#min:1, #max:10]]

#movement is the property's name. A symbol (#) operator must precede the name in the property definition. A colon separates the name's definition and the list of parameters.

#default specifies the property's default value. This example sets 5 as the default.

#format specifies the property's type. This example sets the type as an integer. Some other possible types are Boolean, string, cast member, event, and sound. For a complete list of possible values for #format, see on getPropertyDescriptionList in Director Help or the Lingo Dictionary.

#comment specifies a string that appears next to the parameter in the Parameters dialog box. This example makes "Set motion to the right" the comment that appears in the Parameters dialog box.

#range specifies a range of possible values that the user can assign to the property. Specify the possible values as a list.

To specify a range between a minimum and maximum number, use the form [#min:minimum, #max:maximum]. The example sets the range from 1 to 10. When the range is between a maximum or minimum number, the Parameters dialog box provides a slider that sets the value.

To specify no range, omit the #range parameter. If the property's definition doesn't include #range, a text entry field appears for the user to enter a value in the Parameters dialog box.

To specify a set of possible choices, use a linear list. For example, the list [#mouseUp, #mouseDown, #keyUp, #keyDown] makes these four events possible choices for a parameter. When you specify values in a linear list, the choices appear in a pop-up menu in the Parameters dialog box. (For this example list, you need to specify #format: #symbol for the list to display correctly.)

As another example, this statement defines the property whichSound:

addProp description, #whichSound, [#default: "", #format:#sound, #comment: ¬ 
"Which cast member"]

The value #sound assigned to #format provides a pop-up menu in the Parameters dialog box that includes every sound cast member available in the movie.

If the behavior includes a command that plays a sound, this property can be used to specify a sound cast member to play. For example, if the user chooses Growl from the pop-up menu in the Parameters dialog box, the statement puppetSound whichSound would play the sound cast member Growl.