Click to go to the home page.

See Also
"Script Writer" Movie Script
"Dynamism" Movie Script


Site Nav

css drop down menu by

Script Writer wfsWriteMultiSprite Handler

wfsWriteMultiSprite (managerNameOrSpriteNumToCopy, doNotCreateNewMembers)

Click to go to top of section. Function

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

put wfsWriteMultiSprite(managerNameOrSpriteNumToCopy, doNotCreateNewMembers)

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

wfsWriteMultiSprite will only write code for elements that are currently instantiated in the static multi-sprite you aim it at.

The wfsWriteMultiSprite 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 must be the spriteNum of the Manager of the multi-sprite you want to copy. If it is a string, it must be the name of the multi-sprite you want to copy.

doNotCreateNewMembers determines whether the generated code will create copies of the members of the multi-sprite you want to copy, or whether the generated code will use the same members used by the multi-sprite. If you do not specify this parameter then new copies of members will be created. If you specify any integer value at all for this parameter, no new members will be created when the generated code is run.

Click to go to top of section. Return Value

wfsWriteMultiSprite returns the code necessary to dynamically create the multi-sprite you aim wfsWriteMultiSprite at.

When you paste that code into a Movie Script and run it, a dynamic multi-sprite is created and the spritenum of the newly created manager sprite is returned. Or, if there aren't enough available sprite channels to create the entire multi-sprite, none of it is created and 0 is returned.

When you run the code output by wfsWriteMultiSprite, you specify no parameters.

Click to go to top of section. Example

You can see an example of the use of wfsWriteMultiSprite in the feature demo source code in scene 11. When you click the gray text that says "create" (not "create member") a dynamic copy of the window 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 tour source code, gWFSLastStaticSpriteChannel=84, ie, the drag and drop sprite with the highest channel number is sprite 84 (in scene 10). The feature tour contains 1000 sprite channels. So there are 1000 - 84 = 916 channels that are allocatable for dynamic sprite creation.

  3. The static model of the window named "11.1" was created in the Score. If you start the movie and then navigate to scene 11 in the source code, and then stop the movie, you see all the sprites are static, ie, you can see them in the Score and on the stage. When you stop a movie with dynamic WFS sprites in it, WFS destroys all the dynamic sprites (you can't see them anymore). The "11.1" window is your normal WFS 3.0 type of window.

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

  5. Now we run wfsWriteMultiSprite from the Message Window. It takes two parameters. The first parameter is the name of the manager ("11.1") or the manager's spritenum (9). Either will do. The second parameter determines whether the dynamic multi-sprite'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 wfsWriteMultiSprite(9, 1)

    in the Message Window and, consequently, we see a handler appear in the Message Window. wfsWriteMultiSprite output a handler named "wfsCreate111E10F630" (which is stored in the "generated1" script in the WFS 4 cast). The form of the name of the handlers produced by wfsMultiSprite is as follows. It starts with "wfsCreate". Then it contains the name of the multi-sprite copied. The name of the multi-sprite copied was "11.1". But a handler name cannot contain the "." symbol. wfsWriteMultiSprite strips out all characters that can't be part of a handler name. So the handler name contains "111". Then the handler name contains the "E" symbol followed by the spritenum of the static model's manager (10). Then it contains the "F" symbol followed by the frame number in which wfsWriteMultiSprite ran (630).

  6. The "wfsCreate111E10F630" handler was copied from the Message Window and pasted into a movie script. In particular, it was 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 wfsWriteMultiSprite(9,1). The second parameter means that the members of the dynamic multi-sprite will be the same ones as the members of the static model multi-sprite. But there's one sprite which we want to have its own new member. Note that in scene 11 when you click "create multisprite" to create a new window, the name of the dynamic window 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 15 in scene 11 is the sprite that displays the name of the window. We also note that sprite 15 has a member called "11: Label".

    Now we open up the source code of the "wfsCreate111E10F630" handler. We look for the line that mentions the "11: Label" member. The relevant line looks like this, before editing:

    theNewSpriteNum = wfsCreateSprite(["11: Label", "11: wfsWriteElement", 36, 100, 321, 16, 16, 30, 1])

    --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.

    Note that the list of parameters ends with doNotCreateNewMember, and that the it has a value specified for it in the line of code (namely doNotCreateNewMember=1). That means that when the sprite is created, a new member will not be created; the new sprite will use the same copy of the "11: Label" member as the static model used. But we do want a new member to be created because we want to give the dynamic sprite text that can be different from the static model's text. So we change it like so:

    theNewSpriteNum = wfsCreateSprite(["11: Label", "11: wfsWriteElement", 36, 100, 331, 20, 16, 30])

    The little edit we've done (getting rid of the "1" at the end) will result in a new copy of the "11: Label" member being created each time the "wfsCreate111E10F630" handler runs.

    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 "wfsCreate111E10F630" handler. The code generated by the wfsWriteMultiSprite handler, if you look at it, takes a parameter called "familyIdentifier". However, as is mentioned in the comments in "wfsCreate111E10F630", "Don't specify any value for the 'familyidentifier' parameter. The 'familyIdentifier' parameter is used by wfsWriteMultiSpriteFamily output in calls to wfsWriteMultiSprite output."

    If you look at the code for the "create window" behavior attached to the gray text that says "create multisprite" (sprite 7 in the Score) you see the below code:

    on mouseup me

      if the clickon = spritenum then

        --The below line calls a handler generated with wfsWriteMultiSprite.

        --The 'E10F631' part of the name indicates that the manager of the

        --static model upon which wfsCreate111E10F630 is based was

        --located in channel 9 of frame 641.

        theNewSpriteNum = wfsCreate111E10F630()

      end if


    When you click the text that says "create multisprite", the above handler runs, which calls "wfsCreate111E10F630" and a dynamic multi-sprite is created. theNewSpriteNum will hold the spritenum of the newly created manager or 0 if the multi-sprite could not be created.

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

    Each instantiated multi-sprite must have a name that is unique among other instantiated multi-sprites. The convention used by wfsWriteMultiSprite is pictured below.

    If the name of original multi-sprite is q, then the name of the first copy is q+1, and the name of the second copy is q+2, etc. Any child multi-sprites of q will remain children of q; they will not be children of q+n unless you use wfsSetParent or wfsSetChild to change the parent-child relationships. Also, if q has a behavior that opens some multi-sprite x, then q+n will open x also. Contrast this with the code produced by wfsWriteMultiSpriteFamily.

  10. Note also that if you click the blue button at top right of scene 11 windows, the window 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


        theResult=wfsDestroyMultiSpriteFamily(theManager, 1)

      end if


    We could as well have called wfsDestroyMultiSprite, rather than wfsDestroyMultiSpriteFamily. We are simply destroying a single multi-sprite. The reason wfsDestroyMultiSpriteFamily was used was because the "Destroy Family on Mouseup" behavior had already been developed for use in scene 10 and sufficed also for scene 11.

    wfsGetMyManagerSpriteNum in the above code is part of the "4: Window/Menu Element" API.

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

You can delete the "Script Writer" script from the cast when you are finished generating code. It is a tool for authoring. None of its handlers are called at run-time.

You can also delete the static model from the Score of a COPY(!) of your project when it is ready to be published, if you want. The code that wfsWriteMultiSprite 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 wfsWriteMultiSprite needs those cast members.


Click to go to the home pageScript Writer wfsWriteMultiSprite Handler