Customize getPropertyDescriptionList dialogs

November 2, 2000
by Reda Choukairi

After working on Director movies that use large libraries of resources, such as graphics and other types of Director Cast members, one starts to appreciate ways to sort through these large lists of library materials. Behaviors in Director are widely used in the context of these large library resources, such as Cast member libraries, so one starts to think of ways of saving time and effort by customizing the way behaviors are built and used. This article discusses a particular creative approach that can be timesaving for very large libraries.

Scenario

To get to the heart of the matter, let's take a simple rollover behavior. Easy to create and implement, it may ask the end user to point to only one thing: what graphic member will be used to replace the member of the current sprite when the mouse rolls over it.

Problem

Now consider the fact that the Director movie in which this rollover behavior resides contains references to a huge number of possible rollover graphic Cast members. Without a method and criteria for limiting this seemingly endless list of choices, the end user would be faced with an alarmingly large number of possible choices, most of which are likely to be invalid as far as the end user is concerned.

Solution 1

Use lists and handlers to customize the getPropertyDescriptionList method. Call a handler that returns a list of Cast members as the value to the #range property of the getPropertyDescriptionList method.

Example

on getPropertyDescriptionList

description = [:]
addprop description, #pRolloverMember, [#default:"none", #format:#String, #comment: "Select which Castmember:", #Range: GetCastmemberList() ]

return description

end

on getCastmemberList

  castList = []
  repeat with x = 1 to (the number of members of castlib "ButtonGraphics")
    if castLib("ButtonGraphics").member(x).type = #bitmap then
      addAt CastList, castLib("ButtonGraphic").member(x).name
    end if
  end repeat

return castList

end

The custom handler, getCastMemberList(), could be set up to retrieve a list of Cast members based on many different criteria. As you might have noticed in the example above, the getCastMemberList() handler is hard-coded to retrieve a list of Cast members that are in the "ButtonsGraphics" cast library, and that are bitmaps. But you can design the handler to retrieve a list of Cast members based on any number of criteria.

A useful technique is to name the target items that you wish to sort, Cast members in this case, in such a manner that they can be identified right from their names. For instance, have all the graphic Cast members that are used as rollover states, or button states if you are making rollovers for buttons, to have a prefix of something arbitrary, like "bt-". With this requirement in place, you can have your custom handler look for any Cast member with a name that starts with "bt-", and sort through and retrieve a list of only "button" Cast members based on the prefix you created.

Solution 2

Build a modal Properties dialog box, using the MUI Xtra, such that the user can define criteria from a series of lists that would result in a specific set of possible values for the property in question.

Given the same rollover scenario, suppose we want the user of the behavior to be able to select not only which graphic to use as a rollover, but also what type of graphic (#bitmap, #vector, #Flash, etc.), and in what cast library the rollover graphic resides.

In contrast to the default Parameters dialog box, here is a sample modal Parameters dialog box generated by the MUI Xtra that accomplishes this task. The contents of the Cast member dropdown lists are generated by the values of the other two dropdown lists. This means that if there were no #bitmap Cast members in Castlib "Graphics", then the Cast member dropdown list would be empty.

Sounds like a handful, doesn't it? Well, thanks to Macromedia Director's quirky nature and MUI Xtra's less-than-perfect methods of implementation in Director 7, it is a handful. (See also Director 8's new method of using the MUI Xtra.) Nevertheless, one can achieve some successful results using the MUI Xtra to customize behaviors.

Here are some facts you should know about that make using the MUI Xtra with behaviors possible:

The runPropertyDialog handler gets called by the getPropertyDescriptionList handler, and receives the behavior's description property list from the getPropertyDescriptionList handler (see the documentation on creating behaviors).
Normally unspecified, the runPropertyDialog handler receives the values from the default Parameters dialog box, which appears when the author drags a behavior on a sprite.
If you specify, or "script" the runPropertyDialog handler in your behavior, you can explicitly assign values to the properties of your behavior. In so doing, the Parameters dialog box is overridden and does not appear, even if you try accessing it from the Behavior Inspector. This means you can create behaviors with properties of a fixed value that are not editable through the Behavior Inspector. This can be useful when you want to restrict the user's options.
Because you can explicitly assign a value to a behavior property, you can use any scripting method at your disposal to derive the value for your property. This opens up an opportunity to use the MUI Xtra.

The following code shows how you can override the default Parameters dialog box and explicitly assign a value to a behavior property. In this case, the property's value is set to the default:

property pInitialMember
property pRolloverMember
property pCastmemberType
property spritenum

