Click to go to the home page.

See Also
"Script Writer" Movie Script
wfsWriteMultiSprite
wfsWriteElement
"Dynamism" Movie Script

 

Site Nav

css drop down menu by Css3Menu.com

Script Writer wfsWriteMultiSpriteFamily Handler

wfsWriteMultiSpriteFamily (managerNameOrSpriteNumToCopy, doNotCreateNewMembers)

Click to go to top of section. Function

wfsWriteMultiSpriteFamily generates and returns handlers that you use to create a dynamic copy of a static family of multi-sprites. You call wfsWriteMultiSpriteFamily from the Director Message Window while the movie is running and the target family is instantiated like so:

put wfsWriteMultiSpriteFamily(managerNameOrSpriteNumToCopy, doNotCreateNewMembers)

Lingo code is then output to the Message Window which you copy and paste into a movie script.

wfsWriteMultiSpriteFamily will only write code for elements that are currently instantiated in the static model family you aim it at.

The wfsWriteMultiSpriteFamily handler is in the "Script Writer" movie script.

Click to go to top of section. Parameters

managerNameOrSpriteNumToCopy is an integer or string. If it is an integer, it is the spriteNum of the Manager of the multi-sprite you want to start the family copy at. If it is a string, it must be the name of the multi-sprite you want to start the family copy at.

doNotCreateNewMembers determines whether, when the family is created, new members are created or whether members used by the static version are used. If you specify any integer value at all for this parameter, new members will not be created. If you omit this parameter altogether, or specify 0 or VOID, new members will be created.

Click to go to top of section. Return Value

Code is returned by wfsWriteMultiSpriteFamily

wfsWriteMultiSpriteFamily returns the handlers necessary to create and initialize a family of multi-sprites.

If the family you aim wfsWriteMultiSpriteFamily at has n multi-sprites in it, then n+1 handlers are generated. The first one that appears in the message window is the handler you call to generate the family. It takes no parameters. It contains calls to the other n handlers generated by wfsWriteMultiSpriteFamily. The latter n handlers have been produced by wfsWriteMultiSpriteFamily making calls to wfsWriteMultiSprite, ie, one for each multi-sprite in the family.

The form of the name of the first handler output by wfsWriteMultiSpriteFamily is as follows. It starts with "wfsCreate". Then it contains the name of the multi-sprite you aimed wfsWriteMultiSpriteFamily at. Characters that are illegal in handler names are stripped out. Then it contains the symbol "E". Then the sprite channel in which the manager was located. Then the frame number in which wfsWriteMultiSpriteFamily was executed. Finally, it contains the string "Family". So, for example, if wfsWriteMultiSpriteFamily was aimed at a manager named "main window" that was in sprite channel 10 and frame 572, then the first handler would be named wfsCreatemainwindowE10F572Family.

The other n handlers are named according to the naming conventions of wfsWriteMultiSprite, which are the same as the above except "Family" is not appended at the end.

A property list is returned by code generated by wfsWriteMultiSpriteFamily

Now let's discuss what is returned when you run the first handler generated by a call to wfsWriteMultiSpriteFamily.

A dynamic multi-sprite family is created and a property list is returned. Or it returns 0 if there weren't enough available dynamic channels to create the full family and, in that case, it does not create anything. Each property name in the returned property list is the spriteNum of a manager in the newly created family; each property value in the returned property list is the name of a newly created manager. So, for instance, if the created family consisted of just one multi-sprite, and the dynamic multi-sprite was managed by sprite 345 and the name of the newly created dynamic multi-sprite was "A", then the returned property list would be [345:"A"]. The order in which the property list lists the dynamic multi-sprites reflects a depth-first traversal of the family tree.

Recall that the names of simultaneously instantiated multi-sprites must all be different. So when you create dynamic multi-sprites, their names will not be the same as the names of their corresponding static models. wfsWriteMultiSpriteFamily returns code that names dynamic multi-sprites according to the following rules.

Multi-sprites generated by code returned by wfsWriteMultiSpriteFamily have names that have three components separated by the "+" symbol. So these names are not really appropriate for display to the user. The first component is the name of the static model multi-sprite. The second component is the name of the multi-sprite at which you aimed wfsWriteMultiSpriteFamily. The third component is a number indicating the number of dynamic copies of this family.

