GetPropertyDescriptionList

This is an author-time only event that is sent to a behavior when either:

• You drop the behavior member onto a sprite on the Stage or in the Score
• You drag the behavior member into the behaviors panel of the Property Inspector
• You select a sprite behavior in the behaviors panel of the Property Inspector (in this case, the #getPropertyDescriptionList will be sent continuously until the selected sprite loses focus)
• You open the Behavior Parameters dialog for a sprite behavior by double-clicking on the behavior in the behaviors panel of the Property Inspector or the Behavior Inspector

Its purpose is to return a property list to Director, to enable Director to display the Behavior Parameters dialog. The Behavior Parameters dialog allows you to set the initial parameters for the current instance of the behavior. The choices made in the Behavior Parameters dialog are stored in the scriptList of the sprite.

Example

It is easiest to explain this with the help of an example. Here is a very simple navigation behavior:

  -- Go to Frame X --
 
  property targetFrame<br>
 
  on mouseUp me
    go targetFrame
  end mouseUp<br>
 
  on getPropertyDescriptionList(me)
    vPropertyList = [:]
 
    vPropertyList[ \
  #targetFrame] = [ \
   #comment: "Go to which frame on mouseUp?", \
   #format:  #integer, \
   #default: the frame]
 
    return vPropertyList
  end getPropertyDescriptionList

When you drop this on a sprite or on the Stage, you should see the following modal dialog box appear:

http://nonlinear.openspark.com/wiki/getPDL_simple.jpg

Format

The property list returned by the getPropertyDescriptionList() handler must have the following format:

 [#propertyName: <definition of #propertyName>, ...]

The definition of each property must have the following format:

 [#comment: <string description which will appear in the Behavior Parameters dialog>, \
  #format:  <symbol>, \
  #default: <default value to be displayed the first time the Behavior Parameters dialog opens>]

It can also contain an optional property: #range. The value of range must be a list. If it is a linear list, the elements it contains will be displayed in a popup menu, from which you can select a value. If it is a property list, then it must have the format:

 [#min: <float or integer>, #max: <float or integer>]

The value of #min must be less than or equal to the value of #max. This will display a slider to allow the user to select a number between the two limiting values.

Here are examples of the #range property:

  property direction
  property angle<br>
 
  on getPropertyDescriptionList(me)
    vPropertyList = [:]
 
    vPropertyList[ \
  #direction] = [ \
   #comment: "Turn", \
   #format:  #symbol, \
   #range:  [#clockwise, #counterClockwise], \
   #default: #clockwise]
 
    vPropertyList[ \
  #angle] = [ \
   #comment: "Degrees per frame?", \
   #format:  #integer, \
   #range:  [#min: 0.0, #max: 360.0], \
   #default: 0 ]
 
    return vPropertyList
  end getPropertyDescriptionList

http://nonlinear.openspark.com/wiki/getPDL_range.jpg

Layout

Because of the complexity of the list returned by getPropertyDescriptionList(), developers have adopted a variety of different ways of laying out the list in code. The layout suggested here has the following advantages:

• The name of each behavior property appears on a separate line, flush with the left-hand margin. It is easy to run your eye down the list of property names.
• Each property definition appears as a separate chunk. It is easy to duplicate a chunk and use that as the template for the next property
• Each definition property appears on a separate line.