on beginsprite me
pInitialMember = sprite(me.spritenum).member.name
pCastmemberType = sprite(me.spritenum).member.type
end

on mouseEnter me
sprite(me.spritenum).member = member pRolloverMember
end

on mouseLeave me
sprite(me.spritenum).member = member pInitialMember
end

on getPropertyDescriptionList

description = [:]

addprop description, #pRolloverMember, [#default:"none", #format: #String, #comment: "Select the Rollover graphic:",#range: getCastList(sprite(spritenum).member.type) ]
return description

end

on getCastList theType - this handler is relevant to "Solution 1" of this article.

  castList = []
  repeat with i = 1 to (the number of members of castlib "graphics")
    if member(i).type = theType then
      add castList , member(i).name
    end if
  end repeat

return castList

end

on RunPRopertyDialog me, defaultProps
put "me.spritenum (from RunPRopertyDialog) = " & me.spritenum
return defaultProps
end

The following chart gives a brief overview of the relationships between the key elements that are necessary to establish an MUI Xtra object that will successfully work with the behavior handlers.

Here is a summary of how the MUI Xtra works in conjunction with the RunPropertyDialog handler in a behavior, a custom-made callback handler, and a global variable storing the values of the properties of each component of the custom dialog box that you created with the MUI Xtra.

The MUI Xtra assigns a value to the behavior property by way of the runPropertyDialog.
The MUI Xtra object requires a callback handler to respond to events generated by the user.
Since you cannot reference any component of your custom dialog box (MUI Xtra object) but the one subject to the user event, you need a global variable to update and retrieve the values of those other components if you are going to have a modal dialog box that dynamically changes the values of its components.
- User events trigger the callback handler;
- The callback handler updates the global variable;
- The callback handler references the global variable in order to make changes to other components of the the custom dialog box.

What the MUI Xtra does NOT do

It is worthwhile to note that the MUI Xtra has a significant limitation. When creating a custom dialog box with the current version of the MUI Xtra, it is not possible to directly and arbitrarily reference the properties of each component in that dialog box. The MUI Xtra object returns a list of properties for a single component, be it a button or dropdown list for example, only during the occurrence of a user event, and only for the component that is subject to that event. The only way to gain access to the properties of the other components is save the values of their properties in a global variable, at design time.

The global variable is a list of the property values of all the components in the MUI's dialog box. If the dialog box is to be modal, the property values of components will affect each other. Since the MUI Xtra does not permit one to access values of all the components and compare them, we need to use this global variable and keep it updated in order to compare property values of different components in the dialog box.

The callback handler (a global handler that is scripted by the author, which defines what should happen for specific user events in the MUI's dialog box) is responsible for changing the property values of all the components of the MUI dialog box. The property values for these components are determined, in the case of a modal dialog box, by comparing the property values of more than one component. As mentioned before, the global variable stores these values for access by the callback handler. The callback handler is also responsible for keeping the global variable updated with the latest property values of all the components for future reference during the life span of the MUI dialog box.

Final Note

A detailed description of the implementation of the MUI Xtra is available and can be found in the resources listed at the end of this article. The important thing to remember is that one can explicitly assign a value to a behavior property in the RunPropertyDialog handler, thereby overriding the default Parameters dialog box. You can then take advantage of any scripting method at your disposal to derive the value of that property.

In the context of managing large libraries, as well as time management, it might be worth the effort to use the MUI Xtra even if it requires a certain level of complexity for such a specific task.

In this case, the MUI Xtra is only being used during authoring time. It would have to be removed from the completed .dir file in an efficient way that would not increase production time. Perhaps one way is to ensure that no references to the MUI Xtra are made when the movie is playing.

Resources

URL Links
Building your own dialog boxes with MUI Xtra
buildArticle.php?id=888

Creating dialog boxes from the MUI Xtra
http://www.macromedia.com/support/director/how/d7/MUI.html

Lingo in a Nutshell Bonus Chapter 21: Custom MUI Dialogs
http://www.zeusprod.com/nutshell/chapters/muixtra.html

Books
Lingo in a Nutshell, by Bruce Epstein. Published by O'Reilly and Associates.
Macromedia Director 7, by Gary Rosenzweig. Published by QUE Corporation.

A sample movie is available for download in Mac or PC format.

Reda Choukairi currently works as a Multimedia Developer for an online learning company. This mainly consists mainly of developing, maintaining, and updating a library of Behaviors, Director movie templates for shockwave content, and some authoring tools for production. Reda has completed an Associates degree in Fine Arts, and a Bachelor's degree in Graphic Design.