In the above graphic, the lines joining multi-sprites indicate parent-child relationships: r and s are the names of two multi-sprites, and q is the name of the multi-sprite that is the parent of r and s.

If we were to point wfsWriteMultiSpriteFamily at q, it would generate code to reproduce the family. When we ran that code, we would get a dynamic family named as in the first copy of the family. If we ran the generated code again, while the first copy was still instantiated, we'd get a second family named like the multi-sprites in the second copy of the family.

Suppose q has the "Open a Window" behavior attached to it, and that behavior opens window r. The wfsWriteMultiSpriteFamily handler is smart enough to write code so that q+q+1 will open r+q+1. WFS adjusts links within the family.

It does not adjust links outside the family, though. For instance, if an "Open a Window" behavior was attached to q and the behavior was supposed to open x, some multi-sprite not in the family, then q+q+1 would open x also.

Click to go to top of section. Example

You can see an example of the use of wfsWriteMultiSpriteFamily in the feature demo source code in scene 10. When you click the gray text that says "create multisprite family", a dynamic copy of the family is generated. Let's look step-by-step at how this was done. The steps below follow the same order as the generic steps in using any of the three Script Writer handlers.

  1. We make sure the movie has a copy of the "1: prepareMovie", "Dynamism", and "Script Writer" movie scripts in a cast.

  2. We edit the value of gWFSLastStaticSpriteChannel in the 'initializeDynamism' handler of the "Dynamism" script, as per instructions, if you haven't already. gWFSLastStaticSpriteChannel determines how many sprite channels in your movie are allocatable for dynamic sprite creation. In the feature demo source code, gWFSLastStaticSpriteChannel=84, ie, the drag and drop sprite with the highest channel number is sprite 84 (in scene 10). The feature demo contains 1000 sprite channels. So there are 1000 - 84 = 916 channels that are allocatable for dynamic sprite creation.

  3. The static model of the family was created in the Score.This is quite an extensive family. It consists of about 70 sprites and many windows and menus. If you start the movie and then navigate to scene 10 in the source code, and then stop the movie, you are in the right spot.

  4. Start the movie and navigate to a frame where the static model of the target family is instantiated. In the case of this example, we navigate to scene 10 in the movie.

  5. Now we run wfsWriteMultiSpriteFamily from the Message Window. It takes two parameters. The first parameter is the name of the manager at which we want to start the family copy ("main window") or this manager's spritenum (10). Either will do. The second parameter determines whether the dynamic family's members will be the same as the static model's members, or whether the members will be new copies of the static model's members. If you don't need to create new members, it's best not to because they take up extra resources. We want most of the dynamic sprites to use the same member as the sprites in the static model, so the second parameter will be 1, and we will edit the generated code, later on, concerning the sprites whose members we want to be new copies. So we type

    put wfsWriteMultiSpriteFamily(10, 1)

    in the Message Window and, consequently, we see many handlers appearing in the Message Window. It takes a while for all the code for this family to appear in the Message Window. Wait for it.

    wfsWriteMultiSpriteFamily will first output a handler named something like "wfsCreatemainwindowE10F570Family". This first handler is the one we will call to produce a dynamic family. Read the Return Value section of this document for the rationale concerning how the handler is named. Other handlers will also be produced: one for each multi-sprite in the family.

  6. All the generated handlers were copied from the Message Window and pasted into a movie script. In particular, they were pasted into the movie script named "generated1" that is in the WFS 4 cast. I tend to keep the handlers generated by the Script Writer in one movie script, just so that I know where they all are.

  7. Now that we have the generated code in a movie script, we may wish to do a bit of customization of the generated code. Why and how? Well, we ran wfsMultiSpriteFamily(10,1). The second parameter means that the members of the dynamic family will be the same ones as the members of the static model family. But there's one sprite which we want to have its own new member. Note that when you click "create multisprite family" to create a new family, the name of a dynamic multi-sprite is displayed at top left of the window. If this text used the same member as the static model used, then the text of the name would have to be the same among sprites that use that member. Because sprites that share the same text/field member necessarily display the same text. But we want different dynamic multi-sprites to display their own name.

    We note that that sprite 13 in scene 10 is the sprite that displays the name of the window. We also note that sprite 13 has a member called "main window label".

    Now we open up the source code of the 'generated' movie script in the WFS 4 cast. Search for "main window label" in that script. We see that "main window label" occurs in the below code:

    theNewSpriteNum = wfsCreateSprite(["main window label", "7: Normal Menus", 36, 100, 294, 32, 78, 38])

    --parameters: [member, cast, ink, blend, width, height, locH, locV, doNotCreateNewMember]

    --If you don't specify a value for doNotCreateNewMember, then a copy of the member will be created.

    --If you specify any value for doNotCreateNewMember, then the sprite will be created using the same
    -- member.

    The thing to note is that no value for doNotCreateNewMember is specified. The comments indicate that the parameter list can take 9 things, but there are only 8 things in the line with the call to wfsCreateSprite. Note also that all the other lines that call wfsCreateSprite have 9 things in the parameter list. I edited the above line, deleting the "1" specified elsewhere for the doNotCreateNewMember parameter. Because when the "main window label" sprite is created, I want it to have its own member.

    For more information on editing code produced by the "Script Writer" handlers, read the section entitled "Editing code generated by the Script Writer handlers".

  8. We need to write some Lingo that calls the "wfsCreatemainwindowE10F570Family" handler. If you look at the gray text that says "create multisprite family " in scene 10 of the feature demo, you see it has attached to it a behavior called "tester". If you open up that behavior in the script window, you see the below code:

    on mouseup me

      if the clickon =spritenum then

        --wfsCreatemainwindowE10F570Family was generated by the

        --wfsWriteMultiSpriteFamily handler in the Script Writer movie script.

        --wfsCreatemainwindowE10F570Family creates a dynamic copy of

        --the family of multi-sprites rooted by the manager named "main window"

        --located in channel 10, frame 570.

        --wfsCreatemainwindowE10F570Family was generated via

        --put wfsWriteMultiSpriteFamily(10, 1)

        --typed in the Message Window while the movie was playing and the

        --playback head was in a frame where the target (static) family was

        --instantiated, namely frame 570.

        theBigList = wfsCreatemainwindowE10F570Family()

      end if

    end

    When you click the text that says "create multisprite family", the above handler runs, which calls "wfsCreatemainwindowE10F570Family" and a dynamic family is created.

  9. As you can see if you run the movie and navigate to scene 10, you can click "create multisprite family" repeatedly and, each time, a new family will be created as long as there are enough dynamic sprite channels to create the whole multi-sprite. If there aren't, "wfsCreatemainwindowE10F570Family" will return 0.

  10. Note also that if you click the blue button at top right of scene 10 windows, the family is destroyed. The blue button has a behavior attached to it called "Destroy Family On Mouseup". That behavior contains the below handler:

    on mouseup me

      if the clickon = spritenum then

        cursor 0

        theManager=sprite(spritenum).wfsGetMyManagerSpriteNum()

        theResult=wfsDestroyMultiSpriteFamily(theManager, 1)

      end if

    end

    See the documentation on the destructors for more information on using destructors. WFS does garbage collection of all dynamic sprites at the end of the movie, ie, they are all destroyed and garbage collected, but you can use the destructors during the movie to free up dynamic channels.

Note that if you change the static model, you need to call wfsWriteMultiSpriteFamily again to regenerate the code. Otherwise, the generated code will produce the old version.

You can delete the "Script Writer" handler from the cast when you are finished generating code. That is all it does.

You can also delete the static model from the Score when your project is all finished, if you want. The code that wfsWriteMultiSpriteFamily generates does not depend on the static model being present in the Score. But don't delete the cast members of the static model. The code generated by wfsWriteMultiSpriteFamily needs those cast members.

But it is a good idea to keep a copy of your project that has the static model in it and the Script Writer in it also, so that you can edit it easily later on, ie, regenerate the code and so on.

 
Click to go to the home pageScript Writer wfsWriteMultiSprite Handler